dorfl 0.1.2 → 0.2.0

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.