stack/agents/darkwing/work/queue-61/build.md

Row 61, the task field-writer table as data, round 1 (Darkwing)

Gitea #1550, Vikunja #208. Brief: docs/plans/2026-10-10_design-implementation.md § "Task field-writer table as data". Lead decision 113 settles the code and prose disagreements I raised, and queue rev 672 adds the field table section of docs/plans/2026-10-04_slice-1.md to the files owned. Base 4f8ac1e7; nothing from there to the packet commit touches the candidate's paths.

The candidate is build.patch, 12 files, applied with git apply --index on 4f8ac1e7. candidate-manifest.sha256 lists the 12 files after the apply. Nothing here is committed to refactor.

What ships

The table, packages/tasks/fields.json. It has two layers, as decision 113 rules.

• verbs maps each of the 8 broker task verbs to the writer verbs.mjs checks first: pm (the pm definition, field-writer otherwise), assigned (a role whose bot is an assignee, not-assigned otherwise) or any (no writer check). Only task.scope.change is any, and only task.update.assigned is assigned.
• fields lists the 11 fields in the slice 1 table. Each field names the verbs that write it and the Vikunja calls each verb makes for it, with the same placeholders as the prose.

Whether a write also needs a resolved decision isn't in the file. It comes from the role's authority in roles/*.json, which the broker already reads, so a second copy could only drift.

The schema is code. packages/tasks/src/fields.mjs has checkFields, which refuses any other shape: unknown or missing keys, a writer outside the three, a verb set that isn't exactly the broker's TASK_VERBS, a field twice, a verb twice in one field, a call that isn't a Vikunja write, a call twice, and a verb that writes no field. Labels are capped at 80 characters, the source and notes at 256. loadFields() reads the committed file, checks it and freezes it. Its errors name fields.json, never a path. The repository has no JSON Schema validator, and packages/business checks its files the same way, so I followed that instead of adding a dependency.

The test, packages/tasks/tests/fields.test.mjs. It reads both expectations rather than writing them out. The writer layer comes from the table, and authority from roles/*.json through packages/business loadRole, so the researcher's version 1 file grants nothing. Then it drives every task verb as pm, coder, reviewer and researcher against the fake Vikunja, with the cto as the technical arbiter:

• a role the table's writer excludes gets field-writer or not-assigned and sends no write;
• a role without the verb within-role gets decision-required and sends no write; the test raises a decision, checks it routes to the technical arbiter when the role lists the verb cross-role and to the human otherwise, resolves it and retries;
• every write that goes out is mapped back to the fields it carries (a PATCH by its body keys, a bucket move into done as done), and at the end each verb's writes must equal the table's calls for that verb.

A change to the table, a role file or verbs.mjs that leaves them disagreeing fails this file. Two smaller tests check that the committed table loads frozen with exactly the broker's verbs, and the schema cases.

The inspector. The task page (#/tasks/<ref>) has a "Who may write" section before the trail, with one row per field: the label, its note, and each verb with its writer in words. Its intro says the decision layer comes from the role's authority on Business, and that edits made in Vikunja aren't checked against this table. A table that fails to load shows the read error in that section only; the rest of the page renders.

To get the table to the browser, serve.mjs has GET /api/task-fields, and reads.mjs has fieldTable(file), named so it doesn't read as the taskFields digest in packages/tasks. The table is repository data, so the route answers without --business or a system config and carries no at. A table that fails its check is 503 read-failed with the loader's message and no path; other methods are 405. startServer takes a fieldsFile option for tests only. I count serve.mjs and reads.mjs as part of "the webui Tasks inspector": the page can't read the table without them. If reviewers read the files owned more narrowly, that's the place to say so.

The prose. Only the field table section of the slice 1 plan changes, with the five corrections from decision 113 and a paragraph saying where the data lives. One wording differs from what I proposed: the priority row says "a change after create needs a resolved decision (cross-role)", because task.create is within-role for pm, so priority at create needs none. The READMEs for packages/tasks and packages/webui describe the file, the route and the section.

Out of scope and unchanged: who may write a field, roles/*.json, and close not checking the verdict (Vikunja #218).

This lands on the live Console

Since the 10-12 cutover the Console runs from the canonical checkout (decision 109). Landing this changes serve.mjs, reads.mjs and public/bus.js there, so Sage notifies Mos before it lands, and the status and healthz checks follow. I don't start or restart the Console.

Overlap with row 81

Dewey's row 81 (#1575, in review) also changes serve.mjs, public/bus.js and packages/webui/README.md. The two patches touch different hunks. On 4918d410 I applied both with git apply --3way --index, in each order, and both went in cleanly both times. Whichever row lands second still needs a new round, because its manifest names the other's lines.

Tests

In ~/darkwing-scratch/r61/gate, a detached worktree at 4f8ac1e7 with build.patch applied by git apply --index and node_modules linked. Node v26.8.1, run in order from 18:39:31Z to 18:42:55Z on 2026-10-12 (gate-summary.txt). Every one exits 0:

Suite	Result
packages/tasks (node --test tests/*.test.mjs)	74 pass, 0 fail
packages/webui (node --test tests/)	82 pass, 0 fail
test-auth	15 passed
test-conductor	17 passed
test-config	24 passed
test-discord	66 passed
test-extension-package	18 passed
test-foundation	44 passed
test-queue	150 node tests, 27 suite checks
test-release	14 passed
test-task	26 passed, run with DOCKER_HOST=unix:///nonexistent, so its 4 live checks skip

Afterwards I removed the gate_default Docker network the gate left behind, which had no containers.

Mutants

mutants.sh WORKTREE [browser|light|NAME,...] makes 33 mutants, one site each, runs the named test file in that package and restores the file from a backup. The edits use queue-59-review/r1/mut.mjs. The light 30 ran to 18:39:18Z (mutants-light.txt), the 3 browser ones to 18:38:38Z (mutants-browser.txt). All 33 are killed, and build.patch still hashes the same in the worktree afterwards.

Group	Mutants	Killed by
Schema (fields.mjs)	15: unknown key, optional key, any writer string, field twice, any field name, unbounded label, any note, verb twice, any call, call twice, unused verb, verbs a subset, any source, no freeze, wrong not-JSON code	the schema cases; no-freeze by the load test
Table (fields.json)	8: scope to pm, priority to any, update to any, close to assigned, reassign without its delete, create without the due date, comments by close, done by update	the verb walk; done-to-bucket by the schema
Code (verbs.mjs)	3: priority without a writer check, scope as pm, the assignee check gone	the verb walk
Route and read	4: any method, the route ignoring fieldsFile, a partial table on error, any message	reads.test.mjs
Section (bus.js)	3: a throwing section, the two writers swapped, no note	bus-browser.test.mjs

done-to-bucket moves the done write from task.close to task.update.assigned. The verb walk never runs on it: the load refuses first with "verbs.task.close: writes no field", which fails the whole file. That's the schema doing its job, but it means the walk's own check of the done mapping is only shown by comments-by-close.

An earlier light run left 4 survivors: required-key-optional, label-unbounded, verbs-subset and source-any. I added six schema cases: a blank source, a source that isn't a string, a 257-character source, a task verb missing along with the field it writes, an 81-character label and a 257-character note. All 4 died (mutants-light-r2.txt).