Files
stack/packages/business
jason.woltjeandClaude Opus 5.5 94e41ae29e roles: add the assistant role, move role.launch from the PM to the chief of staff (row 119, #1613)
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]>
2026-10-14 20:10:11 -05:00
..

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"] } }
  ]
}
  • name matches the file name. contract is a Markdown file name in the same directory, not a path. It must exist, be a regular file and not be empty.
  • authority names actions from the closed list in src/vocabulary.mjs. withinRole actions run without asking. crossRole actions 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> or write:<category>, one level per category. all and admin are refused. Vikunja scopes map a route group to verbs, and only the pairs in VIKUNJA_GRANTABLE pass.
  • 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 validate and 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.mjs and src/vars.mjs.