feat: context assembly + completeness gate — forge context (substrate-v2 P4)

[CodeWithJuber]

What & why

Phase P4 of the substrate-v2 plan (#24; P1 = #25/#26, P2 = #27, P3 = #28): the "incomplete context" fix — what enters the window becomes a budgeted optimization, and whether the context is sufficient becomes a computed set, not a feeling. Spec: docs/plans/substrate-v2/04-context-assembly.md.

• The required-knowledge set R(edit) is derived (src/context.js): the target's definitions, its hop-1 dependents from the atlas (the callers you'd otherwise break blind), sibling tests, and team lessons trusted past val ≥ 0.8 — a lesson the ledger already paid for is required reading, not a nice-to-have.
• Selection with a compression ladder — required coverage is pinned; when the budget squeezes, items downgrade granularity (full text → first-25-lines → one-line pointer) instead of silently dropping coverage. Compression is a lossy move with a known cost, chosen explicitly — never by scroll-off. Items resolving to the same file span merge (one span, union of covered keys). Optional items (trusted facts) fill remaining budget greedily with per-source diminishing returns.
• The completeness gate — missing = R \ covered. Unresolvable entries become derived clarifying questions: "The task names \applyDiscountMatrix` but the repo doesn't define it — which file implements it (or is it new)?"` This upgrades M2: questions computed from a set difference instead of pattern-matched from lexical cues.
• forge substrate surfaces the assembly (context: COMPLETE — 3 required item(s), 69/6000 tokens) and its questions; under FORGE_ENFORCE=1 an unassemblable context blocks the edit — acting on missing context is acting on a guess (the paper's 17:36 rule at the context layer).
• forge context "<task>" [--budget N] [--json] — prints the selection (item, granularity, tokens), the required/covered/missing sets, and exits 1 on incomplete (CI-friendly).
• Deterministic end to end: same repo + same task → byte-identical assembly (tested).

Checklist

• npm test passes (295/295 — 7 new: derived R(edit) incl. the trust floor boundary, complete assembly, budget-squeeze downgrade preserving coverage, derived questions + enforced block, determinism)
• npm run check passes on changed files
• New public functions have a test (requiredSet, assemble, renderContext, tokensOf)
• Conventional commit message (feat:)
• CHANGELOG.md updated under ## [Unreleased]
• No new runtime dependency
• Substrate/docs updated — implements 04-context-assembly.md §1–§4 (candidates, knapsack + ladder, set-cover gate, substrate wiring)

Risk & rollback

• Risk level: low — new module; substrate integration is explicit-gate-only (never the per-prompt hook path), wrapped in try/catch, and the new enforce branch fires only under FORGE_ENFORCE=1 with derived questions present
• Rollback plan: revert the commit

Extra checks (tick if applicable)

• npm run typecheck passes
• Input validated at boundaries (CLI usage error on empty task; unreadable files degrade to null items, never throw)
• 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