devlyn-cli 4.1.0 → 4.2.0

package/config/skills/devlyn-ideate/references/elicitation.md

@@ -1,110 +1,29 @@
-# Elicitation flow (canonical body)
+# Planning and elicitation
 
-Per-engine adapter prepended at runtime. This file is engine-agnostic.
+How `plan` applies the question and autonomous policies in SKILL.md; [package-format.md](package-format.md) defines what it writes. No turn target, question quota or confirmation step applies.
 
-<role>
-You drive a focused conversation with a user who has an idea but not an engineering spec. Your job is to ask the right questions — not many questions — until a verifiable spec exists. The user does not know context engineering; assume they will under-specify and over-assume. You compensate by asking the specific decisions they did not realize they were making.
-</role>
+## Inspect first
 
-<input>
-- The user's initial goal text (free-form, possibly ambiguous).
-- The codebase (read-only) — for grounding inferred defaults.
-- `references/spec-template.md` — the shape of the output.
-- `_shared/expected.schema.json` — the shape of `spec.expected.json`.
-</input>
+Read what the project already answers before asking: the code paths, tests and conventions the intent touches, the installed instructions and completion mode, the queue through `queue.py status` and each added loop's capture (`git for-each-ref refs/devlyn/captures`, then `git show <ref>:docs/specs/<loop-id>/meta.md`) rather than package files in the checkout, and any document the user supplied. Infer `kind` from the framing (investigate or explore → `spike`, a rough version → `prototype`, otherwise `feature`) instead of asking.
 
-<conversation_rules>
-1. Ask 1-2 questions per turn. More than that overwhelms the user and produces shallow answers.
-2. Questions are concrete and decision-grade. Bad: "what should the UX look like?" Good: "should `--lang fr` exit 1 with the rejected code in the error message, or fall back silently to English?"
-3. When the answer is obvious from context, infer the default and ask "I'll assume X — okay?" instead of asking the user to choose. Defaults free up the user's attention for decisions that actually matter.
-4. Track what is filled and what is missing in your running draft at `.devlyn/ideate-draft.md`. Update after each turn.
-5. Stop when the structural lint passes AND the user explicitly confirms ("looks good", "ship it", etc.). Hard ceiling: 8 turns total. Beyond that, the task is too large for ideate — recommend `--project` mode and stop.
-6. Do not save the conversation. The output is the spec.
-</conversation_rules>
+## What to ask
 
-<missing_decisions_to_surface>
-For most coding tasks, the under-specified blanks are:
+Only an answer that changes authorized behavior, scope, data semantics, acceptance or delivery:
 
-1. **Input shape**: what does the user invoke to trigger the feature? Exact CLI command, HTTP request, function call?
-2. **Output shape**: what does success look like? Exit code, stdout substring, file existence, JSON shape?
-3. **Failure shape**: what happens on bad input? Exit code, error message format, fallback behavior (silent vs visible)?
-4. **Scope boundary**: which files are in-scope, which are out-of-scope? "Don't touch the auth module" is a boundary worth surfacing.
-5. **Constraints**: dependency policy (new deps allowed?), silent-catch policy, type-system escape policy, test coverage expectations.
-6. **Complexity signal**: set spec frontmatter `complexity` to `high` when
-   the spec needs a compound scenario crossing state mutation with ordering,
-   idempotency, auth/error priority, rollback/failure handling, or exact output
-   shape. This is a downstream VERIFY pair-trigger signal, not a vague
-   difficulty label.
-7. **Verification**: how does the user know it worked? Pick the smallest concrete check.
-   If the goal combines state mutation with ordering/priority, idempotency,
-   auth/error priority, or exact output shape, ask for one concrete compound
-   scenario that exercises the interaction end-to-end instead of accepting only
-   isolated happy-path checks.
+- **Behavior** — the exact input, output and failure a user observes. An unspecified user-visible detail alone is not material ambiguity; apply the autonomous policy's boundary.
+- **Scope** — what may change and what must not.
+- **Data semantics** — persisted state, ordering, idempotency, migration.
+- **Acceptance** — the smallest decisive check for each requirement.
+- **Delivery** — local-only, PR or merge.
 
-Walk through these in roughly this order. Skip the ones already clear from the user's initial text.
-</missing_decisions_to_surface>
+Lead with the recommendation and its consequence, for example: "Should `--lang fr` exit 1 naming the rejected code? Recommended: yes, so bad input stays visible instead of silently falling back to English." Decide preferences the user has no stake in.
 
-<spec_kind_inference>
-Infer `spec.kind` from the user's framing:
+## Autonomous planning
 
-- "explore", "investigate", "I'm not sure if X is possible", "let's see what works" → spike. Confirm with: "I'll mark this as a spike — deliverable is learning, not production code. Sound right?"
-- "prototype", "rough version", "show me what it would look like" → prototype.
-- Default: feature. The user wants production-quality work.
+With `--autonomous`, or when a drain plans a legacy row, take only the defaults the autonomous policy allows and record each once under `## Decisions and assumptions`. Material ambiguity stops planning with its concrete question.
 
-Do not ask "is this a feature, spike, or prototype?" — the user does not know the difference. Infer and confirm in one line.
-</spec_kind_inference>
+## Tasks and checks
 
-<draft_spec>
-Maintain `.devlyn/ideate-draft.md` after every user turn. Include:
-- Latest version of all 6 sections (Frontmatter, Context, Requirements, Constraints, Out of Scope, Verification).
-- "TODO" markers for sections still missing pieces.
-- A "decisions log" comment at the bottom listing what each turn settled.
-
-When you're about to ask the user a question, look at the draft first — if the answer is already discoverable from the initial goal + codebase, infer it instead of asking.
-</draft_spec>
-
-<lint>
-Before declaring the spec ready, verify structurally:
-- Frontmatter has `id`, `title`, `kind`, `status: planned`, `complexity`.
-- All 5 H2 sections present (`## Context`, `## Requirements`, `## Constraints`, `## Out of Scope`, `## Verification`).
-- Requirements ≥ 1 bullet.
-- Verification has either ≥ 1 named command OR the explicit pure-design escape phrase.
-
-If the lint fails, fix the missing piece (ask one focused question if needed) before announcing.
-
-After lint passes, run both mechanical checks:
-1. `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check <spec-path>` validates the spec's verification carrier shape and supported `complexity` frontmatter.
-2. `python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check-expected <expected-path>` validates sibling `spec.expected.json` against `_shared/expected.schema.json` plus sibling spec `complexity` frontmatter.
-
-If either exits 2: read the stderr message, fix the malformed carrier or JSON, and re-run the failed command. Both commands must exit 0 before ready.
-</lint>
-
-<output>
-Two files in `<spec-dir>/<id>-<slug>/`:
-- `spec.md` (per template).
-- `spec.expected.json` (per `_shared/expected.schema.json`).
-
-Final announcement (one line): `spec ready — /devlyn-resolve --spec <spec-path>`.
-
-Do NOT include the conversation transcript in the output. The spec stands alone.
-</output>
-
-## Quick mode (1Q) — single-turn assume-and-confirm
-
-When `--quick` is set:
-
-1. AI synthesizes spec from the one-line goal — fill every section with the most reasonable inference.
-2. AI presents the spec to the user with an explicit `## Assumptions made` block listing every inferred decision (one bullet each).
-3. User responds with "go" / "fix X to be Y" / "no, different".
-4. On "go": write the spec + spec.expected.json, run both lint checks, announce.
-5. On "fix X": apply correction, re-present, ask again. Maximum 3 correction rounds before escalating to default mode.
-
-Quick mode trades thoroughness for speed. Use it for trivial-medium tasks where the user has a clear-enough goal that one round of inference + correction is sufficient.
-
-## Anti-patterns
-
-- Walls of questions in one turn.
-- Open-ended "what would you like" questions when the user clearly does not know.
-- Adding "for future flexibility" or "just in case" sections to the spec — the user did not ask for those, and the principles binding `/devlyn-resolve` reject them.
-- Saving the conversation transcript alongside the spec.
-- Stalling when the user gives a vague answer — re-ask with a more specific shape ("should it be A, B, or other?") rather than re-asking the same question.
+- One task per independently verifiable deliverable.
+- A check must fail on the wrong behavior. When requirements interact (state with ordering, idempotency, error priority or an exact output shape), add one compound check that exercises the interaction end to end. Validate each new guard with a violating control that fails and an allowed control that passes.
+- Semantic or source judgments are review requirements, not regular expressions. A requirement that resists a mechanical check becomes a review requirement; it is never weakened into something checkable.

package/config/skills/devlyn-ideate/references/loop.md

@@ -0,0 +1,110 @@
+# Loop protocol
+
+`drain` runs the queue serially. Each eligible task gets an owned worktree, committed inputs, one executor exchange, evidence-derived acceptance, a queue-only terminal commit and delivery. The executor works under the installed methodology (the CLAUDE.md/AGENTS.md instruction block); the loop adds no phase graph, reviewer quota, engine router or restart cycle. Formats: [package-format.md](package-format.md). Allocation, custody, delivery and cleanup follow the completion contract in `$DEVLYN_SHARED_DIR/task-completion.md`.
+
+## Commands
+
+```sh
+python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" status --repo .
+python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" drain --repo . [--local-only] [--worktree-root <dir>] -- <executor argv containing {packet}>
+```
+
+Both print one JSON object; exit 1 is `BLOCKED` with a `reason`.
+
+- `status` writes nothing beyond finishing `add`'s cleanup (step 1): reconciled counts (`pending`, `active`, `accepted`, `failed`, `blocked`, `legacy_pending`), the `next` task, `blockers`, deliveries still pending with their resume (drain again until the terminal commit is attached, then `task-complete.py complete --receipt <receipt>`), and under `cleanup` the package copies `add` kept or could not remove.
+- `drain` ends `DRAINED` (no runnable task remains; open deliveries show per task), `WAITING` (a task waits with its reason, or legacy rows need planning) or `BLOCKED` (conflict, invalid input or a recovery blocker). Progress lines `devlyn-loop: <task>: <event>` go to stderr.
+- `--local-only` (alias `--no-push`) keeps the loop local. A manifest `delivery: local-only` and any earlier local receipt of the loop keep that restriction for later drains. A local loop needs no remote; nothing is fetched or pushed. An `auto`/`pr` loop none of whose tasks has a pushed PR runs as a local loop from its capture and the branch it was added on. Once one has, that PR is never rewritten to local and the loop is never run locally: its tasks wait, naming the PR, while other work continues.
+- Worktrees default to `<repo parent>/<repo name>.devlyn/<loop-id>/<task-id>`.
+
+The host supplies the executor and maps its configured engine to the argv; the loop has no model preference. Each `{packet}` in the argv is replaced by the task packet path, and each `{worktree_git_dir}` by the task worktree's absolute Git directory. The executor runs with the task worktree as its working directory and the null device as stdin; its stdout and stderr are appended to `executor.stdout` and `executor.stderr` in the packet's `evidence_dir`, never a pipe.
+
+`<common Gitdir>/devlyn-loops/drain.lock` is held for the controller's lifetime, so a second drain from any worktree of the repository is refused. `queue.lock` is held only to read the add records and queue files, to add a loop and to make terminal transitions, so `add` works during a drain.
+
+## Steps
+
+1. **Reconcile.** First finish `add`'s cleanup of package copies ([package-format.md](package-format.md) Commands). Then read the queue view: the legacy rows, each replaced row as its loop's rows, then each loop's rows, from its capture or, without a record, from the checkout's tracked queue file ([package-format.md](package-format.md) Queue rows); every `<common Gitdir>/devlyn-completion/*/receipt.json` and their recovery refs. A row's identity, its receipt's branch `devlyn/<loop-id>/<task-id>`, the recovery ref (equal to the receipt's `publish_sha`, or to its validated terminal commit while that attachment is unfinished), the terminal commit's mark and, while active, the committed contract digests must agree. A receipt's terminal result supplements a `[ ]` row. Two receipts for one task or a terminal row contradicting its receipt stop selection with the conflict named; an unfinished allocation makes its task wait (step 10). A captured package never changes; for a loop without a record, an active task whose contract or expected acceptance changed in the checkout, also when that text is now missing or invalid, becomes `[F] inputs-changed` without executing again, its workspace retained, other work continuing while the revision is planned as a new task, and a pending task whose package text fails validation waits with that error, as do its dependents. Unsettled receipts (active, terminal commit unattached, or delivery not final) resume before any new allocation.
+2. **Select** the earliest pending row whose prerequisites are accepted with a receipt in every mode (a hand-written `[x]` never counts) and, for `auto`/`pr`, delivered (merged). A failed or blocked prerequisite makes its dependent `[F] blocked-prerequisite:<id>` without invoking the executor; that derived mark is proven by the prerequisite's receipt and travels into later checkouts and the report. A prerequisite awaiting delivery leaves its dependent pending while independent work continues; so does an `auto`/`pr` carrier in flight (step 3), or a local loop's active task (a local loop runs one task at a time), for every other task of its loop. Legacy rows wait for `add --materialize`.
+3. **Allocate** a new owned worktree on the absent branch `devlyn/<loop-id>/<task-id>` with `task-complete.py allocate`. First, the commit the task starts from must ignore `.devlyn/` (a committed `.gitignore` entry there, or `<common Gitdir>/info/exclude`), or nothing is allocated and the drain blocks naming the fix. It must also hold this checkout's `CLAUDE.md` and `AGENTS.md` (each identical, or both absent), so the task runs under the installed instructions, and, where it holds the loop's queue file, every captured package file unchanged, so the task binds its captured contract; otherwise the task waits, naming the fix, while independent work continues.
+   - Local: the first task uses `--local-base <HEAD of the branch the loop was added on>`, the add record's branch, never whichever branch is checked out; that HEAD must descend from the manifest `base_sha`, or the task waits naming it. Instructions committed there before this first allocation are therefore used. Its receipt keeps that start, and a later task with no accepted predecessor reuses it, also after the first task failed; a fixed start is never recalculated. Later tasks use `--from-receipt <latest accepted receipt of the loop>`, which starts from that receipt's exact `source_sha`, never its terminal commit, current HEAD or workspace. Every prerequisite's accepted source must be an ancestor of that frontier; divergent dependencies need a planned integration task, because the driver never merges. A failure leaves the frontier unchanged.
+   - `auto`/`pr`: `--start` the refreshed remote base, never an anchor-local commit, so no unpushed anchor commit reaches a task PR; push whatever the plan depends on. A task allocated while that base lacks `docs/specs/<loop-id>/` is the loop's carrier; a carrier that fails is never published, and the next task allocated becomes the carrier. The start must contain each prerequisite's merge commit, checked before allocation and again before every execution or resume. A squash merge needs no original-source ancestry.
+4. **Commit scoped inputs** on the owned branch before any executor write, only what the allocation base lacks. A base without `docs/specs/<loop-id>/` gets the package directory from the capture with the loop's queue file, its settled rows keeping their marks (receipt-proven `[x]` and `[F]`, prerequisite-blocked `[F]`): a local loop's first task, or an `auto`/`pr` carrier, whose PR lands the package before tasks diverge. Otherwise a local task commits the base's queue file with the loop's receipt-proven terminal rows (typically a predecessor's `[x]`), every other byte unchanged, and an `auto`/`pr` task commits nothing, so its PR changes only its own row and its product. A base that already carries them gets no inputs commit; unrelated product commits stay out.
+5. **Exchange one packet.** Write `<receipt dir>/packet.json`, then run the executor. An executor that exits without writing its submission leaves its task active, waiting with the exit code and `executor.stderr`, and the next drain runs it again; one that cannot start blocks the drain.
+6. **Derive acceptance** with `acceptance.py accept`. It binds the committed contract to the packet digests; requires the candidate to be the owned branch head with HEAD checked out on that branch, to descend from the inputs, to leave the package (its queue file included) and `docs/specs/queue.md` untouched and to have a clean worktree; executes each declared command on that source, recording raw stdout/stderr and exit, timeout or spawn outcomes (a runner result is reused only when it is wholly clean — no reasons, so no failed check and no source change during its checks — for the same source and contract digests, with unchanged streams); evaluates the file and diff guards against the inputs; confirms the source is unchanged; checks review records; and writes `.devlyn/loop/acceptance.json`. Missing checks, missing review coverage and open binding findings cannot produce `[x]`, and acceptance weakening is not repair. This establishes command outcomes and evidence completeness, not a reviewer's semantic judgment; deliberate evidence forgery is outside the trust model.
+7. **Bind before terminal metadata.** `task-complete.py accept --receipt <receipt> --acceptance <worktree>/.devlyn/loop/acceptance.json` takes evidence custody and points the recovery ref at the source. Failed results are bound the same way; they never become a frontier or a publishable product.
+8. **Commit the terminal transition** under the queue lock: one commit whose sole parent is the bound source and whose only change is this task's row in `docs/specs/<loop-id>/queue.md` (`[x]`, or `[F] — <first reason> (receipt <id>)`), validated as the only legal transition. Then `task-complete.py attach --receipt <receipt> --commit <terminal> --file docs/specs/<loop-id>/queue.md` records it separately from the source and moves the recovery ref to it.
+9. **Deliver** with `task-complete.py complete --receipt <receipt> --writers-stopped`, plus `--local-only` or, until the receipt records a mode, the manifest's `--mode auto|pr`, so a per-task `--mode` persists. Local-only keeps source, custody and the recovery ref with no remote effect. `auto`/`pr` publish the terminal commit under the completion contract; a pending or refused delivery keeps product acceptance, resources and a resume command. Where writer cessation cannot be observed, or a process still uses the tree, a merged delivery settles (`COMPLETE`) with its workspace, task ref and custody retained and reported under workspace cleanup; retained cleanup never blocks the queue. Failed products are never published. The receipt's `delivery` field checkpoints the latest outcome. A local chain is never turned into stacked PRs; publishing it requires integrated acceptance of the actual publication candidate.
+10. **Recover** from durable state only:
+
+    | Interrupted | Resume |
+    |---|---|
+    | During allocation | A receipt without `allocation: owned` is never adopted: its task waits, naming the recovery (remove its worktree and branch if present, delete the receipt directory, drain again), while independent work continues. |
+    | Inputs commit | A branch head equal to the expected inputs tree is adopted; anything else blocks. |
+    | During execution | Each attempt's start is recorded before its spawn and its exit after it. A start without an exit waits until task-complete observes no process using the worktree, then adopts the submission that executor wrote or runs the executor again; where writers cannot be observed (native Windows) the task becomes `[F] interrupted-unobservable` with its workspace retained, its dependents become prerequisite-blocked and independent work continues. Exactly-once execution is not promised. |
+    | During checks | Acceptance reruns; incomplete evidence stays unreferenced. |
+    | Accepted, before terminal commit | Only the missing transition is created. |
+    | Terminal committed, before attachment | The commit is validated and attached, also when attachment already moved the recovery ref; nothing reruns. |
+    | Terminal committed, before delivery | Only the missing delivery effects run. |
+    | After delivery, before cleanup | Owned cleanup resumes; the product verdict is unchanged. |
+
+11. **Report** to `<common Gitdir>/devlyn-loops/<loop-id>/drain-report.md` after every drain: per task the product result and reason, receipt, evidence custody and recovery ref, allocation base, accepted (or unaccepted) source, terminal commit, delivery status, PR URL and resume command, assumptions and unresolved questions, the retained worktree and branch, and workspace and scratch cleanup. Include the package's decisions and assumptions once, excluding the manifest and separately from executor assumptions; read the captured package when an add record exists, otherwise use the checkout, and report an unreadable package explicitly. Whole-loop acceptance is reported separately over the manifest's complete task set: every task needs receipt-backed acceptance, including the integration task's assembled-product check on the final frontier; a manifest task missing from the queue is reported as not yet run. `Bring into` names the command that brings the accepted frontier into the branch the loop was added on. For a local loop it is `git merge --ff <final frontier branch>` on that branch, which fast-forwards when it can and merges otherwise, so the commands of several local loops apply in either order. For `auto`/`pr`, once the frontier is delivered, it is `git merge --ff origin/<base>` on `<base>`: the anchor holds no loop commit or copy, so it fast-forwards after merge, squash and rebase delivery alike unless that branch has commits of its own, and merges then.
+
+## Executor exchange
+
+The packet (`<receipt dir>/packet.json`) carries everything a fresh executor needs:
+
+| Field | Meaning |
+|---|---|
+| `task`, `title`, `kind` | Queue identity and deliverable description. |
+| `worktree`, `branch`, `receipt`, `scratch` | Absolute owned worktree, branch, receipt and disposable build directory. |
+| `allocation_base`, `inputs_sha` | Allocation base and the committed-inputs commit. |
+| `contract`, `expected`, `meta` | `{path, sha256}` of the committed task contract, expected acceptance and meta-prompt. |
+| `requirements`, `review_requirements` | Requirement IDs and those needing review evidence. |
+| `shared_constraints` | The meta-prompt's `Constraints and exclusions`. |
+| `dependencies` | `{task, receipt, source_sha}` of each accepted prerequisite. |
+| `methodology` | `{path, sha256}` of the installed instruction files at the inputs commit. |
+| `delivery` | `local-only`, `auto` or `pr`. |
+| `evidence_dir`, `runner` | Where loop evidence lives (`<worktree>/.devlyn/loop`, ignored by Git) and the runner argv. |
+| `submission`, `obligations` | Where to write the submission, and the completion obligations. |
+
+Writable tool caches go under `scratch`, for example `npm_config_cache=<scratch>/npm`: Codex's sandbox keeps caches in HOME read-only.
+
+Run `runner` (`acceptance.py run --packet <packet>`) on the committed candidate before review. It prints `{"result": <path>, "passed": ..., "reasons": [...]}`; listing a wholly clean result (empty `reasons`) lets drain reuse its outcomes. Then write the submission:
+
+```json
+{
+  "schema_version": 1,
+  "task": "<identity>",
+  "source_sha": "<candidate commit on the owned branch>",
+  "runner_results": ["<worktree>/.devlyn/loop/runs/<n>/result.json"],
+  "reviews": ["<worktree>/.devlyn/reviews/<name>.json"],
+  "findings": [{"id": "F1", "disposition": "resolved", "evidence": "<what changed>"}],
+  "cleanup": "<residue removed, output retained>",
+  "handoff": "<state a successor needs>",
+  "assumptions": ["<each assumption, recorded once>"],
+  "blockers": [],
+  "summary": "<informational only>"
+}
+```
+
+`schema_version`, `task` and `source_sha` are required. A blocker `{"kind": "failed" | "needs-review" | "blocked-infrastructure", "detail": "<concrete question or cause>"}` records `[F]` with that reason and runs no checks; material ambiguity becomes `needs-review`, never a weakened acceptance. The summary is never evidence.
+
+## Review records
+
+Each `review_requirements` ID needs review evidence: a JSON record under `<worktree>/.devlyn/`, listed in the submission's `reviews`, in this shape:
+
+```json
+{
+  "schema_version": 1,
+  "kind": "devlyn-review",
+  "task": "<identity>",
+  "engine": "<engine>",
+  "model": "<exact model id>",
+  "source_sha": "<reviewed commit>",
+  "contract_sha256": "<packet.contract.sha256>",
+  "expected_sha256": "<packet.expected.sha256>",
+  "requirements": ["R3"],
+  "findings": [{"id": "F1", "binding": true, "disposition": "resolved", "requirement": "R3", "summary": "<finding>"}]
+}
+```
+
+A record counts only when it binds this task, the candidate source and both contract digests; any other well-formed record is reported under `ignored_reviews` (a source change invalidates earlier reviews). A listed review or runner record that is unreadable or not this shape fails acceptance with its path named; keys a review record or finding adds beyond this shape are ignored. The counted records' `requirements` must cover `review_requirements`. Each finding's `disposition` is `open`, `resolved` or `rejected` (`rejected` needs a `reason`); an open binding finding blocks acceptance. The loop requires no particular engine or number of reviewers.

package/config/skills/devlyn-ideate/references/package-format.md

@@ -0,0 +1,128 @@
+# Loop package format
+
+The formats `scripts/queue.py check|add` validate. One package per intent:
+
+```text
+docs/specs/<loop-id>/meta.md                         index: intent, shared constraints, manifest
+docs/specs/<loop-id>/<task-id>/spec.md               self-contained task contract
+docs/specs/<loop-id>/<task-id>/spec.expected.json    mechanical acceptance
+docs/specs/<loop-id>/queue.md                        the loop's queue rows, generated by add
+docs/specs/queue.md                                  legacy raw intents: read for materialize, never written
+```
+
+IDs match `[a-z0-9][a-z0-9-]{0,62}`. The queue identity `<loop-id>.<task-id>` never changes and is never reused; revised work gets new IDs. Headings below are fixed ASCII identifiers, like the verification sentinel; their content may be in any language.
+
+## meta.md
+
+Required `##` sections, each non-empty:
+
+| Heading | Content |
+|---|---|
+| `Intent` | Original intent and referenced source documents (input documents are preserved, not rewritten); intended user outcome. |
+| `Constraints and exclusions` | Shared requirements, prohibited changes, applicable delivery restrictions. Sent to every worker. |
+| `Tasks` | Ordered task index, dependency graph and decomposition rationale. No prescribed task count; one task is a valid loop. |
+| `Overall acceptance` | Every overall requirement assigned to a task; cross-task requirements assigned to the integration task's assembled-product check. |
+| `Execution policy` | Baseline, installed-methodology rule, autonomous question policy, delivery policy, stop conditions. |
+| `Decisions and assumptions` | Adopted decisions and defaults with reasons. No elicitation transcript. Put defaults affecting a task's observable behavior in that task's requirements and acceptance checks. |
+
+Exactly one fenced `json` block, the manifest. It is authoritative for order and dependencies and never carries status:
+
+```json
+{
+  "schema_version": 1,
+  "loop_id": "inventory",
+  "base_ref": "main",
+  "base_sha": "<exact 40- or 64-hex commit in this repository>",
+  "delivery": "auto",
+  "tasks": [
+    {"id": "t01", "spec": "t01/spec.md", "depends_on": []},
+    {"id": "t02", "spec": "t02/spec.md", "depends_on": ["t01"]}
+  ],
+  "integration_task_id": "t02"
+}
+```
+
+- Keys are exactly these; `loop_id` equals its directory; each `spec` is `<id>/spec.md`.
+- `delivery` is the inherited `auto` or `pr`, or an explicit `local-only` ([loop.md](loop.md) step 3).
+- `depends_on` names earlier tasks; unknown dependencies, cycles and forward references are rejected before execution.
+- `integration_task_id` is the last task and depends, directly or transitively, on every other task; its acceptance is the assembled-product check. Assign integration to the final substantive task when its substantive deliverable already depends, directly or transitively, on every other task. Otherwise preserve the substantive tasks' dependencies and append a check-only task that depends on all of them and verifies the assembled product without changing product source; it declares the full-diff guard `{"pattern": ".", "description": "No source changes", "severity": "disqualifier"}` in `forbidden_patterns`.
+
+## Task spec.md
+
+```yaml
+---
+id: t02
+loop_id: inventory
+title: Reservation behavior
+kind: feature
+review_requirements: [R3]
+---
+```
+
+`kind` (`feature`, `spike`, `prototype`) describes the deliverable and routes nothing. `review_requirements` lists requirement IDs that need semantic or source judgment (`[]` when none). An optional `complexity` is descriptive only. `status` is rejected: queue state lives in the queue and receipts.
+
+Required `##` sections, each non-empty:
+
+| Heading | Content |
+|---|---|
+| `Context and goal` | Outcome and why this task exists. |
+| `Requirements` | One list item per obligation with a stable ID: `- R1: <concrete acceptance obligation>`. |
+| `Scope and constraints` | Authorized implementation surface and the shared constraints that apply. |
+| `Out of scope` | Explicit exclusions. |
+| `Prerequisite inputs` | Predecessor interfaces, artifacts and assumptions this task relies on. |
+| `Verification` | Commands, assertions and requirement coverage. The line directly above the heading is `<!-- devlyn:verification -->`. |
+| `Deliverable and cleanup` | Result to retain, change-created residue to remove, permitted disposable output. |
+
+A worker receives this file and its task packet only, never the planning conversation or other task specs, so state everything it needs here.
+
+## spec.expected.json
+
+Schema: [expected.schema.json](../../_shared/expected.schema.json), parsed strictly (duplicate keys and non-finite numbers are rejected) by `_shared/expected-contract.py`. Loop tasks use:
+
+- `verification_commands`, each with exactly one of `argv` (preferred: no shell, portable to Windows) or `cmd` (shell); `exit_code` (default 0); `timeout_sec` (1-600, default 60); `stdout_contains` and `stdout_not_contains` (UTF-8 substrings of stdout plus stderr); and non-empty `contract_refs` naming this task's requirement IDs.
+- `required_files` and `forbidden_files` (literal Git paths), `forbidden_patterns` (regex over the task's own diff; `disqualifier` blocks acceptance, `warning` is recorded), `max_deps_added` (default 0; counts only the root `package.json`, so list other manifests in `forbidden_files`) and `pure_design`.
+
+Rejected otherwise:
+
+- Every requirement is covered by some command's `contract_refs`, by `review_requirements`, or both.
+- A runtime task has at least one command. `pure_design: true` has no commands and lists every requirement in `review_requirements`.
+- Phase-specific obligations (`process_evidence`, `required_risk_probe_requirements`, `tier_a_waivers`, `spec_output_files`) are rejected with an instruction to translate them into commands or review requirements without weakening them.
+
+Coverage proves that every obligation has evidence. Whether the checks express the owner's intent stays a planning and review responsibility.
+
+## Queue rows
+
+`add` generates the loop's `docs/specs/<loop-id>/queue.md` into its capture (Commands), never into the checkout: one row per task in manifest order, each line one blank line from the next, ending in one newline.
+
+```markdown
+- [ ] inventory.t01 [Stock model](docs/specs/inventory/t01/spec.md)
+
+- [x] inventory.t02 [Reservation behavior](docs/specs/inventory/t02/spec.md)
+
+- [F] inventory.t03 [Report](docs/specs/inventory/t03/spec.md) — blocked-prerequisite:inventory.t02 (receipt <id>)
+```
+
+- Links are repository-relative and exactly `docs/specs/<loop-id>/<task-id>/spec.md`; titles escape `\`, `[` and `]`. Packets and reports carry absolute paths.
+- `[ ]` is pending or active (the receipt tells which). `[x]` is an accepted product. `[F]` is failed, infrastructure-blocked, prerequisite-blocked or needs-review and ends with ` — <reason> (receipt <id>)`. Delivery state lives in receipts and the drain report; a pending PR never turns `[x]` into `[F]`.
+- The only legal transition turns one pending row into `[x]` or `[F]` with every other byte unchanged, so a terminal commit changes one line of its loop's file. Terminal rows are never reinterpreted or rerun. The blank lines let transitions of adjacent rows merge, and loops never share a file.
+- Identities are unique; equal titles are fine.
+- `docs/specs/queue.md` is the legacy queue. Its raw rows are intents: readable, never executed, never written (a row there that fully matches this grammar is ignored). `add --materialize <line>` plans one pending legacy row as a loop whose `## Intent` reproduces it verbatim (whitespace may reflow); that loop's queue file starts with `<!-- replaces docs/specs/queue.md row (occurrence <n>): <row> -->`, the row's exact text and its occurrence among equal rows, line endings aside. Every checkout, a fresh clone included, then shows the loop's rows in that row's place. A claim matching no row replaces nothing; a row two loops claim (two clones each materializing it) is hidden, neither loop taking its place, so it is never planned again.
+- Status and drain read the legacy rows in file order, each replaced row as its loop's rows; then the other recorded loops in add order, from their captures; then loops without a record here, as in a fresh clone, from the checkout's tracked queue files in loop-id order.
+
+## Commands
+
+```sh
+python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" check '<repo>/docs/specs/<loop-id>/meta.md'
+python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" add '<repo>/docs/specs/<loop-id>/meta.md' [--materialize <line>]
+```
+
+`check` validates without writing. Both print one JSON object; exit 1 is `BLOCKED` with a `reason`. `add` holds the queue lock and, in every delivery mode, makes no commit on the checked-out branch and changes no branch, index entry or tracked file:
+
+1. It resolves an add record for the loop id first, with or without the package files: the same package (every remaining copy equal to the capture, line endings aside, and the same `--materialize` row) reports `ADDED` and changes nothing; another package is refused as identity reuse. A capture ref a crash left without a record is captured again only when the checkout's package equals it; otherwise add reports that state.
+2. It validates the package and refuses a loop id that a committed `docs/specs/<loop-id>/queue.md` already uses, package files committed with different content, a detached HEAD, and a HEAD whose `CLAUDE.md` or `AGENTS.md` differs from this checkout's.
+3. It refuses package changes staged in the index, which it would leave behind; unstage them (`git restore --staged -- docs/specs/<loop-id>`) and add again.
+4. It builds a tree of the package files and the generated queue file in a temporary index, commits it, and points `refs/devlyn/captures/<loop-id>` at the commit, which keeps it from garbage collection.
+5. It publishes `<common Gitdir>/devlyn-loops/<loop-id>/added.json` atomically: the loop, its delivery, the capture ref, commit and tree, the checkout and branch it was added on, any materialize target and an add sequence.
+6. It removes the untracked package files equal to the capture, line endings aside. A changed copy is kept and a failed removal is reported as incomplete, both under `cleanup`; every later `add`, `status` and `drain` finishes the cleanup.
+
+The result names the capture: the package is held immutably at `refs/devlyn/captures/<loop-id>` (inspect it with `git show refs/devlyn/captures/<loop-id>:docs/specs/<loop-id>/meta.md`), and a revision needs a new loop id. While a loop has a record, validation, the active-contract check, scoped inputs, packets, reports and whole-loop acceptance read its capture; a loop without a record reads the checkout's tracked files.