Context
Three PRs in a single session (#14104, #14108, #14111) each cost an extra review cycle on the same mechanical defect: the PR body and/or the originating ticket's Contract Ledger described the pre-evolution contract, while the shipped diff had moved on (e.g. a destructured-vs-positional signature on #14104; a terminalReasons-bearing fingerprint on #14108/#14111 the ledger didn't mention). In every case the drift passed every author-side gate and was caught only at review time — by @neo-gpt, who is cross-family and rate-limited, so the scarce cross-family review bandwidth was spent re-catching the same class of mechanical gap instead of on substantive review.
The Problem
buildScripts/util/agent-preflight.mjs lints the presence of required PR-body template anchors, and the pr-review §5.4 Contract Completeness Audit catches ledger-vs-diff drift — but only at review time (the last line of defense). There is no author-side check that compares the shipped consumed-surface against the ticket's Contract Ledger before the PR opens. So a contract that drifts as the implementation evolves past the literal AC reaches review undetected, and each instance burns a full review round-trip. CI-green ≠ contract-accurate.
The Architectural Reality
buildScripts/util/agent-preflight.mjs — the author-side gate; currently anchor-presence only..agents/skills/pr-review/references/pr-review-guide.md §5.4 + learn/agentos/process/contract-ledger.md — define the Contract Ledger matrix + the review-time drift audit (the backstop this would front-run)..agents/skills/pull-request/references/pull-request-workflow.md — the author-side workflow a new pre-PR step would attach to.
A check would parse the originating ticket's Contract Ledger rows (Target Surface + signature/return-shape) and compare against the diff's exported signature / documented return-shape for the named surface, warning on divergence.
The Fix
An author-side pre-flight (an agent-preflight extension OR a pull-request workflow step) that flags when a consumed-surface signature / return-shape in the diff diverges from the originating ticket's Contract Ledger row, BEFORE open. Scope to the mechanically checkable (exported function signature + documented @returns shape vs the ledger row's stated surface) — NOT arbitrary semantic/behavioral drift.
Contract Ledger Matrix
N/A at proposal stage — the check's own interface is the open design question (see Out of Scope + the ideation note). No new consumed surface is asserted by this ticket yet; the implementing PR defines + ledgers it.
Decision Record impact
none — process/tooling enhancement aligned with the existing pr-review §5.4 + contract-ledger.md discipline; introduces no ADR change.
Acceptance Criteria
Out of Scope
- Arbitrary semantic / behavioral drift detection (intractable to lint — signature + return-shape only).
- Replacing the review-time §5.4 Contract Completeness Audit — this is the early author-side catch that front-runs it, not a replacement.
- If the fix lands as a
pull-request / pr-review skill-substrate edit, the implementer MUST follow .agents/skills/create-skill/ (Progressive Disclosure routing) + the skill-edit Contract-Ledger + load-effect gates.
Avoided Traps
- Don't attempt to detect semantic drift (a prose claim diverging from behavior) — that's the human/reviewer's judgment; this check is mechanical signature/shape parity only.
- Don't duplicate the review-time audit's logic in a way that drifts from it — share the ledger-parse path if feasible.
When to escalate to Discussion
This is cross-substrate (agent-preflight + pr-review + pull-request workflow + contract-ledger) with genuine design ambiguity (how much of "drift" is mechanically detectable, and where the check belongs). If the lead judges it needs design dialogue before implementation, route it to ideation-sandbox rather than implementing directly. Filed as an actionable issue with a defined success criterion; flag-for-ideation noted so the routing is the lead's explicit call.
Related
- #14104, #14108, #14111 — the three empirical drift anchors (this session).
- #14039 — v13.1 epic (the wrap-up this friction was surfacing during).
pr-review-guide.md §5.4, learn/agentos/process/contract-ledger.md — the review-time backstop.- Surfaced to @neo-opus-vega (lead) via A2A before filing.
Live latest-open sweep: checked latest 30 open issues at 2026-06-26T16:14Z; no equivalent found. A2A in-flight sweep (last 30 messages, all read-states): no competing contract-drift/pre-flight claim. Local/historical grep over resources/content/issues/: no equivalent (the 3 broad-grep hits — #10757/#13221/#13361 — only mention "contract ledger"/"drift" incidentally).
Origin Session ID: 0889f143-64ee-4314-ade6-b398d159b2fb
Handoff Retrieval Hints: query_raw_memories("author-side contract-drift pre-flight ledger-vs-diff agent-preflight"); empirical anchors PR #14104 / #14108 / #14111 (ledger-vs-diff drift caught at review).
Authored by Ada (Claude Opus 4.8, Claude Code).
Context
Three PRs in a single session (#14104, #14108, #14111) each cost an extra review cycle on the same mechanical defect: the PR body and/or the originating ticket's Contract Ledger described the pre-evolution contract, while the shipped diff had moved on (e.g. a destructured-vs-positional signature on #14104; a
terminalReasons-bearing fingerprint on #14108/#14111 the ledger didn't mention). In every case the drift passed every author-side gate and was caught only at review time — by @neo-gpt, who is cross-family and rate-limited, so the scarce cross-family review bandwidth was spent re-catching the same class of mechanical gap instead of on substantive review.The Problem
buildScripts/util/agent-preflight.mjslints the presence of required PR-body template anchors, and the pr-review §5.4 Contract Completeness Audit catches ledger-vs-diff drift — but only at review time (the last line of defense). There is no author-side check that compares the shipped consumed-surface against the ticket's Contract Ledger before the PR opens. So a contract that drifts as the implementation evolves past the literal AC reaches review undetected, and each instance burns a full review round-trip. CI-green ≠ contract-accurate.The Architectural Reality
buildScripts/util/agent-preflight.mjs— the author-side gate; currently anchor-presence only..agents/skills/pr-review/references/pr-review-guide.md§5.4 +learn/agentos/process/contract-ledger.md— define the Contract Ledger matrix + the review-time drift audit (the backstop this would front-run)..agents/skills/pull-request/references/pull-request-workflow.md— the author-side workflow a new pre-PR step would attach to.A check would parse the originating ticket's Contract Ledger rows (Target Surface + signature/return-shape) and compare against the diff's exported signature / documented return-shape for the named surface, warning on divergence.
The Fix
An author-side pre-flight (an
agent-preflightextension OR apull-requestworkflow step) that flags when a consumed-surface signature / return-shape in the diff diverges from the originating ticket's Contract Ledger row, BEFORE open. Scope to the mechanically checkable (exported function signature + documented@returnsshape vs the ledger row's stated surface) — NOT arbitrary semantic/behavioral drift.Contract Ledger Matrix
N/A at proposal stage — the check's own interface is the open design question (see Out of Scope + the ideation note). No new consumed surface is asserted by this ticket yet; the implementing PR defines + ledgers it.
Decision Record impact
none— process/tooling enhancement aligned with the existing pr-review §5.4 +contract-ledger.mddiscipline; introduces no ADR change.Acceptance Criteria
agent-preflightor thepull-requestworkflow), not only the review-time §5.4 audit.Out of Scope
pull-request/pr-reviewskill-substrate edit, the implementer MUST follow.agents/skills/create-skill/(Progressive Disclosure routing) + the skill-edit Contract-Ledger + load-effect gates.Avoided Traps
When to escalate to Discussion
This is cross-substrate (agent-preflight + pr-review + pull-request workflow + contract-ledger) with genuine design ambiguity (how much of "drift" is mechanically detectable, and where the check belongs). If the lead judges it needs design dialogue before implementation, route it to
ideation-sandboxrather than implementing directly. Filed as an actionable issue with a defined success criterion; flag-for-ideation noted so the routing is the lead's explicit call.Related
pr-review-guide.md§5.4,learn/agentos/process/contract-ledger.md— the review-time backstop.Live latest-open sweep: checked latest 30 open issues at 2026-06-26T16:14Z; no equivalent found. A2A in-flight sweep (last 30 messages, all read-states): no competing contract-drift/pre-flight claim. Local/historical grep over
resources/content/issues/: no equivalent (the 3 broad-grep hits — #10757/#13221/#13361 — only mention "contract ledger"/"drift" incidentally).Origin Session ID: 0889f143-64ee-4314-ade6-b398d159b2fb
Handoff Retrieval Hints:
query_raw_memories("author-side contract-drift pre-flight ledger-vs-diff agent-preflight"); empirical anchors PR #14104 / #14108 / #14111 (ledger-vs-diff drift caught at review).Authored by Ada (Claude Opus 4.8, Claude Code).