docs: roles design review fixes (#1873)

Route merge, policy, hire, fire and credential decisions to the human and
keep merge and policy cross-role only. A person-started hire is a decision
record. Restructure the usability table by who acts, list template roles
explicitly, add the arbiter threat row and slice tests.
This commit was merged in pull request #1903.
This commit is contained in:
jason.woltje committed 2026-11-10 15:00:43 -06:00
1 parent c6e341e92e
commit f98f278fbb
1 file changed
+52 -27
+52 -27
View File
@@ -79,7 +79,7 @@ the code enforces it today and which slice closes the gap.
| R2 | The trail and run records are write-once. | `events` and `decision_events` refuse update, delete and replace (`packages/bus/src/migrations/3b.sql:131-132,137-138,144,147`). | None. Hire, deny, expiry and binding entries use the same tables (A4). |
| R3 | Fail closed: an unknown action, tool, right, plugin kind or role field refuses. | Role keys, actions and tools (`role.mjs:190,42,24-29`). Rights (`org-rights.mjs:122-129`). Plugin kinds (`packages/plugins/src/kinds.mjs:147-148`). | Inline roles and plugin-declared tools and actions have no check yet. P1 and PL1. |
| R4 | Hard waits stay with the human. A role can never hold an action outside `ROUTED`. | `vocabulary.mjs:109`, `role.mjs:43`. This covers `git.push.protected`, `git.push.remote`, `host.sudo`, `credential.mint`, `spend`, `deploy` and `data.delete` (`vocabulary.mjs:22,26,29,49,50,51,55`). | Added: the brief's list did not name it, and "any capacity" must not dissolve it. P1 keeps it for every composition. |
| R5 | Human-only acts: approving a hire or fire (`org.hire`), binding a credential, changing personality after hire, installing a plugin, enabling one, and changing a rail. No agent approves its own request. | No agent resolves its own arbitrated raise: it goes to the human (`broker.mjs:7075`). Plugin enabling needs a human session (`broker.mjs:6008`). | Corrected. An agent does resolve another agent's request today: a cross-role raise goes to the domain arbiter, the chief by default, and that role resolves it (`broker.mjs:7074,7212-7215`, `packages/organization/src/org-template.json:5`). That stays for routed work. Every act in this row instead routes to the human, whatever its class (A4). Also corrected: `git.merge.protected` and `policy.change` are routed, so a role may hold them today (`vocabulary.mjs:83,93`). Under this design they appear as flagged lines when a hire carries them. The dev tester may enable some plugin kinds (`broker.mjs:6013`); that stays dev-only. Personality has no field yet (T1). |
| R5 | Human-only acts: approving a hire, fire or role change (`org.hire`), binding a credential, changing personality after hire, installing or enabling a plugin, changing a rail, and resolving a merge or policy decision. No agent approves its own request, and no agent approves a request that changes authority. | No agent resolves its own arbitrated raise: it goes to the human (`broker.mjs:7075`). Plugin enabling needs a human session (`broker.mjs:6008`). Hard waits always go to the human (R4). | Corrected. The brief's "no agent approves another agent's request" is false today. A cross-role raise goes to the domain arbiter, the chief by default, and an agent of that role resolves it (`broker.mjs:7074,7212-7215`, `packages/organization/src/org-template.json:5`). PRD 1.5 REQ-DEC-2 put `git.merge.protected` and `policy.change` on that path (`vocabulary.mjs:69-70,83,93`), and merge-gate holds merge cross-role (`roles/merge-gate.json:10`, `broker.mjs:5198-5201`). This design keeps agent arbitration only for one-off routed work that grants no lasting authority: task, review, record and message actions. A4 routes every decision whose action is `role.hire`, `role.fire`, `credential.mint`, `git.merge.protected` or `policy.change` to the human, whatever its class. That reverses part of REQ-DEC-2, so it needs Jason's approval. The dev tester may enable some plugin kinds (`broker.mjs:6013`); that stays dev-only. Personality has no field yet (T1). |
| R6 | Every agent runs sandboxed as the instance uid, with only the tools its role names. A tool exists only if core or an installed, enabled plugin declares it. | bwrap with user, pid and ipc namespaces and a read-only root (`packages/seat/src/sandbox.mjs:76,176`). Tools are a closed core list (`vocabulary.mjs:142`) and the typed bus tools are fixed in core (`packages/harness/src/tools.mjs:96`). | Corrected: no plugin declares a tool today. PL1 adds plugin-declared tools. A sandbox escape holds the instance uid, which equals root for the instance (accounts design, "Host trust boundary"). |
| R7 | Organizations are isolated. Cross-organization reads go only through the assistant's Console read broker. | Each organization has its own bus and every non-assistant agent's scope is one organization (agent-levels design section 4). | The read broker is not built. It is A6. Until then nothing reads across organizations. |
| R8 | No grant beyond the granter, except through a flagged line in a human-approved decision. | People: `canGrant` subset (`org-rights.mjs:122-129`). Agents: a hire is bounded by `HIRE_ALLOWED` and the chief's list (`broker.mjs:6303-6305`). | A4 replaces that bound with the approval itself. The broker computes the flagged lines; the chief cannot omit them. |
@@ -125,9 +125,11 @@ replaces `HIRE_ALLOWED` and `unhireableAction` at hire time. It:
organization;
3. refuses any action outside `ROUTED` or a plugin's routed set (R4);
4. refuses `role.hire` and `role.fire` (R9);
5. refuses any string that fails `assertClean` (R1), and any field over its
5. allows `git.merge.protected` and `policy.change` only in `crossRole`, so
each use is its own decision that a human resolves (R5);
6. refuses any string that fails `assertClean` (R1), and any field over its
length bound;
6. returns the flagged lines: every action, tool, network, credential scope
7. returns the flagged lines: every action, tool, network, credential scope
and messaging target the chief's own resolved role does not hold (R8).
The validator accepts every composition that passes. There is no allowlist of
@@ -174,8 +176,10 @@ their own `definitions` in `<configDir>/agents.json`.
frozen: nothing changes it except an approved change.
- **Customize** edits the copy. **Invent** writes a definition with no `from`.
Both pass `checkComposition` before they are written.
- **Who writes.** A human holding `org.hire` writes directly in the Console.
The chief proposes a definition only inside a hire or change decision.
- **Who writes.** A human holding `org.hire` drafts or edits a definition in
the Console. A draft no agent uses does nothing. A change to a definition a
hired agent uses takes effect only through a change decision (section 6).
The chief proposes a definition only inside a decision.
- **Template changes.** When a template's current hash differs from a copy's
`from.sha256`, the Console shows a diff and offers apply or keep. Apply is a
change decision (section 6). Nothing applies by itself (ruling 11).
@@ -213,8 +217,8 @@ The broker adds, and the chief cannot set or edit:
already checks (`broker.mjs:7200-7204`);
- `expiresAt`: seven days.
**Raise.** Only the instance in `launch.by` may raise one, as today
(`broker.mjs:6193`). The decision always routes to the human, whatever its
**Raise.** Among agents, only the instance in `launch.by` may raise one, as
today (`broker.mjs:6193`). The decision always routes to the human, whatever its
class, so the arbiter path at `broker.mjs:7074` never applies. A hire needs no
approval count and has no cap (ruling 3). Spend stays bounded by the
organization's limits.
@@ -250,8 +254,13 @@ for an approved hire.
The chief may withdraw its own decision (`broker.mjs:7205-7211`).
**Fire and change** are the same decision with `op` set. Fire revokes and
delists as today (`instance-settings.mjs:396`). A human holding `org.hire` may
also hire, fire or change directly in the Console without a chief decision.
delists as today (`instance-settings.mjs:396`).
**A person starting a hire.** A human holding `org.hire` may start a hire,
fire or change in the Console. It is still a decision, with the same fields,
broker-computed lines, digest and trail, raised and resolved in one step by
that person. Flagged and credential lines still need the owner. I read ruling
8 as limiting which agent raises hires, not as stopping a person from hiring.
**Trail.** Raise, each resolution, the writer receipt and each binding are
events in the write-once tables (R2).
@@ -317,23 +326,29 @@ needs, each citing the plan in its reason. It starts with the fewest agents
and adds one when a task needs a role nobody holds. Separate concerns go in
separate organizations or projects.
Every other shipped role becomes a template only: coder, pm, reviewer,
security-reviewer, merge-gate, researcher, research, cto, the five chiefs
(executive, financial, information, information security, marketing) and the
six creative roles. `conductor-policy.json` is not a role and is unaffected.
Every other shipped organization role becomes a template only: coder, pm,
reviewer, security-reviewer, merge-gate, cto, the five chiefs (executive,
financial, information, information security, marketing) and the six creative
roles (companion, continuity, fact-checker, ideas, proofreader, research).
`researcher.json` is a version 1 worker role (`roles/researcher.json:2`), which
a hire refuses (`broker.mjs:6303`), and `conductor-policy.json` is not a role.
Neither changes.
## 9. Usability and security
Read this first. It says who can change what.
| You can change it freely | It needs a person to approve | Only a reviewed code change |
Everything in the first two columns is done by a person. No agent can do any
of it.
| A person changes it directly | It needs an approved decision | Only a reviewed code change |
|---|---|---|
| Your organizations and projects | Hiring, firing or changing an agent (`org.hire`) | The rails in section 3 |
| An agent's name, model, limits and route, when you hold `org.hire` | Any agent power above the chief's own, shown flagged | The core list of tools and actions |
| Your copy of a role: tools, actions, instructions | Giving an agent a password, key or token | The shipped role templates |
| Personality and traits, by a human after hire | Enabling a plugin in an organization (owner) | The rights table, including `org.hire` |
| Inventing a new role from known parts | Installing a plugin on the instance (instance owner) | Plugin kinds |
| Whether to apply a template update | Moving an agent to the root level (instance owner) | System config, which only bootstrap writes |
| Organizations and projects (owner) | Hiring, firing or changing an agent's role (`org.hire`) | The rails in section 3 |
| Drafting a role copy, or inventing a role from known parts. A draft does nothing until a decision uses it (`org.hire`) | Any agent power above the chief's own, shown flagged (owner approves) | The core list of tools and actions |
| An agent's model, limits and route (`org.hire`) | Giving an agent a password, key or token (owner approves) | The shipped role templates |
| An agent's personality and traits after hire | Applying a template update to your copy | The rights table, including `org.hire` |
| Enabling a plugin in an organization (owner) | Each merge or policy change an agent asks for | Plugin kinds |
| Installing a plugin on the instance (instance owner, at the host) | Adding an agent at the root level (instance owner) | System config, which only bootstrap writes |
What never moves, whoever asks:
@@ -341,8 +356,10 @@ What never moves, whoever asks:
mint a credential, delete data or use sudo by itself. A person decides each
of those every time.
- An agent cannot hire. Only the chief asks, and a person says yes.
- An agent cannot see another organization's work, except the assistant
through the Console.
- An agent cannot merge into a protected branch or change policy unless a
person approves that one merge or change.
- An agent cannot see another organization's work. The assistant's read
across organizations is planned (A6) and not built yet.
- A plugin runs with the same power as the Mosaic service itself. Install
only code you trust.
@@ -354,6 +371,7 @@ What never moves, whoever asks:
| A custom role names an unknown tool | `checkComposition` refuses it at the decision and at the writer. Launch refuses it again (R3). | None. |
| A plugin from an untrusted source | Instance owner only; hash pin; the install screen lists host-run tools. | Approved plugin code runs as the instance uid (R10). A pin does not make code safe. |
| A credential scope wider than the task | Each scope is its own line; owner-only approval; the approver may drop lines; admin and all never granted. | The service's own scope granularity. |
| An arbiter agent approves another agent's merge or policy change | A4 routes those decisions to the human whatever their class (R5). | Other routed work, such as task scope, still has an agent arbiter by design. |
| Approval fatigue on flagged grants | Flagged lines shown apart from plain ones; credential and flagged decisions go to the owner; no batch approval; seven-day expiry. | A busy owner who approves without reading. A later slice could limit how many flagged decisions one approval screen holds. |
| An imported template drifts from its source | The copy is frozen with its source hash. A changed template produces a diff offer, never a silent change. | An owner who keeps an old copy keeps its old behaviour. That is the ruling. |
@@ -396,7 +414,8 @@ unknown right still refuses.
file but it defines authority policy, so Jason's approval. Tests: an unknown
key, action, tool, service or scope refuses; each hard wait refuses;
`role.hire` and `role.fire` refuse; a secret in instructions or personality
refuses; flagged lines match a hand-built expected set for coder against the
refuses; `git.merge.protected` or `policy.change` in `withinRole` refuses;
flagged lines match a hand-built expected set for coder against the
shipped chief.
**T1. Organization definitions and templates.** The `definitions` key,
@@ -407,16 +426,22 @@ change; an `org:` reference to a missing definition refuses at launch; an
agent cannot call the edit verbs.
**A4. Hire as a decision, all levels.** The decision action, raise, Console
approval, the writer calls, credential lines, expiry, fire and change, and
removal of the direct path and `#hireable`. Org and project land first; root
approval, the writer calls, credential lines, expiry, fire and change, the
Console path that raises and resolves in one step, human routing for
`role.hire`, `role.fire`, `credential.mint`, `git.merge.protected` and
`policy.change` decisions (R5), and removal of the direct path and
`#hireable`. Org and project land first; root
waits for A2's root writer. This edits `roles/chief-of-staff.json` and `.md`
(drops `hireable`, rewords hire), the vocabulary and AGENTS.md invariant 7,
so Jason's approval. Tests: a hired agent's raise refuses `role-not-chief`; a
and reverses part of PRD 1.5 REQ-DEC-2, so Jason's approval. Tests: a hired agent's raise refuses `role-not-chief`; a
chief decision cannot carry its own `flagged`; a member with `org.hire`
approving a credential or flagged decision refuses; a stale digest refuses;
deny and expiry write nothing; approval writes the role, the route and the
trail, and launch refuses `credential-unbound` until binding; fire revokes;
the old `instance.hire` verb refuses.
the old `instance.hire` verb refuses; a cross-role `git.merge.protected` or
`policy.change` decision routes to the human and an arbiter's resolve refuses
`not-resolver`; a hire a person starts in the Console leaves a decision record
with its flagged lines.
**PL1. Plugin manifest, install and declared tools.** Manifest, pinned
install root, lock file, the registry merge, and `plugin-disabled` refusals.