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

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 declared executable production parser/resolver path recorded by the disposition inventory; versioned v1 fixtures are not forced through the v2 compiler.
• 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 documentation validation verifies links, schema/example validation, and that checklist rows have owner/evidence or an explicit approved-existing deferral.

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.