devlyn-cli 4.2.26 → 4.3.0

package/config/skills/_shared/harness-store.py

@@ -0,0 +1,201 @@
+"""Release identity and queue resource checks. Readers never write or create locks.
+
+The release verifier is CLI-1's bin/release.js, not a second manifest verifier.
+A Codex projection has .devlyn-harness-projection.json at its plugin root:
+{schemaVersion: 1, release: ReleaseRef, source: "native/codex/plugins/devlyn"}.
+Its complete regular-file tree (except that marker) must match that release subtree.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+
+PROJECTION = ".devlyn-harness-projection.json"
+CODEX_SOURCE = "native/codex/plugins/devlyn"
+
+
+class HarnessError(Exception):
+    pass
+
+
+def require(condition, message):
+    if not condition:
+        raise HarnessError(message)
+
+
+def read_json(path):
+    try:
+        return json.loads(Path(path).read_bytes())
+    except (OSError, ValueError) as exc:
+        raise HarnessError(f"{path}: {exc}") from exc
+
+
+def file_identity(path):
+    path = Path(path)
+    info = path.lstat()
+    require(path.is_file() and not path.is_symlink() and info.st_nlink == 1, f"not a regular resource: {path}")
+    return {"path": str(path), "sha256": hashlib.sha256(path.read_bytes()).hexdigest()}
+
+
+def release_ref(value):
+    require(isinstance(value, dict) and set(value) == {"package", "version", "digest", "root"}
+            and value["package"] == "devlyn-cli"
+            and all(isinstance(value[k], str) and value[k] and "\0" not in value[k] for k in ("version", "digest", "root"))
+            and re.fullmatch(r"[a-f0-9]{64}", value["digest"]) and Path(value["root"]).is_absolute(), "malformed release reference")
+    return value
+
+
+def verify_release(root):
+    root = Path(root)
+    script = "const r=require(process.argv[1]);r.runJson(()=>r.verifyRelease(process.argv[2]));"
+    result = subprocess.run(["node", "-e", script, str(root / "bin/release.js"), str(root)], capture_output=True, text=True, encoding="utf-8")
+    require(result.returncode == 0, f"release verification failed: {root}: {result.stderr.strip()}")
+    try:
+        release = release_ref(json.loads(result.stdout)["data"]["release"])
+    except (KeyError, ValueError, TypeError) as exc:
+        raise HarnessError(f"invalid release verifier result: {root}: {exc}") from exc
+    manifest = read_json(root / "release.json")
+    defaults = file_identity(root / manifest["principles"]["defaults"])
+    return {"schemaVersion": 1, "release": release, "defaults": defaults}
+
+
+def walk_error(error):
+    raise error  # os.walk otherwise silently skips unreadable projection directories.
+
+
+def resolve(skills):
+    """Resolve only this invoking skill's real ancestry; never search another install."""
+    skill = (Path(skills) / "devlyn-ideate").resolve()
+    for parent in (skill, *skill.parents):
+        marker = parent / PROJECTION
+        if marker.exists() or marker.is_symlink():
+            file_identity(marker)
+            projection = read_json(marker)
+            require(isinstance(projection, dict) and set(projection) == {"schemaVersion", "release", "source"}
+                    and type(projection["schemaVersion"]) is int and projection["schemaVersion"] == 1
+                    and projection["source"] == CODEX_SOURCE, f"malformed projection: {marker}")
+            ref = release_ref(projection["release"])
+            binding = verify_release(ref["root"])
+            require(binding["release"] == ref, f"projection release changed: {marker}")
+            source = Path(ref["root"]) / CODEX_SOURCE
+            require(skill == parent / "skills/devlyn-ideate", f"unexpected projection skill: {skill}")
+            expected = {p.relative_to(source) for p in source.rglob("*") if p.is_file()}
+            actual = set()
+            for directory, dirs, files in os.walk(parent, onerror=walk_error):
+                for name in dirs:
+                    require(not (Path(directory) / name).is_symlink(), f"projection directory link: {directory}/{name}")
+                for name in files:
+                    file = Path(directory) / name
+                    if file == marker:
+                        continue
+                    rel = file.relative_to(parent)
+                    actual.add(rel)
+                    require(rel in expected and file_identity(file)["sha256"] == file_identity(source / rel)["sha256"]
+                            and (os.name == "nt" or bool(file.stat().st_mode & 0o111) == bool((source / rel).stat().st_mode & 0o111)),
+                            f"projection resource changed: {file}")
+            require(actual == expected, f"projection file list changed: {parent}")
+            return binding
+        manifest = parent / "release.json"
+        if (manifest.exists() or manifest.is_symlink()) and skill in [parent / p / "devlyn-ideate" for p in
+                ("config/skills", "native/claude/skills", CODEX_SOURCE + "/skills")]:
+            return verify_release(parent)
+    return None
+
+
+def read_binding(common):
+    path = Path(common) / "devlyn-loops/harness.json"
+    if not path.exists() and not path.is_symlink():
+        return None
+    file_identity(path)
+    binding = read_json(path)
+    require(isinstance(binding, dict) and set(binding) == {"schemaVersion", "release", "defaults"}
+            and type(binding["schemaVersion"]) is int and binding["schemaVersion"] == 1, f"incompatible queue binding: {path}")
+    release_ref(binding["release"])
+    resource(binding["defaults"])
+    return binding
+
+
+def resource(value):
+    require(isinstance(value, dict) and set(value) == {"path", "sha256"}
+            and isinstance(value["path"], str) and "\0" not in value["path"] and Path(value["path"]).is_absolute()
+            and isinstance(value["sha256"], str) and re.fullmatch(r"[a-f0-9]{64}", value["sha256"]), "malformed resource binding")
+
+
+def recovery_argv(binding, argv):
+    return [sys.executable, str(Path(binding["release"]["root"]) / "config/skills/devlyn-ideate/scripts/queue.py"), *argv]
+
+
+def check_binding(binding, invoking):
+    if binding is None:
+        return
+    require(invoking is not None and binding["release"] == invoking["release"], "queue-release-mismatch")
+    require(binding == invoking, "queue defaults changed; restore the bound release")
+
+
+def packet_schema(packet):
+    require(isinstance(packet, dict), "task packet must be an object")
+    version = packet.get("schema_version", 1)
+    require(type(version) is int and version in (1, 2), f"incompatible task packet version: {version!r}")
+    if version == 1:
+        return
+    require("harness" in packet and isinstance(packet.get("methodology"), dict), "malformed packet v2 harness/methodology")
+    methodology = packet["methodology"]
+    require(set(methodology) == {"defaults", "projectInstructions"} and isinstance(methodology["projectInstructions"], list),
+            "malformed packet v2 methodology")
+    for entry in methodology["projectInstructions"]:
+        resource(entry)
+    if packet["harness"] is None:
+        defaults = methodology["defaults"]
+        require(packet.get("workerPrompt") is None and (defaults is None or (isinstance(defaults, dict) and defaults.get("source") == "skill")),
+                "legacy packet has release resources")
+        if defaults is not None:
+            resource({k: v for k, v in defaults.items() if k != "source"})
+        return
+    release_ref(packet["harness"])
+    defaults = methodology["defaults"]
+    require(isinstance(defaults, dict) and defaults.get("source") == "release", "packet has no verified release defaults source")
+    resource({k: v for k, v in defaults.items() if k != "source"})
+    resource(packet.get("workerPrompt"))
+
+
+def verify_packet(packet, path, skills):
+    packet_schema(packet)
+    if packet.get("schema_version", 1) == 1:
+        return  # Preserve v1 execution without upgrading its resources.
+    receipt = packet.get("receipt")
+    require(isinstance(receipt, str) and "\0" not in receipt and Path(receipt).is_absolute()
+            and Path(receipt).name == "receipt.json" and Path(receipt).parent.parent.name == "devlyn-completion"
+            and Path(receipt) == Path(path).with_name("receipt.json"),
+            "malformed packet receipt path")
+    binding = read_binding(Path(receipt).parent.parent.parent)
+    if packet["harness"] is None:
+        require(binding is None, "bound task packet has no harness/defaults source")
+        # An unbound installation's own defaults change with its normal updates: never gate acceptance or delivery on
+        # their bytes (queue.py checks only their presence, before a spawn).
+        return
+    require(binding is not None, "packet queue binding is missing; restore harness.json")
+    invoking = resolve(skills)
+    ref = packet["harness"]
+    require(invoking is not None and invoking["release"] == ref,
+            f"packet-release-mismatch; use {Path(ref['root']) / 'config/skills/devlyn-ideate/scripts/queue.py'}")
+    check_binding(binding, invoking)
+    defaults = {"source": "release", **binding["defaults"]}
+    require(packet["methodology"]["defaults"] == defaults, "packet defaults differ from queue binding")
+    expected_runner = [str(Path(ref["root"]) / "config/skills/devlyn-ideate/scripts/acceptance.py"),
+                       "run", "--packet", str(path)]
+    require(isinstance(packet.get("runner"), list) and packet["runner"][1:] == expected_runner, "packet runner differs from bound release")
+    prompt = packet["workerPrompt"]
+    require(prompt["path"] == str(Path(path).parent / "worker-prompt.md") and file_identity(prompt["path"]) == prompt,
+            "worker prompt changed or missing; restore the bound resource")
+    for entry in packet["methodology"]["projectInstructions"]:
+        name = Path(entry["path"]).name
+        require(name in ("CLAUDE.md", "AGENTS.md") and entry["path"] == str(Path(packet["worktree"]) / name),
+                "project instruction path escapes packet worktree")
+        committed = subprocess.run(["git", "-C", packet["worktree"], "cat-file", "blob", f"{packet['inputs_sha']}:{name}"], capture_output=True)
+        require(committed.returncode == 0 and hashlib.sha256(committed.stdout).hexdigest() == entry["sha256"],
+                f"project instruction differs from inputs commit: {name}")

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

@@ -94,10 +94,14 @@ A removed flag stops with its instruction and selects no other behavior.
 
 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. 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>`.
 
+Release-backed queues retain their verified release in `<git-common-dir>/devlyn-loops/harness.json` until all tasks, recovery and delivery settle. A different release refuses with the exact recovery argv; use it. Existing unfinished unbound queues and standalone installations remain legacy.
+
 ## status
 
 Run `python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" status --repo .` and report its counts, `next`, `blockers`, `warnings`, pending deliveries with their resume commands and any `cleanup` entry.
 
+For read-only consumers, `python3 "$DEVLYN_SKILL_DIR/scripts/queue.py" inspect --repo . --json` returns the status summary plus `binding` and `compatibility`, without cleanup, locks or writes.
+
 ## drain
 
 `status`, `add` and `drain` write the repository's Git directory, and auto/pr delivery needs network access, so a sandboxed host runs them with escalation or full access.
@@ -112,7 +116,7 @@ Follow [loop.md](references/loop.md). The executor is the configured route, the
 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:
 
 ```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.
+Execute the devlyn loop task packet {packet}: read its workerPrompt when present; read methodology.defaults.path when named and apply those verified defaults, with explicit user and native owner/project instructions taking precedence; 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. Use the literal DEVLYN_SKILL_DIR and DEVLYN_SHARED_DIR bindings in workerPrompt when present; otherwise set DEVLYN_SKILL_DIR=<DEVLYN_SKILL_DIR> and DEVLYN_SHARED_DIR=<DEVLYN_SHARED_DIR> from these literal values. Never use inherited environment values. Never push, open a pull request or merge: the drain delivers.
 ```
 
 ```sh

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

@@ -28,7 +28,7 @@ The host supplies the executor and maps its configured engine to the argv; the l
    - 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. A refresh failure waits for restored remote access or the base ref. A missing merge before allocation waits for that merge to be restored on the remote base; an allocated baseline is immutable and needs a new loop or verified recovery of a never-executed allocation.
 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 keeps its allocation, packet and durable start/not-started log, waits for executable, permissions or workspace repair, and retries on the next drain.
+5. **Exchange one packet.** Verify the bound release, defaults, packet and worker prompt before execution or recovery; changed or missing resources refuse dispatch. 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 keeps its allocation, packet and durable start/not-started log, waits for executable, permissions or workspace repair, and retries on the next 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.
@@ -53,6 +53,14 @@ Expected task-local operational failures leave the selected task waiting with `<
 
 Package cleanup, parent pruning and report failures appear as diagnostics under `cleanup`, with retained paths and repair guidance; they do not change product acceptance or completed delivery. The next drain retries them.
 
+## Release binding and read-only consumers
+
+`<git-common-dir>/devlyn-loops/harness.json` is authoritative across linked worktrees: `{schemaVersion: 1, release: {package, version, digest, root}, defaults: {path, sha256}}`. Paths are absolute and hashes cover exact bytes. The queue lock covers binding before the first capture. An interrupted first add, unfinished tasks, recovery conflicts and pending delivery retain it; settlement removes it. A different release refuses with `recovery argv` as a JSON argv array, preserving the caller’s arguments. No caller substitutes another implementation.
+
+`queue.py inspect --repo <dir> --json` reads without cleanup, locks or writes. It returns the status summary plus `binding` (null for legacy) and `compatibility`: `compatible`, `legacy`, `reasons`, `recoveryArgv`, `taskPacket` ranges and `queueBinding` ranges. Incompatible or unreadable state is reported, never migrated. Apps should use this reader instead of `status`, which still reconciles cleanup. For a mismatch, `recoveryArgv` names the bound queue’s inspect invocation; use the same bound queue entry point for authorized add/drain operations.
+
+Codex projection writers place `.devlyn-harness-projection.json` at the copied plugin root, beside `skills` and `.codex-plugin`: `{schemaVersion: 1, release: <ReleaseRef>, source: "native/codex/plugins/devlyn"}`. The reader verifies the named release and every projected file’s bytes/mode against that subtree (excluding only the marker). Symlinked skill invocations resolve through their real path. Standalone installs and existing unfinished unbound queues retain legacy behavior; new legacy packets use v2 with a null release, and their `defaults` name the invoking installation's own `_shared/runtime-principles.md` (`source: "skill"`). No engine applicability is inferred from instruction filenames: bound queues use verified release defaults with native instructions taking precedence. Worker and runner paths point to the bound release, independent of a projection cache’s lifetime.
+
 ## Executor exchange
 
 The packet (`<receipt dir>/packet.json`) carries everything a fresh executor needs:
@@ -66,7 +74,9 @@ The packet (`<receipt dir>/packet.json`) carries everything a fresh executor nee
 | `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. |
+| `schema_version`, `harness` | New packets use version 2 and the bound release reference, or null for legacy unbound queues. Existing v1 packets execute unchanged. |
+| `methodology` | `projectInstructions`: `{path, sha256}` of instruction bytes at the inputs commit. `defaults`: `{source: "release", path, sha256}` from the verified binding; for an unbound queue `{source: "skill", path, sha256}` of the installation's own `_shared/runtime-principles.md`. A task whose executor would get no principles at all (no defaults and no committed CLAUDE.md/AGENTS.md) waits with that reason instead of running. Read the named defaults; explicit user and native owner/project instructions take precedence. No native engine applicability is inferred from filenames. |
+| `workerPrompt` | `{path, sha256}` of the task’s worker instructions, or null for legacy unbound queues. Read it before working. |
 | `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. |

package/config/skills/devlyn-ideate/references/plan-add.md

@@ -0,0 +1,12 @@
+# Planning and capture only
+
+This reference grants plan and add operations only. Never drain, implement, run an executor or deliver code from this planning session.
+
+Resolve this reference’s actual containing skill directory (the parent of `references`), resolving symlinks; bind it as `DEVLYN_SKILL_DIR`. Resolve its sibling `_shared` as `DEVLYN_SHARED_DIR`. Verify the loaded files; missing or conflicting source identity is `BLOCKED:skill-source-unresolved`. Never substitute another installation or inherited environment values.
+
+1. Inspect project facts and follow [elicitation.md](elicitation.md). Ask only when the unresolved answer changes authorized behavior, scope, data semantics, acceptance or delivery. Existing authorization remains effective. Under autonomous planning, use conventional, reversible defaults for ordinary details and record each assumption; material ambiguity stops affected work as needs-review with a concrete question. Independent authorized planning may continue.
+2. Write `docs/specs/<loop-id>/meta.md` and self-contained task contracts per [package-format.md](package-format.md). Preserve an input document unchanged and carry every substantive requirement into the package. Use this execution policy in the package: for ordinary details within authorized scope, follow established project conventions, otherwise the narrowest literal or conventional reading consistent with the request; choices must be low-consequence and reversible, recorded with their reasons. Material ambiguity means competing intended outcomes, unresolved persistent data/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. Set delivery from explicit restrictions or the project completion policy; without one GitHub origin, record local-only as an assumption, or ask when the user explicitly requested a PR/merge.
+3. Run `python3 "<DEVLYN_SKILL_DIR>/scripts/queue.py" check '<absolute meta.md>'` and repair until `VALID`. Plan stops here: report the path, tasks, dependencies and assumptions.
+4. When add is authorized, run `python3 "<DEVLYN_SKILL_DIR>/scripts/queue.py" add '<absolute meta.md>'`. It alone writes queue state, captures without committing on the checked-out branch and removes matching untracked package copies. Report the capture ref, its `git show` command and cleanup diagnostics. Revisions need a new loop id. A legacy pending row is materialized with `--materialize <line>` and its verbatim intent in the package.
+
+Report capture and stop. A separate authorized execution session owns drain.

package/config/skills/devlyn-ideate/scripts/acceptance.py

@@ -89,6 +89,11 @@ def load_packet(path):
     packet = read_json(path)
     if not isinstance(packet, dict) or PACKET_KEYS - set(packet):
         raise AcceptanceError(f"{path}: task packet lacks {sorted(PACKET_KEYS - set(packet if isinstance(packet, dict) else {}))}")
+    helper = shared("harness-store")
+    try:
+        helper["verify_packet"](packet, path, SKILLS)
+    except (helper["HarnessError"], OSError) as exc:
+        raise AcceptanceError(str(exc)) from exc
     return packet
 
 

package/config/skills/devlyn-ideate/scripts/queue.py

@@ -170,6 +170,58 @@ def lock(common, name, *, blocking):
         yield
 
 
+def harness_call(name, *args):
+    helper = shared("harness-store")
+    try:
+        return helper[name](*args)
+    except helper["HarnessError"] as exc:
+        raise LoopError(str(exc)) from exc
+
+
+def enforce_binding(common, anchor=None):
+    binding = harness_call("read_binding", common)
+    try:
+        harness_call("check_binding", binding, harness_call("resolve", SKILLS))
+    except (LoopError, OSError) as exc:
+        # A queue that settled outside queue.py (its last delivery finished through task-complete.py) keeps a binding no
+        # work needs: another release drops it instead of refusing. Callers outside the queue lock pass `anchor`.
+        if binding and anchor is not None and release_settled_binding(anchor, common, interrupted_add=True):
+            return enforce_binding(common)
+        if binding:
+            argv = harness_call("recovery_argv", binding, sys.argv[1:])
+            raise LoopError(f"{exc}; recovery argv: {json.dumps(argv, ensure_ascii=False)}") from exc
+        raise
+    return binding
+
+
+def unfinished(v):
+    if v["unreadable"] or counts(v)["legacy_pending"]:
+        return True
+    for state in v["states"].values():
+        receipt = state["receipt"]
+        # A blocked task waits on a failed prerequisite for good, as drain counts it: it holds no binding.
+        if state.get("invalid") or state["kind"] in {"pending", "active"} or receipt and (
+                not receipt.get("queue") or receipt.get("delivery") not in SETTLED):
+            return True
+    # An interrupted capture with no add record is still resumable work.
+    refs = git(v["anchor"], "for-each-ref", "--format=%(refname)", CAPTURES).splitlines()
+    return any(ref.removeprefix(CAPTURES) not in v["records"] for ref in refs)
+
+
+def release_settled_binding(anchor, common, *, interrupted_add=False):
+    """Remove the binding once nothing needs it. The bound release keeps one from an interrupted first add (no record
+    yet) so its retry rebinds the same identity; another release (`interrupted_add`) drops that too, since a binding
+    published before its capture captured nothing. Returns whether it was removed."""
+    with lock(common, "queue.lock", blocking=True):
+        if not harness_call("read_binding", common):
+            return False
+        v = view(anchor, common, pure=True)
+        if unfinished(v) or not (v["records"] or interrupted_add):
+            return False
+        (common / "devlyn-loops/harness.json").unlink()
+        return True
+
+
 def sections(text, path):
     found, current, fence = {}, None, False
     for line in text.split("\n"):
@@ -686,6 +738,7 @@ def derive_state(anchor, common, row, claims, rev):
     if packet.exists():
         bound = read_json(packet)
         require(isinstance(bound, dict) and not acceptance()["PACKET_KEYS"] - bound.keys(), f"{packet}: malformed task packet")
+        harness_call("packet_schema", bound)
         require(bound["worktree"] == receipt["worktree"] and bound["task"] == identity and bound["branch"] == receipt["branch"]
                 and bound["allocation_base"] == receipt["baseline"],
                 f"{packet}: conflicting packet ownership")
@@ -713,11 +766,13 @@ def derive_state(anchor, common, row, claims, rev):
     return state
 
 
-def view(anchor, common, local_only=False):
+def view(anchor, common, local_only=False, *, pure=False):
     """Reconcile the queue with every receipt and recovery ref before anything is selected."""
-    with lock(common, "queue.lock", blocking=True):
+    with contextlib.nullcontext() if pure else lock(common, "queue.lock", blocking=True):
+        if not pure:
+            enforce_binding(common)
         recorded = records(common)
-        cleanup = clean(common, recorded)
+        cleanup = [] if pure else clean(common, recorded)
         rows = queue_view(anchor, recorded)
     claims, unreadable, damaged = {}, [], {}
     canonical = {receipt_path(common, row["identity"]): row["identity"] for row in rows if row["identity"]}
@@ -737,7 +792,7 @@ def view(anchor, common, local_only=False):
             if identity := canonical.get(path):
                 damaged[identity] = str(exc)
     v = {"anchor": anchor, "common": common, "rows": rows, "records": recorded, "packages": {}, "manifests": {}, "states": {},
-         "unreadable": unreadable, "cleanup": cleanup, "local_only": local_only}
+         "unreadable": unreadable, "cleanup": cleanup, "local_only": local_only, "pure": pure}
     errors = {}
     for row in v["rows"]:
         if row["identity"]:
@@ -902,7 +957,7 @@ def local_start(v, loop):
             return None, f"{branch}, the branch {loop} was added on, {where}; bring {base} into {branch}, or plan the work as a new loop"
         if drift := package_drift(v, loop, start, branch):
             return start, drift
-    if drift := instruction_drift(v["anchor"], start):
+    if drift := instruction_drift(v["anchor"], start, pure=v.get("pure", False)):
         return start, f"the installed instructions ({drift}) in this checkout differ from those in its start commit {start}, so it would run without them; {remedy}"
     return start, None
 
@@ -992,12 +1047,14 @@ def package_drift(v, loop, start, where):
             "bytes") if files else None
 
 
-def instruction_drift(anchor, rev):
+def instruction_drift(anchor, rev, *, pure=False):
     """The installed instruction files whose content at `rev` differs from the anchor checkout's (both absent is equal): a
     task starting at `rev` would run without them. Git compares them as `git status` does: a link by its target, line endings
     under the checkout's conversion rules, and an untracked or ignored file as one still to commit."""
     names = ("CLAUDE.md", "AGENTS.md")
-    differ = git(anchor, "diff", "--name-only", "--no-renames", rev, "--", *names).split("\n")
+    # Git's porcelain diff refreshes the index independently of GIT_OPTIONAL_LOCKS.
+    options = ("-c", "diff.autoRefreshIndex=false") if pure else ()
+    differ = git(anchor, *options, "diff", "--name-only", "--no-renames", rev, "--", *names).split("\n")
     differ += git(anchor, "ls-files", "--others", "--", *names).split("\n")
     return ", ".join(name for name in names if name in differ)
 
@@ -1088,7 +1145,7 @@ def ensure_packet(v, row, path, receipt):
         return {"path": str(worktree / rel), "sha256": hashlib.sha256(show(worktree, inputs, rel)).hexdigest()}
 
     packet = {
-        "schema_version": 1, "task": identity, "title": spec["title"], "kind": spec["kind"],
+        "schema_version": 2, "task": identity, "title": spec["title"], "kind": spec["kind"],
         "worktree": str(worktree), "branch": branch, "receipt": str(path), "scratch": str(path.parent / "scratch"),
         "allocation_base": baseline, "inputs_sha": inputs,
         "contract": identity_of(f"docs/specs/{loop}/{task}/spec.md"),
@@ -1105,6 +1162,31 @@ def ensure_packet(v, row, path, receipt):
         "runner": [sys.executable, str(Path(__file__).with_name("acceptance.py")), "run", "--packet", str(packet_path)],
         "obligations": OBLIGATIONS,
     }
+    instructions = packet["methodology"]
+    binding = harness_call("read_binding", v["common"])
+    if binding:
+        defaults = {"source": "release", **binding["defaults"]}
+    else:
+        # An unbound queue's executor still gets the principles: the invoking skill's own copy.
+        own = SKILLS / "_shared/runtime-principles.md"
+        defaults = {"source": "skill", **harness_call("file_identity", own)} if own.is_file() else None
+    if defaults is None and not instructions:
+        raise Waiting(f"{identity}: no principles reach its executor — neither CLAUDE.md/AGENTS.md at the inputs commit nor "
+                      f"{SKILLS / '_shared/runtime-principles.md'}; reinstall devlyn-cli to restore that file, then drain again")
+    packet.update(harness=binding["release"] if binding else None,
+                  methodology={"defaults": defaults, "projectInstructions": instructions}, workerPrompt=None)
+    if binding:
+        harness_call("check_binding", binding, harness_call("resolve", SKILLS))
+        bound_skills = Path(binding["release"]["root"]) / "config/skills"
+        packet["runner"][1] = str(bound_skills / "devlyn-ideate/scripts/acceptance.py")
+        prompt = path.parent / "worker-prompt.md"
+        body = (f"Execute task packet {packet_path}. Work only in {worktree} on its owned branch.\n"
+                f"Read {binding['defaults']['path']} and apply it as defaults; explicit user and native owner/project instructions win.\n"
+                f"Set DEVLYN_SKILL_DIR={bound_skills / 'devlyn-ideate'} and DEVLYN_SHARED_DIR={bound_skills / '_shared'}.\n"
+                f"Follow Executor exchange and Review records in {bound_skills / 'devlyn-ideate/references/loop.md'}.\n"
+                f"Meet the packet obligations, run its runner and write {packet['submission']}. Never push, open a pull request or merge.\n")
+        acceptance()["atomic_write"](prompt, body.encode("utf-8"))
+        packet["workerPrompt"] = harness_call("file_identity", prompt)
     write_json(packet_path, packet)
     return packet_path, packet
 
@@ -1125,6 +1207,7 @@ def ensure_submission(identity, packet_path, packet, executor):
     An attempt's start is recorded before the spawn and its exit after the wait, so a start without an exit may have
     left a live executor: drain observes once and waits if it is active. Only established cessation permits adoption
     or another execution. Where writers cannot be observed the task fails as interrupted-unobservable."""
+    harness_call("verify_packet", packet, packet_path, SKILLS)
     submission = Path(packet["submission"])
     worktree = Path(packet["worktree"])
     log = submission.with_name("executions.log")
@@ -1144,6 +1227,10 @@ def ensure_submission(identity, packet_path, packet, executor):
             raise LoopError(f"cannot establish that an interrupted execution stopped: {exc}; repair writer observation, then drain again") from exc
     if submission.exists():
         return None
+    defaults = packet["methodology"].get("defaults") if packet.get("schema_version") == 2 else None
+    if packet.get("harness") is None and defaults and not Path(defaults["path"]).is_file():
+        # An installation's own copy moves with its updates; only its absence matters, and only before a spawn.
+        raise Waiting(f"{identity}: its principles file {defaults['path']} is gone; reinstall devlyn-cli to restore it, then drain again")
     argv = [part.replace("{packet}", str(packet_path)) for part in executor]
     if any("{worktree_git_dir}" in part for part in argv):  # Optional: a Codex executor lists it as a writable root.
         git_dir = git(worktree, "rev-parse", "--path-format=absolute", "--git-dir")
@@ -1217,6 +1304,8 @@ def advance(v, row, opts):
     if not path.exists() and (refused := allocate(v, row, opts)):
         return refused
     receipt = read_json(path)
+    if receipt.get("acceptance") and (path.parent / "packet.json").exists():
+        harness_call("verify_packet", read_json(path.parent / "packet.json"), path.parent / "packet.json", SKILLS)
     if not receipt.get("acceptance"):
         state["phase"] = "inputs"
         failure = v["states"][identity].get("inputs_changed")
@@ -1269,7 +1358,9 @@ def summary(v, row):
                 branch = receipt["branch"]
             if receipt.get("acceptance") and receipt.get("delivery") not in SETTLED:
                 if receipt.get("queue"):
-                    argv = [sys.executable, str(SKILLS / "_shared/task-complete.py"), "complete", "--receipt", str(state["path"])]
+                    binding = harness_call("read_binding", v["common"])
+                    skills = Path(binding["release"]["root"]) / "config/skills" if binding else SKILLS
+                    argv = [sys.executable, str(skills / "_shared/task-complete.py"), "complete", "--receipt", str(state["path"])]
                     if receipt.get("writers_released"):
                         argv.append("--writers-stopped")
                     if not receipt.get("local_only") and not receipt.get("mode_override"):
@@ -1420,6 +1511,7 @@ def prune_parents(v, root):
 def drain(args):
     anchor, common = repository(args.repo)
     args.repo = anchor  # Preserve the repository root for failures reported by main.
+    enforce_binding(common, anchor)
     diagnostics = skill_diagnostics(anchor)
     require(any("{packet}" in part for part in args.executor), "executor argv must contain {packet}, replaced by the task packet path")
     args.default_worktree_root = args.worktree_root is None
@@ -1456,15 +1548,17 @@ def drain(args):
         last["cleanup"].extend(args.root_diagnostics)
         annotate(last, refused)
         prune_parents(last, args.worktree_root)
+        try:
+            release_settled_binding(anchor, common)
+        except (LoopError, OSError) as exc:
+            last["cleanup"].append(f"queue binding not released: {exc}; the next status or drain retries")
         return {"status": status, "reason": reason, **diagnostics,
                 "reports": write_reports(last, status, reason, diagnostics["warnings"]), "counts": counts(last),
                 "tasks": [summary(last, row) for row in last["rows"] if row["identity"]], "cleanup": last["cleanup"]}
 
 
-def status(args):
-    anchor, common = repository(args.repo)
-    args.repo = anchor  # Preserve the repository root for failures reported by main.
-    v = view(anchor, common, args.local_only)
+def status_summary(v):
+    anchor = v["anchor"]
     row = next_task(v, set())
     annotate(v, {})
     tasks = [summary(v, r) for r in v["rows"] if r["identity"]]
@@ -1475,6 +1569,41 @@ def status(args):
             "delivery": [t for t in tasks if t.get("resume")], "cleanup": v["cleanup"]}
 
 
+def status(args):
+    anchor, common = repository(args.repo)
+    args.repo = anchor
+    enforce_binding(common, anchor)
+    result = status_summary(view(anchor, common, args.local_only))
+    release_settled_binding(anchor, common)
+    return result
+
+
+def inspect(args):
+    anchor, common = repository(args.repo)
+    try:
+        result = status_summary(view(anchor, common, pure=True))
+    except (LoopError, OSError) as exc:
+        result = {"status": "BLOCKED", "reason": str(exc), **skill_diagnostics(anchor)}
+    binding_path = common / "devlyn-loops/harness.json"
+    binding = None
+    compatibility = {"compatible": True, "legacy": not (binding_path.exists() or binding_path.is_symlink()), "reasons": [], "recoveryArgv": None,
+                     "taskPacket": {"inspect": [1, 2], "execute": [1, 2], "write": 2}, "queueBinding": {"read": [1, 1], "write": 1}}
+    try:
+        binding = read_json(binding_path) if not compatibility["legacy"] else None
+        enforce_binding(common)
+        for packet in (common / "devlyn-completion").glob("*/packet.json"):
+            harness_call("packet_schema", read_json(packet))
+    except (LoopError, OSError) as exc:
+        compatibility.update(compatible=False, reasons=[str(exc)])
+        try:
+            valid = harness_call("read_binding", common)
+            if valid:
+                compatibility["recoveryArgv"] = harness_call("recovery_argv", valid, ["inspect", "--repo", str(anchor), "--json"])
+        except (LoopError, OSError):
+            pass  # The diagnostic above describes the malformed binding; no safe argv can be inferred.
+    return {**result, "binding": binding, "compatibility": compatibility}
+
+
 def legacy_target(anchor, number):
     """The pending legacy row on line `number` of the legacy queue, as add records it: its exact text and its occurrence
     among equal rows, line endings aside; None for any other line."""
@@ -1501,7 +1630,9 @@ def add(args):
     ref, package_dir = CAPTURES + loop, f"docs/specs/{loop}"
     require(meta.name == "meta.md" and meta.parent.parent == anchor / "docs/specs" and re.fullmatch(ID, loop),
             f"package must be <repo>/docs/specs/<loop-id>/meta.md: {meta}")
+    enforce_binding(common, anchor)
     with lock(common, "queue.lock", blocking=True):
+        enforce_binding(common)
         recorded = records(common)
         notes = clean(common, recorded)
         target = legacy_target(anchor, args.materialize) if args.materialize else None
@@ -1540,6 +1671,11 @@ def add(args):
             require(" ".join(target["line"][6:].split()) in intent, "meta.md '## Intent' must reproduce the legacy row's intent verbatim")
         paths = [f"{package_dir}/meta.md", *(f"{package_dir}/{task}/{name}" for task in package["tasks"] for name in ("spec.md", "spec.expected.json"))]
         files = {rel: package_bytes(anchor, None, rel) for rel in paths} | {loop_queue(loop): loop_rows(loop, package, target)}
+        # The lock covers both first binding and first capture; an interrupted binding is authoritative on retry.
+        if harness_call("read_binding", common) is None:
+            invoking = harness_call("resolve", SKILLS)
+            if invoking is not None and not unfinished(view(anchor, common, pure=True)):
+                write_json(common / "devlyn-loops/harness.json", invoking)
         tree = build_tree(anchor, None, files)
         if captured:
             require(tree == git(anchor, "rev-parse", captured + "^{tree}"), interrupted)
@@ -2016,6 +2152,9 @@ def main():
         action = actions.add_parser(name)
         action.add_argument("--repo", default=".")
         action.add_argument("--local-only", "--no-push", action="store_true")
+    inspector = actions.add_parser("inspect")
+    inspector.add_argument("--repo", default=".")
+    inspector.add_argument("--json", action="store_true")
     actions.choices["drain"].add_argument("--worktree-root")
     actions.choices["drain"].add_argument("executor", nargs="+", help="host executor argv after --; {packet} becomes the packet path")
     args = parser.parse_args()
@@ -2025,9 +2164,11 @@ def main():
             print(f"queue self-test: PASS ({result.testsRun} tests)")
         return 0 if result.wasSuccessful() else 1
     if args.action is None:
-        parser.error("check, add, status or drain is required")
+        parser.error("check, add, status, inspect or drain is required")
+    if args.action == "inspect":
+        os.environ["GIT_OPTIONAL_LOCKS"] = "0"  # git diff may otherwise refresh the index even with unchanged bytes.
     try:
-        result = {"check": check, "add": add, "status": status, "drain": drain}[args.action](args)
+        result = {"check": check, "add": add, "status": status, "drain": drain, "inspect": inspect}[args.action](args)
     except (LoopError, OSError) as exc:
         result = {"status": "BLOCKED", "reason": str(exc)}
         if args.action in {"status", "drain"}:

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "devlyn-cli",
-  "version": "4.2.26",
+  "version": "4.3.0",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — core engineering principles for CLAUDE.md/AGENTS.md and a loop designer that splits one intent into tasks agents drain hands-free",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {
     "devlyn": "bin/devlyn.js"
   },
   "scripts": {
-    "prepack": "node -e \"require('./bin/release').buildRelease()\""
+    "prepack": "node -e \"require('./bin/release').buildRelease()\"",
+    "postpack": "node -e \"require('./bin/release').cleanGenerated()\""
   },
   "files": [
     "bin",