feat: proof-carrying reuse cache — forge reuse + metrics + substrate stage (substrate-v2 P3)

[CodeWithJuber]

What & why

Phase P3 of the substrate-v2 plan (#24; P1 = #25/#26, P2 = #27): "reuse already-generated code" becomes a deterministic system, the largest single lever toward the ~90 % cost target. Spec: docs/plans/substrate-v2/03-reuse-cache.md.

• src/reuse.js — verified code becomes an artifact claim keyed by a normalized task fingerprint: volatile literals become typed placeholders (listUsers → ⟨ident⟩, 25 → ⟨num⟩, paths → ⟨path⟩, quoted strings → ⟨str⟩) so the same task worded by different teammates lands in one near-neighborhood. Near-match via MinHash + 16×8 LSH banding (collision probability ≈ 0.96 at J=0.8 vs ≈ 0.17 at J=0.5 — a sharp cliff exactly at the near threshold, so big ledgers skip the all-pairs scan).
• The lookup ladder — exact (same normalized spec + same graph-slice context) → near (J ≥ 0.8, serve-with-diff) → adapt (J ≥ 0.6, inject as a verified starting point, generate only the delta) → miss.
• Proof-carrying serving — an artifact serves only when (1) its confidence has been earned past the 0.6 floor (a fresh unverified mint sits at the 0.5 prior and does not serve), and (2) every declared dependency still resolves in the atlas. A failed revalidation appends a graph.reval contradiction to the shared ledger — stale code demotes itself, for everyone, automatically. Serving appends a confirmation, keeping proofs fresh.
• forge reuse query | mint | stats — mint extracts a verifiable pointer (path + content sha256), exports, and relative-import deps from the file; it's honest when unverified ("serving: NOT YET — no evidence").
• forge substrate reuse stage — the explicit gate runs the metered query (evidence + metrics); the ambient hook path uses a read-only peek, so per-prompt hooks never write. A hit renders as: "reuse: EXACT hit — verified module at src/limit.js — start from it, don't regenerate."
• src/metrics.js — the stage-tagged .forge/metrics.jsonl (cost-model spec 05): every cache lookup logs hit_exact|hit_near|hit_adapt|miss + a saved-tokens estimate, so P8's savings report is arithmetic on measured events, never an assertion.
• reuse-first skill — now instructs agents to ask the cache first (guard-over-prose: the prose layer sits on a deterministic lookup).

Honest limit (stated in the spec and kept): MinHash near-match is weak on very short specs (< ~15 tokens — one changed word swings the Jaccard below threshold); realistic-length specs near-hit reliably (tested at J≈0.83/0.64 for the near/adapt tiers). The optional embeddings backend (ADR-0005) is the planned lift.

Checklist

• npm test passes (288/288 — 14 new: normalization placeholders, fingerprint slice-sensitivity, LSH determinism, all four ladder tiers, the proof floor, revalidation demotion, mint→hit→demote store roundtrip, metrics)
• npm run check passes on changed files
• New public functions have a test
• Conventional commit message (feat:)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency
• Substrate/docs updated — implements 03-reuse-cache.md §1–§4

Risk & rollback

• Risk level: low — new modules; the only existing-path touch is the substrate reuse stage, which is wrapped in try/catch (cache trouble can never block the gate) and read-only on hook paths
• Rollback plan: revert the commit; artifact claims and metrics files are inert data

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries (CLI usage errors; mint refuses secret-bearing specs via the ledger)
• Logs contain no secrets/PII
• If AI-assisted: I understand it, verified the package APIs, and it has tests

🤖 Generated with Claude Code

https://claude.ai/code/session_01Fc2MvWJbQ1cyNQ76ymv4hs

---

Generated by Claude Code