roles/assistant.json and assistant.md are new. The assistant holds only
message.send and relays each ruling verbatim to the chief of staff. The
chief of staff gains role.launch; the PM drops it. Test fixtures move
launch.by from "pm" to a `chief` instance.
This does not change the live host. Jason's organization file names
launch.by "pm", which the new role files refuse, so his edit and the
re-pin happen together in one Mos window (decision 144; the order is in
agents/researcher/work/queue-119/build.md).
Lands Researcher's round 2 candidate, approved by Filbert in comment
28528 (rev 1240). Candidate manifest f77c4917, all 22 files match.
Landing gate on 46117feb8: 23 suites, GATE_PASSED 01:09:35Z.
Co-Authored-By: Claude Opus 5.5 <[email protected]>
Business
Role definitions, the business and project files, the variable registry and
the resolver (slice 1 row S1, #1518). Brief: docs/plans/2026-10-04_slice-1.md,
row S1. Design: agents/darkwing/work/slice1-data-model-2026-10-04.md and its
addenda A and B. The package reads files and refuses on any problem. It
never writes, and it never opens a token file.
scripts/mosaic business validate mosaic-stack
scripts/mosaic business resolve mosaic-stack coder --project stack
node --test packages/business/tests/
Files
| File | Who writes it | Holds |
|---|---|---|
roles/<name>.json |
reviewed commits | a role definition: tools, network, authority, credential scopes |
roles/<name>.md |
reviewed commits | the duty contract a version 2 role file names |
<configDir>/businesses/<id>.json |
Jason | role instances, holders, bots, token references, arbiters, projects, launch limits |
<root>/.mosaic/project.json |
reviewed commits in that project | project variables, per-instance project variables |
<configDir> is the directory holding the system config: the directory of
$MOSAIC_CONFIG, or ~/.config/mosaic-dev. Role files come from roles/
in this repository, or $MOSAIC_ROLES_DIR if set.
Role files, version 2
{
"roleVersion": 2, "name": "coder", "title": "Coder", "contract": "coder.md",
"tools": ["read", "write", "edit", "bash", "grep", "find", "ls"],
"network": "api-only",
"authority": {
"withinRole": ["task.update.assigned", "git.push.working", "review.request", "message.send"],
"crossRole": ["task.scope.change"]
},
"credentials": [
{ "service": "gitea", "scopes": ["write:issue", "write:repository", "read:user"] },
{ "service": "vikunja", "scopes": { "tasks": ["read_one", "update"], "tasks_comments": ["create"], "projects": ["views_buckets_tasks"] } }
]
}
namematches the file name.contractis a Markdown file name in the same directory, not a path. It must exist, be a regular file and not be empty.authoritynames actions from the closed list insrc/vocabulary.mjs.withinRoleactions run without asking.crossRoleactions need the arbiter. Any action not listed is gated: it goes to Jason. The nine always-gated actions (deploy,spend,git.push.protected,git.merge.protected,credential.mint,message.external,policy.change,prd.approve,role.revoke) can't appear in either list.- Gitea scopes are
read:<category>orwrite:<category>, one level per category.allandadminare refused. Vikunja scopes map a route group to verbs, and only the pairs inVIKUNJA_GRANTABLEpass. - Version 1 files (
roleVersion,name,tools,network) still load. They have no authority and no credentials, and a business can't use them for a role instance.
scripts/mosaic-task.mjs resolve-role checks both versions through this
package and prints MOSAIC_ROLE_CONTRACT for version 2.
Business file
examples/mosaic-stack.example.json is a complete example. As shipped it
refuses on purpose: every botId is 0 and every date is YYYY-MM-DD. Copy
it to <configDir>/businesses/mosaic-stack.json, put in the bot ids and
token dates from docs/guides/slice-1-identities.md, fix the token paths
and run validate. The file must belong to you and must not be writable
by group or other. The loader checks the owner and mode on the descriptor
it reads from, so the file can't be swapped between the check and the
read.
Each role instance names a definition (a version 2 role file), an
optional holder, its Vikunja bot (tracker, required when the definition
uses Vikunja), a credential reference for each service the definition
lists, and optional agent-layer vars. Several instances may share one
definition. Bot names and bot ids are unique across the instances and the
sync bot.
A credential reference names a token file by absolute path, or an
environment variable by name, plus rotateBy for Gitea or expires for
Vikunja. The checks use lstat and realpath only. A token file must be a
regular file you own, mode 600 or tighter, not empty, and outside the
repository, dataRoot and every project root. A Vikunja token past
expires refuses. One within seven days of it, or a Gitea token past
rotateBy, prints a warning.
launch lets one instance (by) start the listed instances, up to max
sessions per model family (Opus 4, Sonnet 4 at most). by must name an
instance whose definition holds role.launch within-role; otherwise the
file refuses. Only that instance keeps role.launch. Every other instance
loses it, so for them it's gated.
Chief-of-staff and assistant instances
Two roles stand above the PM (PRD 1.2; row 119, #1613).
The assistant role (roles/assistant.json, contract
roles/assistant.md, REQ-ASSIST-1) is the user's main agent: one per user
per organization. It talks with the user and passes work to the chief of
staff. It holds message.send within role and nothing else: no
credentials, no crossRole action, read-only tools. It doesn't direct
agents, create or assign tasks, or launch sessions. The broker's send
limits for it are row 120 (REQ-ASSIST-2).
The chief-of-staff role (roles/chief-of-staff.json, contract
roles/chief-of-staff.md, REQ-COS-1) runs the organization: it hires and
terminates role instances, owns the structure, takes work from the
assistant and never talks to the user. It holds message.send and
role.launch within role (decision 139), with no credentials and the same
read-only tools. It is the only shipped role that holds role.launch, so
it is the only role launch.by can name. The PM holds no role.launch
(REQ-LAUNCH-1); it asks the chief of staff for a session.
The owner adds both instances under roles in the business file, next to
the others, and points launch.by at the chief of staff. The stack never
writes that file. The instance names are the owner's choice; these are the
example file's:
"chief": { "definition": "chief-of-staff" },
"assistant": { "definition": "assistant", "holder": "mos" }
...
"launch": { "by": "chief", "instances": ["coder", "reviewer"], "max": { "opus": 4, "sonnet": 4 } }
Neither entry has a tracker or credentials, because neither role holds
any. A session that launches needs a harness and a model, so give each
instance vars (harness, model) as the PM has, unless the system's
execution settings cover it. A launch.by that names a PM, an assistant or any other instance
whose role lacks role.launch is refused. A file that still names the PM
fails to load with the shipped roles, so edit the file before a copy with
these roles goes live. packages/business/tests/chief-of-staff.test.mjs and
assistant.test.mjs check each role against its approved list and load it
through loadBusiness; role.test.mjs loads every file in roles/
through the validator.
Project file
{ "projectVersion": 1, "id": "stack",
"vars": { "tracker.project": 3, "git.workingBranch": "refactor", "git.protectedBranches": ["main", "next"] },
"roles": { "coder": { "vars": { "limits.tools": ["read", "edit", "bash"] } } } }
id must match the business file's name for the project. A missing
project file is a warning in validate and an error in
resolve --project.
Variables
Every key is declared once in src/vars.mjs with its type, the layers
that may set it and its merge rule. An unknown key refuses, and so does a
key set at a layer it doesn't belong to.
Layers, least specific first: defaults, system (the system config), business
(vars), project (vars, then roles.<instance>.vars), agent (the business
file's roles.<instance>.vars). For a plain key the most specific layer
wins. limits.tools, limits.network and limits.authority intersect:
each layer that sets one narrows it, and the result also narrows the role
definition. limits.authority is an allowlist, so a role action it leaves
out becomes gated.
bus.tester is business-only and defaults to false. Set to true, the bus
binds a tester from tester-cli.mjs for PM tests; it reads the value at bus
start, so a change takes a bus restart.
resolve prints provenance beside vars. For a plain key it's the
layer that set the value (default, system, business:<id>,
project:<id>, project:<id>:roles.<instance>,
business:<id>:roles.<instance>). For a limit it's the list of layers
that narrowed it.
API
import {
loadBusiness, loadProject, systemVars, resolveInstance, classify,
loadRole, validateRoleDocument, checkCredentialRef,
} from "../packages/business/src/index.mjs";
const business = loadBusiness("mosaic-stack", { rolesDir }); // frozen
const project = loadProject(business.projects.stack.root); // frozen
const coder = resolveInstance({ system: systemVars(config), business, project, instance: "coder" });
classify(coder, "git.push.working"); // "within" | "cross" | "gated"
resolveInstance returns a frozen record: business, project,
instance, definition, holder, contract (absolute path), vars,
provenance, limits (tools, network, authority.withinRole,
authority.crossRole), credentials (references only), tracker (bot,
botId or null), launch (the launch block, or null) and digest, the
SHA-256 of the record's canonical JSON. classify refuses an action
outside the vocabulary. launch is set exactly when classify(record, "role.launch") is within. If limits.authority leaves out
role.launch for the launcher, launch is null. A launcher should
still ask classify, not read launch alone.
Errors are BusinessError with exitCode 2 (invalid) or 4 (a required
file missing). The CLI adds 3 for a system config problem and 4 for usage.
Limits
- The action vocabulary lives here, on the host. Neither workers nor
container images read it, so it isn't under
contracts/. - The checks run as you, against files you can change. They catch mistakes; they don't stop someone who already runs as your user.
- A token file can change between
validateand the moment it's opened. The code that opens it at run time repeats these checks (rows S2 and S3). - Slice 1 knows two services and one tracker kind. A new one is a
reviewed change to
src/vocabulary.mjsandsrc/vars.mjs.