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`.
51 lines
3.1 KiB
Markdown
51 lines
3.1 KiB
Markdown
---
|
|
kind: guide
|
|
status: 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.
|