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

docs(fleet): add operator configuration guide #789

Merged
jason.woltje merged 12 commits from docs/758-fleet-config-operator-docs into main 2026-07-20 05:22:27 +00:00
Conversation 2 Commits 12 Files Changed 44
+1870 -366
jason.woltje commented 2026-07-16 14:29:26 +00:00
Owner
Copy Link
Copy Source

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
ci/woodpecker/pr/ci Pipeline was successful
Details
0aee2c0981 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje added 1 commit 2026-07-16 15:05:00 +00:00
fix(fleet): correct operator documentation validation
ci/woodpecker/pr/ci Pipeline was successful
Details
17aa94ca1a 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje added 1 commit 2026-07-16 15:54:52 +00:00
fix(fleet): close documentation safety gaps
ci/woodpecker/pr/ci Pipeline was successful
Details
0db300dce5 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje added 1 commit 2026-07-16 16:23:09 +00:00
test(fleet): normalize env wrapper options
ci/woodpecker/pr/ci Pipeline was successful
Details
22ad7dbbed 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje added 1 commit 2026-07-16 16:42:33 +00:00
test(fleet): harden wrapped command validation
ci/woodpecker/pr/ci Pipeline was successful
Details
0b106651f8 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje added 1 commit 2026-07-16 17:36:05 +00:00
test(mosaic): close fleet command parser gaps
ci/woodpecker/pr/ci Pipeline was successful
Details
587ac423c2 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje added 1 commit 2026-07-16 18:10:53 +00:00
test(fleet): harden documentation command scanner
ci/woodpecker/pr/ci Pipeline was successful
Details
30fad7a2b3 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje added 1 commit 2026-07-16 18:46:16 +00:00
test(fleet): recognize env argv0 operands
ci/woodpecker/pr/ci Pipeline was successful
Details
42c7980dfb 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje added 1 commit 2026-07-16 19:33:26 +00:00
test(fleet): harden static command parsing
ci/woodpecker/pr/ci Pipeline was successful
Details
862dbd5204 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje commented 2026-07-17 22:57:08 +00:00
Author
Owner
Copy Link
Copy Source

VERIFIED REQUEST CHANGES — reviewer-of-record lane: independent current-main prospective-tree review; exact head 862dbd520498a31d2e3f19216e0d513bc6ce04eb; base main d3bf52898b6db2fc7845d4a29af4600973844443; merge-base 9745bc3f29c26b021a478b7ad03cfb494f6c9de3; prospective tree cb2d2aa8c772d630765c2e404134ee5af57d8521.

Blocking findings:

  1. packages/mosaic/src/fleet/fleet-documentation.spec.ts:138-525 implements a general shell parser (segmentation, quoting/escaping, tokenization, GNU env/command, recursive sh/bash -c, and su option semantics), violating the approved no-general-shell-parser boundary. Replace with the closed ConcreteCommand/Synopsis/DataProfile/InlineLiteral grammar model.
  2. packages/mosaic/src/fleet/fleet-documentation.spec.ts:527-570,872-887 scans only fenced blocks plus roster YAML and returns unconstrained heuristic string categories. Rendered inline-code spans and indented code blocks are omitted, so the required exactly-one closed classification is neither comprehensive nor closed. Raw HTML code containers and indented code must reject.
  3. docs/fleet/reference/cli.md:16-17,27-30 and docs/fleet/how-to/start-stop-restart.md:12 use [name]; accepted optional-agent notation is [].

Exact-tree evidence otherwise passed: focused Vitest 7 files / 300 tests, mosaic typecheck, lint, and git diff --check. Publish a blocker-only new head; no design approval, CI, review, or tree evidence transfers. Parent #758 remains open; M4-002/M5-002 and all live action remain held.

VERIFIED REQUEST CHANGES — reviewer-of-record lane: independent current-main prospective-tree review; exact head 862dbd520498a31d2e3f19216e0d513bc6ce04eb; base main d3bf52898b6db2fc7845d4a29af4600973844443; merge-base 9745bc3f29c26b021a478b7ad03cfb494f6c9de3; prospective tree cb2d2aa8c772d630765c2e404134ee5af57d8521. Blocking findings: 1. packages/mosaic/src/fleet/fleet-documentation.spec.ts:138-525 implements a general shell parser (segmentation, quoting/escaping, tokenization, GNU env/command, recursive sh/bash -c, and su option semantics), violating the approved no-general-shell-parser boundary. Replace with the closed ConcreteCommand/Synopsis/DataProfile/InlineLiteral grammar model. 2. packages/mosaic/src/fleet/fleet-documentation.spec.ts:527-570,872-887 scans only fenced blocks plus roster YAML and returns unconstrained heuristic string categories. Rendered inline-code spans and indented code blocks are omitted, so the required exactly-one closed classification is neither comprehensive nor closed. Raw HTML code containers and indented code must reject. 3. docs/fleet/reference/cli.md:16-17,27-30 and docs/fleet/how-to/start-stop-restart.md:12 use [name]; accepted optional-agent notation is [<name>]. Exact-tree evidence otherwise passed: focused Vitest 7 files / 300 tests, mosaic typecheck, lint, and git diff --check. Publish a blocker-only new head; no design approval, CI, review, or tree evidence transfers. Parent #758 remains open; M4-002/M5-002 and all live action remain held.
jason.woltje added 3 commits 2026-07-18 00:45:32 +00:00
test(fleet): close documentation code grammar bfa08e9651 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
test(fleet): close markdown scanner bypasses 1f8c5a6f0a 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
test(fleet): stabilize documentation surface scan
ci/woodpecker/pr/ci Pipeline was successful
Details
a39bafb8e3 
Co-Authored-By: Claude Opus 4.8 <[email protected]>
jason.woltje commented 2026-07-20 05:04:14 +00:00
Author
Owner
Copy Link
Copy Source

VERIFIED APPROVE — reviewer-of-record W-jarvis:reviewer; exact head a39bafb8e3a56e1e663ba8304f50bd17522e2896; exact base/current main 0582a8912b133a86849bea99903ea7431db28595; tree a7f1fcb0e4. Prior stale-head blockers independently verified closed: closed ConcreteCommand/Synopsis/DataProfile/InlineLiteral grammar only; exhaustive exactly-one classification with inline/indented/raw-HTML rejection; optional-agent notation []. Full prospective-tree review found no blockers. Validation: diff check; focused 7 files/214 tests; @mosaicstack/mosaic 61 files/1064 tests; root 43/43 tasks; package/root typecheck+lint; format; credential-pattern scan. Exact-head CI #1907 terminal success. Lane provenance: author jason.woltje; reviewer process W-jarvis:reviewer dispatched by W-jarvis:orchestrator; reviewer made no edits/provider mutations. Content-addressed RoR sha256 0ad2d3d1bd4f1afe360b521e9a2766495be344abec7ec399f7b7244fe6c9e193 (7482 bytes), locally re-hashed byte-exact by Mos. Parent #758 remains open; M4-002/M5-002 and every live action remain held.

VERIFIED APPROVE — reviewer-of-record W-jarvis:reviewer; exact head a39bafb8e3a56e1e663ba8304f50bd17522e2896; exact base/current main 0582a8912b133a86849bea99903ea7431db28595; tree a7f1fcb0e4dd6680a5c677a15f6380197aac08df. Prior stale-head blockers independently verified closed: closed ConcreteCommand/Synopsis/DataProfile/InlineLiteral grammar only; exhaustive exactly-one classification with inline/indented/raw-HTML rejection; optional-agent notation [<name>]. Full prospective-tree review found no blockers. Validation: diff check; focused 7 files/214 tests; @mosaicstack/mosaic 61 files/1064 tests; root 43/43 tasks; package/root typecheck+lint; format; credential-pattern scan. Exact-head CI #1907 terminal success. Lane provenance: author jason.woltje; reviewer process W-jarvis:reviewer dispatched by W-jarvis:orchestrator; reviewer made no edits/provider mutations. Content-addressed RoR sha256 0ad2d3d1bd4f1afe360b521e9a2766495be344abec7ec399f7b7244fe6c9e193 (7482 bytes), locally re-hashed byte-exact by Mos. Parent #758 remains open; M4-002/M5-002 and every live action remain held.
jason.woltje merged commit 627cf2bb38 into main 2026-07-20 05:22:27 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-dogfood-01 (Mosaic fleet seat code-dogfood-01) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) marcie merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) orch-01 (Mosaic fleet seat orch-01) pepper resume rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny topher (Mosaic fleet seat topher) velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#789