diff --git a/docs/plans/2026-10-15_organization-revision-read.md b/docs/plans/2026-10-15_organization-revision-read.md new file mode 100644 index 000000000..03bc122ef --- /dev/null +++ b/docs/plans/2026-10-15_organization-revision-read.md @@ -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.