feat(substrate): whitepaper-fidelity gaps — M5 footprint, doom-loop, failing-test prediction (Tranche B)

[CodeWithJuber]

What & why

Tranche B of the review. Turns three mechanisms the paper specifies but the product barely
built into real, tested features — each grounded in inputs that already exist.

M5 — anti-over-engineering, measured (src/lean.js, forge lean)

The paper flags φ(y) − φ*(x) > 0 — the solution's footprint beyond the task's minimal
sufficient footprint. The old minimalityWarnings was three keyword regexes. Now lean reads the
working diff and measures the real footprint:

• new abstractions the task never named (new functions/classes/types on added lines vs. what
  referencedEntities found in the task),
• a large diff for a short ask,
• files touched beyond the stated scope.

Folded into forge substrate as minimality.footprint, and available standalone: forge lean "<task>".

Doom-loop breaker (self-correction)

The existing shell guard catches the same action repeated. This catches the subtler loop the
paper names — different edits that keep producing the same test failure. cortex_hook now
captures a normalized signature of failing-test output (line numbers, timings, addresses, temp
paths factored out), and detectDoomLoop fires when one signature recurs past a threshold. The
pre-edit hook surfaces a "stop and find the root cause" advisory (with the diagnosis), taking
precedence over lesson/risk notes.

Consequence simulation — failing-tests class (Eq 4)

forge substrate now predicts the tests likely to break before the edit
(impact.predictedTests): impacted files that are tests, plus each impacted source file's
sibling test (foo.js → foo.test.js, foo.py → test_foo.py, __tests__/, test(s)/).
Surfaced in the report and the ambient advisory so you run the narrowest affected tests first.

On the 4th item (recall val) — deliberately not done

I assessed routing recall.js through the val term and chose not to: recall facts are
user-authored pointers with no ground-truth outcome to validate against, so val correctly
lives in lessons.js (where it already ships). Forcing the metric where the data doesn't exist
would be dishonest — flagging the decision rather than shipping a hollow version.

Checklist

• npm test passes (Node 18/20/22) — 215 tests (+11)
• npm run check passes (Biome lint + format)
• New public functions have tests (lean, detectDoomLoop, predictFailingTests)
• Conventional commit message (feat:)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency
• Substrate/docs updated (new forge lean command + substrate fields)

Risk & rollback

• Risk level: low — all three are advisory (never block); the substrate additions are new
  fields; lean is diff-based and quiet with no diff.
• Rollback plan: revert the commit. No migrations.

Extra checks

• npm run typecheck passes
• Input validated at boundaries; errors handled (diff/parse are defensive)
• Logs contain no secrets/PII

Verification

Full suite + typecheck + Biome green. Manual: forge lean on a synthetic 4-class diff flags the
unrequested abstractions; doom-loop unit tests confirm normalization makes the same error match
across runs and that distinct/under-threshold failures stay quiet; predictFailingTests finds the
sibling test of an impacted source file.

Next: Tranche C (enforcement & stewardship — the mandatory gate).

🤖 Generated with Claude Code

https://claude.ai/code/session_01HGZUYFdUb4EViXV5tRid19

---

Generated by Claude Code