diff --git a/docs/SETUP.md b/docs/SETUP.md index 18d572091e..ee81f167d3 100644 --- a/docs/SETUP.md +++ b/docs/SETUP.md @@ -930,7 +930,7 @@ Every script under `tools/` (plus the two report make-targets), grouped by purpo | | `tools/main_lane.py` + `tools/lanes/main.sh` | **(P31 S59)** The EXE's own draft→gate→commit cadence, beside the overlay lanes. main is excluded from every wave draw because its gate is a clean whole-EXE rebuild that bisects; this lane runs that gate on its own clock. Parked drafts (`.run/main_queue/`) first, then `build_wave_atlas --only-bins main`; reloc pre-filter; `gate_main --apply` in batches of 40 (one rebuild verifies the slate, ~15 s measured); BISECTS a COMPILE conflict that gate_main refuses to bisect; credits a bank only when the INCLUDE_ASM line is gone AND main re-checks byte-identical; commits named paths (R42). Failures parked with a try count, capped at 2. | | | `tools/lanes/distill.sh` + `tools/distill_scan.py` | **(P31 S59)** The flywheel's second half, beside drafting. The gater's per-wave `idiom_harvest` is EXTRACTION; this raises a READY marker (`.run/distill_ready/`) when ≥30 novel candidates or ≥2 waves accumulate, and a human + an **Opus/Sonnet** subagent (never Fable) distills and lands the sections. State is `{tag: novel-count-when-mined}`, never a done-list — a re-gated wave rewrites its candidate file under the same tag. Measured: ~82-88% of candidates are already covered, and 1 in 3 credited levers is byte-inert (§266). | | | `tools/lanes/relaunch_drafter_shell.sh`, `restart_gater_when_idle.sh`, `bounce_drafter_on_queue.sh` | **(P31 S59)** Ship a lane change without losing work. bash parses a `while…done` body up front, so a lane-ARG change is invisible to the running shell and a python bounce re-runs the OLD command line. These wait for a safe boundary (a queued wave; an idle gate) and then restart the right thing. See `docs/accelerators.md` #5 for the code/args/draw-defaults table. | -| | `tools/integration_resolver.py` | **(P31 S61)** THE INTEGRATION-RESOLVER LANE, zero model tokens (`frontier-analysis-s60` §4). Intake = backlog rows at closeness 0 ∪ `reloc_rejects` rows with shape MATCH (an INDEX, re-judged against today's tree); per item `rtu_match` at the real split TU → CC1: the gate ladder's draft-side transforms + one retry → MATCH: `reloc_identity` as the disagreeing oracle (rtu masks reloc fields, so a wrong symbol NAME still reads MATCH) → MISMATCH/shape-MATCH: `aprop_symfix` → stage `.run/sweep_resolver//.c` → `sweep_parallel` (whole-binary SHA) → commit at once (R42). Holds `.run/auto/draw.lock` for judge+gate. Ledger `.run/resolver/verdicts.jsonl` (per-candidate verdict + draft/TU hashes; unchanged rejects are not re-judged). `--intake-only` prints the stock with denominators; `--negative-control N` re-judges N banked fns first and refuses on /.c` → `sweep_parallel` (whole-binary SHA) → commit at once (R42). Holds `.run/auto/draw.lock` for judge+gate. Ledger `.run/resolver/verdicts.jsonl` (per-candidate verdict + draft/TU hashes; unchanged rejects are not re-judged). `--intake-only` prints the stock with denominators; `--negative-control N` re-judges N banked fns first and refuses on . tools/doc_links.py reports these as PENDING instead of # BROKEN; `--strict` (gate 2) refuses any entry, so this file must be EMPTY before a PhaseEnd. -docs/wiki/Archive-index.md Phase 33.5 task 6 (the Archive index — one row per sunset document) diff --git a/docs/history/README.md b/docs/history/README.md index a9bca02528..475dc07d64 100644 --- a/docs/history/README.md +++ b/docs/history/README.md @@ -1,8 +1,13 @@ # docs/history — provenance archive (not active guidance) -Superseded and reference material, kept for the record. **Nothing here is current instruction** — the authoritative docs are `PROJECT_CONTEXT.md`, `docs/SETUP.md`, `docs/formats.md`, and `docs/memory-map.md`. +Superseded and reference material from the project's beginnings, kept for the record. **Nothing here is current +instruction** — the wiki (`docs/wiki/`, starting at its Reference index) is the source of truth, and the authoritative +references are `PROJECT_CONTEXT.md`, `docs/SETUP.md`, `docs/formats.md` and `docs/memory-map.md`. - `claude-bfm-starting-point.md` — the original project brief. **Superseded; contains corrected-wrong claims** (see its banner). Do not follow. -- `project_architect_v1.3.0.md` — the methodology template the Project Context File was generated from. -- `Fable5-ultracode-Full research findings-w42n9cp9t.output` — the raw multi-agent research (sotn workflow, Ghidra/MCP stack, BFM knowledge, WSL specifics) that informed the docs. -- `*.txt` link notes — original reference URLs (now folded into the docs above). +- `project_architect_v1.3.0.md` — the methodology template the Project Context File was generated from (the published successor is ProjectArchitect 2.0). +- `cheap-tier-ab-experiment.md` — the June-2026 A/B of cheap vs strong drafters, the measurement behind the model ladder. + +Moved to `docs/sunset/history/` at the Phase-33.5 consolidation (2026-09-07), indexed by the wiki's Archive index: the raw +multi-agent research output (`Fable5-ultracode-Full research findings-*.output`, whose actionable content was folded into +`docs/SETUP.md` and `docs/formats.md` in June) and the three original link-note `.txt` files (their URLs are in `docs/SETUP.md`). diff --git a/docs/sunset/README.md b/docs/sunset/README.md new file mode 100644 index 0000000000..9609e641b4 --- /dev/null +++ b/docs/sunset/README.md @@ -0,0 +1,74 @@ +# docs/sunset — retired documents awaiting the owner's review + +Everything in this folder left `docs/` at the Phase-33.5 consolidation (2026-09-07, v1.32.1) because its purpose was +fulfilled and its information lives elsewhere. Each file was moved with `git mv` (history intact) after a referrer +census found no link to it outside the phase records, and each has a row in the wiki's Archive index +(`docs/wiki/Archive-index.md`) saying what it was, what came of it and where its information lives now. **Nothing may +link into this folder** (`tools/doc_links.py` refuses it); the Archive index names these files as paths so that the +folder can be deleted without breaking a link. + +**Deletion is the owner's decision, made after review — never part of the move.** Tick a row when reviewed; delete the +folder (or single files) with an ordinary commit when done. The phase records that cite these files by their old paths +(PhaseEnds, the decision log, the cookbook) are records and stay as written. + +| Reviewed | File | Class | +|---|---|---| +| ☐ | `automation-runbook.md` | superseded runbook | +| ☐ | `calibration.md` | closed-phase sizing | +| ☐ | `canonical-decl-reconcile-design.md` | design, built | +| ☐ | `exemplar_curriculum.md` | frontier snapshot | +| ☐ | `fable5-strategy-review-2026-07.md` | dated review | +| ☐ | `family-endgame-megaplan.md` | superseded plan | +| ☐ | `family-manifest.md` | superseded manifest | +| ☐ | `frontier-p30.md` | point-in-time report | +| ☐ | `frontier-p32.md` | point-in-time report (PhaseEnd_Phase31 asked that it be kept — archive, do not delete) | +| ☐ | `frontier-s39.md` | point-in-time report | +| ☐ | `gen2-roadmap.md` | superseded roadmap | +| ☐ | `next-session-triage-ladder.md` | spec, shipped | +| ☐ | `phase25-frontier-map.md` | closed-phase artifact | +| ☐ | `phase25-t6-curriculum.md` | closed-phase artifact | +| ☐ | `phase25-t6-fable-brief.md` | closed-phase artifact | +| ☐ | `phase26-triage.md` | closed-phase artifact | +| ☐ | `proto-correspondence.md` | closed spike | +| ☐ | `recovery-queue-s65.md` | closed by outcome | +| ☐ | `resident-dossier.md` | closed by outcome | +| ☐ | `roadmap-to-100.md` | superseded roadmap | +| ☐ | `sister-decomps.md` | realised elsewhere | +| ☐ | `hand-matching-process.md` | folded into the wiki | +| ☐ | `wave-metrics.md` | folded into the wiki | +| ☐ | `portable-decomp-workflow.md` | folded into the wiki | +| ☐ | `hindsight-study.md` | folded into the wiki | +| ☐ | `distill/atbhbkbl.md` | distillation ledger, landed | +| ☐ | `distill/axbm.md` | distillation ledger, landed | +| ☐ | `history/Fable5-ultracode-Full research findings-w42n9cp9t.output` | raw research output | +| ☐ | `history/debug menu link.txt` | link note | +| ☐ | `history/ghidra psx plugin link.txt` | link note | +| ☐ | `history/sotn-decomp wiki link.txt` | link note | +| ☐ | `tool-designs/aprop-lane-s59.md` | session design | +| ☐ | `tool-designs/frontier-analysis-s60.md` | session analysis | +| ☐ | `tool-designs/frontier-analysis-s61.md` | session analysis | +| ☐ | `tool-designs/jtbl-automation-s59.md` | session design | +| ☐ | `tool-designs/jtbl-island-split-review.md` | session review | +| ☐ | `tool-designs/jtbl-island-split.md` | session design | +| ☐ | `tool-designs/main-gate-defects.md` | session note | +| ☐ | `tool-designs/main-lane-fix-s59.md` | session post-mortem | +| ☐ | `tool-designs/o0-cc1-lanes.md` | session study | +| ☐ | `tool-designs/o0-path-s59.md` | session result | +| ☐ | `tool-designs/tells-lane-s59.md` | session proposal | +| ☐ | `generated-snapshots/frontier-atlas.md` | frozen snapshot | +| ☐ | `generated-snapshots/family-cousins.md` | frozen snapshot | +| ☐ | `generated-snapshots/worklist.md` | frozen snapshot | +| ☐ | `generated-snapshots/autopsy.md` | frozen snapshot | +| ☐ | `generated-snapshots/burndown.jsonl` | frozen snapshot | +| ☐ | `generated-snapshots/progress.ov_SC01_005.md` | per-binary snapshot | +| ☐ | `generated-snapshots/progress.ov_SC01_006.md` | per-binary snapshot | +| ☐ | `generated-snapshots/progress.ov_SC01_077.md` | per-binary snapshot | +| ☐ | `generated-snapshots/progress.ov_SC03_001.md` | per-binary snapshot | +| ☐ | `generated-snapshots/progress.resident.md` | per-binary snapshot (stale figures) | +| ☐ | `generated-snapshots/difficulty.ov_SC01_005.md` | per-binary snapshot | +| ☐ | `generated-snapshots/difficulty.ov_SC01_006.md` | per-binary snapshot | +| ☐ | `generated-snapshots/difficulty.ov_SC01_077.md` | per-binary snapshot | +| ☐ | `generated-snapshots/difficulty.ov_SC03_001.md` | per-binary snapshot | +| ☐ | `generated-snapshots/difficulty.resident.md` | per-binary snapshot (stale figures) | +| ☐ | `generated-snapshots/duplicates.ov_SC01_077.md` | per-binary snapshot | +| ☐ | `generated-snapshots/duplicates.resident.md` | per-binary snapshot | diff --git a/docs/automation-runbook.md b/docs/sunset/automation-runbook.md similarity index 100% rename from docs/automation-runbook.md rename to docs/sunset/automation-runbook.md diff --git a/docs/calibration.md b/docs/sunset/calibration.md similarity index 100% rename from docs/calibration.md rename to docs/sunset/calibration.md diff --git a/docs/canonical-decl-reconcile-design.md b/docs/sunset/canonical-decl-reconcile-design.md similarity index 100% rename from docs/canonical-decl-reconcile-design.md rename to docs/sunset/canonical-decl-reconcile-design.md diff --git a/docs/distill/atbhbkbl.md b/docs/sunset/distill/atbhbkbl.md similarity index 100% rename from docs/distill/atbhbkbl.md rename to docs/sunset/distill/atbhbkbl.md diff --git a/docs/distill/axbm.md b/docs/sunset/distill/axbm.md similarity index 100% rename from docs/distill/axbm.md rename to docs/sunset/distill/axbm.md diff --git a/docs/exemplar_curriculum.md b/docs/sunset/exemplar_curriculum.md similarity index 100% rename from docs/exemplar_curriculum.md rename to docs/sunset/exemplar_curriculum.md diff --git a/docs/fable5-strategy-review-2026-07.md b/docs/sunset/fable5-strategy-review-2026-07.md similarity index 100% rename from docs/fable5-strategy-review-2026-07.md rename to docs/sunset/fable5-strategy-review-2026-07.md diff --git a/docs/family-endgame-megaplan.md b/docs/sunset/family-endgame-megaplan.md similarity index 100% rename from docs/family-endgame-megaplan.md rename to docs/sunset/family-endgame-megaplan.md diff --git a/docs/family-manifest.md b/docs/sunset/family-manifest.md similarity index 100% rename from docs/family-manifest.md rename to docs/sunset/family-manifest.md diff --git a/docs/frontier-p30.md b/docs/sunset/frontier-p30.md similarity index 100% rename from docs/frontier-p30.md rename to docs/sunset/frontier-p30.md diff --git a/docs/frontier-p32.md b/docs/sunset/frontier-p32.md similarity index 100% rename from docs/frontier-p32.md rename to docs/sunset/frontier-p32.md diff --git a/docs/frontier-s39.md b/docs/sunset/frontier-s39.md similarity index 100% rename from docs/frontier-s39.md rename to docs/sunset/frontier-s39.md diff --git a/docs/gen2-roadmap.md b/docs/sunset/gen2-roadmap.md similarity index 100% rename from docs/gen2-roadmap.md rename to docs/sunset/gen2-roadmap.md diff --git a/docs/autopsy.md b/docs/sunset/generated-snapshots/autopsy.md similarity index 100% rename from docs/autopsy.md rename to docs/sunset/generated-snapshots/autopsy.md diff --git a/docs/burndown.jsonl b/docs/sunset/generated-snapshots/burndown.jsonl similarity index 100% rename from docs/burndown.jsonl rename to docs/sunset/generated-snapshots/burndown.jsonl diff --git a/docs/difficulty.ov_SC01_005.md b/docs/sunset/generated-snapshots/difficulty.ov_SC01_005.md similarity index 100% rename from docs/difficulty.ov_SC01_005.md rename to docs/sunset/generated-snapshots/difficulty.ov_SC01_005.md diff --git a/docs/difficulty.ov_SC01_006.md b/docs/sunset/generated-snapshots/difficulty.ov_SC01_006.md similarity index 100% rename from docs/difficulty.ov_SC01_006.md rename to docs/sunset/generated-snapshots/difficulty.ov_SC01_006.md diff --git a/docs/difficulty.ov_SC01_077.md b/docs/sunset/generated-snapshots/difficulty.ov_SC01_077.md similarity index 100% rename from docs/difficulty.ov_SC01_077.md rename to docs/sunset/generated-snapshots/difficulty.ov_SC01_077.md diff --git a/docs/difficulty.ov_SC03_001.md b/docs/sunset/generated-snapshots/difficulty.ov_SC03_001.md similarity index 100% rename from docs/difficulty.ov_SC03_001.md rename to docs/sunset/generated-snapshots/difficulty.ov_SC03_001.md diff --git a/docs/difficulty.resident.md b/docs/sunset/generated-snapshots/difficulty.resident.md similarity index 100% rename from docs/difficulty.resident.md rename to docs/sunset/generated-snapshots/difficulty.resident.md diff --git a/docs/duplicates.ov_SC01_077.md b/docs/sunset/generated-snapshots/duplicates.ov_SC01_077.md similarity index 100% rename from docs/duplicates.ov_SC01_077.md rename to docs/sunset/generated-snapshots/duplicates.ov_SC01_077.md diff --git a/docs/duplicates.resident.md b/docs/sunset/generated-snapshots/duplicates.resident.md similarity index 100% rename from docs/duplicates.resident.md rename to docs/sunset/generated-snapshots/duplicates.resident.md diff --git a/docs/family-cousins.md b/docs/sunset/generated-snapshots/family-cousins.md similarity index 100% rename from docs/family-cousins.md rename to docs/sunset/generated-snapshots/family-cousins.md diff --git a/docs/frontier-atlas.md b/docs/sunset/generated-snapshots/frontier-atlas.md similarity index 100% rename from docs/frontier-atlas.md rename to docs/sunset/generated-snapshots/frontier-atlas.md diff --git a/docs/progress.ov_SC01_005.md b/docs/sunset/generated-snapshots/progress.ov_SC01_005.md similarity index 100% rename from docs/progress.ov_SC01_005.md rename to docs/sunset/generated-snapshots/progress.ov_SC01_005.md diff --git a/docs/progress.ov_SC01_006.md b/docs/sunset/generated-snapshots/progress.ov_SC01_006.md similarity index 100% rename from docs/progress.ov_SC01_006.md rename to docs/sunset/generated-snapshots/progress.ov_SC01_006.md diff --git a/docs/progress.ov_SC01_077.md b/docs/sunset/generated-snapshots/progress.ov_SC01_077.md similarity index 100% rename from docs/progress.ov_SC01_077.md rename to docs/sunset/generated-snapshots/progress.ov_SC01_077.md diff --git a/docs/progress.ov_SC03_001.md b/docs/sunset/generated-snapshots/progress.ov_SC03_001.md similarity index 100% rename from docs/progress.ov_SC03_001.md rename to docs/sunset/generated-snapshots/progress.ov_SC03_001.md diff --git a/docs/progress.resident.md b/docs/sunset/generated-snapshots/progress.resident.md similarity index 100% rename from docs/progress.resident.md rename to docs/sunset/generated-snapshots/progress.resident.md diff --git a/docs/worklist.md b/docs/sunset/generated-snapshots/worklist.md similarity index 100% rename from docs/worklist.md rename to docs/sunset/generated-snapshots/worklist.md diff --git a/docs/hand-matching-process.md b/docs/sunset/hand-matching-process.md similarity index 100% rename from docs/hand-matching-process.md rename to docs/sunset/hand-matching-process.md diff --git a/docs/hindsight-study.md b/docs/sunset/hindsight-study.md similarity index 100% rename from docs/hindsight-study.md rename to docs/sunset/hindsight-study.md diff --git a/docs/history/Fable5-ultracode-Full research findings-w42n9cp9t.output b/docs/sunset/history/Fable5-ultracode-Full research findings-w42n9cp9t.output similarity index 100% rename from docs/history/Fable5-ultracode-Full research findings-w42n9cp9t.output rename to docs/sunset/history/Fable5-ultracode-Full research findings-w42n9cp9t.output diff --git a/docs/history/debug menu link.txt b/docs/sunset/history/debug menu link.txt similarity index 100% rename from docs/history/debug menu link.txt rename to docs/sunset/history/debug menu link.txt diff --git a/docs/history/ghidra psx plugin link.txt b/docs/sunset/history/ghidra psx plugin link.txt similarity index 100% rename from docs/history/ghidra psx plugin link.txt rename to docs/sunset/history/ghidra psx plugin link.txt diff --git a/docs/history/sotn-decomp wiki link.txt b/docs/sunset/history/sotn-decomp wiki link.txt similarity index 100% rename from docs/history/sotn-decomp wiki link.txt rename to docs/sunset/history/sotn-decomp wiki link.txt diff --git a/docs/next-session-triage-ladder.md b/docs/sunset/next-session-triage-ladder.md similarity index 100% rename from docs/next-session-triage-ladder.md rename to docs/sunset/next-session-triage-ladder.md diff --git a/docs/phase25-frontier-map.md b/docs/sunset/phase25-frontier-map.md similarity index 100% rename from docs/phase25-frontier-map.md rename to docs/sunset/phase25-frontier-map.md diff --git a/docs/phase25-t6-curriculum.md b/docs/sunset/phase25-t6-curriculum.md similarity index 100% rename from docs/phase25-t6-curriculum.md rename to docs/sunset/phase25-t6-curriculum.md diff --git a/docs/phase25-t6-fable-brief.md b/docs/sunset/phase25-t6-fable-brief.md similarity index 100% rename from docs/phase25-t6-fable-brief.md rename to docs/sunset/phase25-t6-fable-brief.md diff --git a/docs/phase26-triage.md b/docs/sunset/phase26-triage.md similarity index 100% rename from docs/phase26-triage.md rename to docs/sunset/phase26-triage.md diff --git a/docs/portable-decomp-workflow.md b/docs/sunset/portable-decomp-workflow.md similarity index 100% rename from docs/portable-decomp-workflow.md rename to docs/sunset/portable-decomp-workflow.md diff --git a/docs/proto-correspondence.md b/docs/sunset/proto-correspondence.md similarity index 100% rename from docs/proto-correspondence.md rename to docs/sunset/proto-correspondence.md diff --git a/docs/recovery-queue-s65.md b/docs/sunset/recovery-queue-s65.md similarity index 100% rename from docs/recovery-queue-s65.md rename to docs/sunset/recovery-queue-s65.md diff --git a/docs/resident-dossier.md b/docs/sunset/resident-dossier.md similarity index 100% rename from docs/resident-dossier.md rename to docs/sunset/resident-dossier.md diff --git a/docs/roadmap-to-100.md b/docs/sunset/roadmap-to-100.md similarity index 100% rename from docs/roadmap-to-100.md rename to docs/sunset/roadmap-to-100.md diff --git a/docs/sister-decomps.md b/docs/sunset/sister-decomps.md similarity index 100% rename from docs/sister-decomps.md rename to docs/sunset/sister-decomps.md diff --git a/docs/tool-designs/aprop-lane-s59.md b/docs/sunset/tool-designs/aprop-lane-s59.md similarity index 100% rename from docs/tool-designs/aprop-lane-s59.md rename to docs/sunset/tool-designs/aprop-lane-s59.md diff --git a/docs/tool-designs/frontier-analysis-s60.md b/docs/sunset/tool-designs/frontier-analysis-s60.md similarity index 100% rename from docs/tool-designs/frontier-analysis-s60.md rename to docs/sunset/tool-designs/frontier-analysis-s60.md diff --git a/docs/tool-designs/frontier-analysis-s61.md b/docs/sunset/tool-designs/frontier-analysis-s61.md similarity index 100% rename from docs/tool-designs/frontier-analysis-s61.md rename to docs/sunset/tool-designs/frontier-analysis-s61.md diff --git a/docs/tool-designs/jtbl-automation-s59.md b/docs/sunset/tool-designs/jtbl-automation-s59.md similarity index 100% rename from docs/tool-designs/jtbl-automation-s59.md rename to docs/sunset/tool-designs/jtbl-automation-s59.md diff --git a/docs/tool-designs/jtbl-island-split-review.md b/docs/sunset/tool-designs/jtbl-island-split-review.md similarity index 100% rename from docs/tool-designs/jtbl-island-split-review.md rename to docs/sunset/tool-designs/jtbl-island-split-review.md diff --git a/docs/tool-designs/jtbl-island-split.md b/docs/sunset/tool-designs/jtbl-island-split.md similarity index 100% rename from docs/tool-designs/jtbl-island-split.md rename to docs/sunset/tool-designs/jtbl-island-split.md diff --git a/docs/tool-designs/main-gate-defects.md b/docs/sunset/tool-designs/main-gate-defects.md similarity index 100% rename from docs/tool-designs/main-gate-defects.md rename to docs/sunset/tool-designs/main-gate-defects.md diff --git a/docs/tool-designs/main-lane-fix-s59.md b/docs/sunset/tool-designs/main-lane-fix-s59.md similarity index 100% rename from docs/tool-designs/main-lane-fix-s59.md rename to docs/sunset/tool-designs/main-lane-fix-s59.md diff --git a/docs/tool-designs/o0-cc1-lanes.md b/docs/sunset/tool-designs/o0-cc1-lanes.md similarity index 100% rename from docs/tool-designs/o0-cc1-lanes.md rename to docs/sunset/tool-designs/o0-cc1-lanes.md diff --git a/docs/tool-designs/o0-path-s59.md b/docs/sunset/tool-designs/o0-path-s59.md similarity index 100% rename from docs/tool-designs/o0-path-s59.md rename to docs/sunset/tool-designs/o0-path-s59.md diff --git a/docs/tool-designs/tells-lane-s59.md b/docs/sunset/tool-designs/tells-lane-s59.md similarity index 100% rename from docs/tool-designs/tells-lane-s59.md rename to docs/sunset/tool-designs/tells-lane-s59.md diff --git a/docs/wave-metrics.md b/docs/sunset/wave-metrics.md similarity index 100% rename from docs/wave-metrics.md rename to docs/sunset/wave-metrics.md diff --git a/docs/wiki/Archive-index.md b/docs/wiki/Archive-index.md new file mode 100644 index 0000000000..153d99ca23 --- /dev/null +++ b/docs/wiki/Archive-index.md @@ -0,0 +1,84 @@ +# Archive index + +Every document retired from `docs/` at the Phase-33.5 consolidation (2026-09-07, archived at **v1.32.1**), with what it +was, what came of it, and where its information lives now. The files sit under `docs/sunset/`, moved with `git mv` so +their history is intact, for the owner's final review before deletion; nothing links into that folder, and this page +names each file as a path on purpose, so that deleting the folder later breaks no link. The rule for what goes there, +and the referrer census run before every move, are on [Docs and scratch conventions](Docs-and-scratch-conventions.md). +Records that stay — the PhaseEnds, the decision log, the cookbook — keep their citations of these files untouched. + +## Plans, roadmaps and frontier reports of closed phases + +| File (`docs/sunset/…`) | What it was | What came of it | Where it lives now | +|---|---|---|---| +| `gen2-roadmap.md` | The Gen2 roadmap (Phases 8–15), approved 2026-06-15; its Phase 14 (the public flip) was deferred and later re-planned | Gen2 ran as Phases 8–33 and closes at Phase 34; the two-repo mirror it described was superseded by the in-place history rewrite | `phase-ends/DIGEST.md` §1–§2; [Where the project goes next](Where-the-project-goes-next.md) | +| `roadmap-to-100.md` | The endgame roadmap v2 (Phases 27–32), re-baselined by every PhaseEnd | The goal was met: 0 stubs, 218 of 218 binaries; its P33 text was superseded by the re-charter | `PhaseEnd_Phase31/32/33.md`; `docs/phase34-seed.md` | +| `family-endgame-megaplan.md` | The Phase-26 "finish the decomp this weekend" input package | Its scan-derived thesis was byte-proven spent (three gate probes, 0%); superseded by roadmap v2 | `PhaseEnd_Phase26.md`; the decision log | +| `phase25-frontier-map.md` | Phase-25 endgame buckets, rtu-measured at 73.97% | Consumed by the family campaign | `PhaseEnd_Phase25.md` | +| `phase25-t6-curriculum.md`, `phase25-t6-fable-brief.md` | The frontier-model crack curriculum and its input brief (2026-07-09) | The curriculum ran; its outcome and lessons are recorded | `PhaseEnd_Phase25.md`; cookbook §31 (the codegen map it seeded) | +| `phase26-triage.md` | A 119-family crack triage produced by a workflow; paused before its reconcile task | The reconcile machinery was later built and the whole family frontier finished | `PhaseEnd_Phase26.md`; cookbook §33/§58/§59; [How to AI-decomp ch.10](../how-to-ai-decomp/10-integration-and-propagation.md) | +| `frontier-p30.md`, `frontier-s39.md` | Point-in-time frontier reports (2026-07-30, 2026-08-05), never re-baselined by design | The frontier they described emptied | `PhaseEnd_Phase30/31.md`; `docs/progress.fleet.md` (218 of 218) | +| `frontier-p32.md` | The last 21 functions and the five parked payloads, by blocker (2026-09-05) — the Phase-32 jumping-off document | All 21 banked and all 5 payloads onboarded; PhaseEnd_Phase31 asked that it be kept forever, so it is archived, never deleted | `PhaseEnd_Phase32.md`; the decision log P32 entries | +| `recovery-queue-s65.md` | 69 unbanked wave targets classified into four lanes, "build it, run it next session" | Absorbed by the P31–P32 finish; 0 open near-misses at the P32 close | `docs/backlog.md` (0 open); `PhaseEnd_Phase31.md` | +| `next-session-triage-ladder.md` | The triage-ladder specification and its three corrections | Built and shipped (`tools/triage_ladder.py`); the corrections are cookbook §376/§378 | `docs/wave-playbook.md` §4b; `docs/SETUP.md`'s tool row | + +## Studies and syntheses superseded by the wiki + +| File (`docs/sunset/…`) | What it was | What came of it | Where it lives now | +|---|---|---|---| +| `hindsight-study.md` | The optimal order for an AI-driven matching decomp, written mid-Phase 29 at ~78%, with seven meta-principles and a commission for a future study pass | Superseded part by part (its banner carries the table); its §7 became `tools/autopsy.py` + `tools/residual_class.py` | [How to AI-decomp ch.03](../how-to-ai-decomp/03-bootstrap-order.md) (the order, the permuter-failures track); `docs/retrospective.md`; `docs/generic-decomp-package.md` | +| `portable-decomp-workflow.md` | The target-agnostic system written during the campaign (§0–§11) — "the seed of the public deliverable" | The thirteen how-to chapters are its finished successor; six residual items were folded (the per-binary gate lock, the portability test, the lane-restart trap) | [How to AI-decomp](How-to-AI-decomp.md), chapters 00, 02, 05 | +| `hand-matching-process.md` | The Phase-17 Ghidra-driven hand-matching guide for the struct-heavy engine core, updated through July | Its durable content — the two-decompile loop, the five signature moves, target selection, running it as a wave — was folded; its progress numbers, pin recipes and session state were not | [The matching workflow](The-matching-workflow.md) "Matching by hand"; [ch.07](../how-to-ai-decomp/07-compiler-source.md) "Levers from the hand-matching era"; [ch.02](../how-to-ai-decomp/02-byte-gate.md) | +| `wave-metrics.md` | One row per crack wave (agents, tokens, wall-clock, banked) with the findings of each | The measurements and lessons were folded; the S37 execution block moved into the playbook | [ch.09](../how-to-ai-decomp/09-economics.md) "A wave, priced" and the sections after it; [ch.05](../how-to-ai-decomp/05-cards-lanes-waves.md); `docs/wave-playbook.md` §5 | +| `fable5-strategy-review-2026-07.md` | An outside-model strategy and scope review at Phase 22–23 | Its conclusions were acted on and recorded | `docs/retrospective.md`; the decision log P23 entries | +| `sister-decomps.md` | Cross-project knowledge-transfer notes (parked) | Realised as the cross-game signature tool and its check | [Tools from this project](Tools-from-this-project.md) (xsig); `docs/outreach/tools-announcement.md` | +| `calibration.md` | Measured close-rates for sizing Phases 28–29 (with a corrected row) | The phases it sized are closed; the economics are in the chapter | [ch.09](../how-to-ai-decomp/09-economics.md); `docs/retrospective.md` | +| `proto-correspondence.md` | The prototype research spike and its go/no-go (2026-06-14) | Verdict: no symbols in the prototypes; kept only as imported programs | `PhaseEnd_Phase3.5.md`; `config/ghidra/ROSTER.md` | +| `resident-dossier.md` | Per-function analysis of the last 14 resident stubs (2026-07-16) | The resident is 145 of 145; every lever it recorded has a cookbook section (§17, §37, §41, §43, §47, §52a/b, §53) | `PhaseEnd_Phase28/31/32.md`; the cookbook sections named | +| `canonical-decl-reconcile-design.md` | The design input for the ×134 giant unlock | Built as `tools/reconcile_decls.py` | cookbook §33; [ch.10](../how-to-ai-decomp/10-integration-and-propagation.md) | +| `automation-runbook.md` | The OpenRouter-era autonomous campaign runbook (retired 2026-08-31) | Its pipeline was replaced by the wave playbook; its rate-limit economics survive in the chapter | `docs/wave-playbook.md`; [ch.09](../how-to-ai-decomp/09-economics.md) | +| `exemplar_curriculum.md` | A residual curriculum/router for one overlay (snapshot 2026-06-19) | The frontier emptied; the atlas superseded it | `PhaseEnd_Phase31.md` (the atlas) | +| `family-manifest.md` | The Phase-25 structural-family target manifest | Superseded by the family surveys and the atlas | `docs/family-hseq.md`; `PhaseEnd_Phase25.md` | + +## Distillation ledgers + +| File (`docs/sunset/…`) | What it was | What came of it | Where it lives now | +|---|---|---|---| +| `distill/atbhbkbl.md` | 165 candidate idiom notes from waves at/bh/bk/bl, each disposed of with its A/B evidence | Landed as cookbook §265 (the verbatim-asm bank lane), §266 (the inert-rider law) and §267 (the addenda) — §267 cites this ledger as its evidence | `docs/matching-cookbook.md` §265–§267 | +| `distill/axbm.md` | 82 candidate notes from waves ax/bm | Landed as cookbook §268 (the register-pin law on call-clobbered registers) and §269 | `docs/matching-cookbook.md` §268–§269 | + +## Session tool designs and analyses (Phase 31, sessions 58–61) + +| File (`docs/sunset/tool-designs/…`) | What it was | What came of it | Where it lives now | +|---|---|---|---| +| `aprop-lane-s59.md` | The A-prop lane decomposition: 64 functions banked for zero tokens from a lane that had banked 0 of 117 | Byte-proven; the lane shipped | `PhaseEnd_Phase31.md`; the cookbook's lane sections | +| `frontier-analysis-s60.md` | The read-only frontier analysis that found ~571 already-correct drafts refused by plumbing | The integration-resolver lane and `decl_from_use.py`; the finding is the decision log's 2026-08-25 entry | `docs/decision-log.md` (P31 S61, "the wall is an integration wall"); [ch.10](../how-to-ai-decomp/10-integration-and-propagation.md) | +| `frontier-analysis-s61.md` | The exhaustive finish-plan ground truth at the S61 close | Consumed by the completion sprint | `PhaseEnd_Phase31.md` | +| `jtbl-automation-s59.md` | The carve → draft → bank jump-table pipeline | Byte-proven; the lane shipped | cookbook §8/§8a/§8b/§8e/§61b–d/§62/§260 | +| `jtbl-island-split.md`, `jtbl-island-split-review.md` | An unverified design study for the leading-island split, and its adversarial review ("go with changes — two of four steps wrong") | The corrected design shipped as `jtbl_carve --island-split` | cookbook §260; `tools/jtbl_carve.py` | +| `main-gate-defects.md` | Two defects in the executable's gate | Fixed | `docs/wiki/The-matching-workflow.md` (the main gate); `PhaseEnd_Phase31.md` | +| `main-lane-fix-s59.md` | Why 737 drafts for the executable banked zero | Diagnosed, fixed, byte-proven | cookbook §236; R40/R42/R43 | +| `o0-cc1-lanes.md` | An unverified lane study for the `-O0` and compiler-crash populations ("the headline claim was half wrong") | Its verified half became the `-O0` path below | `PhaseEnd_Phase31.md` | +| `o0-path-s59.md` | The `-O0` path: per-population bankability and a byte-proven crack | Shipped | cookbook (the `-O0` sections); `PhaseEnd_Phase31.md` | +| `tells-lane-s59.md` | The tells-lane taxonomy and its four failure causes (proposals) | Folded into the card builder's tell counts | `tools/build_wave_atlas.py` (its comment cites this note); [ch.05](../how-to-ai-decomp/05-cards-lanes-waves.md) | + +## Generated snapshots of the closed frontier + +These were written by tools that are still in the tree. Run at the closed frontier the tools would write empty +documents (0 open stubs), so the last populated snapshot is kept instead of being regenerated — see the conventions page. + +| File (`docs/sunset/generated-snapshots/…`) | Generator | Why it is archived rather than regenerated | +|---|---|---| +| `frontier-atlas.md` | `tools/atlas.py` (`make atlas`) | The atlas at 2,520 open instances; a regen renders empty | +| `family-cousins.md` | `tools/family_cousins.py` (`make atlas`) | The cousin-unit survey over the open frontier; empty at 0 stubs | +| `worklist.md` | `tools/worklist.py` (no target) | The July ranked worklist ("79 live stubs"); `make audit-frontier` reports it absent rather than reconciling against a stale copy | +| `autopsy.md` | `tools/autopsy.py report` (no target) | The permuter-failure classification of a P30 corpus that lives in untracked scratch | +| `burndown.jsonl` | `tools/burndown.py` (no target) | Per-session fleet snapshots; superseded by `docs/story-timeline.md` | +| `progress.{ov_SC01_005,ov_SC01_006,ov_SC01_077,ov_SC03_001,resident}.md`, `difficulty.{…same five…}.md`, `duplicates.{ov_SC01_077,resident}.md` | `tools/progress.py`, `tools/difficulty.py`, `tools/dup_report.py` via `make report BINARY=` | Twelve June/July snapshots of four binaries out of 218 (two carrying figures that are now wrong: the resident at 88.97%, 21 unmatched); regenerable for any binary on demand, so not published as a partial set | + +## The provenance archive's raw material + +| File (`docs/sunset/history/…`) | What it was | Where it lives now | +|---|---|---| +| `Fable5-ultracode-Full research findings-w42n9cp9t.output` | 216 KB of raw multi-agent research JSON from the first day (the sotn workflow, the Ghidra/PSX stack, WSL) | Everything actionable went into `docs/SETUP.md` and `docs/formats.md` in June 2026 | +| `debug menu link.txt`, `ghidra psx plugin link.txt`, `sotn-decomp wiki link.txt` | The original three reference URLs | `docs/SETUP.md` §2 and the memory map's source index | diff --git a/docs/wiki/Reference-index.md b/docs/wiki/Reference-index.md index 52678f96d3..a06afbec48 100644 --- a/docs/wiki/Reference-index.md +++ b/docs/wiki/Reference-index.md @@ -53,6 +53,7 @@ in the Archive index, not here. The conventions behind this page: [Docs and scra | [`badges/`](../badges/) | The four shields endpoints. | `tools/progress.py` | | [`difficulty.md`](../difficulty.md), [`duplicates.md`](../duplicates.md), [`duplicates.cross.md`](../duplicates.cross.md) | The executable's harvest queue and self-duplicates; the cross-binary duplicate groups. | `tools/difficulty.py`, `tools/dup_report.py`, `make report BINARY=main` | | [`backlog.md`](../backlog.md) | The near-miss ledger (0 open). | `tools/backlog.py`, `make report BINARY=main` | +| [`family-hseq.md`](../family-hseq.md) | The structural-family survey with its own coverage line — step 02 of the recorded contract run; at the closed frontier it reads "0 open instances", which is the statement. | `tools/family_hseq.py`; `tools/verify_contract.sh` step 02, `make atlas` | | [`story-timeline.md`](../story-timeline.md), [`story-timeline.svg`](../story-timeline.svg) | The dated digest timeline and its chart. | `tools/timeline.py`; `--check` in `make audit-digest` | | [`commit-map.tsv`](../commit-map.tsv) | The ordinal → hash map for commits cited in historical documents after the history rewrite. | `tools/public_rewrite/build_commit_map.py`, one-shot | diff --git a/phase-ends/CURRENT_PHASE.md b/phase-ends/CURRENT_PHASE.md index 2b94491e82..52b4afdb9e 100644 --- a/phase-ends/CURRENT_PHASE.md +++ b/phase-ends/CURRENT_PHASE.md @@ -44,7 +44,7 @@ in-tree links to `docs/wiki/.md`. 8. `.run/`: only what git tracks; no sca - [x] **3** Wiki — conventions + firewall: `Docs-and-scratch-conventions.md`, `The-ROM-firewall.md` (the gitignore template block); sidebar rows; Repository-layout/Contributing/ch.11 links; forward links in `doc_links_pending.txt` — Max — see Log 2026-09-07 Task 3 - [x] **4** Wiki — reference + direction: `Reference-index.md` (list-driven), `Where-the-project-goes-next.md`, Contributing "AI use — conduct", Home rewritten, sidebar sections — xHigh — see Log 2026-09-07 Task 4 — **P6 rules check done after it** - [x] **5** Integrate the six (hand-matching-process; wave-metrics + the s37w block → wave-playbook; portable-decomp-workflow vs the 13 chapters; generic-decomp-package attributed; hindsight §2.1/§7 → ch.03 + permuter-ils; the gen3 docs → the direction page); re-point every referrer incl. `retrospective.md:10–11` — xHigh — see Log 2026-09-07 Task 5 -- [ ] **6** Sunset moves (~61 files incl. the 6 frozen snapshots) with the referrer census by command; `docs/sunset/README.md`; `Archive-index.md` rows (backticked paths + `v1.32.1`); DIGEST §4 + `docs/history/README.md` refreshed; ledger coverage: every `git ls-files docs` path outside wiki/how-to/sunset is KEEP in the ledger — xHigh +- [x] **6** Sunset moves (59 files — `family-hseq.md` stays, see the log) with the referrer census by command; `docs/sunset/README.md`; `Archive-index.md` rows (backticked paths + `v1.32.1`); DIGEST §4 + `docs/history/README.md` refreshed; coverage: 0 `docs/` files outside wiki/how-to/sunset uncovered — xHigh — see Log 2026-09-07 Task 6 - [ ] **7** Checkers: `doc_links.py` (sunset refusal, index-derived allowlist, wiki-first warnings, TRACKED/UNTRACKED citation classifier + `--disk`, coverage ⊆); reachability in `wiki_render --selftest`; `timeline.py` regen in `report BINARY=main` + `--check` in `audit-digest`; the 14 dangling cookbook cites; the gitignore-template diff; tools-health wiring; SETUP rows — xHigh - [ ] **8** Tracked `.run/` prune (the 172 + the session logs + the 2 firewall files; `untracked_after_rewrite.txt`; `audit_public` check 4 with both controls; runbook §11; the four tool notes) — xHigh — **then P6 rules check** - [ ] **9** Memory reconciliation (move the off-project file; the 7 stale updated; `bfm-decomp-context-system` refreshed; the seed set under `decomp-architect/memory-seed/` with `upstream: PA` tags) — xHigh @@ -342,48 +342,76 @@ kit pointer), accelerators :7, SETUP :1312 (the S88 record line notes the archiv leavers outside records; 6 backticked prose mentions remain, each naming the archive (`docs/sunset/…` or "archived") — the sanctioned citation form. Verify: `doc_links` OK (1 pending), `wiki_render --selftest` 12/12. -## 🛑 SESSION CHECKPOINT — Tasks 0–5 ✓; NEXT = task 6 (the sunset moves + the Archive index; xHigh) +### 2026-09-07 — Task 6 — The sunset moves + the Archive index (xHigh) +The move list was built from ledger L1 (`.run/P33.5_sunset_list.txt`, scratch) and checked against the task-4 coverage one-liner. +**One correction to the plan (R14):** `docs/family-hseq.md` is NOT a frozen snapshot — `tools/verify_contract.sh` step 02 regenerates it +as part of the recorded contract run ("family_hseq regenerated: 217 binaries scanned, 0 open instances" is the contract's own +statement) and `tools/burndown.py` reads it; it stays as KEEP-GENERATED and got a Reference-index row. The other five frozen +snapshots (`frontier-atlas`, `family-cousins`, `worklist`, `autopsy`, `burndown.jsonl`) moved. **The referrer census** (the D3 command +over all 59 basenames, excluding records/self/indexes): every hit was either a substring false positive (`calibration`, `worklist`, +`autopsy` are ordinary words and tool names), an "archived"-style prose mention written in task 5, a provenance label in a tool +comment naming an S60/S61 analysis by its short name (left as provenance — not a path), or a digest/SETUP line, which were refreshed: +DIGEST §4 rewritten around the wiki (the index pages first; `roadmap-to-100` / `frontier-p32` / `automation-runbook` named as archived, +`phase34-seed` + the Gen3 pair added), DIGEST §1's gen2-roadmap line marked archived, `SETUP.md`'s integration_resolver row and +`docs/history/README.md` updated. `resident-dossier.md`'s eight cookbook § cites all resolve to headings (§17, §37, §41, §43, §47, +§52a, §52b, §53) → safe to move. **Moved:** 59 files by `git mv` into `docs/sunset/` — 25 root documents, `distill/` 2, `history/` 4, +`tool-designs/` 11, `generated-snapshots/` 17 (the 5 frozen + the 12 per-binary reports); `docs/tool-designs/` and `docs/distill/` are +gone. **Indexes:** `docs/wiki/Archive-index.md` (six groups; every file as a backticked path + what it was / what came of it / where +it lives now, with wiki-page links only), `docs/sunset/README.md` (the ☐ review table, 59 rows; deletion is the owner's); the last +pending entry cleared. **Verify:** README rows == `git ls-files docs/sunset` (59 = 59, `comm -3` empty); every sunset basename appears +in the Archive index (0 missing); the coverage check: 64 `docs/` files outside wiki/how-to/sunset, **0 uncovered**; `doc_links`: 56 +documents, 429 links, 0 pending, 0 broken; render selftest 12/12; `git log --follow` on three samples confirmed AFTER the commit +(a staged rename shows no history until committed). + +## 🛑 SESSION CHECKPOINT — Tasks 0–6 ✓; NEXT = task 7 (the checkers: doc_links extensions, render reachability, timeline wiring, the 14 dangling cites; xHigh) ### 0. How to use this block You are a FRESH SESSION that has read `PROJECT_CONTEXT.md`, `phase-ends/DIGEST.md`, `PhaseEnd_Phase31/32/33.md` and this file, and nothing else (R64). Replay this block verbatim, state phase / done / NEXT / effort, list the rules from the digest (R1–R83), then -WAIT for Drew. Rebuild the harness task list (16 rows, R28) marking tasks 0–5 completed and task 6 in progress. +WAIT for Drew. Rebuild the harness task list (16 rows, R28) marking tasks 0–6 completed and task 7 in progress. ### 1. Where we are **Phase 33.5** (sub-phase; v1.32.0 → v1.32.1), gate 1 approved 2026-09-07 by Drew in plan mode at Max; effort follows the plan's column (Max for tasks 10, 12, 15 — prompt at each transition, R27; xHigh now). Baseline HEAD `80d45b29b`; task 0 = `39d524991`; -task 1 = `a0cf302e5`; task 2 = `d06923a06`; task 3 = `5d10a0d12`; task 4 = `9970f1e62`; task 5 = the commit after it. Nothing under -`src/`, `config/` or the `Makefile` has changed; the fleet is 218/218 at the Phase-33 close. `docs/doc_links_pending.txt` carries ONE -entry (`docs/wiki/Archive-index.md` → task 6). Wiki: 16 pages + 13 chapters; sidebar sections Using / Working conventions / Reference / -How to AI-decomp / Where next / History (Archive index, pending). The six INTEGRATE documents are folded; the four that leave -(`hand-matching-process.md`, `wave-metrics.md`, `portable-decomp-workflow.md`, `hindsight-study.md`) have 0 links pointing at them -outside the records and only "archived"-style prose mentions. +task 1 = `a0cf302e5`; task 2 = `d06923a06`; task 3 = `5d10a0d12`; task 4 = `9970f1e62`; task 5 = `a0d4ae836`; task 6 = the commit +after it (59 renames + the two indexes). Nothing under `src/`, `config/` or the `Makefile` has changed; the fleet is 218/218 at the +Phase-33 close. `docs/doc_links_pending.txt` is EMPTY (comments only). Wiki: 17 pages (Home, the 10 "Using", Docs-and-scratch- +conventions, The-ROM-firewall, Reference-index, Where-the-project-goes-next, Archive-index, How-to-AI-decomp) + 13 chapters; every +sidebar row resolves. `docs/` outside wiki/how-to/sunset = 64 files, all covered by the Reference index or the README; +`docs/sunset/` = 59 files + README. The coverage one-liner (task-4 log) and the census command (D3) are the prototypes task 7 +turns into `tools/doc_links.py` checks. -### 2. What NEXT does (task 6, xHigh) — exact steps -1. Build the move list from ledger L1 (this file): SUNSET (33 root files incl. the 12 per-binary snapshots) + FROZEN (6: - `frontier-atlas.md`, `family-hseq.md`, `family-cousins.md`, `worklist.md`, `autopsy.md`, `burndown.jsonl`) + INTEGRATE residue (4) - + `distill/` (2) + `history/` (the `.output` + the 3 `*link.txt`) + `tool-designs/` (11) = **61 files**. Cross-check against the - task-4 coverage one-liner's uncovered list (66 lines = 61 files + the 5 split by spaces in the history names) — they must agree. -2. Per file, the D3 census: `git grep -n -F '' -- '*.md' '*.py' '*.sh' Makefile ':!phase-ends/PhaseEnd_*' ':!phase-ends/logs' - ':!phase-ends/CURRENT_PHASE.md' ':!docs/matching-cookbook.md' ':!docs/cookbook-index.md' ':!docs/decision-log.md' ':!docs/commit-map.tsv'` - must return only the file itself, the two index pages, and "archived" prose mentions. Known referrers to fix BEFORE moving: - `resident-dossier.md` — check each lever it records has a cookbook § (grep its §-cites); `tool-designs/frontier-analysis-s60.md` - (docstrings already re-pointed, task 1); `frontier-p32.md` (DIGEST §4 names it — refresh §4 in this task); `roadmap-to-100.md`, - `automation-runbook.md` (DIGEST §4 + `wave-playbook.md:4` name them — the playbook line says "retired"; keep as an archived mention); - `gen2-roadmap.md` (DIGEST §1 names it — it is a record; add "(archived)" there). The cookbook/decision-log/PhaseEnds are records and - keep their citations untouched. -3. `mkdir -p docs/sunset/{generated-snapshots,tool-designs,distill,history}`; `git mv` each file to `docs/sunset/` - (root files → `docs/sunset/`; the 6 frozen + the 12 per-binary snapshots → `docs/sunset/generated-snapshots/`). -4. `docs/sunset/README.md`: the review checklist — one row per file: path · class · the Archive-index row title · ☐ reviewed; the - header says deletion is Drew's decision after review and that nothing links into this folder. -5. `docs/wiki/Archive-index.md`: one row per moved file — `` `docs/sunset/` `` (backticked, never a link) · archived at v1.32.1 · - what it was (one line) · what came of it · where the information lives now (a wiki page link, a PhaseEnd, a cookbook §). Group by - the ledger's classes. Then remove the `Archive-index.md` line from `docs/doc_links_pending.txt` (the last pending entry). -6. Refresh DIGEST §4 (the doc map: drop the sunset names, add the wiki index pages) and `docs/history/README.md` (what left, where). -7. Verify: `comm -3 <(paths from Archive-index) <(paths from sunset README) <(git ls-files docs/sunset ':!docs/sunset/README.md')` empty; - `git log --follow --oneline docs/sunset/hindsight-study.md | wc -l` > 1 (history kept) on 3 samples; the task-4 coverage one-liner - now lists 0 uncovered; `doc_links` 0 broken / 0 pending; `wiki_render --selftest`. Log + checkpoint; commit by explicit path - (`git add docs/sunset docs/wiki/Archive-index.md …` — `git mv` stages the renames). Task 7 is xHigh. +### 2. What NEXT does (task 7, xHigh) — exact steps +1. `tools/doc_links.py` extensions (keep the existing behaviour and output shape; add checks, each printed with its denominator, R41): + (a) **sunset refusal** — any relative link whose resolved target starts with `docs/sunset/` is BROKEN, from any document (the two + index pages included; they use backticked paths); (b) **the index-derived allow-list** — for every document under `docs/wiki/` or + `docs/how-to-ai-decomp/`, a relative link that resolves under `docs/` but outside `docs/wiki/`, `docs/how-to-ai-decomp/` must be a + target of `docs/wiki/Reference-index.md` (a file, or under a directory the index links) or of `README.md`; `Reference-index.md` and + `Archive-index.md` themselves are exempt; (c) **coverage** — every `git ls-files docs` path outside wiki/how-to/sunset must be covered + the same way (the task-4 one-liner, as a check); (d) **wiki-first warnings** (exit 0) — a non-README, non-wiki document linking a + `docs/` file that has a wiki page for its topic: a small map {`SETUP.md`→Toolchain-setup, `verification.md`→Verification-and-progress, + `public-flip-runbook.md`→The-ROM-firewall, `gen3-standards.md`/`gen3-handoff.md`→Where-the-project-goes-next, `wave-playbook.md`→ + The-matching-workflow, `formats.md`/`memory-map.md`→Overlays-and-modules} — print, never fail; (e) **backticked citations** — every + `` `docs/…` `` or `` `.run/…` `` path in the checked set (regex over backticks; skip `<…>` placeholders and globs) is TRACKED (in + `git ls-files`) or UNTRACKED; FAIL only when a `docs/wiki/` or `docs/how-to-ai-decomp/` document cites an UNTRACKED path; print + counts for the rest; `--disk` adds an on-disk PRIVATE/DANGLING split for local use. PhaseEnds and `phase-ends/logs/` are not in the + checked set (records). Negative control (R39): before fixing them, `--disk` must name exactly the 14 dangling cookbook cites the + audit found (cookbook :36918 `.run/P32/t3/restored/sweep_func_80039308.py`, `.run/frontier_p32.json`, `.run/backlog_drafts/…`, + `.run/banked_func_*.json`, `.run/distill_inflight/*.json`, `.run/rtu_shadow/X.jsonl`, `.run/s7/scratch/spliced.c`, `.run/diag_plumbing.py` + in `tools/blocker_probe.py:26` — the cookbook is NOT in the checked set, so run the control over it explicitly with a path argument); + then fix those 14 lines in `docs/matching-cookbook.md` (rewrite each as "(scratch, not kept)" or point at the tracked copy) and + regenerate `docs/cookbook-index.md` (`tools/cookbook_index.py`) if a § heading line changed (it should not). +2. `tools/wiki_render.py --selftest`: add the reachability assertion — every `docs/wiki/*.md` except `_Sidebar`/`_Footer`/`Home` is linked + from `_Sidebar.md`, and every how-to chapter appears in both `_Sidebar.md` and `How-to-AI-decomp.md`; 0 unlisted today. +3. `Makefile`: in the `report BINARY=main` block add `$(VENV_PY) tools/timeline.py` (regen — check its CLI first: `--out`? the docstring); + in `audit-digest` add `$(VENV_PY) tools/timeline.py --check`; in `tools-health` after `doc_links` add the gitignore-template diff: + extract the ```` ```gitignore ```` fence of `docs/wiki/The-ROM-firewall.md` and `diff` it against `decomp-architect/templates/gitignore.decomp` + — that file lands in task 11, so make the diff step SKIP loudly when the template is absent (R43: "[skip] gitignore-template: no + decomp-architect/templates/gitignore.decomp yet") rather than fail. +4. SETUP rows (R21) for the three changed tools; the conventions page already describes the checks — confirm its wording matches. +5. Verify: `doc_links.py --strict` → 0 broken / 0 pending / 0 untracked-cited; the R39 control recorded in the log (14 before, 0 after); + `wiki_render --selftest` with the new assertion; `make audit-digest` green with the timeline check; then this file's log + checkpoint; + commit by explicit path. Task 8 is xHigh (the P6 rules check follows it). ### 3. Standing facts for every task of this phase - One commit per task, after this file's log line (R8/R42 form); commit by explicit path; no trailers (R5); Drew pushes (R6). diff --git a/phase-ends/DIGEST.md b/phase-ends/DIGEST.md index 1b804183b7..e83cba9e46 100644 --- a/phase-ends/DIGEST.md +++ b/phase-ends/DIGEST.md @@ -40,7 +40,8 @@ EXIT** (`docs/phase34-seed.md`; plan it fresh in plan mode at Max). **Gen3 opens SessionStart hook; symbols persist only via `tools/ghidra_apply_symbols.sh`, MCP renames do not); PCSX-Redux is Windows-native bridged over the web API (R11); no `/tmp`, scratch under `.run/` (R12). - **Roadmap:** the constitution's Gen1 roadmap ended at Phase 7 (Gen1 EXIT confirmed 2026-06-15); Gen2 phases 8–32 are - governed by `docs/gen2-roadmap.md` → `docs/roadmap-to-100.md` v2; **Phase 14 (public flip) became P33** — executed as an + governed by `docs/gen2-roadmap.md` → `docs/roadmap-to-100.md` v2 (both archived under `docs/sunset/` at Phase 33.5; the + outcomes are in the PhaseEnds); **Phase 14 (public flip) became P33** — executed as an IN-PLACE flip with the full rewritten history (not gen2-roadmap's two-repo mirror; decision log P33 S86), 2026-09-06/07. - **Effort doctrine (Drew 2026-07-04, `docs/effort-map.md` governs):** xHigh for most tasks, Max for deep tasks (phase plans, PhaseEnds, non-obvious debugging), Ultracode for breadth; plan mode always Max; every transition is prompted @@ -305,11 +306,15 @@ the binding text. R44–R63 one-liners are the P31 table, ratified at P32 gate 1 the LLM-looking text as the reason he minded; sotn-decomp forbids autonomous-tool PRs outright. ## 4. Where things live (the doc map a session needs) -`docs/SETUP.md` (environment, every tool's row, commands) · `docs/matching-cookbook.md` §1–§500 (idioms; 3.5 MB — -grep by §, never read whole) + `docs/cookbook-index.md` (symptom-keyed, derived, 566 KB — grep) · `docs/gcc-2.7.2-map/` -(the compiler map) · `docs/wave-playbook.md` (THE wave procedure; `docs/automation-runbook.md` is retired) · -`docs/effort-map.md` · `docs/roadmap-to-100.md` v2 · `docs/frontier-p32.md` · `docs/decision-log.md` (R31) · +**The wiki is the source of truth for documentation (Phase 33.5):** `docs/wiki/Reference-index.md` lists every live reference and +generated file with how to read it — start there; `docs/wiki/Docs-and-scratch-conventions.md` says where each kind of knowledge goes; +`docs/wiki/The-ROM-firewall.md` is the no-ROM policy; `docs/wiki/Archive-index.md` records every document retired to `docs/sunset/` +(kept for the owner's review; nothing links into it). The files a session touches most: `docs/SETUP.md` (environment, every tool's +row, commands) · `docs/matching-cookbook.md` §1–§500 (idioms; 3.5 MB — grep by §, never read whole) + `docs/cookbook-index.md` +(symptom-keyed, derived, 566 KB — grep) · `docs/gcc-2.7.2-map/` (the compiler map) · `docs/wave-playbook.md` (THE wave procedure; +the OpenRouter-era `automation-runbook.md` is archived) · `docs/effort-map.md` · `docs/phase34-seed.md` (the next phase's seed; +`roadmap-to-100.md` v2 and `frontier-p32.md` are archived — their outcomes are in the PhaseEnds) · `docs/decision-log.md` (R31) · `docs/accelerators.md` · `docs/memory-map.md` (addresses, provenance) · `docs/formats.md` · `docs/disc-completeness.md` + -`docs/disc-ledger.md` · `docs/backlog.md` (near-miss ledger) · `config/wave_exclude.txt` (pinned walls) · -`config/verbatim_manifest.json` · `phase-ends/logs/` (on demand only, R19) · `.run/` (scratch; allowlisted subtrees are -tracked — e.g. `.run/P32/t3/` drafts/ledger). +`docs/disc-ledger.md` · `docs/backlog.md` (near-miss ledger) · `docs/gen3-handoff.md` + `docs/gen3-standards.md` (Gen3) · +`config/wave_exclude.txt` (pinned walls) · `config/verbatim_manifest.json` · `phase-ends/logs/` (on demand only, R19) · `.run/` +(scratch; allowlisted subtrees are tracked — e.g. `.run/P32/t3/` drafts/ledger; the rules are on the conventions page).