feat(substrate): bidirectional verified reconcile + docs/YAML polish

[CodeWithJuber]

What & why

Two follow-ups to the merged LLM-adjudication layer (#14).

Part A — the verified reconcile becomes bidirectional. Today the layer is one-directional: the M2 gate can only tighten (add an ask) and M1 routing can only raise a tier. In a live run that flipped a clearly-specified task to "ASK FIRST." Now a verified reading can also reduce caution — default-on when FORGE_LLM=1, with hard safety rails (llm.bidirectional: false in source/substrate.json reverts to the conservative mode). Still "never blind": the model proposes, external checks gate every move.

• M2 gate (preflight.js) — can clear a false ask (llm-cleared), not only add one. Two floors the model can never override still force the ask: a task with no concrete anchor, or one naming symbols/files the repo doesn't define (repo-grounding, threaded from informationGap). Still bounded ±band, so a genuinely vague task can't be lifted over the line.
• M1 routing (route.js) — a raise is free (spotting hidden complexity costs at most a bigger model); a lower is bounded to one routingBand and never below signalFloor when the rubric detects algorithmic/architectural terms, so a "distributed rate-limiter" can't be talked down to the cheap tier.
• Orchestrator (substrate.js) — threads bidirectional + the band/floor config; surfaces llm.bidirectional and a richer per-faculty llm.provenance (llm-cleared / llm-tightened / llm-raised / llm-lowered).

Part B — docs & YAML polish (signature voice preserved):

• Fixed stale source paths in ARCHITECTURE.md (source/AGENTS.md + source/rules/ → the real source/rules.json, substrate.json, mcp.json) in both the diagram and the repo tree.
• Added archived-pre-Forge banners to every docs/legacy/*.md (the project's own daily report had asked for exactly this), pointing to the current docs and flagging historical action items as superseded — no secrets touched.
• Documented the bidirectional reconcile + the llm.bidirectional knob in the substrate README (with a propose→verify→reconcile mermaid diagram), GUIDE, and CHANGELOG.
• Added purpose comments to the YAML files that lacked one (FUNDING.yml, ci.yml).
• Verified all 67 markdown files are relative-link clean.

Checklist

• npm test passes (Node 18/20/22) — 192 tests (was 180; +12 for the new matrix)
• npm run check passes (Biome lint + format)
• New public functions have a test
• Conventional commit message (feat:)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency (dev deps ok)
• Substrate/docs updated (router/gate behaviour changed)

Risk & rollback

• Risk level: low — bidirectional is bounded + rail-guarded and only active with FORGE_LLM=1; behaviour is byte-identical with the flag off. Every move is externally verified and fail-safe.
• Rollback plan: set llm.bidirectional: false (conservative mode), leave FORGE_LLM unset (feature inert), or revert the commit. No migrations.

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries; errors handled (fail-safe → deterministic)
• Logs contain no secrets/PII — prompt + reply secret-refused; legacy secret TODOs left untouched, only banner-flagged
• If AI-assisted: I understand it, verified the APIs, and it has tests

Verification (end-to-end, real claude CLI)

• FORGE_LLM=1 forge route "add a small in-memory cache with get and set" → llm-lowered to Haiku with a reasoned tag (the rubric had bumped it to mid on the word "cache").
• Unit matrix covers: clear / never-clear (hard-underspecified, unresolved entity, genuinely vague), tighten, free-raise, bounded-lower, strong-signal floor holds, and bidirectional:false reverting to raise-/tighten-only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HGZUYFdUb4EViXV5tRid19

---

Generated by Claude Code