feat(ledger): retire the legacy stores under FORGE_LEDGER_ONLY

[CodeWithJuber]

What & why

Implements the ROADMAP "Next" item "Legacy store retirement". Since P1 the PCM ledger has been the convergent write store (dual-write via ledger_bridge) with a merged read (ledger_read, legacy ∪ ledger). The remaining step was to stop writing the legacy files so the ledger is the only store.

With FORGE_LEDGER_ONLY=1 (default off — every existing test is unchanged):

• lessons_store.save skips the .md write — the ledger already holds the lesson (recordLessonEvent shadows every save)
• cortex confirm/create/distill dedup against ledgerLessons (materialized from the ledger, same legacy ids via provenance.task), not the files
• ledger_read.mergedLessons returns the ledger view alone
• recall.add skips the fact file; recall.readFact now falls back to the ledger — which also fixes a real gap: a merged teammate fact with no local file was previously unreadable
• the CLI re-indexes MEMORY.md / AGENTS.brain.md after the shadow write so those projections stay current under ledger-only

Reads materialize from the existing ledger view (claimToLesson / ledgerFacts), so no new read path was invented. forge ledger import (already present) backfills legacy content so nothing local is stranded when you flip the switch.

• src/util.js — ledgerOnly() switch.
• src/lessons_store.js, src/cortex.js, src/ledger_read.js, src/recall.js, src/cli.js — write-skips + ledger-only reads.
• New test/ledger_only.test.js — exercises the on-path end to end.
• Docs — GUIDE ledger section + env table (FORGE_LEDGER_ONLY), CHANGELOG.md, ROADMAP.

Checklist

• npm test passes — 670 tests, 668 pass, 0 fail (2 pre-existing skips); 4 new cases
• npm run check passes (Biome) — exit 0
• New public functions have a test
• Conventional commit message (feat:)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency
• Substrate/docs updated — this changes the memory stores; GUIDE + ROADMAP + forge docs check reconciled

Risk & rollback

• Risk level: low–medium — the switch is opt-in and default off, so existing behavior (legacy files canonical) is byte-for-byte unchanged and covered by the full suite. The ledger-only path reuses the already-shipped materialization + dual-write.
• Rollback plan: unset FORGE_LEDGER_ONLY (instant revert to legacy-canonical); or revert the commit. No destructive migration — forge ledger import only adds content, idempotently.

Extra checks

• npm run typecheck passes
• Input validated at boundaries; errors handled — secret-refusal still runs before any mint; best-effort ledger writes never fail the command
• Logs contain no secrets/PII
• If AI-assisted: verified the ledger materialization + dual-write pairing that makes the write-skip safe; on-path is unit-tested

🤖 Generated with Claude Code

---

Generated by Claude Code