Problem

The AST gate and baseline counters (Phase 1 child issues of #2433) catch throwing-stub regressions and drift. Neither catches semantic stubs — functions whose return type stays valid (boolean, object) but whose implementation has been gutted to return constant values.

#2337 instance 1: modelSupportsVision returns false (always). Type is boolean, body has no throw, no : never. AST gate doesn't fire. Baselines don't fire. Telegram vision is silently disabled.

Solution

Each fork-boundary module exports a MODULE_ATTESTATIONS constant declaring each export's status:

// src/agents/agent-scope.ts
export const MODULE_ATTESTATIONS = {
  resolveAgentRuntime: "live",
  resolveAgentRuntimeOrThrow: "live",
  resolveAgentAuth: "live",
  // ...
} as const;

CI verifier (scripts/check-attestations.mjs):

1. Imports each fork-boundary module
2. Reads MODULE_ATTESTATIONS
3. Verifies (a) every export listed; (b) "live" exports don't match throwing-stub patterns; (c) "stub" exports have zero non-test importers
4. Sync PRs that change MODULE_ATTESTATIONS show diffs clearly in PR review
5. CODEOWNERS rule for files containing MODULE_ATTESTATIONS

Scope (initial rollout)

Limit to src/agents/* for first iteration to bound rollout cost. Expand to src/middleware/* and other fork-boundary directories in follow-up issues if pattern proves valuable.

Acceptance criteria

• MODULE_ATTESTATIONS convention documented in CONTRIBUTING.md
• Manifest added to all src/agents/*.ts files with exports
• scripts/check-attestations.mjs implemented and wired into CI
• CI fails on missing attestation for a new export
• CI fails on "live" attestation for a function matching throwing-stub patterns
• CI fails on "stub" attestation for a function with non-test importers
• CODEOWNERS rule added for src/agents/**/*.ts (or files containing MODULE_ATTESTATIONS)
• Dry-run: with PR chore: sync upstream v2026.3.7 to v2026.3.8 #2360's stub regression, MODULE_ATTESTATIONS would have flagged the live-vs-actual-stub mismatch

Effort

3-5 days

Open questions (needs-discussion)

• "live" / "stub" / "deprecated" — sufficient classification, or do we need "partial"?
• Where exactly should MODULE_ATTESTATIONS live in the file (top, bottom, separate sibling file)?
• CODEOWNERS scope — repo maintainers or sync-PR specialists?
• Should MODULE_ATTESTATIONS be tree-shakable (it is exported runtime data — small but non-zero bundle cost)?

Dependencies

Blocked by: #2434 (ADR 0005)
Recommended after: AST gate and baseline counters (other Phase 1 child issues of #2433) land first to validate lighter-weight gates
Tracked under: #2433

References

• Epic: meta(fork-sync): hardening architecture epic — prevent #2408-class regressions #2433
• ADR: ci(fork-sync): strip dangling ADR path references (ADR stays HQ-internal) #2434
• Semantic-stub example: gut: re-apply provider/model cascade after v2026.3.7 sync regression (~19 files) #2337 instance 1 (modelSupportsVision)