[audit] mega-run packet; docs repair split to #29

.github/CONTRIBUTING.md

@@ -65,6 +65,90 @@ should include:
 Images should be hosted with GitHub user attachments or another external asset
 URL instead of committed to the repository.
 
+## Fork-as-Lab Workflow
+
+`Fearvox/EverOS` is a development fork of `EverMind-AI/EverOS`. All experimental
+work happens on the fork before selective promotion upstream.
+
+### Staying Current with Upstream
+
+The fork auto-rebases onto upstream `main` every 6 hours via
+`sync-upstream.yml`. This replays fork-only commits (templates, workflows, docs)
+on top of the latest upstream. If you're working on a feature branch:
+
+```bash
+# Rebase your branch onto the latest fork main
+git fetch origin
+git rebase origin/main
+```
+
+If the auto-rebase encounters a conflict, it aborts and opens a tracking issue.
+Manual resolution:
+
+```bash
+git checkout main
+git pull upstream main --rebase
+# resolve conflicts, then:
+git push origin main --force-with-lease
+```
+
+### Branch Strategy
+
+| Branch pattern | Purpose | Lifetime |
+|---------------|---------|----------|
+| `sleep-iter-*-*` | Automated overnight runs | Feature branch, merged or closed |
+| `codex-watch-*` | Codex co-agent patrol | Isolated worktree, never touch |
+| `feature/*` | Human-driven features | Feature branch -> PR to origin/main |
+| `sleep-log` | Overnight run audit log | Persistent tracking branch |
+
+### Label Conventions
+
+| Label | Color | Use on |
+|-------|-------|--------|
+| `pr-mirror` | `#0E8A16` | Issues that mirror an upstream PR; triggers Linear sync |
+| `tracking` | `#5319E7` | Long-lived tracking issues |
+| `security` | `#B60205` | Security advisories or security-relevant PRs |
+| `urgent` | `#D93F0B` | High-priority; escalates in Linear |
+| `sync-failed` | `#D93F0B` | Auto-applied when Linear sync fails for an issue |
+
+### Issue Templates
+
+Use the template picker when opening an issue. The two fork-specific templates:
+
+- **PR Tracker** (`pr_tracker.yml`) tracks an upstream PR for Linear/Slack
+  visibility. Requires `pr_number`, `pr_url`, `author`, `area`, `scope`, and
+  `evidence`. Applies `pr-mirror` and `tracking` labels.
+- **Security Tracker** (`security_tracker.yml`) tracks a security advisory.
+  Adds `security` and `urgent` labels on top of the PR tracker labelset.
+
+Both templates auto-trigger `linear-sync.yml`, which creates a corresponding
+Linear issue in the `EverMind-Dash` project and comments back with the EVE
+identifier.
+
+### Linear Sync
+
+Issues labeled `pr-mirror` are mirrored to Linear's `EverMind-Dash` project
+automatically. The sync is one-way from GitHub to Linear. The bot comments back
+with the matching EVE issue identifier on success.
+
+If the bot adds a `sync-failed` label, check the workflow run logs at
+`https://github.com/Fearvox/EverOS/actions/workflows/linear-sync.yml`.
+
+### Promoting to Upstream
+
+When a fork change is ready for `EverMind-AI/EverOS`:
+
+```bash
+gh pr create --repo EverMind-AI/EverOS \
+  --base main \
+  --head Fearvox:main \
+  --title "feat: description" --body "..."
+```
+
+Templates and workflows committed to the fork are replayed on top of upstream
+during every rebase cycle. They never conflict unless upstream adds same-named
+files, which is handled by auto-rebase conflict detection.
+
 ## Style Notes
 
 - Follow existing patterns before adding new abstractions.

.github/workflows/docs.yml

@@ -19,6 +19,63 @@ permissions:
   contents: read
 
 jobs:
+  markdown-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Collect changed Markdown files
+        id: changed-markdown
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          BASE_REF: ${{ github.base_ref }}
+          BEFORE_SHA: ${{ github.event.before }}
+          AFTER_SHA: ${{ github.sha }}
+        run: |
+          python3 - <<'PY' >> "$GITHUB_OUTPUT"
+          from pathlib import Path
+          import os
+          import subprocess
+
+          event_name = os.environ["EVENT_NAME"]
+          if event_name == "pull_request":
+              base_ref = os.environ["BASE_REF"]
+              subprocess.run(["git", "fetch", "origin", base_ref, "--depth=1"], check=True)
+              diff_range = f"origin/{base_ref}...HEAD"
+          else:
+              before = os.environ.get("BEFORE_SHA", "")
+              after = os.environ["AFTER_SHA"]
+              if before and set(before) != {"0"}:
+                  diff_range = f"{before}..{after}"
+              else:
+                  diff_range = f"{after}^..{after}"
+
+          result = subprocess.run(
+              ["git", "diff", "--name-only", "--diff-filter=ACMRT", diff_range],
+              check=True,
+              text=True,
+              stdout=subprocess.PIPE,
+          )
+          files = [
+              path
+              for path in result.stdout.splitlines()
+              if path.endswith(".md") and Path(path).is_file()
+          ]
+
+          print("files<<EOF")
+          print("\n".join(files))
+          print("EOF")
+          print(f"count={len(files)}")
+          PY
+
+      - uses: DavidAnson/markdownlint-cli2-action@v19
+        if: steps.changed-markdown.outputs.count != '0'
+        with:
+          globs: ${{ steps.changed-markdown.outputs.files }}
+          config: .markdownlint.json
+
   links:
     runs-on: ubuntu-latest
     steps:

.markdownlint.json

@@ -0,0 +1,11 @@
+{
+  "default": true,
+  "MD013": false,
+  "MD024": { "siblings_only": true },
+  "MD033": false,
+  "MD041": false,
+  "MD051": false,
+  "MD060": false,
+  "MD025": { "front_matter_title": "" },
+  "MD007": { "indent": 2 }
+}

.planning/mega-run/DECISIONS.md

@@ -0,0 +1,19 @@
+# Mega Run Decisions
+
+## 2026-05-13T09:09:45Z - Start From Origin Main
+
+Decision: create and work from `mega-24h-curator-2026-05-13` based on `origin/main`.
+
+Reason: current `sleep-log` branch is ahead of `origin/main` by 32 commits. The runbook requires a clean run branch and forbids main/upstream writes. Keeping `sleep-log` untouched preserves prior audit state.
+
+## 2026-05-13T09:09:45Z - Treat #12 As Workflow-Scope Bug
+
+Decision: do not fix 1218 markdownlint findings repo-wide. Repair the workflow so markdownlint only checks changed Markdown files or an explicit baseline.
+
+Reason: runbook explicitly says not to lint 1000+ legacy errors. A repo-wide formatting pass would be high-noise and low owner value.
+
+## 2026-05-13T09:20:39Z - Pin Markdownlint Noise Boundary
+
+Decision: disable `MD060/table-column-style` in `.markdownlint.json` while keeping substantive Markdown rules enabled.
+
+Reason: local `markdownlint` v0.40.0 reports table style noise that the May Agent workflow did not target. The runbook asks for lightweight docs hygiene and forbids broad legacy formatting churn.

.planning/mega-run/FINAL_REPORT.md

@@ -0,0 +1,64 @@
+# Mega Run Final Report
+
+## Verdict
+
+FLAG: The named queue is owner-reviewable and #24 is a clean draft repair PR,
+but not every open PR should merge. #1 remains an older dependency PR with zero
+checks, #16-#22 need review before merge, and full EverCore install/test was
+intentionally skipped as heavy infrastructure.
+
+## Totals
+
+- Total iterations: 30
+- Final score: +52
+- Hard violations observed: 0
+- Draft PR: [#24](https://github.com/Fearvox/EverOS/pull/24)
+- Run branch: `mega-24h-curator-2026-05-13`
+
+## PR URLs
+
+- Curated repair PR: [#24](https://github.com/Fearvox/EverOS/pull/24)
+- Superseded or covered: #7, #12
+- Draft-normalized/reviewed: #21, #22, #23
+- May Agent review packet: #16, #17, #18, #19, #20, #21, #22
+- Extra owner risk: #1
+
+## Changed Files
+
+- `.github/CONTRIBUTING.md`
+- `.github/workflows/docs.yml`
+- `.markdownlint.json`
+- `.planning/mega-run/DECISIONS.md`
+- `.planning/mega-run/FINAL_REPORT.md`
+- `.planning/mega-run/GATE_RESULTS.md`
+- `.planning/mega-run/HEARTBEAT.txt`
+- `.planning/mega-run/ITER_LOG.md`
+- `.planning/mega-run/MAY_AGENT_REVIEW.md`
+- `.planning/mega-run/OWNER_BRIEF.md`
+- `.planning/mega-run/SCOREBOARD.md`
+
+## Commands Run
+
+- Preflight: `git status --short --branch`, `git remote -v`, `git fetch --all --prune`, `gh auth status`, `gh repo view Fearvox/EverOS`, `git ls-remote origin`, `git ls-remote upstream`.
+- PR truth reset: `gh pr list --repo Fearvox/EverOS`, `gh pr view`, `gh pr diff --name-only`, `gh run view --log-failed`.
+- Docs gates: local markdownlint, active relative link check, use-case banner check, workflow YAML parse, changed-Markdown collector simulation.
+- GitHub gates: `gh pr create --draft`, `gh pr edit`, `gh pr ready --undo`, repeated `gh pr view 24` check polling.
+- Repro gates: `docker-compose -f docker-compose.yaml config`, `uv sync --locked --dry-run`, `make -n test`, `make -n lint`.
+- Safety gates: token/local-path pattern scans, branch diff path scan, commit trailer count check.
+
+## Failed Or Skipped Gates
+
+- #7 and #12 remain red as historical PRs; #24 provides the repair path with green checks.
+- #1 remains non-draft with zero checks; left as owner risk because it was outside the named queue.
+- #23 has zero checks; converted to draft and not merged.
+- #16-#22 are coherent but should not merge as-is; see `MAY_AGENT_REVIEW.md`.
+- Full EverCore `uv sync`, service startup, pytest, black, i18n, and pyright were skipped because dry-run showed a large install and service startup would be heavy infra.
+- Local Docker uses standalone `docker-compose`; the `docker compose` subcommand is unavailable on this machine.
+
+## Owner Morning Actions
+
+- Merge/review #24 first: it repairs the docs gate path and carries the audit trail.
+- Close or supersede #7/#12 if #24 is accepted.
+- Read `MAY_AGENT_REVIEW.md` before touching #16-#22.
+- Keep #23 draft until dependency checks exist.
+- Decide separately whether #1 should be drafted, closed, or tested.

.planning/mega-run/GATE_RESULTS.md

@@ -0,0 +1,126 @@
+# Mega Run Gate Results
+
+## Preflight Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| `git status --short --branch` | PASS | `## mega-24h-curator-2026-05-13...origin/main`; untracked `.codex/` and `docs/goal.md` left untouched. |
+| `git remote -v` | PASS | origin fetch/push is `https://github.com/Fearvox/EverOS.git`; upstream fetch/push is `https://github.com/EverMind-AI/EverOS.git`. |
+| `gh repo view Fearvox/EverOS` | PASS | Repo resolved as `Fearvox/EverOS`, parent `EverMind-AI/EverOS`, default branch `main`. |
+| Fork main SHA | PASS | `fe80ca1fd86f64ac27664aa58b41da73b3b2d00c`. |
+| Upstream main SHA | PASS | `29d555c6e94de3630f314c1f594fc1801377ff5a`. |
+| Open PR list | FLAG | #7 and #12 are red; #21/#22 are non-draft; #23 is new dependabot without checks. |
+
+## PR Truth Reset
+
+| PR | Live State | Gate Result | Evidence |
+|----|------------|-------------|----------|
+| #7 | OPEN draft, `UNSTABLE` | BLOCK | Links job fails: `.github/CONTRIBUTING.md: url -> missing`. |
+| #12 | OPEN draft, `UNSTABLE` | BLOCK | Markdownlint job fails after scanning 144 files and reporting 1218 legacy errors. |
+| #21 | OPEN non-draft, `CLEAN` | FLAG | Docs links check is green, but non-draft state conflicts with runbook queue-shape normalization. |
+| #22 | OPEN non-draft, `CLEAN` | FLAG | Docs links check is green, but non-draft state conflicts with runbook queue-shape normalization. |
+| #23 | OPEN non-draft, `CLEAN`, no checks | FLAG | Dependabot uv update with 21 updates; no blind merge. |
+
+## Local Repair Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| Contribution link repair | PASS | Replaced the literal Markdown target `url` with prose in `.github/CONTRIBUTING.md`; active relative link check passes. |
+| Markdownlint scope repair | PASS | `.github/workflows/docs.yml` now collects changed Markdown files and passes them to `markdownlint-cli2-action@v19` instead of linting `**/*.md`. |
+| Local markdownlint | PASS | `npx --yes markdownlint-cli2 .github/CONTRIBUTING.md .planning/mega-run/*.md` reports `Summary: 0 error(s)`. |
+| Workflow YAML parse | PASS | Ruby YAML parser reports `workflow YAML ok`. |
+
+## Remote Repair Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| Draft PR #24 | PASS | `isDraft: true`, base `main`, head `mega-24h-curator-2026-05-13`, merge state `CLEAN`. |
+| Docs `markdown-lint` | PASS | #24 check run concluded `SUCCESS` at `2026-05-13T09:23:18Z`. |
+| Docs `links` | PASS | #24 check run concluded `SUCCESS` at `2026-05-13T09:23:16Z`. |
+
+## Draft Queue Normalization
+
+| PR | Result | Evidence |
+|----|--------|----------|
+| #21 | PASS | Converted with `gh pr ready 21 --repo Fearvox/EverOS --undo`; reverified `isDraft: true`. |
+| #22 | PASS | Converted with `gh pr ready 22 --repo Fearvox/EverOS --undo`; reverified `isDraft: true`. |
+
+## Dependency PR Quarantine
+
+| PR | Result | Evidence |
+|----|--------|----------|
+| #23 | PASS | Touched `methods/EverCore/pyproject.toml` and `methods/EverCore/uv.lock`; had zero checks; converted to draft; no merge attempted. |
+| #1 | FLAG | Older dependabot PR touches `use-cases/game-of-throne-demo/frontend/package.json`; still non-draft with zero checks; outside named repair queue. |
+
+## Workflow Scope Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| Changed Markdown collector | PASS | Local simulation against `origin/main...HEAD` returned six Markdown files, not the full legacy tree. |
+| Branch diff boundary | PASS | `git diff --name-only origin/main...HEAD` lists nine files total: `.github`, `.markdownlint.json`, and `.planning/mega-run` only. |
+| Markdownlint diff set | PASS | Running markdownlint on the PR Markdown diff reports `Summary: 0 error(s)`. |
+
+## May Agent Review Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| #16 strategy gate | FLAG | Draft and links pass, but contains private memory-path reference and unverified external claims. |
+| #17-#22 packet review | FLAG | Draft PRs with green links; source docs are ordered, but index must land last and several claims need evidence. |
+| `MAY_AGENT_REVIEW.md` required fields | PASS | Artifact includes merge order, contradictions, missing evidence, upstream-pitch framing, and what should not be merged. |
+
+## PR Body Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| Draft state | PASS | #24 reports `isDraft: true`. |
+| Base target | PASS | PR body and `gh pr view` confirm target is `Fearvox/EverOS:main`. |
+| Required body sections | PASS | Python assertion found `Changed Files`, `Validation`, `Risks`, and `Rollback` sections. |
+| Latest remote checks | PASS | #24 latest `markdown-lint` and `links` checks concluded `SUCCESS` after commit `2174b39`. |
+
+## Public-Surface And Boundary Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| Token/local-path scan | PASS | Branch artifacts have no GitHub token, API key, local absolute path, or private home-directory memory path patterns. |
+| Branch path boundary | PASS | Branch diff contains 10 intended files and excludes `.codex`, `.claude`, and `docs/goal.md`. |
+| origin/main unchanged | PASS | `fe80ca1fd86f64ac27664aa58b41da73b3b2d00c`. |
+| upstream/main unchanged | PASS | `29d555c6e94de3630f314c1f594fc1801377ff5a`. |
+| Commit trailer count | PASS | Python check found exactly one required co-author trailer in each of 5 branch commits. |
+
+## Reproducibility Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| #24 latest remote checks | PASS | Latest `markdown-lint` and `links` checks concluded `SUCCESS` after boundary audit push. |
+| EverCore quick-start files | FLAG | `docker-compose.yaml`, `pyproject.toml`, `uv.lock`, and `Makefile` exist; `.env.example` absent, `env.template` present. |
+| Compose config | PASS | `docker-compose -f docker-compose.yaml config` passes with an obsolete `version` warning. |
+| Local compose command | FLAG | `docker compose` subcommand is unavailable locally; standalone `docker-compose` exists. |
+| `uv sync --locked --dry-run` | PASS | Dry-run resolves 204 packages without installing; full sync skipped because it would install 193 packages. |
+| `make -n test` / `make -n lint` | PASS | Make dry-runs expand to pytest, black, and i18n check commands. |
+
+## Owner Handoff Prep Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| Open `sync-failed` issues | PASS | `gh issue list --label sync-failed` returned `[]`. |
+| Open PR matrix | FLAG | Named queue is handled, but #1 remains an older non-draft dependency PR with zero checks. |
+| #24 latest checks | PASS | Latest `markdown-lint` and `links` checks both concluded `SUCCESS`; PR is `CLEAN` and draft. |
+
+## Owner Brief Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| Line count | PASS | `OWNER_BRIEF.md` is 10 lines. |
+| Decision categories | PASS | Brief includes merge now, review first, close/rework, defer, risk, repro, boundaries, and next action. |
+| Safety | PASS | No token/local-path patterns in mega-run markdown after reduction. |
+
+## Final Artifact Gate
+
+| Gate | Result | Evidence |
+|------|--------|----------|
+| Iteration count | PASS | `ITER_LOG.md` contains iterations 1-30. |
+| Final report | PASS | `.planning/mega-run/FINAL_REPORT.md` written with required fields. |
+| Owner brief | PASS | `.planning/mega-run/OWNER_BRIEF.md` remains 10 lines. |
+| Local markdownlint | PASS | Mega-run markdown passes local markdownlint. |
+| Public-surface safety | PASS | Mega-run markdown has no token/local-path pattern hits. |
+| Residual queue flags | FLAG | #1 has zero checks; #7/#12 remain red historical PRs; #16-#22 require review before merge. |

.planning/mega-run/HEARTBEAT.txt

@@ -0,0 +1 @@
+2026-05-13T09:49:10Z iter=30 slug=completion-audit-artifacts gate=PASS