docs(ledger): INDEX map + per-contract live files + history sidecars #306

2026-07-21T16:41:05+02:00

claude commented

2026-07-21 16:41:05 +02:00

The design ledger had accreted history through the project's pivots: 2968 lines / ~42k tokens, 59 cycle-stamped realization blocks, 18 [HISTORY] passages, 22 supersession markers, and 11 code-grounded defects stated as current truth (stale crate homes from the #288 roster split, InputSpec→PortSpec, the pre-#241 project model in C16, a stale retirement deferral in C24, three C28-internal inconsistencies).

This PR splits it along the ailang precedent:

INDEX.md — sole addressable entry point: foundation, external components, C-id-keyed contract map, genuinely-open threads only, and the new ledger discipline (live files carry current truth only; supersession markers in a live file are an audit finding; cycle-close edits happen in place, superseded text moves verbatim to the sidecar).
contracts/cNN-slug.md — one live file per contract: Guarantee/Forbids/Why with ratified refinements integrated + code-anchored Current state. All 11 confirmed defects fixed; crate anchors re-verified against the tree.
contracts/cNN-slug.history.md + INDEX.history.md — every superseded block preserved verbatim (stamps and issue refs intact) under a frozen-record banner. Nothing deleted.

Every unit passed an independent statement-by-statement zero-loss verification plus a code-accuracy spot check. C-ids and titles are unchanged — existing citations resolve as before. The configured ledger path (docs/design/INDEX.md) is unchanged; no skills-plugin or CLAUDE.md edits needed.

Follow-up candidates (not in this PR): CLAUDE.md domain-invariant 7 nearly duplicates C10 instead of compressing it; the big three live files (C10/C24/C18) could tighten further at future cycle closes.

The design ledger had accreted history through the project's pivots: 2968 lines / ~42k tokens, 59 cycle-stamped realization blocks, 18 [HISTORY] passages, 22 supersession markers, and 11 code-grounded defects stated as current truth (stale crate homes from the #288 roster split, InputSpec→PortSpec, the pre-#241 project model in C16, a stale retirement deferral in C24, three C28-internal inconsistencies). This PR splits it along the ailang precedent: - **INDEX.md** — sole addressable entry point: foundation, external components, C-id-keyed contract map, genuinely-open threads only, and the new ledger discipline (live files carry current truth only; supersession markers in a live file are an audit finding; cycle-close edits happen in place, superseded text moves verbatim to the sidecar). - **contracts/cNN-slug.md** — one live file per contract: Guarantee/Forbids/Why with ratified refinements integrated + code-anchored Current state. All 11 confirmed defects fixed; crate anchors re-verified against the tree. - **contracts/cNN-slug.history.md** + **INDEX.history.md** — every superseded block preserved verbatim (stamps and issue refs intact) under a frozen-record banner. Nothing deleted. Every unit passed an independent statement-by-statement zero-loss verification plus a code-accuracy spot check. C-ids and titles are unchanged — existing citations resolve as before. The configured ledger path (`docs/design/INDEX.md`) is unchanged; no skills-plugin or CLAUDE.md edits needed. Follow-up candidates (not in this PR): CLAUDE.md domain-invariant 7 nearly duplicates C10 instead of compressing it; the big three live files (C10/C24/C18) could tighten further at future cycle closes.

claude added 1 commit 2026-07-21 16:41:06 +02:00

docs(ledger): split the design ledger into an INDEX map, per-contract live files, and history sidecars 8688a60ded

The single-file ledger had grown to 2968 lines / ~42k tokens, mixing
current design law with accreted history: 59 cycle-stamped realization
blocks, 18 [HISTORY] passages, 22 supersession markers, and the C10 /
C22 / C24 reframe sagas layered several supersessions deep. A
code-grounding audit (31 agents, adversarially verified) confirmed 11
defects stated as current truth: stale crate homes from the C28 #288
roster split (cost nodes, PositionManagement, PositionEvent, Session),
the renamed InputSpec->PortSpec, the pre-#241 project model in C16 and
the open-threads section, a stale HarnessKind retirement deferral in
C24, and three C28-internal inconsistencies.

New shape, per the ailang precedent:

- INDEX.md stays the sole addressable entry point: foundation, external
  components, a C-id-keyed contract map (one line per contract), and
  only the genuinely open architectural threads.
- contracts/cNN-<slug>.md carries each contract's current truth only:
  Guarantee / Forbids / Why with ratified refinements integrated, plus
  a code-anchored Current state. All confirmed defects are fixed here;
  crate anchors were re-verified against the tree.
- contracts/cNN-<slug>.history.md (18 sidecars) and INDEX.history.md
  preserve every superseded block verbatim, stamps and issue refs
  intact, under a frozen-record banner. Nothing was deleted: superseded
  design intent remains an addressable working-tree artifact, off the
  per-cycle audit walk.
- Ledger discipline is now stated in INDEX.md: live files are edited in
  place at cycle close, superseded text moves verbatim to the sidecar,
  and a supersession marker in a live file is itself an audit finding.

Every contract file was verified against its old text by an independent
zero-loss pass (statement-by-statement) plus a code-accuracy spot check;
C-ids and contract titles are unchanged, so existing C-id citations in
code, tests, and issues resolve as before.

claude merged commit 8688a60ded into main

2026-07-21 17:43:58 +02:00

claude deleted branch ledger-refactor

2026-07-21 17:43:58 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Brummel/Aura#306