# Phase 01 — Progressive Context Restructure

**Goal:** adapt the `spark-lesson`/`expert-seed.md` progressive-context pattern to the bt411
port, turning the 2236-line monolithic `CLAUDE.md` into a thin router + a `context/*.md`
knowledge graph. Motivation: CLAUDE.md is loaded every session and is too large; the deep RE
knowledge should load on-demand.

## Design decisions
- **In-place** (context/ + reference/ at bt411 root, mirroring spark-lesson), NOT a separate repo.
- The router serves DOUBLE duty: expert-agent knowledge routing AND the load-bearing WORK
  directives (build recipe, "keep current" mandate) — bt411's CLAUDE.md drives active work, unlike
  spark-lesson's pure knowledge base.
- The existing **`docs/*.md` ledgers stay** as the DETAILED running logs (RECONCILE 1555 lines,
  GAUGE_COMPOSITE 627, HARD_PROBLEMS, SUBSYS_PLAN, P3_LOCOMOTION, …). The `context/*.md` files are
  the CURATED digests that route into them. (docs/ ≈ spark-lesson's phases/; context/ ≈ its context/.)
- **Evidence tiers adapted for RE:** T0 engine/header truth · T1 decompiled+verified · T2
  reconstructed+runtime-verified · T3 best-effort/guarded · T4 unconfirmed hypothesis.
- **Non-destructive:** the live `CLAUDE.md` is UNCHANGED until the migration is complete + approved.
  The proposed router is `context/_ROUTER-DRAFT.md`.

## Status — ✅ COMPLETE (migration done, CLAUDE.md swapped)

The full migration landed: `CLAUDE.md` is now a **160-line router**; the complete 2236-line
monolith is preserved verbatim as **`docs/PROGRESS_LOG.md`** (byte-identical — zero context lost);
**18 context topic files** (1343 lines) digest every CLAUDE.md section; the knowledge graph
validates CLEAN (all `[[links]]` + quick-lookup + docs refs resolve; `scratchpad/checkctx.py`).

### ✅ Foundation built (first pass)
- `reference/glossary.yaml` — ~45 terms (platform/engine, formats, scene/entity, reconstruction).
- `context/decomp-reference.md` — the quantitative hub: resource-type enum, ClassID map, mech
  offsets, damage delivery, weapon constants, env gates, tools.
- `context/reconstruction-gotchas.md` — the 12 systemic bug classes (the conventions/DO-NOT hub).
- `context/bgf-format.md` — geometry format + CONN/PCONN + LOD √3 + ramp shading (frames docs/BGF_FORMAT.md).
- `context/gauges-hud.md` — the gauge/MFD system (frames docs/GAUGE_COMPOSITE.md); the just-completed wave.
- `context/open-questions.md` — deferred systems + get-from-Nick.
- `context/_ROUTER-DRAFT.md` — the proposed slim CLAUDE.md (identity, protocols, quick-lookup,
  evidence tiers, conventions, structure).

### ✅ Second pass — all topics migrated (§→topic)
project-overview (§1-3), pod-hardware (§3), content-archives (§4/4a), asset-formats (§5),
source-completeness (§5a), wintesla-port (§5b/§8), build-and-run (§10a/10a-bis), reconstruction-method
(§10b), locomotion (§7/§10), subsystems (§10d), combat-damage (§10c), rendering (§10 fidelity),
multiplayer (§7/§8). Plus the first-pass hubs (decomp-reference, reconstruction-gotchas, bgf-format,
gauges-hud, open-questions). §6 (the standalone port/ D3D9 viewer sandbox) is noted in wintesla-port;
full detail in PROGRESS_LOG.

### ✅ Swap done
1. `docs/PROGRESS_LOG.md` = the verbatim old CLAUDE.md (lossless safety net + the "full detail" quick-lookup row).
2. `CLAUDE.md` = the router (git history preserves the old monolith too).
3. Verified: knowledge graph clean; a fresh session reads the router → quick-lookup → topics on demand.

### Maintenance going forward
New durable finding → the relevant `context/*.md` (+ the `docs/` ledger for exhaustive detail), with
an evidence tier. New topic → a `context/*.md` + a quick-lookup row + cross-refs. The `docs/*.md`
ledgers (incl. PROGRESS_LOG) remain the detailed logs; `context/*.md` are the curated digests.
Re-run `scratchpad/checkctx.py` to validate links after edits.

## Notes
- The router keeps the build one-liners + the "keep current" mandate so active port work is
  uninterrupted. The detailed §10 combat-bring-up narrative migrates to `combat-damage.md` +
  `locomotion.md` + `rendering.md` + the docs/ ledgers it already references.
- Cross-references use `[[topic-id]]`; the glossary uses `related_topics`.