Triage of Vikunja P19 #228 and its c78, the gaps Jason's first PM request hit. Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
Claude Opus 5.5
@@ -0,0 +1,244 @@
|
||||
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.
|
||||
|
||||
### 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/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.
|
||||
- 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; and the no-argument call still matching today's reply.
|
||||
|
||||
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.
|
||||
|
||||
### 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/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.
|
||||
- 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.
|
||||
|
||||
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 63 and ahead of row 88. 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
|
||||
- tests under `packages/seat/tests/` and `packages/cli/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.
|
||||
- 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.
|
||||
Reference in New Issue
Block a user