docs(phase-33.5): task 6 — 59 documents archived into docs/sunset/ with git mv (25 closed-phase plans/studies, distill 2, history 4, tool-designs 11, generated-snapshots 17); docs/wiki/Archive-index.md (every file: what it was, what came of it, where it lives now — paths, never links) + docs/sunset/README.md (the owner's review checklist); DIGEST §4 rewritten around the wiki, §1 gen2-roadmap marked archived; history README + SETUP row refreshed; family-hseq.md stays (regenerated by the contract run) and joins the Reference index; pending list empty; checks: 59 rows == 59 files, archive coverage 0 missing, docs coverage 0 uncovered, doc_links 56 docs / 429 links / 0 broken; log + checkpoint

This commit is contained in:
Drew T
2026-09-07 17:48:52 -06:00
parent a0d4ae8368
commit 6ec4786bda
67 changed files with 244 additions and 48 deletions
+1 -1
View File
@@ -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/<bin>/<fn>.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 <N/N. Lane wrapper `tools/lanes/resolver_lane.sh`. First run S61: 424 items → 245 staged in 41 s. |
| | `tools/integration_resolver.py` | **(P31 S61)** THE INTEGRATION-RESOLVER LANE, zero model tokens (the S60 frontier analysis §4 — archived as `docs/sunset/tool-designs/frontier-analysis-s60.md`; the finding is the decision log's 2026-08-25 entry). 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/<bin>/<fn>.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 <N/N. Lane wrapper `tools/lanes/resolver_lane.sh`. First run S61: 424 items → 245 staged in 41 s. |
| | `tools/rtu_shadow.py` | **(P31 S61)** Shadow-mode `rtu_match` beside the wave gate to decide the gate INVERSION (§3 of the same analysis). `--wave X` (prospective, before X is gated, never while a gate is in flight) writes `.run/rtu_shadow/X.jsonl`; `--join X` after the gate commit prints the rtu-verdict × outcome matrix, P(bank | rtu MATCH), the false-negative rate, and current-vs-inverted build counts. Drafts map to binaries through the shard's targets file, never by bare name. |
| | `tools/decl_from_use.py` | **(P31 S61)** Infer a MINIMAL C89 extern for a data symbol a draft uses but its destination TU does not declare (the A-prop "no seed decl" / resolver `undeclared` class): access widths/sign/index-scale from the target `.s`, use-forms from the draft, same-binary spellings preferred; refuses STRUCT shapes, conflicting width evidence, function symbols. Negative-controlled on 4,702 banked ground-truth triples (kind agreement 97.4%; the control forced 3 instrument fixes before any case verdict was read). Importable `infer()`/`tu_compiles()` for aprop_autodraft:522 and the resolver. First measured run: 39 of 42 "undeclared" cases were ONE uncompilable TU, not draft defects — classify `undeclared` only after a TU-alone compile probe. Ledger `.run/decl_from_use/verdicts.jsonl`. |
| | `.run/baseline_red.txt` (live gate input) | **(P31 S61)** The binaries whose CLEAN build fails the locked SHA at HEAD. `gate_stage` refuses their drafts pre-build as class BASELINE-RED (a RED binary rejects every draft gated against it — 15/214 binaries were red on 08-26 00:00 and ate 174/245 of the resolver's doubly-verified drafts). Maintained by the fleet audit + repairs; the maintenance lane's lock-aware fleet sweep is the standing detector. Keep it current: a repaired binary comes OFF the list or its drafts stay unjudged. |
-1
View File
@@ -1,4 +1,3 @@
# docs/doc_links_pending.txt — link targets promised by a document and created by a later task of the SAME phase.
# Format: <repo-relative path><TAB><the task that creates it>. 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)
+9 -4
View File
@@ -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`).
+74
View File
@@ -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 |
+84
View File
@@ -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=<alias>` | 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 |
+1
View File
@@ -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 |
+62 -34
View File
@@ -44,7 +44,7 @@ in-tree links to `docs/wiki/<Page>.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 '<basename>' -- '*.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/<same relative path>`
(root files → `docs/sunset/<name>`; 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/<path>` `` (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).
+13 -8
View File
@@ -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).