Skip to content

fix(governance): correct stale campaign-governance pages and schema descriptions - #9015

Merged
bokelley merged 4 commits into
mainfrom
governance/8733-follow-up-defects
Nov 18, 2026
Merged

bokelley merged 4 commits into
mainfrom
governance/8733-follow-up-defects

Conversation

@lukasz-pubx

@lukasz-pubx lukasz-pubx commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Summary

PR 4 for #8733: stale statements found in the campaign-governance pages and schema descriptions while preparing PRs 2 and 3. None was in the original issue. Each edit follows a rule that is already stated elsewhere in the specification or schemas, so this PR adds no new rule. No schema property, enum member or plan_hash rule changes.

Rebased onto main after PR 2 (#9006) merged. The diff now shows only this PR's change, in four commits: 735fb8d (the errata as first reviewed), 74bd575 (the review corrections), 08750e6 (mode on the response) and 6929ad5 (delegation expiry). The one conflict was the Jordan paragraph in governance/overview.mdx, which keeps the text that #9006 merged.

Rebuilt on 2026-11-16 after review (comment, comment):

  • The human_override declaration is removed. Against 3.2.11 it narrowed what validates, so it needs its own review.
  • The PLAN_NOT_FOUND change, in the specification, the check_governance error table and the reference agent, moved to PR 2, because it became part of the A4 decision.
  • The FAQ sentence now says that an omitted human_review_required is accepted from 3.3.

Second revision, 74bd575, 08750e6 and 6929ad5, after this review and this comment:

  • Category flag. The policy-category-definition.json description no longer says that a policy can override the category's setting. A policy adds the requirement, and no policy removes a category's requirement.
  • entries[].mode. The description no longer mentions a governed_actions[].mode field, which does not exist.
  • One strength for mode on audit entries. The specification said MAY, the audit-trail page said every entry, and the schema says SHOULD on check entries and none on outcome entries. The specification and the page now say what the schema says.
  • Image description. The alt text on the overview page no longer says budget is reserved.
  • Reallocation table. The table and the reallocation_threshold description point to reallocation_unlimited: true for unlimited reallocation.
  • Mode on the response, found while fixing the point above. The specification said that governance mode is "not a protocol-level field". The check_governance response has carried an optional mode property since 3.1, the task page documents it, and the reference agent returns it. The specification now says that mode is agent configuration, that no request carries it, and that the agent MAY report it on the response. Callers still MUST NOT branch on it.
  • Delegation expiry. The delegations[].expires_at description said that the governance agent denies an expired delegate's actions. It now follows the plan-access rule from feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006: a re-check that presents a context issued for the plan, and an execution check on an action the agent proposed, are denied, and any other check from that agent returns PLAN_NOT_FOUND.

Refs #8733.

What changes

Area Files Change Rule it follows
Schema descriptions governance/policy-category-definition.json, governance/policy-entry.json requires_human_review says the governance agent sets plan.human_review_required, not the plan. The category description no longer says that a policy can override the category's setting. Specification, "Human review required": the governance agent sets the flag when any resolved policy or policy category carries it.
Docs trust.mdx, reference/known-limitations.mdx, faq.mdx The human-review invariant names all five triggers. The FAQ stops describing 3.0 in the future tense, no longer names authority_level, a field removed in 3.0, and says an omitted flag is accepted from 3.3. The plan-item allOf in sync-plans-request.json: four policy categories, and eu_ai_act_annex_iii in policy_ids. #9007 for the omitted flag.
Docs campaign/specification.mdx, campaign/tasks/sync_plans.mdx budget.reallocation_threshold is required only without reallocation_unlimited. The field table gains a row for reallocation_unlimited. The reallocation table and the reallocation_threshold description point to reallocation_unlimited: true for unlimited reallocation. The schema requires total and currency, and exactly one of the two reallocation fields. The reallocation_unlimited description says to prefer it over a threshold equal to total.
Docs governance/overview.mdx Advisory mode returns approved with findings. The "Execute" step and the image alt text no longer say budget is reserved. Specification, "Governance modes" and "Budget tracking".
Docs, schema description campaign/audit-trail.mdx, campaign/specification.mdx, governance/get-plan-audit-logs-response.json Removes a reference to #3156, which is closed and implemented, a leftover of mode as a plan property, and a mention of a governed_actions[].mode field that does not exist. The specification and the audit-trail page state one strength for mode on audit entries. The specification no longer says mode is "not a protocol-level field". entries[].mode is defined in the response schema, which says SHOULD on check entries and absent on outcome entries; check-governance-response.json has an optional mode property; mode is agent configuration (PR 1).
Training agent governance-handlers.ts The mode property on the sandbox sync_plans tool is described as a test control, and one finding text says "governance mode" where it said "plan.mode". Behaviour is unchanged. campaign/audit-trail.mdx, "The operator's dial": mode "is not a plan field and is not sent in sync_plans".

Doc paths are under docs/ and docs/governance/. Schema paths are under static/schemas/source/.

Notes for review

  • One sentence in the specification changes strength. It said a governance agent MAY include mode in its audit logs. The response schema already says a governance agent SHOULD populate entries[].mode on check entries. The specification now says SHOULD, so the two agree. An agent that conformed before still conforms.
  • Whether a seller should see the buyer's governance mode is not raised here. The response field is released behaviour since 3.1. This PR only makes the specification describe it.
  • The overview diagram still shows a "reserved" label. images/concepts/budget-commitment-phases.png cannot be fixed in a text change. One sentence under the image says what the label means. The image needs redrawing.
  • Left alone on purpose: plan-hash vector 002, which carries mode inside a hashed plan; skills/adcp-governance/SKILL.md, which does not mention reallocation_unlimited; and everything listed as needing a decision in the notice on Governance: campaign-governance coherence sweep — 8 page-vs-spec conflicts, 2 spec-vs-schema contradictions, 6 undefined behaviours #8733.
  • Not in this PR: a compliance storyboard for PLAN_NOT_FOUND. Nothing under static/compliance/source grades it today.

Changeset

patch: descriptions and pages only. No schema property is added or removed.

Verification

Run locally on Node 24.22.1, at 6929ad5:

  • Pre-commit hook: pass. Root unit tests 1,284 passed. The full server unit suite passed in four shards, with 14,494 tests passed and 31 skipped. Typecheck passed.
  • npm run test:schemas, test:json-schema, test:examples, test:mcp-schema-projection, test:docs-nav, test:owned-links, test:additive-minor, test:compliance-snippets: pass
  • node scripts/check-docs-mdx-syntax.mjs, node scripts/docs-json-field-audit.cjs: pass, no new findings against the baseline
  • Pre-push hook: pass. Version sync and the changeset check passed.
  • Pre-push storyboard matrix against the training agent, current compliance source: all seven tenants meet their floors. /governance is 59 clean with 183 steps, governance/budget_periods 7 passed, and the five media_buy_seller/governance_* scenarios pass with their required counts.
  • Pre-push storyboard matrix, released 3.0.28 compliance bundle: all seven tenants meet their floors. /governance is 27 clean with 146 steps.
  • Pre-push docs validation: pass, 67 navigation tests.

🤖 Generated with Claude Code

@bokelley

Copy link
Copy Markdown
Contributor

@lukasz-pubx could you split human_override out of this PR? It adds a new schema property (x-added-in: 3.3.0) right at the 3.3 RC cut, and it needs its own review as a feature rather than as errata. The doc corrections can go ahead on their own once #9006 is aligned. Also, #9006 is being revised (see my comment there), so please rebase the A4 sentence edits on whatever lands.

@KonstantinMirin

Copy link
Copy Markdown
Collaborator

@lukasz-pubx the page and description corrections in 1b6616c look right to me against the existing rules. Two questions:

  • human_override. The published 3.2.11 plan item is open (additionalProperties: true), so any human_override value validates there, while this schema rejects a reason-only object, a string and an empty reason. Isn't that a narrowing? The additive-minor lint skips the file because it is experimental, so I think the six-week notice rule would apply. Would an issue offering the PR fit better, in line with splitting it out?
  • docs/faq.mdx. "Since AdCP 3.0 … When such a plan omits the flag, the governance agent sets it." Isn't the omission behaviour new in 3.3? Through 3.2.x the flag was required.

Also, I couldn't find anything in static/compliance/source that grades PLAN_NOT_FOUND. Would one check_governance step with expect_error: true be worth adding?

@lukasz-pubx

Copy link
Copy Markdown
Contributor Author

@KonstantinMirin thanks, both are right.

  • human_override. It is a narrowing against 3.2.11. The plan item there is open and does not declare the property, so a string or a reason-only object validates, and this schema rejects both. The lint skips the file because the surface is experimental, as you say. It comes out of this PR, which is also what @bokelley asked for, and an issue is the better place for it, with the notice question stated.
  • docs/faq.mdx. Correct. Through 3.2.x the schema required the flag on such a plan, and accepting an omitted flag is new in 3.3 with fix(governance): accept an omitted human_review_required and state two sync_plans validation rules #9007. The sentence will say that.

On a storyboard for PLAN_NOT_FOUND: nothing grades it today. What the step should expect for a plan the caller cannot access depends on the answer to your question on #9006, so it should wait for that.

This PR stays a draft until #9006 settles, since its remaining edits build on those sentences.

@lukasz-pubx
lukasz-pubx force-pushed the governance/8733-follow-up-defects branch from 93e5d26 to 050a9ea Compare November 16, 2026 13:19
@lukasz-pubx lukasz-pubx changed the title fix(governance): correct stale campaign-governance pages and declare human_override fix(governance): correct stale campaign-governance pages and schema descriptions Nov 16, 2026
@lukasz-pubx

Copy link
Copy Markdown
Contributor Author

@bokelley rebuilt as you asked, in 050a9ea. The description and the title are updated.

What is left is the page and description corrections: the five human-review triggers, who sets the flag, the reallocation fields, the overview page and the audit-log wording. The changeset is patch.

It stays a draft until #9006 merges, because the branch is built on it. After that it is rebased onto main and marked ready.

@bokelley

Copy link
Copy Markdown
Contributor

Thanks @lukasz-pubx, this is the right scope: human_override out, and the rest reads as errata. Two last things:

  1. Timing. This and feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006 both carry changesets, so they land after the 3.3 rc.0 marker merges and go out in rc.1. Please don't mark it ready before then.
  2. human_override. Could you file the follow-up issue you mentioned, with the 3.2.11 narrowing and six-week-notice question stated, and link it here? Then nothing gets lost when this merges.

I've left one more comment on #9006, about which callers count as able to access the plan. It affects the sentences this PR builds on.

@lukasz-pubx

Copy link
Copy Markdown
Contributor Author

@bokelley both noted.

  1. Timing. This stays a draft until the 3.3 rc.0 marker has merged and feat(governance): settle the campaign-governance rules that were contradictory or undefined #9006 has landed.
  2. human_override. Filed as Governance: declare human_override on the sync_plans plan item and state the human-review downgrade rule #9068. It states the narrowing against 3.2.11 and puts the six-week-notice question as three possible resolutions.

The plan-access sentence is being fixed in #9006. This branch gets rebased on that once it lands.

@KonstantinMirin KonstantinMirin left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lukasz-pubx 050a9ea is ready once it's rebased. Each edit matches the rule it cites, and the schema and governance tests pass at the head.

The rc.0 marker has merged, so only #9006 is left. The cherry-pick onto #9006's 84cbf74 conflicts in the Jordan paragraph at overview.mdx:240. Keep #9006's audit-mode sentences and this PR's advisory sentence, because #9006 still says advisory mode returns real denied statuses.

Four stale statements remain in files this PR already touches:

  1. policy-category-definition.json:80 still says "policies can override on policy-entry.requires_human_review". The trigger is any resolved policy or category (specification.mdx:154), so a policy can't turn a category's requirement off.
  2. get-plan-audit-logs-response.json:313 describes "a future governed_actions[].mode field". No such field exists, so I'd delete the sentence instead of rewording it.
  3. Mode on audit entries has three strengths: every entry (audit-trail.mdx:317), SHOULD on check entries and absent on outcome entries (the schema), and MAY (specification.mdx:887). The schema is the precise one.
  4. The image alt at overview.mdx:246 still says "budget reserved".

Nit: the table at specification.mdx:96 still offers a threshold equal to budget.total as the unlimited case, which the schema description advises against. A reallocation_unlimited: true row would close it.

The mode sentence the description attributes to the specification is at audit-trail.mdx:232.

What I ran at 050a9ea on Node 24: npm run test:schemas (36 schema validations plus 1,267 tests, 0 failures), the 14 governance training-agent files (1,072 passed), the MDX syntax check, and ajv over the budget oneOf (threshold only and unlimited: true only pass; neither, both, or unlimited: false fail). I also checked the triggers and the FAQ's version claims against dist/schemas/3.0.0 and 3.2.11.


lukasz-pubx and others added 2 commits November 17, 2026 17:40
…escriptions

PR 4 for #8733: defects found while preparing PRs 2 and 3. Each edit
follows a rule that is already stated in the specification or schemas.
No schema property, enum member or plan_hash rule changes.

- name all five human-review triggers on the trust, known-limitations
  and FAQ pages; the FAQ says an omitted flag is accepted from 3.3
- the requires_human_review descriptions say the governance agent sets
  plan.human_review_required
- reallocation_threshold is required only without reallocation_unlimited
- overview: advisory mode returns approved; no budget is reserved
- drop a stale reference to a closed issue; mode is agent configuration
- the training agent's plans[].mode is labelled a sandbox test control

Rebuilt on the aligned PR 2 (#9006). The human_override declaration is
removed from this PR, and the PLAN_NOT_FOUND change now lives in #9006.

Refs #8733

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Second revision of adcp#9015 after review.

- policy-category-definition.json: the requires_human_review description
  no longer says that a policy can override the category's setting. A
  policy adds the requirement, and no policy removes a category's.
- get-plan-audit-logs-response.json: the entries[].mode description no
  longer mentions a governed_actions[].mode field, which does not exist.
- specification.mdx, audit-trail.mdx: state one strength for mode on
  audit entries, the one the schema has. A governance agent SHOULD record
  the mode on check entries, and outcome entries carry none. The
  specification said MAY and the audit-trail page said every entry.
- overview.mdx: the image alt text no longer says budget is reserved.
- specification.mdx, sync-plans-request.json: the reallocation table and
  the reallocation_threshold description point to
  reallocation_unlimited: true for unlimited reallocation, because a
  threshold equal to total tightens when total changes.
- Changeset: cover the edits above.

No schema property, enum member or plan_hash rule changes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@KonstantinMirin

Copy link
Copy Markdown
Collaborator

@lukasz-pubx one more for this PR, now that #9006 has merged: sync-plans-request.json:383 still says "After expiration, the governance agent denies actions from this agent", while specification.mdx:215 now gives a caller with an expired delegation and no issued context PLAN_NOT_FOUND.

lukasz-pubx and others added 2 commits November 17, 2026 17:46
…sponse

The specification said that governance mode is "an internal
implementation detail of the governance agent, not a protocol-level
field". The check_governance response has carried an optional mode
property since 3.1, the task page documents it, and the reference agent
returns it.

- specification.mdx: mode is configuration of the governance agent. No
  request carries it, and it is not a plan field. The agent MAY report
  the mode in force on the check_governance response. Callers still MUST
  NOT branch on it.
- Changeset: cover the edit.

No schema, wire field or agent behaviour changes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…n-access rule

The delegations[].expires_at description in sync-plans-request.json said
that the governance agent denies an expired delegate's actions. Since
adcp#9006 a caller with an expired delegation and no issued context
gets PLAN_NOT_FOUND.

- sync-plans-request.json: after expiration the agent is no longer a
  current delegate. Its intent re-check that presents a
  consultation_context issued for the plan, and an execution check on an
  action it proposed, are denied with a delegation_authority finding.
  Any other check from that agent returns PLAN_NOT_FOUND.
- Changeset: cover the edit.

Description only. No schema property or validation outcome changes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@lukasz-pubx
lukasz-pubx force-pushed the governance/8733-follow-up-defects branch from 050a9ea to 6929ad5 Compare November 17, 2026 18:35
@lukasz-pubx

Copy link
Copy Markdown
Contributor Author

@KonstantinMirin thanks, all of these are in 74bd575. The branch is rebased onto main now that #9006 has merged, and the description is updated.

  1. policy-category-definition.json. The description no longer says that a policy can override the category's setting. It now says that a policy's own requires_human_review: true adds the requirement, and that no policy removes a category's requirement.
  2. get-plan-audit-logs-response.json. The sentence about a future governed_actions[].mode field is deleted.
  3. Mode on audit entries. The specification and the audit-trail page now say what the schema says: a governance agent SHOULD record the mode on check entries, and outcome entries carry none. This changes one MAY in the specification to SHOULD, and the description says so.
  4. Image alt. It no longer says budget is reserved.

The nit. The table row for a threshold equal to budget.total now says it holds only until budget.total changes and points to reallocation_unlimited: true. A sentence under the table covers the reallocation_unlimited: true case. The reallocation_threshold description in the schema no longer recommends a threshold equal to total.

The description. The mode sentence is now attributed to audit-trail.mdx.

The rebase. The only conflict was the Jordan paragraph in overview.mdx. It keeps the text that #9006 merged, which already has the advisory sentence you asked for.

One more erratum, in 08750e6. Your point 3 led to the sentence above it. The specification said that governance mode is "not a protocol-level field", while check-governance-response.json has had an optional mode property since 3.1 and the task page documents it. The specification now says that mode is agent configuration, that no request carries it, and that the agent MAY report it on the response. Callers still MUST NOT branch on it.

Delegation expiry, in 6929ad5. The expires_at description now follows the access rule: an intent re-check that presents a consultation_context issued for the plan, and an execution check on an action the agent proposed, are denied with a delegation_authority finding. Any other check from that agent returns PLAN_NOT_FOUND.

@lukasz-pubx
lukasz-pubx marked this pull request as ready for review November 17, 2026 20:16

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ladon verdict: Escalate to human review

Escalate — gated schema paths require human/CODEOWNERS approval.

This PR modifies four files under static/schemas/source/governance/**, which fall under the repo's hard, path-based approval gate (gated_paths: true). The current review_decision is REVIEW_REQUIRED, not APPROVED, so the gate is not yet satisfied (decision table row 2).

The reviewer's findings are clean: this is a description-and-docs-only errata sweep on the experimental campaign-governance surface with no schema property/enum/required/structural change, no oneOf regression, no dist/** mutation, and a correct patch changeset. No critical/high/medium findings were reported, so there are no blocking code-level issues — but the deterministic gated-path gate still requires a human reviewer to approve before this can merge.

Escalation reasons:

  • Modifies gated schema source files (get-plan-audit-logs-response.json, policy-category-definition.json, policy-entry.json, sync-plans-request.json under static/schemas/source/governance/) while review_decision is REVIEW_REQUIRED — human/CODEOWNERS approval required to satisfy the hard approval gate.

Why human review

  • Modifies gated schema source files under static/schemas/source/governance/ (get-plan-audit-logs-response.json, policy-category-definition.json, policy-entry.json, sync-plans-request.json) while review_decision is REVIEW_REQUIRED — human/CODEOWNERS approval required to satisfy the hard approval gate (decision table row 2).
  • This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/governance/get-plan-audit-logs-response.json (modified) matches static/schemas/source/**; static/schemas/source/governance/policy-category-definition.json (modified) matches static/schemas/source/**; static/schemas/source/governance/policy-entry.json (modified) matches static/schemas/source/**; static/schemas/source/governance/sync-plans-request.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

@aao-secretariat aao-secretariat Bot added the ladon/needs-human-review Ladon has escalated this PR for human review. label Nov 17, 2026
@aao-secretariat
aao-secretariat Bot requested a review from bokelley November 17, 2026 20:20

@bokelley bokelley left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Errata only: page, description and wording corrections against the #9006 rules, with human_override split out to #9068/#9074. Thanks @lukasz-pubx.

@bokelley
bokelley merged commit d24319d into main Nov 18, 2026
71 of 72 checks passed
@bokelley
bokelley deleted the governance/8733-follow-up-defects branch November 18, 2026 01:10
@bokelley bokelley mentioned this pull request Nov 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ladon/needs-human-review Ladon has escalated this PR for human review.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants