# 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.
