stack/docs/plans/2026-10-12_pm-task-flow.md

Status: written by Sage, lead. It follows docs/plans/BRIEF-TEMPLATE.md. It triages Vikunja P19 #228 (dogfood), which Mos filed from Jason's first PM request after the PM started (talk fef3fa41, PM RESULT e300f8af, about 2026-10-12T19:27Z; Mos sage-0100), and the three gaps Mos added in #228 c78 from the same test (sage-0101). Three rows: the board read, the requirement ids, and the role checkout. All three block S7 (row 42): the PM can't carry a request to a task, or the coder work on the project, until they land. Gitea issues #1583, #1584 and #1585.

The PM's task flow on a real board (#228)

PM task reads that fit a session

Problem

The PM's list_tasks tool takes no arguments (packages/harness/src/tools.mjs:116, obj({})). The broker's tasks verb returns every row of task_current with all its fields, description included (packages/bus/src/broker.mjs:313-329, :860), and the MCP server sends it as indented JSON (packages/harness/src/mcp-server.mjs:40, pi-extension.mjs:45). On the Mosaic Stack board that reply was about 120 KB. Claude Code saved the oversized result to a file outside the PM's workspace, and the run's file guard refused to read it. That refusal is right; the reply is the defect. So the PM couldn't see the board.

The same session text lists the wrong built-in tools for Claude Code (the PM's findings, fault 9). bundle.mjs:67 prints the role's pi names, so the PM read "read, write, edit, grep, find, ls", while Claude Code gets Read, Write, Edit, Grep and Glob (packages/harness/src/gate.mjs:17,29, claudeBuiltins).

Owner and reviewer

Owner: Dewey, after row 81 lands. Reviewer: Darkwing.

Files owned

• packages/bus/src/broker.mjs, the tasks verb and #taskRows only
• packages/harness/src/tools.mjs, mcp-server.mjs, pi-extension.mjs
• packages/harness/src/bundle.mjs, the built-in tools line only
• packages/bus/README.md, packages/harness/README.md, the sections on the tasks verb and the tool replies
• tests under packages/bus/tests/ and packages/harness/tests/
• agents/dewey/work/queue-<row>/

What ships

• The broker's tasks verb takes optional arguments. With none, it returns what it returns today, so the Console and mosaic are unchanged. With any, it filters and pages: done (true, false; the tool's default is false), assignee (a role), label, requirement, limit (default 50, at most 200) and after (a task ref, for the next page). A filtered reply is { tasks, total, next }, and each task is the short form: ref, title, done, bucket, assignee roles, labels, priority, requirement and the last change time, with no description. An unknown argument or a bad value refuses with invalid-request.
• One more argument, task_ref, returns that one task in full, as today's row, so the PM reads a description only when it needs one.
• list_tasks exposes those arguments and says the default is open tasks, 50 at a time. A get_task tool takes task_ref. Both are typed for the pm role and the same holders as today.
• Every tool reply has a size cap, in mcp-server.mjs and pi-extension.mjs both, set below the size at which the pinned Claude CLI saves a tool result to a file. Dewey finds that size for the version the bus unit runs (MOSAIC_CLAUDE_BIN, decision 91), records how in the packet, and sets the cap with margin. Over the cap, the tool returns an error naming the size and the cap and telling the session to narrow the query, never a cut-off reply. Replies go out as compact JSON, not indented.
• The session text names the built-in tools the session's harness really has: claudeBuiltins(policy) for Claude Code, the pi names for pi.
• Tests: a board of 500 fixture tasks with long descriptions, where list_tasks with defaults fits under the cap and pages to the end with next; each filter; task_ref; the refusals; the cap error from both servers; the no-argument call still matching today's reply; and the tools line for each harness.

Suites: the bus, harness, webui and cli node suites, and every scripts/test-*.sh.

Out of scope

Loosening the run's file guard or adding the tool-results directory to the workspace. The Console's task views. Any change to who may read tasks. Server-side search over descriptions.

Gate

Darkwing approves on the row's issue, naming the candidate manifest. The suites above pass on Sage's gate rerun. The broker and harness change is live at the next bus restart, which ends the PM session and launches a new one (decision 109). Sage notifies Mos before the landing and sends the commit after it; Mos restarts the bus and confirms the PM relaunched.

The approved requirement ids as data

Problem

task.create needs a requirement id, and verbs.mjs:187 checks only its format, REQ-[A-Z]+-[1-9][0-9]*. Nothing tells the PM which ids exist. The PRD (docs/prd/mosaic-stack.md, version 1.0, approved 2026-10-05, lead decision 61) holds 24 of them, but no tool reads it. So the PM refused to create a task, and asked Jason in its RESULT instead of raising a decision to his Inbox. In the same test it later created P19 #229 and #230 under REQ-QA-1, which passes the format check and isn't in the PRD.

Two more gaps from #228 c78 are words, not missing paths:

• task_create's request says "Id of the message or human input this task answers" (tools.mjs:41). create() accepts only a human.input event id (verbs.mjs:352, broker.mjs:460), so the PM's message id refused request-not-found. Each message message.receive returns already carries that id as request (broker.mjs:790-797); the tool doesn't say to use it.
• A blocking decision needs a task (broker.mjs:596, task-required), and the PM read that as no Inbox path for a missing requirement. A non-blocking decision needs none. prd.approve is gated (broker.mjs:29), so it routes to the human. Nothing tells the PM this.
• The same rule stopped the PM asking Jason to stop the coder and reviewer (PM fault 10, #228 c91, Mos sage-0107). It raised a blocking role.revoke with no task and got task-required. A non-blocking one routes to the human, since role.revoke is gated too (broker.mjs:38). Stopping a run is the human's own verb (mosaic stop; launch.revoke is human-only, broker.mjs:815-823), and nothing in the session text says so.

Owner and reviewer

Owner: Dewey, after the row above (both touch broker.mjs). Reviewer: Filbert.

Files owned

• packages/tasks/requirements.json, new
• packages/tasks/src/requirements.mjs, new, and packages/tasks/src/verbs.mjs, the task.create requirement check only
• packages/bus/src/broker.mjs, a requirements read verb only
• packages/harness/src/tools.mjs, a list_requirements tool and task_create's request description only
• roles/pm.md, the paragraphs on creating tasks and raising decisions only
• packages/harness/src/bundle.mjs, one session-text line on stopping a run, and tools.mjs's raise_decision blocking description
• packages/tasks/README.md, packages/bus/README.md
• tests under packages/tasks/tests/, packages/bus/tests/ and packages/harness/tests/
• agents/dewey/work/queue-<row>/

What ships

• packages/tasks/requirements.json lists the PRD version and path and each id with a one-line title. A test reads the PRD's **REQ-...** bullets and fails unless the list matches them exactly, ids and order. A later PRD version is a new list in a reviewed commit, like the PRD.
• requirements.mjs checks the file's shape and loads it frozen, as fields.mjs does for fields.json (row 61). A bad file refuses at load.
• task.create refuses with unknown-requirement when the id isn't in the list. The format check stays.
• The broker's requirements verb returns the list, a read for every session that can create tasks. The list_requirements tool exposes it to the pm role.
• roles/pm.md: before creating a task, pick the id from list_requirements. When no id fits the request, raise a decision with action prd.approve, blocking false and no task_ref, naming the request and the nearest ids, and don't create the task; don't ask in a RESULT.
• task_create's request says it is the request field of the human message being answered, not the message id. pm.md says the same.
• raise_decision's blocking (tools.mjs:100, today "True when you can't continue without the answer") says a blocking decision holds a task and needs task_ref; a request with no task is non-blocking. The broker's rule stays: a blocking decision with no task still refuses task-required.
• The session text says a run is stopped by the human with mosaic stop; a session that thinks a run should stop raises role.revoke with blocking false, naming the run, and says why. pm.md says the same.
• Tests: the PM's role session raises that prd.approve decision with no task and it routes to the human; task.create with a message id still refuses request-not-found, and with that message's request it passes the request check; a non-blocking role.revoke with no task from the PM routes to the human's Inbox.

Suites: the tasks, bus, harness, webui and cli node suites, and every scripts/test-*.sh.

Out of scope

Editing the PRD or adding ids. Mapping Jason's past requests to ids. Showing the list in the Console. Letting a blocking decision go without a task. What happens to #229 and #230; their id is the PM's and Jason's to correct.

Gate

Filbert approves on the row's issue, naming the candidate manifest. The suites above pass on Sage's gate rerun. Live at the next bus restart and PM launch, so the same decision-109 notices as the row above.

A project checkout in each role workspace

Problem

A launched role session works in <dataRoot>/workspaces/<business>/<instance>/ (packages/seat/src/session.mjs:20,46), which the launcher creates empty (packages/cli/src/launcher.mjs:159-160). Nothing puts the project there. In #228's test the coder's workspace held only a fresh .git and its own new files, so it worked beside the source rather than in it, and the PM asked Jason for a checkout (dad88d23). Slice 1's goal is the stack building pieces of itself (2026-10-04_slice-1.md, line 20), which needs the coder in the project. The business file names each project's root (packages/business/src/business.mjs:170-177); that is the only source the launcher has.

Owner and reviewer

Owner: Darkwing, after row 92 (#1586, sessions confined to their own files), so the clone is built and tested inside the confined workspace. Reviewer: Filbert.

Files owned

• packages/cli/src/launcher.mjs, the workspace step in start() only
• packages/seat/src/checkout.mjs, new
• packages/seat/README.md, packages/cli/README.md, the workspace paragraphs
• packages/harness/src/bundle.mjs, the line in prompt() that names the clone's path and the doc comment on the session argument (added by decision 126)
• tests under packages/seat/tests/, packages/cli/tests/ and packages/harness/tests/
• agents/darkwing/work/queue-<row>/

What ships

• At every launch, before the bundle is built, the host makes sure each project in the business file has a clone at <workspace>/<project id>/. The host runs git, outside the session's sandbox. A missing clone is git clone --no-hardlinks <root>, at the root's checked-out branch. An existing clone with a clean tree on that branch fast-forwards from its origin. Anything else (a dirty tree, another branch, a fast-forward that fails) is left exactly as it is, and the launch log records checkout-kept with the project id and the reason. The host never resets, cleans, deletes or force-updates a clone.
• A clone's origin is the local root path. No credential, token or Gitea remote goes into it. The root is never written.
• A clone that can't be made refuses the launch with checkout-failed and the project id, through the broker's refuse() like the other launch steps. No partial clone is left behind.
• The bundle's session text names the clone's path, so the session knows where the project is.
• The clone is written by the session, so the host treats it as hostile before it runs git there (decision 126). Without these guards, a session could make the host run a command outside the sandbox, which would undo row 92.
  • Every git call runs with GIT_CONFIG_NOSYSTEM=1, GIT_CONFIG_GLOBAL=/dev/null, an empty host-made HOME and GIT_TERMINAL_PROMPT=0, and with -c core.hooksPath=/dev/null -c core.fsmonitor=false -c protocol.allow=never -c protocol.file.allow=always.
  • Before any git runs in an existing clone, the host checks it with lstat and never follows a link. <workspace>/<id> and its .git are real directories. Nothing under .git is a symlink or a special file, and no regular file there has more than one link. .git/commondir and objects/info/alternates are absent.
  • The host reads .git/config, a regular file under a size cap, with git config --file <f> --list, which follows no include and runs nothing. Every key is on an allowlist: the keys git clone writes, with remote.origin.url equal to the root and the standard fetch line, plus branch.<name>.remote and branch.<name>.merge.
  • A clone that fails a check is kept, checkout-kept with reason not-a-clone or config-changed, and no git runs in it.
  • The checks and the git calls run only while no session holds that workspace, so a session can't change the clone between check and use. If the launcher already refuses a second live session in one workspace, the packet cites that refusal and a test shows it. Otherwise the clone is kept with reason session-live.
  • A new clone goes to a temporary sibling directory and is renamed into place, so a failure removes only that directory.
  • A root with no branch checked out refuses checkout-failed for a missing clone and keeps an existing one.
  • The git step gets no bwrap sandbox of its own. One would have to bind the root's .git, whose remote URL may carry a credential. The allowlist closes the execution paths instead, and Filbert reviews it as the row's main risk.
• Tests: one case for each way a session could make the host run something or write outside the clone: core.fsmonitor, core.hooksPath, a hook file, include.path, a symlinked clone directory, a gitdir: file, a symlink under .git (logs, refs, objects), alternates and commondir. Each case keeps the clone and shows the command never ran, because the marker file it would write is absent. The root is unchanged.
• Tests: a first launch clones; a second fast-forwards after a commit to the root; a dirty clone and one on another branch are kept and logged; an unreadable root refuses checkout-failed with nothing left; the root's tree and refs are unchanged after each case; no remote URL in a clone carries a credential.

Suites: the seat, cli, bus and harness node suites, and every scripts/test-*.sh.

Out of scope

How the coder's change reaches the reviewer and the repository: pushing a working branch (git.push.working), the reviewer reading the coder's change, and landing. That is the next row, which Sage briefs once this one lands. Credentials in a clone. The PM's workspace contents beyond the clone.

Gate

Filbert approves on the row's issue, naming the candidate manifest. The suites above pass on Sage's gate rerun. The launcher runs in the bus host, so the change is live at the next bus restart: the same decision-109 notices as the rows above.