Problem

RemoteClaw has experienced a recurring class of fork-sync regression where:

1. Upstream sync re-introduces a previously-gutted file as a stub (unconditional throw, no-op return, or constant-false handler)
2. Production callers exist
3. All call-site tests mock the function, returning what the non-stub version would return
4. CI passes (mocks "work")
5. Production crashes user-visibly on every dispatch

Documented instances:

• fix(agents): restore resolveAgentRuntimeOrThrow body — regression stub crashed every agent dispatch #2408 — resolveAgentRuntimeOrThrow unconditional throw → every Slack auto-reply, /agent CLI, cron isolated agent crashes
• gut: re-apply provider/model cascade after v2026.3.7 sync regression (~19 files) #2337 instance 1 — modelSupportsVision returning false → Telegram vision silently disabled
• gut: re-apply provider/model cascade after v2026.3.7 sync regression (~19 files) #2337 instance 2 — skillsHandlers returning empty map → node-host skills silently broken
• gut: re-apply provider/model cascade after v2026.3.7 sync regression (~19 files) #2337 instance 3 — modelsHandlers returning empty map → TUI listModels fails

Three sync events (#2298, #2360) shipped this class. Manual review and acceptance-criteria unit tests have not been sufficient at fork-sync scale (sync PRs touch 700-2,500 commits).

Architecture decision

Per /suggest + /evaluate analysis on 2026-04-19:

• The actual lever is mock/real divergence detection, not "more tests"
• The strongest interventions are CI gates / lint rules / declarative attestation, not new test files
• Sequenced rollout in 3 phases over ~8 weeks

Phase 0 — Foundational

• ci(fork-sync): strip dangling ADR path references (ADR stays HQ-internal) #2434 — docs(adr): author ADR 0005 — fork-sync hardening architecture

Phase 1 — NOW (within 2 weeks of #2408 fix)

• ci(fork-sync): extend check-throwing-stub-callers.mjs with : never calibration signal (H7) #2435 — ci(fork-sync): AST gate — fail on throwing-stub exports with live callers (Option 1) — 1-2 days, would have caught fix(agents): restore resolveAgentRuntimeOrThrow body — regression stub crashed every agent dispatch #2408
• ci(fork-sync): fork-boundary mock baseline in check-stub-debt.mjs (H8) #2436 — ci(fork-sync): generalize check-stub-debt.mjs with 3 new counters (Option 5) — 1-2 days

Phase 2 — within 6 weeks

• ci(fork-sync): MODULE_ATTESTATIONS manifest for src/agents/* (Option 6) #2437 — ci(fork-sync): MODULE_ATTESTATIONS manifest for src/agents/* (Option 6) — 3-5 days, semantic-stub coverage

Phase 3 — within 8 weeks

• ci(fork-sync): sync-PR composite gate workflow (Option 7) #2441 — ci(fork-sync): sync-PR composite gate workflow (Option 7) — 0.5 day, depends on ci(fork-sync): extend check-throwing-stub-callers.mjs with : never calibration signal (H7) #2435, ci(fork-sync): fork-boundary mock baseline in check-stub-debt.mjs (H8) #2436, ci(fork-sync): MODULE_ATTESTATIONS manifest for src/agents/* (Option 6) #2437

Deferred (with revisit triggers in child issues)

• test(fork-sync): mock ablation suite for fork-boundary modules (Option 2 — DEFERRED) #2438 — test(fork-sync): mock ablation suite (Option 2 — DEFERRED)
• test(fork-sync): reflective mock factory for fork-boundary modules (Option 3 — DEFERRED) #2439 — test(fork-sync): reflective mock factory (Option 3 — DEFERRED)
• ci(fork-sync): mock-allowlist for fork-boundary vi.mock calls (Option 4 — DEFERRED) #2440 — ci(fork-sync): mock-allowlist (Option 4 — DEFERRED)

Success criteria

• No new instances of the class ship in 2026
• AST gate (ci(fork-sync): extend check-throwing-stub-callers.mjs with : never calibration signal (H7) #2435) would have caught fix(agents): restore resolveAgentRuntimeOrThrow body — regression stub crashed every agent dispatch #2408 at PR time (verified via dry-run on the introducing commit fc2cefeeab)
• All Phase 0-3 issues closed within 8 weeks of fix(agents): restore resolveAgentRuntimeOrThrow body — regression stub crashed every agent dispatch #2408 fix landing

Dependency graph

#2434 (ADR) ─┬─> #2435 (AST gate) ─────┐
             ├─> #2436 (baselines) ────┼──> #2441 (composite gate)
             └─> #2437 (attestation) ──┘

Deferred items (#2438, #2439, #2440) are tracked under this epic but not on the active path.

References

• Trigger bug: fix(agents): restore resolveAgentRuntimeOrThrow body — regression stub crashed every agent dispatch #2408
• Sibling cascade: gut: re-apply provider/model cascade after v2026.3.7 sync regression (~19 files) #2337
• Audit class: Audit: upstream fixes silently lost in sync (v2026.2.25 → v2026.3.22, 32 gaps) #2406 (different failure mode)
• Existing infrastructure: chore(ci): add stub debt gate (ADR 0005 H5) #2353 (introduced check-stub-debt.mjs), chore(ci): drive stub debt baseline to zero and remove it #2354 (drives baseline to zero)