dorfl 0.1.1 → 0.2.0

package/dist/skills/drive-tasks/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: drive-tasks
+disable-model-invocation: true
+description: 'The supervised conductor: build every ready work/ task in a loop via dorfl, reviewing each diff and merging, until none can advance. Requires the dorfl CLI.'
+---
+
+# drive-tasks
+
+**Be the conductor, not the player.** `dorfl do task:<slug> --isolated` already builds ONE task autonomously (claim → build agent → acceptance gate → optional Gate-2 review → PR) in a worktree off the arbiter. `drive-tasks` is the layer ABOVE: it looks at the _whole_ board, checks each ready task is still _fresh_, decides _what_ to build and in _what order_, drives `do` per task, then acts as a **third reviewer** (Gate-3, the conductor's own diff-vs-criteria pass — see step 4b) over each PR before merging it.
+
+It is a **methodology skill** (prose you follow), like `to-task` / `review` — NOT a runner command. **Precondition:** it drives the **`dorfl` CLI** over a repo using the **`work/` contract** — if neither is present, this skill does not apply. (It is the ONE skill that leans on the runner CLI directly; that is its job. The other skills stay protocol-native.) It composes:
+
+- **`dorfl do task:<slug> --isolated`** — the per-task worker (build + acceptance gate + optional PR/code-review gate), run `--isolated` ALWAYS (a job worktree off the arbiter, never the human checkout). The harness, model, acceptance gate, review mode, and integration mode all come from dorfl CONFIG (per-repo / global) — do NOT hardcode them; `--isolated` is the one flag this skill pins, and any other flag (`--review`/`--merge`/…) is a user-confirmed per-run override only.
+- **`review`** (`skills/review/`) — the discipline for your own diff-vs-criteria pass over each opened PR.
+- **`to-task`** (`skills/to-task/`) — for the forward-note step and any re-tasking the human asks for.
+
+It is **scoped to building ready TASKS.** The broader job — survey _everything_ (observations, ideas, specs, tasks), figure out what can advance, fill judgement gaps conversationally until new tasks are READY, then build them — is `orchestrate`, which delegates the BUILDING back to this skill. Keep `drive-tasks` focused on building ready tasks; hand the deep survey up to `orchestrate`.
+
+## How it stalls (the stuck-set)
+
+There is ONE loop. The skill **advances every task it can** and, whenever it hits a wall on a particular task, it does NOT halt — it records that task + its specific question in a **stuck-set** and moves to the next independent ready task (the [accumulate-don't-block rule](#the-accumulate-dont-block-rule)). Only when nothing more can advance does it deal with the stuck-set, and HERE is the only behavioural fork — it depends purely on whether a human is reachable in this session:
+
+- **A human is present** (the normal case — you are running in their session): present the accumulated stuck-set as one [batched set of questions](#batching-the-questions), take the answers, and **continue the loop** (a task whose question is resolved becomes buildable again; one the human defers stays parked).
+- **No human is reachable** (you were invoked to run unattended): do not block waiting — finish everything that can advance, then **stop and report the stuck-set** (plus the built/merged/needs-attention summary) as your result.
+
+That is the whole difference; the loop, the selection, and the stuck-set are identical either way.
+
+### Selection + isolation
+
+This skill does its OWN intelligent per-task selection (graph order + freshness + diff review) and dispatches `do` **per chosen slug** — it never uses `do`'s auto-pick (that is `run`'s daemon mechanism, not a conductor's). It builds **one task at a time, end-to-end**, and it builds **`--isolated`, ALWAYS** — never in-place.
+
+`do task:<slug> --isolated` builds in a per-job worktree off THIS repo's arbiter (the SAME isolation `run` uses), inferring the arbiter from cwd. The human checkout is **never touched**: no dirty-tree refusal, no claim/done-move churn in your tree, no entanglement with the human's (or your own) uncommitted work, no rebuild-the-dist-mid-drive dance. The conductor is a pure observer of the arbiter. (`do --remote <url>` is the same isolation against a FOREIGN repo with no checkout; `--isolated` is its same-repo sibling.)
+
+The ONE consequence to respect: an isolated build reads the task + its `blockedBy` deps from the **arbiter's `main`**, so a **local-only / un-pushed task is INVISIBLE** to it. Do NOT fall back to in-place for such a task — **push it (and its deps) to the arbiter first** (the arbiter is the source of truth; a task that isn't on it isn't ready to drive). There is no in-place mode in this skill.
+
+The loop, selection, freshness check, Gate-3 review, and stuck-set are exactly as described below; `--isolated` is simply the standing build mode.
+
+## When to use vs. not
+
+- **Use** to take a `work/tasks/ready/` from "N ready tasks" to "no ready task can advance", building + reviewing + merging each, in dependency-and-practical order; to conduct the dorfl worker through a phase of task-building; as the building engine `orchestrate` delegates to.
+- **Don't** use it as the unattended daemon — that's `run` (genuine parallelism, no human). `drive-tasks` is **one task at a time, end-to-end**. Don't use it to _author_ tasks from scratch (that's `to-task`), or to _task specs / triage observations / fill judgement gaps / answer scattered open questions across the whole tree_ (that's `orchestrate`). Don't use it to FORCE a blocked task — it respects the gate.
+
+## The golden rules (do not violate)
+
+1. **One task at a time, end-to-end** (build → Gate-3 review → merge) so each merge unlocks the next cleanly and rebases stay trivial. Parallelism is `run`'s job.
+2. **Never force a failed task.** A red gate / Gate-2 block / rebase conflict routes the item to needs-attention (its per-item lock is marked `state: stuck`) — leave it there, branch preserved, skip its dependents, continue with independent ready tasks, report it at the end.
+3. **Capture, don't fix-in-place, off-path findings.** Spot drift outside a task's scope → write a `work/notes/observations/` note (and COMMIT + PUSH it when a later build depends on it — see rule 5), don't expand the task.
+4. **You merge the approval.** GitHub refuses `gh pr review --approve` on a PR whose commits are under your own identity — so post the verdict as a PR **comment** (`gh pr comment <n> --body-file …`, lead with `APPROVE ✅` / `BLOCK`), then `gh pr merge <n> --squash --delete-branch`. The comment + merge IS the approval.
+5. **Commit + PUSH your own `work/notes/observations/` notes before they need to matter.** Because builds are `--isolated` (off the arbiter), a dirty local tree does NOT block dispatch — but an un-pushed note or task is INVISIBLE to an isolated build until it lands on the arbiter. So commit your contract-native notes (append-only, low-risk) AND push them when a soon-to-build task depends on them being on `main` (e.g. a forward-note planted in a task body — step 2). Report what you committed/pushed in the summary. **What a conductor commits:** its own `work/notes/observations/` notes; a load-bearing **forward-note it plants in a task body** (step 2 — it MUST be committed to take effect before that task's `do`, and it is a small protocol-mechanical edit, not authored content); and the protocol's own moves the runner/`do`/`complete` make (claim reverts, done-moves, PR merges). It does NOT hand-author-and-commit a full spec or a fresh task SET — producing those is `to-spec`/`to-task`' job and they are left for human review. Report every commit in the summary.
+6. **Accumulate, don't stall.** When ONE task is stuck or needs a judgement call, write it into the stuck-set and move to the next INDEPENDENT ready task — never block the whole loop on one item. When nothing more can advance, surface the stuck-set: ask the human if one is present, else report it. See [the rule](#the-accumulate-dont-block-rule).
+7. **Never touch the target checkout; be checkout-agnostic.** Driving is a side-effect-free observation of the arbiter, so as a side-effect of driving you perform NO git mutation in the target repo's working checkout — no `git switch`/`checkout -B`/`branch -D`/`reset`/`rebase`/commit in the human's working tree. If you need a working tree for a cheap verification (e.g. re-run a task's own tests off its pushed branch), use a THROWAWAY clone / the job worktree / a temp dir — NEVER the human checkout. The human's uncommitted work and current branch are sacrosanct; leave the tree exactly as you found it. And because you need only the arbiter (a URL/remote) + `gh` + a scratch area, you can RUN FROM ANYWHERE: resolve the arbiter EXPLICITLY rather than assuming `cwd` is the repo, and if `cwd` happens to BE the human's checkout, treat it as READ-ONLY. Your own `work/notes/observations/` note commits (rule 5) go to the arbiter without dirtying the working tree. (UNLESS the human explicitly asks to drive in-place in a specific checkout.) This is the same arbiter-is-truth posture `do --remote`/`run` already use; the repeated `git rebase origin/main` reconciliations a checkout-bound drive needs are the symptom this rule removes.
+
+## The accumulate-don't-block rule
+
+The loop's job is to **advance as much as possible**, not to halt at the first judgement call. Whenever you hit a **wall** on a task —
+
+- it looks **stale/drifted** (the freshness check in step 1 fires),
+- a **forward-note** seems needed but you're unsure it's wanted,
+- a **Gate-3 review** surfaces a genuine judgement call (a maybe-blocking nit, an ambiguously-met criterion), or
+- the task is otherwise ambiguous / rests on an unresolved decision
+
+— do NOT stop the loop. **Record the item + the specific question in a STUCK-SET** (a running list you keep for the session), SKIP that task (and its dependents), and **continue with the next independent ready task.** Only when nothing more can advance do you deal with the stuck-set:
+
+- **A human is present** → present the stuck-set as a [batched set of questions](#batching-the-questions), take answers, and resume the loop (a task whose question is resolved becomes buildable again; one the human defers stays parked).
+- **No human reachable** → finish all you can, then stop and report the stuck-set (+ the built/merged/needs-attention summary) as your result; do not block waiting.
+
+Either way the discipline is the same: do as much as can be done, then surface the residue in ONE batch — never dribble out one question at a time, never stall the whole loop on a single item.
+
+## Recovering a needs-attention item (requeue)
+
+When a task has routed to needs-attention (a red gate / Gate-2 block / rebase conflict / a build-time STOP marks its per-item lock `state: stuck`), its body carries the reason and its `work/<type>-<slug>` branch is **preserved on the arbiter** — nothing is lost. Whether you can re-drive it depends on the reason:
+
+- **A fixable problem the agent can resolve on a retry** — a real bug the gate caught, a scoping miss, a flaky-test red — is a CONDUCTOR move, not a human question. Recover it with **`dorfl requeue <slug> --arbiter origin`** (DEFAULT = keep + continue: releases the stuck lock; the body is already resting in the pool `tasks/ready/`, and the branch is left UNTOUCHED so the next claim CONTINUES from its tip). Optionally add a precise handoff with **`-m "<what to fix>"`** (appended to the body). Then `do task:<slug>` again: the re-claim CONTINUES from the kept branch, and the merged `agent-prompt-continue-context` puts the prior work + the needs-attention reason
+  - your `-m` note into the agent's prompt — so it BUILDS ON the good code and fixes the gap rather than restarting.
+- **A genuine human-decision block** — the task is ambiguous / drifted / rests on an unresolved fork — is NOT something a retry fixes. Leave it parked; it is a stuck-set question (ask it if a human is present, else report it). Do NOT requeue a task whose premise is wrong — re-scope it first (that is `orchestrate`/human work).
+- **`requeue --reset`** (DISCARD + fresh: deletes the remote branch first, then releases the lock so the next claim starts CLEAN) is for when the kept work is worthless. It is guarded and NEVER the default — only on an explicit human call; the conductor's default recovery is keep+continue.
+
+AFTER any requeue, re-sync (`git fetch && pull --rebase`) so the re-`do` claims off the latest main. A requeued-and-rebuilt task then flows through the normal step-4 BUILD → REVIEW → MERGE.
+
+> **Let `do` re-drive a recovered branch — do NOT hand-roll a parallel `pr/<slug>` branch.** When a flake-recovered task's `work/<type>-<slug>` branch already holds green work but needs only a small lifecycle fixup before its PR (release the stuck lock, strip the runner's "aborted/needs-attention" commit subjects), the right move is `requeue` (keep+continue) + re-`do`: the re-claim continues from the kept branch tip and the runner ITSELF opens the PR — no manual PR at all. If you genuinely must fix up by hand, commit the fixup **ON the existing `work/<type>-<slug>` branch** and PR that branch (`gh pr create --head work/<type>-<slug>`). NEVER spin a separate `pr/<slug>` branch off `main` and re-apply the tree: it **orphans** the canonical `work/<type>-<slug>` branch on the remote (it then has to be remembered and hand-deleted — easy to miss) and **discards** the branch's real history for mere cosmetic single-commit tidiness. One branch, its own history, no orphan.
+
+## The loop
+
+### 0. ANALYSE the task set + dependency graph
+
+Read every `work/tasks/ready/*.md` frontmatter (`slug`, `blockedBy`/`deps`, `needsAnswers`, `humanOnly`, `spec`, `covers`) and the `work/tasks/done/` set. Build the graph:
+
+- **READY** = every `blockedBy` is in `work/tasks/done/` AND `needsAnswers !== true` AND `humanOnly !== true`. (BOTH gate fields exclude a task from READY: `needsAnswers` means open questions a human must answer first; `humanOnly` means a human must DRIVE it. Check BOTH in the frontmatter scan, not just `needsAnswers`. A `humanOnly` task dispatched to `do` will rightly STOP at build time, wasting a claim/surface cycle, so catch it UP FRONT.)
+- **BLOCKED** = a `blockedBy` is still in the pool `tasks/ready/`, held (in-progress on its lock), or stuck (needs-attention on its lock).
+- **GATED** = `needsAnswers: true` OR `humanOnly: true` (needs a human first, by question or by drive-ownership; not part of the AUTONOMOUS READY set; list it but do not AUTO-build it, even once its deps land). The agent-buildable READY set is the tasks that are neither blocked nor gated by EITHER field.
+  - **"GATED" gates AUTONOMOUS SELECTION, not explicit human dispatch.** `humanOnly`/`needsAnswers` keep a task out of the set THIS LOOP (and `run`/`advance`/auto-pick) picks ON ITS OWN; they do NOT make the task unbuildable. An EXPLICIT `dorfl do task:<slug>` typed by a human (or by THIS conductor on a human's explicit instruction to build that named slug) STILL builds it — the readiness guard does not consult `humanOnly` on the human path ("a human is never bound by `humanOnly`"), and explicit dispatch drops the policy term ("the pool gates the policy, not the explicit claim"). So a `humanOnly` task is the human's to drive by NAME, never the conductor's to AUTO-select. (This is also why `humanOnly` can serve, off-label, as a "keep CI/`run` off while I drive this by hand" latch — but prefer POSITION/staging for that; see WORK-CONTRACT.md "Task `humanOnly` is NARROW".)
+
+(A task in the STAGING slot `tasks/backlog/` is review-first, awaiting a human's promotion into the pool `tasks/ready/`; it is NOT in the READY set — surface it, don't build it.) Note which tasks **unlock the most downstream work** when they land — those go first.
+
+> **This is the DEFAULT and it does NOT change:** the READY set is computed from the agent POOL `work/tasks/ready/`, and `work/tasks/backlog/` is review-first STAGING the conductor does NOT build (it surfaces those, it never dispatches `do` against them). Unless the caller explicitly opts into the drive-from-backlog mode below, behave exactly as documented above.
+
+#### Opt-in: drive tasks from `tasks/backlog/` (the staging folder)
+
+**OPT-IN ONLY — never the default.** When, and ONLY when, the **caller EXPLICITLY instructs** this skill to drive tasks from the staging folder `work/tasks/backlog/` (e.g. "drive the tasks in backlog/", "build the backlog tasks <slugs>", an explicit drive-from-backlog mode), the conductor builds those staged tasks too, using the **identical** loop, selection, freshness check, Gate-3 review, requeue recovery, and stuck-set discipline described in this whole skill — the ONLY change is WHERE the READY set is read from. Absent that explicit instruction, `tasks/backlog/` stays review-first staging you surface but do NOT build (the default above). If you are unsure whether the caller meant this, do NOT assume it — treat the staging folder as review-first and ask.
+
+In this mode the READY computation reads **`work/tasks/backlog/`** instead of `work/tasks/ready/` (or, if the caller explicitly says to drive BOTH, the UNION of `tasks/backlog/` + `tasks/ready/`). Everything else is unchanged:
+
+- **READY** = every `blockedBy` is in `work/tasks/done/` AND `needsAnswers !== true` AND `humanOnly !== true` — the SAME gating, just over the staging set (and, when the caller scopes the run to specific slugs, restricted to those). `blockedBy` still resolves against `work/tasks/done/` exactly as in the default; deps held in `tasks/backlog/` (or `tasks/ready/`) that are not yet `done/` are BLOCKED, so honour the same dependency ordering.
+- **GATED** (`needsAnswers`/`humanOnly`) and **BLOCKED** mean exactly what they mean above; a `humanOnly`/`needsAnswers` staged task is NEVER agent-buildable here either.
+- The build is the SAME `dorfl do task:<slug> --isolated --allow-backlog`, the SAME Gate-3 diff-vs-criteria review, the SAME merge-via-PR-comment, and the SAME accumulate-don't-block stuck-set. The one added flag is **`--allow-backlog`**: it widens `do`'s task resolution to also search `tasks/backlog/`, so the isolated build can resolve a staged slug. WITHOUT it, `do` searches only `tasks/ready/` + in-progress and would throw `no task '<slug>' found in work/in-progress/, work/tasks/ready/` — i.e. this opt-in mode is a spec without a mechanism unless you pass the flag. Everything else about the build (claim, lock, gate, Gate-2) is identical to driving a ready task; the staged task done-moves `tasks/backlog/ → tasks/done/` directly, because your explicit drive IS the promotion. (The staged task must be on the arbiter's `main` for the isolated build to see it — per [Selection + isolation](#selection--isolation), push it and its deps first if they are local-only.)
+
+This mode exists so a caller who has already decided a set of staged tasks is good can have the conductor build them straight from `tasks/backlog/` without first promoting them into `tasks/ready/`. It does NOT relax the review-first nature of staging for any OTHER caller or run; it is a per-invocation, explicitly-requested override of the read location only.
+
+**Why drive in place beats promote-then-drive (the competition window).** The obvious-but-wrong way to build a staged task is to first promote it `tasks/backlog/ → tasks/ready/`, then drive it. But `tasks/ready/` is the AGENT POOL: the instant a task lands there on the arbiter, a CI `advance` leg OR a machine-local `run` daemon can CLAIM it (both pull from `tasks-ready`). So promote-then-drive opens a **competition window** — the autonomous claimer races the human who wanted to drive the work themselves. Driving in place with `--allow-backlog` keeps the body resting in `tasks/backlog/` (never the pool), so no CI leg or `run` daemon can claim it: the human keeps sole control of the set they are driving until they decide (if ever) to promote. Staging is not only review-first admission; it is the human-control position — promotion to the pool is EXACTLY what makes an item claimable-by-anyone. So drive in place; never promote-then-drive.
+
+### 1. CHECK freshness / up-to-dateness of each ready task
+
+**A ready task is not necessarily a CORRECT task.** Tasks are authored ahead of time; by the time one is ready its load-bearing premises may have **drifted** — something it says is "unconsumed / not yet built / still TODO" may already have landed in `work/tasks/done/` + the code. Building a drifted task wastes a full `do` run (the build agent will rightly STOP, or worse, churn working code) — and the conductor, which sees the WHOLE graph, can catch it cheaply UP FRONT.
+
+For each ready task, before dispatching `do`, sanity-check its premises against current reality:
+
+- Read the task's "What to build" + any **drift-check / READ-FIRST** block (tasks often name the exact files + the premise to confirm).
+- Spot-check the load-bearing claims: if it says "X has zero consumers", "Y still uses the old path", "the seam is unwired" — grep `work/tasks/done/` + `src/` to confirm that is STILL true. Recently-merged tasks are the usual culprit (a convergence that already happened, a verb already renamed, a primitive already adopted).
+- Glance at `work/notes/observations/` for a `*-premise-drifted` / drift note naming this task.
+
+If the task still holds → proceed. **If it smells stale → it's a WALL**: record it in the stuck-set with the specific premise that no longer holds + a suggested re-scope, SKIP it (per the accumulate-don't-block rule), and move on. (This catches drift cheaply up front. The build-time backstop also exists: a task that IS drifted and slips past this check makes the build agent raise a STOP — the runner routes it to needs-attention with the agent's reason, skipping the wasted gate — but catching it here saves the whole `do` run.)
+
+This is also the natural place for a **light look-ahead**: skim `work/specs/ready/` (and, if cheap, `work/notes/observations/` + `work/notes/ideas/`) for what's coming — it informs the forward-notes in step 2. The DEEP survey-everything pass is `orchestrate`'s job, not this skill's; keep this shallow.
+
+### 2. CHECK for forward-looking notes a soon-to-be-tasked spec will need
+
+Before building, scan `work/specs/ready/` for a spec that will be tasked soon and whose design **depends on the shape** of tasks you're about to land (a `taskedAfter:` / "builds on the X convergence" relationship). If a ready task should carry a `> FORWARD-POINTER` note so that spec can be tasked later WITHOUT amending the spec (e.g. "keep this loop/tick separable", "keep `-n` sequential", "don't rename X — the advance migration owns it", "shape this as a named callable unit"), **add the note to the task body now** (compose `to-task`' forward-note discipline). These notes are load-bearing: they prevent the downstream spec from needing changes. A note you're CONFIDENT about: plant it and COMMIT it (it must land before that task's `do` to take effect; per rule 5 this small protocol edit is committed, unlike authored artifacts). If a note is non-trivial or you're unsure it's wanted, that is a WALL → record it in the stuck-set (surface it with the batch when the loop stalls) rather than planting a guessed note.
+
+> This is the step that earns the conductor its keep — a per-task `do` agent only sees its own task; only the conductor sees the whole graph + the pending specs and can plant the cross-task notes.
+
+### 3. SELECT the tasks + a practical order
+
+From the READY set, order by: (a) **dependency** (a task that unlocks others first), then (b) **practical** concerns — serialise tasks that edit the SAME hot file (e.g. one big `cli.ts`) so rebases stay trivial; prefer the order that keeps each subsequent claim rebasing cleanly off fresh `main`. State the planned order (and why) before you start.
+
+### 4. For EACH fresh, ready task, in order — BUILD → REVIEW → MERGE
+
+**4a. Build it** — ALWAYS `--isolated`:
+
+```sh
+dorfl do task:<slug> --isolated
+```
+
+**`--isolated` is the one flag this skill mandates. Everything else — review mode, integration mode, harness, model — is LET TO CONFIG** (resolved `flag > env > per-repo > global > default`), so do NOT hardcode `--review`/`--propose`/`--merge` here: the repo's `.dorfl.json` decides, and `do --propose` is already the default. (`--isolated` reads the target repo's committed `.dorfl.json` from the arbiter's main, so per-repo `harness`/`verify`/`noPR`/`review` apply automatically — no `--harness`/env workaround.) **At the START of a drive, CONFIRM the run mode with the user** — do they want Gate 2 (`--review`, off by default — the human-first family default), and propose vs merge integration? — and add `--review` / `--merge` / etc. as explicit per-run OVERRIDES only when the user asks; otherwise let config drive every build of the drive.
+
+After a failed/aborted isolated run, a stale job worktree can linger and block the next build's mirror fetch — run `dorfl gc` (or `gc --force --yes` once you've confirmed the work is safe on the arbiter) to reap it before continuing. Use a **generous timeout** — `do` runs a build agent + the full gate + (if enabled) the Gate-2 review and can take well over an hour for a big task. If you interrupt it, KILL the spawned `do`/agent process tree explicitly (an abort of your wrapper does NOT stop the child); the isolated worktree is then reaped/recovered via `gc` + the kept arbiter branch (your checkout is untouched).
+
+- **Non-zero exit** (red gate / Gate-2 block / rebase conflict) → the item is now in needs-attention (its lock is `state: stuck`) with its reason in the body and its branch preserved on the arbiter. STOP that task (golden rule 2), skip its dependents, move to the next INDEPENDENT ready task. If the reason is a FIXABLE problem (not a human-decision block), it is recoverable IN-LOOP via `requeue` + re-`do` (continues from the kept branch) — see [Recovering a needs-attention item](#recovering-a-needs-attention-item-requeue); otherwise it becomes a stuck-set question.
+
+**4b. Gate-3 — review the opened PR yourself** (the conductor's own review, the third review layer after Gate-1 = `do`'s acceptance gate and Gate-2 = `do`'s PR/code-review gate — the discipline that makes you a real reviewer of the result, not a rubber stamp). `do` already ran Gate-1 AND Gate-2 before opening the PR, so **trust that green** — do NOT re-run the (potentially slow) acceptance gate here. Your job is the JUDGEMENT the gates can't fully do: does the diff actually deliver THIS task?
+
+- Read the **diff against the task's acceptance criteria** — tick each criterion (apply the `review` skill's lenses + destination check).
+- **Verify every drift note / forward-pointer / must-fix-before-consume** the task carried was actually honoured (these are exactly where a `do` agent silently drifts — e.g. "don't rename X", "keep it sequential", "make the omitted path REFUSE"). Grep the branch to confirm.
+- Read the gate-generated `work/notes/observations/review-nits-<slug>-*.md` and triage each nit (blocking? benign? a real off-path finding worth its own observation?).
+- **Verdict:** if a drift note was violated or an acceptance criterion is unmet → **BLOCK** (comment the blocking findings; do NOT merge). If it is a clear BLOCK or clear APPROVE, act on it. If it is a genuine **judgement call** (a maybe-blocking nit, an ambiguously-met criterion), that is a WALL → record it in the stuck-set and skip (do not merge on a coin-flip), per the [accumulate-don't-block rule](#the-accumulate-dont-block-rule). Otherwise **APPROVE**.
+
+  > Dropping the Gate-3 re-verify is SOUND by default: `do`'s OWN acceptance gate runs against the merged artifact, because the `freshWorktreeGate` config (ON by default) runs `prepare`+`verify` in a CLEAN throwaway worktree cut from the work branch REBASED onto `<arbiter>/main` (the exact tree that integrates) — closing the checkout-vs-pushed-tree divergence at the root, so there is no separate per-task re-verify to re-introduce. (The opt-out `--no-fresh-worktree-gate` reverts to the old in-build-worktree pre-rebase gate, where that rare divergence is consciously accepted.)
+
+**4c. Merge** (golden rule 4):
+
+```sh
+gh pr comment <n> --body-file /tmp/approve-<n>.md     # leads with APPROVE ✅ + per-criterion reasoning
+gh pr merge <n> --squash --delete-branch
+```
+
+Use `--body-file` (PR bodies are backtick-heavy and break inline `--body` shell quoting).
+
+> PROVIDER ASSUMPTION: the verdict-as-PR-comment + `gh pr merge` flow above assumes **`--propose` mode + a GitHub arbiter** (the only review-surface this skill knows today). In `--merge` mode `do` integrates directly with no PR — then your Gate-3 diff review still applies, but you record the verdict in the task/observation, not a PR comment, and there is nothing to `gh pr merge`. A non-GitHub arbiter has no `gh` at all. Making the approval/merge surface provider-agnostic (a likely future `dorfl` command, e.g. an `approve`/`land` verb) is NOT built yet; until then this step is GitHub-propose-specific — adapt the merge mechanics to the repo's actual integration mode.
+
+**4d. Re-sync + re-evaluate:** recompute the READY set from the ARBITER (read-only) — `git fetch origin` and read the refreshed `origin/main` `work/` state (or use the mirror-side scan). You do NOT need to mutate a working checkout to do this:
+
+```sh
+git fetch origin   # then read origin/main's work/ state to recompute the ready set
+```
+
+Builds run `--isolated` on the arbiter, NOT your checkout, so a `git fetch` against the arbiter is all you need to RECOMPUTE the READY set — there is no local rebase dance, no branch switch, and no clean-tree precondition for the next dispatch (per golden rule 7, do not `git checkout`/`pull` INTO the human's working tree as a driving side-effect; if you are driving from a scratch clone you own, fast-forwarding IT is fine). If the next `do` runs from a BUILT copy of dorfl (e.g. a local checkout of this very repo), rebuild it so the merge you just made is in the binary the next `do` invokes. The merge landed `work/tasks/done/<slug>.md` on `main`; any task blocked only by it is now unlocked. Recompute the READY set (steps 0–1, including a fresh freshness check on newly-unlocked tasks) and continue.
+
+### 5. CONTINUE until nothing can advance
+
+Repeat step 4 until no ready task can advance (the READY set is empty OR every remaining ready task is parked in the stuck-set). THEN deal with the stuck-set ([the rule](#the-accumulate-dont-block-rule)): if a human is present, ask the batched questions and resume the loop from the answers; if not, report the stuck-set and stop.
+
+### 6. SUMMARISE — the conductor's report
+
+End with a structured rundown (this is a first-class deliverable, not an afterthought):
+
+- **Built + merged** — each task with its PR number + a one-line note on any drift/forward-pointer/must-fix it honoured (`do` ran the acceptance + review gates; you reviewed the diff).
+- **Routed to needs-attention** — each, with the EXACT blocking reason, whether the agent produced no code vs. a real bug the gate caught, and that the branch is preserved on the arbiter (recoverable via `requeue` + re-claim, or `work-on`).
+- **Still blocked / gated** — what remains and on what (a needs-attention item? a `needsAnswers` human gate?).
+- **What's now UNLOCKED in the project** — new commands, new behaviours/capabilities, retired verbs, and crucially **which specs are now taskable / unblocked** by what landed (the cross-cutting view only the conductor has).
+- **Observations filed** (committed as you go, per rule 5) — list them so the human can find them in `git log`.
+- **Housekeeping** — any direct-to-`main` chore commits you made (claim reverts, forward-notes), so the human can see them in `git log`.
+
+When you run unattended (no human reachable), this report (plus the stuck-set) is your RESULT to whoever invoked you, not a message to a human.
+
+## Batching the questions
+
+When the loop stalls with a non-empty stuck-set, do NOT ask one question at a time. **Regroup the stuck-set into a single, well-organised batch** (the way a good conductor surfaces everything at once for one efficient answering pass):
+
+- Group by item, each with: the task, the SPECIFIC question, why it's stuck (stale premise / uncertain forward-note / review judgement call), enough inline context to answer WITHOUT opening the file, and a **suggested default** where you have one.
+- Order by leverage (a question whose answer unblocks the most downstream work first).
+- If a human is present: present the batch, take answers, resume the loop (resolved → buildable again; deferred → stays parked). If not: this batch is the residue you report and stop on.
+
+The batch is conversational (asked) or reported (unattended), not a written file.
+
+## Beyond tasks
+
+This skill builds READY TASKS. Two things sit ABOVE it, sharing its loop shape:
+
+- **`orchestrate`** — the human-in-the-loop META conductor: surveys _everything_ (observations / ideas / specs / tasks), advances what it can (tasking specs, triaging), fills judgement gaps with the human conversationally until new tasks are READY, then **delegates the building to THIS skill** and surfaces the stuck-set to the human.
+- **`advance`** — the AUTONOMOUS, file-mediated version of the same idea, driven by `run`/CI with a `work/questions/` sidecar. `drive-tasks` + `orchestrate` are the human-agency, synchronous siblings of `advance`; they share the same tick contract.
+
+The conductor is **tick-agnostic**: today the per-item action is `dorfl do task:<slug>` (build a task); as `advance`-class ticks land (task / triage / surface / apply), the SAME loop applies — only the per-item command in step 4a changes. (Mirrors the loop/tick split in `run`: the conductor is a _loop_; the per-item command is the _tick_.)
+
+## Pitfalls
+
+- **The interrupt footgun.** Aborting your `do` wrapper does NOT kill the spawned agent — it keeps editing files in the background. After any interrupt, `ps`-find + kill the `do`/agent/`tsc` tree, discard its partial edits, and release the claim (the runner reverts the lock; the body is already resting in the pool `tasks/ready/`) before redoing.
+- **Flaky tests red a good gate.** If a task's gate fails ONLY on a known-flaky test with everything else green, re-run before treating it as a real block (and the flake itself is a `notes/observations/` note, not a task fix).
+- **A `do` that delivers no code is NOT a success** (nothing changed → the gate passes vacuously). The runner catches this two ways — an agent STOP (drift) routes to needs-attention before the gate, and Gate-2 (plus your Gate-3) check the _diff against the criteria_, not just the gate. Trust the block; never merge an empty-or-criteria-unmet diff.
+- **Don't sum two freshness models.** When reporting cross-repo + local state, keep them distinct.

package/dist/skills/from-idea/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: from-idea
+disable-model-invocation: true
+description: 'The from-scratch ON-RAMP: take a raw project idea and end with a scaffolded work/-contract repo where that idea is captured as a spec in work/specs/ready/, ready to task. The front door that owns the idea-interview and sequences setup (scaffold) then to-spec (synthesize). NOT a spec-producer itself — to-spec is the synthesis primitive it calls; NOT adversarial spec-grilling (that is the separate grilling skill).'
+---
+
+# from-idea
+
+**The from-scratch entrance to the main flow.** You have a raw idea ("I want to build X") and want ONE move that ends with a contract-ready repo holding that idea as a spec in `work/specs/ready/`, ready to task. This is **rung A of the spec lifecycle's front door** — the on-ramp that wraps the first two steps of the main flow (`setup` then `to-spec`) and adds the one thing neither does: a thin **interview that turns a raw idea into something spec-worthy**.
+
+It is an **on-ramp** (per `work/SKILL.md`'s taxonomy — a starting situation that generates work, then merges onto the main flow), not a survey-loop. It is a **thin orchestrator**: its entire net-new surface is the idea interview plus two skill invocations in order plus the plumbing between them. Everything else is borrowed.
+
+## What it is NOT (the boundaries that keep it thin)
+
+- **NOT a spec-producer of its own.** `to-spec` writes the spec (it owns the spec shape, the `work/protocol/spec-template.md`, the launch-snapshot banner, the `specs/ready/` target, the two autonomy axes). from-idea is the FRONT DOOR that calls it. Read the two names as a pair: `from-idea` owns the on-ramp (setup + the interview); `to-spec` is the synthesis primitive it hands the conversation to. Do not reimplement any of to-spec here.
+- **NOT a scaffolder of its own.** `setup` owns the `work/` skeleton, the `work/protocol/` docs, `CONTEXT.md`, the `.dorfl.json` `verify`/`prepare` gate, and the empty-vs-populated detection. from-idea CALLS setup; it never hand-rolls a "is this a contract repo?" check or writes `CONTEXT.md` itself (that forks setup's detection and drifts). The one-way direction is fixed: **from-idea calls setup; setup never calls from-idea** (setup stays a focused adoption primitive). setup's empty-repo branch MAY _mention_ from-idea as the next step — a discoverability pointer, never an invocation.
+- **NOT adversarial grilling.** Stress-testing a plan/design before building is the personal `grilling` skill's job. from-idea clarifies only enough to be spec-worthy and DEFERS the rest (see the interview floor below). If the user wants the idea grilled, that is a separate move after the spec lands.
+
+## The sequence (honor BOTH human checkpoints; never auto-commit)
+
+```
+clarify the idea  →  setup (PLAN → HARD STOP → scaffold)  →  to-spec (write specs/ready/<slug>.md, unstaged)
+```
+
+`setup` MUST run first: `to-spec` writes to `work/specs/ready/`, which requires `work/` to exist. The flow has **two natural human checkpoints**, and from-idea honors both:
+
+1. **setup's plan-confirm HARD STOP** — setup presents the proposed description + detected `verify`/`prepare` gate (+ any Phase-B mapping) and STOPS for the user to ratify before writing the judgement-heavy parts. Do NOT bulldoze this; it is a real stop. Let setup own its arc.
+2. **The spec landing unstaged in `specs/ready/`** — `to-spec` leaves the file in the working tree for the human to review; it does not stage/commit. from-idea inherits that etiquette: **never stage/commit/push** at any step.
+
+## Step 1 — Clarify the idea (the ONE net-new piece): just enough to be spec-worthy
+
+This is the only doing from-idea adds. Run a SHORT interview to lift the raw idea to the floor a spec needs — no further.
+
+**The interview floor (the stop condition).** Clarify enough that `to-spec` can write a coherent launch snapshot. Borrow to-spec's own spine — a spec-worthy idea has:
+
+- **(a) the problem / intent** — what is this for, what pain or opportunity does it address;
+- **(b) the rough shape of success** — what does "it works" look like, who/what uses it, what it integrates with;
+- **(c) the obvious seams / constraints** — the highest seams the feature would be tested at, and any hard constraints (stack, platform, external systems) the user already knows.
+
+That is the FLOOR, not "everything resolved." Ask a small number of focused questions (think 2–5, batched), then stop.
+
+**The no-grill / defer rule (do not become a second grilling skill).** Genuine design forks, unknowns, and "we'll decide later" calls are NOT interview rounds — they are recorded by `to-spec` as `needsAnswers: true` with the open questions in the spec body, and DEFERRED. The auto-tasker then refuses to task until a human resolves them. Be honest: a spec flagged `needsAnswers` is the correct output of a real but unresolved idea, far better than over-interviewing to force a false resolution. When in doubt, defer rather than grill. (If the idea is so thin it is barely a wish, say so and offer to capture it as a `notes/ideas/` note instead of pushing it through to a spec.)
+
+**One interview, two consumers.** The answers you gather here feed BOTH downstream skills — do not let them re-ask:
+
+- the one-to-two-sentence **project description** (problem + intent) is what setup's A2 step needs for `CONTEXT.md`;
+- the fuller **problem + shape + seams + open questions** is what to-spec synthesizes into the spec.
+
+So you interview ONCE. When setup's A2 asks "what is this repo about?", you already have the description — supply it, do not re-interview (that same-session double-ask is exactly the drift the on-ramp pattern forbids). setup (not from-idea) writes `CONTEXT.md` from that description.
+
+## Step 2 — Run setup (always; let its idempotency decide depth)
+
+**Always invoke `setup`** — do NOT hand-roll a `test -d work/` to decide whether to. setup's A1 already detects empty-vs-populated and does the right thing in each case, and re-running it on an existing contract repo **re-syncs the `work/protocol/` docs** (the one legitimate clobber) so the repo picks up protocol updates. Skipping setup would skip that refresh and fork its detection logic.
+
+- **Empty / new repo (the common from-idea case):** setup does Phase A — scaffolds `work/`, copies `work/protocol/`, writes `CONTEXT.md` (from the description you gathered in step 1) and `.dorfl.json` (the `verify`/`prepare` gate it detects, presented for confirmation at its HARD STOP). Phase B is empty.
+- **Existing contract repo (adding a new idea to a repo already set up):** setup's Phase A is a near-no-op + protocol re-sync; the scaffold already exists. You then go straight to step 3. **Flag the Phase-B-hijack seam:** if the repo is populated with convertible material, be explicit that the intent is "scaffold/refresh and accept a NEW idea", not "migrate everything" — do not let setup's Phase-B conversion hijack the from-idea session. (A new idea is not migration of existing material.)
+
+Honor setup's HARD STOP: present the plan, wait for confirmation, then it scaffolds. Feed it the description from step 1 so its A2 does not re-ask.
+
+## Step 3 — Hand the conversation to to-spec
+
+Once `work/` exists (setup's scaffold confirmed and written), invoke `to-spec`. It synthesizes the SAME conversation you have been having — the idea, the clarifications from step 1, the codebase understanding setup just established — into `work/specs/ready/<slug>.md`:
+
+- to-spec targets **`specs/ready/`** (the auto-task pool) — that is its written target and the goal of this on-ramp. from-idea does NOT route the spec into `specs/proposed/` (staging): there is no grilling/promotion gate here (grilling is scoped out), so the review gate is simply the **unstaged file** a human reviews before tasking. (If a session later wants the idea grilled before it is trusted, that is a separate move — and `specs/proposed/` is where a review-first spec would live — but from-idea's deliberate target is `ready/`.)
+- to-spec sets the two autonomy axes from what the interview resolved: `humanOnly` if a human must drive the tasking, and `needsAnswers: true` (with the questions in the body) for everything step 1 deliberately deferred.
+- to-spec writes the file UNSTAGED and reports the path. from-idea does not commit it.
+
+## Report + hand off
+
+Tell the user, concisely:
+
+- the repo is now contract-ready (what setup scaffolded / re-synced, the `verify` gate configured);
+- the spec written, by path — `work/specs/ready/<slug>.md` — left UNSTAGED for review, plus any `needsAnswers` questions it carries that a human must resolve before tasking;
+- **what's next on the main flow:** review the spec, then task it with `to-task` (or `dorfl do spec:<slug>` once the runner is installed and the spec is agent-safe). If the idea has real design forks worth pressure-testing first, point at the `grilling` skill — explicitly NOT part of this on-ramp.
+
+**Git etiquette:** never stage, commit, or push — leave both setup's scaffold and to-spec's spec in the working tree for the user to inspect and commit (the producer-skill convention setup and to-spec both follow).
+
+## Boundary (what from-idea does NOT do)
+
+- It does NOT reimplement detection (setup A1), the gate (setup A3/A3b), `CONTEXT.md` (setup A2), the spec shape / banner / target (to-spec + `spec-template.md`). Its only net-new surface is the idea interview + ordering the two calls + feeding the description to setup.
+- It does NOT grill the idea adversarially (the `grilling` skill), force-resolve genuine unknowns (they become `needsAnswers`), or push a barely-a-wish idea onto the spec board (offer `notes/ideas/` instead).
+- It is NOT called BY setup (one-way: from-idea → setup). setup may _mention_ it; it never invokes it.
+- It NEVER auto-commits, and it never bulldozes setup's plan-confirm HARD STOP.

package/dist/skills/merge-prs/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: merge-prs
+disable-model-invocation: true
+description: "Review the open work/ PRs and land them EFFICIENTLY: partition into conflict-free clusters, gate each cluster's combined tip ONCE, then merge the cluster; PRs that don't cleanly combine fall out to their own gate. The batch-landing sibling of drive-tasks (which builds+merges one task at a time). Requires gh + a GitHub arbiter in propose mode."
+---
+
+# merge-prs
+
+**Land the already-built, not build the not-yet-built.** `drive-tasks` is the conductor that _builds_ ready tasks one at a time and merges each PR as it opens. `merge-prs` starts one step LATER: a set of work PRs is already OPEN (they came from `dorfl do --propose`, `run`, CI intake, or a `drive-tasks` pass you didn't merge), and the job is to review them and get them ONTO `main` with the fewest possible gate runs.
+
+The trick is **batching by conflict-free clustering**. Instead of one review then gate then merge per PR (N gate runs), partition the approved PRs into clusters that touch disjoint files, combine each cluster onto a scratch branch, run the repo's `verify` gate ONCE against that combined tip, and merge the whole cluster. N PRs that don't overlap become 1 gate run, not N.
+
+It is a **methodology skill** (prose you follow), like `review` and `drive-tasks`, NOT a runner command. **Precondition:** it operates over **open GitHub PRs** on a repo using the **`work/` contract**, in **`propose` integration mode**, with **`gh`** available. If the arbiter is not GitHub, or integration is `merge` (no PRs), this skill does not apply as written (see [Provider assumption](#provider-assumption)). It composes:
+
+- **`review`** (`skills/review/`): the diff-vs-criteria discipline, applied PER PR before it is eligible to join a cluster. A PR that fails review never enters the batch.
+- **`drive-tasks`** (`skills/drive-tasks/`): the sibling conductor. Its [accumulate-don't-block rule](../drive-tasks/SKILL.md) and its **never-touch-the-target-checkout** rule (golden rule 7) apply here UNCHANGED. A PR you can't cleanly land goes in the stuck-set and you move on; all combining/gating happens in a scratch worktree/clone you own, never the human checkout.
+
+## When to use vs. not
+
+- **Use** when several work PRs are already open and you want to land the sound ones in as few gate runs as possible; after a `run`/CI burst left a pile of green-gated PRs awaiting a human merge; when you'd rather review-and-land a backlog of PRs than build new tasks.
+- **Do NOT use** to BUILD tasks; that is `drive-tasks` (or `dorfl do`). If there are zero open PRs, there is nothing to do here. If integration mode is `merge` (direct-to-main, no PR), there is no PR surface to batch, because the landing already happened at build time.
+
+## The one correctness rule (why clustering, not just "gate the combine")
+
+The whole value is "gate once for N PRs", but a combined gate is only HONEST if **what you gated is what actually lands**. Two ways to break that, and the rule that avoids both:
+
+- Under `gh pr merge`, each PR squash-merges onto the CURRENT `main`, so after the first merge the tree GitHub produces for the second PR is NOT byte-identical to the combined tip you gated. If two PRs touch the **same file**, a green combined gate can still yield a broken/conflicted `main`.
+- So a combined gate over OVERLAPPING PRs is necessary-but-not-sufficient. It can lie.
+
+**The rule: only ever batch PRs whose file-sets are DISJOINT.** Within a conflict-free cluster there is no overlap for a later merge to invalidate, so the combined green gate genuinely predicts each per-PR merge. Concretely: partition by "do these PRs' changed-file sets intersect?" A PR that overlaps any other lands in its OWN singleton cluster (gate it alone, merge it alone). You lose the batching win for that one, but never the honesty. This is the "combine only the PRs that make sense" instinct, made a hard invariant.
+
+> Overlap is judged on **changed files** (`gh pr diff <n> --name-only`), which is a conservative proxy: two PRs can touch the same file on non-adjacent lines and still merge cleanly, so file-level disjointness may over-split (extra singletons) but never under-splits into a dishonest batch. That trade is deliberate: prefer an extra gate run over a lying one. (If you want tighter packing later, upgrade the test to an actual trial `git merge`/`rebase` in the scratch tree and treat a clean 3-way merge as non-conflicting; until then, file-set disjointness is the safe default.)
+
+## The loop
+
+Run from ANYWHERE: you need only the arbiter (a URL/remote) plus `gh` plus a scratch area. Resolve the arbiter EXPLICITLY; if `cwd` is the human's checkout, treat it as READ-ONLY (drive-tasks golden rule 7).
+
+**0. Enumerate the open work PRs.** `gh pr list --state open --json number,title,headRefName,url`. Keep only the ones that are work-branch PRs (dorfl pushes `work/<slug>` head branches, so filter on `headRefName` prefix / your repo's convention). Map each PR back to its task slug and the `work/tasks/**/<slug>.md` it done-moves, so review has the acceptance criteria to check against.
+
+**1. Per-PR review (the eligibility gate).** For EACH PR, apply the `review` discipline (`skills/review/`) to its diff vs. its task's criteria. This is the same Gate-3 diff-vs-criteria pass `drive-tasks` step 4 does, just done up front for all PRs:
+
+- clear **APPROVE** → the PR is eligible to be batched.
+- clear **BLOCK** (a drift note violated, an acceptance criterion unmet, an empty/vacuous diff) → drop it from the batch, record the blocking finding (post it as a PR comment leading with `BLOCK`, per drive-tasks step 4), and do NOT land it.
+- genuine **judgement call** (maybe-blocking nit, ambiguously-met criterion) → that is a WALL, so stuck-set it and skip, per the [accumulate-don't-block rule](../drive-tasks/SKILL.md). Never merge on a coin-flip.
+
+**2. Cluster the approved PRs by conflict-freedom.** For each approved PR collect its changed-file set (`gh pr diff <n> --name-only`). Group PRs so that within a group every pair has DISJOINT file-sets (the [one correctness rule](#the-one-correctness-rule-why-clustering-not-just-gate-the-combine)). Any PR overlapping another becomes its own singleton cluster. Note that dorfl PRs each done-move their OWN `work/tasks/…/<slug>.md` (distinct paths) and edit distinct code, so in practice most PRs land in one big disjoint cluster and overlaps are the exception.
+
+**3. Per cluster: combine → gate ONCE → merge the cluster.** In a scratch worktree/clone you own (NEVER the human checkout):
+
+- fetch the arbiter, create a scratch integration branch off the current `main`, and merge each PR's head branch into it (`git merge --no-ff <headRef>` or cherry-pick the PR range). A merge that CONFLICTS despite the file-set proxy (rare, but possible) → pull that PR OUT of the cluster into a singleton and re-form the cluster; do not force it.
+- run the repo's **`verify` gate** ONCE against the combined tip. In this repo that is `pnpm -r build && pnpm -r test && pnpm format:check` (the `dorfl verify` equivalent; see AGENTS.md. Do NOT invent a gate, read the repo's `dorfl.json` `verify`).
+- **green** → merge every PR in the cluster: `gh pr comment <n> --body "APPROVE ✅ (batch-gated with #a #b #c)"` then `gh pr merge <n> --squash --delete-branch` for each. Because the file-sets are disjoint, the sequential squash-merges reproduce the tip you gated.
+- **red** → the cluster is NOT landable as a batch. Do NOT merge any of it on a batch coin-flip. Bisect by falling back to gating the cluster's PRs INDIVIDUALLY (singleton gate each), land the green ones, and stuck-set the red one with the failing gate output. A batch red almost always means one bad PR poisoning the combine, and the singleton pass isolates it.
+
+**4. Recompute and continue.** Each cluster merge lands `work/tasks/done/<slug>.md` for its PRs on `main`. Fetch, re-enumerate open PRs (new ones may have appeared; a PR blocked-by a now-merged one may have become reviewable), and repeat from step 0 until no open work PR can advance.
+
+**5. Surface the residue in ONE batch.** When nothing more can land, deal with the stuck-set exactly as drive-tasks does: **human present** → present the blocked/judgement-call PRs as one batched set of questions, take answers, resume; **no human reachable** → stop and report the stuck-set plus the landed/blocked summary. Never dribble questions one at a time.
+
+## Confirm the run mode first
+
+At the START, CONFIRM with the user (mirrors drive-tasks): squash vs. merge-commit for the `gh pr merge` (default `--squash --delete-branch`), and whether they want you to actually merge or only review-and-report the clusters (a dry-run: emit "these N PRs cluster into these groups, each would gate as one" without merging). Batch-MERGING is mutating and irreversible-ish (branches deleted), so a dry-run first pass is often the right default; offer it.
+
+## Provider assumption
+
+The `gh pr comment` + `gh pr merge` flow assumes **`propose` mode + a GitHub arbiter**, the only review-and-land surface dorfl exposes today. There is **no `dorfl` merge/land/approve verb yet** (checked against the CLI: `scan/run/do/advance/complete/promote/requeue/drop/intake/...`, none land a PR), so this skill is GitHub-propose-specific by necessity, same as `drive-tasks` step 5. In `merge` mode there are no PRs to batch. A future provider-agnostic land verb would let this skill drop the `gh` specifics; until then, adapt the merge mechanics to the repo's actual arbiter.
+
+## Relationship to the other conductors
+
+- **`drive-tasks`** BUILDS ready tasks (one at a time, build then review then merge). `merge-prs` starts where a build left an OPEN PR and batches the LANDING. Use `drive-tasks` to turn tasks into PRs; use `merge-prs` to turn a pile of PRs into merges cheaply.
+- **`orchestrate`** is the meta-conductor over the whole tree. If it (or `run`) produced a burst of PRs, `merge-prs` is the natural closer to land them in a batch rather than one-by-one.

package/dist/skills/orchestrate/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: orchestrate
+disable-model-invocation: true
+description: 'The human-in-the-loop meta-conductor: survey the whole work/ tree, advance every autonomous rung, batch the judgement residue to the human, then build the ready tasks via drive-tasks.'
+---
+
+# orchestrate
+
+**The conductor of conductors.** `drive-tasks` builds the _ready tasks_. `orchestrate` is the layer above THAT: it looks at the **entire** `work/` tree — observations, ideas, specs, tasks, needs-attention — works out **what can advance and what is stuck on a human**, does every autonomous rung it can, and turns the human into nothing but an **answerer of well-batched questions**, looping until the backlog of ready tasks is drained.
+
+It is a **methodology skill** (prose you follow), like `to-task` / `review` — NOT a runner command. It is **protocol-native**: it works the `work/` tree by reading the contract files directly (frontmatter + bodies), not by leaning on runner commands to tell it the state. (The one place runner commands ARE used is building — which it hands to `drive-tasks`, the skill whose job is to drive the `dorfl` CLI.) It composes:
+
+- **`drive-tasks`** (`skills/drive-tasks/`) — to BUILD the ready tasks (you load and FOLLOW it for the build loop; it owns the runner-CLI mechanics).
+- **`review`** (`skills/review/`) — to judge any artifact (task / spec / observation / code).
+- **`to-task`** (`skills/to-task/`) — to task a ready spec into tasks (the `tasks/backlog` staging slot).
+- **`promote`** (`skills/promote/`) — to judge a STAGED task/spec (`tasks/backlog/` / `specs/proposed/`) against its acceptance + destination before recommending its promotion into the pool.
+- **`answer-questions`** (`skills/answer-questions/`) — to walk the open `work/questions/` sidecars, DRAFT answers to the factual ones for the human to ratify, and DEFER the genuine-judgement ones into the step-3 batch.
+- **`to-spec`** (`skills/to-spec/`) — when an idea/observation has matured enough to become a spec.
+
+## When to use vs. not
+
+- **Use** when you have a populated `work/` and want the system to do _everything it can autonomously_ and then _ask you only at the real judgement residue_ — in one interactive sitting, with full visibility and agency; to answer "what needs me?" across the whole tree; as the human-driven alternative to the autonomous `advance` loop when you want to watch and steer.
+- **Don't** use it just to build already-ready tasks (that's `drive-tasks` directly), just to task one spec (`to-task`), or just to review one artifact (`review`). Don't use it as the unattended daemon (`run`/`advance`). It is **always main-session and conversational** — its defining job is the live Q&A.
+
+## Relationship to the autonomous `advance` engine
+
+`orchestrate` is the **interactive, human-in-the-loop** way to drain a `work/` tree: it asks its questions conversationally, in the session, and you answer live. Its autonomous, file-mediated counterpart is the `advance` capability, driven by `run`/CI with `work/questions/` sidecars the human answers whenever they like. Same lifecycle drain, different mode: reach for `orchestrate` when the human is present and wants visibility + agency; the autonomous engine is for unattended draining. They share the same rung contract.
+
+## Core invariant
+
+**Advance every rung you can; for everything else, ASK — never invent an answer.** Each `work/` item has autonomous rungs (triage, task, build, promote, surface-question, answer/apply) and a judgement residue (ambiguity, design forks, `needsAnswers`, stale premises). Do the autonomous part; surface the residue as batched questions; apply the answers; repeat. The human's throughput is the only limit; everything else is automatic.
+
+## The loop
+
+### 1. SURVEY the whole tree (one read pass)
+
+Read across ALL buckets and build a single picture of state + what each item needs to advance ONE rung:
+
+- **`work/notes/observations/`** — untriaged signals. Each wants: promote to a task/spec/ADR? keep as a note? delete? (a judgement rung — compose `review`).
+- **`work/notes/ideas/`** — incubating. Any matured enough to become a spec (`to-spec`)? Most are left alone (no readiness to force) — note them, don't push.
+- **`work/specs/ready/`** — for each spec: is it already tasked (does it RESIDE in `work/specs/tasked/`)? `humanOnly`/`needsAnswers`? `taskedAfter:` satisfied? → **taskable now**, **blocked on a dep**, or **blocked on a human answer**. (Tasked-ness is folder residence, not a `tasked:` marker.)
+- **STAGING** — `work/tasks/backlog/` (review-first tasks) and `work/specs/proposed/` (review-first specs), the items awaiting human promotion into the pool. NOT built/tasked here; they are a **promotion rung** (step 2, compose `promote`). Either folder may be absent when empty per the contract — treat a missing staging folder as "nothing awaiting promotion", not an error.
+- **`work/tasks/ready/`** — the task dependency graph (READY / BLOCKED / GATED), AND each ready task's **freshness** (drifted vs current `tasks/done/`+code — same check `drive-tasks` step 1 does).
+- **`work/questions/`** — open question sidecars (a `<type>-<slug>.md` with an unanswered entry). Each is an item PAUSED on an answer; classify each open question factual-vs-judgement for the answer rung (step 2, compose `answer-questions`). A missing/empty `work/questions/` means "no pending questions", per the empty-folder rule — not an error.
+- **needs-attention** — stuck items (their per-item lock is `state: stuck`) + the recorded reason; each wants a human decision (requeue-continue / requeue-reset / re-scope / drop). Read them via `dorfl status`/`scan` (which read the lock refs).
+
+Produce a short **state map**: what's ready to build, what's taskable, what's triageable, and what's parked on a human.
+
+### 2. ADVANCE the non-build rungs (no human needed)
+
+Do the autonomous rungs that PREPARE work — i.e. everything EXCEPT building ready tasks (building is step 4, deliberately last, so all gap-filling happens first). In leverage order (the rung that unlocks the most downstream work first):
+
+- **Taskable specs** → task them, NAMING the choice between the two paths that meet at the same `work/tasks/*` artifact (don't default to the conversational one by reflex):
+  - **`dorfl do spec:<slug>`** — the AUTONOMOUS, unattended path (gate-gated by `autoTask` + the spec's own gates; runner-owns-git; harness/model/gate from dorfl config, don't hardcode). PREFER this for a **ready, agent-safe spec** (`humanOnly: false`, no open `needsAnswers`, `taskedAfter:` satisfied) — and it is the path to use when the intent is to exercise the runner.
+  - **`to-task`** (the skill) — the CONVERSATIONAL, human-in-the-loop, protocol-only path (no dorfl dependency). Use it for a **`humanOnly` / unclear / not-yet-ready spec**, or whenever a conversation is wanted. (`to-task` deliberately stays runner-agnostic — it never points BACK at `do spec:`; this routing lives HERE, in the runner-aware conductor, by design.)
+  - The choice is "unattended run vs conversation", decided by the spec classification you already did in step 1 (`humanOnly`/`needsAnswers`/`taskedAfter`). A `do spec:` on a spec it cannot take (e.g. `humanOnly`) correctly REFUSES on the agent path — that refusal IS the protocol routing you to `to-task`.
+  - Then **review the produced tasks** (compose `review`; the tasker's own review→edit loop also runs on the `do spec:` path). Newly-produced tasks feed back into the survey (they may be READY, or carry their own questions).
+- **Staged items awaiting promotion** (`tasks/backlog/`, `specs/proposed/`) → run the **promotion rung**: for each, compose `promote` (review + freshness + pool-readiness gate) and emit promote / keep-staged / drop. A clear PROMOTE is recommended to the human (you never move it yourself — the runner's `promote` verb / the human does the `git mv`); a KEEP-STAGED with a fixable gap, or a judgement-call promotion, becomes a step-3 question; a clear DROP routes to the regime terminal. Promotion is the human review-gate, so the MOVE is always the human's/runner's — you surface the verdict.
+- **Clearly-resolvable observations** → triage them (compose `triage-observations`: leave / promote into a self-contained task/spec/ADR / direct-delete) where the right outcome is obvious; the ambiguous ones become questions (step 3).
+- **Open question sidecars** (`work/questions/`) → run the **answer rung**: compose `answer-questions` over the pending sidecars. It DRAFTS answers to the factual ones (each cited to its evidence) for the human to RATIFY — a ratified draft is a human-authored answer you then apply — and DEFERS the genuine-judgement ones into the step-3 batch. You never invent/finalise an answer (the human is the clock); you draft for ratification and surface the rest.
+- **Apply any human answers** you already have (ratified drafts from the answer rung, plus answers from earlier in the session) → flip the relevant `needsAnswers`, fill the task/spec gap, which may make new items advanceable (re-run step 1's classification for them).
+
+(Ready tasks are NOT built here — they accumulate for step 4, after the residue is resolved.)
+
+Commit policy (matches the producer skills): **commit your own `work/notes/observations/` notes and small load-bearing forward-notes you plant in a task body** (these are contract-native protocol edits), plus the runner-owned transitions that `do spec:` / `do` / `complete` make themselves (the tasking transition, done-moves, PR merges). Do NOT hand-author-and-commit a full spec or a fresh TASK SET — producing those is `to-spec`/`to-task`' job, and per their convention they are left UNSTAGED for human review (you surface them; the human commits). Never sweep in unrelated source. Report everything you committed in the final summary. (Tasks that get BUILT are committed/merged by `drive-tasks` via the normal PR flow.)
+
+### 3. ASK the residue — batched, conversational, never invented
+
+Everything that needs judgement becomes a **question**. Do NOT ask one at a time and do NOT guess: **regroup all open questions into one efficient batch** (the discipline this skill is named for), each with:
+
+- the item + the SPECIFIC question, inline context to answer without opening files, the consequence of each option, and a **suggested default** where you have a view.
+- grouped/ordered by leverage (answer-unblocks-the-most first).
+
+Present the batch, take the human's answers, then **apply them** (back to step 2 for the now-unblocked items). Iterate steps 1–3 until the only thing left is _building ready tasks_. Questions the human defers stay parked; you proceed with the rest.
+
+> If the human prefers to answer later / asynchronously rather than inline, offer to persist the batch as a question file under `work/questions/<date>-batch.md` (the file-mediated fallback the autonomous `advance` engine also reads). Default is conversational.
+
+### 4. BUILD the ready tasks (follow `drive-tasks`)
+
+Once the survey + gap-filling have produced a set of READY tasks, build them by **loading and following the `drive-tasks` skill inline** (you are already in the human's session — `drive-tasks` runs its build→review→merge loop here, asking the human when it stalls, exactly as you do). Hand it the whole ready set; it re-runs its own freshness check + dependency ordering, so you do NOT need to pre-filter or pre-order beyond what your survey established. Its build-loop mechanics (the long `do` process, the interrupt footgun, the diff-review, merge) are ITS to own — don't re-derive them here.
+
+Any task `drive-tasks` parks in its stuck-set (a drifted task, a Gate-3 judgement call) comes back to YOUR step 3 batch — same residue, same human.
+
+### 5. LOOP until drained, then SUMMARISE
+
+Repeat 1→4 until no rung can advance without a human answer you don't have. Then give the meta report:
+
+- **Advanced autonomously** — observations triaged, specs tasked, tasks built+merged (PR numbers from `drive-tasks`'s own report).
+- **What's now unlocked** — new ready tasks, newly-taskable specs, capabilities landed (the whole-tree view only this skill has).
+- **Parked on the human** — the questions still unanswered / deferred, and exactly what each unblocks when answered.
+- **Still stuck** — needs-attention items + the decision each awaits.
+- **Suggested next sitting** — the smallest set of human answers that would unblock the most work.
+
+## Pitfalls
+
+- **Don't invent answers.** The one unforgivable move. A confident wrong answer to a judgement question produces drifted tasks that cost far more than asking. Ask.
+- **Don't over-ask either.** Resolve from the code/ADRs what is genuinely a small certain factual gap; only the real judgement residue becomes a question (same discipline `drive-tasks`/the build agents use for tasks).
+- **Commit observations + forward-notes; leave authored artifacts for review.** Your `work/notes/observations/` notes and small planted forward-notes are committed as you go (contract-native) and listed in the summary; a freshly-authored spec or task SET is left UNSTAGED for the human (the producer-skill convention). Don't sweep in unrelated source changes.
+- **Building mechanics live in `drive-tasks`.** When you build (step 4), the long-running `do` process, the interrupt footgun (an abort does NOT kill the spawned agent), generous timeouts, flaky-gate retries, and the Gate-3 diff review are all `drive-tasks`'s — follow that skill for them; don't re-derive them here.
+- **If your OWN run is interrupted, re-orient before resuming.** This loop can run long. On resume, do a fresh step-1 survey (state lives in the `work/` files + `git`, not your memory): re-read the buckets, check what is now in-progress / needs-attention / merged, and continue from the recomputed state — never assume the pre-interrupt picture still holds.
+- **Ideas are incubating.** Don't force `work/notes/ideas/` toward readiness; surface the ripe ones, leave the rest.

package/dist/skills/promote/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: promote
+description: 'The pre-promotion checklist: judge ONE staged work/ item (a task in tasks/backlog/, a spec in specs/proposed/) against its acceptance + destination before a human admits it into the agent pool. Emits a promote / keep-staged / drop recommendation; the human (or the runner promote verb) does the move.'
+---
+
+# promote
+
+**Staging is the human review-gate.** In the `work/` contract, `tasks/backlog/` and `specs/proposed/` are STAGING (untrusted / agent-authored output lands here); the agent POOL is `tasks/ready/` and `specs/ready/`. Items enter staging by a runner-deterministic placement decision; they leave it ONLY when a human promotes them. This skill is the **discipline a human applies to ONE staged item before promoting it** — it is the checklist that makes the gate a real review, not a rubber stamp.
+
+It is a thin **methodology skill** (prose you follow), a sibling of `review`. It does NOT move anything: the promotion `git mv` (`tasks/backlog/ → tasks/ready/`, `specs/proposed/ → specs/ready/`) is a runner-owned transition (a future `dorfl promote <item>` verb, or the human's own move). You EMIT a verdict; the caller acts on it. Per the contract, an agent never sets position.
+
+## When to use vs. not
+
+- **Use** before admitting a staged task/spec into the pool: when reviewing what an agent (tasking / intake) emitted into `tasks/backlog/` or `specs/proposed/`, to decide promote / keep-staged / drop for each. `orchestrate` composes this in its survey (the "awaiting promotion" set); a human also reaches for it directly to clear a staging backlog.
+- **Don't** use it to judge an item already IN the pool (that is plain `review`), to build a ready task (`drive-tasks`), or to task a spec (`to-task`). It is the ONE gate-crossing judgement: staging → pool.
+
+## How to use
+
+For each staged item, run the `review` discipline FIRST (it is the body of this check), then add the promotion-specific gate:
+
+1. **Review the artifact** — apply `review` (i.e. `work/protocol/REVIEW-PROTOCOL.md`'s lenses + the destination check) to the staged task/spec exactly as you would any `work/` artifact. This already covers: does it deliver its stated goal, is it coherent, does it match the spec/ADR it descends from.
+2. **Freshness / drift** — staging items are often agent-authored ahead of time. Spot- check the load-bearing premises against current reality (`tasks/done/` + `src/`): does anything it says is "not yet built / still TODO / has no consumers" already hold? A drifted staged item is NOT promotable as-is — it is keep-staged with the stale premise named (the same drift check `drive-tasks`/`orchestrate` run on ready tasks, applied one step earlier).
+3. **Pool-readiness gate** — once in the pool, can the item rest there SAFELY? Promote if yes. The bar is "safe in the pool", NOT "claimable this instant":
+   - **`blockedBy` is NOT a promotion gate — it is machine-ENFORCED at claim time, so a blocked task is safe in the pool.** Do NOT keep a task staged merely because a `blockedBy` slug has not yet reached `tasks/done/`. The claim predicate already refuses an item whose `blockedBy` is unresolved, so a blocked-but-otherwise-ready task simply WAITS in `tasks/ready/` until its blocker lands, then becomes claimable automatically — no human re-check needed. Holding it in staging for an unresolved dependency duplicates an enforced invariant and needlessly strands ready work behind a human round-trip. (The blocker slug does not even need to exist yet; `blockedBy` resolves lazily against `tasks/done/` whenever a claim is attempted.) Promote a well-formed blocked task NOW; the dependency graph sequences it for you.
+   - **Task → the real gates are the UNENFORCED, human-owned ones:** `needsAnswers` is false (no open question a human must answer first — an open question is NOT machine-enforced, so a `needsAnswers:true` task promoted into the pool would be picked up blind), and `humanOnly` is correctly set (off unless never-for-agents-by-nature). A staged task carrying open questions is keep-staged until they are answered, not promoted-then-blocked. (Contrast `blockedBy` above: that one IS enforced, so it is not a reason to keep-stage.)
+   - **Spec** → `humanOnly`/`needsAnswers` correct and it is genuinely taskable (not still a design sketch). Like `blockedBy`, `taskedAfter:` is ENFORCED against `specs/tasked/` residence by the auto-tasker, so an unsatisfied `taskedAfter:` is NOT a reason to keep a taskable spec staged — promote it and let the tasker sequence it. An unready (design-sketch / question-bearing) spec stays `specs/proposed/`.
+4. **No collision / no duplicate** — confirm no item with the same `(umbrella, slug)` already rests in the destination pool or a terminal, and the work isn't already covered by a done item.
+5. **Verdict** — emit ONE of:
+   - **PROMOTE** — review passed, fresh, pool-ready, no collision. State the move the caller should make (`dorfl promote <item>`, or the `git mv`).
+   - **KEEP-STAGED** — a fixable gap that is NOT machine-enforced: a drifted premise, an open question (`needsAnswers`), a wrongly-set `humanOnly`, or a spec that is still a design sketch. (An unresolved `blockedBy` / `taskedAfter:` is NOT such a gap — it is enforced, so it is a PROMOTE, not a keep-staged.) State the SPECIFIC gap so it can be resolved, then re-checked.
+   - **DROP** — superseded / out-of-scope / duplicate. Route to the regime terminal (`tasks/cancelled/` / `specs/dropped/`) with the `reason:`, per the contract.
+
+You WRITE nothing and you MOVE nothing — you surface the verdict; the human or the runner's `promote` verb performs the transition (and a DROP is its own runner-owned move to the terminal). Batch the verdicts when judging several staged items at once, ordered by leverage (what each promotion unblocks downstream).
+
+> Why position is human-gated and runner-moved: placement is runner-deterministic on the way IN (the `originTrust` stamp + policy decide STAGING vs POOL); promotion OUT is the human's review-gate. The agent never sets the folder. See `work/protocol/WORK-CONTRACT.md` (staging → pool).

package/dist/skills/review/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: review
+description: 'Thoroughly and adversarially review a work/-protocol artifact against the work/ contract, ending in a destination check against the spec/ADR goal. Use before any artifact is trusted: a task before it lands, code in a work PR against its task, a spec before tasking, or a captured note. Emits a verdict; the caller routes it.'
+---
+
+# review
+
+**The review discipline lives in `work/protocol/REVIEW-PROTOCOL.md`** (the in-band protocol doc every set-up repo carries; the source-of-truth is `skills/setup/protocol/REVIEW-PROTOCOL.md`). This skill is the **human-facing pointer** to that standard — the operator/agent entry point a person reaches for to invoke the discipline interactively. The standard itself (the lenses, the destination check, the emitted-verdict shape) is stated ONCE in the protocol doc so the autonomous runner and the human caller cannot drift.
+
+## How to use
+
+1. Read `work/protocol/REVIEW-PROTOCOL.md` in the repo you are working in.
+2. Apply its lenses IN ORDER to the artifact under review, ENDING in the destination check.
+3. Emit the verdict it specifies (`{verdict, findings, …}`); the caller routes it (you write nothing — see "Your output" in the protocol doc).
+
+> Why the standard lives in `work/protocol/`: a `review`-named discipline that the autonomous runner invokes BY NAME must be in-band in every set-up repo, not host-installed. Operator skills (this file) are human-facing and not copied.