Implement Contract Completeness Gate and Contract Ledger

Context Ideation Sandbox Discussion #10703 highlighted that 5 of 6 review cycles on PR #10700 were spent negotiating the exact API contract (edge cases, legacy fallbacks, concurrent test design) because the agent was allowed to assume the contract implicitly.

The Problem Allowing agents to assume the explicit contract for public or consumed surfaces leads to downstream negotiation during PR review, causing high friction and multi-cycle delays. Ambiguity in the contract must be resolved before coding begins.

The Architectural Reality Currently, ticket-intake classifies tickets by "reality" (stale/duplicate/real) but does not evaluate "contract completeness." The ticket creation process (ticket-create) does not force the author to explicitly define the contract matrix.

The Fix Implement a "Contract Completeness Gate" using a shared Contract Ledger matrix.

• Create learn/agentos/contract-ledger.md (sibling to Evidence Ladder) defining the L1-L4 taxonomy for contracts.
• Update .agents/skills/ticket-create/references/ticket-create-workflow.md to require the author to embed a Contract Ledger matrix for any public/consumed API changes.
• Update .agents/skills/ticket-intake/references/ticket-intake-workflow.md to verify the presence of the Contract Ledger before allowing the agent to branch/code.
• Update .agents/skills/pr-review/references/pr-review-workflow.md to formally audit PR adherence to the Contract Ledger.

Acceptance Criteria

• learn/agentos/contract-ledger.md is authored with the L1-L4 taxonomy and the matrix schema (Target Surface, Source of Authority, Proposed Behavior, Fallback, Docs, Evidence).
• ticket-create-workflow.md is updated to mandate the Contract Ledger matrix for public-surface tickets.
• ticket-intake-workflow.md is updated to include the Contract Completeness verification step.
• pr-review-workflow.md is updated to include the Source-of-Authority/Evidence Audit against the Contract Ledger.

Out of Scope

• This does NOT replace the "ticket reality" classifications (real/stale/duplicate/negative-ROI).
• This is NOT a universal gate for all tickets (e.g., simple bug fixes or internal refactors that do not change consumed surfaces are exempt).

Avoided Traps

• Trap: Adding a simple contract-ambiguous label. Why rejected: Orthogonal to reality classifications. A ticket can be real AND contract-ambiguous. A structured matrix (Contract Ledger) provides actionable spec alignment rather than just a blocker label.
• Trap: Putting all the burden on ticket-intake. Why rejected: The ticket creator has the context; writing the contract should be cheap upstream (ticket-create), while ticket-intake performs a cheap verification downstream.

Related

• Discussion #10703
• PR #10700 (Originating pain point)

Origin Session ID Origin Session ID: 5b81325c-f19f-4fa3-a3de-8673eb0982db

Contract Ledger (Dogfooding for #10704)