Status

DEFERRED — see Revisit Conditions below. Tracked for visibility, not actively scheduled.

Problem (when revisited)

Hand-written mocks in tests diverge silently from real module implementations. A factory that imports the real module, asserts each export's shape, then substitutes behavior would fail-fast at test setup when the real module's contract changes incompatibly.

Proposed solution (when revisited)

Replace inline vi.mock("../../agents/agent-scope.js", () => ({...})) with:

import { mockAgentScope } from "../../../test/mock-factories/agent-scope.js";
mockAgentScope({ runtime: "claude" });

Internally the factory imports the real module, asserts each export's shape (e.g., assertCallable(mod.resolveAgentRuntimeOrThrow, { returns: "string" })), then substitutes. When the real module's contract changes (e.g., resolveAgentRuntimeOrThrow becomes : never), the assertion fails at test setup time → all dependent tests fail → CI red.

Why deferred

• Migration cost — 5+ test files for agent-scope alone, growing per fork-boundary module
• Benefit largely subsumed by the attestation manifest (other child issue of meta(fork-sync): hardening architecture epic — prevent #2408-class regressions #2433) at lower cost
• "Shape assertion" is a second source of truth competing with TypeScript types — risks brittleness
• Requires the mock-allowlist (other deferred child issue) to enforce factory usage on new tests

Revisit when

• (a) Attestation manifest (other child issue of meta(fork-sync): hardening architecture epic — prevent #2408-class regressions #2433) experiences meaningful drift, demonstrating that declarative-only is insufficient, OR
• (b) a future regression escapes the Phase 1-2 gates specifically because of a mock shape mismatch (not a stub regression)

Effort (estimated when revisited)

3-5 days first module + factory; ongoing per-module (~1 day each).

Dependencies

Tracked under: #2433
Companion: mock-allowlist (other deferred child issue of #2433) — would be required to enforce factory usage

References

• Epic: meta(fork-sync): hardening architecture epic — prevent #2408-class regressions #2433
• /evaluate analysis: full deep-dive in evaluation report (2026-04-19 conversation)