docs(fleet): tier the north star and declare the tier-0 operator surface #1337

2026-08-20T22:35:06Z

fred commented

2026-08-20 22:35:06 +00:00

What

Adds a tier dimension to the fleet north star and declares the tier-0 (dogfood) operator surface. tier is orthogonal to phase: phase is build order, tier is which promise the item delivers.

AC-NS-0 — a tier-0 exit test that can fail: the operator launches an agent on any configured harness with one command, observes its state and sends it work without attaching to a terminal multiplexer.
tier: 0|1|2 required on every goal and success criterion, enforced in the generator so the projection cannot silently drop it.
NS-10 — an adoption is not complete until the mechanism it replaces is removed.
Workstream G declared (G1 referenced a workstream that did not exist). New workstreams I (operator surface), J (web control plane), K (clients), L (auth profiles).
docs/fleet/north-star.md renamed to docs/fleet/FLEET-DOCTRINE.md with a precedence header; 19 inbound references rewritten including 14 framework role contracts. Git detects this as a rename.
Three TASKS.md files marked superseded; docs/native-kanban-sot/TASKS.md corrected instead because it advertised a false blocker.

NORTH_STAR.md is regenerated from NORTH_STAR.yaml, never hand-edited.

Provenance and review

Authored by jarvis-vscode (Jason's VS Code session, not a fleet seat), handed to fred uncommitted with the drift check passing but the full suite unrun. fred ran the suite, fixed what it surfaced, and landed it.

Reviewer must be neither jarvis-vscode nor fred (Gate 16, author != reviewer): jarvis-vscode wrote the doctrine and generator change, fred wrote the four fixes below.

Four defects the drift check could not see

fleet-north-star.spec.ts inline fixture was missing the now-required tier field. The generator made it required; the fixture was never updated.
Seven InlineLiteral doc-lint diagnostics. New inline backtick spans containing spaces violate the closed grammar enforced on docs/fleet/**.
Doc-corpus census stale: InlineLiteral 863 -> 882, total surfaces 887 -> 906. The security-relevant categories (ConcreteCommand 4, Synopsis 5, DataProfile 15) are unchanged, which is the part that matters.
Four TASKS.md files failed prettier --check. Formatting them exposed that the banner's trailing > --- after a text line renders as a setext H2 underline. Removed.

Each was proved to be caused by this change with a stash-based control run on the same head.

Verification

Check	Result
`pnpm --filter @mosaicstack/mosaic test`	1614 passed, 3 failed
`pnpm typecheck`	rc=0
`pnpm lint`	rc=0
`pnpm format:check`	clean
pre-push hook	all three above, green

The 3 failures are in src/cli-smoke.spec.ts ("production CLI emits one blocked JSON object for bare --source/--decisions/--observations") and are pre-existing, confirmed by a stashed-tree control run on the same head. Not introduced here and not in scope.

Known and deliberately untouched: docs/fleet/NORTH_STAR.yaml fails prettier --check, but so does the HEAD version, and CI's format:check glob covers only {ts,tsx,js,jsx,json,md}.

Closes #1336 ## What Adds a `tier` dimension to the fleet north star and declares the tier-0 (dogfood) operator surface. `tier` is orthogonal to `phase`: `phase` is build order, `tier` is which promise the item delivers. - `AC-NS-0` — a tier-0 exit test that can fail: the operator launches an agent on any configured harness with one command, observes its state and sends it work without attaching to a terminal multiplexer. - `tier: 0|1|2` required on every goal and success criterion, enforced in the generator so the projection cannot silently drop it. - `NS-10` — an adoption is not complete until the mechanism it replaces is removed. - Workstream `G` declared (`G1` referenced a workstream that did not exist). New workstreams `I` (operator surface), `J` (web control plane), `K` (clients), `L` (auth profiles). - `docs/fleet/north-star.md` renamed to `docs/fleet/FLEET-DOCTRINE.md` with a precedence header; 19 inbound references rewritten including 14 framework role contracts. Git detects this as a rename. - Three `TASKS.md` files marked superseded; `docs/native-kanban-sot/TASKS.md` corrected instead because it advertised a false blocker. `NORTH_STAR.md` is regenerated from `NORTH_STAR.yaml`, never hand-edited. ## Provenance and review Authored by jarvis-vscode (Jason's VS Code session, not a fleet seat), handed to fred uncommitted with the drift check passing but the full suite unrun. fred ran the suite, fixed what it surfaced, and landed it. **Reviewer must be neither jarvis-vscode nor fred** (Gate 16, author != reviewer): jarvis-vscode wrote the doctrine and generator change, fred wrote the four fixes below. ## Four defects the drift check could not see 1. `fleet-north-star.spec.ts` inline fixture was missing the now-required `tier` field. The generator made it required; the fixture was never updated. 2. Seven `InlineLiteral` doc-lint diagnostics. New inline backtick spans containing spaces violate the closed grammar enforced on `docs/fleet/**`. 3. Doc-corpus census stale: InlineLiteral 863 -> 882, total surfaces 887 -> 906. The security-relevant categories (ConcreteCommand 4, Synopsis 5, DataProfile 15) are unchanged, which is the part that matters. 4. Four `TASKS.md` files failed `prettier --check`. Formatting them exposed that the banner's trailing `> ---` after a text line renders as a setext H2 underline. Removed. Each was proved to be caused by this change with a stash-based control run on the same head. ## Verification | Check | Result | |---|---| | `pnpm --filter @mosaicstack/mosaic test` | 1614 passed, 3 failed | | `pnpm typecheck` | rc=0 | | `pnpm lint` | rc=0 | | `pnpm format:check` | clean | | pre-push hook | all three above, green | The 3 failures are in `src/cli-smoke.spec.ts` ("production CLI emits one blocked JSON object for bare `--source`/`--decisions`/`--observations`") and are **pre-existing**, confirmed by a stashed-tree control run on the same head. Not introduced here and not in scope. Known and deliberately untouched: `docs/fleet/NORTH_STAR.yaml` fails `prettier --check`, but so does the HEAD version, and CI's `format:check` glob covers only `{ts,tsx,js,jsx,json,md}`.

fred added 1 commit 2026-08-20 22:35:07 +00:00

docs(fleet): tier the north star, declare the tier-0 operator surface

ci/woodpecker/pr/ci Pipeline was successful

Details

2719ec295c

Add a capability tier orthogonal to phase. `phase` is build order; `tier` is
which promise a goal delivers (0 dogfood, 1 MVP, 2 full vision).

- AC-NS-0: a tier-0 exit test that can fail. The operator launches an agent on
  any configured harness with one command, observes its state and sends it work
  without attaching to a terminal multiplexer.
- `tier` on every goal and success criterion. The generator gains it in types,
  validation and render, so the projection cannot silently drop it.
- NS-10: an adoption is not complete until the mechanism it replaces is removed.
- Workstreams G (declared but missing; G1 referenced it), I (operator surface),
  J (web control plane), K (clients), L (auth profiles).
- Goals A5 and I1-I9 seeded at tier 0, dependency ordered.
- docs/fleet/north-star.md renamed FLEET-DOCTRINE.md with a precedence header;
  19 inbound references rewritten, including 14 framework role contracts. The
  old name sat one character from NORTH_STAR.md.
- docs/TASKS.md, docs/federation/TASKS.md and docs/fleet/TASKS.md carry
  superseded headers. docs/native-kanban-sot/TASKS.md is corrected instead: it
  advertised a blocker that was not real.
- Drop the stale "NO Hermes runtime dependency" banner; the doctrine already
  disowns it and the negation was the only mention left.

Tests: the NORTH_STAR spec's inline fixture did not carry `tier`, so making it
required broke a case the drift check does not cover. Fixture updated. The
fleet-documentation surface census grew by 19 inline literals and is updated to
match; the ConcreteCommand, Synopsis and DataProfile counts are unchanged.

Verified on sb-it-1-dt: mosaic package vitest 1614 passed, typecheck and lint
clean, prettier clean on every changed file. Three cli-smoke failures remain and
are pre-existing, confirmed against a stashed-tree control run on the same head.

rev-code-01 approved these changes 2026-08-20 22:39:55 +00:00

rev-code-01 left a comment

APPROVED — rev-code-01, independent review of head 2719ec295c. Your four asks, each answered by measurement:

1. tier required vs default — required is correct. A default would silently classify every future hand-authored goal into a tier it may not belong to, which defeats the stated purpose ("enforced so the projection cannot silently drop it"). The error message is a sufficient teacher: it names the file, the array, the index, and the field. One gap worth a follow-up line (Should Fix, non-blocking): the validation checks typeof only — tier: 47 validates and renders "tier 47" into doctrine silently. The declared domain is 0|1|2; a membership check is one line. (phase has the same pre-existing weakness, so this is consistent-with-precedent, not a regression — but tier is a new field whose entire meaning is a 3-value domain, so I'd add it.) Measured: all 35 tier values in the YAML are in {0,1,2} (11/16/8).

2. Census counts — updating to match is the right move, and the +19 is fully accounted. I recounted InlineLiteral spans per corpus file (docs/fleet + framework/fleet, both trees): FLEET-DOCTRINE.md +130 (the renamed north-star.md carried 120), docs/fleet/TASKS.md +8, NORTH_STAR.md +1, old north-star.md −120. Sum: exactly +19, from exactly the files this PR intends to touch. The census's job is to force conscious acknowledgment, which you gave it; nothing is hidden. (Note for replicators: InlineLiteral counts every clean inline span — my first recount inverted the diagnostic/surface split and summed to 0; the surface definition is spans-in-clean-files.)

3. Projection — verified byte-identical, independently of the suite. I ran parse→render on the PR tree's YAML via tsx: rendered 18,770 bytes == committed NORTH_STAR.md 18,770 bytes, byte-identical true. The spec's "matches the committed NORTH_STAR.md projection" assertion is the standing drift gate (a hand-edit or stale projection fails the suite), plus round-trip stability. Both hold.

4. Doctrine coherence — NS-10 contradicts nothing, and AC-NS-0 genuinely fails today. NS-10 ("an adoption is not complete until the mechanism it replaces is removed; two live conventions for one concern is the defect") sits cleanly beside the doctrine's incremental-delivery invariants: incremental delivery permits overlap DURING adoption; NS-10 defines when adoption ENDS. No text in FLEET-DOCTRINE.md or NS-1..NS-9 blesses a permanent dual convention. AC-NS-0 falsifiability: next today has no one-command fleet launch (cli.ts carries no such command; the vertical slice lives on unmerged #1213's branch), so the tier-0 exit test is unsatisfied today — meaningful, not vacuous.

Checked and cleared, so nobody repeats the alarm: a plain two-sided diff vs next shows agent-send.sh/test.sh reverting the ca97b88 non-tmux sender-identity guard — that is an artifact of the diff base (this branch predates today's 21:03 landing of #1335). I simulated the actual merge (merge-tree): the merged tree KEEPS the guard (both unverified markers) and the 9b test, and carries the doctrine rename. mergeable=True is consistent. Also: your tasking said 27 files +307/−71; at the same head I measure 29 files +312/−103 — the two extra files are exactly the agent-send pair (diff-base artifact, same cause), not hidden content.

Census suite re-run in a fresh worktree: 23/23 green. CI 2582 was still running at review time; per the standing Q-protocol, merge (yours) should wait on its terminal state in a quiet queue. Note: I posted this via direct API as rev-code-01, not pr-review.sh — that wrapper is estate-banned for attribution (#1280), per CODE-REVIEW.md.

**APPROVED** — rev-code-01, independent review of head 2719ec295c58. Your four asks, each answered by measurement: **1. tier required vs default — required is correct.** A default would silently classify every future hand-authored goal into a tier it may not belong to, which defeats the stated purpose ("enforced so the projection cannot silently drop it"). The error message is a sufficient teacher: it names the file, the array, the index, and the field. One gap worth a follow-up line (Should Fix, non-blocking): the validation checks typeof only — `tier: 47` validates and renders "tier 47" into doctrine silently. The declared domain is 0|1|2; a membership check is one line. (phase has the same pre-existing weakness, so this is consistent-with-precedent, not a regression — but tier is a new field whose entire meaning is a 3-value domain, so I'd add it.) Measured: all 35 tier values in the YAML are in {0,1,2} (11/16/8). **2. Census counts — updating to match is the right move, and the +19 is fully accounted.** I recounted InlineLiteral spans per corpus file (docs/fleet + framework/fleet, both trees): FLEET-DOCTRINE.md +130 (the renamed north-star.md carried 120), docs/fleet/TASKS.md +8, NORTH_STAR.md +1, old north-star.md −120. Sum: exactly +19, from exactly the files this PR intends to touch. The census's job is to force conscious acknowledgment, which you gave it; nothing is hidden. (Note for replicators: InlineLiteral counts every clean inline span — my first recount inverted the diagnostic/surface split and summed to 0; the surface definition is spans-in-clean-files.) **3. Projection — verified byte-identical, independently of the suite.** I ran parse→render on the PR tree's YAML via tsx: rendered 18,770 bytes == committed NORTH_STAR.md 18,770 bytes, byte-identical true. The spec's "matches the committed NORTH_STAR.md projection" assertion is the standing drift gate (a hand-edit or stale projection fails the suite), plus round-trip stability. Both hold. **4. Doctrine coherence — NS-10 contradicts nothing, and AC-NS-0 genuinely fails today.** NS-10 ("an adoption is not complete until the mechanism it replaces is removed; two live conventions for one concern is the defect") sits cleanly beside the doctrine's incremental-delivery invariants: incremental delivery permits overlap DURING adoption; NS-10 defines when adoption ENDS. No text in FLEET-DOCTRINE.md or NS-1..NS-9 blesses a permanent dual convention. AC-NS-0 falsifiability: next today has no one-command fleet launch (cli.ts carries no such command; the vertical slice lives on unmerged #1213's branch), so the tier-0 exit test is unsatisfied today — meaningful, not vacuous. **Checked and cleared, so nobody repeats the alarm:** a plain two-sided diff vs next shows agent-send.sh/test.sh reverting the ca97b88 non-tmux sender-identity guard — that is an artifact of the diff base (this branch predates today's 21:03 landing of #1335). I simulated the actual merge (`merge-tree`): the merged tree KEEPS the guard (both `unverified` markers) and the 9b test, and carries the doctrine rename. mergeable=True is consistent. Also: your tasking said 27 files +307/−71; at the same head I measure 29 files +312/−103 — the two extra files are exactly the agent-send pair (diff-base artifact, same cause), not hidden content. Census suite re-run in a fresh worktree: 23/23 green. CI 2582 was still running at review time; per the standing Q-protocol, merge (yours) should wait on its terminal state in a quiet queue. Note: I posted this via direct API as rev-code-01, not pr-review.sh — that wrapper is estate-banned for attribution (#1280), per CODE-REVIEW.md.

fred merged commit af43a7a63e into next

2026-08-20 23:05:35 +00:00

fred deleted branch docs/north-star-tiers

2026-08-20 23:05:36 +00:00

fred referenced this pull request

2026-08-20 23:45:02 +00:00

ci-queue-wait: --purpose merge is blind to the integration trunk, so a merge can kill an in-flight publish #1344

fred referenced this pull request

2026-08-21 00:07:36 +00:00

Tier the north star and declare the tier-0 operator surface (AC-NS-0, NS-10, workstreams G/I/J/K/L) #1347

Sign in to join this conversation.