Repository navigation
Description
Summary
The documentation says that a buyer needs a human_override artifact to lower human_review_required from true to false on a re-sync, and the specification puts human_override in the plan_hash preimage. No schema declares the field, the sync_plans field table does not list it, and the specification never states the downgrade rule. Only the reference agent defines the shape and enforces it.
This issue asks to declare the field and state the rule. It also asks how the declaration should land, because it narrows what validates against 3.2.11. It was split out of #9015 at the maintainers' request (comment, comment).
Current state
All paths are at 620b161. Re-verify them at implementation time.
Where the field is named
docs/governance/annex-iii-obligations.mdx:64:A buyer who previously declared
human_review_required: truecannot downgrade it on re-sync without an explicithuman_overrideartifact (reason + approver).docs/governance/campaign/specification.mdx:936, in theplan_hashprofile:All other fields — including
ext,custom_policies,objectives,delegations,human_override, and every field declared in thesync_plansplan-item schema — are IN the preimage.docs/reference/release-notes.mdx:1107: "downgrades require ahuman_overrideartifact".CHANGELOG.md:8882adds the detail "(≥20-char reason, email approver, 24h-freshapproved_at)".
Where it is missing
static/schemas/source/governance/sync-plans-request.json: the plan item does not declarehuman_override. The item is open ("additionalProperties": true), so any value validates. The publisheddist/schemas/3.2.11/governance/sync-plans-request.jsonis the same on both points.docs/governance/campaign/tasks/sync_plans.mdx: the field table has no row for it, and the error table has no row for a rejected downgrade.docs/governance/campaign/specification.mdx:150-165, "Human review required": the section says when the flag is set and thatfalseis rejected while a triggering policy is present. It does not mention lowering the flag on a re-sync or the artifact.- No file under
static/compliance/sourceortestsmentionshuman_override.
What the reference agent does
server/src/training-agent/governance-handlers.ts:770-780declares the shape on its own tool schema: an object withreason(20 to 1000 characters),approver(email), and an optionalapproved_at, withreasonandapproverrequired.:1251-1277: when the stored plan has human review required and the re-sync would leave it not required, the agent rejects the sync withVALIDATION_ERRORunlesshuman_overrideis present, has a reason of at least 20 characters, has an emailapprover, and has anapproved_atthat is not in the future and not older than 24 hours.:1321: the agent stores the artifact on the plan and keeps it on later re-syncs that do not send one.
A name that looks related and is not. drift_metrics.human_override_rate in get-plan-audit-logs-response.json is the fraction of escalations in which the human overrode the agent's recommendation. It has no connection to this artifact.
Problem
Two conformant governance agents give different answers on a regulatory safeguard. A plan declares policy_categories: ["fair_housing"], so human review is required. The buyer re-syncs the plan without that category and without the flag.
- Agent A follows the reference agent. It rejects the sync with
VALIDATION_ERROR, because the stored plan required human review and nohuman_overridewas sent. - Agent B is built from the specification and the schemas. Neither states the rule, so it accepts the sync and stops escalating the plan's actions.
Both agents conform to the normative text. The rule that separates them is one sentence on an explanatory page.
A buyer cannot know what to send. The only description of the shape is "(reason + approver)". A buyer that sends "human_override": "approved by legal" passes schema validation at 3.2.11 and on main, and is rejected by the reference agent.
The field is in the plan_hash preimage with no stated lifetime. If the artifact is sent only on the sync that lowers the flag, the next re-sync without it changes plan_hash and invalidates outstanding governance_context tokens. The reference agent keeps the stored artifact, but the preimage is the plan "as supplied on sync_plans" (specification.mdx:920).
Proposed change
-
Declare
plans[].human_overrideinsync-plans-request.json. Optional property, normative shape:"human_override": { "type": "object", "description": "Record of the human decision that permits lowering human_review_required from true to false on a re-sync. Part of the plan_hash preimage.", "properties": { "reason": { "type": "string", "minLength": 1 }, "approver": { "type": "string" }, "approved_at": { "type": "string", "format": "date-time" } }, "required": ["reason", "approver"], "additionalProperties": true }
-
State the rule in the specification, in "Human review required". Normative:
- A
sync_plansthat would change a stored plan from human review required to not required MUST carryhuman_override. Without it the governance agent MUST reject the sync withVALIDATION_ERRORand leave the plan unchanged. - The rule applies whether the re-sync sends
falseor omits the flag. - A governance agent MAY apply stricter checks, such as a minimum reason length, a freshness window on
approved_at, or bindingapproverto an authenticated identity. human_overridenever permitsfalsewhile a triggering policy or category is present. That rejection is unchanged.
- A
-
sync_planstask page. A field-table row, and the rejected downgrade in theVALIDATION_ERRORrow. -
Compliance. One storyboard that re-syncs a plan to lower the flag without the artifact and expects
VALIDATION_ERROR, then with it and expects success.
Cases that need no change: a plan that never required human review, a re-sync that keeps the flag true, and a re-sync that raises it.
Compatibility and the notice question
The file is x-status: experimental.
- The declaration narrows what validates. At 3.2.11 the plan item is open and the property is undeclared, so a string, an object with only
reason, and an emptyreasonall validate. The shape above rejects all three. - The lint does not catch it.
scripts/lint-additive-minor.cjs:689-697skips files marked experimental. - The contract for experimental surfaces (
docs/reference/experimental-status.mdx:41-45) requires for a breaking change "At least 6 weeks published in release notes and the changelog before the change lands", a migration note, and an alias where feasible.
The question for the maintainers is whether declaring a property that the documentation already named, on an open experimental object, is a breaking change under that contract. Three resolutions would settle it:
- A. Treat it as breaking. Publish the notice and land the declaration in the first minor after six weeks.
- B. Treat it as documenting existing behaviour. The only shape ever described is "reason + approver", and the reference agent has rejected every other shape since feat(governance)!: enforce Art 22 / Annex III as schema invariants (#2310) #2338. Land it in a 3.3 release candidate with a migration note.
- C. Declare it loosely now, tighten after notice. Declare an object with no required members in 3.3, and add
requiredafter the notice period.
A and B both work. C avoids the question, at the cost of a schema that still accepts a reason-only object for one more release.
Open questions
- Does an omitted flag count as a downgrade? Since fix(governance): accept an omitted human_review_required and state two sync_plans validation rules #9007 an omitted flag is derived. The reference agent treats "stored
true, now derivedfalse" as a downgrade. The proposal above follows it. - Does the rule apply when the earlier
truewas derived and not set by the caller? The reference agent does not distinguish the two. - How long does the artifact live? Either the buyer keeps sending it on every later re-sync, or the specification says that it is carried forward and how that affects
plan_hash. - What is
approver? A free string, an email address as the reference agent requires, or an identity the governance agent can authenticate. - Should the audit log record the downgrade? The entry types in
get-plan-audit-logs-response.jsonarecheck,outcomeandadjustment, so a plan change has no entry today.
Alternatives considered
- Do nothing. The rule stays on an explanatory page, and agents diverge on whether a regulated plan can leave human review silently.
- Forbid the downgrade. A plan that required human review keeps it for life, and a buyer that changes scope syncs a new
plan_id. This needs no artifact and no new field. It removes a path the 3.0 release notes describe as supported, and it would also be a behaviour change for the reference agent. - Keep the field undeclared and state only the rule. This fixes the divergence between agents and leaves the buyer without a shape to send.
Files affected
static/schemas/source/governance/sync-plans-request.jsondocs/governance/campaign/specification.mdx, "Human review required"docs/governance/campaign/tasks/sync_plans.mdxdocs/governance/annex-iii-obligations.mdx, to point at the normative rule- A schema test, and one storyboard under
static/compliance/source - Release notes and the migration guide, for the notice if resolution A or C is chosen
Not affected: the plan_hash rule itself, drift_metrics.human_override_rate, and the reference agent's behaviour, unless question 4 changes the approver format.
Related
- fix(governance): correct stale campaign-governance pages and schema descriptions #9015: this was split out of that PR. The review there raised the narrowing and the notice question (comment).
- Governance: campaign-governance coherence sweep — 8 page-vs-spec conflicts, 2 spec-vs-schema contradictions, 6 undefined behaviours #8733: the campaign-governance coherence sweep that found the gap.
- fix(governance): accept an omitted human_review_required and state two sync_plans validation rules #9007: made an omitted
human_review_requiredvalid, which is why question 1 exists. - feat(governance)!: enforce Art 22 / Annex III as schema invariants (#2310) #2338 and GDPR Art 22 / EU AI Act Annex III: block agent_full for regulated verticals #2310: introduced the downgrade rule and the artifact in 3.0.
- conformance: plan_hash canonicalization test vectors #2477 (closed): asked for a
plan_hashtest vector that exerciseshuman_override{}. - RFC: Surface buyer-side human approval as an issuer claim in the governance token #6381 (closed, not planned): proposed carrying a human's approval of a buy in the governance token. That is approval of one action. This issue is about permission to remove a plan's review requirement.
Activity
KonstantinMirin commentedon Nov 17, 2026
@lukasz-pubx thanks for splitting this out. I wonder whether forbidding the downgrade would be simpler than declaring
human_override. Once a stored plan requires human review, it would keep it for thatplan_id, and a buyer whose scope changed would sync a new plan.A few things push me that way, and I may be missing context:
human_override, so the documented shape would fail validation outside the training agent. 3.2.11 accepts any value only since fix(schemas): open the 3.3 schemas that were meant to be open #8866 opened the object.reasonandapprovercome from the party whose review is being removed, so it reads to me like the spending agent approving its own spend, whichtrust.mdx:22rules out.specification.mdx:165re-evaluates the flag on every sync, so a spec-built agent accepts the downgrade today, and rejecting it is what narrows.If that holds, I'd lean towards option A applied to the rule: a notice in rc.1, then the MUST six weeks later.
On the open questions, if we drop the artifact:
true; only an explicitfalseis rejected.truewas derived or set.human_overridewould leave the preimage atspecification.mdx:936.approverneeded.Does that match how you see it? I sketched the rule text and test vectors in this gist. Happy to review the PR.
bokelley commentedon Nov 17, 2026
Thanks @lukasz-pubx, a clear write-up. Decision: resolution B, in 3.4 rather than a 3.3 RC, with a migration note. "Reason + approver" is the only shape ever documented, and the reference agent has enforced it since 3.0. Option C doesn't avoid the question, because declaring any object still stops a string from validating.
On the open questions:
true, now derivedfalse.true: yes, the rule applies whether the earliertruewas set by the caller or derived.plan_hashrule stays as it is. A buyer SHOULD resendhuman_overridewhile the flag stays lowered, because omitting it changesplan_hashand invalidates outstandinggovernance_contexttokens. That fails safe.approver: a string. A governance agent MAY require an email address or bind it to an authenticated identity.That's implemented in #9074, which waits until 3.3.0 ships.