[debate] agent-spec v1: per-action mandate with enforced_by, replacing the autonomy label #10

What you're proposing

Replace agent-spec.schema.yaml v0.1.0 with a v1 that assigns authority action by action, each row requiring an enforcing mechanism, and drop the single per-agent autonomy label the current format requires.

What it affects

• An aux.H* heuristic ID or definition
• An aux.T* trust stage ID or definition
• A tg.* gap ID or definition
• A schema file in /schemas/
• Public vocabulary (the words we use externally)
• Other — aux-audit's rule set and its published output contract

Why now

The repository contradicts itself, in one file.

schemas/trust-architecture.yaml says:

Autonomy is not a slider you push to the right. It is a spectrum you choose per action, calibrated to evidence and stakes.

Enforcement lives in a mechanism, not in a prompt. A prompt saying "only update qualification information" is not the same as a tool that exposes only the qualification field. The first is a request; the second is a boundary.

schemas/agent-spec.schema.yaml requires:

autonomy:
  type: enum
  values: ["human-in-the-loop", "human-on-the-loop", "autonomous"]
  required: true

One slider position, for the whole agent. The reference input format requires precisely the abstraction the standard tells readers to avoid.

It is not cosmetic. aux-audit scores on it:

• rules.ts — aux.H01 and aux.H03 take their base score from spec.autonomy (lines 55–70, 99–112)
• guarantees is free text, described in the schema as "explicit contracts the agent makes with the user (e.g. 'will always ask before sending external email')" — a promise. Three rules read it. There is no field anywhere in the format for the mechanism that enforces it.

So the audit's two most prominent heuristics rest on a label the canon calls wrong, and its notion of a guarantee is the exact thing enforcement.rule says is not a control.

Second, smaller defect: the file is not JSON Schema, though it uses the reserved $schema key as a container for a bespoke notation ({ type: string, required: true }). Any JSON Schema tool reads it wrong, and check_schema fails on it.

This is the first thing a careful reader finds. The docs say "don't use autonomy labels"; the reference implementation requires one.

Proposal

Adopt a v1 built as real JSON Schema draft 2020-12, whose core is:

mandate:
  type: array
  description: Assigned authority, action by action. Never an autonomy score.
  items:
    required: [action, authority, enforced_by]
    properties:
      authority:
        enum: [autonomous, human_approval, human_only, prohibited]
      enforced_by:
        description: The mechanism, not the intention.
                     "System prompt" is not a valid answer for human_only or prohibited.

Plus human_control (observe / interrupt / approve / override / disable — a kill switch alone is not oversight) and shutdown with a required tested boolean, because an untested kill switch is a claim, not a control.

A working draft exists and is the basis of this proposal.

Two things to settle before adoption

1. ID namespace. The draft's trust_stage enum is T01–T04. This repo's canon is aux.T01–aux.T04. Left unfixed this re-introduces the same fork that feat(schemas): merge the substance from the parallel schema set #9 had to unpick.
2. Should the input carry the output at all? trust_stage in the draft is described as "the stage demonstrably earned" — but aux-audit computes the trust stage. Either the audit ignores the field, or it does something better: compares the claim against its own computation and reports the gap. "You declare T03; the spec supports T01" would be the most useful line the tool could print. That is a feature decision, not a schema detail.

Migration note

This is aux-audit v0.2, not a patch. Concretely:

• spec.ts — rewritten. Real JSON Schema validation needs a validator; the package currently has exactly one runtime dependency (yaml), so adding ajv is its own call.
• rules.ts — aux.H01 and aux.H03 stop asking "what is the autonomy label" and start asking "does every non-autonomous action name an enforcing mechanism". That is a better question and a different computation.
• All fixtures and 34 tests.
• repos/aux-audit/README.md publishes the v0.1 output contract; scores computed under v1 are not comparable to scores computed under v0.1, so the version has to move where anyone can see it.

Proposed sequencing, one PR:

• schemas/agent-spec.v0.yaml — the current file, kept readable for anything already written against it
• schemas/agent-spec.schema.yaml — v1
• the CLI rewrite lands in the same PR. Renaming first would leave a window where the canonical filename describes a format the shipped CLI cannot read.

Alternatives considered

• Keep v0.1, soften the docs. Rejected: the doctrine is the product. Weakening "define authority for specific actions" to match a schema is the wrong direction of fit.
• Add mandate alongside autonomy, keep both. Rejected as a permanent state — two ways to say the same thing is how a standard rots — but it is a reasonable transitional shape if v1 needs to ship before the CLI rewrite is ready.
• Do nothing before launch. Rejected. This is a self-contradiction in the flagship artifact, and it is more expensive to be shown it than to fix it.

Interim, regardless of this outcome

The repository should not ship a known self-contradiction silently. A deprecation header on agent-spec.schema.yaml naming both defects and pointing here is going up now — the same treatment evolution_stage: schema-undefined got, which is: name the defect where the reader meets it.