mirror of https://github.com/Druthulu/BFM-decomp synced 2026-09-26 13:33:34 -04:00

Files

T

Drew T a0cf302e5b docs(phase-33.5): task 1 — unblock, code side: seven tool docstring/comment cites re-pointed off docs/tool-designs and docs/hindsight-study (decision-log S61 entry, cookbook §260, how-to ch.03 Phase 2b); CLAUDE.md R1–R83, the H1 fail-safe dated to Phase 33 C3, the effort default = the DIGEST §1 doctrine; log + checkpoint

2026-09-07 17:16:17 -06:00

68 KiB

Raw Blame History

CURRENT_PHASE — Phase 33.5: Docs consolidation, the wiki as source of truth, the tracked-`.run/` prune, and the day-one decomp kit

Gate 1 approved 2026-09-07 (Drew, plan mode, Max, Fable 5.1). Rules R74–R83 ratified at gate 1 (the Phase 33 candidates (a)–(j); binding; full text in phase-ends/DIGEST.md §3). The approved plan is reproduced VERBATIM at the end of this file (§"Approved plan") — its ~/.claude/plans/ copy is not part of the repo. This is a sub-phase between Phase 33 (closed at v1.32.0) and Phase 34 (the flip, docs/phase34-seed.md, untouched); it closes at v1.32.1. It changes no build input: the fleet's 218/218 is asserted by make tools-health (report BINARY=main + audit-digest), not by an R22 rebuild. Baseline HEAD at open: 80d45b29b (Drew's Phase-33 CLOSE commit; tree clean).

Milestone (gate 2 — what Drew confirms)

The wiki is the source of truth: every file under docs/ (outside wiki/, how-to-ai-decomp/, sunset/) is either a row in docs/wiki/Reference-index.md or README-linked (the ⊆ check in tools/doc_links.py); the five new pages exist and are reachable from _Sidebar.md; no wiki/how-to page links a docs/ file outside the index; nothing links into docs/sunset/; tools/doc_links.py --strict = 0 broken / 0 pending / 0 untracked-cited; a real tools/wiki_render.py run exits 0.
No information lost: every sunset file is under docs/sunset/ with history (git log --follow), a row in docs/wiki/Archive-index.md (what · outcome · where it lives now) and a review row in docs/sunset/README.md (comm -3 empty).
Tracked .run/ is flip-ready: git ls-files -ci --exclude-standard .run = 0; the finished-work groups untracked (the list in the task-8 log == git diff --diff-filter=D); the two disassembly files untracked and named in tools/public_rewrite/untracked_after_rewrite.txt; tools/audit_public.py OK with its new content check and both R39 controls recorded; purge_set.txt unchanged so gate_scan.py --all stays PASS.
The kit exists and installs: decomp-architect/ (README, intake, SETUP, methodology, templates, corpus, memory-seed, MANIFEST) passes tools/kit_lint.py, and the dry-run install in a throwaway repo produced the expected manifest with the guardrail assertions unchanged — or, past the cut line, KNOWN-DEFECTS.md says exactly what did not (R66).
Memory reconciled: the off-project memory moved, the seven stale ones updated, the portable set present as the kit's seed.
make tools-health OK; PhaseEnd_Phase33.5.md + DIGEST §0/§2 append + CURRENT_PHASE.md archived; left for Drew's close commit.

Effort / model (R7/R26/R27 — every transition is PROMPTED, never assumed)

Per task (the plan's table): Max for tasks 0, 3, 10, 12, 15; xHigh for the rest. Task 5's three document diffs may fan out to read-only agents (breadth); no Ultracode/Workflow otherwise. The dry-run (task 13) is ONE subagent under D6's guardrails.
Drew-only (R6): every git push; the gate-2 confirmation; the eventual deletion of docs/sunset/.

Owner decisions (binding — AskUserQuestion, 2026-09-07)

Kit in-tree now (decomp-architect/), split into its own repository after the flip as xsig was. 2. Phase 33.5, v1.32.1, (a)–(j) ratified now as R74–R83. 3. Sunset = git mv → docs/sunset/ + git rm --cached of finished tracked .run/; Drew reviews and deletes later. 4. The kit's SETUP.md opens with "install ProjectArchitect 2.0 first, then this". 5. BFM's own memories stay in ~/.claude (kit seed only; no .claude-state/ retrofit). 6. The two fable_cd4 disassembly files: untrack + an audit-only rule + a content check; no second history rewrite (the tracked C + the pinned compiler reproduce those bytes). 7. Link form: relative in-tree links to docs/wiki/<Page>.md. 8. .run/: only what git tracks; no scan of the untracked 29 GB. 9. README's docs/ links stay.

Tasks (strict order; one commit per task after this file is updated; harness task list = the same 16 rows, R28)

0 Gate 1 close-out: this file (ledgers + checkpoint), R74–R83 into DIGEST §3 (+ §0), phase34-seed.md amended, TaskCreate ×16 — Max
1 Unblock, code side: tool docstrings re-pointed (decl_from_use.py, integration_resolver.py, jtbl_carve.py, autopsy.py, residual_class.py); CLAUDE.md lines 11 / 61 / the effort-default sentence — xHigh — see Log 2026-09-07 Task 1
2 Unblock, doc side: banners (concurrency-design, gen2-mips-matching-model, psyq-worklist, distill/*, hindsight-study HISTORICAL + supersession table); SETUP §1a rewritten; the pin count re-derived (one dated number + its command, both gen3 docs) — xHigh
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
4 Wiki — reference + direction: Reference-index.md (list-driven), Where-the-project-goes-next.md, Contributing "AI use — conduct", Home rewritten, sidebar sections — xHigh — then P6 rules check
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
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
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
10 Kit part 1: README.md, intake.decomp.md, decomp-architect.md, templates/registry-E.decomp.md, corpus/decomp-kernels.md, templates/PLACEHOLDERS.md — Max
11 Kit part 2: the firewall pack, docs/run READMEs, ops-setup, bootstrap, CLAUDE overlay, pa-overlays.md, LICENSE/NOTICE/README/CONTRIBUTING skeletons, .clang-format + format snippet, tools/MANIFEST.md; tools/kit_lint.py in tools-health — xHigh
12 Kit part 3: SETUP.md (§0–§10, --answers, the PA-2.0 version pin, the honesty section, Path A only) — Max — then P6 rules check
13 Dry-run install under D6's guardrails; fix; re-run to green; fixture + expected manifest + logs tracked under .run/P33.5/kit-dryrun/ — xHigh
14 Wiki Start-a-new-decomp-project.md + README/Tools-from-this-project.md rows + SETUP rows (R21) + decision-log entry (R31) + accelerators entry if earned — xHigh
15 Close: real render; tools-health foreground; doc_links --strict; audit_public; PhaseEnd_Phase33.5.md + DIGEST §0/§2 + log archive; left for Drew — Max (Tier 1, WAIT for gate 2)

Blockers

None at open. The GitHub Support purge (ticket #4736982) is Phase 34's blocker, not this phase's.

The execution ledgers (from the three gate-1 audits; the audit reports exist only in the planning session — R30)

L1. The docs/ classification (path → class · note). Classes: KEEP-LIVE · KEEP-GEN · FROZEN→SUNSET · INTEGRATE→SUNSET · SUNSET

Path (under `docs/`)	Class	Note
`SETUP.md`	KEEP-LIVE	§1a is false ("never committed") — rewrite (task 2)
`accelerators.md`	KEEP-LIVE	README-linked; its substance reaches the wiki via the kit corpus + the new-project page's table
`actor-struct.md`	KEEP-LIVE	Gen3 input (`gen3-handoff` §5)
`automation-runbook.md`	SUNSET	already bannered HISTORICAL/superseded by `wave-playbook.md`; economics in how-to ch.09
`autopsy.md`	FROZEN→SUNSET	generated by `tools/autopsy.py` from untracked `.run/autopsy/`; a P30 snapshot
`backlog.md`	KEEP-GEN	`backlog.py prune` in `make report BINARY=main`; 0 open
`badges/*.json` (4)	KEEP-GEN	`progress.py write_badges()`; README shields
`burndown.jsonl`	FROZEN→SUNSET	`burndown.py`, no target; superseded by `story-timeline.md`
`calibration.md`	SUNSET	P28/P29 close-rate sizing; economics in ch.09 + `retrospective.md`
`canonical-decl-reconcile-design.md`	SUNSET	"✅ RESOLVED — built as tools/reconcile_decls.py (cookbook §33)"
`commit-map.tsv`	KEEP-GEN	one-shot, `public_rewrite/build_commit_map.py`; README-linked
`community-matching-model-plan.md`	KEEP-LIVE	linked by the published `matching-drafter-pipeline.md`; parked (licensing decision)
`concurrency-design.md`	KEEP-LIVE	banner "not yet implemented" is FALSE — six tools implement it; fix (task 2)
`cookbook-index.md`	KEEP-GEN	`cookbook_index.py --check` in tools-health
`debug-menu-list.txt`	KEEP-LIVE	primary data (Drew's transcription, S45)
`decision-log.md`	KEEP-LIVE	README-linked; append-only (R31)
`decompme-preset.md`	KEEP-LIVE	README-linked; Phase 34 E1
`difficulty.md`	KEEP-GEN	`make report`
`difficulty.{ov_SC01_005,ov_SC01_006,ov_SC01_077,ov_SC03_001,resident}.md` (5)	SUNSET	orphaned per-binary snapshots (June/July; resident says "21 unmatched" — wrong now); regenerable by `make report BINARY=<alias>`
`disc-completeness.md`	KEEP-LIVE	wiki `Overlays-and-modules` links it
`disc-ledger.md`	KEEP-GEN	`make audit-disc`
`distill/atbhbkbl.md`, `distill/axbm.md`	SUNSET	banners say "PROPOSED ONLY" but both LANDED as cookbook §265–§269 (verified); kept as the A/B evidence ledger the cookbook cites — banner fix first (task 2)
`doc_links_pending.txt`	KEEP-LIVE	the pending-link mechanism
`duplicates.md`, `duplicates.cross.md`	KEEP-GEN	`dup_report.py` in `make report BINARY=main`
`duplicates.{ov_SC01_077,resident}.md` (2)	SUNSET	orphaned per-binary snapshots
`effort-map.md`	KEEP-LIVE	governs effort; how-to 01/08 link it
`exemplar_curriculum.md`	SUNSET	`exemplar_miner.py` snapshot of 2026-06-19; frontier empty
`fable5-strategy-review-2026-07.md`	SUNSET	dated standpoint; conclusions in `retrospective.md` + decision log
`family-cousins.md`, `family-hseq.md`	FROZEN→SUNSET	`make atlas` would rewrite them EMPTY (0 stubs); keep the last populated snapshot
`family-endgame-megaplan.md`	SUNSET	bannered SUPERSEDED by `roadmap-to-100.md`; PhaseEnd_Phase26 records the outcome
`family-manifest.md`	SUNSET	Phase-25 target manifest; superseded
`formats.md`	KEEP-LIVE	wiki Home + Overlays link it
`frontier-atlas.md`	FROZEN→SUNSET	`make atlas` (2,520 open at `252dc930c`) → EMPTY at HEAD
`frontier-p30.md`, `frontier-s39.md`	SUNSET	point-in-time reports, self-declared not re-baselined
`frontier-p32.md`	SUNSET	PhaseEnd_Phase31 says "keep forever" → MOVE, never delete; outcomes in PhaseEnd_Phase32
`gcc-2.7.2-map/*` (7 incl. `cite_overrides.tsv`)	KEEP-LIVE	README-linked; `gccmap_cites --check`
`gen2-mips-matching-model.md`	KEEP-LIVE	status line "not started" is stale — it was built; fix (task 2)
`gen2-roadmap.md`	SUNSET	Gen2 closes at Phase 34; the record is DIGEST + PhaseEnds
`gen3-handoff.md`	KEEP-LIVE (+INTEGRATE)	summarised into `Where-the-project-goes-next.md`; `doc_links` DEFAULT
`gen3-parking-lot.md`	KEEP-LIVE	correctly parked; `gen3-handoff` §7 re-adopts it
`gen3-standards.md`	KEEP-LIVE (+INTEGRATE §3)	README-linked; §3 → Contributing "AI use — conduct" + the direction page
`generic-decomp-package.md`	KEEP-LIVE (+attribute)	how-to 00/06 link it; attribute in ch.03/06
`hand-matching-process.md`	INTEGRATE→SUNSET	→ `The-matching-workflow` (+ch.07)
`hindsight-study.md`	INTEGRATE→SUNSET	mid-P29 at ~78%; superseded part-by-part (ch.03, `generic-decomp-package`, `retrospective`, `gen3-handoff` §5; §7 realised as `autopsy.py`); referrers: how-to 00/02, `retrospective.md:10–11`, `gen3-handoff` §8, `autopsy.py`/`residual_class.py` docstrings, backticked cites
`history/README.md`, `history/claude-bfm-starting-point.md`, `history/project_architect_v1.3.0.md`, `history/cheap-tier-ab-experiment.md`	KEEP-LIVE	archive; story/retrospective cite them
`history/Fable5-ultracode-Full research findings-w42n9cp9t.output`	SUNSET	216 KB raw JSON, one reader (its README); folded into SETUP/formats long ago
`history/{debug menu link,ghidra psx plugin link,sotn-decomp wiki link}.txt` (3)	SUNSET	URLs already in SETUP
`idxtab-map.md`	KEEP-LIVE	Gen3 lever (`gen3-handoff` §5)
`matching-cookbook.md`	KEEP-LIVE	README-linked; grep by §
`matching-drafter-pipeline.md`	KEEP-LIVE	README-linked
`memory-map.md`	KEEP-LIVE	wiki links it
`next-session-triage-ladder.md`	SUNSET	"BUILT AND SHIPPED (P31 S69) — Status: DONE"; corrections = cookbook §376/§378
`outreach/archipelago.md`, `outreach/tools-announcement.md`	KEEP-LIVE	Phase 34 tasks
`permuter-ils.md`	KEEP-LIVE	README-linked; receives hindsight §7's pointer
`phase25-frontier-map.md`, `phase25-t6-curriculum.md`, `phase25-t6-fable-brief.md`, `phase26-triage.md`	SUNSET	closed phase artifacts; PhaseEnd_Phase25/26 carry the outcomes
`phase34-seed.md`	KEEP-LIVE	the live Phase 34 plan
`portable-decomp-workflow.md`	INTEGRATE→SUNSET	"the seed of the public deliverable" — the 13 chapters are its successor; diff, fold uniques
`progress.md`, `progress.json`, `progress.fleet.md`	KEEP-GEN	`make report BINARY=main`; CI reads `progress.json`
`progress.{ov_SC01_005,ov_SC01_006,ov_SC01_077,ov_SC03_001,resident}.md` (5)	SUNSET	orphaned per-binary snapshots (resident says 88.97% — wrong now)
`proto-correspondence.md`	SUNSET	verdict in PhaseEnd_Phase3.5 + `config/ghidra/ROSTER.md`
`psyq-sample-idioms.md`	KEEP-LIVE	small; SETUP §5.6 cites it
`psyq-worklist.md`	KEEP-LIVE	the only per-object record of the 1,256 LINKED functions; add COMPLETE banner (task 2)
`public-flip-runbook.md`	KEEP-LIVE	README-linked; §11 gains the residue note (task 8)
`recovery-queue-s65.md`	SUNSET	closed by outcome (backlog 0, 218/218)
`resident-dossier.md`	SUNSET	resident is 145/145; check each lever has a cookbook § before moving
`retrospective.md`	KEEP-LIVE	README-linked; links hindsight at :10–11 → re-point (task 5)
`roadmap-to-100.md`	SUNSET	goal met; successors `phase34-seed.md` + `gen3-handoff.md`
`second-oracle.md`	KEEP-LIVE	Makefile + four tools read it
`sister-decomps.md`	SUNSET	realised as xsig's cross-game check
`story.md`, `story-timeline.md`, `story-timeline.svg`	KEEP-LIVE / KEEP-GEN	README-linked; `timeline.py` to be wired (task 7)
`struct-core-pivot.md`	KEEP-LIVE	Gen3 input
`tool-designs/*` (11: aprop-lane-s59, frontier-analysis-s60, frontier-analysis-s61, jtbl-automation-s59, jtbl-island-split, jtbl-island-split-review, main-gate-defects, main-lane-fix-s59, o0-cc1-lanes, o0-path-s59, tells-lane-s59)	SUNSET	closed P31 session artifacts; outcomes in PhaseEnd_Phase31 + cookbook §8/§8a/§8b/§8e/§61b–d/§62/§154-A/§236/§260; re-point `decl_from_use.py`, `integration_resolver.py`, `jtbl_carve.py` first
`tooling-audit.md`	KEEP-LIVE	how-to ch.04's evidence base — cite it there (task 5)
`verification.md`	KEEP-LIVE	README-linked; CI header cites it
`wall-taxonomy.md`	KEEP-LIVE	Gen3 input
`wave-metrics.md`	INTEGRATE→SUNSET	→ ch.09/05; its `.run/s37w.js` execution block → `wave-playbook.md` first
`wave-playbook.md`	KEEP-LIVE	the procedure
`worklist.md`	FROZEN→SUNSET	July snapshot ("79 live stubs"); read by `make audit-frontier` (outside tools-health) — the audit reports absence
`wiki/`, `how-to-ai-decomp/`	the wiki	the source set of `wiki_render.py`

L2. Tracked `.run/` (1,086 files / 15 MB at open)

Untrack, self-sealing (172 tracked-but-ignored; verified this session): s6h 38 · s6f 25 · w6 16 · s37 16 · s6g 15 · s6i 8 · t4 6 · s6b_cracks 2 · fable_frontier 2 · audit 1 · 43 loose root files (alias_defs.py, attract_loadmap.jsonl, disc_code_sweep.txt, jr_family_sweep.py, maintenance.sh, resident_wave_verdicts.json, sc03_hunt_loadmap.jsonl, s3_sc07_whale.py, s6f_gate.py, s6g_*, s6h_*, s10*, s33–s36_capture.py, s36_wave.json, s36w.js, s37_wave.json, s37w.js, s7_*, s8_*, s9_*, w6*, w7_wave*.json). Prose citations to move first: wave-metrics.md:62 (.run/s37w.js) and :153 (.run/s6f_gate.py). Tool defaults/comments to annotate: wave_judge.py:8 (WAVE=.run/t4), claude_wave_packs.py:16, jtbl_family_bank.py:380, dedup_propagate.py:114.
Untrack with .gitignore narrowing (enumerate at task 8): .run/P32/t3s3/ session logs (67 tracked: 44 .log, 15 bank_*) and the duplicate tools_health.log / report_close.log under t3s3/t4b/t4d/t4e — keep any copy a doc cites (verification.md cites .run/P32/t4e/r22_check.log).
Untrack + audit rule (the firewall pair): .run/giants/fable_cd4/mine_full.txt (398 lines, 0: 27bdffc0 addiu sp,sp,-64) and target_full.txt (399 lines, 0: addiu $sp, $sp, -0x40) — allowlisted by !/.run/giants/fable_cd4/*.txt. purge_set.txt must NOT change (gate_scan.py reads it as the history census); the rule goes in tools/public_rewrite/untracked_after_rewrite.txt, read by audit_public.py.
KEEP-TRACKED: P33/verify (15) · P33/e1 (1) · P32/** drafts/notes/banks/reproducers (482 minus the logs above) · giants (279, minus the pair) · S79w (33) · s43 (22) · fable_80178004 (22) · wave22 (19) + wave22_targets.json · near6 (16) + near6_measure.{py,json} + near6_ils_*.log · s45 (12) · s42 (3) · probe_jtbl (3) · backlog.jsonl · fuel_manifest.json.
POST-FLIP (0 tracked files; on disk only): .run/decompme/, .run/public_rewrite/, .run/objdiff/ — Phase 34 tasks 2/7.
Doc citations of .run/: 653 backticked (58 tracked / 581 untracked-on-disk / 14 dangling incl. cookbook :36918 .run/P32/t3/restored/sweep_func_80039308.py, .run/frontier_p32.json, .run/backlog_drafts/func_80011380.c, .run/banked_func_*.json, .run/distill_inflight/*.json, .run/rtu_shadow/X.jsonl, .run/s7/scratch/spliced.c, .run/diag_plumbing.py) — the checker is disk-independent (TRACKED/UNTRACKED by git ls-files), strict only for wiki/how-to pages.

L3. The memory store (81 files + MEMORY.md under `~/.claude/projects/-home-musashi-bfm-decomp/memory/`)

ALREADY-IN-REPO (52): autonomous-lane-architecture · breadth-isolated-agents-not-serial† · build-tasklist-after-plan-approval · capture-knowledge-before-fresh-session · carve-state-files-never-blanket-add · check-against-a-known-true-case · checkpoint-current-phase-before-pause · commit-banked-work-immediately · commit-message-from-tool-output · commit-per-task-after-phase-log · cross-project-idiom-discovery · decomp-accelerator-ledger† · decomp-community-ai-standards · derive-from-invariants-not-reparsing · dont-conclude-unsteerable-try-register-pins · effort-prompt-ultracode-on-breadth · exonerate-the-instrument · fable-agents-for-lane-tooling† · fleet-tool-parallelism-defaults · gating-speed-playbook† · journal-notes-are-pack-fuel · lane-blockers-are-harness-not-model · matching-cookbook · matching-is-solved-integration-is-the-bottleneck · mcp-reconnect-after-restart · mcp-renames-dont-persist-use-applysymbols · measure-the-steady-state-not-the-launch · no-commit-co-author · no-tmp-project-local-data · parallel-gate-via-worktrees · pass-j-to-every-build · phase-worklogs-reference-only · pkill-pattern-kills-own-shell · private-repo-backup-policy (partly stale) · quote-the-denominator · report-every-lane-not-the-loud-one · reprobe-exclude-lists-after-tool-fixes · rescan-twins-after-every-bank · session-start-list-rules-in-full · session-summary-plain-english · setup-md-keep-current · silently-narrowed-tool-scope · standalone-match-is-not-bankable · structural-family-mechanical-remap · subagent-model-ladder† · tool-must-refuse-unsupported-input · tools-folder-convention · ultracode-harvest-pattern · verdict-names-its-instrument · verify-blast-radius-not-just-defect · wave-harvest-is-a-pipeline-step · wave-prompt-seed-step0-and-gaps · web-research-compiler-quirks. († carries a portable rider: the quadratic main-loop-context arithmetic; the accelerator-ledger habit as a rule; the per-stuck-lane briefing recipe; "a slow gate is a BUG"; what the frontier model is NOT for.)
PORTABLE-NOT-IN-REPO (14): in PA 2.0's seed already — repo-self-contained-claude-state, drew-working-preferences, dont-block-loop- with-askuserquestion, justify-new-tools-before-adopting, clarify-misconception-before-costly-action. New for the kit (9): no-sleep-polling-background-tasks, live-coop-answer-before-grinding, tools-health-foreground-not-background, resume-means-resumefromrunid, tool-change-updates-siblings-and-docs, bank-idioms-before-checkpoint, phaseend-verbosity-for-the-retrospective, offline-tooling-first, wave-playbook-is-the-procedure — plus the five riders and three decomp seeds (matching-flywheel, byte-gate-is-the-only-claim, mcp-reconnect-after-restart). upstream: PA tag on the four harness-generic ones.
BFM-SPECIFIC (9, keep): bfm-decomp-context-system · continuous-gater-lane-plan · crack-wave-sweep-map-regen · dedup-backlog-leave-it · disc-dump-location · endgame-budget-unconstrained · gate-main-only-with-gate-main · roadmap-to-100 · wsl-disk-capped-75gb.
STALE (7, update in place): cheap-tier-ab-validated · effort-doctrine-xhigh-default (the memory is right; CLAUDE.md is stale) · private-repo-backup-policy · project-endgame-deliverables · roadmap-to-100 · rom-content-git-policy · bfm-decomp-context-system's status block.
OFF-PROJECT (1, move): vantage-edge-never-leaks → the Vantage project's memory directory under ~/.claude/projects/.

L4. The wiki mechanism, the link policy and the kit design — see the Approved plan (§"What exists", D1–D6) below.

Log (newest last; one entry per task; the 🛑 block at the end is rewritten after every task)

2026-09-07 — Task 0 — Gate 1 close-out (Max)

Plan approved in plan mode after three exploration audits (docs/ tree, tracked .run/ + firewall, memory store + ProjectArchitect) and one adversarial Plan-agent review (12 amendments folded in: forward links via the pending list; referrer census by command; frozen snapshots instead of empty regens; the audit-only rules file because purge_set.txt is the history gate's census; a content check whose shapes come from the offenders; disk-independent citation checks; the kit as a Phase-0.5 overlay with an intake document for PA's own interview; dry-run write guardrails; a cut line). Spot-checked the claims the plan leans on (172 tracked-but- ignored; the two disassembly files; §265–§269 landed; the tools-health chain). R74–R83 written into DIGEST §3 from the Phase-33 candidates' text; DIGEST §0 notes the sub-phase; phase34-seed.md amended. Harness task list built (16 rows). Effort for task 1 is xHigh — the transition is prompted (R27). Commit 39d524991.

2026-09-07 — Task 1 — Unblock, code side (xHigh; Drew set `/effort xhigh`)

Seven docstring/comment cites re-pointed to durable records: decl_from_use.py + integration_resolver.py → the decision log's 2026-08-25 (P31 S61) "the wall is an integration wall" entry (the S60 frontier analysis's 178/292 = 61% and ~571 finished-draft measurements live there); jtbl_carve.py ×3 → cookbook §260 (the leading-island split; the review's correction #7); autopsy.py + residual_class.py → docs/how-to-ai-decomp/03-bootstrap-order.md Phase 2b (the permuter track — task 5 adds the "mine the permuter's failures" paragraph there; "originally hindsight-study §7, archived" kept as provenance). CLAUDE.md: R-range R1–R83; the H1 fail-safe dates the re-tightening to Phase 33 C3 (2026-09-06, the history rewrite) — the flip has not happened; the Reasoning section's "default working level is Max" replaced by the DIGEST §1 doctrine (xHigh for most tasks, Max for deep tasks, Ultracode for breadth; plan mode always Max). Verify: py_compile on the five tools OK; git grep -E 'tool-designs|hindsight-study' tools/ Makefile = 0; doc_links OK. Deviation from the plan's verify column: make tools-health was NOT run for docstring-only edits (proportionality — nothing it measures changed); the first tools-health of the phase runs at task 7, where the Makefile and the checkers change.

🛑 SESSION CHECKPOINT — Tasks 0–1 ✓; NEXT = task 2 (unblock, doc side: banners, SETUP §1a, the pin count; 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–1 completed and task 2 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; Drew set /effort xhigh after task 0 (the Max tasks are 3, 10, 12, 15 — prompt at each, R27). Baseline HEAD 80d45b29b; task 0 = 39d524991; task 1 = the commit after it (docstrings + CLAUDE.md only). 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).

2. What NEXT does (task 2, xHigh) — exact steps

Banners/status lines (H5: add, never drop): docs/concurrency-design.md — replace "Not yet implemented." with "implemented in tools/shared_lock.py + the gate snapshot layer (P31); cited by gate_stage.py, bulk_harvest.py, dedup_propagate.py, ox_campaign.py, verify_worktree.py"; docs/gen2-mips-matching-model.md — "Status: design / not started" → built (P22–P23; train_lora.py/export_pairs.py/format_finetune.py; distilled by docs/matching-drafter-pipeline.md); docs/psyq-worklist.md — a top banner "COMPLETE at P31 S79 #5 — the residue (SSGM.o 8 ins inside matched C; the sound region's two cross-object-common walls) is named at the tail"; docs/distill/atbhbkbl.md + axbm.md — replace the "PROPOSED ONLY" banner with "LANDED as cookbook §265, §266, §267 (this file) / §268, §269 (axbm) on P31 S59b/c; kept as the A/B evidence ledger those sections cite"; docs/hindsight-study.md — a top banner "HISTORICAL — written 2026-07-20 mid-P29 at ~78%; superseded part by part" + the supersession table (§0–§2 → how-to ch.03 + generic-decomp-package.md; §3 → portable-decomp-workflow.md/the chapters; §4 → gen3-handoff.md §5 + wiki Tools-from-this-project; §5 → retrospective.md §5; §6 → fulfilled by retrospective.md + the how-to + tools/mine_hindsight.py; §7 → tools/autopsy.py — live pointer stays in ch.03).
docs/SETUP.md §1a (line ~68): rewrite — .run/ is gitignored by the contents-exclude rule /.run/* with 22 dated ! allowlist blocks (R20: "commit what a rerun CANNOT reproduce"); what IS tracked (P32/P33 evidence, the giants recon, the R20 ledgers) and what never is (the 29 GB of regenerable scratch); point at the wiki conventions page (task 3 — register the forward link in docs/doc_links_pending.txt if you link it; or just name it in prose).
The pin count: run ONE grep over src/ (e.g. grep -rhoE 'register [^;]*__asm__$"\$[a-z0-9]+"$' src | wc -l — check what each doc's number was derived from first: gen3-handoff.md §3 shows its six commands) and write the same dated number + the exact command into docs/gen3-standards.md §4 and docs/gen3-handoff.md §3 (R75: a number in prose is a dated snapshot with its command).
Verify: .venv/bin/python tools/doc_links.py OK; the pin-count command reproduces the number; then this file's log + checkpoint; commit by explicit path (docs(phase-33.5): task 2 — …). Task 3 is Max — prompt Drew and WAIT (R27).

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).
Forward links from any new wiki page go into docs/doc_links_pending.txt as <path>\t<task N> in the SAME commit; the render refuses dead relative links (exit 1); tools/doc_links.py non-strict is in tools-health; --strict only at task 15.
Nothing moves while a wiki page / how-to chapter / doc_links DEFAULT document / tool docstring cites it — the referrer census command in the plan's D3 runs before every git mv.
purge_set.txt is never edited in this phase. Never git clean -x. The untracked 29 GB of .run/ is out of scope.
Effort transitions are prompted and waited for (R27): Max for tasks 3, 10, 12, 15; xHigh otherwise.

Approved plan (verbatim, 2026-09-07)

Phase 33.5 — Docs consolidation, the wiki as source of truth, the tracked-`.run/` prune, and the day-one decomp kit

Version: v1.32.0 → v1.32.1. Gate 1 ratifies the Phase 33 candidates (a)–(j) as R74–R83 (DIGEST §3). Effort: planning at Max (set); per-task effort annotated (R7). Phase number 33.5 per ProjectArchitect's sub-phase convention (PhaseEnd_Phase33.5.md sorts after 33 and before 34 under sort -V). Phase 34 (the flip) is untouched and follows this phase; docs/phase34-seed.md stays live. Reviewed adversarially by a Plan agent (12 amendments folded in).

Context

Phase 33 closed at v1.32.0 with everything before the public flip done; Phase 34 (flip + Gen2 exit) waits on GitHub Support (ticket #4736982). Reviewing docs/ ahead of the flip, Drew found the tree is not publishable as a documentation set: ~100 authored files from 33 phases — an out-of-date study (hindsight-study.md, written mid-P29 at ~78%), ledgers whose banners say "never applied" (docs/distill/), a 216 KB raw agent-research JSON (docs/history/…output), eleven per-session tool designs, frontier analyses and worklists for sessions long closed — beside the live references. The wiki (13 pages + 13 how-to chapters) was written in Phase 33 as a summary layer over those files and links back into them; it carries no page on how docs/ or .run/ are used, no .gitignore template, no AI-conduct rules, nothing on the Gen3 standards, and no "set up a new decomp project" installer. The tracked .run/ evidence (1,086 files) is visible on GitHub as-is, and 172 of those files are tracked only by index inertia. The working knowledge that ran the project — 81 memory files under ~/.claude — is two-thirds already written into the repo and one-third (Claude-Code harness and working-agreement wisdom) nowhere in it.

Drew's charter (2026-09-07): (1) the wiki is the single source of truth; every docs/ file is KEEP / INTEGRATE / SUNSET (docs/sunset/, indexed, for Drew's final review; no information lost); in-repo docs link wiki pages, not docs/ files (README's links may stay). (2) .run/ public readiness for what git tracks only — finished work leaves tracking, post-flip inputs stay; no scan of the untracked 29 GB. (3) The wiki documents the docs/ and .run/ conventions, a .gitignore template and the rules that keep ROM content out of history forever. (4) A Claude Code installer in the ProjectArchitect style that says "install ProjectArchitect 2.0 first", then sets up an entire new decomp project for the chosen game from this project's hindsight — the optimal starting order, the ROM firewall from commit one, the flywheel, the model ladder + effort doctrine, the strict AI-use rules, and the Gen3 readability items — built in-tree now, split out after the flip as xsig was. (5) The memory store reconciled; the portable memories become the kit's seed.

Owner decisions at this gate (AskUserQuestion, 2026-09-07): kit in-tree now (split later) · Phase 33.5 / v1.32.1 / ratify (a)–(j) now · sunset = git mv → docs/sunset/ + git rm --cached of finished tracked .run/ · the kit's SETUP.md opens with "install ProjectArchitect 2.0 first, then this" · BFM's own memories stay in ~/.claude (kit seed only; no .claude-state/ retrofit) · the two ROM-disassembly files: untrack + an audit rule + a content check in audit_public, no second history rewrite (the tracked C + the pinned compiler already reproduce those bytes) · link form: relative in-tree links to docs/wiki/<Page>.md.

What exists (the three audits, condensed — the execution ledger; copied into `CURRENT_PHASE.md` at task 0, R30)

The wiki mechanism (audit A §D)

tools/wiki_render.py: source set = docs/wiki/*.md + docs/how-to-ai-decomp/*.md only; how-to chapters render as How-to-AI-decomp-NN-name; wiki→wiki links become page names; any other in-repo relative link becomes https://github.com/Druthulu/BFM-decomp/blob/main/<path> (tree/ for dirs, raw.githubusercontent for images); a dead relative link = RenderError, exit 1. _Sidebar.md, Home.md's table and How-to-AI-decomp.md's table are hand-written; nothing checks a page is reachable from the sidebar. tools/wiki_sync.sh deletes every *.md in the wiki clone and copies the render in (--push is Drew's; the clone only exists after the flip). tools/doc_links.py: 25 DEFAULT documents + globs docs/wiki/*.md, docs/how-to-ai-decomp/*.md; checks every relative Markdown link; docs/doc_links_pending.txt (<path>\t<task> → PENDING instead of BROKEN; --strict refuses pending; must be empty at a PhaseEnd) is the mechanism for forward links; backticked .run/ / docs/ citations are NOT links and are not checked. make tools-health runs doc_links (non-strict) and only the render selftest (fixture), not a real render. Consequence: every new page's forward links are registered in doc_links_pending.txt in the same commit; nothing moves while any wiki page / how-to chapter / DEFAULT doc links it — re-point first, move second.

docs/ classification (audit A — the classes; per-file detail in the audit table, reproduced in CURRENT_PHASE.md)

KEEP-LIVE (45): SETUP.md, accelerators.md, actor-struct.md, community-matching-model-plan.md, concurrency-design.md (banner "not yet implemented" is false — six tools implement it), debug-menu-list.txt, decision-log.md, decompme-preset.md, disc-completeness.md, doc_links_pending.txt, effort-map.md, formats.md, gen2-mips-matching-model.md (status line stale), gen3-handoff.md, gen3-parking-lot.md, gen3-standards.md, generic-decomp-package.md, idxtab-map.md, matching-cookbook.md, matching-drafter-pipeline.md, memory-map.md, permuter-ils.md, phase34-seed.md, psyq-sample-idioms.md, psyq-worklist.md (add "COMPLETE at P31 S79" banner), public-flip-runbook.md, retrospective.md, second-oracle.md, story.md, struct-core-pivot.md, tooling-audit.md (how-to ch.04's evidence base — cite it there), verification.md, wall-taxonomy.md, wave-playbook.md, gcc-2.7.2-map/* (7), outreach/* (2), history/README.md, history/claude-bfm-starting-point.md, history/project_architect_v1.3.0.md, history/cheap-tier-ab-experiment.md.
KEEP-GENERATED (12, regenerated by a live target): progress.md/.json/.fleet.md, difficulty.md, duplicates.md/.cross.md, backlog.md, badges/* (4), cookbook-index.md, commit-map.tsv (one-shot), disc-ledger.md, story-timeline.md/.svg (timeline.py: today wired to nothing and STALE at HEAD — it derives from git log dates; regenerate inside make report BINARY=main and --check inside make audit-digest, the progress.py --check pattern).
FROZEN SNAPSHOTS of the closed frontier → SUNSET, never regenerated (6): frontier-atlas.md, family-hseq.md, family-cousins.md (make atlas would rewrite them EMPTY — 0 stubs), worklist.md (a July snapshot read by make audit-frontier, itself deliberately outside tools-health), autopsy.md, burndown.jsonl. Regenerating replaces the last populated snapshot with an empty document — information loss. They move to docs/sunset/generated-snapshots/ with archive rows naming the generator, the fact that a regen at HEAD renders empty, and the commit of the last populated run (via docs/commit-map.tsv). No worklist.py wiring.
INTEGRATE-INTO-WIKI (6), then sunset the residue: gen3-standards.md §3 (AI conduct) → Contributing + the direction page; gen3-handoff.md → the direction page; hand-matching-process.md → The-matching-workflow (+ch.07); wave-metrics.md → how-to ch.09/05 (+ the .run/s37w.js execution block → wave-playbook.md); portable-decomp-workflow.md → diff against the 13 chapters, fold uniques into ch.03/05/09; hindsight-study.md → ch.03 (its §2.1 + §7; §7 is realised as tools/autopsy.py). Known referrers of hindsight: how-to 00/02, gen3-handoff §8, retrospective.md:10–11 (a DEFAULT doc — real links), two tool docstrings, backticked cites in SETUP/accelerators/permuter-ils/wave-playbook/decision-log/cookbook. The hand list is not trusted: task 6 runs the referrer-census command per file.
SUNSET (~55 + the 6 snapshots): the 12 orphaned per-binary snapshots (progress|difficulty|duplicates.{ov_SC01_005,ov_SC01_006, ov_SC01_077,ov_SC03_001,resident}.md); tool-designs/* (11; re-point decl_from_use.py, integration_resolver.py, jtbl_carve.py first); distill/* (2 — "PROPOSED ONLY" banners are stale: both landed as cookbook §265–§269, verified; keep as the A/B evidence ledger the cookbook cites); history/Fable5-ultracode-…output, history/*link.txt (3); automation-runbook.md, calibration.md, canonical-decl-reconcile-design.md, exemplar_curriculum.md, fable5-strategy-review-2026-07.md, family-endgame-megaplan.md, family-manifest.md, frontier-p30.md, frontier-p32.md (PhaseEnd_Phase31 says "keep forever" → move, never delete), frontier-s39.md, gen2-roadmap.md, next-session-triage-ladder.md, phase25-frontier-map.md, phase25-t6-curriculum.md, phase25-t6-fable-brief.md, phase26-triage.md, proto-correspondence.md, recovery-queue-s65.md, resident-dossier.md (check each lever has a cookbook §), roadmap-to-100.md, sister-decomps.md.
README's own docs/ links (stay): verification, matching-cookbook, gcc-2.7.2-map/, decision-log, accelerators, story, retrospective, public-flip-runbook, commit-map.tsv, gen3-standards, permuter-ils, decompme-preset, matching-drafter-pipeline, how-to-ai-decomp/00-README (+ badges/progress.json).
Wiki coverage gaps (audit A §E): .run/ = one table cell; docs/ layout = one prose row; gitignore rules = prose, no template; accelerators = links only; portable-decomp-workflow / generic-decomp-package = one link each; gen3-standards / gen3-handoff / AI conduct = absent; no "start a new decomp" document (ch.03's 12-item checklist is the closest). SETUP.md §1a still says .run/ is "never committed" — false since P25. CLAUDE.md line 11 says "R1–R64", line 61 "since the public flip (Phase 33)" (should be "since Phase 33 C3"), and its "default working level is Max" contradicts DIGEST §1's xHigh doctrine.

Tracked `.run/` (audit B — 1,086 files / 15 MB; spot-checked this session)

172 tracked-but-ignored (verified: git ls-files .run | git check-ignore --stdin --no-index | wc -l = 172): s6h 38, s6f 25, w6 16, s37 16, s6g 15, s6i 8, t4 6, s6b_cracks 2, fable_frontier 2, audit 1, 43 loose root files. git rm --cached is self-sealing (no .gitignore edit). Move first: wave-metrics.md:62 (.run/s37w.js execution block → wave-playbook) and :153 (.run/s6f_gate.py). Tool defaults/comments citing pruned paths get a "(untracked since P33.5)" note: wave_judge.py:8, claude_wave_packs.py:16, jtbl_family_bank.py:380, dedup_propagate.py:114.
Allowlisted FINISHED session logs (enumerated at task 8): .run/P32/t3s3/ (67 tracked; 44 .log, 15 of them bank_*); the duplicate tools_health.log / report_close.log copies under t3s3/t4b/t4d/t4e — keep any copy a doc cites (verification.md cites .run/P32/t4e/r22_check.log); narrow their .gitignore re-includes.
KEEP-TRACKED (~860 after the prune): P33/verify (cited by verification.md, two wiki pages, the CI header, verify_contract.sh's cleanliness assertion), P33/e1 (E1 open in Phase 34), P32/** drafts/notes/banks (PhaseEnd_Phase32: "the only copy"), giants (cookbook ×12+), S79w, s42, s43, s45, wave22, near6, fable_80178004, probe_jtbl (a project-built TU, not ROM), 7 allowlisted root files.
FIREWALL: .run/giants/fable_cd4/{mine_full.txt,target_full.txt} (verified: 398/399 lines of 0: 27bdffc0 addiu sp,sp,-64 / 0: addiu $sp, $sp, -0x40), allowlisted by !*.txt, invisible to audit_public (path/hash/size). purge_set.txt is also gate_scan.py's census over reachable HISTORY — adding a rule there with no rewrite turns the runbook's first-push gate red permanently. So: an audit-only sibling file (D4).
POST-FLIP-PENDING: .run/decompme/, .run/public_rewrite/, .run/objdiff/ — 0 tracked files; on-disk only, governed by phase34-seed.md tasks 2 and 7. Nothing to do.
Doc citations of .run/: 653 backticked, 58 tracked / 581 untracked-on-disk / 14 dangling (cookbook :36918 etc.). Any disk-dependent check would go red on a fresh clone — the checker must be disk-independent (D2).

Memory store (audit C — 81 files + MEMORY.md, all outside git)

(1) ALREADY-IN-REPO — 52. Five carry portable riders: the quadratic main-loop-context arithmetic; the accelerator-ledger habit as a rule; the per-stuck-lane briefing recipe; "a slow gate is a BUG"; what the frontier model is NOT for.
(2) PORTABLE-NOT-IN-REPO — 14: in PA 2.0's seed already (cite): repo-self-contained-claude-state, drew-working-preferences (→ who-is-dev), dont-block-loop-with-askuserquestion, justify-new-tools-before-adopting, clarify-misconception-before-costly-action. New for the kit: no-sleep-polling-background-tasks, live-coop-answer-before-grinding, tools-health-foreground-not-background, resume-means-resumefromrunid, tool-change-updates-siblings-and-docs (+ no end-of-session audits), bank-idioms-before-checkpoint, phaseend-verbosity-for-the-retrospective, offline-tooling-first, wave-playbook-is-the-procedure; + the five riders; + three decomp seeds (matching-flywheel R16, byte-gate-is-the-only-claim, mcp-reconnect-after-restart R29). The four harness-generic ones (no-sleep-polling, tools-health-foreground, resume-means, tool-change-updates-siblings) are tagged upstream: PA so the split phase sends them to ProjectArchitect instead of burying them in a decomp kit.
(3) BFM-SPECIFIC — 9 (keep, not seeded). (4) STALE — 7 (update in place: cheap-tier-ab-validated, effort-doctrine-xhigh-default — the memory is right, CLAUDE.md is stale —, private-repo-backup-policy, project-endgame-deliverables, roadmap-to-100, rom-content-git-policy, bfm-decomp-context-system's status block). (5) OFF-PROJECT — 1: vantage-edge-never-leaks — move it to the Vantage project's memory directory under ~/.claude/projects/ (find it with ls), never delete from a store with no history; the kit's who-is-dev interview carries a generic "cross-project export policy" line with none of its content.
Other defects: pin count 43,857 (gen3-standards.md §4) vs 44,243 (gen3-handoff.md §3) — re-derive once, publish one number as a dated snapshot WITH its command in both docs and the wiki (the "re-derive, do not trust" form gen3-handoff already uses).

ProjectArchitect 2.0 (the model for the kit — and the constraint on it)

Package at /mnt/z/Storage/git/ProjectArchitect/project-architect-2.0/: SETUP.md (§0 execution contract; ✓ Verify per step; idempotent via CURRENT_PHASE.md checkboxes; commit by explicit path; never push; §8 fills the generation-time placeholders {{DOMAIN_FAILSAFES}}/{{DOMAIN_SESSION_START_EXTRAS}}/effort-map/cookbook/ops-setup via the Mode-1 intake, then §9 hard-stops; PROJECT_CONTEXT.md is permanent from then on, PA P1). templates/ (CLAUDE, PROJECT_CONTEXT skeleton, RULES_REGISTRY seed §A–§M

§E project rules with provenance tags + §F per-phase, CURRENT_PHASE with a per-task checkpoint log but no verbatim SESSION CHECKPOINT block, PhaseEnd without the believed/failed/sooner axis, cookbook, effort-map, ops-setup), corpus/, memory-seed/ (16 + MEMORY.md rows - [title](file) — line; §5 verifies the count 16), statusline/, tools/backup-claude-state.sh. BFM runs the older PA 1.3.0 layout (no RULES_REGISTRY.md); the kit targets PA 2.0 and is not testable against BFM — it must therefore pin the PA version it overlays and refuse otherwise (R43).

Design

D1. Wiki information architecture (the target `_Sidebar.md`; every new page's sidebar row ships in the page's own commit)

Home (rewritten; "records behind the wiki" → the Reference index).
Using the project — the existing 10 pages. Contributing gains "AI use — conduct" (gen3-standards §3 summarised, linking the direction page); Repository-layout's docs/ and .run/ rows link the conventions page.
Working conventions (NEW) — Docs-and-scratch-conventions.md: where each kind of knowledge goes (cookbook / decision-log / accelerators / runbook / PhaseEnd / DIGEST); authored vs generated ("numbers are generated, never typed"); the doc_links contract + pending list; docs/sunset/ + the archive index; frontier snapshots are frozen at the closed frontier; .run/: R12, the contents-exclude + ! allowlist idiom with its dated provenance comment, "commit what a rerun cannot reproduce", the per-session .run/<session>/ layout, untracked-.run/ citations are private breadcrumbs, the citation checker. · The-ROM-firewall.md: H1 with no private exemption; the nine classes of ROM-derived content; the copyable .gitignore template (a fenced block that must diff clean against the kit's templates/gitignore.decomp — one tools-health line); audit_public + the no-ROM CI + one purge set consumed by audit AND rewrite; the content check; cite-by-date; the post-purge realities; the one recorded residue (the two fable_cd4 files, in history by owner decision).
Reference (NEW) — Reference-index.md: one row per KEEP-LIVE / KEEP-GENERATED file, grouped (environment · formats and addresses · the knowledge base · verification and progress · releases · Gen3 inputs · history/), each with what it is, how to read it, who generates it. The only sanctioned place for wiki→docs/ links; a directory row (gcc-2.7.2-map/, badges/) is a prefix. The two index pages are exempt from the rules they define.
How to AI-decomp — 13 chapters unchanged in number; ch.03 absorbs hindsight §2.1/§7; ch.05/09 absorb wave-metrics; ch.04 cites tooling-audit; ch.11 links The-ROM-firewall; ch.03/06 attribute generic-decomp-package.
Where the project goes next (NEW) — Where-the-project-goes-next.md: Phase 34 (from phase34-seed) and Gen3 (standards §1–§3 in summary, the census with one dated pin count + its command, the invariant, the levers, the order of work, parked ideas).
Start a new decomp project (NEW, task 14) — Start-a-new-decomp-project.md: (1) install ProjectArchitect 2.0, handing PA's interview the kit's intake.decomp.md; (2) "Read decomp-architect/SETUP.md and do it"; what it installs and what it does NOT; the hindsight phase ladder; the AI-use rules; the Gen3 items at day one; the memory seed; the tools manifest; the accelerators as a one-line-per-entry table.
History (NEW section) — story, timeline, retrospective (via the index), Archive-index.md (NEW): every sunset file — what it was · its outcome · where the information lives now. Rows cite the file as a backticked path + the v1.32.1 tag, never as a link into docs/sunset/ — the index must outlive the folder's deletion without turning doc_links/wiki_render red.

D2. Link policy — `tools/doc_links.py` extensions (task 7), wired into tools-health

Canonical target = the wiki page, as a relative in-tree link to docs/wiki/<Page>.md.
Refuse any link into docs/sunset/ from any document (no permitted referrer — the archive index uses backticked paths).
Refuse a wiki/how-to link into a docs/ file not listed in Reference-index.md (the allowlist is derived from the index page with LINK_RE, resolved paths, directory rows as prefixes — R33; introduced only after tasks 4/6 exist).
Warn (list, exit 0) on non-README in-repo docs linking a docs/ file whose topic has a wiki page (a small topic→page map).
Backticked citations, disk-independent: classify every `.run/…` and `docs/…` citation in the checked set as TRACKED / UNTRACKED (git ls-files, never the disk); fail only when a wiki/how-to page cites an UNTRACKED path (exempt <…> placeholders); print counts with denominators for the records (R41); a local-only --disk flag adds the PRIVATE/DANGLING split for the R39 control (the 14 dangling cookbook lines are fixed once by hand). PhaseEnds and phase-ends/logs/ are records — excluded from the citation rules.
Reachability: wiki_render.py --selftest (or doc_links) asserts every docs/wiki/*.md except _Sidebar/_Footer/Home is linked from _Sidebar.md, and every how-to chapter appears in _Sidebar.md and How-to-AI-decomp.md (0 unlisted today).
Coverage: from task 7 on, git ls-files docs ':!docs/sunset' ':!docs/wiki' ':!docs/how-to-ai-decomp' ⊆ (Reference-index targets ∪ README targets), computed with LINK_RE over both pages (resolved paths; prefixes) — not substring grep.

D3. Sunset mechanics

Per file, in this order: (1) fold unique content into its wiki page; (2) referrer census by command — git grep -n -F '<basename>' -- '*.md' '*.py' '*.sh' Makefile ':!phase-ends/PhaseEnd_*' ':!phase-ends/logs' ':!docs/sunset' must return only Archive-index.md / docs/sunset/README.md rows; (3) git mv docs/<path> docs/sunset/<same path> (subfolders generated-snapshots/, tool-designs/, distill/, history/); (4) the archive-index row + the docs/sunset/README.md review row (file · class · ☐ reviewed). Set-equality check: comm -3 of the paths in Archive-index.md and docs/sunset/README.md vs git ls-files docs/sunset ':!docs/sunset/README.md' is empty. DIGEST §4's doc map and docs/history/README.md are refreshed in the same task. Deletion is Drew's, at Phase 34 or later; nothing in this phase deletes a document.

D4. Tracked `.run/` prune (task 8)

(1) git rm -r --cached the 172 inertia paths (after task 5 moved the two wave-metrics citations); (2) the finished session logs: git rm --cached + narrow their .gitignore re-includes; (3) the two firewall files: git rm --cached, a .gitignore exclusion, and a new audit-only rules file tools/public_rewrite/untracked_after_rewrite.txt (dated provenance comment: "remains in history by owner decision 2026-09-07 — the tracked C reproduces the bytes"), read by audit_public.py check 1 alongside purge_set.txt (refuse if empty, R43); purge_set.txt stays equal to the rewritten set so gate_scan.py --all stays green; runbook §11 + The-ROM-firewall cite the file; (4) audit_public.py check 4 — CONTENT: shapes derived from the offenders (asm-differ ^\s*\d+:\s+[a-z]{2,8}(\.[a-z]+)?\s+(\$|-?0x|-?\d|[a-z_]), objdump ^\s*[0-9a-f]+:\s+[0-9a-f]{8}\s+\w+, splat /* ADDR HEX hex */, glabel/dlabel blocks); criterion = longest CONTIGUOUS run per file, threshold 64 lines; prints each file's max run with denominators; R39 controls recorded in the log: before untracking exactly the 2 files fail; after, 0 — and tools/xsig/tests/fixture_{a,b}.txt (40 lines, the project's own function) pass. Verify: the removal list is enumerated in the log entry and git diff --name-only --diff-filter=D HEAD~1 | sort equals it; git ls-files -ci --exclude-standard .run | wc -l = 0 (the real invariant); git status --porcelain .run | grep -c '^??' = 0; every removed path still exists on disk; the four tool defaults carry the note; audit_public.py OK; CI no-rom green on Drew's next push.

D5. The kit — `decomp-architect/` (in-tree; mirrors PA 2.0's package shape; runs AFTER PA 2.0 as the project's Phase 0.5)

The slot. PA's constitution is permanent after PA §9 and PA §8 fills the domain placeholders during the PA install, so the kit never writes PROJECT_CONTEXT.md. Instead it ships intake.decomp.md — PA Mode 1's 12 intake items pre-answered for a decomp plus the hindsight phase ladder with machine-checkable milestones — which the developer hands to PA §8 during the PA install. The kit's own SETUP.md then runs as Phase 0.5 and does marked-section APPENDS (PA §5.1's precedent) to CLAUDE.md (decomp fail-safes + session-start extras), RULES_REGISTRY.md §E (G-numbers, each with provenance: BFM … per PA's registry rule — never BFM R-ids), docs/effort-map.md, docs/<project>-cookbook.md, docs/ops-setup.md, and appends rows to .claude-state/memory/MEMORY.md (PA §5's count 16 becomes 16+N). §1 asserts grep -q '^> \*\*Version:\*\* 2\.0' docs/project-architect.md and RULES_REGISTRY.md + phase-ends/ exist, else STOP and send the user to PA (R43); an existing decomp repository (PA Path B/C) is an explicit STOP — out of scope for this version.

decomp-architect/
  README.md                 for humans: (1) install PA 2.0 with intake.decomp.md as the interview input; (2) copy this folder;
                            (3) "Read decomp-architect/SETUP.md and do it"; what it installs; what it does NOT (see below); scope
  intake.decomp.md          PA Mode-1 intake pre-answered + the phase ladder (milestone · tools built · rules ratified · the
                            accelerator/retrospective citation that earned its position)
  SETUP.md                  §0 contract · §1 PREREQUISITES (PA 2.0 pinned; Path A only) · §2 the game interview (title, platform,
                            region/serial, dump path, container layout, SDK/compiler-era evidence, community work, goals, the
                            AI-disclosure + license decisions) · §3 the ROM firewall from commit one (gitignore, audit + its
                            planted-fixture negative control, no-rom CI, config/firewall.txt) · §4 layout + conventions READMEs ·
                            §5 toolchain bootstrap skeleton (bootstrap.template.sh; the fingerprint ladder as a Phase task) · §6 the
                            flywheel SKELETON (cookbook seed, effort map, the MANIFEST as Phase-1 tasks — the tools are NOT installed)
                            · §7 registry §E appends (G-rules, distilled R-rules, AI conduct, Gen3-at-day-one) · §8 CLAUDE/effort/
                            cookbook/ops-setup overlays + LICENSE/NOTICE/README/CONTRIBUTING skeletons · §9 memory seed + corpus ·
                            §10 verify (placeholder diff against PLACEHOLDERS.md), manifest, gitignore the package, delete-the-package
                            note, hard stop. Every step `✓ Verify`; idempotent via CURRENT_PHASE.md; `--answers <file>` unattended
                            mode ("if the file exists every question is answered from it; an unanswered question STOPs, never defaults")
  decomp-architect.md       the methodology: the ladder; the byte gate; lanes/waves; flywheel laws; models/effort as METHOD (BFM
                            numbers only inside ```calibration fences); conduct; Gen3-at-day-one; what stays hard
  templates/                gitignore.decomp · audit_public.template.py (hash sources from config/firewall.txt, R32 refusal when
                            absent) · no-rom.template.yml · firewall-fixture/ (a 16-byte synthetic blob + its sha1) ·
                            docs-README.md · run-README.md · ops-setup.decomp.md · bootstrap.template.sh · CLAUDE.decomp-overlay.md ·
                            registry-E.decomp.md · pa-overlays.md (ONE file of fenced blocks: DIGEST synopses-only template, the
                            🛑 SESSION CHECKPOINT block for CURRENT_PHASE, the PhaseEnd narrative axis, effort-map, cookbook,
                            wave-playbook, settings.json, mcp.json) · LICENSE/NOTICE/README/CONTRIBUTING skeletons · .clang-format
                            (sotn's) + a `make format` snippet · PLACEHOLDERS.md (copy-time vs generation-time; the grep is a diff)
  corpus/decomp-kernels.md  accelerators A1–A9/#12–#20/S77–P32 + the failure museum + retrospective §4, de-BFM'd; PA's "growing it" rule
  memory-seed/              the 9 new + 5 riders + 3 decomp seeds; MEMORY.md rows in PA's format; PA's 7 cited, not duplicated
  tools/MANIFEST.md         portable BFM tools by stage: what each does, BFM hard-codes flagged, "copy after the split" — Phase-1 tasks

Honesty (R41/R43): the installer verifies skeleton documents and config; it does not install a byte gate, a permuter harness or an m2c context — those are Phase-1 tasks from the MANIFEST until the split phase de-BFMs the tools. SETUP.md says so. Leak instrument: tools/kit_lint.py in tools-health — grep SLUS|Musashi|BFM|Druthulu|func_80|ov_SC|/home/musashi|/mnt/z|172\.17\.| \bR[0-9]{1,2}\b|§[0-9]+ over decomp-architect/ outside ```calibration fences and provenance: lines; the placeholder-set diff against PLACEHOLDERS.md; bash -n / py_compile; the gitignore-template diff against the wiki's fenced block. Platform scope: generic in structure, PS1/PsyQ-complete in content; other platforms get TODO(platform) markers (R43).

D6. The dry-run (task 13) — write-scope guardrails

A subagent in .run/P33.5/kit-dryrun/repo/ (a throwaway git init), with PA 2.0 copied from /mnt/z/…/project-architect-2.0/ and the kit copied in, runs PA's install then the kit's, from answers.md: fictional title + serial SLUS-99999, a dump path that does not exist, container/SDK-evidence strings, goals, license + AI-disclosure choices, PA §1 = Path A, PA §5 answers, "effort Max already set" for PA Gate 2 (logged as a deviation), pinned INSTALL_DATE, "skip PA §6" (no writes under ~/.claude), the synthetic control blob + sha1, positive AND negative git check-ignore probes (disks/x.bin, asm/x.s, extracted/x vs src/main.c, config/x.yaml), and expected-manifest.txt so "manifest present" is a diff. The brief forbids git clean anywhere and relative rm -rf; every git call is git -C <abs>. Before/after assertions by the main session: sha1sum ~/.claude/settings.json ~/.claude/statusline.sh, ls ~/.claude/projects/-home-musashi-bfm-decomp/memory | wc -l, git -C ~/bfm-decomp status --porcelain, ls ghidra | wc -l, ls dumps/*.bin | wc -l — all unchanged (R57). .gitignore gains one block: !/.run/P33.5/ /.run/P33.5/* !/.run/P33.5/kit-dryrun/ /.run/P33.5/kit-dryrun/* !…/answers.md !…/expected-manifest.txt !…/*.log (the nested repo stays ignored). Cut line: if the dry-run is still red at the end of session 3, ship decomp-architect/KNOWN-DEFECTS.md, make the re-run the split phase's first task, and the PhaseEnd says so (R66).

D7. Governance for the phase

Gate 1 ratifies (a)–(j) → R74–R83 (full text from PhaseEnd_Phase33 → DIGEST §3, the gate-1 commit); phase34-seed.md's "candidates proposed" line amended. One commit per task after the CURRENT_PHASE log line (R8/R42 form). No src//config/ build inputs change → no R22 fleet rebuild; make tools-health (foreground, ~15-min timeout) is the gate, plus a real render at task 15. P6 rules check after tasks 4, 8, 12. Forward links always via doc_links_pending.txt, emptied by task 15.

Tasks (in order; one commit each; effort per R7)

#	Task	Effort	Verify
0	Gate 1 close-out: `phase-ends/CURRENT_PHASE.md` (this plan as the checklist + the ledgers + a 🛑 checkpoint); R74–R83 into DIGEST §3 (+ §0 "Phase 33.5 open"); amend `phase34-seed.md`; TaskCreate one task per row (R28)	Max	DIGEST diff shows R74–R83; TaskList = 16 rows
1	Unblock, code side: re-point tool docstrings (`decl_from_use.py`, `integration_resolver.py`, `jtbl_carve.py` → cookbook §; `autopsy.py`, `residual_class.py` → the ch.03 anchor); CLAUDE.md lines 11 ("R1–R83"), 61 ("since Phase 33 C3"), the effort-default sentence → DIGEST §1's doctrine	xHigh	`git grep -n 'tool-designs\|hindsight-study' tools/` = 0; tools-health OK
2	Unblock, doc side: banners/status lines (`concurrency-design` implemented, `gen2-mips-matching-model` built, `psyq-worklist` COMPLETE, `distill/*` LANDED as §265–§269, `hindsight-study` HISTORICAL + supersession table); SETUP §1a rewritten (the allowlist idiom, what IS tracked); the pin count re-derived (one grep, one dated number + command in both gen3 docs)	xHigh	`doc_links` 0 broken; the pin-count command reproduces the number
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 registered in `doc_links_pending.txt`	Max	`wiki_render --selftest`; `doc_links` 0 broken (pending allowed)
4	Wiki — reference + direction: `Reference-index.md` (list-driven: every KEEP-ledger path has a row), `Where-the-project-goes-next.md`, Contributing "AI use — conduct", Home rewritten, sidebar sections. P6 rules check	xHigh	every KEEP-LIVE/GENERATED ledger path appears (script over LINK_RE); render selftest
5	Integrate the six (hand-matching-process, wave-metrics + the s37w block → wave-playbook, portable-decomp-workflow diffed vs the 13 chapters, generic-decomp-package attributed, hindsight §2.1/§7 → ch.03 + permuter-ils, gen3 docs → the direction page); re-point every referrer incl. `retrospective.md:10–11`	xHigh (the three diffs may fan out to agents — breadth)	`doc_links` 0 broken; a per-file "unique claims folded" checklist in the log
6	Sunset moves per D3 (~61 files incl. the 6 frozen snapshots); referrer census by command per file; `docs/sunset/README.md`; `Archive-index.md` rows (backticked paths + tag); DIGEST §4 + `docs/history/README.md` refreshed	xHigh	`comm -3` empty; `git log --follow` on 3 samples; `doc_links` 0 broken
7	Checkers: `doc_links.py` extensions per D2; reachability in `wiki_render --selftest`; `timeline.py` regen in `report BINARY=main` + `--check` in `audit-digest`; the 14 dangling cookbook cites fixed (+ `cookbook-index` regen); the gitignore-template diff line; tools-health wiring; SETUP rows (R21)	xHigh	`doc_links --strict` 0 broken/0 pending/0 untracked-cited; R39 control with `--disk`: the pre-fix tree fails on exactly the 14; coverage ⊆ check passes
8	Tracked `.run/` prune per D4 (the 172 + the session logs + the 2 firewall files; the audit-only rules file; the content check with both controls; runbook §11; the four tool notes). P6 rules check	xHigh	the D4 verify list, all recorded in the log
9	Memory reconciliation: move the off-project file; update the 7 stale in place; refresh `bfm-decomp-context-system`; write the seed set under `decomp-architect/memory-seed/` (+ `upstream: PA` tags)	xHigh	`MEMORY.md` rows == files; frontmatter valid; `kit_lint` grep clean on the seeds
10	Kit part 1: `README.md`, `intake.decomp.md`, `decomp-architect.md`, `templates/registry-E.decomp.md`, `corpus/decomp-kernels.md`, `templates/PLACEHOLDERS.md`	Max	every ladder phase cites an accelerator/retrospective item; `kit_lint` clean
11	Kit part 2: the firewall pack (gitignore, audit template + `config/firewall.txt`, fixture, no-rom yml), docs/run READMEs, ops-setup, bootstrap, CLAUDE overlay, `pa-overlays.md`, LICENSE/NOTICE/README/CONTRIBUTING skeletons, `.clang-format` + format snippet, `tools/MANIFEST.md`; `tools/kit_lint.py` in tools-health	xHigh	`kit_lint` clean (placeholder diff, `bash -n`, `py_compile`, gitignore diff vs the wiki block)
12	Kit part 3 — `SETUP.md` per D5 (§0–§10, `--answers`, the version pin, the honesty section, Path A only). P6 rules check	Max	placeholder diff clean; a structural read-through against PA's SETUP.md
13	Dry-run install per D6; fix defects; re-run to green; the answers fixture + expected manifest + logs tracked under `.run/P33.5/kit-dryrun/`	xHigh	manifest `diff` empty; placeholder grep clean; both check-ignore probe sets; trailer-free commits; the before/after assertions unchanged
14	Wiki `Start-a-new-decomp-project.md` + README/`Tools-from-this-project.md` rows + SETUP rows for the kit and the checkers (R21) + `decision-log.md` P33.5 entry (R31) + `accelerators.md` entry if the dry-run taught one	xHigh	render selftest; `doc_links --strict`
15	Close: a real render to `.run/P33.5/wiki-render/`; `make tools-health` foreground; `doc_links --strict`; `audit_public`; `git status` clean; `PhaseEnd_Phase33.5.md` (Build Log, Deviations, believed/failed/sooner, rules, changelog, recap), DIGEST §0/§2 append, `CURRENT_PHASE.md` → `phase-ends/logs/Phase33.5.md`; left uncommitted for Drew (R6)	Max	every checkbox walked (P7); pending list empty; the R18/R25 recap

Scale, with its denominator (R41): 16 tasks. Calibration: Phase 33 was priced at 17–21 sessions and took 4 (59 commits); this phase is roughly half of P33's writing plus one novel item (the dry-run). Estimate 2–3 sessions; the kit (tasks 10–13) is about half the work; the cut line is D6's.

Verification (end of phase)

make tools-health OK (foreground): the existing chain + doc_links (with D2) + render selftest with reachability + timeline --check + kit_lint + the gitignore-template diff.
A real wiki_render.py run exits 0; doc_links --strict 0 broken / 0 pending / 0 untracked-cited from wiki pages.
tools/audit_public.py OK incl. check 4; both R39 controls recorded (2 before / 0 after; xsig fixtures pass).
git ls-files -ci --exclude-standard .run | wc -l = 0; git status --porcelain .run | grep -c '^??' = 0; the removal list == the diff; purge_set.txt unchanged; gate_scan.py --all --worktree still PASS.
comm -3 archive-index / sunset README / git ls-files docs/sunset empty; the coverage ⊆ check passes.
Kit: the dry-run's manifest diff empty and the guardrail assertions unchanged; kit_lint clean.
Memory: MEMORY.md rows == files in ~/.claude/…/memory/; the seed has no BFM literals.
The fleet untouched: docs/progress.json unchanged (218/218, 100/100/100), asserted by make audit-digest.

Handoff rule for the executing session

Task 0 copies the ledgers above into CURRENT_PHASE.md — the audit reports exist only in this planning session's context (R30). The 🛑 checkpoint after every task carries: the task done, the exact commands, the counts, the pending-list state, and the next single step.

68 KiB Raw Blame History Unescape Escape

CURRENT_PHASE — Phase 33.5: Docs consolidation, the wiki as source of truth, the tracked-.run/ prune, and the day-one decomp kit