17aa94ca1a
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
86 lines
5.0 KiB
Markdown
86 lines
5.0 KiB
Markdown
# 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
|
|
|
|
- [x] Loaded repository/global delivery and documentation contracts.
|
|
- [x] Verified `origin/main` is exact required base and created isolated worktree.
|
|
- [x] Tracking updated first.
|
|
- [x] Checklist mapped and docs authored.
|
|
- [x] Validation green.
|
|
- [x] Review/remediation complete.
|
|
- [x] Commit, queue guard, push, PR #789.
|
|
- [x] 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.
|