spec(governance): require check_governance on every spend-commit (#2403)

[bokelley]

Closes #2403.

Summary

Turns Embedded Human Judgment into an enforceable MUST. When a governance agent is configured on the plan, buyer agents MUST invoke check_governance before every spend-commit request — full stop. No dollar floors, anomaly thresholds, or cold-start exemptions. Auto-approve fast-paths live inside the governance agent's own policy via the existing budget.reallocation_threshold and human_review_required surfaces.

Seller enforcement makes the MUST real: a seller receiving a spend-commit for a governance-configured plan MUST require a valid, in-date governance_context token for the matching plan and phase, and MUST reject with PERMISSION_DENIED otherwise. A buyer that skips check_governance cannot produce a valid token, so the commit is rejected at the seller.

Why always-invoke instead of the threshold design posted on #2403

The working-group comments on #2403 proposed a three-trigger threshold (operator floor + 3× median + cold-start). After expert review, that design lost on five fronts:

1. Gaming surface. Per-commit floors invite split-orders, anomaly medians can be poisoned by seeding the baseline with a few inflated commits, cold-start is gamed by rotating plan_ids or sellers.
2. Contradicts an existing invariant. check_governance.mdx already says "if governance is configured and unreachable, MUST NOT proceed." That's incompatible with "configured but this commit is small enough to skip."
3. Regulator clarity. "Every spend-commit was checked" is a one-line attestation. "Every spend-commit above an operator floor, or 3× median, or within cold-start, was checked" is an audit nightmare — a verifier has to recompute the buyer's median to prove the MUST held.
4. Threshold already lives in the right place. reallocation_threshold + human_review_required on the plan are where the governance agent is told when to auto-approve vs. escalate. Duplicating that one layer up was a design mistake.
5. Seller enforcement becomes a pure token check. A seller can't verify a buyer computed the median correctly. "Valid governance_context token or reject" is all a seller can meaningfully enforce.

Spend-commit tasks in scope

create_media_buy, update_media_buy, acquire_rights, update_rights, activate_signal, build_creative, and any future spend-commit task. NOT triggered by discovery (get_products, get_signals), reporting (get_media_buy_delivery), or operational-status tasks.

Test plan

• npm run test:unit — 587 passing
• npm run typecheck — clean
• Mintlify renders new sections; anchor links resolve (#spend-commit-invocation, #signed-governance-context, #idempotency, #seller-verification-checklist)
• Working-group sign-off on the always-invoke direction before merge

🤖 Generated with Claude Code

[github-actions]

Schema Link Check Results

Commit: 772d1c7 - spec(governance): apply expert-review feedback to #2403 — intent-phase clarifications + seller retention (#2403 follow-up)

⚠️ Warnings (schema not yet released)

These schemas exist in source but haven't been released yet. The links will be broken until the next version is published:

• https://adcontextprotocol.org/schemas/v3/enums/specialism.json
  • Schema exists in latest (source) but not yet released in v3
  • Action: This link will work after next 3.x release is published

---

To fix: Either:

1. Wait for the next release and merge this PR after the release is published
2. Use latest instead of a version alias if you need the link to work immediately (note: latest is the development version and may change)
3. Coordinate with maintainers to cut a new release before merging

[bokelley]

Expert review round applied

Ran the always-invoke shape by security-reviewer and ad-tech-protocol-expert in parallel. Both independently flagged the same latent bug: the first draft of the Seller enforcement paragraph read as if the buyer produced a purchase-phase token, contradicting the JWS profile (intent tokens are pre-seller; purchase tokens are seller-assigned with media_buy_id).

Applied in the follow-up commit:

Correctness

• Name the buyer's token as intent-phase up front (§126, §148, check_governance.mdx invocation section)
• Document the two-step flow: buyer's intent check → seller's execution check → purchase-phase token bound to the newly assigned media_buy_id for the rest of the lifecycle
• Fix pre-existing bug in check_governance.mdx pseudocode that passed phase: "purchase" to the verifier for a token the buyer just attached

New MUSTs surfaced by the security review

• Sellers MUST persist accepted governance tokens keyed by (jti, iss, aud, sub, phase, outcome, timestamp) so auditor reconciliation between seller records and get_plan_audit_logs is possible — without this, the audit log is single-sourced from the entity under scrutiny
• Idempotency/replay-dedup carve-out: repeated jti with the same idempotency_key is a legitimate retry, not a replay attack

Clarifications

• Sellers MAY refuse to transact on plans lacking a configured governance agent as commercial policy (closes the "buyer declares no governance agent to evade the MUST" loophole without forcing the protocol to mandate one)
• Multi-seller fanout produces one intent token per seller (correct protocol shape), and operators should know their GA sees the full shopping list
• Accepted residual risk for stale approvals: tight exp bounds the window; operators who cannot tolerate it set reallocation_threshold: 0 or human_review_required: true

CI remains green. Ready for working-group review.