Context
Echo carries ~309 markdown docs. The authoritative surfaces (docs/spec/,
docs/quickstart-local-contract-host.md, ARCHITECTURE.md) are excellent but
swim in a much larger sea of historical design packets, and external
consumers can't tell which layer they're reading. Two concrete failure modes
observed while building Graft's Echo integration witness:
Idea
- Classify every doc into three tiers: authoritative contract (spec/,
quickstart, ARCHITECTURE), living direction (BEARING, NORTHSTAR, METHOD),
and historical design packets (the long tail).
- The Tome: one narrative, source-cited reference in the style of
Wesley's docs/END_TO_END.md + docs/TECHNICAL_TEARDOWN.md — domain
dictionary, golden paths, payload anatomy, authority boundaries — built
from tier-1 docs and live source.
- Archive historical packets under
docs/design/archive/ with an index
manifest mapping each to its landing PR/commit, excluded from the
"current truth" reading path.
- Citation lint: authoritative docs cite source as
[<filepath>#<line>@<git sha>]; CI (docs-truth style, as Wesley already
does) flags dangling paths so drift like the EINT v2 gap fails loudly
instead of silently.
First step
Generate an inventory (path, title, status marker, last-touched commit) and
propose the tier split as a reviewable PR — no deletions, moves only.
Filed from the Graft integration lane under the standing cool-ideas grant.
Context
Echo carries ~309 markdown docs. The authoritative surfaces (
docs/spec/,docs/quickstart-local-contract-host.md,ARCHITECTURE.md) are excellent butswim in a much larger sea of historical design packets, and external
consumers can't tell which layer they're reading. Two concrete failure modes
observed while building Graft's Echo integration witness:
and never mentioned the session-proto EINT v2 (fixed in Worktree-safe verify-local stamps; SPEC-0009 EINT v1/v2 layer clarification #534) — doc drift
that only source-validation caught.
distinguish "contract you can build against" from "design history."
Idea
quickstart, ARCHITECTURE), living direction (BEARING, NORTHSTAR, METHOD),
and historical design packets (the long tail).
Wesley's
docs/END_TO_END.md+docs/TECHNICAL_TEARDOWN.md— domaindictionary, golden paths, payload anatomy, authority boundaries — built
from tier-1 docs and live source.
docs/design/archive/with an indexmanifest mapping each to its landing PR/commit, excluded from the
"current truth" reading path.
[<filepath>#<line>@<git sha>]; CI (docs-truth style, as Wesley alreadydoes) flags dangling paths so drift like the EINT v2 gap fails loudly
instead of silently.
First step
Generate an inventory (path, title, status marker, last-touched commit) and
propose the tier split as a reviewable PR — no deletions, moves only.
Filed from the Graft integration lane under the standing cool-ideas grant.