---
kind: record
status: active
---

# FCM-M5-001 Fleet Documentation Deferrals and Holds

**Issue:** #758 · **Branch:** `docs/758-fleet-config-operator-docs`

These are accepted existing DAG boundaries, not omissions silently claimed as delivered.

## FCM-M3-002 hold

- Boot/reboot preservation for roster members persisted stopped or disabled.
- Current installation may enable all agent units, while the launcher projection does not yet carry
  `lifecycle.enabled` or `desired_state`; documentation therefore does not claim lifecycle-safe reboot.
- Heartbeat/liveness integration into roster-v2 `status`, `doctor`, and `verify`; current observations
  cover systemd active state, tmux sessions, holder ownership, and unmanaged sessions only.

## FCM-M4-002 hold

- Executable v1-to-v2 cutover, reversible canary, and rollback.
- Stale-projection/orphan migration classification and current-host managed/unmanaged fixture coverage.
- Any live migration, lifecycle, systemd/tmux/session, or rollback action.

M5 docs describe prerequisites and the preview boundary only. A ready preview is not migration or rollback evidence.

## Explicit validate-operation gap

- `FCM-REQ-03` requires a documented programmatic `mosaic fleet validate` operation.
- The current CLI does not expose that operation. Existing mutation/reconcile validation and the
  documentation example test are not a replacement for the missing command.
- FCM-M5-001 documents this implementation gap without inventing syntax, JSON, exit behavior, or an
  owning implementation card. Parent #758 must remain open until the requirement is implemented and
  evidenced or the PRD/DAG is explicitly revised through the authoritative process.

## FCM-M5-002 hold

- Deterministic source-versus-installed asset revision detection and safe refresh implementation.
- Rolling local canary, independent validator certificate, final release evidence, merge-gate approval, and parent #758 closure.

`operations/upgrade-assets.md` is therefore a fail-closed hold, not an invented procedure.

## Compatibility interpretation

The M0 cross-cutting row requiring every retained/migrated artifact to validate through the executable contract is satisfied by each artifact's declared executable disposition, not by forcing versioned v1 fixtures through the v2 parser:

- retained examples are explicit `version: 1` fixtures validated by the production v1 parser;
- canonical profiles validate through the shared baseline plus `roles.local` resolver;
- the service preset validates through its production service-policy reader;
- migration candidates validate through the production v2 compiler and shared semantic resolver.

The executable disposition inventory rejects undeclared additions/removals and prevents silent legacy drift.

## Repository-wide documentation structure

The accepted #758 IA is the domain book under `docs/fleet/`. Creating global `USER-GUIDE`, `ADMIN-GUIDE`, or `DEVELOPER-GUIDE` books and cleaning unrelated pre-existing `docs/` root files are outside this bounded card. The repository sitemap links the fleet book. No HTTP/API/auth contract changed, so OpenAPI and endpoint-index updates are not applicable.

Canonical documentation remains in-repository; no external publishing or generated publishing output is in scope. Parent issue #758 stays open through M5.
