stack/docs/scratchpads/758-fleet-config-docs-ia-checklist.md

#758 Fleet configuration documentation IA acceptance checklist

Scope: M0 planning gate for issue #758. This checklist defines required documentation outcomes; it does not authorize source, schema, role, example, systemd, or live-fleet changes.

Acceptance states

Use required, deferred, or complete. A deferred item requires a target milestone and rationale. M5 cannot exit with a required item incomplete.

Path	Purpose	Owner milestone	Required evidence	State
docs/PRD.md	Normative requirements, scope, authority, lifecycle, migration, risks, and acceptance criteria	M0	Approved requirements PR linked to #758	required
docs/TASKS.md	M0–M5 one-card/one-PR DAG and review gates	M0	Every delivery card maps to acceptance criteria and dependencies	required
docs/fleet/README.md	Fleet configuration entry point and operator decision tree	M5	Links all accepted fleet-config pages and passes link validation	required
docs/fleet/concepts/desired-vs-observed-state.md	Desired, generated, and observed state boundaries	M5	Matches lifecycle contract and status JSON	required
docs/fleet/concepts/identity-class-runtime.md	Stable identity, alias, class, runtime/provider/model policy	M5	Matches executable schema and shared role resolver	required
docs/fleet/concepts/role-authority-and-leases.md	Authority matrix and bounded capacity leases	M1	Independently reviewed against role contracts	required
docs/fleet/concepts/generated-env-launch-chain.md	.env.generated, .env.local, quarantine, and unit/launcher chain	M2	Security review and launch-chain tests linked	required
docs/fleet/reference/roster-v2.schema.json	Published executable schema artifact	M1	Schema/parser parity suite consumes this artifact	required
docs/fleet/reference/roster-v2-fields.md	Every field, default, constraint, compatibility rule, and example	M1	Field-by-field parity review	required
docs/fleet/reference/cli.md	Config, CRUD, lifecycle commands, JSON shapes, and exit codes	M3	CLI contract tests and examples linked	required
docs/fleet/reference/role-classes.md	Required/optional classes, aliases, and powers	M1	Existing resolver validates every documented class	required
docs/fleet/reference/lifecycle-transitions.md	Complete enabled/desired/observed transition table	M3	Lifecycle and reboot tests linked	required
docs/fleet/reference/status-and-drift.md	Drift planes, readiness, ownership proof, and safe output	M3	Golden JSON/status tests linked	required
docs/fleet/how-to/create-update-delete-agent.md	Safe CRUD and dry-run workflows	M2	Fresh and idempotent examples validate	required
docs/fleet/how-to/start-stop-restart.md	Transient versus persisted lifecycle operations	M3	Matches transition tests	required
docs/fleet/how-to/configure-tess-interaction.md	Configurable interaction instance, not hardcoded identity	M5	Example validates through shared resolver	required
docs/fleet/how-to/configure-ultron-validator.md	Validator instance without merge authority	M5	Example validates and authority review passes	required
docs/fleet/how-to/customize-roles.md	Baseline plus roles.local resolution and policy	M1	No parallel resolver described or implemented	required
docs/fleet/operations/reconcile-and-recover.md	Plan/apply, partial failure, recovery, and rollback	M3	Failure-injection evidence linked	required
docs/fleet/operations/env-quarantine.md	Legacy key inventory and secret-safe disposition	M2	Security tests prove no values are emitted	required
docs/fleet/operations/systemd-tmux-troubleshooting.md	Exact local targeting and non-destructive diagnostics	M3	Named/default socket and unmanaged-session tests linked	required
docs/fleet/operations/backup-restore.md	Generation backup and rollback	M4	Migration rollback drill linked	required
docs/fleet/operations/upgrade-assets.md	Source/installed asset drift and update behavior	M5	Package/update test linked	required
docs/fleet/migration/v1-to-v2.md	Normative field mapping and stopped-state preservation	M4	Migration fixtures and canary evidence linked	required
docs/fleet/migration/example-profile-disposition.md	Disposition of every shipped example/profile	M1	Inventory has no unresolved item at M1 exit	required
docs/fleet/migration/legacy-class-aliases.md	Deterministic aliases and manual-review classes	M1	Alias/unknown-role tests linked	required
docs/SITEMAP.md	Navigation index	M5	Link checker passes with all required pages	required

Cross-cutting acceptance checks

• Every documented command has stable text and JSON behavior plus an exit-code contract.
• Every documented schema field is accepted by the executable validator, and every accepted field is documented.
• Examples use synthetic non-secret values only.
• Generated files are explicitly labeled non-authoritative and rebuildable.
• Gateway-backed mosaic agent records are documented as a separate control plane; no implicit convergence is promised.
• Local M1–M5 scope excludes remote/SSH reconciliation, connector mutation, secret-reference schema, arbitrary commands/channels, and UI/gateway config convergence.
• Independent correctness, security, and validator evidence is linked before M5 acceptance.
• Documentation links and formatting pass repository gates.