devlyn-cli 3.0.0 → 3.1.0

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

@@ -109,7 +109,7 @@ Structural lint (inline check, no script needed):
 
 After lint passes:
 1. Write `<spec-dir>/<id>-<slug>/spec.md` (the spec).
-2. Generate `<spec-dir>/<id>-<slug>/spec.expected.json` from the spec's `## Verification` block + any `forbidden_patterns` / `required_files` / `forbidden_files` / `max_deps_added` the conversation surfaced.
+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 verification carrier shape, supported `complexity` frontmatter, and any present actionable solo-headroom hypothesis; if the spec uses a legacy inline `## Verification` JSON carrier, any solo-headroom hypothesis command must match that carrier's `verification_commands[].cmd`. If exit 2, fix the carrier/frontmatter/hypothesis 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 and any present actionable solo-headroom hypothesis; if the spec has a solo-headroom hypothesis, its observable command must match `spec.expected.json.verification_commands[].cmd`. If exit 2, fix the JSON/frontmatter/hypothesis and re-run.
 5. Print: `spec ready — /devlyn:resolve --spec <spec-path>`.
@@ -133,7 +133,7 @@ Prompt body: `references/from-spec-mode.md`.
 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 (best-effort from `## Verification` block).
+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. If the source is a pair-evidence candidate without an actionable solo-headroom hypothesis, the announcement must say `pair-evidence not ready` instead of implying measurement readiness.

package/config/skills/devlyn:ideate/references/spec-template.md

@@ -95,11 +95,11 @@ Schema: `_shared/expected.schema.json`. Required when Requirements have observab
 python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check-expected <expected-path>
 ```
 
-Generated by ideate from the conversation:
-- `verification_commands` ← parsed from `## Verification` body + any commands the conversation surfaced.
-- `forbidden_patterns` ← from Constraints that mention specific anti-patterns ("no silent catches", "no any types").
-- `required_files` / `forbidden_files` ← from Out of Scope and Requirements.
-- `max_deps_added` ← from Constraints (default 0 unless the spec licenses a new dep).
+Map mechanically decidable rules from both Requirements and Constraints into the existing carriers. Validate each new guard with a violating control that fails and an allowed control that passes, preserving permitted pre-existing occurrences:
+- `verification_commands` ← `## Verification` + commands the conversation surfaced. For semantic annotation or exception-handling rules, use a suitable syntax-aware/executable check, preferring existing checks; explicitly retain uncovered semantics as source-review obligations.
+- `forbidden_patterns` ← literal syntax constraints only; regex does not prove semantics. It scans the whole file-filtered diff, including context, deletions and headers; additions-only guards must exclude those lines.
+- `required_files` / `forbidden_files` ← file requirements and exclusions in Requirements, Constraints and Out of Scope.
+- `max_deps_added` ← dependency limits in Requirements or Constraints (default 0 unless the spec licenses a new dep).
 - `required_risk_probe_requirements` ← for specs where a Requirement combines ordering/priority, rollback, idempotency, auth/signature, concurrency, atomic-batch, or exact output shape, declare the risk categories PHASE 1.5 risk-probe derivation must cover directly, e.g. `[{"tag": "rollback_state", "derived_from": "<exact ## Verification bullet>"}]`. This replaces guessing the required categories from prose — declare them explicitly so the check works in any language. `tag` must be one of the risk-probe tags in `_shared/spec-verify-check.py:RISK_PROBE_TAGS`; `derived_from` must be an exact substring of `## Verification`. Omit entirely when the spec has no ordering/rollback/idempotency/auth/concurrency/atomic-batch/exact-shape risk.
 
 ## Quality bar (lint enforces structurally; ideate enforces substantively)

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

@@ -1,6 +1,6 @@
 ---
 name: devlyn:resolve
-description: Hands-free pipeline for any coding task — bug fix, feature, refactor, debug, modify, PR review. Free-form goal or formal spec input. Plan → Implement → Build-gate → Cleanup → Verify (fresh subagent, findings-only). Mechanical-first verification; Verify dual-judge is default-when-available. Use when the user says "resolve this", "fix this", "implement this", "refactor this", "debug this", "review this PR", or wants hands-off completion.
+description: Hands-free full pipeline for explicit resolve requests, formal specs, queue drains, material ambiguity, subsystem/design work, security/auth/payment/persistence/concurrency/public-API-contract changes, or no decisive acceptance check. Free-form goal or formal spec input. Plan → Implement → Build-gate → Cleanup → Verify (fresh subagent, findings-only). Mechanical-first verification; Verify dual-judge is default-when-available. Clear, local, reversible, low-risk conversational edits with decisive checks default to direct execution; explicit small resolve keeps the full workflow.
 ---
 
 Orchestrator for the 2-skill harness pipeline. One fresh worker per phase; file-based handoff via `.devlyn/pipeline.state.json`. VERIFY spawns a fresh-context worker so independence is structural — not advisory.
@@ -63,7 +63,7 @@ Each phase routes to an engine and prepends the per-engine adapter header from `
 Three input shapes:
 
 1. **Free-form**: `/devlyn:resolve "fix the login bug"` (inline goal) or `/devlyn:resolve --goal-file <path>` (goal text read from a file — the devlynd `ResolveAdapter` launcher path, injection-safe). PHASE 0 runs the complexity classifier and either proceeds with an internal mini-spec (trivial), drafts focused questions for in-prompt resolution (medium), or synthesizes a best-effort spec with a logged `## Assumptions` block (large; zero-scope-signal goals halt). No mid-pipeline prompts in any branch.
-2. **Spec**: `/devlyn:resolve --spec docs/roadmap/phase-N/X.md`. Spec is read-only. Stage verification commands from sibling `spec.expected.json`; if absent, use the legacy `## Verification` JSON block.
+2. **Spec**: `/devlyn:resolve --spec docs/roadmap/phase-N/X.md`. Supplied specs and expected files are read-only inside resolve. Stage verification commands from sibling `spec.expected.json`; if absent, use the legacy `## Verification` JSON block.
 3. **Verify-only**: `/devlyn:resolve --verify-only <diff-or-PR-ref> --spec <path>`. Skips PHASE 1-4. Runs PHASE 5 (VERIFY) on the supplied diff against the spec.
 </modes>
 
@@ -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/free-form-mode.md

@@ -75,6 +75,7 @@ When the rules are silent (rare — pathological goal text), default to `medium`
 The internal mini-spec written for trivial / medium / large-assumptions paths must satisfy:
 
 - `## Requirements` non-empty, each bullet testable (CLI command, test command, observable file change).
+- For generated verification carriers, follow `../../devlyn:ideate/references/spec-template.md` § "Sibling file: `spec.expected.json`" for constraint coverage, diff scope and guard controls.
 - `## Verification` is preceded by a `<!-- devlyn:verification -->` sentinel on its own line directly above the heading — the machine locator `spec-verify-check.py` uses; the heading text itself is decorative and may be any language. `## Verification` non-empty if the goal implies any runnable acceptance check. Empty Verification is allowed only when all Requirements are pure-design (e.g. "follow existing pattern X").
 - If a free-form goal includes pair-evidence intent and already includes an actionable solo-headroom hypothesis, preserve that literal hypothesis in `.devlyn/criteria.generated.md` unchanged enough for VERIFY to detect `solo-headroom hypothesis`, `solo_claude`, `miss`, and the backticked observable command line that itself contains `miss`, emit the canonical `spec.solo_headroom_hypothesis` pair trigger reason, and satisfy regenerated-evidence checks such as `benchmark audit --require-hypothesis-trigger`.
 - If a free-form goal includes unmeasured pair-candidate intent and already includes solo ceiling avoidance, preserve that literal note in `.devlyn/criteria.generated.md` unchanged enough for reviewers to see `solo ceiling avoidance`, `solo_claude`, and the concrete difference from rejected or solo-saturated controls such as `S2`-`S6`.

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.0",
+  "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