From cfe3878c99216a87d2d5eaeb41b5e09cb59c9ab7 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Tue, 14 Jul 2026 14:38:16 -0500 Subject: [PATCH] docs(fleet): inventory interaction service preset --- docs/PRD.md | 4 ++-- docs/TASKS.md | 4 ++-- docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md | 10 +++++----- .../LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md | 13 +++++++++++-- 4 files changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/PRD.md b/docs/PRD.md index de5473e..b021392 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -101,7 +101,7 @@ gateway-backed agent catalog. | `FCM-REQ-05` | The launch chain SHALL consume deterministic, digest-stamped generated input only. Optional local overrides SHALL be parsed as strict data, may not shadow authoritative generated keys, and may not contain arbitrary commands, credential values, channels, or unknown `MOSAIC_AGENT_*` keys. Forbidden legacy keys, including `MOSAIC_AGENT_COMMAND`, SHALL be privately quarantined before launch and reported only by key name and content hash. | | `FCM-REQ-06` | Mutations and apply SHALL validate before mutation, use an expected generation/lock, write projections atomically, produce a deterministic plan, and emit recovery information on partial failure. Reconciliation SHALL act only on local, enabled, roster-owned projections and SHALL not kill unmanaged tmux sessions by fuzzy name. | | `FCM-REQ-07` | Canonical required classes are `code`, `review`, `validator`, `orchestrator`, `team-leader`, `enhancer`, and `interaction`. `validator` issues an independent final certificate but has no merge authority; `merge-gate` remains sole approve-to-land/merge authority. Team-leader capacity is bounded by an orchestrator-issued lease, and interaction is request/status only. Tess and Ultron are configurable instance/display names, not required machine identities. | -| `FCM-REQ-08` | v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example/profile SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note. | +| `FCM-REQ-08` | v1 migration SHALL be field-complete, reversible, and explicit about aliases, unresolved classes, lifecycle inference, generated-file regeneration, local override quarantine, schema-only remote/connector fields, and rollback. Every shipped example, profile, and service preset SHALL be migrated and executable, retained as an explicitly versioned v1 fixture, or retired with a replacement and deprecation note. | | `FCM-REQ-09` | M1–M5 SHALL remain local tmux/systemd control-plane work. Remote/SSH reconciliation, connector mutation, secret references, arbitrary command/channel overrides, gateway/API convergence, and UI configuration storage are excluded and require a separate PRD/threat model. | | `FCM-REQ-10` | Documentation and examples are delivery gates. The M0 checklist at [docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md](./fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md) and the baseline disposition inventory at [docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md](./fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md) SHALL be maintained as acceptance evidence. | @@ -112,7 +112,7 @@ gateway-backed agent catalog. 3. `AC-FCM-03`: Local create/update/delete is generation-guarded, atomic, idempotent, and safe by default; it permits supported runtime/model/harness/effort/workdir/role changes without direct editing of generated environment files and does not start a newly created agent unless explicitly persisted. 4. `AC-FCM-04`: The generated-env/local-override launch chain rejects generated-key shadowing, arbitrary command override, unknown keys, shell evaluation, and sensitive-value diagnostics before any agent starts; known-safe legacy input is regenerated or strictly relocated, and forbidden input is quarantined. 5. `AC-FCM-05`: Local lifecycle reconciliation implements the persisted/transient start-stop rules, exact default/named tmux socket targeting, systemd/tmux status, stale generated state, unmanaged-session reporting, and rollback without surprise restarts or fuzzy destructive targeting. -6. `AC-FCM-06`: A v1 roster migration previews field-by-field disposition, preserves observed stopped/running state, inventories rather than reconciles remote/schema-only entries, supports a canary and rollback, and classifies every shipped example/profile according to the M0 inventory. +6. `AC-FCM-06`: A v1 roster migration previews field-by-field disposition, preserves observed stopped/running state, inventories rather than reconciles remote/schema-only entries, supports a canary and rollback, and classifies every shipped example, profile, and service preset according to the M0 inventory. 7. `AC-FCM-07`: Required role authority is validated: validator certificate is consumed but does not merge, merge-gate is the sole merge authority, team-leader leases do not change roster/credentials/authority, and interaction/Tess cannot claim orchestration or merge powers. 8. `AC-FCM-08`: Documentation, examples, migration, troubleshooting, operational recovery, package/update asset drift, schema/example/profile validation, independent code/security review, validator certificate, and terminal-green CI are complete before #758 closes. diff --git a/docs/TASKS.md b/docs/TASKS.md index 9b01f4e..4097373 100644 --- a/docs/TASKS.md +++ b/docs/TASKS.md @@ -54,10 +54,10 @@ Active workstream is **W1 — Federation v1**. Workers should: | id | status | description | issue | agent | repo | branch | depends_on | estimate | notes | | ---------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ----------------- | --------------------------------------- | ---------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- | -| FCM-M0-001 | in-progress | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758 | sonnet | mosaicstack/stack | `docs/758-fleet-config-management` | — | 18K | M0 exit: approved docs; every shipped example/profile classified; docs-only PR | +| FCM-M0-001 | in-progress | Publish normative PRD requirements/acceptance criteria, this M0–M5 DAG, docs-IA checklist, and legacy example/profile disposition inventory; no implementation changes | #758 | sonnet | mosaicstack/stack | `docs/758-fleet-config-management` | — | 18K | M0 exit: approved docs; every shipped example/profile/service preset classified; docs-only PR | | FCM-M1-001 | not-started | Implement narrow local-tmux v2 roster structural contract/compiler with YAML/JSON canonicalization and schema/parser parity tests | #758 | codex | mosaicstack/stack | `feat/758-roster-v2-compiler` | FCM-M0-001 | 30K | No lifecycle, remote, connector, secret, channel, or gateway work | | FCM-M1-002 | not-started | Reuse existing profile/persona/provision resolver for roster semantics; add canonical class/authority validation and approved aliases | #758 | codex | mosaicstack/stack | `feat/758-shared-role-resolution` | FCM-M0-001 | 25K | Validator is certificate-only; merge-gate remains sole merge authority | -| FCM-M1-003 | not-started | Convert the M0 legacy inventory into executable example/profile validation and explicit v1-version/retirement checks | #758 | codex | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002 | 20K | Every shipped file must validate, be versioned v1, or be retired with replacement | +| FCM-M1-003 | not-started | Convert the M0 legacy inventory into executable example/profile/service-preset validation and explicit v1-version/retirement checks | #758 | codex | mosaicstack/stack | `test/758-example-profile-dispositions` | FCM-M1-001, FCM-M1-002 | 20K | Every shipped artifact must validate, be versioned v1, or be retired with replacement | | FCM-M2-001 | not-started | Migrate generic launch chain to deterministic `.env.generated` plus strict data-only `.env.local`; quarantine forbidden legacy keys | #758 | codex | mosaicstack/stack | `feat/758-generated-env-boundary` | FCM-M1-001, FCM-M1-002 | 30K | No arbitrary command compatibility path; diagnostics expose key names/hashes only | | FCM-M2-002 | not-started | Add generation-guarded local fleet agent create/get/update/delete mutations with plan/dry-run, atomic roster writes, and recovery output | #758 | codex | mosaicstack/stack | `feat/758-fleet-agent-crud` | FCM-M1-001, FCM-M2-001 | 30K | Fresh create persists stopped unless explicit persisted start | | FCM-M3-001 | not-started | Implement local roster-owned reconcile/apply plus lifecycle/status/verify/doctor contracts and stable JSON/exit codes | #758 | codex | mosaicstack/stack | `feat/758-local-reconciler` | FCM-M2-001, FCM-M2-002 | 35K | Exact systemd/tmux ownership; remote/schema-only entries are inventory only | diff --git a/docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md b/docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md index 6c277f7..b6f9afc 100644 --- a/docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md +++ b/docs/fleet/FLEET-CONFIG-DOCS-IA-CHECKLIST.md @@ -26,7 +26,7 @@ recorded in the M0 task/PR. - [ ] `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. + fleet example, profile, and service preset before M1 implementation starts. ## Required documentation IA for M1–M5 @@ -72,10 +72,10 @@ recorded in the M0 task/PR. ## 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. +- [ ] Every retained or migrated YAML/JSON example, profile, and service preset validates through the + same executable schema and shared baseline-plus-`roles.local` resolver used by the CLI. +- [ ] Every retired example/profile/service preset has a replacement link and deprecation note; no + unresolved legacy class or tool-policy alias 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 diff --git a/docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md b/docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md index 89b40b6..318b4e9 100644 --- a/docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md +++ b/docs/fleet/LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md @@ -1,4 +1,4 @@ -# Fleet Configuration Management — Legacy Example and Profile Disposition Inventory +# Fleet Configuration Management — Legacy Example, Profile, and Service Disposition Inventory **Issue:** #758 · **Baseline:** `origin/main` `49e8a541` · **Status:** M0 inventory; no source examples or profiles are changed by this document. @@ -31,6 +31,12 @@ parallel resolver. | `framework/fleet/profiles/research.yaml` | `lead-researcher`, `researcher`, `data-analyst`, `data-scientist`, `market-analyst`, `documentation`, `review` | Same resolver-or-version/retire rule | Per-class resolver CI result and explicit compatibility posture | | `framework/fleet/profiles/software-delivery.yaml` | `orchestrator`, `board`, `planner`, `decomposition`, `code`, `review`, `security-review`, `site-tester`, `documentation`, `merge-gate`, `rebase`, `operator`, `session-review`, `enhancer` | Retain as the governance reference; add `validator`, `team-leader`, and `interaction` only through approved role/profile work, not silent substitution | CI validates all current classes; separate fixture proves required M1 authority seats | +## Service presets + +| Shipped file | Current policy evidence | M0 disposition decision | Required M1/M4 evidence | +| ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `framework/fleet/services/operator-interaction.yaml` | Generic policy only: `runtime: pi`, `model: openai/gpt-5.6-sol`, `reasoning: high`, `tool_policy: operator-interaction`; provisioning supplies the agent name as data | Retain as a generic service policy, not a Tess identity. Migrate `tool_policy: operator-interaction` only through the approved interaction tool-policy alias/semantic resolver; do not infer a class or machine name from this file. | Service-policy fixture validates runtime/model/reasoning and alias behavior; generic provisioning proves a configured interaction instance is supplied without a hardcoded Tess name. | + ## Required disposition controls 1. **No silent aliasing:** only `implementer → code`, `reviewer → review`, and @@ -43,5 +49,8 @@ parallel resolver. of an installed v1 roster separately preserves observed stopped/running state. 4. **No secret or command migration:** examples/profiles must not introduce credential values or `MOSAIC_AGENT_COMMAND`; those legacy keys are M2 quarantine inputs, never v2 authoring fields. -5. **Evidence is executable:** M1/M4 CI must enumerate these exact files, validate retained/migrated +5. **Service presets are included:** service policies are inventoried alongside examples/profiles. + They may express launch/tool policy, but do not create a class, a canonical agent identity, or a + second validation path. +6. **Evidence is executable:** M1/M4 CI must enumerate these exact files, validate retained/migrated inputs through the shared resolver, and fail if a file lacks its documented disposition.