Files

T

arcattackandClaude Opus 4.8 f914fc040a context-system: complete migration -> CLAUDE.md is now a 160-line router (zero context lost)

Full migration of the 2236-line monolithic CLAUDE.md into the progressive-context
knowledge graph (per spark-lesson / expert-seed.md), so the deep RE knowledge loads
on-demand instead of every session.

ZERO CONTEXT LOST:
- docs/PROGRESS_LOG.md = the complete old CLAUDE.md, VERBATIM (byte-identical) -- the
  lossless safety net + the "full detail" quick-lookup fallback.
- 18 context/*.md topic files (1343 lines) digest every section (§1-3 -> project-overview,
  §4 -> content-archives, §5 -> asset-formats/bgf-format, §5a -> source-completeness,
  §5b/§8 -> wintesla-port, §7/§10 -> locomotion, §10a -> build-and-run, §10b ->
  reconstruction-method, §10c -> combat-damage + reconstruction-gotchas, §10d -> subsystems,
  render notes -> rendering, gauges -> gauges-hud, MP -> multiplayer, §9 -> open-questions).
- reference/glossary.yaml (53 terms). decomp-reference.md = the offsets/ClassIDs/addresses hub.

CLAUDE.md (160 lines) = router: identity, answer/reason protocols, quick-lookup table,
evidence tiers (T0 engine-truth / T1 decompiled+verified / T2 reconstructed+runtime /
T3 guarded / T4 hypothesis), conventions + DO-NOT (the systemic bug classes), structure.
Retains the load-bearing work directives (build recipe pointer, "keep current" mandate).

Knowledge graph validates CLEAN (scratchpad/checkctx.py -- all [[links]] + quick-lookup +
docs refs resolve; [[name]] -> topic file or glossary term). docs/*.md ledgers stay as the
detailed logs; context/*.md are the curated digests that route into them.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-07 22:19:50 -05:00

4.2 KiB

Raw Permalink Blame History

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

docs/PROGRESS_LOG.md = the verbatim old CLAUDE.md (lossless safety net + the "full detail" quick-lookup row).
CLAUDE.md = the router (git history preserves the old monolith too).
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.

4.2 KiB Raw Permalink Blame History