feat(memory): make the ledger the default store — finish the M2 migration

[CodeWithJuber]

What & why

Completes M2 — the last open finding from the deep review. The PCM ledger becomes the
default and only memory store; the legacy file stores are retired.

FORGE_LEDGER_ONLY now defaults on. .forge/lessons/*.md and recall/brain fact files are
no longer written, and every read (cortex injection/summary, routing, recall/brain, the
pre-edit advisory, doctor) materializes from the ledger. The ledger has been the convergent
dual-write store since P1, so existing memory is already present; forge ledger import
back-fills any pre-ledger history. FORGE_LEDGER_ONLY=0 is a one-release escape hatch that
restores the legacy file store.

The real work: closing the ledger-only gaps

Piloting this flip earlier surfaced real gaps (which is why the earlier PR shipped only the
safe reconcileFacts fix). This PR fixes them:

• brain.remember (and the forge_remember MCP tool) now shadow the fact into the repo
  ledger — previously the fact was simply lost when no file was written.
• cortex_features.featuresForEdit and cortex_hook_main's distill lesson lookup
  now read the merged ledger view instead of the empty legacy file store.
• cortex.js's injection / summary / distillation read paths were already ledger-aware; no
  change needed there. reconcileFacts was already guarded (shipped in the prior PR).

Tests

• The legacy-store suites are pinned to the FORGE_LEDGER_ONLY=0 escape hatch — they
  legitimately exercise the file path, which still works.
• ledger_only.test.js gains a default-mode end-to-end test of the full
  create → confirm → promote learning loop through the ledger, plus explicit
  default-vs-escape-hatch assertions and a no-data-loss reconcile test.

Scope note

The escape hatch is deliberately retained this release, so the legacy write code stays
(it backs the hatch). Deleting the legacy store code entirely is a follow-up for the
release after the escape hatch is removed.

Checklist

• npm test passes (1072 pass / 0 fail / 2 gated skips)
• npm run check passes (Biome — 0 errors)
• New default-mode behavior has an end-to-end test
• Conventional commit message
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency
• Docs updated (docs/GUIDE.md — the new default + escape hatch)

Risk & rollback

• Risk level: medium — changes the default memory persistence. Mitigated by: dual-write
  means no data is orphaned, the destructive reconcile is already guarded, all read paths
  are ledger-aware, and FORGE_LEDGER_ONLY=0 instantly restores prior behavior.
• Rollback plan: revert the commit, or set FORGE_LEDGER_ONLY=0.

Extra checks

• npm run typecheck passes
• node src/cli.js docs check green
• Live smoke: forge remember writes no legacy file and persists to the ledger

🤖 Generated with Claude Code

https://claude.ai/code/session_01C7htTiesXKLvAUtv6ET2jz

---

Generated by Claude Code