# Fleet Configuration Management — Documentation IA Acceptance Checklist **Issue:** #758 · **Scope:** M0 documentation gate for the local fleet declarative-configuration program. This checklist is an acceptance contract for documentation and examples. It does not authorize schema, runtime, systemd, role, profile, or live-fleet changes. An item is complete only when its named artifact exists, is linked from the fleet documentation entry point, and its evidence is recorded in the M0 task/PR. ## M0 baseline acceptance - [ ] `docs/PRD.md` states the roster as desired-state SSOT; generated environment, systemd, tmux, and heartbeat artifacts as non-authoritative projections; and fail-closed handling of unsupported or quarantined legacy input. - [ ] `docs/PRD.md` defines the required classes and authority boundary: `validator` certifies but does not merge; `merge-gate` remains sole approve-to-land/merge authority; `team-leader` capacity is lease-bounded; `interaction` is request/status only; instance names such as Tess and Ultron remain configurable. - [ ] `docs/PRD.md` defines local lifecycle semantics for `enabled`, persisted desired state, and observed state, including stopped-state preservation through migration, apply, and reboot. - [ ] `docs/PRD.md` defines the generated-env/local-override boundary, explicitly denies arbitrary command overrides in M1–M5, and requires key-name/hash-only quarantine diagnostics. - [ ] `docs/PRD.md` identifies the M1–M5 local-tmux scope and excludes remote reconciliation, connector mutation, secret references, arbitrary commands/channels, gateway convergence, and UI configuration storage. - [ ] `docs/TASKS.md` contains the complete M0–M5 one-card/one-PR dependency DAG for #758 with agent tier, branch, dependency, estimate, and evidence expectations. - [ ] `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` classifies every current shipped fleet example, profile, and service preset before M1 implementation starts. ## Required documentation IA for M1–M5 | Path | Minimum content | Delivery gate | | ------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------- | | `docs/fleet/README.md` | Fleet configuration entry point, desired-vs-observed decision tree, link map | M5 | | `docs/fleet/concepts/desired-vs-observed-state.md` | SSOT/projection model, drift, generation and ownership | M5 | | `docs/fleet/concepts/identity-class-runtime.md` | Stable name, display alias, class, runtime/provider/model separation | M5 | | `docs/fleet/concepts/role-authority-and-leases.md` | Required roles, validator/merge-gate separation, lease limits | M5 | | `docs/fleet/concepts/generated-env-launch-chain.md` | Generated/local files, precedence, quarantine and non-shell parsing | M5 | | `docs/fleet/reference/roster-v2.schema.json` | Executable v2 structural contract | M1 | | `docs/fleet/reference/roster-v2-fields.md` | Every field, default, constraint, compatibility behavior and examples | M1 | | `docs/fleet/reference/cli.md` | `config`, `agent`, lifecycle, plan/apply, JSON and exit-code contracts | M2–M3 | | `docs/fleet/reference/role-classes.md` | Canonical classes, aliases, authority matrix and instance-name rule | M1 | | `docs/fleet/reference/lifecycle-transitions.md` | Create/start/stop/restart/apply/reboot/rollback transition table | M3 | | `docs/fleet/reference/status-and-drift.md` | Desired/observed/managed state, orphans, revision mismatch, doctor output | M3 | | `docs/fleet/how-to/create-update-delete-agent.md` | Safe CRUD, expected generation, dry-run and rollback | M2 | | `docs/fleet/how-to/start-stop-restart.md` | Persisted versus one-shot lifecycle actions | M3 | | `docs/fleet/how-to/configure-tess-interaction.md` | Configurable interaction instance; no hardcoded identity | M5 | | `docs/fleet/how-to/configure-ultron-validator.md` | Configurable validator instance; no merge authority | M5 | | `docs/fleet/how-to/customize-roles.md` | Existing baseline + `roles.local` resolution and validation | M1 | | `docs/fleet/operations/reconcile-and-recover.md` | Plan/apply failure recovery, generation lock and canary rollout | M3 | | `docs/fleet/operations/env-quarantine.md` | Legacy-key inventory, private quarantine and redaction behavior | M2 | | `docs/fleet/operations/systemd-tmux-troubleshooting.md` | Socket ambiguity, ownership proof, systemd/tmux drift | M3 | | `docs/fleet/operations/backup-restore.md` | Roster/projection backup and rollback boundaries | M4 | | `docs/fleet/operations/upgrade-assets.md` | Source-vs-installed asset revision detection and safe refresh | M5 | | `docs/fleet/migration/v1-to-v2.md` | Normative field map, observed-state preservation and rollback | M4 | | `docs/fleet/migration/example-profile-disposition.md` | Final disposition of every shipped example/profile | M1–M4 | | `docs/fleet/migration/legacy-class-aliases.md` | Alias, unresolved-class, and retirement rules | M1 | ## PRD acceptance-criteria mapping | PRD acceptance criterion | Owning card(s) | Required evidence | | ------------------------------------------------------------ | ---------------------------------- | --------------------------------------------------------------------------------------- | | `AC-FCM-01` schema, semantic validation, canonical rendering | FCM-M1-001, FCM-M1-002 | YAML/JSON positive/negative and schema/parser/resolver parity tests | | `AC-FCM-02` deterministic plan and no-mutation check | FCM-M3-001 | Stable JSON/exit-code and desired-versus-observed fixture tests | | `AC-FCM-03` safe generation-guarded CRUD | FCM-M2-002 | Create/update/delete idempotency, expected-generation, dry-run, and recovery tests | | `AC-FCM-04` generated/local boundary and quarantine | FCM-M2-001 | Launch-chain, shadow, injection, redaction, and forbidden-key tests | | `AC-FCM-05` lifecycle/reconcile/socket/drift safety | FCM-M3-001, FCM-M3-002 | Isolated systemd/tmux, stopped-state, orphan, socket, and rollback evidence | | `AC-FCM-06` v1 migration and example/profile disposition | FCM-M4-001, FCM-M4-002, FCM-M1-003 | Preview/canary/rollback fixture plus executable disposition inventory | | `AC-FCM-07` authority and lease boundaries | FCM-M1-002 | Role/authority/lease denial tests and resolved role contracts | | `AC-FCM-08` documentation and final release gate | FCM-M5-001, FCM-M5-002 | Checklist closure, link/example validation, reviews, certificate, and terminal-green CI | ## Cross-cutting evidence gates - [ ] Every retained or migrated YAML/JSON example, profile, and service preset validates through the same executable schema and shared baseline-plus-`roles.local` resolver used by the CLI. - [ ] Every retired example/profile/service preset has a replacement link and deprecation note; no unresolved legacy class or tool-policy alias remains silently shipped. - [ ] Documentation examples contain no secret values, arbitrary command override, or product-hardcoded Tess/Ultron identity. - [ ] CLI snippets distinguish local fleet desired-state commands from the separate gateway-backed `mosaic agent` catalog. - [ ] Migration, quarantine, lifecycle, status, and troubleshooting documentation state that values of legacy sensitive keys are never printed. - [ ] M5 release review verifies links, schema/example validation, and that all checklist rows have owner/evidence or an explicit approved deferral.