feat(substrate): opt-in, verified LLM adjudication across the cognitive substrate

[CodeWithJuber]

What & why

The substrate's "logic algorithm" (the M1–M6 mechanisms + faculties in the white paper) was implemented almost entirely with static regex term-lists, keyword/stop sets, and hand-tuned weights — the module headers themselves flag these as temporary "SEAMS." This PR moves those lexical judgments beyond regex with a thin, opt-in LLM layer that is never trusted blindly, honoring the paper's load-bearing principle (Panickssery et al. C12; tabayyun, 49:6): the model may propose, but an external check arbitrates — an LLM is never its own judge.

One shared fail-safe primitive — src/adjudicate.js (a claude -p proposer with an injectable runner and secret refusal) — is wired thinly into every faculty. Each faculty keeps its deterministic rubric as the judge and adds a small *LLM proposer + a reconcile step:

• M2 assumption gate (preflight.js) — LLM completeness/questions, bounded ±band by the rubric (can't flip a clearly-specified/vague task); the gate only ever tightens; extra questions must be grounded in a flagged dimension or a real repo entity.
• M1 routing (route.js) — LLM complexity band is raise-only (max with the rubric), so it never under-provisions on the model's word; escalation still gates on a verified failure.
• Impact / code graph (atlas.js) — LLM proposes the coupled edges the regex misses (dynamic dispatch, DI, reflection); a candidate is kept only if the file is real AND a grep confirms the reference, tagged source:"llm-verified".
• M4 goal-drift (anchor.js) — rescues an off-goal file off→on only, and only with a goal-referencing reason (preserves the "errs toward on-goal" invariant).
• Memory val term (lessons.js) — retrieval is now the paper's relevance × freshness × validity × scope; validity() is a ground-truth Beta posterior so outcome-confirmed lessons rank above merely-recent ones.
• Orchestrator (substrate.js) — threads an llm option, exposes per-faculty llm.provenance (deterministic / llm-verified / llm-agreed) in --json, and adds a guarantees.llmVerified bucket.

Off by default (FORGE_LLM=1 to enable; FORGE_LLM_AMBIENT=1 for the Claude Code hook, which stays deterministic otherwise). Behaviour is byte-identical with the flag off, any failure falls back to the deterministic path, and it never blocks. Zero new runtime dependency — access is a CLI shell-out. The Cortex distiller now shares the same primitive.

Checklist

• npm test passes (Node 18/20/22) — 180 tests pass (151 baseline + 29 new)
• npm run check passes (Biome lint + format) — clean on all changed files
• New public functions have a test
• Conventional commit message (feat:/fix:/docs: …)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency (dev deps ok)
• Substrate/docs updated if this changes forge substrate, forge impact, router/gate, or MCP substrate tools

Risk & rollback

• Risk level: low — the LLM layer is off by default and the deterministic path is unchanged when disabled; every proposal is externally verified and fail-safe.
• Rollback plan: revert the commit, or simply leave FORGE_LLM unset (feature is inert). No schema/data migrations.

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries; errors handled (no swallowing) — adjudicate catches all failures → null
• Logs contain no secrets/PII — prompt and reply are secret-refused via SECRET_RE
• If AI-assisted: I understand it, verified the package APIs, and it has tests

Verification

• forge substrate "make the auth better" (default) → deterministic, unchanged.
• FORGE_LLM=1 forge substrate "..." --json → model consulted; route returned a verified raise, other faculties fell back safely; the gate correctly stayed ASK FIRST.
• Unit tests exercise every LLM path with an injected stub runner: verified blend, garbage/secret → fallback, and reconcile rejecting ungrounded claims (hallucinated impact file, ungrounded drift rescue, on→off flip).

🤖 Generated with Claude Code

https://claude.ai/code/session_01HGZUYFdUb4EViXV5tRid19

---

Generated by Claude Code