veronica
f0d2dd9920
Applies the document contract from
docs/plans/2026-08-20_stack-docs-flatten-and-alignment.md section 3, partially:
`kind` and `status` only. `parent` is deliberately held until the flatten in
section 4 lands, so that 127 documents do not have to be re-pointed by hand
when docs/fleet/NORTH_STAR.yaml moves to docs/NORTH_STAR.yaml.
Scope, measured on origin/next at 63069149:
127 live docs = all *.md under docs/ minus docs/archive/ minus docs/_old_structure/
104 stamped here
19 held operator judgement (plan section 9), worklist in the same PR
3 held the SUPERSEDED TASKS.md stamps, which cite the moving path
1 untouched docs/fleet/FLEET-DOCTRINE.md, already stamped in W1
Kinds applied: 54 guide, 34 record, 9 spec, 6 tracking, 1 projection.
Every row carries a confidence and a one-line rationale in the worklist.
Two collisions with the existing state, both flagged rather than resolved:
1. docs/README.md:150-160 already documents a front-matter convention
(title/type/audience/status/source_of_truth) with its own allowed values.
It is applied to 4 of 127 files. Its `status` vocabulary is
current|draft|deprecated|historical; the new contract's is active|superseded-by.
The key collides. This commit lets the new contract win and rewrites
`status: current` to `status: active` on those 4 files, keeping their other
legacy keys untouched. No code reads any of them: `git grep source_of_truth`
outside docs/ returns nothing. docs/README.md still prescribes the old
convention and is an operator row, so it is not edited here.
2. Two of the plan's 20 operator rows are YAML files, not markdown
(docs/fleet/examples/roster-v2.yaml, docs/openapi-tess.yaml), and the
contract's front-matter form has no defined meaning for a .yaml document.
That gap also applies to docs/fleet/NORTH_STAR.yaml, the source of truth
itself. Raised in the worklist.
A third row from the plan, docs/fleet/north-star.md, no longer exists: W1
renamed it to docs/fleet/FLEET-DOCTRINE.md.
Verification: 104/104 parse with the expected kind and status in front matter;
the check was shown to reject a wrong kind before it was trusted. The diff
removes 4 lines total, all of them `status: current`.
75 lines
5.9 KiB
Markdown
75 lines
5.9 KiB
Markdown
---
|
|
kind: guide
|
|
status: active
|
|
---
|
|
|
|
# Executable Fleet Example, Profile, and Service-Preset Dispositions
|
|
|
|
**Issue:** #758 · **Card:** FCM-M1-003 · **Status:** M1 executable disposition evidence
|
|
|
|
This document records the executable disposition for every currently shipped fleet YAML artifact.
|
|
The authoritative baseline classification remains the
|
|
[legacy inventory](../LEGACY-EXAMPLE-PROFILE-DISPOSITION-INVENTORY.md). The executable guard is
|
|
`packages/mosaic/src/fleet/example-profile-dispositions.ts`; its test fails if a shipped YAML
|
|
artifact is added, removed, or left without one of the dispositions below.
|
|
|
|
## Disposition rules
|
|
|
|
- **Explicit v1 fixture:** the artifact is loaded through the existing v1 roster parser and must
|
|
declare version: 1. It remains a compatibility fixture; it is not silently treated as a v2
|
|
roster or given inferred aliases.
|
|
- **Canonical profile:** the artifact is loaded through `loadProfiles`, which uses the shared
|
|
baseline-plus-`roles.local` persona resolver and rejects unreadable or unresolved classes.
|
|
- **Canonical service policy:** the artifact is loaded through the operator-interaction service
|
|
policy reader and provisioned with a generic supplied identity. It validates its runtime, model,
|
|
reasoning, and legacy tool-policy compatibility without hardcoding a product identity.
|
|
|
|
No artifact is retired in this card. A later retirement requires both a replacement link and a
|
|
visible deprecation note; the executable guard must then record the new disposition before the
|
|
artifact can be removed.
|
|
|
|
## Shipped artifacts
|
|
|
|
| Artifact | Disposition | Executable path | Compatibility notes |
|
|
| ------------------------------------ | ------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
| `examples/coding.yaml` | Explicit v1 fixture | v1 roster parser | Retains approved `implementer` and `reviewer` compatibility inputs. |
|
|
| `examples/general.yaml` | Explicit v1 fixture | v1 roster parser | Retains unresolved `worker` without an inferred canonical role. |
|
|
| `examples/hybrid.yaml` | Explicit v1 fixture | v1 roster parser | Retains `implementer`, `reviewer`, and resolver-dependent `researcher`. |
|
|
| `examples/local-canary.yaml` | Explicit v1 fixture | v1 roster parser | Retains the local-tmux canary topology. |
|
|
| `examples/minimal.yaml` | Explicit v1 fixture | v1 roster parser | Retains `canary` without an inferred canonical role. |
|
|
| `examples/operator-interaction.yaml` | Explicit v1 fixture | v1 roster parser | Keeps Tess only as an example instance name; `operator-interaction` remains compatibility input. |
|
|
| `examples/research.yaml` | Explicit v1 fixture | v1 roster parser | Retains resolver-dependent `researcher` and `analyst`. |
|
|
| `profiles/business.yaml` | Canonical profile | shared profile/persona resolver | Every referenced business class must resolve to a readable contract. |
|
|
| `profiles/marketing.yaml` | Canonical profile | shared profile/persona resolver | Every referenced marketing class must resolve to a readable contract. |
|
|
| `profiles/personal-assistant.yaml` | Canonical profile | shared profile/persona resolver | No interaction equivalence is inferred. |
|
|
| `profiles/research.yaml` | Canonical profile | shared profile/persona resolver | Every research class must resolve to a readable contract. |
|
|
| `profiles/software-delivery.yaml` | Canonical profile | shared profile/persona resolver | Retains the governance profile; authority validation remains FCM-M1-002 evidence. |
|
|
| `services/operator-interaction.yaml` | Canonical service policy | service-policy reader/provisioner | Generic provisioning supplies the instance name; the policy itself never names Tess. |
|
|
|
|
## M4 migration-preview evidence
|
|
|
|
FCM-M4-001 layers an executable migration posture over the same 13-entry M1 inventory without
|
|
changing the retained artifact classification:
|
|
|
|
- every `v1-fixture` is previewed only with explicit class and lifecycle evidence;
|
|
- every `canonical-profile` remains validated by the shared baseline-plus-`roles.local` resolver;
|
|
- the canonical service policy remains generic and uses only the approved tool-policy alias.
|
|
|
|
`validateShippedFleetMigrationDispositions` first runs the existing executable M1 guard, then requires
|
|
explicit decisions and lifecycle observations and executes `previewV1ToV2Migration` for every shipped
|
|
v1 fixture. `collectShippedFleetMigrationDispositions` derives the 13-entry posture directly from
|
|
`SHIPPED_FLEET_ARTIFACT_DISPOSITIONS`, so additions or removals continue to fail the M1 guard rather
|
|
than creating a second artifact list. None of these dispositions claims a cutover, canary, or
|
|
rollback; those gates belong to FCM-M4-002. See [v1-to-v2 preview](./v1-to-v2.md).
|
|
|
|
## Running the guard
|
|
|
|
```fleet-command
|
|
pnpm --filter @mosaicstack/mosaic test -- v1-v2-migration.spec.ts \
|
|
-t "validates all 13 shipped artifacts and executes ready previews for every v1 fixture"
|
|
```
|
|
|
|
The guard is intentionally limited to shipped assets and validation. It does not generate
|
|
environment files, mutate a roster, reconcile a fleet, migrate an installed roster, or launch an
|
|
agent.
|