stack/docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md

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 and profile 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 and profile validates through the same executable schema and shared baseline-plus-roles.local resolver used by the CLI.
• Every retired example/profile has a replacement link and deprecation note; no unresolved legacy class 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.