stack/docs/plans/2026-10-11_multi-project-sync.md

Multi-project sync: rows A and B (2026-10-11)

Status: written by Sage, lead. It follows docs/plans/BRIEF-TEMPLATE.md. Jason answered Q61a, relayed by Mos: agents see and work his nested projects ("just share them. Get it done."). Mos ruled the shape: row A now, row B after row A is done, and task.create takes an optional project. Lead decision 86 records it.

Three constraints hold for both rows. A change that breaks one of them is out of scope, whatever else it fixes.

• A task's ledger ref stays vikunja:<project>/<task>. The ledger checks that form on task_snapshots, decisions and the events subject (packages/bus/schema.sql), and task_snapshots is append-only. Neither row changes packages/bus/. Never key a task by its id alone.
• tracker.descendants defaults to false. With it false, the adapter behaves exactly as v0 does, and every v0 test passes unchanged.
• The adapter never writes to a board. A child project is installed only if its one manual kanban view already has the five buckets (todo, in-progress, in-review, blocked, done), done and default wired, as the root's install check requires. Any other child is watch-only. No bucket, view or project write ships in either row.

Multi-project sync: the adapter reads a project tree (row A)

Problem

The adapter watches one project. settings() takes one tracker.project (packages/tasks/src/adapter.mjs:21), startup checks that project alone (startup.mjs:37), and sync reads its board and task list only (sync.mjs:21, sync.mjs:45). A task in any other project is a shape error in the walk (sync.mjs:59), and a move to another project is a tombstone (sync.mjs:123). Jason's projects nest. The bus binds to #19 "Mosaic Stack", and he wants agents to follow work into its child projects.

Owner and reviewer

• Owner: Darkwing.
• Reviewers: Dewey and Filbert.

Files owned

• packages/business/src/vars.mjs and packages/business/tests/vars.test.mjs
• packages/tasks/src/adapter.mjs, startup.mjs, sync.mjs, fake.mjs, vikunja.mjs, index.mjs
• packages/tasks/tests/ (all files and fixtures)
• packages/tasks/README.md, packages/tasks/live/README.md
• agents/darkwing/work/queue-<row>/

verbs.mjs is read-only in this row. Verbs keep refusing a task outside the root with task-project, as they do now.

What ships

• tracker.descendants, a project-layer boolean var, default false. tracker.project stays the root.
• With descendants on, the tree is the root plus every descendant the sync bot can see through GET /projects (key 9 has projects read_all), followed by parent_project_id. Discovery runs at startup and at each reconcile, not each tick. Archived projects are not in the tree. Record your rule for a project that leaves the tree (archived, moved out, unshared or deleted) in the README and test it. Its tasks become task.missing with a reason. The ledger is never rewritten.
• Install state per project. The root's install check refuses the business, exactly as today. A child that passes the same check is installed. A child that fails it is watch-only and never refuses the business. Sync records title, done, assignees and comments for a watch-only child, and no bucket state.
• Sync covers each project in the tree. A task moved between two projects in the tree gets the moved tombstone naming the new project and a snapshot under its new ref. A move out of the tree stays the tombstone it is today.
• Poll cost. Probe whether v2.7.0 serves a cross-project task read to the sync key's scopes. If it does, use one read per tick for the tree. If not, read per project and state the per-tick call count in the README. The probe results go in agents/darkwing/work/queue-<row>/probes.md.
• fake.mjs models parent_project_id, the project list route, archived projects and access inherited from an ancestor's share.
• Tests: descendants off matches v0; a three-level tree; a watch-only child keeps the business ready; a root without buckets refuses; moves root to child, child to child and child to outside; a new child appears at reconcile; a child leaves the tree.
• Gate suites: node --test 'packages/tasks/tests/*.test.mjs', node --test 'packages/business/tests/*.test.mjs', node --test 'packages/bus/tests/*.test.mjs', and every scripts/test-*.sh.

Out of scope

Verbs on child projects (row B). Any change to packages/bus/. Any write to a Vikunja board or project. An archive guard: the adapter has no project verb, so the pm's projects.update can't reach a project through the bus. A row that adds a project verb adds the guard.

Gate

Dewey and Filbert approve on the issue, naming the candidate manifest. The suites above pass on Sage's gate rerun. Sage then runs one live read against tasks.woltje.com with descendants on, root #19, read-only, and attaches the tick log.

Multi-project verbs: task verbs across the tree (row B)

Problem

After row A, the bus sees child projects but can't act in them. target() and relation() refuse a ref from another project (verbs.mjs:74, verbs.mjs:79), read() refuses a task that isn't in the root (verbs.mjs:88), and task.create always posts to the root (verbs.mjs:355) with no project argument.

Owner and reviewer

• Owner: Darkwing, after row A is done.
• Reviewers: Dewey and Filbert.

Files owned

• packages/tasks/src/verbs.mjs, fake.mjs
• packages/tasks/tests/verbs.test.mjs and fixtures
• packages/tasks/README.md
• packages/harness/src/tools.mjs (the task_create tool schema gets the optional project) and its test
• agents/darkwing/work/queue-<row>/

What ships

• Mos's ruling: task.create takes an optional project. It must be an installed project in the tree; a watch-only or unknown project refuses with a new code the README names. Without it, the task goes to the root, as today.
• target(), relation() and read() accept a task in any installed project of the tree. A bucket move uses that project's own view and buckets, not the root's.
• A verb on a task in a watch-only project refuses with the same new code.
• Tests for each verb across two installed projects, a watch-only refusal and a relation between projects.
• Gate suites as row A.

Out of scope

Project verbs (create, rename, archive, move). They need their own brief, an archive guard and a ruling.

Gate

Dewey and Filbert approve on the issue, naming the candidate manifest, and the suites pass on Sage's gate rerun.