mosaicstack/stack
1
0
Fork 0
Code Issues 74 Pull Requests 1 Actions Packages Projects Releases 15 Wiki Activity

docs(fleet): add operator configuration guide #789

Open
jason.woltje wants to merge 9 commits from docs/758-fleet-config-operator-docs into main
pull from: docs/758-fleet-config-operator-docs
merge into: mosaicstack:main
Conversation 0 Commits 9 Files Changed 25 +1554 -78
jason.woltje commented 2026-07-16 14:29:26 +00:00
Owner
Copy Link

Scope

Delivers FCM-M5-001 documentation, examples, deterministic documentation validation, and tracking for parent #758. Parent #758 remains open.

M5 checklist evidence

Baseline contracts

  • Roster desired-state authority, derived/observed state, lifecycle, generated/local boundary, authority separation, and local-tmux exclusions: docs/PRD.md, docs/fleet/README.md, and docs/fleet/concepts/.
  • M0-M5 DAG and exact M4-001 completion evidence: docs/TASKS.md.
  • Shipped example/profile/service disposition: docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md and docs/fleet/migration/example-profile-disposition.md.

Accepted documentation IA

  • Entry point and decision tree: docs/fleet/README.md.
  • Concepts: docs/fleet/concepts/desired-vs-observed-state.md, identity-class-runtime.md, role-authority-and-leases.md, and generated-env-launch-chain.md.
  • Schema and reference: docs/fleet/reference/roster-v2.schema.json, roster-v2-fields.md, cli.md, role-classes.md, lifecycle-transitions.md, status-and-drift.md, and generated-env-boundary.md.
  • Operator how-tos: CRUD, one-shot lifecycle, configurable interaction/validator instances, and role customization under docs/fleet/how-to/.
  • Operations: reconcile/recover, quarantine, systemd/tmux troubleshooting, backup/restore boundaries, and upgrade-asset hold under docs/fleet/operations/.
  • Migration: v1-to-v2 preview, disposition, and alias rules under docs/fleet/migration/.
  • Navigation: docs/SITEMAP.md.
  • Closure/deferral evidence: docs/reports/documentation/758-fleet-config-ia-closure.md and docs/reports/deferred/758-fleet-config-deferrals.md.

Deterministic validation

  • packages/mosaic/src/fleet/fleet-documentation.spec.ts verifies every accepted IA page exists, local fleet-book/sitemap links resolve, the canonical v2 example validates through the production parser and shared semantic resolver, and the example contains no sensitive-looking keys, arbitrary command override, or hardcoded Tess/Ultron identity.
  • docs/fleet/examples/roster-v2.yaml is the generic canonical example.

Validation

  • Focused fleet contract suites: 7 files, 195 tests passed.
  • pnpm format:check: passed.
  • pnpm lint: 23 tasks passed.
  • pnpm typecheck: 42 tasks passed.
  • pnpm test: 43 tasks passed; @mosaicstack/mosaic 61 files / 1,045 tests passed.
  • Framework sanitization gate: passed.
  • Resident-budget gate: passed.
  • git diff --check: passed.

Explicit holds and boundaries

  • FCM-M4-002 remains unchecked and held: no executable/live cutover, canary, stopped-state migration, rollback, orphan migration, deployment, systemd/tmux/session, or generated-projection action was implemented or executed.
  • FCM-M5-002 remains unchecked and held: no asset-drift implementation, rolling canary, validator certificate, merge-gate approval, or parent-issue closure is claimed.
  • Independent exact-head review and terminal-green PR CI remain post-PR gates.
  • roster.yaml remains the sole writable desired-state authority; generated state remains derived/observed.
  • mos-comms remains temporary and is not documented as permanent architecture.
  • No credentials, sensitive values, privileged command content, remote reconciliation, connector mutation, or product mutation is introduced.
  • This PR must not be self-merged.

Parent: #758

## Scope Delivers FCM-M5-001 documentation, examples, deterministic documentation validation, and tracking for parent #758. Parent #758 remains open. ## M5 checklist evidence ### Baseline contracts - Roster desired-state authority, derived/observed state, lifecycle, generated/local boundary, authority separation, and local-tmux exclusions: `docs/PRD.md`, `docs/fleet/README.md`, and `docs/fleet/concepts/`. - M0-M5 DAG and exact M4-001 completion evidence: `docs/TASKS.md`. - Shipped example/profile/service disposition: `docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md` and `docs/fleet/migration/example-profile-disposition.md`. ### Accepted documentation IA - Entry point and decision tree: `docs/fleet/README.md`. - Concepts: `docs/fleet/concepts/desired-vs-observed-state.md`, `identity-class-runtime.md`, `role-authority-and-leases.md`, and `generated-env-launch-chain.md`. - Schema and reference: `docs/fleet/reference/roster-v2.schema.json`, `roster-v2-fields.md`, `cli.md`, `role-classes.md`, `lifecycle-transitions.md`, `status-and-drift.md`, and `generated-env-boundary.md`. - Operator how-tos: CRUD, one-shot lifecycle, configurable interaction/validator instances, and role customization under `docs/fleet/how-to/`. - Operations: reconcile/recover, quarantine, systemd/tmux troubleshooting, backup/restore boundaries, and upgrade-asset hold under `docs/fleet/operations/`. - Migration: v1-to-v2 preview, disposition, and alias rules under `docs/fleet/migration/`. - Navigation: `docs/SITEMAP.md`. - Closure/deferral evidence: `docs/reports/documentation/758-fleet-config-ia-closure.md` and `docs/reports/deferred/758-fleet-config-deferrals.md`. ### Deterministic validation - `packages/mosaic/src/fleet/fleet-documentation.spec.ts` verifies every accepted IA page exists, local fleet-book/sitemap links resolve, the canonical v2 example validates through the production parser and shared semantic resolver, and the example contains no sensitive-looking keys, arbitrary command override, or hardcoded Tess/Ultron identity. - `docs/fleet/examples/roster-v2.yaml` is the generic canonical example. ## Validation - Focused fleet contract suites: 7 files, 195 tests passed. - `pnpm format:check`: passed. - `pnpm lint`: 23 tasks passed. - `pnpm typecheck`: 42 tasks passed. - `pnpm test`: 43 tasks passed; `@mosaicstack/mosaic` 61 files / 1,045 tests passed. - Framework sanitization gate: passed. - Resident-budget gate: passed. - `git diff --check`: passed. ## Explicit holds and boundaries - FCM-M4-002 remains unchecked and held: no executable/live cutover, canary, stopped-state migration, rollback, orphan migration, deployment, systemd/tmux/session, or generated-projection action was implemented or executed. - FCM-M5-002 remains unchecked and held: no asset-drift implementation, rolling canary, validator certificate, merge-gate approval, or parent-issue closure is claimed. - Independent exact-head review and terminal-green PR CI remain post-PR gates. - `roster.yaml` remains the sole writable desired-state authority; generated state remains derived/observed. - `mos-comms` remains temporary and is not documented as permanent architecture. - No credentials, sensitive values, privileged command content, remote reconciliation, connector mutation, or product mutation is introduced. - This PR must not be self-merged. Parent: #758
jason.woltje added 1 commit 2026-07-16 14:29:27 +00:00
docs(fleet): add operator configuration guide
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
0aee2c0981 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-07-16 15:05:00 +00:00
fix(fleet): correct operator documentation validation
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
17aa94ca1a 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-07-16 15:54:52 +00:00
fix(fleet): close documentation safety gaps
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
0db300dce5 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-07-16 16:23:09 +00:00
test(fleet): normalize env wrapper options
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
22ad7dbbed 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-07-16 16:42:33 +00:00
test(fleet): harden wrapped command validation
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
0b106651f8 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-07-16 17:36:05 +00:00
test(mosaic): close fleet command parser gaps
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
587ac423c2 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-07-16 18:10:53 +00:00
test(fleet): harden documentation command scanner
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
30fad7a2b3 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-07-16 18:46:16 +00:00
test(fleet): recognize env argv0 operands
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
42c7980dfb 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-07-16 19:33:26 +00:00
test(fleet): harden static command parsing
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
862dbd5204 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
All checks were successful
ci/woodpecker/pr/ci Pipeline was successful
Details
This pull request can be merged automatically.
This branch is out-of-date with the base branch
You are not authorized to merge this pull request.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin docs/758-fleet-config-operator-docs:docs/758-fleet-config-operator-docs
git checkout docs/758-fleet-config-operator-docs
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#789
Delete Branch "docs/758-fleet-config-operator-docs"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?