mosaicstack/stack
25
0
Fork 1
Code Issues 400 Pull Requests 13 Actions Packages Projects Releases 15 Wiki Activity

docs: briefs for the Q167 north-star rows 135-143 and the eight vikunja-19 landings

Browse Source 
Rows 135-143 are Vikunja P19 task 314 (Q167). The landing brief covers
Jason's merge decisions 29ff6589, 0eebf83f, 17bb9efc and 12a20e47, landed
through Sage rows as Mos relayed.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
jason.woltje
2026-10-15 17:15:02 -05:00
co-authored by Claude Opus 5.5
parent fc5b342f83
commit e37d6e5836
2 changed files with 542 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plans/2026-10-15_q167-north-star-rows.md
+427
View File
@@ -0,0 +1,427 @@
# Q167: the Stack runs from a north star (2026-10-15)
Status: written by Sage, lead, for Vikunja P19 task 314. It follows
`docs/plans/BRIEF-TEMPLATE.md`, one `##` heading per row. The plan went to
Mos as sage-0376. Mos answered Q4 and Q5 on 2026-10-15 at about 22:07Z:
agents land into the business working repository's protected branch
through the host, and canonical `refactor` stays Sage's landing. Q167
covers shrinking GATED_ONLY and the role grants through rows 135 and 139.
Jason's ruling, as Mos relayed it: "Me having to approve every decision
within the Stack is not working for me. I gave a directive, I want it to be
done." and "Use the T3 seats to make these updates and changes, so I can
have a functional system."
Hard waits stay with Jason. This list matches Jason's waits list as Mos
gave it: spending money, deleting data, anything irreversible, new internet
exposure, new external accounts, messages to people outside the fleet, and
force-push or history rewrite. Also gated to Jason: any change to the
hard-waits list itself, and any grant of a hard-wait action to a role. No
row below may weaken that.
Each row's suites: the bus, business, harness and cli node suites as the
row touches them, plus every `scripts/test-*.sh`, green on the owner's gate.
For each new check, a mutant that removes it fails a test. Code-only rows go live in any
re-pin after the 3e window, each with Mos's go. Rows 138 and 141 change the
schema and each gets its own window, one schema step per window. The gap
rule from `agents/sage/work/window-plan/schema-chain-3c-3e.md` applies to
each window: no land-work against the live bus between a schema landing and
its migration.
## PRD 1.5 under Q167: north-star specs, agent decisions and hard waits
### Problem
The PRD routes every gated decision to the human (REQ-DEC-2), and
GATED_ONLY in `packages/business/src/vocabulary.mjs` holds policy.change,
prd.approve and git.merge.protected, so no role file can grant them. Of
the 16 decisions the Stack routed on 2026-10-15, all went to Jason and none
to an agent. The PRD has no requirement for a north-star spec, for spec
versions, for agent landing, for name addressing or for agents reviewing
Jason's proposals.
### Owner and reviewer
- Owner: Sage. Q167 makes Jason's confirmation the approval, so there is
no in-Stack prd.approve for this version.
- Reviewer: Filbert.
### Files owned
- `docs/prd/mosaic-stack.md`, as a new version 1.5 with a source block
quoting Jason. It is never edited in place.
- `docs/acceptance/314.md`, the acceptance script Jason runs.
### What ships
- REQ-DEC-2 replaced: a decision the business's current north-star spec
covers goes to the arbiter for its domain. Only a decision the spec does
not cover, or a hard wait, goes to Jason.
- A hard-waits requirement naming the list above, with the action each
maps to, including new ones for deleting data, new internet exposure and
new external accounts. git.push.protected covers force-push and history
rewrite.
- Requirements for: the north-star spec per need, kept by the assistant
with Jason; spec versions that never reopen a settled decision; approvals
that outlive the run; agent landing into the business working repository;
pm asking chief for staff; messages addressed by agent name; agents
reviewing Jason's proposals and returning blocks; the assistant
summarizing instead of relaying.
- The acceptance script, as sent to Mos in sage-0376 and corrected in
sage-0377.
### Out of scope
Code. Every behaviour change is in rows 136 to 143.
### Gate
Filbert approves on the row's issue naming the candidate manifest. The row
lands after 297's PRD 1.4.
## Approvals bind to the decision and the role instance, not the run
### Problem
An approved decision can be consumed only by the run that raised it:
`#checkAuthority` in `packages/bus/src/broker.mjs` requires
`d.raised_by_run === s.run` (line 600), and decision.raise's supersede
requires `old.raised_by_run === s.run` (line 1044). Any restart starts a
new run, so every approval dies with the run that raised it.
### Owner and reviewer
- Owner: Dewey.
- Reviewer: Filbert.
### Files owned
- `packages/bus/src/broker.mjs`, `#checkAuthority` and the supersede check
in decision.raise only
- `packages/bus/tests/` files covering them
- `packages/bus/README.md`, the paragraphs on consuming a decision
### What ships
- A resolved decision is consumable by any run of the same business and
the same role instance (`s.role`, the key in the business's roles map).
When the raising run held a thread, the consuming run must hold the same
thread.
- It is consumable once. If the bus does not already refuse a second
consumption, it does now, from the recorded action.allowed for the
decision, with a refusal code named in the README.
- Supersede follows the same rule: the same role instance, and the old
decision still open.
- role.revoke keeps its holderRun check.
- Every other check in `#checkAuthority` stays.
- Tests: approve, end the run, a new run of the same instance consumes it;
a second consumption refuses; another instance refuses; a run in another
thread refuses; supersede from a later run of the same instance works and
from another instance refuses.
### Out of scope
Schema changes, routing, and anything in land-work. If the change needs a
schema step, the row stops and tells Sage.
### Gate
Filbert approves on the row's issue naming the candidate manifest; bus
suite and every `scripts/test-*.sh` green on the owner's gate.
## Agents land approved merges into the business working repository
### Problem
No role can land a merge. git.merge.protected is in GATED
(`packages/bus/src/broker.mjs` line 32) and GATED_ONLY, and land-work
(`scripts/land-work.sh`, row 116) runs only from a conductor checkout into
canonical `refactor`. The host's git socket (`packages/cli/src/git-socket.mjs`)
already carries push and fetch for coder and reviewer runs, checked by the
broker.
### Owner and reviewer
- Owner: Darkwing.
- Reviewers: Filbert and Dewey.
### Files owned
- `packages/cli/src/git-socket.mjs` and the host code it calls
- a shared module for land-work's checks and gate, moved out of
`scripts/land-work/` only as far as both callers need
- `packages/bus/src/broker.mjs`, the authority check for the new op only
- tests in `packages/cli/tests/`, `packages/bus/tests/` and
`scripts/test-*.sh` for the above
- docs/TOOLS.md and package READMEs, the paragraphs on landing
### What ships
- A `land` op on the host git socket. The run that holds an approved
git.merge.protected decision (row 136 lets a later run of the same
instance use it) asks the host to land the work ref the decision names
into the business working repository's protected branch.
- The host runs the same checks land-work runs today: the decision is
resolved with the approval option, the ref is at the reviewed commit, a
verdict approves it, it is not superseded, the base hasn't moved, no root
file, and the gate passes. Any refusal is an action.refused on the task's
trail with land-work's code.
- A landing is recorded as the action.allowed for git.merge.protected with
the landed commit, and consumes the decision.
- The sandbox binds the op only for a role that holds a resolved merge
decision, the same way push and fetch are bound today.
- Canonical `refactor` is never a target. land-work.sh keeps working for
Sage's landings.
### Out of scope
Routing (row 139), GATED_ONLY and role grants (row 139), and any push to a
remote. Force-push or history rewrite stays impossible.
### Gate
Filbert and Dewey approve on the row's issue naming the candidate manifest;
bus, cli and harness suites and every `scripts/test-*.sh` green. Needs row
136 done.
## North-star specs with versions that don't reopen settled decisions
### Problem
The Stack has no place for Jason's north star per need. Decisions carry no
reference to what covered them, so nothing can say a decision was settled
under an earlier spec.
### Owner and reviewer
- Owner: Rocko.
- Reviewer: Dewey.
### Files owned
- `packages/bus/src/store.mjs`, the 3e to 3f step and its migration
- `packages/bus/src/broker.mjs`, the spec verbs and the decision columns
- `packages/business/src/vocabulary.mjs`, one new within-role action for
the assistant
- `roles/assistant.json` and `roles/assistant.md`, the grant and the
contract text for it
- `packages/cli/src/` for a human confirm verb, and tests in each package
- MIGRATION.md in the row's packet, package READMEs
### What ships
- A specs table: per business, a spec id per need, versions of text,
who proposed each and when the human confirmed it.
- The assistant proposes a version within-role. It takes effect only when
the human confirms it through the mosaic CLI, under REQ-DEC-3's rule
that a human action comes only from a CLI session outside any run.
- decisions gain spec_id and spec_version, set when a raise cites a spec.
A decision settled under version N stays settled when N+1 takes effect.
Nothing reopens it.
- A read verb any role instance of the business can call for the current
version of a spec.
- Migration 3e to 3f preserves every existing row, tested on a copy of a
3e store, with the steps written for the window.
### Out of scope
Routing on the spec (row 139). Any change to who may resolve a decision.
### Gate
Dewey approves on the row's issue naming the candidate manifest; bus,
business and cli suites and every `scripts/test-*.sh` green; the migration
tested on a 3e copy. Lands in its own window after 3e is live.
## Decisions the spec covers go to an agent; only hard waits reach Jason
### Problem
`classify` (`packages/business/src/resolve.mjs` line 99) and
`#classification` (`packages/bus/src/broker.mjs` line 447) make anything a
role isn't granted "gated", and decision.raise routes gated to the human
(line 1036). GATED_ONLY holds policy.change and prd.approve, which caused 9
of the 16 decisions sent to Jason on 2026-10-15.
### Owner and reviewer
- Owner: Dewey.
- Reviewer: Filbert.
### Files owned
- `packages/business/src/vocabulary.mjs`, GATED_ONLY and the new hard-wait
actions
- `packages/bus/src/broker.mjs`, GATED and decision.raise routing
- `roles/*.json`, grants only as the PRD 1.5 text requires
- tests in the bus and business packages, and READMEs
### What ships
- GATED and GATED_ONLY become the hard-waits list from PRD 1.5 and nothing
else, with new actions for deleting data, new internet exposure and new
external accounts.
- A decision.raise that cites a confirmed spec version covering it routes
to the business's arbiter for its domain, never to the human, unless the
action is a hard wait.
- A hard wait always routes to the human, spec or no spec. A change to the
hard-waits list or a grant of a hard-wait action is itself a hard wait.
- Tests for each hard wait, for a spec-covered merge going to the arbiter,
and for an uncovered decision still going to the human.
### Out of scope
Who may confirm a spec (row 138). The landing mechanism (row 137).
### Gate
Filbert approves on the row's issue naming the candidate manifest; bus and
business suites and every `scripts/test-*.sh` green. Needs rows 135, 136
and 138 done.
## pm asks chief for staff, and chief hires and launches
### Problem
pm can't ask for workers in any typed way, and chief has no contract text
for answering such a request. Q164 and Q165 set chief as the launcher.
### Owner and reviewer
- Owner: Researcher.
- Reviewer: Filbert.
### Files owned
- `roles/pm.md`, `roles/chief-of-staff.md`, contract text only
- `packages/bus/src/broker.mjs` and `packages/business/src/vocabulary.mjs`
for a staff request message class, if one is needed
- `packages/harness/` for a typed tool, if one is needed
- tests and READMEs for the above
### What ships
- pm sends chief a staff request naming roles and counts for a task.
chief launches through role.launch within its limits and answers with
the instances it launched or a refusal and the reason.
- Tests show the request reaches chief only from pm, and that chief's
launch stays inside the organization's limits.
### Out of scope
Role grants beyond the PRD 1.5 text, and capacity limits.
### Gate
Filbert approves on the row's issue naming the candidate manifest; the
touched suites and every `scripts/test-*.sh` green.
## Messages are addressed by agent name
### Problem
REQ-MSG-1 addresses a message to a role. Q166 and pm's in-Stack decision
623b1665 (resolved yes by Jason, 21:45:23Z) ask for agent names. Mos's
decision 28a5782d note: decision 109 notices go to the assistant until
messages can be addressed by agent.
### Owner and reviewer
- Owner: Darkwing.
- Reviewer: Filbert.
### Files owned
- `packages/bus/src/store.mjs`, the 3f to 3g step and its migration
- `packages/bus/src/broker.mjs`, message.send and the instance records
- `packages/cli/src/cli.mjs` and the harness tool for message.send
- tests and READMEs
### What ships
- Each instance has a name. message.send takes a name or a role; a role
still delivers as today.
- Migration 3f to 3g preserves every row, tested on a copy of a 3f store.
### Out of scope
Thread routing beyond what names need.
### Gate
Filbert approves on the row's issue naming the candidate manifest; touched
suites and every `scripts/test-*.sh` green; the migration tested on a 3f
copy. Lands in its own window after 3f is live.
## mosaic talk prints only the reply to its own message
### Problem
`talk` in `packages/cli/src/cli.mjs` (lines 240 to 244) prints and marks
read every message in the human's inbox while it waits, not only the reply
to the message it sent.
### Owner and reviewer
- Owner: Researcher.
- Reviewer: Filbert.
### Files owned
- `packages/cli/src/cli.mjs`, `talk` only
- `packages/cli/tests/` for talk
- docs/TOOLS.md, the talk paragraph
### What ships
- Without --follow, talk prints only the reply whose in_reply_to is the
sent message, marks only that read, and leaves the rest unread for
`mosaic inbox`. --follow and `mosaic follow` keep today's behaviour.
- Tests: another role's message during the wait stays unread and unprinted.
### Out of scope
The bus. Row 128's named threads.
### Gate
Filbert approves on the row's issue naming the candidate manifest; cli
suite and every `scripts/test-*.sh` green.
## Agents review Jason's proposals, and the assistant summarizes
### Problem
Jason's proposals go straight to work with no agent check against the
spec, and the assistant relays chief's text word for word: of 49 messages
to the human on 2026-10-15, 24 came from the assistant, mostly repeats.
### Owner and reviewer
- Owner: Rocko.
- Reviewer: Dewey.
### Files owned
- `roles/assistant.md`, `roles/pm.md`, `roles/cto.md`, contract text
- `packages/bus/src/broker.mjs` and `packages/business/src/vocabulary.mjs`
for PROPOSAL and BLOCK message classes, if needed
- tests and READMEs
### What ships
- The assistant sends a proposal from Jason to pm or cto as a PROPOSAL.
The receiver checks it against the current spec and answers with a BLOCK
naming the conflict, or an accept. The assistant returns the answer to
Jason in its own words.
- The assistant contract says to summarize chief's text and not repeat it.
- Tests for the classes and the routing, and a contract text test.
### Out of scope
The spec store (row 138) and routing (row 139).
### Gate
Dewey approves on the row's issue naming the candidate manifest; touched
suites and every `scripts/test-*.sh` green.
docs/plans/2026-10-15_vikunja-19-landings.md
+115
View File
@@ -0,0 +1,115 @@
# Landing the eight approved vikunja-19 merges (2026-10-15)
Status: written by Sage, lead. It follows `docs/plans/BRIEF-TEMPLATE.md`,
one `##` heading per row. Jason approved eight merge decisions in the
mosaic-stack business through the CLI:
- 29ff6589 `all`: 295, 297, 302 and 301
- 0eebf83f `all`: 305 and 306
- 17bb9efc `merge`: 307
- 12a20e47 `merge`: 309
Mos relayed the landing instruction on 2026-10-15: land them through
Sage's own landing procedure into canonical `refactor`, as Sage rows, not
through land-work. Rebase the ones that conflict and the stacked ones, and
Filbert reviews each rebased diff. No new Jason decision is needed unless a
rebase changes behavior beyond conflict resolution; if one does, Sage stops
and tells Mos. Mos gave a standing push go for these eight, after a green
gate and the usual push checks, in one push. Live re-pins still wait on
Mos's go.
Decision 123 go for 302's `public/` diff covers it as it is at abda248a8:
`app.js` adds `busDown()`, which fetches `/api/bus-status` and writes
through `node()`, and `node()` uses `textContent` via `inert()`.
`index.html` adds one hidden `#bus-down` div. If the landing changes any
other `public/` line, Sage asks Mos again.
land-work can't take these. It lands one work ref per decision, and
29ff6589 names four (the read check on 2026-10-15 refused `work-ref`).
The commits were built in the business working repository and fetched into
canonical by object id, with no refs. All eight branch from 07c12b51b,
which is on `refactor`.
| Task | Branch | Commit | Shape |
|------|--------|--------|-------|
| 297 | `work/vikunja-19-297` | b3dd8de83 | 3 commits, PRD 1.4 text; applies cleanly |
| 302 | `work/vikunja-19-302` | abda248a8 | 1 commit; applies cleanly |
| 301 | `work/vikunja-19-301` | bbf61d6dd | 1 commit; applies cleanly |
| 306 | `work/vikunja-19-306` | 3c80fea74 | stacked on 301 |
| 295 | `work/vikunja-19-295` | 813671596 | 7 commits, includes 296; conflicts on `packages/harness/src/tools.mjs` |
| 307 | `work/vikunja-19-307` | 6219c5c8c | stacked on 295 |
| 305 | `work/vikunja-19-305` | f4d7b91a9 | stacked on 295; conflicts on `packages/bus/src/broker.mjs` |
| 309 | `work/vikunja-19-309` | 0e7d1d8b8 | stacked on 305 |
## Land the approved vikunja-19 merges that apply cleanly
### Problem
Tasks 297, 302 and 301 are approved and apply to `refactor` without
conflict, but they are not in canonical.
### Owner and reviewer
- Owner: Sage.
- Reviewer: none. The business reviewer approved each commit, Jason
approved each merge, and the diff lands unchanged.
### Files owned
The files each commit changes from 07c12b51b, as they are in the commit.
### What ships
- One canonical commit per task, in the order 297, 302, 301. Each applies
`git diff 07c12b51b <commit>` unchanged and names the task, branch,
source commit and decision.
- Each commit passes the suites for the files it touches.
- 302's `public/` lines match abda248a8 byte for byte.
- The row's landing comment on its issue names each landed commit and gate.
### Out of scope
Any change to the diffs. Any live re-pin.
### Gate
The applicable suites green for each commit; Sage's full gate before the
push; the push checks; one push with the other row.
## Rebase and land the stacked and conflicting vikunja-19 merges
### Problem
Tasks 306, 295, 307, 305 and 309 are approved but stacked on each other or
in conflict with `refactor` on `packages/harness/src/tools.mjs` and
`packages/bus/src/broker.mjs`.
### Owner and reviewer
- Owner: Sage.
- Reviewer: Filbert, on each rebased diff.
### Files owned
The files each commit changes from its parent task, as rebased.
### What ships
- One canonical commit per task, in the order 306, 295, 307, 305, 309.
306 applies `git diff bbf61d6dd 3c80fea74`. 295 applies its seven
commits as one. 307, 305 and 309 each apply their own commit on top.
- Conflict resolution only. A resolution that changes behavior beyond
merging both sides stops the row, and Sage tells Mos.
- The candidate shows each rebased diff and, for each conflict, both
sides and the resolution.
- The row's landing comment on its issue names each landed commit and gate.
### Out of scope
Any change beyond conflict resolution. Any live re-pin.
### Gate
Filbert approves on the row's issue naming the candidate; Sage's full gate
before the push; the push checks; one push with the other row.