docs: brief for the organization revision read (row 132 follow-up)

Researcher's row 132 build found that a role holding organization.change
must send the organization revision, and only the human's limits read
returns it. organization.set fails closed on a stale revision, so this is
a follow-up row, not a blocker for the 3d window.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
jason.woltjeandClaude Opus 5.5 committed 2026-10-15 12:59:59 -05:00
1 parent 346347c950
commit 26f4f97017
1 file changed
+58
@@ -0,0 +1,58 @@
# A role with organization.change can't read the revision it must send (2026-10-15)
Status: written by Sage, lead, from Researcher's row 132 build report
(sage-0355). It follows `docs/plans/BRIEF-TEMPLATE.md`. One row.
## Organization revision read for a role holding organization.change
### Problem
Row 123 (#1617, 89fd2d6fe) added `organization.set` for a role whose file
lists `organization.change`, and row 132 (#1628) gives the chief a typed
`change_organization` tool for it. The verb requires `revision`
(`packages/bus/src/broker.mjs` line 99, `ORGANIZATION_KEYS`, and line 732).
The only verb that returns the current revision is `limits`, and it refuses
anyone but the human: `if (!role && !s.human) fail("human-required")` at
line 729. So a role session can call `organization.set` only with a
revision it got some other way. A wrong or stale one fails closed with
`revision-conflict` (`packages/business/src/organization.mjs` line 185),
so nothing is damaged. The tool just can't be used on its own.
### Owner and reviewer
- Owner: assigned by Sage when the row is briefed.
- Reviewer: Filbert.
### Files owned
- `packages/bus/src/broker.mjs`, the `limits` / `organization.set` branch only
- `packages/bus/tests/` files that cover that branch
- `packages/harness/` files for the chief's tool, if the read becomes a tool
- the bus and harness READMEs, the paragraphs on these verbs only
### What ships
- A role session that holds `organization.change` can learn the current
organization revision before it calls `organization.set`. The owner
proposes the mechanism in the build packet. Two candidates: a read verb
limited to sessions whose role lists `organization.change`, or the
current revision returned with the `revision-conflict` refusal. The
read returns the revision only, not the limits, models or instances,
unless the brief is amended.
- A session without `organization.change` still gets no revision. Tests
show both cases, and mutants show each check is load-bearing.
- Reading the revision must not consume the `organization.change` grant.
- The bus, business and harness node suites and every
`scripts/test-*.sh` pass on the owner's gate.
### Out of scope
Any change to who may call `organization.set` or `limits.set`, to the
human `limits` read, or to `roles/*.json`. No schema change. If the chosen
mechanism needs any of these, the row stops and Sage takes it to Jason.
### Gate
Filbert approves on the row's issue naming the candidate manifest, and the
suites above are green on the owner's gate run. The row lands after row
132.