Files

T

veronica f0d2dd9920 docs(W4): stamp kind and status front matter on 104 live documents

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`.

2026-08-20 19:30:25 -05:00

5.9 KiB

Raw Blame History

kind, status

kind	status
guide	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. 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.

Running the guard

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.

5.9 KiB Raw Blame History