Repository navigation
fix(governance): correct stale campaign-governance pages and schema descriptions - #9015
Conversation
|
@lukasz-pubx could you split |
|
@lukasz-pubx the page and description corrections in
Also, I couldn't find anything in |
|
@KonstantinMirin thanks, both are right.
On a storyboard for This PR stays a draft until #9006 settles, since its remaining edits build on those sentences. |
93e5d26 to
050a9ea
Compare
|
@bokelley rebuilt as you asked, in
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 It stays a draft until #9006 merges, because the branch is built on it. After that it is rebased onto |
|
Thanks @lukasz-pubx, this is the right scope:
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. |
|
@bokelley both noted.
The plan-access sentence is being fixed in #9006. This branch gets rebased on that once it lands. |
KonstantinMirin
left a comment
There was a problem hiding this comment.
@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:
policy-category-definition.json:80still 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.get-plan-audit-logs-response.json:313describes "a futuregoverned_actions[].modefield". No such field exists, so I'd delete the sentence instead of rewording it.- 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. - The image
altatoverview.mdx:246still 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.
…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>
|
@lukasz-pubx one more for this PR, now that #9006 has merged: |
…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>
050a9ea to
6929ad5
Compare
|
@KonstantinMirin thanks, all of these are in
The nit. The table row for a threshold equal to The description. The mode sentence is now attributed to The rebase. The only conflict was the Jordan paragraph in One more erratum, in Delegation expiry, in |
There was a problem hiding this comment.
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.jsonunderstatic/schemas/source/governance/) whilereview_decisionisREVIEW_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) matchesstatic/schemas/source/**; static/schemas/source/governance/policy-entry.json (modified) matchesstatic/schemas/source/**; static/schemas/source/governance/sync-plans-request.json (modified) matchesstatic/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.
bokelley
left a comment
There was a problem hiding this comment.
Errata only: page, description and wording corrections against the #9006 rules, with human_override split out to #9068/#9074. Thanks @lukasz-pubx.
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_hashrule changes.Rebased onto
mainafter 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) and6929ad5(delegation expiry). The one conflict was the Jordan paragraph ingovernance/overview.mdx, which keeps the text that #9006 merged.Rebuilt on 2026-11-16 after review (comment, comment):
human_overridedeclaration is removed. Against 3.2.11 it narrowed what validates, so it needs its own review.PLAN_NOT_FOUNDchange, in the specification, thecheck_governanceerror table and the reference agent, moved to PR 2, because it became part of the A4 decision.human_review_requiredis accepted from 3.3.Second revision,
74bd575,08750e6and6929ad5, after this review and this comment:policy-category-definition.jsondescription 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 agoverned_actions[].modefield, which does not exist.alttext on the overview page no longer says budget is reserved.reallocation_thresholddescription point toreallocation_unlimited: truefor unlimited reallocation.check_governanceresponse has carried an optionalmodeproperty 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.delegations[].expires_atdescription 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, aredenied, and any other check from that agent returnsPLAN_NOT_FOUND.Refs #8733.
What changes
governance/policy-category-definition.json,governance/policy-entry.jsonrequires_human_reviewsays the governance agent setsplan.human_review_required, not the plan. The category description no longer says that a policy can override the category's setting.trust.mdx,reference/known-limitations.mdx,faq.mdxauthority_level, a field removed in 3.0, and says an omitted flag is accepted from 3.3.allOfinsync-plans-request.json: four policy categories, andeu_ai_act_annex_iiiinpolicy_ids. #9007 for the omitted flag.campaign/specification.mdx,campaign/tasks/sync_plans.mdxbudget.reallocation_thresholdis required only withoutreallocation_unlimited. The field table gains a row forreallocation_unlimited. The reallocation table and thereallocation_thresholddescription point toreallocation_unlimited: truefor unlimited reallocation.totalandcurrency, and exactly one of the two reallocation fields. Thereallocation_unlimiteddescription says to prefer it over a threshold equal tototal.governance/overview.mdxapprovedwith findings. The "Execute" step and the imagealttext no longer say budget is reserved.campaign/audit-trail.mdx,campaign/specification.mdx,governance/get-plan-audit-logs-response.jsongoverned_actions[].modefield 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[].modeis defined in the response schema, which says SHOULD on check entries and absent on outcome entries;check-governance-response.jsonhas an optionalmodeproperty; mode is agent configuration (PR 1).governance-handlers.tsmodeproperty on the sandboxsync_planstool 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 insync_plans".Doc paths are under
docs/anddocs/governance/. Schema paths are understatic/schemas/source/.Notes for review
entries[].modeon check entries. The specification now says SHOULD, so the two agree. An agent that conformed before still conforms.images/concepts/budget-commitment-phases.pngcannot be fixed in a text change. One sentence under the image says what the label means. The image needs redrawing.002, which carriesmodeinside a hashed plan;skills/adcp-governance/SKILL.md, which does not mentionreallocation_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.PLAN_NOT_FOUND. Nothing understatic/compliance/sourcegrades 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: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: passnode scripts/check-docs-mdx-syntax.mjs,node scripts/docs-json-field-audit.cjs: pass, no new findings against the baseline/governanceis 59 clean with 183 steps,governance/budget_periods7 passed, and the fivemedia_buy_seller/governance_*scenarios pass with their required counts./governanceis 27 clean with 146 steps.🤖 Generated with Claude Code