stack/agents/darkwing/work/slice1-s1/build.md

Row 36, S1: roles v2, business and project files, variable layers

Darkwing, 2026-10-04. Issue #1518, reviewer Filbert. Brief: docs/plans/2026-10-04_slice-1.md, section "Slice 1 S1". Design: agents/darkwing/work/slice1-data-model-2026-10-04.md sections 1 and 2, addendum A sections 7 and 8, addendum B section 2. Nothing in the candidate is committed, staged or pushed.

Base is fef4b362 (origin/refactor at build time). In a fresh clone at that commit the patch applies, the result matches the manifest 34/34, and node --test packages/business/tests/ passes 57/57 in three runs.

Files

build.patch (sha256 8067882052abc6e75684b318f738ef990f53c7a35913a8313a341282d259bd94) changes 4 files and adds 30. build-manifest.sha256 (sha256 d934e5af30cd646194bbf1d9bffc2b4d51486a4bb4c097ec43376352830b0195) pins all 34 after the patch.

New:

• roles/pm.json, cto.json, coder.json, reviewer.json: version 2 definitions. roles/pm.md, cto.md, coder.md, reviewer.md: their duty contracts (Duties, Authority, Protocol).
• packages/business/src/: vocabulary.mjs (the closed lists), role.mjs (versions 1 and 2), vars.mjs (the key registry and merge), credentials.mjs (reference parse and stat checks), business.mjs, project.mjs, resolve.mjs (resolveInstance, classify), cli.mjs, util.mjs, errors.mjs, index.mjs.
• packages/business/tests/: 57 tests in 7 files plus helpers.mjs.
• packages/business/examples/mosaic-stack.example.json: the business file for Sage's SR template. It refuses as shipped (every botId is 0, every date YYYY-MM-DD); a test proves it validates once filled in.
• packages/business/README.md, package.json.

Changed:

• scripts/mosaic-task.mjs: validateRole delegates to the package, so both versions share one validator. resolve-role also prints MOSAIC_ROLE_CONTRACT=<absolute path> for a version 2 role.
• scripts/test-task.sh: 8 new checks (version 1 prints no contract line; the four shipped roles resolve with their contracts; a minimal version 2 role passes; unknown action, gated-only action, a Vikunja verb no role may hold, a missing contract and a linked contract each exit 2).
• scripts/mosaic: a business branch, like queue. This is outside the brief's file list. The brief asks for a TOOLS entry for any new command, and a command needs an entry point; the change is four lines.
• docs/TOOLS.md: a section for scripts/mosaic business, and the resolve-role row now says it takes versions 1 and 2.

Does the vocabulary go under contracts/?

No. contracts/ is baked into the worker image because workers read it. Nothing in a worker reads the action vocabulary: the broker classifies actions on the host, and the role files are read on the host by the launcher and the broker. Baking it in would give the image a copy that nobody checks against. The vocabulary lives in packages/business/src/vocabulary.mjs, and a change to it is a reviewed commit, like a role file. Containerfile copies package.json, contracts, src and adapters only, so neither packages/ nor scripts/mosaic-task.mjs is in the image, and the new import doesn't reach it. No contracts change, so no review by Sage for one.

Choices and deviations from the design

1. contract is a file name in the role file's own directory ("coder.md"), not the note's "roles/coder.md". A path relative to the repository breaks under MOSAIC_ROLES_DIR, which agent.sh and the tests use for sandbox role directories. The validator refuses a name with a slash, a non-.md name, a missing, empty or linked file.
2. pm authority adds three actions to the note's table (section 1.2):
   • task.update.assigned (within): addendum A section 2 says all four roles update the tasks assigned to them, and the note's pm row left it out.
   • task.reassign (within): addendum A's action table gives reassign to pm, cross-role for the others.
   • task.scope.change (cross): pm splits and rewrites tasks, and a scope change on one in technical work needs the CTO, the technical arbiter. Filbert, push back if you read it differently.
3. The business file must belong to the user and not be group or other writable. It holds authority, so a file someone else can edit would let them widen it. Missing file: exit 4. A linked file: exit 4.
4. Bot names and bot ids are unique across role instances and the sync bot. Two instances sharing one Vikunja bot would make the tracker's record of who did what wrong.
5. role.launch stays within-role only for the instance the business file's launch.by names. Everywhere else the resolver removes it, so classify returns gated. With no launch block nobody launches.
6. limits.authority is an allowlist. A role action it doesn't name becomes gated. It can't add an action the definition lacks.
7. Credential checks use lstat and realpath only. A test makes a token file mode 0200 (write-only) and the check still passes, which shows the package never opens it. A token inside the repository, dataRoot or a project root refuses, also through a linked directory. Vikunja: past expires refuses, within 7 days warns. Gitea: past rotateBy warns; Gitea tokens don't expire on their own. An env reference that isn't set warns, because the launcher sets it.
8. Lookups use Object.hasOwn. Ids may be any lowercase name, and constructor is one, so roles[name] would have treated it as declared. Tests cover arbiters, launch, the model family and a label titled __proto__.
9. validate treats a declared project with no project file as a warning ("absent"). resolve --project treats it as a missing file, exit 4. When a project file exists, validate resolves every instance against it, so a project file naming an undeclared instance refuses there.
10. Error text for version 1 roles now comes from the package. Every existing test-task.sh case still passes; only wording changed.
11. The package says "role file" for roles/<name>.json, so it doesn't share a name with the Markdown contract. mosaic-task.mjs and agent.sh keep their old wording ("role contract"); I didn't touch those messages.

Tests and suites

Node 26.8.1 on the host, outputs teed:

• node --test packages/business/tests/: 57/57. Files: role 12, vars 6, credentials 6, business 14, project 2, resolve 8, cli 9.
• scripts/test-config.sh 24/24, scripts/test-task.sh 98/98, scripts/test-conductor.sh 17/17, scripts/test-queue.sh 27/27 (scripts/mosaic changed).

Node 24.21.0 in the node:24 image, no network, the clone mounted read-only: node --test "packages/business/tests/*.test.mjs" 57/57. The glob is needed because Node 24 reads node --test tests/ as a module path and fails. That is true of every package in the repository; I checked packages/queue the same way. Follow-up for Sage, not part of S1.

Mutants, each run against the full test set and each caught: the forbidden-root check off (3 failures), the role.launch gate off (1), the token mode mask widened to other only (1), hasOwn dropped from the instance lookup (2), the business file mode check off (1), limit intersection replaced by overwrite (2).

The CLI tests point MOSAIC_CONFIG, HOME and MOSAIC_ROLES_DIR into a temp directory. No test reads the real ~/.config.

For other rows

• S2 (Rocko) consumes loadBusiness and resolveInstance. The frozen API is in packages/business/README.md, section "API".
• S3 (mine) opens token files, so it repeats the stat checks at open time and trims one trailing newline.
• S6 decides how a launcher passes MOSAIC_ROLE_CONTRACT to the session. agent.sh reads only MOSAIC_ROLE_TOOLS today and ignores the new line.

Follow-ups, not in this candidate

• node --test <dir>/ fails on Node 24 in every package (above).
• scripts/mosaic-task.mjs keeps its own SUPPORTED_TOOLS for tasks. The package has the same list in TOOLS. One should import the other in a later change.