stack/docs/scratchpads/fcm-m5-001-fleet-config-operator-docs.md

FCM-M5-001 — Fleet configuration operator documentation

• Task: FCM-M5-001
• Issue: #758
• Branch: docs/758-fleet-config-operator-docs
• Exact base: 9745bc3f29c26b021a478b7ad03cfb494f6c9de3 (tree 4da210da9a71b035130d4160a4a2e691bdfde2da)

Objective

Deliver the accepted fleet documentation information architecture, operator workflows, operations and migration references, comprehensive contract documentation, and deterministic link/example validation without live fleet action or product mutation.

Scope and constraints

• Documentation, examples, documentation validation, and tracking only.
• roster.yaml remains the sole writable desired-state authority; generated state is derived/observed.
• No M4-002 implementation or execution; no canary, migration, rollback, deployment, systemd/tmux/session, generated projection, or product mutation.
• mos-comms is temporary and is not permanent architecture.
• Parent issue #758 remains open through M5.
• No credentials, sensitive values, or privileged command content.

Plan

1. Update tracking first with exact M4-001 evidence and mark M5-001 in progress.
2. Map the M0 checklist and current implementation behavior to documentation pages.
3. Author operator, operations, migration, schema/reference, recovery, troubleshooting, and security/authority docs.
4. Add or extend deterministic documentation/link/example validation if required, red-first.
5. Run repository documentation, link, example, and relevant package checks; review and remediate.
6. Commit, queue-guard, push one branch, and open one wrapper-created PR; stop for independent review.

Budget

• Task estimate: 24K.
• Working cap: stay within the card estimate by parallelizing read-only discovery and limiting edits to checklist-required artifacts.

Progress checkpoints

• Loaded repository/global delivery and documentation contracts.
• Verified origin/main is exact required base and created isolated worktree.
• Tracking updated first.
• Checklist mapped and docs authored.
• Validation green.
• Review/remediation complete.
• Commit, queue guard, push, PR #789.
• Rejected exact-head RoR findings repaired on a new descendant commit candidate.
• New exact-head review and CI after repair push.

Tests and verification

• Red-first documentation validator initially failed for the absent fleet entry point and canonical example, then passed after the IA and example were added.

• pnpm --filter @mosaicstack/mosaic exec vitest run src/fleet/roster-v2.spec.ts src/fleet/example-profile-dispositions.spec.ts src/fleet/fleet-documentation.spec.ts src/fleet/v1-v2-migration.spec.ts src/fleet/generated-env-boundary.spec.ts src/fleet/fleet-agent-crud.spec.ts src/fleet/fleet-reconciler.spec.ts — 7 files, 195 tests passed after building workspace dependencies.

• pnpm format:check — passed.

• pnpm lint — 23 tasks passed.

• pnpm typecheck — 42 tasks passed.

• pnpm test — 43 tasks passed; @mosaicstack/mosaic contributed 61 files and 1,045 tests.

• bash packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh — passed.

• bash packages/mosaic/framework/tools/quality/scripts/check-resident-budget.sh — passed.

• git diff --check — passed before final review.

• Independent staged-snapshot review identified four documentation/validation blockers: reboot safety, heartbeat observation, migration failure envelope, and example-scan coverage. All were remediated; focused rereview approved the staged remediations with no blockers. Exact committed-head review remains a post-PR gate.

• Post-remediation @mosaicstack/mosaic lint/typecheck passed; package test passed 61 files / 1,045 tests; sanitization and resident-budget gates passed again.

• Post-PR exact-head RoR on rejected head 0aee2c09819fd06e28f927384ea56fa2ef374edf identified five blockers: update-lifecycle overclaim, missing explicit fleet validate gap, fragment-blind link validation, unsupported checklist-evidence claim, and insufficient example safety validation. Red-first regressions failed before implementation for missing-heading, privileged-command, and credential-format fixtures. Repairs now preserve/document implementation truth, validate heading fragments, narrow checklist claims, and scan fenced/canonical examples for common credential formats and privileged commands without printing fixture values.

• Repair-focused fleet contracts: 7 files, 192 tests passed after review remediation; documentation validator contributed 11 tests. Full gates passed: format; lint 23/23; typecheck 42/42; test 43/43 tasks with @mosaicstack/mosaic 61 files / 1,052 tests; sanitization; resident budget; and git diff --check. New exact-head review/CI remain pending until the repair commit is pushed.

Risks/blockers

• Checklist may include behavior intentionally deferred to M4-002/M5-002; such items must be recorded as approved-existing holds rather than claimed delivered.
• Commands/examples must remain non-live and avoid privileged/sensitive content.

Final evidence

• Pending.