stack/agents/darkwing/work/queue-62/BUILD.md

# Row 62 (#1555): the adapter reads a project tree, candidate packet

Author: Darkwing. Reviewers: Dewey and Filbert. Brief:
`docs/plans/2026-10-11_multi-project-sync.md`, row A. Base: `edc5de71`
(`base.txt`). It applies unchanged to `6ae8b844`, where the gate ran: the
commits between the two touch no file in this candidate. The feature is
uncommitted; only this packet is committed. I pushed nothing.

## Files

`files.txt` lists the 13 repository paths. `candidate-manifest.sha256`
has their sha256. `build.patch` is `git diff --cached --binary edc5de71`
over them: 13 files, +608/−73.

| File | Change |
|---|---|
| `packages/business/src/vars.mjs` | `tracker.descendants`: project layer, boolean, default false |
| `packages/business/tests/vars.test.mjs` | accepts true, refuses `"true"`, `1` and the business layer; default false with provenance `default` |
| `packages/cli/src/config.mjs` | one line, `descendants: v["tracker.descendants"]` in `trackerFor()` (decision 87) |
| `packages/cli/tests/config.test.mjs` | the two tracker tests expect `descendants: false`; one more assertion that `true` reaches the boot entry |
| `packages/cli/tests/trackers-boot.test.mjs` | line 44 expects `descendants: false`; see "Scope" |
| `packages/tasks/src/adapter.mjs` | `settings()` takes `descendants` (absent means false, a non-boolean refuses `tracker-config`); `ctx.tree` |
| `packages/tasks/src/startup.mjs` | `inspect(ctx, project)` is the install check for any project; new `discover(ctx)` |
| `packages/tasks/src/sync.mjs` | tick and reconcile read each project in `ctx.tree`; watch-only reads; the leave-tree rule in `missing()` |
| `packages/tasks/src/fake.mjs` | project trees: parents, the project list, archive, inherited access |
| `packages/tasks/tests/tree.test.mjs` | new: 11 tests, listed below |
| `packages/tasks/tests/shapes.test.mjs` | new test: the fake's project list against recorded shapes |
| `packages/tasks/README.md` | new section "Project trees"; the host contract and startup notes |
| `packages/tasks/live/README.md` | new section "Project trees" |

`verbs.mjs`, `vikunja.mjs`, `index.mjs` and `packages/bus/` are unchanged.

## Scope

`packages/cli/src/config.mjs` and `config.test.mjs` are outside the
brief's files. Sage added them as lead decision 87 (commit `9277de33`), a
decided scope addition: without the line, a host config with
`tracker.descendants` set never reaches the adapter, and the gate read
would need a packet script.

`packages/cli/tests/trackers-boot.test.mjs` is not named in decision 87.
It follows from it. Line 44 compares `boot.trackers` with an exact
object, so the config line breaks it: with the original line 44 and the
candidate `config.mjs` the test fails, 0 passed and 1 failed. The change
adds `descendants: false` to that object and nothing else. Reviewers and
Sage should treat it as part of decision 87's addition, or tell me to
take it out.

The extra `config.test.mjs` assertion, `true` reaching the boot entry, is
mine. Decision 87 asked for the two `false` updates. Without the new
assertion no test sent `true` through `config.mjs`, and the gate's live
run is the first place that value is used.

## How it works

With `descendants` off, `ctx.tree` holds the root and its view from
startup and nothing else. Every read is the v0 read with the root's
project id. The v0 tests pass unchanged, and tree test 1 checks that no
`GET /projects` and no read under a child happens.

With it on:

1. Startup is unchanged. The root's install check still refuses the
   business with `tracker-install`.
2. Each reconcile, including the first one at start, calls `discover()`.
   It reads `GET /projects`, every page, and walks `parent_project_id`
   breadth-first from the root. It skips ids at or below 0 and archived
   projects. Each child gets `inspect()`. A pass gives its view, a
   `tracker-install` refusal gives `null` (watch-only), and any other
   refusal propagates. `ctx.tree` is replaced only after the walk
   finishes, so a failed reconcile keeps the previous tree.
3. Tick and reconcile read each project in `ctx.tree`. An installed
   project is read through its board, as v0 reads the root. A watch-only
   one is read through `walk(ctx, 'done = false', {}, project)`, and each
   task gets bucket `WATCH_ONLY` (0).
4. Gone detection in a tick uses a set of refs placed by this tick's
   reads, not task ids. A task moved from A to B shows on B's board under
   the same id; keying by id would hide the old ref's tombstone. The
   `placed-by-id` mutant below fails the move test.
5. `missing()` takes the project from the ref (`parseRef`). If the task
   still reads 200 in the same project but that project is no longer in
   `ctx.tree`, the task gets `no-access` with its last `updated`.

`fieldsFor()` builds the fields of a watch-only task with
`taskFields(task, 1)` and then sets `bucket: 0`. `taskFields` checks the
bucket is a positive integer, so the 1 is a placeholder that never
reaches the ledger. The bus schema accepts 0 (an integer).

One line in reconcile changed meaning: `if (!bucket) continue` became
`if (bucket === undefined) continue`. The old form would skip every
watch-only task, since 0 is falsy. `undefined` is still the case it was
written for, an open task the board didn't show.

## The brief, line by line

| Brief | Where |
|---|---|
| `tracker.descendants`, project-layer boolean, default false | `vars.mjs`; `vars.test.mjs` "types" and "merge" |
| The tree from `GET /projects` by `parent_project_id` | `discover()`; tree tests 2 and 5 |
| Discovery at startup and each reconcile, not each tick | tree test 2 (tick has no `GET /projects`, reconcile starts with it); test 8 (a late child joins at reconcile, not tick) |
| Archived projects are not in the tree | tree test 5 (with the list forced to include archived ones); test 9 |
| Leave-tree rule, recorded and tested | README "Project trees"; tree test 9, three ways |
| The ledger is never rewritten | tree test 9: snapshots read `open`, then `no-access` with the same `updated` |
| Root install fails: refuse | tree test 4 |
| Child passes: installed. Fails: watch-only, business ready | tree tests 2 and 3 |
| Watch-only records title, done, assignees, comments; no bucket state | tree test 11, decision 87's bucket 0 |
| Moves root to child, child to child, child to outside | tree test 7 |
| Poll cost stated | README; tree test 2 counts 6 GETs per tick and 11 per reconcile; probes.md P4 |
| Cross-project read probed | probes.md P4 and "Gate read" |
| The fake models the tree | `fake.mjs`; probes.md "Fake"; shapes test 2 |
| Descendants off matches v0 | tree test 1; every pre-existing tasks test unchanged |
| verbs read-only; a child task refuses `task-project` | `verbs.mjs` unchanged; tree test 11 |
| No change to `packages/bus/`; no Vikunja writes | `files.txt`; tree test 11 checks `sync.mjs` has no write method string |

## Tests

`packages/tasks/tests/tree.test.mjs`:

1. With descendants off the adapter reads no project list and no child, as in v0.
2. A three-level tree is read per project, and a project outside it is
   not. Root, an installed child, a watch-only grandchild and an outside
   project shared with the sync bot. The tick's six requests are checked
   in order; the reconcile is `GET /projects` plus 10.
3. A watch-only child keeps the business ready, and a failed child read
   refuses as transient (a 503 on its views).
4. A root without the installed buckets refuses with descendants on.
5. The project list refuses without `read_all`, and skips archived
   projects and saved filters. A fetch wrapper adds `is_archived=true`,
   so the fake returns archived projects and the adapter's own check has
   to drop them.
6. `descendants` must be true or false.
7. A move inside the tree is a moved tombstone plus a snapshot under the
   new ref: root to A, A to B (watch-only), A to outside.
8. A child made after startup joins the tree at the next reconcile.
9. A child that leaves the tree has its tasks recorded missing, and the
   ledger keeps their history: archived, reparented to the top with a
   direct share, and reparented under a project the bot can't see. The
   hidden parent's title never reaches the bus.
10. A task in a bucket outside the five keeps its raw bucket id.
11. Bucket 0 on a watch-only task never becomes a bucket or a state. A
    move between open buckets records nothing; done then reopen records
    `done` twice; every snapshot has bucket 0; no `task.state` event; a
    verb refuses `task-project`; the source of `sync.mjs` has no
    `.titles` or `.ids[` lookup and no write method string. This is the
    test decision 87 asked for.

`shapes.test.mjs` adds "the project list holds recorded project objects
in the recorded list envelope". No recording holds a `GET /projects`
list, so it checks the envelope against the recorded views list and each
item against the recorded `GET /projects/{p}` body, keys and types.

### Mutants

`out/mutants.sh` edits one source file in the build worktree, runs the
tests, and restores the file from the candidate. Each mutant fails at
least one test (`out/mutants.txt`):

| Mutant | Fails |
|---|---|
| `no-leave-tree-check`: drop the `ctx.tree.has(project)` branch in `missing()` | tree 9 |
| `no-watch-only-bucket`: `fieldsFor` keeps the bucket it is given | tree 2, 3, 7, 8, 11 |
| `placed-by-id`: gone detection keyed by task id | tree 7 |
| `keep-archived`: `discover()` keeps archived projects | tree 5 |
| `config-drops-descendants`: `config.mjs` passes `false` | cli config "trackers come from..." |

## Things a reviewer should know

- The `p.id <= 0` skip guards shape only. The walk starts at the root
  and follows positive parent ids, so it can't reach a negative id. The
  skip stops a saved filter from failing the `parent_project_id` check.
- The fake's `GET /projects/{p}` body now has `parent_project_id`,
  `position`, `created` and `updated`, from a shared `#projectJson`.
  Shapes test 1 still matches it to the recorded body.
- `commentsAt` and `commentCount` stay keyed by task id. Vikunja task ids
  are global, so a moved task keeps its comment state.
- A watch-only child's open tasks come from its task list, so a tick
  costs the same two GETs as an installed project.
- I noticed in the v2.7.0 source that creating a project under v2 also
  creates a default kanban with a backlog bucket. A child made in the UI
  is then watch-only until someone installs the five buckets by hand.
  Nothing in this row depends on it.
- No probe in this row touched a live Vikunja. probes.md has the source
  evidence and the exact gate read.

## Gate

The gate ran in a detached worktree of `6ae8b844` with `build.patch`
applied and `node_modules` linked to the main checkout's
(`out/gate/apply.txt`, `out/gate/gate.sh`). Every suite ran in order and
each log is in `out/gate/`. test-task ran with
`DOCKER_HOST=unix:///nonexistent`.

Every suite passed on this candidate (`out/gate/summary.txt`):

| Suite | rc | Result |
|---|---|---|
| `packages/tasks` | 0 | 63 passed, 0 failed |
| `packages/business` | 0 | 60 passed, 0 failed |
| `packages/bus` | 0 | 74 passed, 0 failed |
| `packages/cli` | 0 | 83 passed, 0 failed |
| test-auth | 0 | 15 passed, 0 failed |
| test-conductor | 0 | 17 passed, 0 failed |
| test-config | 0 | 24 passed, 0 failed |
| test-discord | 0 | 66 passed, 0 failed |
| test-extension-package | 0 | 18 passed, 0 failed |
| test-foundation | 0 | 44 passed, 0 failed |
| test-queue | 0 | 27 passed, 0 failed |
| test-release | 0 | 14 passed, 0 failed |
| test-task | 0 | 26 passed, 0 failed |

After the run I removed the gate worktree's `gate_default` Docker
network; it had no containers.

Two earlier gate runs were stopped. The first had no `node_modules` link,
so test-discord failed its "pi binary present" check, 57 passed and 1
failed. The second I stopped to add the `true` assertion to
`config.test.mjs`, which changed the candidate. Neither run's logs are
in this packet; they were on the earlier candidate.

## Gate read for Sage

probes.md "Gate read" has the exact requests: `GET /api/v2/projects` and
`GET /api/v2/tasks` with a `project in 19, 18, 20, 21` filter, sync key 9,
GETs only. The adapter reads per project whatever read 2 answers; a 200
there opens a follow-up row.