arcattackandClaude Opus 4.8
f914fc040a
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>
63 lines
4.2 KiB
Markdown
63 lines
4.2 KiB
Markdown
# 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`.
|