diff --git a/docs/plans/2026-11-10_roles-and-rails-design.md b/docs/plans/2026-11-10_roles-and-rails-design.md index fb6222b65..5099b6328 100644 --- a/docs/plans/2026-11-10_roles-and-rails-design.md +++ b/docs/plans/2026-11-10_roles-and-rails-design.md @@ -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 `/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.