devlyn-cli 4.1.0 → 4.2.0

package/config/skills/_shared/task-completion.md

@@ -0,0 +1,235 @@
+# Outer-owner task completion
+
+Completion belongs to the outer task owner after source acceptance; it does not
+change product verdicts or worker isolation. Direct work edits the current
+checkout, then delivers each completed, verified request with attributable
+changes. Finish the whole request, including steering received before acceptance;
+internal subtasks, messages and conversation end are not delivery boundaries.
+Honor explicit batching or delivery holds; otherwise deliver completed requests
+without waiting for later requests.
+
+Without a delivery instruction, use project policy below, default `auto`. A bare
+commit request uses `--local-only`, a PR request `--mode pr`, and a merge request
+`--mode auto`. Local-only/no-push restrictions prevent publication; no-commit or
+just-edit instructions skip delivery. Existing session-wide restrictions remain
+in force until changed. Read-only work, unchanged work and incidental generated
+files do not trigger delivery. An ideate drain delivers every task.
+
+## Concurrent writers
+
+When other sessions or agents are known to write this checkout (the user says
+so, or you see them), allocate a worktree below before editing. Changes present
+at the start are the user's work in progress: preserve them, and continue unless
+their ownership or the task's dependence on them is unclear. Re-read a file
+before overwriting it, and check `git status` and the diff at verification and
+commit points. On changes you cannot explain, stop writing to the shared
+checkout and ask whether to continue there or isolate. With no one to ask, move
+only your own edits, and only when the task's context can be rebuilt in the
+worktree; otherwise leave the checkout as it is and report the task blocked.
+Isolation changes the work location, not delivery scope. Allocate for the
+resolved delivery policy and reuse that worktree when suitable. Isolation
+without delivery uses `--local-base`. A local receipt remains local; later
+publication requires a fresh publication allocation, candidate and acceptance.
+
+## Allocate for delivery or isolation
+
+Use the caller's DEVLYN_SHARED_DIR. When this reference is opened
+directly, bind it to this reference's reader-supplied containing
+directory, resolving directory symlinks first. Missing source identity is
+BLOCKED:skill-source-unresolved; a missing task-complete.py is
+BLOCKED:shared-dir-unresolved. Never select another installation.
+
+For direct delivery, run the bound task-complete.py after completing the request's
+edits and checks, before committing the delivery candidate. Allocate before
+editing when concurrency requires isolation; if isolation is unavailable, do
+not write to the shared checkout. Queue drains retain their allocation order.
+
+```sh
+python3 "$DEVLYN_SHARED_DIR/task-complete.py" allocate --repo . \
+  --task '<task identity>' --branch '<absent task branch>' \
+  --worktree '<absent path>' --repository '<owner/repo>' --remote origin --base main
+```
+
+Every delivery allocation owns a linked worktree; `--worktree` is required.
+A publication allocation normally starts at the exact fetched remote base,
+independent of the anchor's branch or dirty state, and leaves the anchor's
+HEAD, index and files untouched. For a commit request, local-only work or
+isolation without publication, use `--local-base` with the exact current HEAD
+and omit `--repository`/`--remote`. Nothing is fetched or pushed; complete with
+`--local-only` only when committing is allowed.
+
+When delivery is implicit and no GitHub origin is configured, use the existing
+local-only route and report `LOCAL_ONLY`, the commit and why no PR/merge occurred.
+An explicit PR/merge request remains blocked. Authentication, network and
+configuration failures are not grounds for this fallback.
+
+After local completion or confirmed PR merge, reconcile the original checkout
+only when its branch and changes remain understood and can be preserved.
+After remote delivery, fetch first. If the branch can fast-forward to the
+delivered result, recheck the copied edits' current ownership and contents,
+then remove them: `git restore --source=HEAD --staged --worktree -- <paths>`
+for tracked paths holding only your edits, and delete copied untracked files.
+Then use `git merge --ff-only <task branch>` for local delivery, or
+`git merge --ff-only <remote>/<base>` on the base branch after remote delivery;
+a drain's `Bring into` command is its own. Once a local delivery is reconciled,
+remove its worktree and task branch (`git worktree remove <worktree>`,
+`git branch -d <task branch>`). Do not switch branches, create a reconciliation
+merge commit or discard WIP to force this step. If reconciliation is unsafe,
+retain and report the edits, delivered result and remaining bring-in action.
+
+Save the returned receipt path under the common Gitdir. `reconciled` reports earlier accepted,
+PR-delivered tasks whose merged resources were cleaned or retained; it is
+informational, so never resume or release a receipt you do not own. Existing
+branches/trees cannot be adopted, even when their names look generated. Nor
+can a receipt that never reached `allocation: owned`: remove its worktree and
+branch if present, delete its receipt directory, then allocate again.
+Unreceipted tasks remain owner-managed.
+
+Copy attributable task edits into the allocated worktree as a patch, never a
+stash. Establish attribution from the pre-edit contents and starting Git state,
+including staged, unstaged and untracked work. A path-scoped
+`git diff --binary HEAD` (after `git add -N` for new files), applied with
+`git -C <worktree> apply --3way`, is suitable only when every included change
+belongs to this task and its prerequisites exist in the candidate baseline. Otherwise construct the task-only
+delta; if attribution or independence from unshipped work is unclear, preserve
+the checkout and report delivery blocked.
+
+Review the resulting candidate diff and verify that candidate. Reuse prior
+check evidence only when the checked source and relevant execution inputs are
+unchanged; changed bases, conflict resolutions or other relevant differences
+require the affected checks again.
+
+Keep the original edits through pending or failed delivery; only reconciliation
+removes them. Preserve all other work and report anything left behind.
+
+Allocation also returns a receipt-owned `scratch` directory. Put disposable
+build intermediates there (for example, set
+`CARGO_TARGET_DIR` to `<scratch>/target`). Keep source checkouts, Git data,
+lockfiles, reports and restart evidence outside scratch. Do not create unowned
+temporary build trees or preserve them by copying them into evidence custody.
+Prefer `TemporaryDirectory`/`finally` for short-lived test fixtures.
+
+After waiting for task writers, `complete --writers-stopped` empties this
+scratch on delivery returns, including local-only and pending-PR routes. To
+release build caches when parking or after a failed run, use:
+
+```sh
+python3 "$DEVLYN_SHARED_DIR/task-complete.py" clean-scratch \
+  --receipt '<returned receipt.json>' --writers-stopped
+```
+
+This empties only the prospectively owned scratch, preserves its directory
+identity for interrupted cleanup and later builds, checks live users and reports
+the logical byte count separately from actual free disk space. It does not depend on a product PASS or rewrite that verdict.
+Unknown historical roots, source/recovery data, shared caches and terminal
+history are never adopted or swept. A refused cleanup does not block source
+delivery; it stays visible in the handoff with its receipt and retry command
+(`CLEANUP_PENDING` after delivered source). No task is described as cleaned
+while owned disposable files remain. On resumption, finish any pending scratch
+cleanup before allocating more temporary storage; the next allocation also
+retries it for completed deliveries with released writers. Rebuild from retained
+inputs when needed; cleanup is not an instruction to restart parked work.
+
+## Accept a scoped commit
+
+In the allocated worktree, finish the candidate's decisive checks and diff
+review, then stage and commit only accepted task changes. The helper never
+stages product files. Write a
+root acceptance file in the checkout (usually ignored `.devlyn/acceptance.json`):
+
+```json
+{"kind":"direct","task":"<task identity>","source_sha":"<full commit>","checks":[{"command":"<actual check>","evidence":".devlyn/checks.log"}]}
+```
+
+The owner accepts these checks; the helper preserves evidence bytes and does
+not independently prove the assertions. Acceptance binds exact source and
+evidence before publication. Direct `complete` binds acceptance itself; no
+separate `accept` call is needed.
+
+Changed accepted source or evidence requires a new accepted task, never implicit
+descendant approval. Resume an existing receipt only for its unchanged candidate.
+After merge, implement follow-ups from the updated base. An additive follow-up
+depending on an open PR waits for that predecessor to merge.
+
+If a correction invalidates an open candidate, run `complete --mode pr` against
+its unchanged receipt, with its task tree clean, to cancel owned auto-merge, then
+reobserve the PR. If it
+remains open, close it as superseded and retain its receipt and custody; do not
+resume its delivery. Allocate a replacement from the current remote base,
+include only the still-needed task changes and correction, and verify and
+accept it anew. If the predecessor has merged, make a new follow-up instead.
+
+Queue drains follow ideate's loop protocol
+(`../devlyn-ideate/references/loop.md`): its evidence-derived `loop` result is
+bound with `accept` before the queue-only terminal commit is attached with
+`attach`, and dependent local tasks allocate from the accepted predecessor's
+source. Failed results keep custody and a recovery ref but are never published.
+
+## Deliver and resume
+
+Wait for your children, stop your dev servers and task writers, then leave the
+task tree. Make the FIRST completion call from outside it with the installed
+helper and `--writers-stopped`; this releases the tree for cleanup after merge:
+
+```sh
+python3 "$DEVLYN_SHARED_DIR/task-complete.py" complete \
+  --receipt '<returned receipt.json>' \
+  --acceptance '<task worktree>/.devlyn/acceptance.json' --writers-stopped
+```
+
+Project policy is `git config --local devlyn.completionMode auto|pr`; absent means
+`auto`. Invalid local values fail before external effects, even with an override.
+Use `complete --mode auto|pr` for one task, or `--local-only`/`--no-push` to honor
+the user's delivery restriction. These per-task choices persist in the receipt; `--local-only` is refused once the task ref is pushed.
+
+`pr` pushes the exact accepted task ref and creates/reuses its exact repository,
+head and base PR. While OPEN, it cancels owned auto-merge, reports `PR` with its URL
+and retains the checkout. Once MERGED by any method, either mode cleans released
+resources in that call, on resume or at the next allocation. Default `auto` also requests
+`gh pr merge --auto --merge --match-head-commit <accepted SHA>`. Repository
+checks/reviews and merge policy remain authoritative: no admin bypass, strategy
+fallback or repository setting changes. When the repository disallows merge
+commits or refuses the request, delivery reports `PR` with `merge_refused` and
+the PR waits for a person. Command success alone never proves merge.
+
+`PENDING` retains the workspace and reports a receipt-based resume command.
+`BLOCKED` names the cause and retry action; repair that condition before retrying.
+Resume reobserves Git/PR state under a per-receipt lock, reuses the original
+acceptance and performs only missing eligible effects.
+
+Verification and delivery obey the session's actual permissions. When an
+operation needs unavailable approval, finish permitted work, preserve the edits
+and evidence, and report that operation and its retry action. Before allocation,
+identify the original checkout and outstanding operation; after allocation,
+include the receipt-based resume command. Headless execution neither waives
+permissions nor silently changes delivery policy.
+
+Report verification, delivery and checkout reconciliation separately. A delivery
+error does not rewrite an accepted product result; unperformed verification
+must never be reported as accepted.
+
+## Yield and retain recoverability
+
+Cleanup requires actual matching MERGED evidence; linked-tree removal also
+requires the owner's recorded release. OS observation supplements it; neither the receipt
+nor a scan guarantees exclusion of future writers. Processes with cwd or open
+files inside the tree, inaccessible process state (on Linux, other users'
+processes unless run as root), caller cwd inside the tree, dirty/untracked files,
+a nested repository or worktree, or changed refs/Gitdir/registration retain
+affected resources. Use `git worktree lock` to keep a tree.
+On native Windows, locking and file durability are supported, but the helper cannot prove writer cessation and reports `writer observation unsupported on this platform; retain workspace`. Even `--writers-stopped` cannot authorize deletion without that observation: retain the workspace, its task refs and external receipt/custody, report delivery separately, and preserve the receipt-based resume command. A merged delivery therefore reports `CLEANUP_PENDING` (delivery `COMPLETE`) with `workspace_cleanup` naming the reason and resume. Do not kill unknown processes or force worktree removal to make completion pass.
+
+The receipt directory holds byte-verified `custody/`, `manifest.json` and a guarded
+`refs/devlyn/completed/<id>` recovery ref. Check evidence is copied there
+before publication; removal rechecks it, the recovery ref and the merge commit on base.
+Ignored build output and other ignored files are disposable under native
+non-force worktree removal. The tree's `.devlyn/` files are byte/mode-verified
+and preserved as `<receipt dir>/records/.devlyn`; non-regular files or symlinks
+there retain the tree. Partial/corrupt custody or records retain it for repair.
+
+Legacy in-place receipts retire refs only once their task branch is no longer
+checked out; their checkout is never modified. Local ref deletion is guarded by
+the expected SHA; remote deletion uses an exact force-with-lease solely as
+compare-and-delete, never for product publication. A changed remote branch is
+retained. Retry uses the external receipt/evidence after removal. Recovery
+refs/evidence have no automatic expiry.

package/config/skills/devlyn-engines/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: devlyn-engines
-description: Show and pin engine roles for the devlyn pipeline (executor / pair judge). Reads and writes machine-local .devlyn/engines.json with fail-closed validation. Use when the user asks which models are configured, wants to force a specific model for pipeline work ("수동모드", "engine 고정", "use codex to implement"), or wants to clear pins back to auto-detection.
+description: Show and pin the engine that executes devlyn implementation work. Reads and writes machine-local .devlyn/engines.json with fail-closed validation. Use when the user asks which engine is configured, wants to force a specific engine for implementation ("수동모드", "engine 고정", "use codex to implement"), or wants to clear the pin back to the default.
 ---
 
-Utility front-end for the role-resolution contract in `_shared/engine-preflight.md#role-resolution`. It adds no semantics of its own: everything it writes is exactly what `/devlyn-resolve` PHASE 0 reads.
+Utility front-end for the executor contract in `_shared/engine-preflight.md`. It adds no semantics of its own.
 
 <args>
 $ARGUMENTS
@@ -48,18 +48,16 @@ with the failed path. Never search another installation.
 Verify DEVLYN_SHARED_DIR/role-config.py and DEVLYN_SHARED_DIR/engine-doctor.sh before their respective commands. In omp, use `printf '%s\n' skill://devlyn-engines`.
 </runtime_paths>
 
-## No args — status + how to choose
+## No args — status
 
-1. Run `python3 "$DEVLYN_SHARED_DIR/role-config.py" --workdir "$PWD" --default-engine <orchestrator-supported-default>` and print each resolved role's engine, requested model/effort, source and channel. Null model/effort means inherited/unresolved, not an attested identity. Show unavailable pins and requested priority even when no OTHER is available; status does not authorize dispatch. A current run can instead be inspected with `--state .devlyn/pipeline.state.json`; do not reread config as though it changed the active run. Show returned observations with their evidence basis; effective effort remains unknown when only argv is bound.
-2. Run `bash "$DEVLYN_SHARED_DIR/engine-doctor.sh"` and show its availability/eligibility table. This does not prove authentication or model fitness.
+1. Run `python3 "$DEVLYN_SHARED_DIR/role-config.py" --workdir "$PWD" --default-engine <this CLI's engine>` and print the executor's engine, source (`engines.json` pin or `default`) and availability. `inactive` lists keys earlier releases wrote for retired pipeline roles: they select nothing, and `clear` removes them. CLI presence is not authentication.
+2. Run `bash "$DEVLYN_SHARED_DIR/engine-doctor.sh"` and show its availability/eligibility table.
 3. Show the subcommands below. Status never launches a model.
 
 ## Subcommands
 
-- `executor <name>` — pin the legacy executor; optional worker/primary profiles take their documented precedence. PLAN is orchestrator-fixed and never follows the pin. Refuse names with no `_shared/adapters/<name>.md`, or whose adapter's `## Role eligibility` section declares `executor: no` (judge-only backends), listing the valid names either way. If the engine's CLI is not currently available, still write the pin but warn: pins are promises — the run will stop with `BLOCKED:<name>-unavailable` until it is installed.
-- `pair <name>[,<name>...]` — set `pair_judge_priority` (ordered; first adapter-valid, pair-judge-eligible, non-primary, available entry wins at VERIFY/risk-probe time). Refuse names with no `_shared/adapters/<name>.md`, or whose adapter declares `pair_judge: no`.
-- `role <worker|primary_judge|pair_judge> <JSON object>` — write one atomic role entry, e.g. `{"engine":"codex","model":"gpt-6-astra","effort":"high"}`. Invoke `python3 "$DEVLYN_SHARED_DIR/role-config.py" --workdir "$PWD" --default-engine <orchestrator-supported-default> --set-role <role> --value '<JSON object>'` using structured argv, never shell interpolation of user text. Unknown fields/types and ineligible roles fail without changing prior bytes.
-- `role <name> clear` — same command with `--value clear` removes only that override.
-- `clear` — invoke the helper with `--set-role clear` to remove legacy and role pins; preserve unrelated keys and delete an empty file.
+- `executor <name>` — run the status command with `--set-executor <name>`. It refuses a name with no `_shared/adapters/<name>.md`, or whose adapter declares `executor: no`, and lists the valid names. An engine whose CLI is not available is still pinned, with a warning: pins are promises, and dispatch stops with `BLOCKED:<name>-unavailable` until it is installed.
+- `clear` — run the status command with `--clear`: it removes the executor pin and the inactive keys, preserves unrelated keys, and deletes an empty file.
+- `pair` and `role` were removed with the retired pipeline roles: say so and change nothing.
 
-Writes preserve unrelated top-level keys already in the file; unknown fields inside roles are errors. After every change, re-print the resolved role table. Never modify anything outside `.devlyn/engines.json`, and never launch a pipeline from this skill.
+Pass the engine name as one structured argument, never by shell interpolation of user text. After every change, re-print the status. Never modify anything outside `.devlyn/engines.json`.

package/config/skills/devlyn-ideate/SKILL.md

@@ -1,33 +1,21 @@
 ---
 name: devlyn-ideate
-description: Extract a verifiable spec from a user's idea by driving the conversation with focused questions. Output is a single-feature `spec.md` + `spec.expected.json` that `/devlyn-resolve --spec` consumes directly. Use when the user has an idea but not a spec, or wants AI to elicit the missing engineering context. Modes — default (single spec, AI drives Q&A), `--quick` (assume-and-confirm from one-line goal), `--from-spec <path>` (normalize external spec), `--project` (plan.md index + N specs). Optional in the pipeline — `/devlyn-resolve` works standalone via free-form mode for users who skip ideate.
+description: Loop designer and intent queue. Turns an intent or a document into a validated loop package (a meta-prompt plus self-contained task contracts), queues its tasks, reports queue status, and drains the queue serially with evidence-derived acceptance, recovery and delivery. Operations — plan, add, status, drain; a bare intent is planned and, when the request authorizes implementation, continues through add and drain; no arguments shows status. Use when the user wants an idea, goal or document planned into tasks, wants to stack work ("queue this", "큐에 넣어줘"), asks what is queued, or wants unattended execution ("drain the queue", "큐 드레인 시작", "밤새 돌려줘").
 ---
 
-Spec-elicitation surface for users who have ideas but not engineering specifications. AI drives the conversation with focused questions until a structurally-valid, verifiable spec exists. Output consumed directly by `/devlyn-resolve --spec`.
+Ideate owns planning and durable serial execution. Each task runs under the installed methodology, the CLAUDE.md/AGENTS.md instruction block; ideate adds no phase graph, reviewer quota, engine router or restart cycle.
 
-<elicit_config>
+<ideate_args>
 $ARGUMENTS
-</elicit_config>
-
-<orchestrator_context>
-This skill is OPTIONAL. `/devlyn-resolve` is standalone-capable: free-form mode handles trivial/medium tasks without a spec, `--spec` mode accepts handwritten specs from any source. Use ideate when the user wants AI to do the elicitation work.
-</orchestrator_context>
-
-<elicitation_contract>
-The user does not know context engineering. They will under-specify and over-assume. AI's job is to ask focused, specific questions that surface the missing engineering decisions.
-
-1. Ask one or two questions per turn, not more. Multi-question lists overwhelm and produce shallow answers.
-2. Questions are concrete and decision-grade — what is the input, what is the expected output, what command verifies success, what files are out of scope.
-3. Do not ask design preferences the user clearly does not have. Infer the simplest reasonable default and confirm in one line.
-4. Stop when the spec passes structural lint AND the user explicitly confirms or 8 turns have elapsed (whichever comes first). Eight turns is a hard ceiling — beyond that, the spec is either ready or the task is too large for ideate.
-5. The output is the spec, not a transcript. Do not include the conversation in the saved files.
-</elicitation_contract>
+</ideate_args>
 
 <harness_principles>
-Read `_shared/runtime-principles.md` (Subtractive-first / Goal-locked / Evidence-over-claim). The principles bind the spec content as well as your conversation. A spec that says "for future flexibility" is a Subtractive-first violation. A spec that asks for `try { ... } catch { return null }` is a No-workaround violation. AI flags these in elicitation, not after `/devlyn-resolve` has built them.
+`_shared/runtime-principles.md`, mirrored in the installed instruction block (read the file only when no block is loaded), binds package content as well as the conversation: a requirement "for future flexibility" violates Subtractive-first, and acceptance that permits a silent fallback violates No-workaround. Flag these while planning, not after execution.
 </harness_principles>
 
 <runtime_paths>
+Before any operation, establish the bindings below.
+
 Resolve bundled resources from the SKILL.md loaded for this invocation.
 
 Reader-rendered directory hint:
@@ -61,116 +49,78 @@ written as _shared/... use this binding. Verify the directory and each
 required resource before use; failure is BLOCKED:shared-dir-unresolved
 with the failed path. Never search another installation.
 
-Verify DEVLYN_SHARED_DIR/spec-verify-check.py before validation. Use `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py"` for spec validation commands after binding the path in that shell. In omp, use `printf '%s\n' skill://devlyn-ideate`.
+Verify DEVLYN_SKILL_DIR/scripts/queue.py before running it. In omp, use `printf '%s\n' skill://devlyn-ideate`.
 </runtime_paths>
 
-<engine_routing>
-Default engine: Claude. The per-engine adapter from `_shared/adapters/<engine>.md` is prepended to the elicitation prompt so the model honors its own official prompt-engineering guidance during the Q&A.
-</engine_routing>
-
-<modes>
-Four modes, selected by flag:
-
-1. **Default** (no flag) — single-spec elicitation. AI asks questions in-conversation until lint passes. Output: `<spec-dir>/<id>-<slug>/spec.md` + `<spec-dir>/<id>-<slug>/spec.expected.json`. Default spec dir: `docs/specs/` (configurable via `--spec-dir <path>`).
-2. **`--quick`** — one-line goal, AI synthesizes a spec with explicit assumptions block, asks the user to confirm or correct in a single turn. Use when the user wants speed over thoroughness.
-3. **`--from-spec <path>`** — external spec exists. AI lints it for the canonical structure, normalizes section names, generates a missing `spec.expected.json` if absent, fixes minor schema issues, and stops. Does NOT reshape Requirements / Out-of-Scope content; structural changes only.
-4. **`--project`** — multi-feature project. AI elicits a project description, decomposes it into 3-7 feature specs, writes `<spec-dir>/plan.md` (the index) and one `<spec-dir>/<id>/spec.md` + `<spec-dir>/<id>/spec.expected.json` per feature. See `references/project-mode.md`.
+## Operations
 
-`--spec-dir <path>` overrides the default output directory. `--engine <model>` selects the adapter.
-</modes>
+| Invocation | Behavior |
+|---|---|
+| `plan <intent or absolute document path>` | Inspect, elicit what is necessary and write a validated loop package. Does not enqueue or execute. |
+| `add <intent or absolute package path>` | Plan when necessary, then capture the package and queue its tasks in dependency order. Does not execute. |
+| `status` | Reconciled pending, active, accepted and failed counts; the next runnable task; delivery and recovery blockers. |
+| `drain` | Resume or drain the queue serially under existing execution authorization. |
+| Bare intent | Plan; when the request authorizes implementation, continue through add and drain without reconfirmation. |
+| No arguments | Status. |
 
-<spec_kind_escape_hatch>
-The spec carries `spec.kind ∈ {feature, spike, prototype}` in its frontmatter. The kind changes downstream behavior:
+Two controls only: `--autonomous` applies the autonomous policy to plan or add (drain always applies it), and `--local-only` keeps a drain's delivery local (`--no-push` is equivalent). A delivery restriction already established for a loop persists. Engine selection and pins stay project and host settings (`/devlyn-engines`).
 
-- **feature** — production-quality implementation expected. `/devlyn-resolve --spec` runs the full pipeline (PLAN → IMPLEMENT → BUILD_GATE → CLEANUP → VERIFY).
-- **spike** — exploratory work; deliverable is learning, evidence, or a disposable demo. `/devlyn-resolve --spec` proceeds but VERIFY's quality bar is relaxed for code that the spike says is throwaway.
-- **prototype** — between feature and spike. Production-shape but not production-grade. CLEANUP runs; VERIFY's quality bar is stricter than spike, looser than feature.
+A removed flag stops with its instruction and selects no other behavior.
 
-The user picks the kind during elicitation. Default = feature when not specified. `--quick` infers from the goal text (verbs like "explore", "investigate", "spike" → spike; "implement", "ship", "add" → feature).
-</spec_kind_escape_hatch>
+| Flag | Instruction |
+|---|---|
+| `--quick` | Removed: use `plan <intent>`, adding `--autonomous` to plan without questions. |
+| `--from-spec <path>` | Removed: use `plan <absolute path>`; the document stays unchanged as the input contract. |
+| `--project` | Removed: every plan is a loop package with as many tasks as the intent needs. |
+| `--spec-dir`, `--spec-id`, `--in-place` | Removed: packages live at `docs/specs/<loop-id>/` with generated IDs, and input documents are never rewritten. |
+| `--engine` | Removed: drain uses the configured executor; pin it with `/devlyn-engines executor <name>`. |
 
-## PHASE 0: PARSE + ROUTE
+## Question policy
 
-1. Parse flags from `<elicit_config>`:
-   - `--quick`
-   - `--from-spec <path>`
-   - `--project`
-   - `--spec-dir <path>` (default `docs/specs/`)
-   - `--engine MODE` (default `claude`)
-   - `--spec-id <id>` — optional explicit id; auto-generated when absent.
+> Inspect available project facts before asking. Ask only when the unresolved answer changes authorized behavior, scope, data semantics, acceptance or delivery. State the recommended answer and its consequence. Ask the smallest useful question. Stop eliciting when the contract is executable and verifiable; no turn target or mandatory confirmation applies. Existing authorization remains effective.
 
-2. Engine pre-flight: `_shared/engine-preflight.md`.
+## Autonomous policy
 
-3. Mode dispatch:
-   - default → PHASE 1.
-   - `--quick` → PHASE 1Q (single turn assume-and-confirm).
-   - `--from-spec` → PHASE 1F (lint + normalize external).
-   - `--project` → PHASE 1P (project decomposition).
+> For ordinary details the intent leaves open within authorized scope, follow established project conventions, otherwise the narrowest literal or conventional reading consistent with the request; these defaults may be user-visible but must be low-consequence and reversible. Record each choice and reason once. Material ambiguity means competing readings with materially different intended outcomes, unresolved persistent data or state semantics, or public surface beyond the request; stop affected work as needs-review with a concrete question. Independent authorized work may continue. Never omit requested work or weaken acceptance to obtain completion.
 
-## PHASE 1: ELICITATION (default mode)
+## plan
 
-Prompt body: `references/elicitation.md`. Adapter prepended.
+1. Inspect, then elicit, per [elicitation.md](references/elicitation.md). A document argument is the input contract: carry each substantive requirement into a task without weakening it, cite the document in `## Intent`, and never modify it.
+2. Write `docs/specs/<loop-id>/meta.md` and each task's `spec.md` and `spec.expected.json` per [package-format.md](references/package-format.md). In the manifest, `base_ref` is the delivery branch and `base_sha` the exact commit the loop builds on; `delivery` is `local-only` when the user restricted delivery or, recorded as an assumption, when `origin` does not name one GitHub repository; `pr` when the user asked to stop at the PR; `auto` when the user asked to merge, even under a `pr` project policy; else the project's `git config --local devlyn.completionMode` (absent means `auto`). An explicit PR or merge request whose `origin` does not name one GitHub repository stops planning with that question. `## Execution policy` quotes the autonomous policy, which binds every task's executor.
+3. Run `python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" check '<absolute meta.md>'` and repair the package until it reports `VALID`.
+4. Report the package path, the tasks with their dependencies, and every recorded assumption.
 
-The elicitation agent:
-1. Reads the user's initial goal from `<elicit_config>`.
-2. Identifies the missing engineering decisions (input shape, output shape, success command, scope boundary, constraints).
-3. Asks 1-2 focused questions per turn until each blank is filled or the user accepts an inferred default.
-4. Maintains a running draft spec in `.devlyn/ideate-draft.md` (run-scoped, gitignored).
-5. Stops when the structural lint passes AND user confirms, or 8 turns elapsed.
+## add
 
-Structural lint (inline check, no script needed):
-- Frontmatter has `id`, `title`, `kind`, `status: planned`, `complexity`.
-- `## Context` non-empty (≥ 1 sentence).
-- `## Requirements` has ≥ 1 `- [ ]` bullet.
-- `## Out of Scope` present (may list "none" if truly nothing).
-- `## Verification` is preceded by a `<!-- devlyn:verification -->` sentinel and has either ≥ 1 named command OR sibling `spec.expected.json` declares `"pure_design": true`.
+An absolute path to a package's `meta.md` is added as it is; anything else is planned first. Add with `python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" add '<absolute meta.md>'`, the only writer of a loop's queue file `docs/specs/<loop-id>/queue.md`; never edit one by hand. In every delivery mode add makes no commit on the checked-out branch and leaves the branch, the index and tracked files as they are: it holds the package and its rows at `refs/devlyn/captures/<loop-id>`, records the add and removes the package copies equal to that capture. Report the capture ref and its `git show` command, any `cleanup` entry, and that a revision needs a new loop id. It refuses package changes staged in the index (unstage them and add again), and a retry of the same add reports it as added, also once the copies are gone. Tasks start from committed state, a local loop from the branch it was added on and `auto`/`pr` from the remote base, so commit, and for `auto`/`pr` push, whatever the plan depends on. A pending legacy raw-intent row of `docs/specs/queue.md` is replaced in place by a package whose `## Intent` reproduces the row verbatim, added with `--materialize <line>`.
 
-After lint passes:
-1. Write `<spec-dir>/<id>-<slug>/spec.md` (the spec).
-2. Generate `<spec-dir>/<id>-<slug>/spec.expected.json` following `references/spec-template.md` § "Sibling file: `spec.expected.json`" for constraint coverage, diff scope and guard controls.
-3. Run `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check <spec-path>` to validate the actual spec's carrier shape and supported `complexity` frontmatter. Sibling `spec.expected.json` takes precedence over the legacy inline `## Verification` JSON carrier. If exit 2, fix the file named in the error and re-run.
-4. Run `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check-expected <expected-path>` to validate sibling `spec.expected.json` against `_shared/expected.schema.json` plus sibling spec `complexity` frontmatter. If exit 2, fix the JSON/frontmatter and re-run.
-5. Print: `spec ready — /devlyn-resolve --spec <spec-path>`.
+## status
 
-## PHASE 1Q: QUICK MODE
+Run `python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" status --repo .` and report its counts, `next`, `blockers`, pending deliveries with their resume commands and any `cleanup` entry.
 
-Single-turn assume-and-confirm. Prompt body: see `references/elicitation.md` § "Quick mode".
+## drain
 
-1. AI synthesizes a spec from the one-line goal.
-2. AI surfaces an explicit "Assumptions made" section listing every inferred decision.
-3. User responds with "go" / "fix X" / "no, different".
-4. On "go": write spec + spec.expected.json + lint + announce.
-5. On "fix X": apply correction, re-show, ask again. Maximum 3 correction rounds before escalating to default mode.
+Follow [loop.md](references/loop.md). The executor is the configured route, the `.devlyn/engines.json` `executor` pin or else this CLI, checked per `_shared/engine-preflight.md`. Pass its argv after `--`. `<git dir>` is the output of `git rev-parse --path-format=absolute --git-common-dir`, where the executor commits and writes its submission; the drain fills `{worktree_git_dir}` with the task worktree's own Git directory, which Codex's sandbox keeps read-only unless that exact directory is listed:
 
-## PHASE 1F: FROM-SPEC MODE
+| Executor | argv |
+|---|---|
+| Claude | `claude -p "<prompt>" --dangerously-skip-permissions --add-dir "<git dir>"` |
+| Codex | `bash "<DEVLYN_SHARED_DIR>/codex-monitored.sh" --skip-git-repo-check -s workspace-write -c 'sandbox_workspace_write.writable_roots=["<git dir>","{worktree_git_dir}"]' -c 'sandbox_workspace_write.network_access=true' "<prompt>"` |
 
-Prompt body: `references/from-spec-mode.md`.
+Another engine needs an argv that starts one fresh non-interactive session able, without prompts, to edit, run commands and commit in its task worktree and to write the packet's submission file. `<prompt>` carries the absolute binding values, while `{packet}` stays literal for the drain to fill:
 
-1. Read the external spec at `<path>`.
-2. Lint structure (same checks as default mode).
-3. Identify missing pieces (no frontmatter, missing sections, malformed Verification block).
-4. Apply structural fixes only — do NOT reshape Requirements / Out-of-Scope content. The user's substantive intent is preserved.
-5. Generate `spec.expected.json` if absent, following the same template carrier guidance as default mode.
-6. Write the normalized spec back to `<spec-dir>/<id>-<slug>/` (preserves original at `<path>` untouched unless user passes `--in-place`).
-7. Run both lint checks: `--check <spec-path>` and `--check-expected <expected-path>`.
-8. Lint pass → announce. Lint fail → surface the unfixable issue and exit non-zero.
-
-## PHASE 1P: PROJECT MODE
-
-Prompt body: `references/project-mode.md`.
-
-1. AI elicits a project description (longer Q&A — multi-feature scope warrants more turns).
-2. AI decomposes the project into 3-7 feature specs. Each feature is independently shippable; cross-feature dependencies surface explicitly in the spec frontmatter `depends_on:` field.
-3. AI writes `<spec-dir>/plan.md` — index file with: project name, decomposition rationale, list of feature specs with id + title + dependency, suggested implementation order.
-4. AI writes one `<spec-dir>/<id>/spec.md` + `<spec-dir>/<id>/spec.expected.json` per feature, each lint-validated.
-5. Announce: `project ready — N specs at <spec-dir>/. Start with /devlyn-resolve --spec <first-spec-path>`.
+```text
+Execute the devlyn loop task packet {packet}: work only in its owned worktree under the installed instructions; meet its obligations, then write its submission and any review records as "Executor exchange" and "Review records" in <DEVLYN_SKILL_DIR>/references/loop.md specify. Set DEVLYN_SKILL_DIR=<DEVLYN_SKILL_DIR> and DEVLYN_SHARED_DIR=<DEVLYN_SHARED_DIR> from these literal values, never from your inherited environment. Never push, open a pull request or merge: the drain delivers.
+```
 
-`/devlyn-resolve` consumes one spec at a time; the user works through `plan.md`'s suggested order. Multi-feature parallel runs are Mission 2 work.
+```sh
+python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" drain --repo . [--local-only] -- <executor argv>
+```
 
-## State management
+A drain can run for hours. Do not end the turn until it exits: run it in the foreground with the longest allowed timeout, or in the background and await its completion notice, because a headless host kills background tasks at its final response.
 
-ideate is conversational, not pipeline-staged. State lives in:
-- `.devlyn/ideate-draft.md` — current draft spec during elicitation (run-scoped, gitignored).
-- `<spec-dir>/<id>-<slug>/` — final output (committed to repo by user choice).
+- `WAITING` on legacy rows: plan and materialize each under the autonomous policy, then drain again; a row whose planning stops on material ambiguity stays pending and its question is reported.
+- `WAITING` on anything else, or `BLOCKED`: report the reason and resume commands; never edit receipts, refs or queue rows to get past them.
+- An interrupted drain is resumed by running `drain` again; accepted work is never replayed, and a failed task is never rerun: plan its work again as a new loop.
 
-No `pipeline.state.json` here — that's resolve's surface.
+Report each task's product result, delivery status, PR URL, resume command, assumptions and unresolved questions, plus whole-loop acceptance, the package's `## Decisions and assumptions`, the drain report paths and its exact `Bring into` command; leave running it to the user. Report any `cleanup` entry too: a package copy left in the checkout stops that command until it is removed.