veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
3.1 KiB
kind, status
| kind | status |
|---|---|
| guide | active |
Fleet Role Classes and Authority
A fleet role class is a machine identity resolved from the persona library. Resolution uses the
canonical class before consulting the baseline fleet/roles/ and operator fleet/roles.local/
layers. A readable role contract is required; an index entry alone is not semantic success.
Canonicalization
Only these legacy class aliases are recognized:
| Requested class | Canonical class |
|---|---|
implementer |
code |
reviewer |
review |
operator-interaction |
interaction |
No other alias is inferred. In particular, worker, analyst, and canary are custom classes only
when an operator supplies a readable contract for that exact class. Tess and Ultron are instance
names, not classes. agents[].alias is display-only and cannot grant authority.
Canonicalization happens before role lookup. For example, requesting implementer resolves
code.md; a separate roles.local/implementer.md cannot redefine the legacy alias. A canonical
roles.local/code.md still overrides the baseline roles/code.md contract.
Protected authority
Protected authority is immutable metadata derived only from canonical class. Role prose, instance name, display alias, tool policy, runtime, and custom role files cannot grant it.
| Canonical class | Granted authority | Explicit limits |
|---|---|---|
merge-gate |
Sole approve-to-land and merge authority | No authority is inferred by similarly named custom roles or policies. |
validator |
May issue a validation certificate | Cannot approve-to-land or merge. |
orchestrator |
May orchestrate, manage topology, and issue leases | Cannot approve-to-land or merge. |
team-leader |
May use orchestrator-leased capacity | Cannot issue leases or mutate roster, configuration, credentials, or merge state. |
interaction |
Request and status surface | Cannot orchestrate, issue leases, mutate roster/configuration, or merge. |
| all other classes | No protected authority implicitly | Custom contracts do not acquire protected powers from prose. |
Roster-v2 semantic validation requires a protected class and its canonical tool policy to match. It
also rejects an unprotected class paired with a protected tool policy. The legacy tool-policy name
operator-interaction canonicalizes to interaction.
This mapping describes authority metadata only. Lease issuance, validation-certificate storage or workflow, lifecycle reconciliation, credentials, roster mutation, and merge execution are outside this resolver contract.