Skip to content

Governance: declare human_override on the sync_plans plan item and state the human-review downgrade rule #9068

Open

Description

@lukasz-pubx

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: true cannot downgrade it on re-sync without an explicit human_override artifact (reason + approver).

  • docs/governance/campaign/specification.mdx:936, in the plan_hash profile:

    All other fields — including ext, custom_policies, objectives, delegations, human_override, and every field declared in the sync_plans plan-item schema — are IN the preimage.

  • docs/reference/release-notes.mdx:1107: "downgrades require a human_override artifact". CHANGELOG.md:8882 adds the detail "(≥20-char reason, email approver, 24h-fresh approved_at)".

Where it is missing

  • static/schemas/source/governance/sync-plans-request.json: the plan item does not declare human_override. The item is open ("additionalProperties": true), so any value validates. The published dist/schemas/3.2.11/governance/sync-plans-request.json is 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 that false is 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/source or tests mentions human_override.

What the reference agent does

  • server/src/training-agent/governance-handlers.ts:770-780 declares the shape on its own tool schema: an object with reason (20 to 1000 characters), approver (email), and an optional approved_at, with reason and approver required.
  • :1251-1277: when the stored plan has human review required and the re-sync would leave it not required, the agent rejects the sync with VALIDATION_ERROR unless human_override is present, has a reason of at least 20 characters, has an email approver, and has an approved_at that 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 no human_override was 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

  1. Declare plans[].human_override in sync-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
    }
  2. State the rule in the specification, in "Human review required". Normative:

    • A sync_plans that would change a stored plan from human review required to not required MUST carry human_override. Without it the governance agent MUST reject the sync with VALIDATION_ERROR and leave the plan unchanged.
    • The rule applies whether the re-sync sends false or omits the flag.
    • A governance agent MAY apply stricter checks, such as a minimum reason length, a freshness window on approved_at, or binding approver to an authenticated identity.
    • human_override never permits false while a triggering policy or category is present. That rejection is unchanged.
  3. sync_plans task page. A field-table row, and the rejected downgrade in the VALIDATION_ERROR row.

  4. 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 empty reason all validate. The shape above rejects all three.
  • The lint does not catch it. scripts/lint-additive-minor.cjs:689-697 skips 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 required after 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

  1. 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 derived false" as a downgrade. The proposal above follows it.
  2. Does the rule apply when the earlier true was derived and not set by the caller? The reference agent does not distinguish the two.
  3. 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.
  4. What is approver? A free string, an email address as the reference agent requires, or an identity the governance agent can authenticate.
  5. Should the audit log record the downgrade? The entry types in get-plan-audit-logs-response.json are check, outcome and adjustment, 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.json
  • docs/governance/campaign/specification.mdx, "Human review required"
  • docs/governance/campaign/tasks/sync_plans.mdx
  • docs/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

Activity

  1. KonstantinMirin commented on Nov 17, 2026

    @KonstantinMirin
    Collaborator

    @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 that plan_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:

    1. I'm not sure the artifact was ever sendable. As far as I can see, every published plan item from 3.0.0 through 3.2.10 is closed and doesn't declare 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.
    2. It's self-asserted. reason and approver come from the party whose review is being removed, so it reads to me like the spending agent approving its own spend, which trust.mdx:22 rules out.
    3. I think the narrowing is the rule, not the field. On my fix(governance): correct stale campaign-governance pages and schema descriptions #9015 question: declaring an optional property on an open object looks additive to me. But specification.mdx:165 re-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:

    1. An omitted flag keeps the stored true; only an explicit false is rejected.
    2. The rule applies whether the earlier true was derived or set.
    3. Nothing to carry forward, so human_override would leave the preimage at specification.mdx:936.
    4. No approver needed.
    5. No new audit entry type, since a rejected sync changes nothing.

    Does that match how you see it? I sketched the rule text and test vectors in this gist. Happy to review the PR.

  2. bokelley commented on Nov 17, 2026

    @bokelley
    Contributor

    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:

    1. Omitted flag: yes, it's a downgrade. The rule follows the stored state: stored true, now derived false.
    2. Derived true: yes, the rule applies whether the earlier true was set by the caller or derived.
    3. Lifetime: follow the reference agent. The governance agent keeps the artifact on re-syncs that omit it, and the plan_hash rule stays as it is. A buyer SHOULD resend human_override while the flag stays lowered, because omitting it changes plan_hash and invalidates outstanding governance_context tokens. That fails safe.
    4. approver: a string. A governance agent MAY require an email address or bind it to an authenticated identity.
    5. Audit entry: out of scope for now.

    That's implemented in #9074, which waits until 3.3.0 ships.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions