mosaicstack/stack
14
0
Fork 1
Code Issues 315 Pull Requests 11 Actions Packages Projects Releases 15 Wiki Activity

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

New Issue
Closed
opened 2026-08-21 00:00:54 +00:00 by fred · 1 comment
fred commented 2026-08-21 00:00:54 +00:00
Collaborator
Copy Link
Copy Source

Problem

The north star describes what the fleet is for, but it cannot say which promise a given goal delivers, and it has no exit test that can fail. That has two consequences:

  1. There is no way to ask "what is the minimum that makes the operator's day work?" and get an answer from the document.
  2. phase is doing double duty. It encodes build order, and people read it as priority. Those are different questions and they diverge.

Alongside this, several live documents state statuses that the repo contradicts, and one advertises a blocker that does not exist. Stale docs do not merely fail to help an agent, they actively misroute one.

What this issue covers

Tiering the north star and declaring the tier-0 operator surface, plus the doc-neutralisation that goes with it.

  • 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 on every goal and criterion, orthogonal to phase (phase = build order, tier = which promise it delivers).
  • NS-10 — an adoption is not complete until the mechanism it replaces is removed.
  • Workstream G declared (goal 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 FLEET-DOCTRINE.md with a precedence header; 19 inbound references rewritten, 14 of them framework role contracts.
  • docs/TASKS.md, docs/federation/TASKS.md, docs/fleet/TASKS.md marked superseded. docs/native-kanban-sot/TASKS.md corrected instead — it advertised a false blocker, and superseding it would have hidden rather than fixed that.
  • Generator packages/mosaic/src/commands/fleet.ts gains tier in types, validation and render, so the projection cannot silently drop it.

Why the generator change is required, not incidental

NORTH_STAR.md is a projection of NORTH_STAR.yaml. Adding a field to the source without teaching the generator produces a document that is silently missing the field while the drift check still passes. The field has to exist in types, validation and render for the tier to survive the round trip.

Acceptance

  • tier present on every goal and criterion, and validated — a missing or invalid tier fails.
  • NORTH_STAR.md regenerates from the YAML with the drift check green.
  • No live doc states a status the repo contradicts.
  • No inbound reference to the old north-star.md filename survives.

Out of scope

The tier-0 implementation work (I1–I9) that this document declares. Tiering the north star is what makes those items nameable; building them is separate and follows.

Also out of scope: the docs/fleet/NORTH_STAR.yaml → docs/NORTH_STAR.yaml flatten. That is a different change with its own coupling — a hardcoded path in resolveNorthStarPaths() and a test pin at fleet-north-star.spec.ts:197-198 — and it gets its own PR.

## Problem The north star describes what the fleet is for, but it cannot say **which promise a given goal delivers**, and it has no exit test that can fail. That has two consequences: 1. There is no way to ask "what is the minimum that makes the operator's day work?" and get an answer from the document. 2. `phase` is doing double duty. It encodes build order, and people read it as priority. Those are different questions and they diverge. Alongside this, several live documents state statuses that the repo contradicts, and one advertises a blocker that does not exist. Stale docs do not merely fail to help an agent, they **actively misroute one**. ## What this issue covers Tiering the north star and declaring the tier-0 operator surface, plus the doc-neutralisation that goes with it. - **`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`** on every goal and criterion, **orthogonal to `phase`** (`phase` = build order, `tier` = which promise it delivers). - **`NS-10`** — *an adoption is not complete until the mechanism it replaces is removed.* - Workstream `G` declared (goal `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 `FLEET-DOCTRINE.md` with a precedence header; 19 inbound references rewritten, 14 of them framework role contracts. - `docs/TASKS.md`, `docs/federation/TASKS.md`, `docs/fleet/TASKS.md` marked superseded. `docs/native-kanban-sot/TASKS.md` **corrected instead** — it advertised a false blocker, and superseding it would have hidden rather than fixed that. - Generator `packages/mosaic/src/commands/fleet.ts` gains `tier` in types, validation and render, so the projection cannot silently drop it. ## Why the generator change is required, not incidental `NORTH_STAR.md` is a projection of `NORTH_STAR.yaml`. Adding a field to the source without teaching the generator produces a document that is silently missing the field while the drift check still passes. The field has to exist in types, validation and render for the tier to survive the round trip. ## Acceptance - `tier` present on every goal and criterion, and validated — a missing or invalid tier fails. - `NORTH_STAR.md` regenerates from the YAML with the drift check green. - No live doc states a status the repo contradicts. - No inbound reference to the old `north-star.md` filename survives. ## Out of scope The **tier-0 implementation work** (`I1`–`I9`) that this document declares. Tiering the north star is what makes those items nameable; building them is separate and follows. Also out of scope: the `docs/fleet/NORTH_STAR.yaml` → `docs/NORTH_STAR.yaml` flatten. That is a different change with its own coupling — a hardcoded path in `resolveNorthStarPaths()` **and** a test pin at `fleet-north-star.spec.ts:197-198` — and it gets its own PR.
fred closed this issue 2026-08-21 00:07:25 +00:00
fred commented 2026-08-21 00:07:36 +00:00
Author
Collaborator
Copy Link
Copy Source

Closing as already delivered. This issue should not have been filed — my error, and the reason is worth recording because it will repeat.

The work described here landed tonight in PR #1337, squash-merged to next as af43a7a6 at 23:05:35Z. Same branch, same head:

#1337 closed merged=True
head ref: docs/north-star-tiers  sha 2719ec295c
base: next   merge_commit: af43a7a63e

Verification that it is genuinely in next, not just claimed

Of the 27 files the branch touched, zero still differ from current origin/next:

git diff --name-only HEAD origin/next -- <the 27 files>   ->  0 lines

Independent controls, since an empty diff is exactly the result a broken command also produces:

Check on origin/next Result
tier: occurrences in NORTH_STAR.yaml 35
AC-NS-0 occurrences 2
docs/fleet/FLEET-DOCTRINE.md exists yes

How I filed a duplicate

I searched for an existing PR with pulls?state=all&limit=50 and got no match, so I concluded none existed. The Gitea API caps that page at 50 regardless of the limit value. #1337 was outside the first page.

The same cap bit me minutes later on the branch list — limit=200 returned 50, and the true total was 181 across 4 pages. I caught it there and paginated. I did not go back and re-run the PR search that had already given me a negative on the same flawed assumption. Catching a measurement error in one place and not sweeping for the same error in the others I had already made is the actual mistake here.

I also trusted a stale local refs/remotes/origin/docs/north-star-tiers ref as evidence the branch was on the remote. It was not — the branch had been deleted after the merge, which is normal. A local remote-tracking ref is not evidence of a remote branch; git ls-remote with a control is.

Cleanup done

I re-pushed the merged branch before realising, and have deleted it again (- [deleted] docs/north-star-tiers, verified absent with a passing control). No PR was opened. Nothing else was touched.

The tier-0 implementation items (I1–I9) that this document declares remain open work; they were never in this issue's scope.

**Closing as already delivered. This issue should not have been filed — my error, and the reason is worth recording because it will repeat.** The work described here **landed tonight** in PR #1337, squash-merged to `next` as `af43a7a6` at 23:05:35Z. Same branch, same head: ``` #1337 closed merged=True head ref: docs/north-star-tiers sha 2719ec295c base: next merge_commit: af43a7a63e ``` ## Verification that it is genuinely in `next`, not just claimed Of the **27 files** the branch touched, **zero** still differ from current `origin/next`: ``` git diff --name-only HEAD origin/next -- <the 27 files> -> 0 lines ``` Independent controls, since an empty diff is exactly the result a broken command also produces: | Check on `origin/next` | Result | |---|---| | `tier:` occurrences in `NORTH_STAR.yaml` | 35 | | `AC-NS-0` occurrences | 2 | | `docs/fleet/FLEET-DOCTRINE.md` exists | yes | ## How I filed a duplicate I searched for an existing PR with `pulls?state=all&limit=50` and got no match, so I concluded none existed. **The Gitea API caps that page at 50 regardless of the `limit` value.** #1337 was outside the first page. The same cap bit me minutes later on the branch list — `limit=200` returned 50, and the true total was 181 across 4 pages. I caught it there and paginated. **I did not go back and re-run the PR search that had already given me a negative on the same flawed assumption.** Catching a measurement error in one place and not sweeping for the same error in the others I had already made is the actual mistake here. I also trusted a stale local `refs/remotes/origin/docs/north-star-tiers` ref as evidence the branch was on the remote. It was not — the branch had been deleted after the merge, which is normal. **A local remote-tracking ref is not evidence of a remote branch;** `git ls-remote` with a control is. ## Cleanup done I re-pushed the merged branch before realising, and have deleted it again (`- [deleted] docs/north-star-tiers`, verified absent with a passing control). No PR was opened. Nothing else was touched. The tier-0 implementation items (`I1`–`I9`) that this document declares remain open work; they were never in this issue's scope.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) pepper rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1347