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`.
2.6 KiB
kind, status
| kind | status |
|---|---|
| guide | active |
Legacy Fleet Class Aliases
Fleet class compatibility is intentionally narrow. The shared resolver accepts exactly three legacy class names and converts them to canonical classes before persona lookup:
| Legacy value | Canonical value | Migration action |
|---|---|---|
implementer |
code |
Replace class and tool-policy references with code. |
reviewer |
review |
Replace class and tool-policy references with review. |
operator-interaction |
interaction |
Replace class and roster-v2 tool-policy references with interaction. The legacy service artifact remains compatible. |
Alias support preserves existing inputs while provisioning and typed semantic output use canonical identities. Requested and canonical class values remain separately observable during semantic validation.
Lookup and override behavior
Canonicalization precedes baseline and roles.local lookup. A legacy-named override such as
roles.local/implementer.md is not a separate authority and is not selected for an implementer
request. Customize the canonical role instead, for example roles.local/code.md.
The compatibility file operator-interaction.md remains shipped, but interaction is the canonical
role class. Tess is an example display name only.
Unresolved and custom classes
No names are inferred from historical usage, instance names, or similar wording. worker, analyst,
canary, Tess, and Ultron are not aliases. An otherwise unknown class is accepted only if the shared
resolver can read an actual baseline or roles.local contract for that exact class. A LIBRARY.md
row without a readable contract fails semantic validation.
Custom classes receive no protected authority implicitly. Protected class/tool-policy mismatches fail closed.
Retirement guidance
New configuration should emit canonical values. Existing inputs may use the three aliases during the compatibility period, but operators should migrate class and tool-policy fields together. Do not create new legacy-named role overrides; move their intended content to the canonical filename and validate the roster/profile before removing the old artifact.