diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 404dd9391..8fecefb40 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -118,6 +118,34 @@ succeeded run → clean target tree → path allowlist → syntax gates → apply → policy suites → attribution commit. Any failure reverts. Push is never automatic. +## Conductor (landing approved work) + +```bash +scripts/land-work.sh [--base refactor] [--dry-run] [--subject TEXT] + [--attribution LINE] [--business ID] [--project ID] +``` + +Turns a merge decision the human resolved into one gated local commit on +`refactor` (#1610). It reads `/bus/bus.sqlite` read-only through +`scripts/land-work/read.mjs` and checks that the human picked the raise's +approval option, that the question names one `work/vikunja-

-`, and +that the task's latest `review.verdict` approves a commit C that the work +ref in the working repository still points at. It then applies +`git diff $(merge-base refactor C) C` in a detached worktree, checks the +patch-id, runs every package suite except `queue` and every +`scripts/test-*.sh`, and commits. The subject is the approval option's +text unless `--subject` overrides it, and `--attribution` replaces the last +line, `Applied-under: scripts/land-work.sh (conductor)`. `--business` and +`--project` are needed only when the config has more than one business file +or the business more than one project. The tool prints the line for the PM +and doesn't send it. `--dry-run` runs every check and the gate and writes +no ref. A refusal names its reason and exits 2; the reasons are listed at +the top of the script. The worktree, its `node_modules` link and its Docker +network are removed on every exit. The gate log directory stays and the +tool names it. Keep `TMPDIR` short: the gate inherits it, the cli suite +puts unix sockets under it, and a 46-byte `TMPDIR` failed 8 of those tests. +Push is a separate act. + ## Maintenance | Command | Purpose | Notes | @@ -128,6 +156,7 @@ Push is never automatic. | `scripts/test-release.sh` | Release selftests | 14 cases | | `scripts/test-conductor.sh` | Auto-apply selftests (sandboxed) | 17 cases | | `scripts/test-auth.sh` | Auth checkpoint selftests (no Docker) | 13 cases | +| `scripts/test-land-work.sh` | Land-work selftests (sandboxed, fake Docker) | 84 cases | | `scripts/gitea-api.sh [body]` | Gitea API helper; reads the JSON credential file or a raw per-seat token file | Token never on argv/stdout | ## Seat launch with registration (`scripts/mosaic`) diff --git a/docs/plans/CONDUCTOR.md b/docs/plans/CONDUCTOR.md index 0d5deff5c..bab3525a6 100644 --- a/docs/plans/CONDUCTOR.md +++ b/docs/plans/CONDUCTOR.md @@ -43,6 +43,33 @@ tracked, versioned files whose changes arrive as reviewed commits. - Verification is mechanical: suites + `node --check` / `bash -n` gates. - Recursive decomposition = "fail → smaller task", never "hope." +## Landing approved work + +A stack coder pushes `work/vikunja-

-` to the working repository, the +reviewer approves a commit on it, and the PM raises a `git.merge.protected` +decision for the human. After the human resolves it with the merge option, +the conductor runs: + +```bash +scripts/land-work.sh --dry-run +scripts/land-work.sh +``` + +The tool binds the commit to what was reviewed and decided. It reads the +decision, its raise and the latest verdict from the bus database +read-only, requires the work ref to be at the approved commit, squashes +the reviewed diff onto `refactor` in a detached worktree, checks the +patch-id, runs the full gate and commits once, locally. It refuses work +that adds a file at the repository root, in a new top-level directory, or +under `src/` or `v1/`. Each +refusal names its reason (`docs/TOOLS.md`). Don't work around one; fix the +cause or go back to the PM. + +The conductor then reviews the commit, pushes it as a separate act and +sends the PM the line the tool printed. Only `refactor` lands this way. +Merges to `next` or `main`, re-pins and restarts keep their own authority, +and no stack role runs this tool. + ## Worker task template ```json