dorfl 0.0.0 → 0.1.0

package/dist/protocol/CLAIM-PROTOCOL.md

@@ -0,0 +1,217 @@
+# Claim protocol (consumed by the runner — `dorfl claim`/`do`/`complete`)
+
+This documents how a `work/tasks/ready/<slug>.md` item is **atomically claimed** by one agent (human or autonomous) when several may try at once. The tasking discipline does not perform claims — it only emits files in a shape this protocol can consume. The runner/lifecycle implements the steps here.
+
+## The core idea: claim = acquiring the item's per-item LOCK (an atomic create-only ref push)
+
+A claim **acquires the item's per-item lock** — a hidden `refs/dorfl/lock/<type>-<slug>` ref (`<type>` is `task`/`prd`) created by an ATOMIC create-only push (`--force-with-lease=<ref>:`, i.e. "succeed only if the ref is still absent"). Git's ref-update-on-push IS the compare-and-swap: the winner creates the ref; a concurrent acquirer for the SAME item finds it present and is rejected = **definitively lost, with NO retry budget** (a per-item ref only ever contends with another writer for that same item — a genuine conflict the loser should lose). The item's body STAYS in `work/tasks/ready/<slug>.md`; **claim writes NOTHING to `main`** (so an agent can claim even on a protected `main`).
+
+The claimable predicate is **"the body is in the pool `tasks/ready/` on `main` AND no lock is held on its ref."**
+
+**Separate the claim from the work.** Acquire the lock first (cheap, collision-detecting); do the work only after the lock is provably held.
+
+## The arbiter: one serialization point for updating `main`
+
+The atomicity comes from a **single repo that everyone treats as the integration point** (`origin`), whose ref update on push linearizes claims. It can be EITHER:
+
+- **A remote remote** — e.g. GitHub. Bare by construction; works across machines; everyone (including the human) participates by pushing to it.
+- **A local bare remote** — a `--bare` repo in a folder (e.g. `work.git`), reached via `file://`. Works fully offline. **Must be `--bare`** (you cannot work _in_ the arbiter: a non-bare repo with `main` checked out rejects pushes to `main`, and force-enabling that moves `main` under your working tree).
+
+The protocol is **identical** for both — it targets a remote _by name_ (`<arbiter>`), not a hardcoded URL. Switching offline↔online is `git remote set-url <arbiter> <url>` (or adding a second remote); the claim steps do not change.
+
+> **Consequence the human must accept:** you participate like an agent — you reach `main` via push (ff / `pull --rebase` then push), NOT via unsynchronized local commits onto a checked-out `main` that is also the arbiter. The arbiter ref and a working `main` you hand-commit to cannot be the same ref. This is mild, good hygiene, and is what keeps the claim guarantee intact for everyone.
+>
+> **WARNING — reconcile by REBASE, never a plain `git pull` merge.** A merge does NOT re-run `verify` on the reconciled tree, so a clean merge can hide a semantically-broken result. If your push is rejected non-fast-forward: `git pull --rebase`, then re-run `verify` on the rebased tree BEFORE pushing. (The runner path enforces this automatically as the land invariant below; on the human path it is on you — the human path is deliberately lighter, but the invariant is the same.)
+
+### Offline setup (local bare arbiter), once
+
+```sh
+# create the bare arbiter next to (not inside) your working clone
+git clone --bare /path/to/project /path/to/project-work.git   # or: git init --bare
+# in each working clone, point an `arbiter` remote at it
+git remote add arbiter file:///path/to/project-work.git
+```
+
+When back online, repoint: `git remote set-url arbiter <github-url>` (or push the bare repo's `main` up). Same protocol throughout.
+
+## The command: `dorfl claim` / `do`
+
+These steps are implemented (and verified against real git, including a truly simultaneous two-agent race) by the runner — so a human or agent does not hand-run the dance:
+
+```sh
+dorfl claim <slug> [--arbiter <remote>] [--by <who>] [--dry-run]
+```
+
+Exit codes: `0` claimed · `2` not claimable (not in the pool, or the lock is already held = lost) · `1` usage/env error. The acquire is self-arbitrating (no contended-retry class — a per-item lock never falsely contends). The steps it performs:
+
+## Claim steps
+
+```
+CLAIM (acquire the per-item lock; collision-detecting, no body move):
+  1. fetch the lock refs from <arbiter> (refs/dorfl/lock/*)
+  2. confirm the body is still in the pool: work/tasks/ready/<slug>.md on <arbiter>/main
+  3. build a PARENTLESS lock-entry commit (action: implement, state: active,
+     holder/since) with plumbing — never touches the working tree/HEAD
+  4. push it create-only to refs/dorfl/lock/<type>-<slug>   (<type> = task/prd)
+     with --force-with-lease=<ref>:   (the EMPTY expected value = "ref must be absent")
+     ├─ ACCEPTED  -> the lock is atomically yours (the body stays in tasks/ready/;
+     |              NOTHING was written to main).
+     └─ REJECTED  -> the ref already exists: another writer holds this SAME item's
+                    lock. You LOST, definitively (exit 2). No retry budget — pick a
+                    DIFFERENT pool item. (holder/since are readable on the lock entry
+                    via `dorfl status`.)
+     # who/when rides the lock entry, not a frontmatter field (no claimed_by/claimed_at).
+
+WORK (only after the lock is held):
+  5. git switch -c work/<type>-<slug> <arbiter>/main   # the body is still in tasks/ready/ on main
+     (use a dedicated worktree/clone for isolation when running in parallel)
+  6. do the work; tests green.
+  7a. SUCCESS path — the runner, at integration, lands the DURABLE move on main:
+        git mv work/tasks/ready/<slug>.md work/tasks/done/<slug>.md
+      committed together with the work (completed-task message, see below), then
+      RELEASES the lock (delete the ref). Order: durable main-move FIRST, lock
+      release SECOND — a crash between leaves a done-on-main item with a stale lock,
+      and recovery treats the main record as authoritative and clears it.
+  7b. STUCK path — if it could NOT complete (red gate, rebase/merge conflict, task
+      too ambiguous to build, timeout, rejected review): the runner amends the held
+      lock active -> stuck (+ reason and any surfaced questions ON THE LOCK ENTRY)
+      and SAVES the recoverable work as a wip commit on the kept work/<type>-<slug>
+      branch (pushed to the arbiter). NO main write, NO folder move. A human resumes
+      (stuck -> active) or requeues (stuck -> released; the body is already in the
+      pool). (The build agent never touches the lock — the runner owns it.)
+  8. integrate to <arbiter>/main as normal (PR on GitHub, or ff/rebase push offline).
+```
+
+> The durable `tasks/ready → tasks/done` / `prds/ready → prds/tasked` / `tasks/ready → tasks/cancelled` moves are the ONLY writes to the shared `main` ref, so THEY keep a small retrying CAS; the per-item LOCK acquire/release never does (it is self-arbitrating). The two are independent substrates that may legitimately disagree (e.g. `tasks/done` on `main` + a `stuck` lock co-exist after a rebase-conflict bounce of a just-completed item).
+
+## The land invariant — rebase + re-verify + advance
+
+Step 7a's durable `main` move (the LAND) is the mode-agnostic primitive: **fetch current `main` → rebase the work branch onto it → re-run `verify` (and review) on the rebased tree → advance.** A lost CAS or a moved-`main` between gate and push INVALIDATES any prior green and re-arms the gate (re-rebase, re-`verify`, retry — never a `--force`, never an auto-resolved conflict). Merge mode runs it inline at the serialised land; propose mode runs it at the human checkpoint (the propose PR is merged only after the rebased tip re-verifies green). Human review is ADDITIVE (intent/design/security), NEVER a substitute for the re-verify on the rebased tree. The durable _why_ — and the floor/ceiling gradient from bare git to a capable host — lives in ADR `land-primitive-rebase-reverify-advance`.
+
+## The prompt handed to the work agent (the `## Prompt` wrapper)
+
+When a human or an autonomous runner dispatches an agent to do the WORK phase, the agent is given a small, constant **wrapper** around the task's own `## Prompt` section. The wrapper is the same every time except the slug; an autonomous runner emits it deterministically. The task file is the spec; the wrapper just frames it and draws the line around git.
+
+```
+You are completing one work task in this repo. It has already been claimed for
+you (its per-item lock is held) and lives at work/tasks/ready/<slug>.md — read that
+file fully; it is your complete spec (What to build, Acceptance criteria, Prompt).
+Also read its source spec (the task's `prd:` field, at work/prds/ready/<prd>.md)
+for context.
+
+<!-- if promptGuidance.testFirst -->
+Implement it to satisfy every Acceptance criterion. At the agreed seam, write
+the failing test BEFORE the production code, matching the repo's house style;
+this is guidance, not a gate — the `verify` step still decides pass/fail.
+<!-- else -->
+Implement it to satisfy every Acceptance criterion. TDD where the task asks for
+it; match the repo's house style.
+<!-- /if -->
+
+If you NOTICE a problem OUTSIDE this task's scope (a flaky test, a latent bug, a
+suspicious behaviour), do NOT fix it and do NOT expand your scope. Instead drop a
+short, dated note in work/notes/observations/<short-slug>.md (one or two sentences
+is enough — what you saw and where) so the signal is captured, then carry on with
+your task. (work/notes/observations/ is an append-only capture bucket; anyone, you
+included, may add to it. Writing such a NOTE is the one exception to the "no file
+changes outside your task" rule below — it is a note, not work.)
+
+If the TASK ITSELF is the problem — it is ambiguous, under-specified, rests on a
+premise that no longer matches the code/ADRs (it has DRIFTED), or hides an
+unresolved design decision — do NOT guess and build on it. STOP and report
+specifically what is unclear or contradicted (and where), so a human can resolve it
+(the runner routes the item to needs-attention). Do not be shy about this: a
+confident build on a wrong/ambiguous premise produces wrong-but-compiling work that
+is far more expensive than a question. Building exactly what a flawed task says is
+NOT success.
+
+To STOP, make NO source change and end your final report with this EXACT
+machine-readable block (the runner detects it, routes the item to
+needs-attention with your reason VERBATIM, and SKIPS the gate + review — so put
+the specific drift report INSIDE it):
+
+=== TASK-STOP ===
+<the specific reason: which premises are false, where, and a suggested re-scope>
+=== END TASK-STOP ===
+
+The decision bar between "resolve and proceed" and "STOP" / "record a decision":
+A genuinely small, certain, SELF-CONTAINED factual gap you can resolve from the
+code itself (it affects nothing outside this task), resolve and proceed silently.
+But a choice that touches ANOTHER command/flag/task, introduces a new
+ERROR/REFUSAL, or sets a USER-VISIBLE DEFAULT is a DESIGN decision, NOT a small
+factual gap — do NOT bury it in code. If it is load-bearing AND hard to reverse,
+STOP (above). Otherwise PROCEED but RECORD it DURABLY and LINK it from the done
+record, one entry per decision — what you chose + why + the alternative(s) you
+considered + what it touches (which other flag/command/task). Any durable home
+is acceptable: a module JSDoc at the choice site (best when there is an obvious
+code site the decision governs), a "## Decisions" block in the done record / PR
+body (the recommended fallback when there is no natural code site), or a dated
+observation note under work/notes/observations/. Whichever home you pick, LINK
+it from the done record so it is discoverable. This does NOT stop the build; it
+makes the choice visible so the reviewer + the human can ratify or reverse it.
+The bar is "would another task / a user / a reviewer be surprised this was
+decided here?" — if yes, record it. A real ambiguity or stale premise, STOP.
+
+COHERENCE CHECK (before you introduce a new concept). Consistency and coherence
+with the system's existing LANGUAGE is a first-class quality. Before you add a new
+flag / config key / status / verb / named concept, check it against the project's
+`CONTEXT.md` glossary + the ADRs + the existing code: (1) does the name already
+MEAN something — are you silently re-meaning it or making it mean two things? (2)
+is the concept at the RIGHT LAYER (e.g. a policy gate on the autonomous-selection
+step vs the explicit verb a human typed)? (3) does it DUPLICATE/overlap an existing
+concept you should reuse or rename instead of forking? If a new concept conflicts
+with, re-means, or duplicates an existing one — or sits at the wrong layer — that is
+NOT a "small factual gap": STOP if it is load-bearing/hard-to-reverse, else RECORD
+it durably per the rule above (JSDoc at the choice site, a `## Decisions` entry
+in the done record, or an observation note — linked from the done record), noting
+what concept, what it overlaps, why your placement. This is
+the prevention half of the review's conceptual-coherence lens — a muddled concept
+that compiles is far more expensive than the question, because every later artifact
+that reuses the muddled term inherits the debt.
+
+Do NOT perform any git operations on THIS repo — do not stage, commit, push, or
+move any files between work/ folders, and do not touch the item's lock ref or its
+body at work/tasks/ready/<slug>.md. The runner (or human) owns every git-state
+transition (the durable main-moves AND the per-item lock acquire/release/amend).
+(Your TESTS may freely create and operate on their OWN throwaway git repos — that
+is expected.)
+
+Leave a CLEAN working tree — only the changes this task intends. The runner
+commits everything untracked (`git add -A`), so any scratch, debug, or
+runtime-artifact file you or your tools created would otherwise be swept into the
+commit. Before you stop, delete such stray untracked files, or add them to
+.gitignore if they legitimately belong ignored. This is NOT git work: deleting an
+untracked file or editing .gitignore is producing clean WORK, like writing source
+— the "no git" rule above (no stage/commit/push/move) still holds.
+
+When the acceptance criteria are met and the repo's build/test/format checks are
+green, STOP and report what you did. The runner handles the durable `git mv` of the
+body tasks/ready/ -> work/tasks/done/, the completion commit, the lock release, and
+integration.
+```
+
+The "no git" line is **in-band** in the prompt (not delegated to a host config like a global `AGENTS.md`): a portable runner cannot assume the target machine has any such rule, so the boundary travels with the prompt. This keeps the acceptance-test gate authoritative (the agent can't commit/merge around it) and the runner the single owner of git state.
+
+## Completed-task commit message
+
+The commit that completes a task (the work + the `git mv` to `work/tasks/done/`) uses a consistent, greppable format so the lifecycle is visible in `git log` and an autonomous runner can author it deterministically:
+
+```
+<type>(<slug>): <task title or short summary>; done
+```
+
+- `<type>` follows conventional-commits (`feat`, `fix`, `docs`, `chore`, …); use `feat` for a task that adds behaviour.
+- `<slug>` is the task slug (its `work/tasks/done/<slug>.md` basename).
+- the trailing **`; done`** marks the durable `tasks/ready→tasks/done` transition landing in this commit (the claim itself has no `main` commit to mirror — it is a lock-ref acquire, not a folder move).
+
+Example: `feat(scan): cross-repo eligible-work queue (read-only); done`
+
+Keep it ONE commit (work + the `git mv`) so a task's completion is a single, atomic, revertable unit — just as the claim is a single commit.
+
+## Why this prevents (not merely detects) double-claims
+
+The rejected push is the rejection of the claim. Because the arbiter serializes ref updates, only one create-only push to `refs/dorfl/lock/<type>-<slug>` can win; all others are rejected atomically by `git receive-pack`'s ref lock. No lock server, no integrator process. `--force-with-lease` is a CAS against the expected old value (safe); `--force` would clobber and MUST NOT be used.
+
+## Isolation for parallel agents
+
+Run each agent's work in its **own clone or worktree** so on-disk code changes can't collide; conflicts then only surface at integration time (normal PR-style resolution), never as corrupted shared state. Clones-of-an-arbiter give fully independent object stores (best isolation); worktrees share one object store (save disk) — either is fine, but prefer separate clones when many agents run at once.

package/dist/protocol/REVIEW-PROTOCOL.md

@@ -0,0 +1,119 @@
+# REVIEW-PROTOCOL
+
+The **review discipline** the autonomous runner invokes by name on a `work/`-protocol artifact before that artifact is _trusted_ — a task before it lands/is claimed, code in a work PR against the task that specified it, a spec before tasking, a set of tasks before they land, or a captured note. The runner spawns a fresh-context agent and tells it to "run the review protocol"; that agent reads THIS doc and applies its standard.
+
+The protocol describes how work is AUTHORED (`WORK-CONTRACT.md`, the templates), CLAIMED and BUILT (`CLAIM-PROTOCOL.md`, the Gate-1 `verify` floor), and JUDGED BEFORE LANDING (this doc). It is in-band in every set-up repo, never host-specific. (The human-facing pointer is `skills/review/SKILL.md`; the standard lives here.)
+
+> This doc is **protocol-native**: it assumes the repo uses the `work/` contract and reviews the artifact AGAINST that contract. Every bare "WORK-CONTRACT" / "ADR-FORMAT" mention below refers to `work/protocol/<doc>` in the repo under review.
+
+You **emit a verdict; you do not act on it** — see [Your output](#your-output). Routing the verdict (to `needsAnswers`, needs-attention, a batch file, a merge) is the caller's job. This discipline is the _assessment_, not the disposition.
+
+## When to use vs. not
+
+- **Use** to review: a **task** (well-cut? claim-ready?); **code** in a work PR (does it deliver the task it claims?); a **spec** (taskable? gate axes honest?); a **note** (right bucket? actionable?); or a **set of tasks** — the whole-SET lens: **graph coherence / gaps / overlap / goal-composition** (does the dependency graph cohere, are there set-level gaps or overlapping/duplicated tasks, and do they compose into the spec/ADR goal?). The set-level checks live in lens 3 (cross-artifact composition) and lens 5 (the destination check).
+- **Don't** use it to _produce_ the artifact (that's `to-spec` / `to-task` / the build agent), nor to _route_ the verdict (that's the caller — a review gate, a conductor skill, or a human). This protocol only assesses.
+
+## The core disciplines (what makes a review thorough, not shallow)
+
+These are _why_ this beats a single "looks fine" pass — apply them throughout:
+
+1. **Run a SEQUENCE of distinct angles, not one pass.** Each lens below is a different framing. Re-running the _same_ angle converges on nothing fast; changing the angle keeps finding distinct _classes_ of defect. Stop when a full pass across the angles finds nothing NEW.
+2. **A reviewer is ADVERSARIAL.** Try to _break_ the artifact ("attack these tasks: granularity? dependency order? gate correctness? drift? a missed seam?"), don't confirm it. Self-review in the producing context rubber- stamps; review as if someone else wrote it (ideally a fresh/cold read).
+3. **Verify against what ACTUALLY LANDED, not intent or memory.** Read the real code / the committed artifact — not what you _think_ a change did. Edits silently fail; specs drift. Trust the bytes on disk.
+4. **A SECOND instance of the same finding is a SIGNAL, not noise.** "I've seen this shape before" → generalise the fix, don't patch instances one by one (this applies to the artifact's defects _and_ to your own repeated mistakes).
+5. **Defects concentrate in the TASK/SPEC more than in the code.** Agents build what they're told, correctly; the expensive bugs are an ambiguous premise, a wrong "reuse X", an assumed-but-absent seam, a stale central assumption. Spend the most scrutiny on the spec.
+6. **Flag, don't guess.** When something is genuinely unresolved, that is a `block`/`needsAnswers` finding — not a guess dressed as approval. A false "looks fine" ships wrong-but-compiling work; a flagged question costs one human glance.
+7. **Weight findings by REAL impact — do not cargo-cult the lenses.** A finding is only worth raising if acting on it changes an outcome someone would actually hit. A technically-true nit that no reader/builder/runtime will ever be bitten by is NOT a `block` (often not even worth recording). Running a lens as a checklist and reporting conformance misses ("this optional field is empty", "a list could be renumbered") as blocking is the failure mode this rule exists to stop: it buries the findings that matter under bookkeeping noise. Ask of each finding: _who hits this, and what breaks?_ No answer → drop it. The lenses find candidates; impact decides severity.
+
+## The lenses — apply IN ORDER, ending in the destination check
+
+For each lens: _what it catches_ + _how to apply it (against the contract)_.
+
+### 1. Claim-vs-reality
+
+Every concrete claim the artifact makes, checked against the real world.
+
+- Task/spec: each referenced symbol, path, function signature, "reuse X" — does it exist and have the assumed shape? (Catches ghost paths, wrong module homes, "reuse X" where X is private / wrongly-shaped.)
+- Code: does the diff actually do what its task/commit claims?
+- Any doc: does it match what landed in `tasks/done/` and the relevant ADRs/findings?
+- **Drift is a `needs-attention` / `needsAnswers` signal**, never something to paper over (WORK-CONTRACT.md). A task built on a stale premise is a `block`.
+
+### 2. Cleanup-vs-behaviour
+
+Anything framed as removal / dead-code / no-op, checked for **hidden live behaviour** (e.g. a flag claimed "just cleanup" that is actually still read somewhere). If a "cleanup" changes behaviour, that's a defect or an unowned scope.
+
+This lens also owns **acceptance-criteria conformance** for code:
+
+- Does the code meet every acceptance criterion of its task?
+- **Shared-write isolation rule (WORK-CONTRACT.md):** if the code writes to a shared/global location (a real home/config dir, a system path, a shared service, an external tool's store), do its tests ISOLATE that location (temp/scratch via the named env/config lever) AND assert the real one is UNTOUCHED? A missing isolation test is a `block` — it silently pollutes and can crash unrelated tools.
+
+### 3. Cross-artifact composition (contract conformance)
+
+Do the artifacts COMPOSE, and do they obey the contract?
+
+- **Composition:** handoffs (one task ships a stub another fills), shared helpers with no owner, two tasks editing the SAME file/command in parallel (a merge conflict waiting to happen — should carry a `blockedBy` to serialise), one task deleting another's live tooling, cross-task side-effects.
+- **Contract conformance (assume these rules; flag violations):**
+  - **status = folder**, never a frontmatter field; **one file per item**; **no shared index/manifest**.
+  - **content-derived slug**, never a counter; **camelCase** field names (`humanOnly`, `needsAnswers`, `blockedBy`, `taskedAfter`).
+  - **gate axes set HONESTLY** — `humanOnly` (a human must drive this) and `needsAnswers` (open questions, listed in the body) reflect the artifact's real nature; a task's gate is decided from _building that task_, NOT inherited from its spec; a falsely-complete `needsAnswers:false` is a defect.
+  - **`blockedBy` / `prd` / `covers`** present and correct (`prd` required iff `covers` is set); deps reference real slugs.
+  - **bucket polarity** for notes: _observation_ = spotted/unverified (append-only); _finding_ = verified EXTERNAL/domain ground truth; _ADR_ = a decision WE made + why (in `docs/adr/`). A note in the wrong bucket is a finding.
+  - **a task's `## Prompt`** is self-contained (an agent could start from the file alone) and includes the drift-check.
+
+### 4. Conceptual coherence (does it fit the system's LANGUAGE?)
+
+The artifact may be internally correct yet INCOHERENT against the concepts the system already has. This lens catches the conflation that mechanical conformance (lens 3) and claim-checking (lens 1) miss — a single concept applied at the WRONG LAYER (e.g. a policy gate placed on an explicit verb when it should gate only the autonomous selection step), an inconsistency that can otherwise survive across multiple tasks and specs.
+
+For each concept / flag / config key / verb / status the artifact introduces or touches, ask three questions:
+
+- **(a) Consistent meaning?** Is the term used the SAME way it is already defined elsewhere (the project's `CONTEXT.md` glossary is the source of truth, plus the ADRs, other tasks, the code)? A term that silently RE-MEANS an existing word — or means two different things in two places — is incoherent.
+- **(b) Right layer?** Is the concept placed at the conceptual layer it actually belongs to? (A policy gate on the autonomous-SELECTION step vs on the explicit VERB; a knob on the loop vs on the one-shot; a check on "who invoked" when the system cannot even distinguish the invokers.) A correct mechanism at the wrong layer is incoherent.
+- **(c) Duplicate / overlap?** Does it FORK an existing concept under a new name instead of reusing or renaming the one that already exists? (Two flags meaning "isolate"; a new status that is really an existing one; a second lock primitive.) If it overlaps, the artifact should reuse/rename, not add.
+
+A concept that is coherent in ISOLATION but incoherent against the system's existing language is a `block` (or, for a task/spec not yet built, a `needsAnswers` / re-scope). Coherence is a first-class quality, not a nicety: an incoherent concept is debt that compounds silently across every artifact that later reuses the muddled term. When you spot the muddle, also check whether the GLOSSARY (`CONTEXT.md`) needs the term pinned so the next author cannot re-fork it.
+
+### 5. The destination check (the final, highest-value move)
+
+_"If every task is built / the code is merged exactly as written, do we END UP WITH the system the spec/ADR describes?"_ — distinct from per-piece correctness, and the strongest signal a decomposition is trustworthy (especially with no human).
+
+- Take the spec/ADR end-state as the target; **map every promised element to a delivering task** — a hole = an element no task delivers.
+- Confirm **coverage is complete + non-duplicated** — every user story covered exactly once.
+- Audit the **deletion sweep** — a new system means the OLD surface is GONE; every removal owned by exactly one task, none unowned or double-owned.
+- Check for **orphans** (a task delivering something the end-state doesn't need) and that assumed-pre-existing foundations actually exist.
+- Confirm **deliberate non-deliveries are flagged** as named follow-ups, not silently missing.
+
+**`approve` must mean "provably reaches the spec/ADR goal," not "each piece looks fine."** If this lens finds a hole, it is the most important thing to `block`.
+
+## Your output
+
+Emit a verdict per reviewed item — and **write nothing** (no frontmatter edits, no `git mv`, no file changes). The caller routes it.
+
+The verdict is a single JSON object with this shape (the **emitted-shape contract**). The runtime PARSER is the source of truth for the shape; this prose mirrors what it enforces:
+
+- `verdict` — REQUIRED, exactly `"approve"` or `"block"`. `approve` lets the artifact proceed; `block` keeps it out (the caller routes to needs-attention / `needsAnswers` / a comment).
+- `findings` — REQUIRED, an array (possibly empty). Each finding is:
+  - `severity` — `"blocking"` (keeps the item out of "ready") or `"non-blocking"` (a nit / future improvement). Be honest about which.
+  - `question` — the question / defect, with enough context to act WITHOUT re-deriving it.
+  - `context` — OPTIONAL, the relevant excerpt, `file:line`, or reasoning.
+
+Several caller-specific optional channels MAY ride on the same JSON object. They are OPT-IN: each caller's prompt names which ones to fill. The shape they take when present:
+
+- `review` — a single deliberately-authored, human-readable REVIEW string the caller posts as a comment on the PR (leads with Approved/Blocked, then the lenses + the destination-check reasoning). Plain text inside the JSON string. Advisory only — never gates the verdict.
+- `edits` — full-content edits to apply between passes in an improver loop: an array of `{path, content}`, where `path` is a repo-relative target (typically `work/tasks/backlog/<slug>.md`) and `content` is the FULL replacement file body. The runner writes them; the agent does no disk/git.
+- `edit` — for the lone-task review only: a single in-memory full-replacement task BODY (the markdown AFTER the frontmatter), applied before the next round. No path — the task has not been emitted yet.
+- `questions` — an array of strings carrying open questions for a human to answer (the non-converge sink in the lone-task review).
+- `uncertainTasks` — for the tasker improver loop: specific tasks to emit `needsAnswers: true` with the questions in their bodies. Each is `{path, questions: string[]}`.
+- `decompositionUnclear` — for the tasker improver loop: when the WHOLE decomposition is unsound, `{questions: string[]}` to record as the spec's needs-attention reason.
+
+Any unrecognised field is ignored by the parser; the caller routes on `verdict`/`findings` plus the channels its prompt asked for.
+
+**Keep the JSON parseable** (a malformed verdict strands the work). Emit defensively: emit it MINIFIED on ONE single line; do NOT use a literal double-quote `"` inside any string value (paraphrase, or use single quotes — a dropped escape on an inner `"` is the most common corruption); keep every string field SHORT and SINGLE-LINE (write `\n` literally, never embed a real newline / tab / control char); and cap the longest field (`review`) at roughly 1500 characters — say less, not more.
+
+### How callers route your verdict (not your job — for orientation only)
+
+- a **review GATE** routes a `block` → set `needsAnswers: true` on the artifact (question in its body) or mark its per-item lock `state: stuck` (needs-attention); `approve` → let it land / auto-merge.
+- a **conductor** (e.g. `drive-tasks`/`orchestrate`) routes a `block` → into its stuck-set / batched questions for the human; `approve` → merge / advance.
+
+## Scope fence
+
+This doc is the review _protocol/discipline_ only. The review **gates** — _when_ review runs (task-time / PR-time), per-repo toggles, the model override, the `--propose` PR arbiter, auto-merge-on-approve, the role/seam wiring, the trust resolver — are NOT here; they live in the runner machinery. This protocol assumes nothing about its caller beyond "you will route my verdict."

package/dist/protocol/SURFACE-PROTOCOL.md

@@ -0,0 +1,121 @@
+# SURFACE-PROTOCOL
+
+The **surface-questions discipline** the autonomous runner invokes by name on ONE `work/` item before that item can advance a lifecycle rung. The runner spawns a fresh-context agent and tells it to "run the surface protocol"; that agent reads THIS doc and applies its standard.
+
+The protocol describes how work is AUTHORED (`WORK-CONTRACT.md`, the templates), CLAIMED and BUILT (`CLAIM-PROTOCOL.md`, the `verify` floor), JUDGED BEFORE LANDING (`REVIEW-PROTOCOL.md`) and — when judgement is genuinely open — has its OPEN QUESTIONS SURFACED for a human to answer (this doc). It is in-band in every set-up repo, never host-specific. (The human-facing pointer is `skills/surface-questions/SKILL.md`; the standard lives here.)
+
+> This doc is **protocol-native**: it assumes the repo uses the `work/` contract and surfaces the open-judgement residue of an item AGAINST that contract. Every bare "WORK-CONTRACT" / "REVIEW-PROTOCOL" mention below refers to `work/protocol/<doc>` in the repo under work.
+
+It is **doc-shaped, exactly like `review`**: you produce an assessment (here, a set of questions) and the **caller routes/persists it**. You never set `needsAnswers`, never write a sidecar, never `git mv`, never commit. The advance engine's surface-question rung spawns you fresh-context, takes your questions, and **ITSELF writes the sidecar (CAS-atomic)** — exactly as the review gate uses `review`. **The skill judges; the engine persists.**
+
+## The two laws (state them; they keep the tool honest)
+
+1. **GATHER-only.** Your job is to FORMULATE the open questions for the item — by composing the existing reviewing/triage judgement, not by re-deriving it. You add no new disposition of the item.
+2. **PERSIST-NEVER.** You EMIT questions and **write nothing** (no `needsAnswers` edit, no sidecar, no `git mv`, no commit) — mirroring `review`. The caller (the advance engine, or a human) routes and persists. If you are tempted to write a file, STOP: that is the engine's job (or, by hand, the `advance` verb — see [the no-runner path](#the-no-runner-path)).
+
+**The humility rule (the heart of it):** you **surface the residue, you NEVER invent an answer.** A `default:` is a _suggested_ default offered for the human's convenience — it is a humility aid, not a decision, and it never substitutes for the human answering. Automating answer creation is rejected by design; the human is the clock. When judgement is genuinely open, that is a QUESTION — never a guess dressed as a resolution.
+
+## When to use vs. not
+
+- **Use** to formulate the open questions for ONE item before it can advance a lifecycle rung — a task or spec that may carry open judgement, an untriaged observation, code in a work PR — whether you are the advance engine's surface rung or a human doing it by hand with no runner.
+- **Don't** use it to PRODUCE an item (that is `to-spec` / `to-task` / the build agent), to APPLY a human's answer or advance the item (that is the engine's apply rung / the `advance` verb), or to PERSIST the questions (the engine, or the `advance` verb, owns the write). And do not use it to invent answers — there is no answer-creation here, by design.
+
+## What you COMPOSE (single sources — do NOT duplicate)
+
+You are a GATHERER. You stand up the existing producers/reviewers and collect what they emit; you do not reimplement their judgement. `to-task` and `review` stay the single sources, **composed and UNCHANGED**.
+
+1. **`review` (`work/protocol/REVIEW-PROTOCOL.md`) — for a task / spec / code.** Run the `review` discipline; it EMITS a verdict `{verdict, findings:[{severity, question, context}]}` and writes nothing. ROUTE its **`block`** findings into your emitted questions (a blocking finding is an open question that must be answered before the item advances). A non-blocking finding is a nit — record it as an optional/low-priority question, never as a blocker. Do NOT re-derive review's lenses here; you call review and carry its findings over.
+2. **The native observation-triage question — for an observation.** An observation has no gate for `review` to assess; its question is **"what becomes of this signal?"** Emit a single plain question asking the human, in their own words, what should happen to it (see [the emitted question shape](#the-emitted-question-shape-must-match-the-sidecar)). This judgement is NATIVE to this skill — investigate the observation's claim against current reality (code / tasks / specs / ADRs) so the inline context and the suggested default are honest, exactly as the triage discipline demands.
+3. **The item's PRE-EXISTING open questions.** Collect what the item already carries: a `needsAnswers: true` item's `## Open questions` block, and any open question already written in the body. Carry each over verbatim as an emitted question (with its context). These are open judgement the author already named — they must surface, not be silently dropped.
+
+For each gathered question, attach **inline CONTEXT** (the relevant excerpt / `file:line` / the reasoning — so the human need not open the source item) and, where you can honestly suggest one, an **optional suggested DEFAULT** (the humility aid — never a decision).
+
+## The emitted question shape (MUST match the sidecar)
+
+The questions you emit MUST match the **sidecar entry fields**, so the engine persists them with **zero translation**. The runtime PARSER (`parseSurfaceEmit`) is the source of truth for the shape; this prose mirrors what it enforces.
+
+Emit a single JSON object of this exact shape (no prose OUTSIDE it):
+
+```json
+{
+	"item": "<type>:<slug>",
+	"questions": [
+		{
+			"question": "…",
+			"context": "…",
+			"default": "… (optional; omit if none)"
+		}
+	],
+	"note": "… (optional free prose; your reasoning / findings live HERE)"
+}
+```
+
+- **`item`** — OPTIONAL, the namespaced identity the surface is for (orientation only; the resolver owns identity — the parser tolerates absence).
+- **`questions`** — REQUIRED, an ORDERED array. An EMPTY array is VALID — the honest "no open judgement" result; absence is NOT (the parser rejects it, never a silent surface). Each entry is:
+  - **`question`** — REQUIRED, the question verbatim. An all-whitespace question is dropped as a placeholder.
+  - **`context`** — OPTIONAL, inline context so the human need not open the item (the relevant excerpt / `file:line` / reasoning).
+  - **`default`** — OPTIONAL, the suggested default — the humility aid; omit when you cannot honestly suggest one (never fabricate a default just to fill the field).
+- **`note`** — OPTIONAL free-prose channel for your reasoning / findings (the surface counterpart of the verdict's `review` field). It is the HOME for any explanation you want to give: put it HERE, INSIDE the object, never as prose around the JSON. The engine does not persist `note` (the parser ignores it); its only purpose is to give your prose somewhere to go so the emitted object can be your final, clean, single-object output. Like `review`, keep it short and single-line (write `\n` literally, never a raw newline).
+
+There is NO `disposition` field, and no token vocabulary to learn or pick: a sidecar entry is BINARY (no-answer | answered), and the human answers in PLAIN LANGUAGE. What to DO with the answer — mint a task, a SPEC, or an ADR; delete the source; or ask a follow-up — is the agentic apply decision (read off the human's answer + the source item), not a token the surface emits. An observation's triage question is therefore just an ordinary plain question ("what becomes of this signal?"); the human writes back in their own words, and if the answer is "throw it away", the discharge is the direct-delete path (the human, the `answer-questions` skill, or the `dorfl` delete verb removes the source + sidecar in one revertible commit), not a `delete` token.
+
+You do NOT assign ids, `answered:`, `answer:`, or `allAnswered`. Those are the SIDECAR's machine-owned fields — the engine assigns the stable monotonic id (`q1`, `q2`, …), the human fills `answer:`, and the serialiser derives `answered:`/`allAnswered`. You emit only the three authoring fields above; the engine owns the rest. (This is precisely why you must not write the sidecar: you do not own its machine fields.)
+
+Because the shape is the sidecar's, the engine APPENDS your questions to any existing sidecar (never overwriting an already-answered entry) and writes the whole thing in one CAS-atomic commit. You need not know any of that — you just emit the four fields.
+
+If the item carries **no open judgement** (review approves with no blocking findings, the observation has an obvious conservative outcome the repo's auto-triage bar covers, nothing pre-existing) — emit the object with an **empty `questions` array** (put WHY in `note`). Surfacing nothing is a valid, honest result; do not manufacture a question to look busy. Do NOT replace the empty-array object with a prose explanation: the JSON object is always your output, even when it carries no questions.
+
+**The emitted object is your FINAL and ONLY output.** Do not narrate your process, and add no remark, summary, or sign-off before or after it — and take no further turn once you have emitted it (emitting it is how you finish). The caller reads only your LAST turn, so a trailing chatty turn AFTER the object discards the emit and strands the run. This is the same discipline Gate-2's verdict carries; the `note` field exists precisely so all your prose has a home inside the object.
+
+### How the caller persists your questions (NOT your job — for orientation only)
+
+- **The advance engine's surface-question rung** spawns you fresh-context, takes your emitted questions, and writes them to the sidecar `work/questions/<type>-<slug>.md` CAS-atomically (assigning ids, appending, setting `needsAnswers: true`). The skill judges; the engine persists.
+- **A human (no runner)** persists via the `advance` verb (see below), or hand-writes the documented sidecar format.
+
+## The no-runner path
+
+You stay **human-invokable**. A human with no runner can invoke this discipline by hand, take the emitted questions, and persist them one of two ways:
+
+- **Persist via the `advance` verb** — the apply/surface rung of the `advance` command (a **sibling top-level verb**, like `do` and `run`). It is `advance`, **NOT `do advance`** — `advance` is its own verb.
+- **Hand-write the documented sidecar format** — write `work/questions/<type>-<slug>.md` by hand per the human-readable Markdown shape below. Because the emitted shape already matches the sidecar entry, this is a transcription, not a translation.
+
+The hand-written sidecar shape (the SAME file is both human-readable on GitHub and machine-parseable — the machine fields hide in HTML comments that GitHub renders as nothing, the human content is real Markdown):
+
+```
+<!-- dorfl-sidecar: item=<type>:<slug> type=<type> slug=<slug> allAnswered=false -->
+
+## Q1
+
+**<the question, verbatim>**
+
+> <inline context so the human need not open the item>
+
+_Suggested default: <optional default; omit the whole line if none>_
+
+<!-- q1 fields: id=q1 -->
+
+**Your answer** (write below this line):
+
+## Q2
+
+**<next question…>**
+
+…
+```
+
+Notes for the hand-writer:
+
+- The **identity HTML comment** at the top carries `item`/`type`/`slug` and the derived `allAnswered` mirror. Set `allAnswered=false` on first write (no answers yet); the engine recomputes it on every subsequent serialise.
+- Each entry opens with a `## Qn` heading (`Q1`, `Q2`, …, monotonic — never reused). The heading is BOTH the entry separator and the answer-region boundary.
+- The **question is a bold line**, the **context is a Markdown blockquote** (each line prefixed `> `), the **default is one italic line** prefixed `_Suggested default: ` and closed with `_`. Omit context/default lines entirely when absent.
+- The **per-entry HTML comment** carries `id=qN`. There is no `disposition=` field (the token vocabulary is retired — an entry is binary). Do NOT add an `answered=` field either — the engine derives answered-ness from the answer text and only emits the override when it disagrees with that derivation.
+- The fixed marker `**Your answer** (write below this line):` is followed by an empty region; the answer is everything from the marker up to the next `## ` heading (heading-delimited so a `---` inside an answer cannot break parsing).
+- The human just types prose under the answer marker — no `key:`, no escaping, no fence.
+
+**No separate write-skill is added.** Hand-writing the sidecar (or the `advance` verb) is enough. Do not invent one here.
+
+## Boundaries (the scope fence)
+
+- **`to-task` / `review` stay COMPOSED and UNCHANGED.** You call them; you never modify or reimplement them. They are the single sources for tasking/reviewing judgement.
+- **You formulate the questions for ONE item; you do not batch, apply, or iterate.** Batching, applying answers, and iterating are the ENGINE's job (or `orchestrate`'s, for the human batch) — NOT yours.
+- **You write nothing and you invent no answer.** Both laws, restated because they are the whole point: GATHER-only, PERSIST-NEVER; surface the residue, NEVER invent an answer.

package/dist/protocol/TASKING-PROTOCOL.md

@@ -0,0 +1,122 @@
+# TASKING-PROTOCOL
+
+The **tasking discipline** the autonomous runner invokes by name on a spec in `work/prds/ready/` to decompose it into independently-grabbable, file-based work tasks (tracer-bullet vertical tasks). The runner spawns a fresh-context agent and tells it to "run the tasking protocol"; that agent reads THIS doc and applies its standard.
+
+This is one of the runner-invoked protocol disciplines (alongside `CLAIM-PROTOCOL.md`, `REVIEW-PROTOCOL.md`, and `SURFACE-PROTOCOL.md`): the protocol describes how work is AUTHORED (`WORK-CONTRACT.md`, the templates), CLAIMED and BUILT (`CLAIM-PROTOCOL.md`, the `verify` floor), JUDGED BEFORE LANDING (`REVIEW-PROTOCOL.md`), has its OPEN QUESTIONS SURFACED (`SURFACE-PROTOCOL.md`), and — between spec and buildable task — TASKED (this doc). It is in-band in every set-up repo, never host-specific. (The human-facing pointer is `skills/to-task/SKILL.md`; the standard lives here.)
+
+> This doc is **protocol-native**: it assumes the repo uses the `work/` contract. Every bare "WORK-CONTRACT" / "CLAIM-PROTOCOL" mention below refers to `work/protocol/<doc>` in the repo under work.
+
+You **emit task files; you do not act on them** — see [Git protocol](#git-protocol). Committing them, moving the spec, claiming any of them is the caller's job (the runner, on the agent path; a human, on the no-runner path). This discipline is the _decomposition_, not the disposition.
+
+## When to use vs. not
+
+- **Use** when tasking a `work/prds/ready/<slug>.md`, a design doc, or a plan into grabbable units for solo-with-agents (incl. parallel) work.
+- **Don't** use to _write_ the spec (that's a separate step — `to-spec`) or to _claim/run_ a task (that's the runner: `dorfl claim`/`do`/`complete`, or the `drive-tasks` conductor). Don't introduce a shared index file or a status field — status is the folder (see `WORK-CONTRACT.md`).
+
+## Process
+
+### 1. Locate / confirm the source
+
+Work from a `work/prds/ready/<slug>.md`, a design doc, or the conversation context. If the source is a path, read it fully. The `work/` folder lives **inside the target project repo** (versioned with its code).
+
+### 2. Explore the codebase (if not already)
+
+Task titles and descriptions use the project's domain glossary. Respect ADRs / findings in the area you're touching.
+
+**Check the spec against reality first (drift = a needs-attention signal).** A spec is a launch snapshot and may have DRIFTED from what has since landed (`tasks/done/`, ADRs, sibling tasks). Before tasking, verify its assumptions still hold. If it has drifted such that tasking it as-is would emit tasks built on a false premise, do NOT task it: set `needsAnswers: true` on the spec with the discrepancy in its body (or fix a small certain factual error first). See WORK-CONTRACT.md "Drift is a needs-attention signal". Never emit tasks from a stale spec.
+
+### 3. Draft vertical tasks
+
+Each task is a **tracer bullet** — a thin vertical path through ALL layers end-to-end, not a horizontal cross-section of one layer.
+
+- Each task delivers a narrow but COMPLETE path (schema → logic → API/UI → tests).
+- A completed task is demoable/verifiable on its own.
+- Prefer many thin tasks over few thick ones.
+- Set the **two gate axes** ONLY where they apply (both default to OMITTED on most tasks): **`humanOnly: true`** = NEVER-for-agents BY NATURE (the NARROW DECIDED axis — secrets/release/security; survives even in the pool `work/tasks/ready/`); **`needsAnswers: true`** = unresolved questions block autonomous work (the DISCOVERED axis — list the questions in the task body). Omitted on either means "undeclared"; whether an agent may then auto-build is the _repo's_ `autoBuild` policy. Mark `blockedBy` for ordering. See `WORK-CONTRACT.md` for the two-axis semantics, the predicate, and the `autoBuild` precedence.
+  - **A task's `humanOnly` is decided from the nature of BUILDING THAT TASK — never inherited from the spec.** Evaluate each task on its own merits (does _building it_ genuinely need to be done by a human BY NATURE — secrets handling, release pipeline, hard security boundary, an AGENTS.md prohibition?), AS IF the spec's `humanOnly` field did not exist. (The two flags are disjoint — see §3b.)
+  - **Do NOT stamp `humanOnly` to mean "a human should REVIEW this before the agent builds it"** — that is the POSITION's job, not the flag's. The runner BIRTHS tasks STAGED in `work/tasks/backlog/` (not eligible); a human promotes the approved ones into the pool `work/tasks/ready/`. Review-first is encoded by the staging position; `humanOnly` is reserved for the rare never-by-nature case. (See WORK-CONTRACT.md "Task `humanOnly` is NARROW".)
+  - **Do NOT be shy about `needsAnswers` — when genuinely unsure, FLAG, don't guess.** `needsAnswers` is cheap (a human clears it in seconds) and a confidently-underspecified task is expensive (an agent builds the wrong thing, convincingly). Defects concentrate in TASKING far more than in implementation: an ambiguous premise, an unresolved design fork, a "reuse X" where X's shape is unverified, or a seam you _assume_ exists — each is a `needsAnswers` with the open question written in the body, NOT a guess dressed as a spec. The asymmetry is the whole point: a false `needsAnswers` costs one human glance; a false confidence ships wrong-but-compiling work.
+- **Prefer file-orthogonal tasks to minimise merge conflicts.** `blockedBy` encodes logical ordering, but two independent tasks that edit the SAME files will conflict when the second integrates after the first. Parallel agents make this real. So: split along file/module boundaries where you can; and when two tasks are known to touch the same module, add a `blockedBy` to **serialize** them even if there's no strict logical dependency. The runner only rebases-or-surfaces conflicts (it never auto-resolves), so avoiding them at tasking time is the cheap win.
+
+### 3a. Wide refactors are the EXCEPTION to vertical slicing (expand → migrate → contract)
+
+Most work slices vertically (§3). A **wide refactor** does not, and forcing it to is the failure mode this subsection exists to stop. A wide refactor is one mechanical change — rename a shared symbol or a column, retype a pervasive identifier, cut a vocabulary over — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and **no vertical tracer-bullet task can land green on its own**. Sequence it as **expand → migrate → contract** instead:
+
+- **Expand** (one task): add the NEW form BESIDE the old so nothing breaks yet. Nothing is removed; the gate stays green because every existing caller still resolves.
+- **Migrate** (one task PER batch, each `blockedBy` the expand task): move call sites onto the new form in batches sized by blast radius — per package, per directory, per module. Each batch is its own task and stays green because the old form still exists. Split batches file-orthogonally (§3's merge-conflict rule) so parallel agents don't collide.
+- **Contract** (one task, `blockedBy` EVERY migrate batch): delete the old form once no caller remains. It cannot start until every migrate batch is done — that is what its `blockedBy` fan-in encodes.
+
+**When even the batches cannot stay green alone** (the change is so entangled that an individual batch can't pass the gate in isolation), keep the same expand → migrate → contract shape but let the batches share a common **integration point**: task each batch onto the work-branch discipline the runner already uses, and add a final **integrate-and-verify** task `blockedBy` all of them where green is promised — green is guaranteed only at that fan-in, not batch-by-batch. Prefer the plain green-batch-by-batch form; reach for the shared-integration form only when a batch genuinely cannot be made to pass alone.
+
+The test for "is this a wide refactor?" is whether a single mechanical edit breaks the gate across many call sites at once such that no thin vertical path can be green. If yes, use this sequence; if a normal vertical slice CAN be green, it is not a wide refactor — slice it vertically (§3).
+
+### 3b. Spec gate vs task gate are DISJOINT + honour cross-prd `taskedAfter`
+
+- **`humanOnly` on a spec and `humanOnly` on a task are DISJOINT — they gate different verbs and DO NOT flow into each other.**
+  - **Spec `humanOnly`** gates _tasking_: its ONLY effect is that an agent may not **auto-task** that spec (even where the repo's `autoTask` policy is on); a human must drive the decomposition. That is its entire meaning.
+  - **Task `humanOnly`** gates _building_: it is decided per task from the nature of building that task (see §3), independently.
+  - There is **NO inheritance, NO propagation, and NOT EVEN A HINT** from the spec flag to the task flags. A `humanOnly: true` spec can produce entirely agent-buildable tasks; an un-flagged spec can produce some `humanOnly` tasks. When setting a task's gate, ignore the spec's `humanOnly` entirely.
+  - Likewise **`needsAnswers`**: on a spec it blocks auto-tasking until the questions are answered; on a task it blocks auto-building. Set a task's `needsAnswers` only when _that task_ has unresolved questions (list them in its body) — not because the spec had open questions (a spec with open questions should be resolved BEFORE tasking, not task-inherited).
+  - (A spec's body may still _describe_ which areas are judgement-heavy — use that as ordinary domain input when reasoning about a task's own build-nature, the same as any other spec prose; it is not a flag-setting shortcut.)
+- **`taskedAfter` (cross-prd order).** If this prd has `taskedAfter: [other-prd]`, those prds must already be TASKED (their tasks exist) before you task this one — so this prd's tasks can reference the real slugs of those prds' tasks in `blockedBy`. (The auto-tasker enforces this; a human may task anyway but must then know the blocker slugs.) If a needed blocker prd is not yet tasked, task it first or record the dependency and stop.
+
+### 4. Quiz the user — OR (no human present) do a confidence check
+
+**If a human is present** (the normal interactive path): present the breakdown as a numbered list — Title, the two gate axes, Blocked-by, and (if the source has them) which user stories it covers. Ask: granularity right? dependencies right? merge/split any? gates correct? Iterate until approved.
+
+**If NO human is present** (an agent auto-tasking in CI): step 4 is replaced by a **confidence check**, because there is no one to quiz. Do NOT emit guessed tasks. The source spec should already be clear (the auto-tasker only runs on a spec that is not `humanOnly` and not `needsAnswers`). If, while tasking, ANY of {granularity, dependency order, a gate, a seam} is genuinely unresolved by the spec/ADR, do not guess: either set `needsAnswers: true` (with the open questions in the body) on the specific uncertain task, or — if the whole decomposition is unclear — stop and route the spec to needs-attention with the questions, rather than emitting a wrongly-cut task. Only emit tasks you would have gotten the human to approve.
+
+### 5. Write the task files
+
+For each approved task, write `work/tasks/backlog/<slug>.md` using `work/protocol/task-template.md`. Create `work/` and `work/tasks/backlog/` lazily if absent. One file per task. Use a content-derived slug, never a counter. Fill `blockedBy` with the slugs of blocking tasks, and set the **required `prd`** field to the slug of the source `work/prds/ready/<slug>.md` (so `covers` story numbers are unambiguous — see `WORK-CONTRACT.md`).
+
+### 6. Trim the spec to its durable framing (one-time)
+
+The spec is a launch snapshot (see the `to-spec` skill). Now that the work is tasked, the spec's **technical detail is redundant** (it lives in the tasks) and is the part that would otherwise go stale. Do a ONE-TIME trim:
+
+- The tasks now own _what to build_ (Implementation/Testing detail) — remove those sections from the spec.
+- Any **durable rationale** worth keeping (the _why_ of a decision) is RELOCATED to an ADR (`docs/adr/<slug>.md`), not deleted.
+- The spec settles to its durable framing: Problem / Solution / User Stories / Out of Scope (+ its launch-snapshot banner). Leave a one-line pointer that detail moved to tasks/ADRs.
+- **Move the spec to `work/prds/tasked/`** to record that it has been tasked: `git mv work/prds/<src>/<slug>.md work/prds/tasked/<slug>.md`, where `<src>` is the spec's CURRENT non-pool resting position — `ready` on the runner/dorfl path, but `proposed` on the human-driven path (a human MAY task a spec straight from `prds/proposed/` without first promoting it to `ready/`; doing so is deliberate — staging keeps it out of the auto-tasking pool so CI cannot race the human, and a forced `proposed → ready` pre-move would re-open exactly that race). The DESTINATION is always `tasked/` regardless of source. Transforming a spec into tasks MUST move it: residence in `work/prds/tasked/` IS tasked-ness (the build-machine `tasks/done/` analogue for specs, the sole signal); a tasked spec left in `proposed/`/`ready/` both lies about its state and stays auto-taskable (CI could re-fan-out). Do NOT add a `tasked:` frontmatter marker; the folder is the source of truth. (On the dorfl path `do prd:<slug>` performs this move itself as part of its runner-owned integration commit; this manual step is for the human-driven, no-lock tasking path.)
+
+This is a hand-off transition, not ongoing maintenance — after this single trim the spec is stable because the stale-prone part was relocated, not because it is kept in sync. (Nothing is lost: detail → tasks; rationale → ADR.)
+
+## Git protocol
+
+Do NOT commit/push — leave the work for the caller to inspect/integrate. The one exception is the spec `prds/<ready|proposed>/ → prds/tasked/` relocation above, which is a `git mv` (so it is staged as a rename); leave every other new/edited file unstaged. Report the exact paths written (and the trimmed + relocated spec).
+
+When the runner spawns you on the agent tasking path, you EDIT files only — write the task files under the STAGING folder, trim the spec — and the RUNNER owns every git-state transition (it commits the produced tasks, releases the tasking lock, and moves the spec into `work/prds/tasked/`). Do not stage, commit, push, or move any files yourself. The runner integrates the tasking transition through the shared band (`--propose` PR / `--merge` main) honouring the caller's flags.
+
+## The emitted task shape (mirrors `work/protocol/task-template.md`)
+
+Each emitted task file is a markdown document with YAML frontmatter, BORN STAGED in `work/tasks/backlog/<slug>.md`. The shape's enforced source of truth is the frontmatter parser code (`parseFrontmatter`) and the templated body in `work/protocol/task-template.md`; this section DESCRIBES it in prose so the spawned agent emits files the parser and the runner read identically.
+
+### Required frontmatter fields
+
+- **`title:`** — a short, human-readable title for the task (one line).
+- **`slug:`** — the URL-safe content-derived slug; matches the filename `<slug>.md`. Never a counter.
+- **`prd:`** — the slug of the source `work/prds/ready/<prd>.md` this task derives from. REQUIRED when `covers:` is non-empty; OMITTED only on a self-contained chore/refactor (with `covers: []`). Disambiguates `covers:` story numbers.
+- **`blockedBy:`** — a YAML inline list of slugs that must reach `work/tasks/done/` first; `[]` means startable now.
+
+### Optional frontmatter axes (omit when undeclared)
+
+- **`humanOnly: true`** — gate axis 1 (DECIDED, NARROW): NEVER-for-agents BY NATURE (secrets / release / security / an `AGENTS.md` prohibition). Survives even in the pool `work/tasks/ready/`. OMIT when the task is agent-buildable — "review this before the agent builds" is the POSITION's job (the task is BIRTHED in `work/tasks/backlog/`), NOT `humanOnly`'s.
+- **`needsAnswers: true`** — gate axis 2 (DISCOVERED): open questions block autonomous work. List the questions under an `## Open questions` heading in the body. OMIT when the task launches fully resolved.
+- **`covers:`** — an inline list of user-story numbers within `prd:` this task covers; `[]` (or omitted) means no specific story coverage.
+- **`issue:`** — the GitHub issue number an `intake`-emitted task was transformed from. Carried only when the task is the direct closer for an issue (mutually exclusive with `prd:` carrying the closure via the spec).
+
+### Body sections
+
+- **`## What to build`** — a concise description of the vertical task — the end-to-end behaviour (a thin path through every layer: schema → logic → API/UI → tests), NOT a layer-by-layer implementation plan. Avoid specific file paths / code snippets (they go stale).
+- **`## Acceptance criteria`** — a bullet list of verifiable / demoable criteria, ending with the test-coverage line and (where applicable) the shared-write isolation rule from `WORK-CONTRACT.md`.
+- **`## Blocked by`** — prose mirror of the frontmatter `blockedBy:`; `None — can start immediately.` when `blockedBy: []`.
+- **`## Prompt`** — self-contained instructions to paste into a fresh agent context: an agent must be able to start from THIS FILE ALONE. State the goal, the relevant domain vocabulary, where to look (by module/concept, not brittle paths), the seams to test at, and what "done" means. Reference any constraining ADRs / findings.
+- **`## Open questions`** — present iff `needsAnswers: true`; lists the unresolved questions blocking autonomous build. Stripped by the apply rung on full resolution.
+
+### Placement rule
+
+The tasker ALWAYS writes emitted task files to `work/tasks/backlog/` (the STAGING folder). The pool `work/tasks/ready/` is the agent-eligible pool the runner owns the promotion into; a write outside the staging folder is dropped by the runner-deterministic placement resolver. The agent never self-places into the pool.
+
+## The on-disk contract
+
+The full `work/` layout, slug rules, and frontmatter are in `work/protocol/WORK-CONTRACT.md`. The claim/lifecycle protocol these files are designed to support (consumed by the runner — `dorfl claim`/`do`/`complete`) is in `work/protocol/CLAIM-PROTOCOL.md` — read it so the files you emit are claim-ready, but this discipline does not itself claim or run tasks.