87 lines
8.8 KiB
Markdown
87 lines
8.8 KiB
Markdown
# 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.
|