docs: Substrate v2 plan — complete the whitepaper via the Proof-Carrying Memory protocol

[CodeWithJuber]

What & why

ForgeKit v0.4 implements roughly half of the committed cognitive-substrate whitepaper. This PR adds the complete implementation plan for the rest — nine specs under docs/plans/substrate-v2/ + two ADRs — closing every remaining paper gap (validity-anchored memory, outcome-validated learning, imagination, doom-loop diagnosis, M3–M6) and the project-owner pains the paper only gestures at: ~90 % cost target, reuse of already-generated code, team/shared memory, incomplete context, and generic AI-template UI.

One idea unifies it: the Proof-Carrying Memory (PCM) protocol (01-pcm-protocol.md, ADR-0006). Every stored unit — lesson, fact, cached artifact, graph edge, design fingerprint, diagnosis — is a content-addressed claim carrying provenance and evidence; confidence is a decayed Beta posterior moved only by independent oracles (tests, typecheck, CI, human accept/revert — never the model's self-assessment, per paper C12); retrieval implements the paper's Eq. 3 (α·rel + β·rec + γ·val). On top of it:

• Team memory (02): git-native CRDT ledger — set-union semilattice merge, so teammates' memories converge with zero conflicts and no server.
• Reuse cache (03): verified code served with its proof (MinHash/LSH near-match, atlas revalidation, outcome-driven demotion) — one teammate's verified work is everyone's cache hit.
• Context assembly (04): token-budget knapsack selection + a set-cover completeness gate that computes the missing-knowledge set instead of letting the agent assume (upgrades M2's questions from pattern-matched to derived).
• Cost model (05): the honest composition toward ~90 % — routing's measured 62 % × cache × context × gate — with the P8 harness that replaces targets with measurements.
• Faculties & mechanisms (06): AST-tier atlas + mandatory impact gate, imagination dry-run (impacted-test set cover + worktree sandbox), external-oracle cascade, M3 partition planning, M4 CUSUM drift control, M5 footprint/MDL metric, M6 optimal-stopping checkpoint cadence, outcome-calibrated routing.
• UI quality gate (07): anti-template system — deterministic design-fingerprint extraction (OKLCH palette, spacing/type scale recovery), slop-distance vs. project-conformance scoring, uicheck v2 constraint checks, machine-readable taste profiles.
• forge dash (08): local zero-infra dashboard over the ledger, cost stages, cache, and blast radius.

ADR-0005 relaxes the zero-dep rule to selective optional deps with stdlib fallbacks (supersedes ADR-0001's blanket rule, per owner decision); ROADMAP.md now carries the dependency-ordered P1–P8 phases with acceptance gates; CHANGELOG updated.

Docs only — no runtime behavior changes.

Checklist

• npm test passes (222/222 locally)
• npm run check — no JS/JSON touched (docs only)
• New public functions have a test — n/a (no code)
• Conventional commit message (docs:)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency (ADR-0005 plans selective optional deps; this PR adds none)
• Substrate/docs updated — this PR is the substrate docs update

Risk & rollback

• Risk level: low (documentation only)
• Rollback plan: revert the single commit; no state or behavior to unwind

Extra checks (tick if applicable)

• npm run typecheck — unaffected (no source changes)
• Logs contain no secrets/PII
• If AI-assisted: content cross-checked against the whitepaper's evidence appendix (C-grades preserved; measured vs. target figures kept distinct)

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fc2MvWJbQ1cyNQ76ymv4hs

---

Generated by Claude Code