# 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 M5 closure report and linked deferral evidence.

## M0 baseline acceptance

- [x] `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.
- [x] `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.
- [x] `docs/PRD.md` defines local lifecycle semantics for `enabled`, persisted desired state, and
      observed state, including stopped-state preservation through migration, apply, and reboot.
- [x] `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.
- [x] `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.
- [x] `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.
- [x] `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

- [x] Every retained or migrated YAML/JSON example, profile, and service preset validates through the
      same declared executable production parser/resolver path recorded by the disposition inventory;
      versioned v1 fixtures are not forced through the v2 compiler.
- [x] Every retired example/profile/service preset has a replacement link and deprecation note; no
      unresolved legacy class or tool-policy alias remains silently shipped.
- [x] Documentation examples contain no secret values, arbitrary command override, or product-hardcoded
      Tess/Ultron identity.
- [x] CLI snippets distinguish local fleet desired-state commands from the separate gateway-backed
      `mosaic agent` catalog.
- [x] Migration, quarantine, lifecycle, status, and troubleshooting documentation state that values of
      legacy sensitive keys are never printed.
- [x] M5 documentation validation verifies required IA paths, local file and heading-fragment links,
      the canonical roster through the production compiler/resolver, and fenced/canonical-example
      safety checks.
- [ ] FCM-M5-001 does not deterministically assert owner/evidence/deferral metadata for every checklist
      row. Closure and deferral reports provide human-reviewable evidence only; broader assertion
      coverage remains unclaimed.

## Held downstream gates

These unchecked items are intentionally outside FCM-M5-001 and are not authorized by this checklist:

- [ ] FCM-M4-002 executes and evidences live cutover, canary, stopped-state preservation, and rollback.
- [ ] FCM-M5-002 completes independent exact-head review and issues the validator certificate.
- [ ] The exact PR head reaches terminal-green CI after independent review.
