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`.
Fleet Configuration Management
This book documents the local roster-v2 desired-state control plane delivered under issue #758. The normative requirements are the FCM section of the repository PRD, not the older fleet-suite or observability planning pages.
Authority boundary
<MOSAIC_HOME>/fleet/roster.yaml is the sole writable desired-state authority for local fleet membership, launch policy, and persisted lifecycle. Generated environment files, systemd enablement, tmux sessions, heartbeat files, and status output are derived or observed. Rebuild projections from the roster; never edit them as desired state.
This control plane is local tmux/systemd only. Remote/SSH entries and connectors are inventory, not reconciliation targets. Arbitrary commands, channels, secret references, gateway catalog convergence, and UI configuration storage are outside this workstream. mos-comms is temporary transport glue, not permanent fleet architecture.
Choose the right workflow
- Need to inspect intent? Read the roster and use mosaic fleet get; see desired versus observed state.
- Need to inspect reality? Use
statusordoctor; useverifyfor a strict non-zero drift/ownership gate. These commands do not repair anything. - Need to change membership or persisted policy? Use generation-guarded
plan,create,update, ordelete; see safe CRUD. - Need a one-time runtime action? Use
start,stop, orrestart. These do not change persisted desired state. - Need convergence? Review apply --dry-run, resolve blockers, then use
applywith the same current generation; see reconcile and recover. - Need v1 migration evidence? Use preview only. Cutover, canary, and rollback remain held for FCM-M4-002.
- Need the gateway-backed agent catalog? That is the separate mosaic agent surface, not local fleet desired state.
Concepts
- Desired versus observed state
- Identity, class, runtime, provider, and model
- Role authority and leases
- Generated environment launch chain
Operator how-to
- Create, inspect, update, and delete
- Start, stop, restart, and reconcile
- Configure an interaction instance
- Configure a validator instance
- Customize roles
Operations and recovery
- Reconcile and recover
- Environment quarantine
- Systemd/tmux troubleshooting
- Backup and restore boundary
- Upgrade and asset-drift hold
Reference and migration
- Roster v2 fields · executable JSON Schema · validated example
- CLI and exit codes
- Role classes
- Lifecycle transitions
- Status and drift
- Generated environment boundary
- v1-to-v2 preview
- Example/profile dispositions
- Legacy class aliases
Acceptance evidence and holds
- M0/M5 IA checklist
- Legacy example/profile inventory
- M5 closure evidence
- Approved-existing deferrals and live-action holds
The canonical publishing source remains this repository. This card does not publish externally, run a migration, operate a live fleet, or close parent issue #758.