feat(agent-spec): land v1 as canonical, with a version shim in the CLI

[RevenuePuzzles]

What this PR does

Fixes the contradiction #10 was opened on. The canonical input format now assigns authority action by action, each non-autonomous row requiring an enforced_by mechanism, instead of the single per-agent autonomy label the canon tells readers to avoid.

File
schemas/agent-spec.schema.yaml	v1.0 — real JSON Schema draft 2020-12
schemas/agent-spec.v0.yaml	frozen; what aux-audit 0.1.x reads
schemas/MIGRATION.md	why, the field mapping, the timeline
schemas/migrate-v0-to-v1.py	converter

The shim is the point

Landing v1 under the canonical filename while the CLI still reads v0 would normally trade an inconsistent document for a broken tool, which is worse — a reader can reason around a document. Measured on a scratch copy before building anything, a v1 spec handed to the shipped CLI came back with:

aux-audit: agent spec is not valid:
  - `version` is required and must be a non-empty string
  - `surface` is required
  - `autonomy` is required        <- the field v1 removes on purpose
  - `memory` is required

Now:

aux-audit: this is an agent-spec v1.0 document; aux-audit 0.1.x reads v0.1.0.
  Nothing was graded. v1 scoring lands in aux-audit 0.2.0.
  Migrating a v0 spec:  python3 schemas/migrate-v0-to-v1.py your-spec.yaml
  Background:           schemas/MIGRATION.md, trustkit#10

Detection is two markers — mandate or spec_version — checked before validation, so a version mismatch can never produce a field error. An invalid v0 spec still gets its field errors; the shim swallows nothing it should not, and there is a test asserting exactly that.

Cost, measured rather than estimated

#10 called the swap "aux-audit v0.2, not a patch". For the file swap that was wrong, and the correction is recorded on the Issue:

	tests
v1 dropped in, no CLI change	5/34
+ spec.ts repointed at agent-spec.v0.yaml	32/34
+ the two tests reading the schema by name	34/34

This PR adds four more tests for the shim: 38/38.

Linked Issue

Advances #10; does not close it. Scoring v1 is still open — aux.H01 and aux.H03 read spec.autonomy today, and under v1 they become "does every non-autonomous action name an enforcing mechanism". Better question, different computation, aux-audit 0.2.0.

Type

• New pattern
• New gap
• Teardown
• Framework edit (must include rationale, ID migration note if renamed, updated examples)
• Schema fix
• Doc fix / typo / link
• Other

Migration note: v0.1.0 is not deleted, not renamed in place, and not stopped from working. It moves to agent-spec.v0.yaml, keeps its own header explaining what replaced it, and remains what the shipped CLI validates against. Anything written against v0 keeps scoring identically. schemas/MIGRATION.md carries the field-by-field mapping.

Contribution bar — checklist

• I've read CONTRIBUTING.md.
• If this introduces or renames an ID, I opened a debate Issue first. — [debate] agent-spec v1: per-action mandate with enforced_by, replacing the autonomy label #10, opened, argued and decided before any of this was written.
• If this adds a pattern, it has a diagram, a runnable example, and an anti-pattern. — n/a.
• If this adds a gap, it has a reproducible scenario and references a heuristic or trust stage. — n/a.
• CI passes (schema validation, link check). — 38/38 tests, yamllint clean with zero warnings, check:schemas clean, check-coverage.py 12/12, links resolve, and v1 verified as a valid draft 2020-12 schema by Draft202012Validator.check_schema.
• No emoji in code or schemas. — the incoming v0 header used a warning glyph; removed.
• Short sentences. Named things over adjectives.

One config change worth flagging

yamllint's colons rule is disabled. v1 aligns its $ref columns deliberately:

observe:   { $ref: "#/$defs/control" }
interrupt: { $ref: "#/$defs/control" }
approve:   { $ref: "#/$defs/control" }

That reads better than the unaligned form, and leaving thirteen warnings on every CI run would cost more than the rule is worth. Everything else stays strict.

Out of scope

• Scoring v1 — see Linked Issue.
• validate.py — in fix(schemas): brain-spec used the wrong ID namespace; add a cross-schema check #12, which also fixes a brain-spec ID mismatch it caught. The two PRs touch different files and compose; fix(schemas): brain-spec used the wrong ID namespace; add a cross-schema check #12 first is the tidier order, since its validator recognises agent-spec.v0.yaml as the frozen format and checks v1 as real JSON Schema.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MhpqWEvwKp7NrmJfdXYq4M

---

Generated by Claude Code