Skip to content

docs(architecture): the spine told once — narrative out, numbers to the ledger, one tree drawing#447

Merged
drewstone merged 1 commit into
mainfrom
docs/architecture-told-once
Jul 2, 2026
Merged

docs(architecture): the spine told once — narrative out, numbers to the ledger, one tree drawing#447
drewstone merged 1 commit into
mainfrom
docs/architecture-told-once

Conversation

@drewstone

Copy link
Copy Markdown
Contributor

What

The spine-cluster consolidation from the grounded DX evaluation: architecture.md is the decreed canonical spine, but it told the atom/tree/timescales 3x each, carried dated session narrative, and mirrored every gate number that already lives in the ledger.

  • docs/architecture.md (888 -> 668 lines). Header loses the dated stamps + status inventory (live status = .evolve/current.json + the memory ledger; the wins-on-conflict rule stays). The session-narrative §0 is deleted (each locked decision verified restated: atom -> §1, selector != judge -> §1/§7, scaffold-then-GEPA -> §9, moat -> §8, sandbox driver -> §3). Gate-A/Gate-B inline definitions become pointers to their canonical homes (interpretations §5 / learning-flywheel.md). §11 collapses to a ledger pointer keeping only the two timeless laws verbatim (domain-boundary, honesty). §12 is deleted (executed to-do list; the vocabulary law moves to glossary.md; bench/src/{refine-loop,run-pool,directives}.ts verified present). §13/§14 merge into ONE picture book with a single tree drawing.
  • Two stale factual claims corrected: §13.7 said the ask/answer edges were "designed, not built" — ask_parent/answer_question are shipped (src/mcp/tools/coordination.ts:159-160, priority-queued on the event bus); and two anchors re-verified against code (Agent at supervise/types.ts:49, not :51; createExecutor at supervise/runtime.ts:1517, not :1137).
  • docs/architecture-interpretations.md (236 -> 233 lines). Status header + §2 selector numbers + §5 measured paragraph become qualitative verdict + ledger pointer; the five lenses, §4 verdict, and the Gate-A definition stay verbatim as the audit record they are. The dangling architecture.md §11 cite now points at the ledger.
  • docs/glossary.md (70 -> 72 lines). Absorbs the vocabulary law (qualify driver-worker loop by timescale; benchmark = adapter; selector picks, never the judge) so the §12 deletion is lossless.

Every deleted number was verified present in .evolve/current.json or the memory ledger before deletion; the one missing cluster (the FinSearchComp SOTA breakdown) was appended to the ledger first. concepts.md, execution-model.md, and canonical-api §1/§1.5 are untouched per the evaluation verdicts.

Note for external readers: architecture.md §11/§12 deep-links now resolve to the ledger pointer; the picture book keeps the §13 number.

Checks

  • pnpm run docs:check — green (freshness gate: version pins, 10 citations, prose symbols across the 3 curated docs)
  • pnpm run lint / pnpm run typecheck — green
  • grep -c '2026-' docs/architecture.md -> 0; cross-file grep for refs to deleted sections -> 0

…ve measured numbers to the ledger

architecture.md 888 -> 668 lines: the session-narrative section and the
executed consolidation checklist are gone (§11/§12 folded into the ledger
pointer), Gate-A/Gate-B definitions are pointers to their canonical homes
(interpretations §5 / learning-flywheel.md), §13/§14 merge into one picture
book with a single tree drawing, and the command-hierarchy section now
states its built status (ask_parent/answer_question at coordination.ts:159-160)
with corrected anchors (types.ts:49, runtime.ts:1517). The vocabulary law
moves to glossary.md; every measured number lives in .evolve/current.json +
the memory ledger, with the domain-boundary and honesty laws kept verbatim.

@tangletools tangletools left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ Auto-approved drewstone PR — f36b57bf

This PR was opened by the trusted drewstone account.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

tangletools · auto-approval · reason: drewstone_author · 2026-07-02T22:21:12Z

@drewstone drewstone merged commit bd0b891 into main Jul 2, 2026
1 check passed
@drewstone drewstone deleted the docs/architecture-told-once branch July 3, 2026 02:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants