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`.
104 lines
7.7 KiB
Markdown
104 lines
7.7 KiB
Markdown
---
|
|
kind: guide
|
|
status: active
|
|
---
|
|
|
|
# Fleet Generated Environment Boundary
|
|
|
|
**Card:** FCM-M2-001 · **Issue:** #758 · **Status:** merged contract
|
|
|
|
The local fleet roster is the desired-state authority. A launch reads a deterministic,
|
|
roster-derived generated projection and an optional strictly data-only local file; neither file is
|
|
a second roster or a command configuration surface.
|
|
|
|
## Paths and ownership
|
|
|
|
For agent <name> under <MOSAIC_HOME>/fleet/agents/:
|
|
|
|
| Path | Owner | Purpose |
|
|
| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
|
|
| <name>.env.generated | Mosaic projection writer | Complete deterministic launch data rendered from the authoritative roster. |
|
|
| <name>.env.local | Operator | Optional, constrained local machine data. It cannot shadow generated keys. |
|
|
| <name>.env | Legacy input only | Read once during projection generation, then regenerated/relocated or privately quarantined. It is never a launch authority. |
|
|
| <name>.env.quarantine | Mosaic quarantine | Mode-`0600` private record of forbidden legacy input; it is never read by the launcher. |
|
|
|
|
The systemd templates do not load either environment file. They invoke Bash with a fixed, cleared
|
|
bootstrap environment; the launcher reads and validates `.env.generated` and `.env.local` itself before
|
|
it queries, creates, or stops an exact tmux session. It does not `source`, `eval`, or execute an
|
|
environment-supplied command. Exact stop derives its socket from the same validated generated projection,
|
|
not from systemd or ambient environment data.
|
|
|
|
All projection, local, and quarantine files must be regular files with no group or world permissions.
|
|
The agent environment directory must also be a real, non-symlink private directory; it is validated
|
|
before either environment file is read or tmux is queried. Unsafe paths, symlinks, or permissions fail
|
|
closed. Diagnostics identify only a rule code, key name, and SHA-256 content hash; they never print
|
|
values, credential material, or command text.
|
|
|
|
## Allowed data
|
|
|
|
`.env.generated` is complete and ordered exactly as follows:
|
|
|
|
```dotenv
|
|
MOSAIC_AGENT_NAME=<roster name>
|
|
MOSAIC_GIT_IDENTITY=<roster name>
|
|
MOSAIC_AGENT_CLASS=<roster class>
|
|
MOSAIC_AGENT_RUNTIME=<roster runtime>
|
|
MOSAIC_AGENT_MODEL=<roster model hint>
|
|
MOSAIC_AGENT_REASONING=<roster reasoning>
|
|
MOSAIC_AGENT_TOOL_POLICY=<roster tool policy>
|
|
MOSAIC_AGENT_WORKDIR=<absolute roster work directory>
|
|
MOSAIC_TMUX_SOCKET=<roster socket or empty>
|
|
```
|
|
|
|
`MOSAIC_GIT_IDENTITY` is derived from and must equal `MOSAIC_AGENT_NAME`; it is not a separate
|
|
operator-controlled identity authority. The generated launch contract supports only `claude`, `codex`,
|
|
`opencode`, and `pi`. fleet add uses that same runtime authority and rejects any other runtime before it writes the roster or changes
|
|
projection, local, or quarantine files. The legacy dogfood stub on its separate `mosaic-factory`
|
|
socket remains an observability canary; it has no generated-launch adapter and cannot be added through
|
|
this projection path.
|
|
|
|
`.env.local` may contain only these non-secret data keys:
|
|
|
|
- `MOSAIC_RUNTIME_BIN`
|
|
- `MOSAIC_HEARTBEAT_RUN_DIR`
|
|
- `MOSAIC_HEARTBEAT_INTERVAL`
|
|
- `MOSAIC_CLAUDE_JSON`
|
|
- `CLAUDE_CONFIG_DIR`
|
|
|
|
Local paths must be safe absolute paths and the interval must be a positive integer. Comments,
|
|
quoted/export syntax, duplicate keys, unknown keys, generated-key shadowing, sensitive key names,
|
|
and `MOSAIC_AGENT_COMMAND` are rejected. The launcher derives the only executable command from the
|
|
validated runtime, model, and reasoning data; no arbitrary command compatibility path exists. When a
|
|
Pi runtime writes a fresh <name>.hb.native marker, its native heartbeat remains authoritative; the
|
|
shell sidecar resumes its `status=ok` fallback only after that marker is stale or absent.
|
|
|
|
## Legacy disposition
|
|
|
|
During projection generation, legacy roster-derived keys are regenerated from the roster. A valid
|
|
allowed local value is relocated to `.env.local`; forbidden, malformed, duplicate, sensitive, and
|
|
unknown legacy entries cause the legacy file to be moved to `.env.quarantine` and are represented by
|
|
sanitized diagnostics. This is deterministic and idempotent after the legacy file has been consumed.
|
|
|
|
## USC interface packet
|
|
|
|
This card does not add a USC site file, write a USC roster, or run a site canary. The following is the
|
|
consolidated downstream interface packet. Status is deliberately separated from checkout presence: no
|
|
product release version has been evidenced for this interface set.
|
|
|
|
| Interface | Canonical public path and version | Tracker/release status | Downstream limit |
|
|
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
|
|
| M1 structural compiler | `parseRosterV2` in `packages/mosaic/src/fleet/roster-v2.ts`; schema `docs/fleet/reference/roster-v2.schema.json`; roster version: 2 | FCM-M1-001 is recorded done, merged as #764 (`aa5b43b`); no released product version is asserted here. | Parse YAML/JSON and canonicalize a supplied v2 site roster without writes. |
|
|
| M1 semantic resolver | `validateRosterV2Semantics` in `packages/mosaic/src/fleet/roster-v2.ts`; baseline `framework/fleet/roles/` plus `roles.local/` | FCM-M1-002 merged as #768 (`a5e8e55`); no released product version is asserted here. | Reuse the shared resolver only; no parallel role resolver or lifecycle action. |
|
|
| M1 disposition evidence | `packages/mosaic/src/fleet/example-profile-dispositions.ts`; `docs/fleet/migration/example-profile-disposition.md`; retained fixture version: 1 | FCM-M1-003 merged as #770 (`e9c4aa3`); checkout evidence remains validation, not migration authorization. | Inspect fixture/profile/service disposition evidence only; it is not migration authorization. |
|
|
| M2 generated boundary | `packages/mosaic/src/fleet/generated-env-boundary.ts`; generated projection contract in this document | FCM-M2-001 merged as #772 (`191efae`); no released product version is asserted here. | Render/write a roster-derived projection; local input is never authority. |
|
|
|
|
The canonical source remains <MOSAIC_HOME>/fleet/roster.yaml for the current local fleet path.
|
|
Generated environment data is a rebuildable projection, not an operator-editable source of membership,
|
|
runtime policy, or lifecycle state.
|
|
|
|
**Corrected downstream gates:** M2 supplies only parse/validation/projection evidence and does not
|
|
permit a USC site canary, reconciliation, or lifecycle mutation. M3 must first define and validate the
|
|
canonical local reconcile/lifecycle path. M4 then supplies preview/migration and its separate
|
|
canary/rollback gates; only after those M3 and M4 gates may a site migration or canary be considered.
|
|
This card authorizes none of those actions.
|