docs: row brief for adding and changing role instances (P19 332, #1662); I6 brief records Jason's P19 333 ruling

Mos relayed Jason's answers in mos-0787. P19 332: a CLI command and a
Console view for role-instance changes, held until Jason confirms Mos's
reading. P19 333: accepted as a documented limit, so the I6 brief and the
design's limits line now say I6 writes it as a known limit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
jason.woltjeandClaude Opus 5.5 committed 2026-10-18 13:10:41 -05:00
1 parent d62c61fbd8
commit ab9f23d9ef
3 files changed
+137 -3

No files matched your search

@@ -1014,7 +1014,8 @@ writes them.
Jason's uid also passes directly, through the relay or through the
engine (decisions 95 and 105, section 5). The other-uid half of this
line waits on Jason's answer, P19 333 (section 5). I6 writes what
Jason rules. REQ-DEC-3 holds against agent containers and against
Jason rules. Correction, 2026-10-18: Jason accepted it as a documented
limit (mos-0787), so I6 writes it as a known limit. REQ-DEC-3 holds against agent containers and against
accidental or inherited launches.
- **The rootful daemon.** Jason is in the `docker` group, so any host
process under Jason's uid can reach the rootful daemon, which is
@@ -444,8 +444,10 @@ and no document states the limits in design section 10.
- The install section of the README: the steps, the config key, and
every limit in design section 10, each with its decision number. The
other-uid half of the host-process limit says what Jason ruled on
P19 333. If Jason hasn't ruled when I6 reaches that section, the row
waits on it.
P19 333: he accepted it as a documented limit (mos-0787, 2026-10-18).
So the limits section states it as a known limit: a host process under
another uid that reaches the Console's loopback port acts as Jason, and
nothing in the install closes that. Sage closes P19 333 when I6 lands.
`LAYERS.md` L4 and `CONDUCTOR.md:17,40` describe what is built.
- Tests:
- the whole install starts and stops cleanly, and leaves no container
+131
View File
@@ -0,0 +1,131 @@
# Adding and changing role instances without editing the file, 2026-10-18
Status: written by Sage, lead, on Mos's relay mos-0787 of Jason's answer
to P19 332. Line numbers are at d62c61fbd. It follows
`docs/plans/BRIEF-TEMPLATE.md`, one `##` heading per row.
Jason's answer, verbatim: "I want a command and a WebUI surfacing for the
modifications".
Mos's reading, which Jason hasn't confirmed yet: Jason wants to add and
change role instances through a `mosaic` CLI command and a Console view
instead of hand-editing the business file. That is the pattern of Q169
(`docs/plans/2026-10-16_q169-assistant-config.md`). Gitea #1662.
**Hold.** The row stays queued and nobody builds it until Mos relays
Jason's confirmation of that reading. If Jason reads it differently, Sage
rewrites this brief first. Until the row lands, acceptance 314 stays as
written (`docs/acceptance/314.md:27-29`): Jason adds the
security-reviewer and merge-gate instances by editing the business file.
## The human adds and changes role instances
### Problem
What exists at d62c61fbd:
- No verb adds a role instance. The organization writers change only
what exists: `packages/business/src/launch-settings.mjs:46-52` sets
`vars.model` on an instance and refuses one the file doesn't declare,
and `packages/business/src/business.mjs:130` refuses a
`launch.instances` entry the file doesn't declare. Row 141's names
table and row 155's assistant writer don't add instances either.
- So staffing a role the file doesn't declare means editing
`~/.config/mosaic-dev/businesses/<id>.json` by hand, with no revision
check, no actor and no change record. Acceptance 314 does this today.
- The safe write path exists. `organizationWriter().write`
(`packages/business/src/organization.mjs:177-219`) takes the file's
revision and an actor, refuses a stale revision with
`revision-conflict`, validates the document with
`validateBusinessDocument` before and after serialization, and appends
prepared and committed entries with the actor, the before and after
hashes and the changes to `businesses/.history/<id>/changes.jsonl`.
- `mosaic business validate` (`packages/business/src/cli.mjs:64`) runs
`loadBusiness`, which calls `validateBusinessDocument`, and then
resolves every instance against every project file.
### Owner and reviewer
- Owner: Darkwing, after row 155, which changes the same writers, CLI
and Console settings view.
- Reviewers: Dewey, for security, and Filbert.
### Files owned
- `packages/business/src/`: one new instance writer beside
`launch-settings.mjs`, built on `organizationWriter().write`.
- `packages/cli/src/`: the human's command below.
- `packages/webui/src/serve.mjs` and `packages/webui/src/public/`: the
Console view and its routes.
- Tests in those packages, the webui browser tests, the business and cli
READMEs, and `docs/TOOLS.md`.
- `docs/acceptance/314.md`, only to replace the hand edit with the
command once the row lands.
### What ships
1. A role instance here is one entry under the business file's `roles`,
plus its place in `launch.instances`. The human can:
- add an instance: a new id, a `definition` from `roles/`, its `vars`,
and whether it goes into `launch.instances`;
- change an existing instance's `definition` and `vars`, and add it to
or remove it from `launch.instances`.
`holder`, `credentials` and `tracker` stay out of this row. Deleting
an instance from the file is out of scope.
2. The CLI command is under `mosaic business` (the owner proposes the
verb and flags in the packet before any code). The Console gets a
view that lists instances and a form for the same two operations.
Both carry the file's revision, and a stale one is refused with
`revision-conflict`.
3. Only the human. The CLI command needs the human proof the other
organization writers use, and the Console routes need the signed-in
human. No role, the chief of staff included, gets a tool or a grant
for this in this row. Jason hasn't ruled on the chief of staff, so
that waits for him.
4. Validation goes through the same path as `mosaic business validate`.
The writer refuses any document that `validateBusinessDocument`
refuses, and any document in which an instance doesn't resolve
against a project file, the check `validate` runs after loading. A
write that lands always leaves a file that `mosaic business validate`
accepts. The writer can't change any instance's definition to one in
`END_PROTECTED` or remove the assistant's protection; row 155's rule
holds here too.
5. Each change writes an audit entry through the writer's change log:
the actor, the business, the before and after hashes and the changed
keys. The CLI prints the new revision and the transaction id.
6. A change reaches a running bus the way row 141's and row 155's
changes do. The packet says which reads pick it up and whether
anything needs a bus restart.
Tests:
- the CLI and the Console add an instance; `mosaic business validate`
then exits 0 and the change log has the human as actor;
- changing an instance's definition, vars and launch membership
succeeds and logs before and after;
- each `validateBusinessDocument` refusal and an unresolvable instance
are refused, and the file's bytes don't change;
- a stale revision is refused;
- a call without the human proof, and any role's attempt, are refused;
- a definition change into `END_PROTECTED`, or one that strips the
assistant's protection, is refused.
Mutants: one per behavior above, with the killing test in the packet.
### Out of scope
Deleting instances. Changing `holder`, `credentials` or `tracker`. Any
chief of staff tool or grant, until Jason rules. Editing the
repository's role files in `roles/`, which change only through reviewed
commits. Any live change: the row goes live through a re-pin with Mos's
go.
### Gate
- Mos relays Jason's confirmation before the row moves to briefed.
- Dewey and Filbert approve on the row's issue naming the candidate
manifest.
- Mos's decision 123 go on the `public/` diff.
- Business, cli and webui suites and every `scripts/test-*.sh` green on
Sage's gate.
- Needs row 155 done.