feat(impact-certificate): certify a change's cross-boundary reach before it lands (spec-store arc, change 3)

[clay-good]

Third and final change of the spec-store integration arc (openspec/changes/SPEC-STORE-INTEGRATION.md), stacked on #180 (change 2). Adds the change-impact certificate: for the current diff, OpenLore emits ONE deterministic, conclusion-shaped certificate of what the change touches — before it lands.

Stacked on #180. Review after #180 merges (GitHub will retarget this to main automatically). The change-3-only diff is the two commits on this branch.

What it does

change_impact_certificate (MCP tool) + openlore impact-certificate (CLI) compose, for a proposed change:

• Blast radius / tests / drift — reused verbatim from blast_radius.
• Newly-opened paths into each declared covering surface (a semantic/governance boundary you declare, not a directory glob) — the paths the change makes newly reachable, computed differentially (reachable after but not before). This is the cross-boundary signal file-ownership can't see.
• Decay — the certificate is anchored to the touched symbols via the existing freshness lease, persisted under .openlore/impact-certificates/, and the spec-store health check re-fires a stale one as a certificate-stale finding. An expired certificate is never presented as silently still-true.

Advisory by default (never blocks); opt-in blocking only on a configured surface severity (e.g. impactCertificate.block: ["critical"]). No LLM — north star c6d1ad07 holds.

The differential, without the unbuilt incremental graph

The proposal specified deriving the post-change graph via add-watch-incremental-dependency-graph, which is still a DRAFT/unbuilt. A new call edge can only originate from a changed file, so this re-parses only the changed files at base vs working tree (the same bounded primitive structural_diff uses), resolves the added/removed callee names to canonical ids by unique-name match, and adjusts the canonical adjacency both ways:

post = canonical + addedEdges − removedEdges
pre  = canonical − addedEdges + removedEdges

A node that reaches a surface in post but not pre is newly able to — and the opening is attributed to the exact added edge, with its shortest path named. No full rebuild, no dependency on the unbuilt graph. Ambiguous added callees are reported (unresolved-added-call), never guessed. Recorded as decision 187224b0.

Verification

• Unit: impact-certificate.test.ts — 17 tests: surface resolution (file+symbol, unresolved→finding, ambiguous→no-guess), both differential scenarios (opens a 2-hop path / touches only existing callers → none) + direct + already-reachable + empty, the block gate, conclusion-shape + contract classification, and decay fresh→stale against a real on-disk edge store + the spec-store health-check re-fire.
• e2e dogfood on this repo (6,286 functions) — caught a controlled critical newly-opened path dogfoodNewlyOpensSurface → validateSpecStoreConfig, blocked the hook at exit 1 under block: ["critical"] and stayed advisory (exit 0) without it, persisted 31 lease anchors, and turned a certificate stale on an anchored-symbol edit. See openspec/changes/DOGFOOD-change-impact-certificate.md.
• Full CI-equivalent suite: vitest run src examples (integration excluded) — 4,376 passed / 2 skipped.

Surface registration

New tool joins the opt-in federation preset only (out of minimal/navigation/memory). Tool count 62→63; tools/list budget, doc size/count figures, presets/contract/tool-driver guards all updated consciously.

Adversarial hardening (round 2)

Two independent reviewers + real-input e2e probes found and fixed two correctness bugs in the changed-file plumbing (both from computeEdgeDelta diverging from the sibling structural_diff) plus one no-throw gap:

• Rename false positive (HIGH): the diff dropped oldPath, so a renamed file's pre-existing calls all looked added — a pure git mv falsely reported a newly-opened critical path and would have wrongly blocked the commit under block: ["critical"]. Fixed: read old content from oldPath ?? path.
• Untracked false negative (MEDIUM): git diff excludes untracked files, so a brand-new file opening a critical surface was certified as "no new reach." Fixed: fold in git ls-files --others --exclude-standard (as structural_diff does).
• No-throw gap (MEDIUM): the decay re-check could throw out of the contractually no-throw handleSpecStoreStatus. Fixed: catch at the source + a boundary at the call site; an unverifiable certificate is conservatively stale.

All three reproduced with real inputs, fixed, and pinned by 4 new regression tests against a real temp git repo + the real CallGraphBuilder (17 → 21 tests). See the Round 2 section of DOGFOOD-change-impact-certificate.md.

Adversarial hardening (round 3 — second pass)

A second adversarial round (two fresh reviewers + new real-input probes) found two more correctness bugs, a file-hygiene defect, and doc/test gaps. All fixed and regression-tested.

• Homonym phantom opening (HIGH): resolving an added call's callee by name against the canonical graph mis-bound a LOCAL helper sharing a covering-surface symbol's name to the canonical surface — a phantom newly-opened path that falsely tripped the critical block-gate (reproduced e2e). Fixed: key changed-file calls by their snapshot-internal resolved id and only name-resolve callees external to the snapshot, honoring the local binding.
• Same-diff surface member missed (MEDIUM): a surface symbol added in the same diff was unresolvable (canonical-only), silently downgrading a critical opening to a warn. Fixed: resolve surfaces over canonical ∪ post-change nodes.
• Three stray NUL bytes (accidental key separators) made the handler read as binary and hid it from grep; replaced with the equivalent escape.
• Docs: the tool/command previously appeared only in CLAUDE.md; now fully documented in docs/mcp-tools.md (table + prose + parameters + finding codes), docs/cli-reference.md, README.md, and docs/federation.md.
• Tests: added a CLI test file (hook install/uninstall + advisory/blocking exit codes), a dispatchTool MCP-path reachability test, and homonym + same-diff regression tests against a real temp git repo. Full suite: 4,399 passed / 2 skipped.

Adversarial hardening (round 4 - third pass)

A third adversarial pass (scale/determinism/correctness reviewer + new real-input probes) found two more HIGH correctness bugs and several integrity gaps. All fixed + regression-tested.

• Base-ref divergence (HIGH): getChangedFiles diffs against the merge-base (three-dot) but the differential read old content from the base-ref tip - so when the base branch advanced, the certificate's two halves diffed against different commits (phantom/missed openings). Fixed: read old content from git merge-base(base, HEAD); pinned in a real temp git repo.
• Wrong-typed surface severity (HIGH): an out-of-enum severity made highestSurfaceSeverity come out null (NaN rank index), breaking the block-signal contract. Fixed: coerce to warn in surfacesFromConfig (reproduced e2e: was null, now warn).
• Duplicate/empty surface names dropped; a member with both symbol+file resolves both; total-order path sort (deterministic top-N); per-surface truncation now reports the true count + a caveat (no silent truncation); large-diff caveat; and a new/untracked file now gets a file-level lease anchor so the certificate actually decays for it.
• Docs: docs/configuration.md now documents the impactCertificate config (surfaces, members, severity, block) - the last doc surface that lacked it.
• Suite: 4,405 passed / 2 skipped (merge-base, severity coercion, dedup, both-member, file-anchor-decay regressions added).

Round 5 - doc accuracy + MCP-server integration (4th pass)

A fourth pass (spec/doc-accuracy + integration-coverage reviewer + a real large-diff perf probe) found no new runtime bugs - the differential, decay, config hardening, and finding codes were all confirmed accurate - and fixed documentation + integration-coverage gaps:

• Doc accuracy: five normative spec/proposal bodies still asserted the un-shipped "incremental dependency graph" mechanism (contradicting the shipped differential edge-delta and their own notes). Reworded all five (canonical mcp-handlers requirement, the change-delta spec, proposal items, tasks.md) to be mechanism-neutral; extended the lease note to record the new-file file-level anchor.
• Integration coverage: the spec-12 conformance test ran the live MCP stdio server but its ListTools check was one-directional. Made it bidirectional (every defined tool is advertised) + a positive assert that change_impact_certificate is advertised — 7/7 conformance tests pass, confirming the tool is reachable end-to-end through the real MCP server (not just unit dispatch). Protects all tools.
• Perf probe (real input): a 300-file diff completes in ~8.8s, 300/300 openings detected, no hang — validating the round-4 >200-file caveat (capping is correctly avoided; it would miss openings).
• Finding codes / CLI flags confirmed accurate; added the --uninstall-hook doc example.

🤖 Generated with Claude Code