devlyn-cli 3.0.1 → 3.1.0

package/config/skills/devlyn:queue/SKILL.md

@@ -31,11 +31,11 @@ Read `docs/specs/queue.md` (absent → report "queue empty — nothing staged" a
 
 - `add <intent text>` — append `- [ ] <intent>` to `docs/specs/queue.md` (create the file with its header if missing). If the intent came out of a conversation that already produced a spec, link it: `- [ ] (spec: docs/specs/<id>/spec.md) <intent>`.
 - `drain` — serial drain per the project-instructions contract. For each pending item, in order:
-  1. Spec it if unspecced (the queue entry is the user's go-ahead). Unattended assumptions may only take scope-narrowing, reversible, non-user-visible defaults; material ambiguity (user-visible behavior, data/state semantics, new files/scripts/flags, implementation surface) → mark `[F] needs-review: <question>`, commit that queue transition, and continue.
+  1. Allocate the owner's absent task branch per `../devlyn:resolve/references/task-completion.md` (linked worktree optional), then spec it if unspecced (the queue entry is the user's go-ahead). Unattended assumptions may only take scope-narrowing, reversible, non-user-visible defaults; material ambiguity (user-visible behavior, data/state semantics, new files/scripts/flags, implementation surface) → mark `[F] needs-review: <question>`, commit that queue transition, and continue.
   2. Commit the current queue-item delta and linked spec bundle as the scoped owner baseline, then run `/devlyn:resolve --spec <path>` hands-free.
      After every resolve invocation, run `python3 "$DEVLYN_SHARED_DIR/terminal-claim-check.py" .`; exit 79 marks `[F] FAILED-INCOMPLETE` from the predicate, never from the session self-report.
   3. Outer loop on the terminal verdict: PASS → mark `[x]`. Findings-backed verdicts (NEEDS_WORK, verify/build-gate exhaustion) → amend the spec, commit that scoped amendment, then re-run — at most 3 outer iterations. Infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts are not spec-amendable → mark `[F] <verdict>` immediately.
-  4. Commit each terminal `[x]` / `[F]` queue transition before advancing. A blocked item never halts the queue.
-  5. When the queue is drained (or the session must stop), emit the drain report: per-item verdict, every logged assumption, and the commit range produced.
+  4. Commit each terminal `[x]` / `[F]` queue transition before advancing. For successfully archived normal runs, invoke owner completion once after that declared queue-file-only commit; bind it separately from the verified source. Honor local-only/no-push. Failed products never publish. Retain PR/pending workspaces and use a separate owned branch from base for the next item; unavailable safe placement stops the drain with remaining items pending. A product-blocked item otherwise never halts the queue.
+  5. When the queue is drained (or the session must stop), emit the drain report: per-item product verdict and separate delivery status/URL/resume, every logged assumption, and the commit range produced.
 
 Strictly SERIAL — one `/devlyn:resolve` run at a time, never parallel. Never invent queue items, never reorder them, and never delete an item — only mark `[x]` / `[F]`.

package/config/skills/devlyn:resolve/SKILL.md

@@ -77,6 +77,8 @@ For every direct complete→spawn handoff, call `state-phase-write.py ... --phas
 
 ## PHASE 0: PARSE + CLASSIFY + ROUTE
 
+Outer-owner boundary: before normal task writes, follow `references/task-completion.md` for prospective task-branch ownership (linked worktree optional) and `references/outer-loop.md` for owner-input commits. Existing branches cannot be retroactively adopted. Verify-only does not allocate or publish; phase workers never own delivery.
+
 1. Run the bootstrap once with the exact tokenized `<pipeline_config>` and this orchestrator's default engine from `<engine_routing>`:
 
    ```bash
@@ -379,6 +381,8 @@ Open the `final_report` span through the predecessor's `state-phase-write.py --d
 
 6. **Archive** — invoke the deterministic script: `python3 "$DEVLYN_SHARED_DIR/archive_run.py"`. The script reads `run_id` from `.devlyn/pipeline.state.json`, moves the static per-run artifact set (`PER_RUN_PATTERNS` remains the single ownership list) plus every state-bound process-evidence manifest/raw stream into `.devlyn/runs/<run_id>/`, preserves evidence-relative layout, and rehashes bound bytes before any move. An unsafe/missing/altered evidence path or destination collision reports archive failure without changing the already-derived product verdict. It then best-effort prunes to the last 10 completed runs. Archive must run; running this step as deterministic-script-not-prose ensures the move actually happens (iter-0033a Smoke 3 caught a case where the agent claimed archive ran without moving the files).
 
+After successful normal-run archive, return to the outer owner for `references/task-completion.md`. A queue owner first commits its terminal queue transition, then completes once. Honor local-only/no-push; report delivery pending/failure separately from the archived product verdict. This is outside the phase graph.
+
 ## State management
 
 `.devlyn/pipeline.state.json` is the single authoritative verdict source. Branch on `state.phases.<name>.verdict` directly; never parse `.devlyn/*.findings.jsonl` for routing decisions. Schema and write protocol: `references/state-schema.md`. Every "State write: `phases.X.{...}`" note above describes the resulting shape only — the orchestrator writes it via initial `spawn`, atomic `transition` for direct handoffs, or terminal `complete`; re-entry preserves the prior lifecycle in `history[]` (`references/state-schema.md#write-protocol`). Phase workers never edit `pipeline.state.json` directly.

package/config/skills/devlyn:resolve/references/outer-loop.md

@@ -3,13 +3,21 @@
 A full `/devlyn:resolve` run starts only from committed owner inputs. Keep each
 commit scoped: no unrelated paths or queue-item changes.
 
-1. Before an item's first full run, commit the current queue-item delta, when
+1. Before task writes, the outer owner allocates an absent task branch per
+   [task completion](task-completion.md); linked worktree allocation is optional.
+   Never adopt a pre-existing task branch. Before an item's first full run, commit the current queue-item delta, when
    applicable, together with its linked spec bundle. For conversational work,
    commit the agreed spec bundle before the full run.
 2. When findings require an accepted verification amendment, commit only that
    linked spec-bundle amendment before rerunning the item.
 3. After a terminal result, commit the current item's `[x]` or `[F]` queue
    transition before starting the next pending item.
+4. After mandatory successful normal-run archive and any terminal queue commit,
+   the outer owner completes delivery once per [task completion](task-completion.md).
+   Bind the verified source and declared queue-only commit separately. Failed or
+   verify-only runs do not publish; local-only/no-push wins. Pending delivery
+   retains its workspace and never changes the product verdict.
 
 Drain strictly serially. Bootstrap and resolve never make these owner commits;
-the outer-loop driver owns them.
+the outer-loop driver owns them. Return queue custody before completion; never
+advance onto a retained pending task branch.

package/config/skills/devlyn:resolve/references/task-completion.md

@@ -0,0 +1,117 @@
+# Outer-owner task completion
+
+Completion belongs to the outer task owner after source acceptance. It does not
+add a phase or change product verdicts, finish-gate/archive authority or worker
+isolation. Explicit local-only/no-push instructions win. Otherwise delivery is
+authorized by the task scope; no additional approval ceremony is required.
+
+## Allocate before work
+
+Use the installed `_shared/task-complete.py` from the retained base checkout,
+before committing owner inputs or starting direct/full work:
+
+```sh
+python3 "$DEVLYN_SHARED_DIR/task-complete.py" allocate --repo . \
+  --task '<task identity>' --branch '<absent task branch>' \
+  --repository '<owner/repo>' --remote origin --base main
+```
+
+This creates and switches to a native task branch. Add `--worktree <absent path>`
+only when the owner explicitly chooses a linked checkout; allocation is optional
+for worktrees. Save the returned receipt path, outside the task checkout under
+the common Gitdir. Existing branches/trees cannot be adopted, even when their
+names look generated. An interrupted allocation stays blocked for inspection;
+do not delete its receipt and enroll the resulting branch. Pre-existing tasks
+remain owner-managed and cannot use this helper retroactively.
+
+## Accept a scoped commit
+
+Direct work: finish actual decisive checks and diff review, stage only the
+accepted paths and commit them. 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
+claim to have independently proved the assertions. No synthetic pipeline state
+or full resolve run is needed to deliver a direct task.
+
+For full resolve, use only its intended successfully archived normal run:
+
+```json
+{"kind":"pipeline","task":"<task identity>","source_sha":"<cleanup.post_sha>","run_id":"<exact archived run_id>"}
+```
+
+Terminal CLEAN alone is insufficient. Successful VERIFY and terminal precedence,
+the run-bound report/digest, clean finish summary and required evidence must
+agree. Failed, incomplete and verify-only runs are ineligible. Acceptance binds
+exact bytes and source before push; changed acceptance/evidence or subsequent
+product commits require a new accepted task, never implicit descendant approval.
+
+For a queue drain, resolve returns the acceptance/archive to the queue owner.
+Commit the terminal queue transition first, then add
+`"queue":{"commit":"<full terminal commit>","file":"docs/specs/queue.md"}` to
+acceptance. This commit must have only the verified source as parent and change
+exactly the declared queue file. The owner reviews the transition; the helper
+does not infer that arbitrary edits to that file are valid queue metadata.
+Complete once per item after that commit. Failed items are never published.
+
+## Deliver and resume
+
+```sh
+python3 "$DEVLYN_SHARED_DIR/task-complete.py" complete \
+  --receipt '<returned receipt.json>' --acceptance .devlyn/acceptance.json
+```
+
+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.
+
+`pr` pushes the exact accepted task ref and creates/reuses its exact repository,
+head and base PR, then reports `PR` with its URL and retains the checkout. `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. A repository that disallows
+merge commits fails visibly; disabled auto merge may also reject a pending
+request. Command success alone never proves merge.
+
+`PENDING` retains the workspace and reports a receipt-based resume command.
+`BLOCKED` includes the cause and the same retry path; repair the reported condition
+before retrying. Resume reobserves Git/PR state under a per-receipt lock, reuses
+the original acceptance, and performs only missing eligible effects. Delivery results remain separate from the
+immutable product result; do not rewrite an archived PASS for a delivery error.
+
+## Yield and retain recoverability
+
+After actual matching MERGED evidence, wait for the owner's actual children,
+stop/yield known task writers, and invoke completion with `--writers-stopped`.
+For a removable linked checkout, run from outside it using the installed helper
+outside that checkout. An OS process observation supplements the owner assertion;
+neither the receipt nor a scan guarantees exclusion of future writers. Unknown
+writers, inaccessible process state, caller cwd inside the tree, dirty/untracked
+files, changed refs/Gitdir/registration or locks retain the affected resources.
+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. Archive/check evidence is copied there
+before publication; removal rechecks it and source reachability through the merge.
+Ignored files in removable trees must be covered by that exact owned evidence
+manifest. Unknown ignored data requires explicit owner custody outside the helper;
+it never silently archives or deletes arbitrary user content. A partial/corrupt
+custody copy blocks cleanup and retains the original for repair.
+
+In-place completion retains the checkout and its ignored user data, switches
+safely to updated base, then compare-deletes only its exact owned task refs.
+Linked completion uses native non-force removal. 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 after removal uses the external receipt and evidence, so the
+removed checkout is not needed. Recovery refs/evidence have no automatic expiry.
+
+Queue drains remain serial. Record source verdict and delivery status separately;
+retain pending/PR workspaces. Before advancing, use a separate owned branch from
+base; do not put the next item's commits on a retained pending branch. If safe
+placement is unavailable, report remaining items pending and stop the drain.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — take intent to shipped, engineer-quality software hands-free with phase-gated pipelines and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {

package/scripts/lint-skills.sh

@@ -66,6 +66,7 @@ _shared/judge-output-parser.py
 _shared/collect-codex-findings.py
 _shared/verify-merge-findings.py
 _shared/archive_run.py
+_shared/task-complete.py
 _shared/state-phase-write.py
 _shared/terminal-claim-check.py
 _shared/resolve-stop-hook.py
@@ -79,6 +80,8 @@ devlyn:resolve/SKILL.md
 devlyn:queue/SKILL.md
 devlyn:engines/SKILL.md
 devlyn:resolve/references/state-schema.md
+devlyn:resolve/references/task-completion.md
+devlyn:resolve/references/outer-loop.md
 devlyn:resolve/references/free-form-mode.md
 devlyn:resolve/references/phases/plan.md
 devlyn:resolve/references/phases/probe-derive.md
@@ -401,7 +404,7 @@ check_skill_mirror_parity \
 
 # ---------------------------------------------------------------------------
 # 6b. VERIFY merge verdict binding self-test.
-for helper in role-config judge-role-evidence; do
+for helper in role-config judge-role-evidence task-complete; do
   if python3 "config/skills/_shared/$helper.py" --self-test >/dev/null 2>&1; then
     ok "$helper.py self-test passed"
   else