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`.
92 lines
9.9 KiB
Markdown
92 lines
9.9 KiB
Markdown
---
|
|
kind: guide
|
|
status: active
|
|
---
|
|
|
|
# Previewing a Fleet Roster v1-to-v2 Migration
|
|
|
|
**Issue:** #758 · **Card:** FCM-M4-001 · **Effect boundary:** preview only
|
|
|
|
mosaic fleet migrate-v1 preview inventories a v1 roster and emits a canonical v2 candidate plus
|
|
recovery evidence. It does not write a roster, apply environment projections, invoke systemd or
|
|
`tmux`, contact connectors or remote hosts, launch an agent, run a canary, or execute rollback.
|
|
FCM-M4-002 owns reversible cutover and rollback.
|
|
|
|
## Inputs
|
|
|
|
```fleet-command
|
|
mosaic fleet migrate-v1 preview \
|
|
--source roster-v1.yaml \
|
|
--decisions migration-decisions.json \
|
|
--observations reviewed-observations.json
|
|
```
|
|
|
|
The command emits one JSON object and exits nonzero when the preview is blocked, including when any of
|
|
`--source`, `--decisions`, or `--observations` is omitted, passed without a path value, or passed an empty
|
|
path value. These request-shape failures are reported before any input file is read. Decision and
|
|
observation JSON is validated fail-closed: unknown fields, malformed values, and records for non-local
|
|
agents are rejected. Decisions must supply a positive v2 `generation`, a reviewed `fleetHost` whenever
|
|
v1 agents include `host` or `ssh`, explicit `defaultRuntime`, and per-local-agent provider, model,
|
|
reasoning, enabled state, and launch policy. The v1 source remains authoritative for socket semantics:
|
|
a supported declared socket field, including an explicit empty value for the default tmux server, is
|
|
preserved; if both supported root aliases are absent, the production v1 default is the literal empty socket.
|
|
A matching `socketName` decision is accepted and an incompatible decision blocks, but a decision never
|
|
supplies or repairs a missing source socket. If v1 omitted `tool_policy`, decisions must supply an
|
|
explicit replacement; it is never derived from `class`. `model_hint` is never split or treated as
|
|
authority.
|
|
|
|
Observations are separate reviewed evidence keyed by local agent name:
|
|
|
|
```json
|
|
{
|
|
"coder0": { "systemd": "inactive", "tmux": "missing" }
|
|
}
|
|
```
|
|
|
|
Only `active` plus `present` maps to `running`; only `inactive` plus `missing` maps to `stopped`.
|
|
Missing, extra, unknown, or contradictory evidence blocks output. An observed-running agent cannot
|
|
be marked disabled. Observed-stopped agents always remain stopped.
|
|
|
|
## Field disposition
|
|
|
|
| v1 field | v2 disposition |
|
|
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `version`, `transport`, `tmux`, `defaults`, `runtimes` | Inventoried and structurally compiled; omitted runtimes retain v1 built-in defaults, while each explicitly declared runtime without a reset field follows the production v1 `/clear` fallback; present-empty holder/work-directory/reset values block |
|
|
| agent `name`, `alias`, `runtime`, working directory, persona/reset flags | Copied or explicitly defaulted only when absent; present-empty alias/work-directory values block for explicit disposition. Canonical ~/~/... values stay unchanged in roster evidence and traversal-free forms expand only at the shared production environment-projection boundary before unchanged absolute-path validation |
|
|
| `provider`, `model_hint`, `reasoning_level` | Explicit provider/model/reasoning decisions; no model-hint inference |
|
|
| `class`, `tool_policy` | Only approved aliases canonicalize automatically; other classes require explicit preserve/replace disposition and shared-resolver validation |
|
|
| `kickstart_template` | No v2 field; explicit inventory-only disposition required |
|
|
| agent `host`, `ssh` | host != fleetHost is demonstrably remote and inventory-only; host == fleetHost stays local; SSH targets with or without an explicit user must agree with `host`; ssh-only, missing fleet-host evidence, or contradictory targets block |
|
|
| agent `socket` | Same-host candidate only when it matches the canonical fleet socket; conflicts block for explicit future disposition |
|
|
| root `connector` | Inventory-only; never contacted or reconciled |
|
|
| unknown fields or snake/camel synonym collisions | Inventoried and block readiness |
|
|
| `.env.generated` | Rebuild from canonical roster data |
|
|
| no legacy `.env` | `absent`; no legacy action required |
|
|
| legacy `.env` containing generated keys only | `regenerate-only`; replace later from canonical roster data |
|
|
| legacy `.env` containing strict local keys | `relocate-local`; preserve those keys in `.env.local` during a later reviewed cutover |
|
|
| legacy `.env` containing forbidden/unsafe/sensitive/malformed keys | `quarantine`; private input only, with diagnostics limited to code, key, and SHA-256 |
|
|
|
|
The only automatic aliases are implementer → code, reviewer → review, and
|
|
operator-interaction → interaction. Similar or domain-specific names are never inferred. Automatic
|
|
classes do not accept competing disposition records. Semantic validation delegates to the existing
|
|
baseline-plus-`roles.local` resolver after the candidate is compiled by the existing v2 compiler.
|
|
|
|
## Evidence and recovery boundary
|
|
|
|
Ready output includes source and candidate SHA-256 identities, value-free field inventory, excluded
|
|
remote/connector entries, explicit environment dispositions with sanitized diagnostics, and the lifecycle
|
|
evidence used for each local candidate. Canonical lifecycle and remote-exclusion evidence ordering compares
|
|
Unicode code points directly and does not depend on source-agent order or process locale. Source field
|
|
inventory remains position-addressed evidence of the exact input. Recovery is marked non-executable and
|
|
assigns the executable gate to FCM-M4-002.
|
|
|
|
Before any later cutover, preserve these artifacts:
|
|
|
|
1. authoritative v1 roster backup;
|
|
2. agent environment backup, including `.env.local` and private quarantine inputs;
|
|
3. reviewed lifecycle observations;
|
|
4. canonical candidate v2 roster and its SHA-256.
|
|
|
|
See [backup and restore](../operations/backup-restore.md). Preview output is migration-readiness
|
|
evidence, not proof that migration, canary, or rollback occurred.
|