devlyn-cli 3.1.1 → 3.1.2

package/config/skills/_shared/process-evidence.py

@@ -185,7 +185,7 @@ def _source_expected_path(work: pathlib.Path, state: dict) -> pathlib.Path | Non
     if not isinstance(spec_path, str) or not spec_path:
         raise EvidenceError("state.source.spec_path is missing")
     spec_rel = _safe_relative_path(spec_path, "state.source.spec_path")
-    expected = work.joinpath(*spec_rel.parts).with_suffix(".expected.json")
+    expected = work.joinpath(*spec_rel.parts).with_name("spec.expected.json")
     try:
         expected.resolve().relative_to(work.resolve())
     except (OSError, ValueError) as exc:
@@ -682,6 +682,21 @@ def self_test() -> int:
             "cmd": "printf raw-out; printf raw-err >&2; exit 7",
             "exit_code": 7, "stdout_contains": ["raw-outraw-err"],
         })
+        spec_dir = work / "docs"
+        spec_dir.mkdir()
+        (spec_dir / "X.md").write_text("# Named spec\n", encoding="utf-8")
+        expected = spec_dir / "spec.expected.json"
+        expected.write_text(json.dumps({
+            "process_evidence": [obligation],
+            "verification_commands": [{"cmd": "printf required"}],
+        }), encoding="utf-8")
+        (spec_dir / "X.expected.json").write_text("{}\n", encoding="utf-8")
+        named_state = {**state, "source": {"type": "spec", "spec_path": "docs/X.md"}}
+        assert declared_obligations(work, named_state, "implement") == [obligation]
+        assert mechanical_evidence_required(work, named_state)
+        expected.unlink()
+        assert declared_obligations(work, named_state, "implement") == []
+        assert not mechanical_evidence_required(work, named_state)
         entry = capture_process(work, manifest, state["run_id"], "implement", 0, obligation)
         assert entry["expectation_met"]
         assert (manifest.parent / "red-first.stdout").read_bytes() == b"raw-out"

package/config/skills/_shared/resolve-bootstrap.py

@@ -282,16 +282,13 @@ def init_spec_source(
         block("BLOCKED:invalid-flags", f"spec unreadable: {raw_path}: {exc}")
     helper = shared_dir / "spec-verify-check.py"
     expected = path.with_name("spec.expected.json")
-    if expected.is_file():
-        run_checked([sys.executable, str(helper), "--check-expected", str(expected)], cwd)
-    else:
-        run_checked([sys.executable, str(helper), "--check", str(path)], cwd)
     module = load_spec_helper(shared_dir)
     if expected.is_file():
         found, _staged, error, _expected_path, _data = module.stage_from_expected(path, staging_dir)
         if not found or error:
             block("BLOCKED:invalid-flags", error or f"expected contract not found: {expected}")
     else:
+        run_checked([sys.executable, str(helper), "--check", str(path)], cwd)
         _staged, error = module.stage_from_source(path, staging_dir)
         if error:
             block("BLOCKED:invalid-flags", error)
@@ -1210,6 +1207,34 @@ def self_test() -> int:
         subprocess.run(["git", "restore", "app.py"], cwd=work, check=True)
         print("PASS bootstrap self-test patch lifecycle: full-mode removal + dirty verify-only exact capture")
 
+        for valid_named in (True, False):
+            named_work = root / f"named-spec-{valid_named}"
+            init_repo(named_work)
+            named_spec = named_work / "X.md"
+            named_spec.write_text(
+                "---\ncomplexity: " + ("medium" if valid_named else "hihg") + "\n---\n# Named spec\n",
+                encoding="utf-8",
+            )
+            (named_work / "spec.md").write_text(
+                "---\ncomplexity: " + ("hihg" if valid_named else "medium") + "\n---\n# Unrelated spec\n",
+                encoding="utf-8",
+            )
+            (named_work / "spec.expected.json").write_text(json.dumps({
+                "verification_commands": [{"cmd": "printf named-contract"}],
+            }), encoding="utf-8")
+            try:
+                result = bootstrap(["--spec", "X.md"], named_work, script_shared)
+            except BootstrapBlocked as exc:
+                assert not valid_named and exc.reason == "BLOCKED:invalid-flags", exc
+                assert "frontmatter complexity" in exc.detail, exc.detail
+                assert not (named_work / ".devlyn").exists()
+            else:
+                assert valid_named, "invalid named spec was accepted via unrelated spec.md"
+                assert result["source"]["spec_path"] == "X.md"
+                assert result["source"]["spec_sha256"] == sha256(named_spec.read_bytes())
+                staged = strict_json((named_work / ".devlyn/spec-verify.json").read_text(encoding="utf-8"))
+                assert staged["verification_commands"] == [{"cmd": "printf named-contract"}]
+
         dirty_work = root / "dirty-repo"
         init_repo(dirty_work)
         bootstrap(["clean", "baseline"], dirty_work, script_shared)

package/config/skills/_shared/spec-verify-check.py

@@ -844,10 +844,21 @@ def validate_expected_shape(data) -> str | None:
     return None
 
 
-def validate_expected_against_sibling_spec(expected_path: Path, data: object) -> str | None:
+def validate_inline_shape(data: object) -> str | None:
+    if isinstance(data, dict):
+        unknown = sorted(set(data) - {"verification_commands"})
+        if unknown:
+            return (
+                f"unsupported inline key(s): {', '.join(unknown)}; inline carriers "
+                "support only verification_commands. Encode these checks as commands, "
+                "or use a real spec with sibling spec.expected.json."
+            )
+    return validate_shape(data) or validate_expected_shape(data)
+
+
+def validate_expected_against_sibling_spec(spec_path: Path, data: object) -> str | None:
     if not isinstance(data, dict):
         return None
-    spec_path = expected_path.with_name("spec.md")
     if not spec_path.is_file():
         return None
     try:
@@ -881,8 +892,7 @@ def validate_expected_against_sibling_spec(expected_path: Path, data: object) ->
     )
 
 
-def validate_sibling_spec_complexity(expected_path: Path) -> str | None:
-    spec_path = expected_path.with_name("spec.md")
+def validate_sibling_spec_complexity(spec_path: Path) -> str | None:
     if not spec_path.is_file():
         return None
     try:
@@ -1208,7 +1218,7 @@ def stage_from_source(md: Path, devlyn_dir: Path) -> tuple[bool, str | None]:
         data = loads_strict_json(block)
     except ValueError as e:
         return (False, f"`<!-- devlyn:verification -->` ```json``` block in {md} has invalid JSON: {e}")
-    err = validate_shape(data)
+    err = validate_inline_shape(data)
     if err:
         return (False, f"`<!-- devlyn:verification -->` ```json``` block in {md}: {err}")
     normalized = {"verification_commands": data["verification_commands"]}
@@ -1236,6 +1246,9 @@ def stage_from_expected(
     if err:
         return (True, False, err, expected_path, None)
     assert data is not None
+    err = validate_sibling_spec_complexity(md) or validate_expected_against_sibling_spec(md, data)
+    if err:
+        return (True, False, f"{expected_path}: {err}", expected_path, None)
     commands = data.get("verification_commands")
     if not commands:
         spec_path = devlyn_dir / "spec-verify.json"
@@ -1892,7 +1905,7 @@ def run_check_mode(md_path: Path) -> int:
             file=sys.stderr,
         )
         return 2
-    err = validate_shape(data)
+    err = validate_inline_shape(data)
     if err:
         print(f"[spec-verify --check] {md_path}: shape error: {err}", file=sys.stderr)
         return 2
@@ -1915,11 +1928,11 @@ def run_check_expected_mode(expected_path: Path) -> int:
     if err:
         print(f"[spec-verify --check-expected] {expected_path}: shape error: {err}", file=sys.stderr)
         return 2
-    complexity_err = validate_sibling_spec_complexity(expected_path)
+    complexity_err = validate_sibling_spec_complexity(expected_path.with_name("spec.md"))
     if complexity_err:
         print(f"[spec-verify --check-expected] {expected_path}: shape error: {complexity_err}", file=sys.stderr)
         return 2
-    sibling_err = validate_expected_against_sibling_spec(expected_path, _data)
+    sibling_err = validate_expected_against_sibling_spec(expected_path.with_name("spec.md"), _data)
     if sibling_err:
         print(f"[spec-verify --check-expected] {expected_path}: shape error: {sibling_err}", file=sys.stderr)
         return 2
@@ -3691,6 +3704,54 @@ def run_self_test() -> int:
             print("generated criteria carrier was not staged into .devlyn/spec-verify.json", file=sys.stderr)
             return 1
 
+        inline_marker = generated_user / "inline-command-ran"
+        inline_command = "printf bad > inline-command-ran; printf bad"
+        for source_type in ("generated", "spec"):
+            for contract, diagnostic in (
+                ({"verification_commands": [{"cmd": inline_command}],
+                  "required_files": ["missing.txt"]}, "unsupported inline key(s): required_files"),
+                ({"verification_commands": [{"cmd": inline_command,
+                  "stdout_not_contians": ["bad"]}]}, "unknown key(s): stdout_not_contians"),
+                ({"verification_commands": [{"cmd": inline_command,
+                  "stdout_not_contains": ["bad"]}]}, None),
+            ):
+                inline_marker.unlink(missing_ok=True)
+                (generated_devlyn / output_findings_name()).unlink(missing_ok=True)
+                generated_criteria.write_text(
+                    "# Inline constraints\n\n<!-- devlyn:verification -->\n## Verification\n\n```json\n"
+                    + json.dumps(contract) + "\n```\n", encoding="utf-8",
+                )
+                prefix = "criteria" if source_type == "generated" else "spec"
+                (generated_devlyn / "pipeline.state.json").write_text(json.dumps({
+                    "source": {
+                        "type": source_type,
+                        f"{prefix}_path": str(generated_criteria),
+                        f"{prefix}_sha256": hashlib.sha256(generated_criteria.read_bytes()).hexdigest(),
+                    }
+                }), encoding="utf-8")
+                # A stale valid carrier must not bypass malformed source validation.
+                (generated_devlyn / "spec-verify.json").write_text(json.dumps({
+                    "verification_commands": [{"cmd": inline_command}]
+                }), encoding="utf-8")
+                inline_check = subprocess.run(
+                    [sys.executable, script_path, "--check", str(generated_criteria)],
+                    cwd=generated_user, capture_output=True, text=True, encoding="utf-8",
+                )
+                inline_run = subprocess.run(
+                    [sys.executable, script_path], cwd=generated_user,
+                    capture_output=True, text=True, encoding="utf-8",
+                )
+                assert inline_check.returncode == (2 if diagnostic else 0)
+                assert inline_run.returncode == 1
+                if diagnostic:
+                    assert diagnostic in inline_check.stderr and diagnostic in inline_run.stderr
+                    assert not inline_marker.exists(), "malformed inline constraint executed a command"
+                else:
+                    assert inline_marker.exists(), "valid inline output guard was not executed"
+                    assert "correctness.spec-literal-mismatch" in (
+                        generated_devlyn / output_findings_name()
+                    ).read_text(encoding="utf-8")
+
         generated_criteria.write_text(
             "# Criteria\n\n## Verification\n\n- generated criteria omitted its machine-readable carrier.\n",
             encoding="utf-8",
@@ -3750,6 +3811,54 @@ def run_self_test() -> int:
             print("sibling spec.expected.json was not staged into .devlyn/spec-verify.json", file=sys.stderr)
             return 1
 
+        pure_prose = "# Design\n\n<!-- devlyn:verification -->\n## Verification\n\n- No runtime verification commands.\n"
+        stale_command = {"verification_commands": [{"cmd": "printf unexpected-command"}]}
+        pure_inline = pure_prose + "\n```json\n" + json.dumps(stale_command) + "\n```\n"
+        for name, filename, source, contract, expected_rule in (
+            ("pure-prose", "spec.md", pure_prose, {"pure_design": True}, None),
+            ("pure-inline", "design-notes.md", pure_inline, {"pure_design": True, "verification_commands": []}, None),
+            ("empty-runtime", "design-notes.md", pure_inline, {"verification_commands": []}, "correctness.spec-verify-malformed"),
+            ("contradictory-pure", "spec.md", pure_inline, {"pure_design": True, **stale_command}, "correctness.spec-verify-malformed"),
+            ("pure-required-file", "spec.md", pure_inline, {"pure_design": True, "required_files": ["missing.md"]}, "correctness.required-file-missing"),
+        ):
+            case_root = work / name
+            case_root.mkdir()
+            case_devlyn = case_root / ".devlyn"
+            case_devlyn.mkdir()
+            case_spec = case_root / filename
+            case_spec.write_text(source, encoding="utf-8")
+            (case_root / "spec.expected.json").write_text(json.dumps(contract), encoding="utf-8")
+            (case_devlyn / "spec-verify.json").write_text(json.dumps(stale_command), encoding="utf-8")
+            (case_devlyn / "pipeline.state.json").write_text(json.dumps({
+                "source": {"type": "spec", "spec_path": str(case_spec)},
+            }), encoding="utf-8")
+            case_run = subprocess.run(
+                [sys.executable, script_path], cwd=case_root,
+                capture_output=True, text=True, encoding="utf-8",
+            )
+            if case_run.returncode != (1 if expected_rule else 0):
+                print(f"{name}: sibling execution returned {case_run.returncode}: {case_run.stderr}", file=sys.stderr)
+                return 1
+            case_findings = [
+                loads_strict_json(line) for line in
+                (case_devlyn / output_findings_name()).read_text(encoding="utf-8").splitlines()
+            ]
+            if [finding["rule_id"] for finding in case_findings] != ([expected_rule] if expected_rule else []):
+                print(f"{name}: unexpected sibling findings: {case_findings}", file=sys.stderr)
+                return 1
+            case_results = case_devlyn / "spec-verify.results.json"
+            if expected_rule == "correctness.spec-verify-malformed":
+                if case_results.exists():
+                    print(f"{name}: malformed sibling reached command execution", file=sys.stderr)
+                    return 1
+            elif (
+                loads_strict_json(case_results.read_text(encoding="utf-8"))
+                != {"commands": [], "process_evidence": None}
+                or (case_devlyn / "spec-verify.json").exists()
+            ):
+                print(f"{name}: pure-design sibling ran or retained a stale command", file=sys.stderr)
+                return 1
+
         malformed = work / "malformed-sibling"
         malformed.mkdir()
         malformed_devlyn = malformed / ".devlyn"
@@ -4915,8 +5024,8 @@ def main() -> int:
                 print(f"[spec-verify] carrier malformed: {expected_error}", file=sys.stderr)
                 write_malformed_finding(devlyn_dir, expected_error, expected_path)
                 return 1
-            if expected_staged:
-                staged, error = (True, None)
+            if expected_found:
+                staged, error = (expected_staged, None)
             else:
                 staged, error = stage_from_source(source_md, devlyn_dir)
         else:

package/config/skills/_shared/task-complete.py

@@ -204,6 +204,9 @@ def allocate(args):
     path = directory / "receipt.json"
     receipt["id"] = key
     receipt["recovery_ref"] = "refs/devlyn/completed/" + key
+    scratch = directory / "scratch"
+    scratch.mkdir()
+    receipt["scratch_identity"] = workspace_identity(scratch, directory)
     # Persist prospective intent BEFORE native creation. An interrupted allocation
     # stays visibly incomplete; a later call may not adopt whatever now exists.
     atomic_json(path, receipt)
@@ -215,7 +218,7 @@ def allocate(args):
     receipt["worktree_identity"] = workspace_identity(target, Path(receipt["worktree_gitdir"]))
     receipt["allocation"] = "owned"
     atomic_json(path, receipt)
-    return {"status": "ALLOCATED", "receipt": str(path), "worktree": str(target)}
+    return {"status": "ALLOCATED", "receipt": str(path), "worktree": str(target), "scratch": str(scratch)}
 
 
 def pipeline_acceptance(work, acceptance, files, directory):
@@ -269,7 +272,7 @@ def pipeline_acceptance(work, acceptance, files, directory):
                 require(evidence_module["bound_carrier_outcome"](reconstructed, carrier)["verdict"] == "PASS", "required process evidence failed")
         source = state.get("source") or {}
         if source.get("spec_path"):
-            expected = Path(source["spec_path"]).with_suffix(".expected.json")
+            expected = Path(source["spec_path"]).with_name("spec.expected.json")
             original = safe_path(work, str(expected))
             if original.exists():
                 dest = safe_path(reconstructed, str(expected))
@@ -342,7 +345,8 @@ def bind_acceptance(receipt, path, supplied):
                     require(committed.returncode == 0 and committed.stdout == source_file.read_bytes(), "source contract changed since accepted commit")
                 bound_digest = source.get(key.replace("_path", "_sha256"))
                 require(file_record(source_file)["sha256"] == bound_digest, "source contract differs from run binding")
-                expected = str(Path(source[key]).with_suffix(".expected.json"))
+                source_path = Path(source[key])
+                expected = str(source_path.with_name("spec.expected.json") if key == "spec_path" else source_path.with_suffix(".expected.json"))
                 if safe_path(work, expected).exists():
                     paths.append(expected)
     else:
@@ -437,6 +441,75 @@ def stopped_writers(work, *, linked):
         raise CompletionError("writer observation unsupported on this platform; retain workspace")
 
 
+def scratch_mounts():
+    if sys.platform.startswith("linux"):
+        rows = Path("/proc/self/mountinfo").read_text(encoding="utf-8").splitlines()
+        paths = []
+        for line in rows:
+            fields = line.split()
+            require(len(fields) >= 6, "cannot parse mount table; retain scratch")
+            paths.append(re.sub(r"\\([0-7]{3})", lambda m: chr(int(m[1], 8)), fields[4]))
+    elif sys.platform == "darwin":
+        paths = []
+        for line in command(["mount"]).splitlines():
+            description, separator, options = line.rpartition(" (")
+            candidates = [description[match.end():] for match in re.finditer(" on ", description)]
+            require(separator and options.endswith(")") and candidates, "cannot parse mount table; retain scratch")
+            # Darwin prints literal paths. Consider every possible separator so
+            # ' on ' in a device or directory name can only cause retention.
+            paths.extend(candidates)
+    else:
+        raise CompletionError("mount observation unsupported; retain scratch")
+    return [Path(value).resolve() for value in paths]
+
+
+def raise_walk_error(error):
+    raise error
+
+
+def clean_scratch(receipt, path, writers_stopped):
+    """Empty the owned build directory; keep its identity across resume/reuse."""
+    scratch = path.parent / "scratch"
+    if "scratch_identity" not in receipt:
+        return {"status": "NOT_OWNED"}
+    require(writers_stopped, "stop/yield scratch writers, then use --writers-stopped")
+    require(scratch == scratch.resolve() and scratch.is_dir(), "owned scratch missing or redirected; retain and inspect")
+    identity = receipt["scratch_identity"]
+    require(workspace_identity(scratch, path.parent) == identity, "scratch directory was replaced; retain")
+    require(shutil.rmtree.avoids_symlink_attacks, "safe scratch removal unsupported on this platform; retain")
+    require(not any(mount.is_relative_to(scratch) for mount in scratch_mounts()), "scratch contains a mounted filesystem; retain")
+    stopped_writers(scratch, linked=True)
+    size = 0
+    for directory, dirs, files in os.walk(scratch, followlinks=False, onerror=raise_walk_error):
+        require(not any(name.casefold() == ".git" for name in dirs + files), "scratch contains Git recovery data; move it to retained custody before cleanup")
+        for name in dirs + files:
+            item = Path(directory) / name
+            info = item.lstat()
+            require(info.st_dev == identity[0][0], "scratch contains a mounted filesystem; retain")
+            size += info.st_size if stat.S_ISREG(info.st_mode) else 0
+    stopped_writers(scratch, linked=True)
+    require(workspace_identity(scratch, path.parent) == identity, "scratch changed before removal; retain")
+    require(not any(mount.is_relative_to(scratch) for mount in scratch_mounts()), "scratch mount appeared before removal; retain")
+    for item in scratch.iterdir():
+        if item.is_dir() and not item.is_symlink():
+            shutil.rmtree(item)
+        else:
+            item.unlink()
+    require(workspace_identity(scratch, path.parent) == identity and not any(scratch.iterdir()), "scratch changed during cleanup; retain and inspect")
+    result = {"status": "CLEAN", "logical_bytes_removed": size}
+    receipt["scratch_cleanup"] = result
+    atomic_json(path, receipt)
+    return result
+
+
+def clean_scratch_command(args):
+    path = Path(args.receipt).absolute()
+    with locked_receipt(path) as receipt:
+        result = clean_scratch(receipt, path, args.writers_stopped)
+        return {"status": "SCRATCH_CLEAN" if result["status"] == "CLEAN" else "SCRATCH_NOT_OWNED",
+                "receipt": str(path), "scratch_cleanup": result, "product_verdict_unchanged": True}
+
+
 def cleanup(receipt, path, pr, writers_stopped):
     require(pr["state"] == "MERGED" and pr.get("mergedAt") and pr.get("mergeCommit", {}).get("oid"), "actual matching merge evidence is required")
     require(writers_stopped, "wait actual children, stop/yield known writers, then resume with --writers-stopped")
@@ -522,11 +595,27 @@ def locked_receipt(path):
 
 def complete(args):
     path = Path(args.receipt).absolute()
-    resume = shlex.join([sys.executable, str(Path(__file__).resolve()), "complete", "--receipt", str(path)])
+    resume = shlex.join([sys.executable, str(Path(__file__).resolve()), "complete", "--receipt", str(path)] +
+                        (["--writers-stopped"] if args.writers_stopped else []))
     with locked_receipt(path) as receipt:
         def result(status):
-            return {"status": status, "receipt": str(path), "pr": receipt.get("pr_url"), "resume": resume,
-                    "acceptance": (receipt.get("acceptance") or {}).get("kind"), "product_verdict_unchanged": True}
+            scratch = {"status": "NOT_OWNED"}
+            if "scratch_identity" in receipt:
+                try:
+                    scratch = clean_scratch(receipt, path, args.writers_stopped)
+                except (CompletionError, OSError, ValueError, KeyError, TypeError, IndexError) as error:
+                    scratch = {"status": "RETAINED", "reason": str(error), "resume": shlex.join([
+                        sys.executable, str(Path(__file__).resolve()), "clean-scratch", "--receipt", str(path), "--writers-stopped"])}
+                    receipt["scratch_cleanup"] = scratch
+                    try:
+                        atomic_json(path, receipt)
+                    except OSError as record_error:
+                        scratch["record_error"] = str(record_error)
+            return {"status": "CLEANUP_PENDING" if status == "COMPLETE" and scratch["status"] == "RETAINED" else status,
+                    "delivery_status": status, "receipt": str(path), "pr": receipt.get("pr_url"), "resume": resume,
+                    "acceptance": (receipt.get("acceptance") or {}).get("kind"), "product_verdict_unchanged": True,
+                    "scratch_path": str(path.parent / "scratch") if "scratch_identity" in receipt else None,
+                    "scratch_cleanup": scratch}
         if args.local_only or receipt.get("local_only"):
             receipt["local_only"] = True
             atomic_json(path, receipt)
@@ -610,20 +699,24 @@ def main():
     completion.add_argument("--mode", choices=("auto", "pr"))
     completion.add_argument("--local-only", "--no-push", action="store_true")
     completion.add_argument("--writers-stopped", action="store_true")
+    scratch_cleanup = actions.add_parser("clean-scratch")
+    scratch_cleanup.add_argument("--receipt", required=True)
+    scratch_cleanup.add_argument("--writers-stopped", action="store_true")
     args = parser.parse_args()
     if args.self_test:
         return self_test()
     if args.action is None:
-        parser.error("allocate or complete is required")
+        parser.error("allocate, complete or clean-scratch is required")
     try:
-        result = allocate(args) if args.action == "allocate" else complete(args)
+        result = (allocate(args) if args.action == "allocate" else
+                  clean_scratch_command(args) if args.action == "clean-scratch" else complete(args))
         print(json.dumps(result, sort_keys=True))
         return 0
-    except (CompletionError, OSError, ValueError, KeyError, TypeError, SystemExit) as exc:
+    except (CompletionError, OSError, ValueError, KeyError, TypeError, IndexError, SystemExit) as exc:
         result = {"status": "BLOCKED", "reason": str(exc)}
-        if args.action == "complete":
+        if args.action in {"complete", "clean-scratch"}:
             result["receipt"] = str(Path(args.receipt).absolute())
-            result["resume"] = shlex.join([sys.executable, str(Path(__file__).resolve()), "complete", "--receipt", result["receipt"]])
+            result["resume"] = shlex.join([sys.executable, str(Path(__file__).resolve()), args.action, "--receipt", result["receipt"], *(["--writers-stopped"] if args.writers_stopped else [])])
         print(json.dumps(result, sort_keys=True))
         return 1
 
@@ -770,11 +863,138 @@ class CompletionTests(unittest.TestCase):
         self.task = Path(result["worktree"])
         return result
 
-    def accept(self, pipeline=False, queue=False, spec_expected=None):
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_disposable_scratch_cleans_for_local_only_and_preserves_source(self):
+        result = self.allocate()
+        scratch = Path(result["scratch"])
+        (scratch / "target").mkdir()
+        (scratch / "target" / "object").write_bytes(b"rebuildable")
+        (self.task / "uncommitted-work").write_text("preserve")
+        result, _ = self.cli("complete", "--receipt", self.receipt, "--local-only", "--writers-stopped")
+        self.assertEqual(result["status"], "LOCAL_ONLY")
+        self.assertFalse(any(scratch.iterdir()))
+        self.assertEqual((self.task / "uncommitted-work").read_text(), "preserve")
+        self.assertEqual(result["scratch_cleanup"]["logical_bytes_removed"], 11)
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+        self.assertEqual(result["status"], "SCRATCH_CLEAN")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_rejects_active_writer_and_requires_owner_assertion(self):
+        scratch = Path(self.allocate()["scratch"])
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, success=False)
+        self.assertIn("--writers-stopped", result["reason"])
+        child = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"], cwd=scratch)
+        try:
+            result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped", success=False)
+            self.assertIn("active process", result["reason"])
+            self.assertTrue(scratch.is_dir())
+        finally:
+            child.terminate()
+            child.wait(timeout=5)
+        self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_rejects_redirect_and_git_data_but_does_not_follow_child_links(self):
+        scratch = Path(self.allocate()["scratch"])
+        outside = self.root / "outside"
+        outside.mkdir()
+        (outside / "keep").write_text("source")
+        retained = scratch.with_name("retained")
+        scratch.rename(retained)
+        scratch.symlink_to(outside, target_is_directory=True)
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped", success=False)
+        self.assertIn("redirected", result["reason"])
+        scratch.unlink()
+        retained.rename(scratch)
+        (scratch / ".GiT").write_text("gitdir: elsewhere")
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped", success=False)
+        self.assertIn("Git recovery data", result["reason"])
+        (scratch / ".GiT").unlink()
+        (scratch / "external-link").symlink_to(outside, target_is_directory=True)
+        self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+        self.assertEqual((outside / "keep").read_text(), "source")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_reuse_and_partial_cleanup_keep_original_identity(self):
+        scratch = Path(self.allocate()["scratch"])
+        (scratch / "first-build").write_bytes(b"first")
+        self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+        (scratch / "resumed-build").write_bytes(b"next")
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped")
+        self.assertEqual(result["scratch_cleanup"]["logical_bytes_removed"], 4)
+        self.assertFalse(any(scratch.iterdir()))
+        scratch.rename(scratch.with_name("original"))
+        scratch.mkdir()
+        (scratch / "foreign").write_text("preserve")
+        result, _ = self.cli("clean-scratch", "--receipt", self.receipt, "--writers-stopped", success=False)
+        self.assertIn("replaced", result["reason"])
+        self.assertIn("--writers-stopped", result["resume"])
+        self.assertEqual((scratch / "foreign").read_text(), "preserve")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_refusal_does_not_block_local_only_delivery(self):
+        scratch = Path(self.allocate()["scratch"])
+        (scratch / ".git").mkdir()
+        result, _ = self.cli("complete", "--receipt", self.receipt, "--local-only", "--writers-stopped")
+        self.assertEqual(result["status"], "LOCAL_ONLY")
+        self.assertEqual(result["scratch_cleanup"]["status"], "RETAINED")
+        self.assertIn("Git recovery data", result["scratch_cleanup"]["reason"])
+        self.assertEqual(json.loads(self.receipt.read_text())["scratch_cleanup"]["status"], "RETAINED")
+        self.assertTrue((scratch / ".git").is_dir())
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_refusal_reports_delivery_separately(self):
+        scratch = Path(self.allocate()["scratch"])
+        self.accept()
+        (scratch / ".git").mkdir()
+        result, _ = self.cli("complete", "--receipt", self.receipt, "--acceptance", self.acceptance, "--writers-stopped")
+        self.assertEqual(result["status"], "CLEANUP_PENDING")
+        self.assertEqual(result["delivery_status"], "COMPLETE")
+        self.assertEqual(result["scratch_cleanup"]["status"], "RETAINED")
+        self.assertIn("--writers-stopped", result["scratch_cleanup"]["resume"])
+        self.assertIn("--writers-stopped", result["resume"])
+        (scratch / ".git").rmdir()
+        result, _ = self.cli("complete", "--receipt", self.receipt, "--writers-stopped")
+        self.assertEqual(result["status"], "COMPLETE")
+
+    @unittest.skipUnless(sys.platform == "darwin" or sys.platform.startswith("linux"), "writer observation requires POSIX")
+    def test_scratch_mount_and_scan_failure_preserve_contents(self):
+        from unittest.mock import patch
+        scratch = Path(self.allocate()["scratch"])
+        (scratch / "keep").write_text("retained")
+        receipt = json.loads(self.receipt.read_text())
+        with patch.dict(clean_scratch.__globals__, {"scratch_mounts": lambda: [scratch / "same-device-bind"]}):
+            with self.assertRaisesRegex(CompletionError, "mounted filesystem"):
+                clean_scratch(receipt, self.receipt, True)
+        def failed_walk(*args, **kwargs):
+            kwargs["onerror"](PermissionError("unreadable subtree"))
+        with patch.object(os, "walk", failed_walk):
+            with self.assertRaisesRegex(PermissionError, "unreadable subtree"):
+                clean_scratch(receipt, self.receipt, True)
+        self.assertEqual((scratch / "keep").read_text(), "retained")
+
+    def test_scratch_mount_table_parsing_preserves_ambiguous_literal_paths(self):
+        from unittest.mock import patch
+        target = "/task/scratch/name on inside\\040literal"
+        with patch.object(sys, "platform", "darwin"), patch.dict(scratch_mounts.__globals__, {
+            "command": lambda args: "device on source on " + target + " (local, journaled)",
+        }):
+            self.assertIn(Path(target).resolve(), scratch_mounts())
+        alias = self.root / "scratch-alias"
+        alias.symlink_to(self.root, target_is_directory=True)
+        with patch.object(sys, "platform", "darwin"), patch.dict(scratch_mounts.__globals__, {
+            "command": lambda args: "device on " + str(alias / "mounted") + " (local)",
+        }):
+            self.assertEqual(scratch_mounts(), [(self.root / "mounted").resolve()])
+        with patch.object(sys, "platform", "linux"), patch.object(Path, "read_text", return_value="truncated row"):
+            with self.assertRaisesRegex(CompletionError, "cannot parse mount table"):
+                scratch_mounts()
+
+    def accept(self, pipeline=False, queue=False, spec_expected=None, spec_name="spec.md"):
         if spec_expected is not None:
-            (self.task / "spec.md").write_text("# Fixture\nProduct contains accepted bytes.\n", encoding="utf-8")
+            (self.task / spec_name).write_text("# Fixture\nProduct contains accepted bytes.\n", encoding="utf-8")
             (self.task / "spec.expected.json").write_text(json.dumps(spec_expected), encoding="utf-8")
-            self.g("add", "spec.md", "spec.expected.json", work=self.task)
+            self.g("add", spec_name, "spec.expected.json", work=self.task)
         (self.task / "product").write_text("accepted\n", encoding="utf-8")
         self.g("add", "product", work=self.task)
         self.g("commit", "-m", "scoped task", work=self.task)
@@ -802,7 +1022,7 @@ class CompletionTests(unittest.TestCase):
             self.state = {"run_id": a["run_id"], "mode": "free-form", "source": source, "phases": phases, "process_evidence": None}
             if spec_expected is not None:
                 self.state["mode"] = "spec"
-                self.state["source"] = {"type": "spec", "spec_path": "spec.md", "spec_sha256": hashlib.sha256((self.task / "spec.md").read_bytes()).hexdigest()}
+                self.state["source"] = {"type": "spec", "spec_path": spec_name, "spec_sha256": hashlib.sha256((self.task / spec_name).read_bytes()).hexdigest()}
             (archive / "pipeline.state.json").write_text(json.dumps(self.state), encoding="utf-8")
             (archive / "finish-gate.summary.json").write_text(json.dumps({"mode": self.state["mode"], "exit": 0, "offenders": 0, "checked": 1}), encoding="utf-8")
             (archive / "verify-merge.summary.json").write_text(json.dumps({"verdict": "PASS"}), encoding="utf-8")
@@ -1167,6 +1387,22 @@ class CompletionTests(unittest.TestCase):
         self.assertIn("implement process evidence", json.loads(r.stdout)["reason"])
         self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
 
+    def test_named_spec_custody(self):
+        self.allocate(); self.accept(pipeline=True, spec_expected={"pure_design": True}, spec_name="X.md")
+        result, _ = self.complete("--mode", "pr")
+        self.assertEqual(result["status"], "PR")
+        receipt = json.loads(self.receipt.read_text(encoding="utf-8"))
+        self.assertIn("spec.expected.json", receipt["files"])
+        self.assertEqual((self.receipt.parent / "custody/spec.expected.json").read_bytes(), (self.task / "spec.expected.json").read_bytes())
+
+    def test_named_spec_missing_required_process_evidence(self):
+        expected = {"process_evidence": [{"id": "red-first", "phase": "implement", "argv": [sys.executable, "-c", "print('red')"], "exit_code": 0, "timeout_sec": 10}]}
+        self.allocate(); self.accept(pipeline=True, spec_expected=expected, spec_name="X.md")
+        _, r = self.complete(success=False)
+        self.assertNotEqual(r.returncode, 0)
+        self.assertIn("implement process evidence", json.loads(r.stdout)["reason"])
+        self.assertEqual(json.loads(self.data.read_text(encoding="utf-8")).get("pushs",0), 0)
+
 
 if __name__ == "__main__":
     runpy.run_path(str(Path(__file__).with_name("platform-support.py")))["configure_utf8"]()

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

@@ -96,7 +96,7 @@ python3 "$DEVLYN_SHARED_DIR/spec-verify-check.py" --check-expected <expected-pat
 ```
 
 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.
+- `verification_commands` ← `## Verification` + commands the conversation surfaced. While drafting both Verification and its carrier, omit a standalone check only when another command in that contract runs the same assertions under the required execution conditions and propagates failure; describe that shared coverage in Verification and keep both carriers aligned. Preserve distinct scenarios and required independent verification; execute approved commands unchanged without reusing results across phases. 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).

package/config/skills/devlyn:resolve/references/free-form-mode.md

@@ -75,7 +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.
+- For executable generated verification, put one fenced `json` object with only `verification_commands` inside the sentinel-marked `## Verification` section. Generated mode reads this inline carrier, not a sibling file. Follow `../../devlyn:ideate/references/spec-template.md` § "Sibling file: `spec.expected.json`" for constraint coverage, diff scope and violating/allowed controls, but express those checks as executable `verification_commands`; sibling-only fields such as `required_files` and `forbidden_patterns` are rejected inline. Preserve uncovered semantics as source-review obligations.
 - `## 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/phases/build-gate.md

@@ -59,7 +59,7 @@ Append all findings; do not stop on the first failure.
 
 <output>
 - `.devlyn/build_gate.findings.jsonl` — JSONL stream, one finding per line. Schema: `{id, rule_id, severity, file, line, message, fix_hint, criterion_ref}`.
-- `.devlyn/build_gate.log.md` — human-readable summary of which gates ran and their raw output.
+- `.devlyn/build_gate.log.md` — human-readable gate results with raw output or links to complete raw-output files, using sealed artifacts where available. Retain complete inventories/hash maps in `.devlyn/` files; report their paths, digests and relevant deltas instead of dumping them into the conversation.
 - Report `PASS` if zero CRITICAL/HIGH findings, `FAIL` for genuine product findings, or `BLOCKED:build-env-underprovisioned` only for the evidence-backed capability path above. A capability blocker leaves no product finding. Do not edit `pipeline.state.json` yourself — the orchestrator records it via `state-phase-write.py` from these artifacts.
 </output>
 

package/config/skills/devlyn:resolve/references/phases/verify.md

@@ -10,11 +10,13 @@ Independent quality layer. You answer one question: did the diff deliver what th
 - `spec.md` (or `.devlyn/criteria.generated.md` for free-form mode) — the contract.
 - `spec.expected.json` — the mechanical acceptance contract per `_shared/expected.schema.json`.
 - The cumulative diff against `state.base_ref.sha`.
-- The source hash (`state.source.spec_sha256` for spec mode, `state.source.criteria_sha256` for generated free-form mode) — re-read the source contract from disk and confirm the hash matches; if it does not, write `state.phases.verify.verdict: "BLOCKED"` with reason `source_sha256_mismatch` and stop.
-- `.devlyn/spec-verify.results.json` plus the validated VERIFY
+- The source hash (`state.source.spec_sha256` for spec mode, `state.source.criteria_sha256` for generated free-form mode) — re-read the source contract from disk and confirm the hash matches; if it does not, emit a verdict-binding finding with reason `source_sha256_mismatch` and terminal verdict `BLOCKED`, then stop reviewing without editing state.
+- `.devlyn/spec-verify.results.json` plus any required validated VERIFY
   process-evidence manifest and raw stdout/stderr streams named by its
   `process_evidence` carrier. These are immutable MECHANICAL results; rehash
-  every named byte before JUDGE spawn and again during merge.
+  every named byte before JUDGE spawn and again during merge. Valid pure-design
+  contracts with no executable obligations have `commands: []` and
+  `process_evidence: null`.
 
 You do NOT receive: PLAN, IMPLEMENT's reasoning, BUILD_GATE's findings, CLEANUP's allowlist negotiations. Reading those would compromise independence. Inspect authorized source, diff and sealed evidence using native read/search tools or non-mutating shell commands; executable verification belongs exclusively to MECHANICAL.
 </input>
@@ -40,14 +42,14 @@ On the constrained Windows read route, the orchestrator supplies the complete sp
 
 Grade the diff against the spec on rubric axes:
 
-- **Spec compliance** — did every Requirement get an `evidence` record pointing at code that satisfies it?
+- **Spec compliance** — does cited evidence show how every applicable Requirement and Constraint is satisfied?
 - **Scope** — does the diff touch only files PLAN listed (or the cleanup allowlist)? Out-of-scope file = HIGH finding `scope.out-of-scope-violation`.
 - **Quality** — does the implementation follow the framework's idiomatic patterns, or are there hand-rolled helpers replacing standard primitives? `design.unidiomatic-pattern` MEDIUM if so.
 - **Consistency** — internal style (naming, error shape, module boundaries) consistent with the surrounding code.
 
 **Bounded primary review**: the primary JUDGE makes one broad pass over the
 source contract, sealed MECHANICAL carrier, and cumulative diff, covering all
-four rubric axes and every binding Requirement clause. It then makes one
+four rubric axes and every binding Requirement and Constraint clause. It then makes one
 targeted interaction pass over the clauses the broad pass left unresolved.
 Before any third pass, emit the required terminal result. If R1–R8 or another
 spec axis remains uncovered, emit a verdict-binding BLOCKED coverage finding
@@ -55,7 +57,7 @@ instead of continuing or assuming PASS.
 
 For each finding, write file:line evidence. Do not paraphrase code; quote it.
 
-**Clause-level check**: split each Requirement into its binding clauses before
+**Clause-level check**: split each Requirement and Constraint into its binding clauses before
 you pass it. Words like `before`, `after`, `once`, `always`, `never`,
 `regardless`, `irrelevant`, `permanent`, `idempotent`, `duplicate`, `raw`, and
 `signature` usually encode a separate invariant. A passing verification command
@@ -90,7 +92,7 @@ risk probes and present in the sealed MECHANICAL evidence. Missing coverage is
 a verdict-binding finding; review the implementation's clause and code order
 without inventing a replacement command.
 
-**Coverage check**: before declaring done, confirm you have sealed evidence and code-order support for every spec axis. If an axis lacks declared MECHANICAL coverage, or the diff does not touch the code that produces it, set `state.verify.coverage_failed: true` and surface the missing-evidence finding rather than passing on assumption.
+**Coverage check**: account for every applicable Requirement and Constraint using sealed MECHANICAL evidence for required executable checks and cited source/design evidence for pure-design clauses or explicitly retained source-review obligations. Inspect applicable unchanged code and documentation; absence of a code change alone is not missing coverage. Source review never substitutes for required executable coverage. For any unsupported clause, emit a verdict-binding coverage finding identifying the missing evidence. JUDGE does not run checks or edit state; the orchestrator records `state.verify.coverage_failed: true` from coverage findings before merge.
 
 **Verdict-binding check**: a demonstrated violation of an applicable mandatory
 task, public, or existing test contract is binding, including unmet new

package/config/skills/devlyn:resolve/references/state-schema.md

@@ -67,7 +67,7 @@ Single authoritative verdict source for `/devlyn:resolve`. The orchestrator bran
 - **implement_passed_sha** — captured at end of PHASE 2; null until then. Activates the post-implement invariant for SURFACE_CLOSE, CLEANUP, and VERIFY.
 - **criteria** — generated from spec's `## Requirements` checklist (one per `- [ ]`). `status: pending → implemented` is the legal transition. `failed_by_finding_ids` populates when VERIFY surfaces a finding tied to a criterion.
 - **`.devlyn/untracked.baseline` artifact** — written at PHASE 0 (`spec-verify-check.py --write-untracked-baseline`); BUILD_GATE flags created-during-run unauthorized untracked files against it (`.devlyn/` exempt; semantics in `phases/build-gate.md` step 4).
-- **verify.coverage_failed** — outcome-dependent telemetry set when JUDGE cannot exercise a spec axis. It no longer gates pair dispatch: after MECHANICAL passes, `pair.default` dispatches both judges concurrently whenever `pair_default_enabled != false` and the OTHER engine is available. An orchestrator without foreground parallel dispatch runs the same two required judges sequentially; a primary blocker never skips the pair. A verdict-binding MECHANICAL blocker still skips both. Legacy complexity values remain accepted only for archived compatibility.
+- **verify.coverage_failed** — outcome-dependent telemetry set by the orchestrator when JUDGE reports missing clause evidence. It no longer gates pair dispatch: after MECHANICAL passes, `pair.default` dispatches both judges concurrently whenever `pair_default_enabled != false` and the OTHER engine is available. An orchestrator without foreground parallel dispatch runs the same two required judges sequentially; a primary blocker never skips the pair. A verdict-binding MECHANICAL blocker still skips both. Legacy complexity values remain accepted only for archived compatibility.
 - **verify.pair_trigger** — strict decision state: `{ "eligible": boolean, "reasons": string[], "skipped_reason": string|null }`. Schema v3.0 eligible state requires `pair.default` plus every applicable telemetry reason and `skipped_reason: null`; outcome-dependent reasons are appended after both judges return. Canonical reasons are `pair.default`, `mode.verify-only`, `mode.pair-verify`, `complexity.high`, `complexity.large`, `spec.complexity.high`, `spec.complexity.large`, `spec.solo_headroom_hypothesis`, `risk.high`, `risk_probes.enabled`, `risk_probes.present`, `coverage.failed`, `mechanical.warning`, and `judge.warning`. Ineligible new-run state has empty reasons and only `user_no_pair`, `mechanical_blocker`, `auto_pair_other_engine_unavailable`, or null; `primary_judge_blocker` remains parser-recognized only for archived v2.0 replay and retains its existing pre-known-reason rejection. Explicit `mode.pair-verify` cannot use the unavailable-engine skip. Missing, contradictory, incomplete, or unknown trigger state BLOCKs VERIFY.
 
 ## Per-phase shape

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

@@ -24,6 +24,33 @@ 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.
 
+Allocation also returns a receipt-owned `scratch` directory. Put disposable
+build intermediates there (for example, set
+`CARGO_TARGET_DIR` to `<scratch>/target`). Keep source checkouts, Git data,
+lockfiles, reports and restart evidence outside scratch. Do not create unowned
+temporary build trees or preserve them by copying them into evidence custody.
+Prefer `TemporaryDirectory`/`finally` for short-lived test fixtures.
+
+After waiting for task writers, `complete --writers-stopped` empties this
+scratch on delivery returns, including local-only and pending-PR routes. To
+release build caches when parking or after a failed run, use:
+
+```sh
+python3 "$DEVLYN_SHARED_DIR/task-complete.py" clean-scratch \
+  --receipt '<returned receipt.json>' --writers-stopped
+```
+
+This empties only the prospectively owned scratch, preserves its directory
+identity for interrupted cleanup and later builds, checks live users and reports
+the logical byte count separately from actual free disk space. It does not depend on a product PASS or rewrite that verdict.
+Unknown historical roots, source/recovery data, shared caches and terminal
+history are never adopted or swept. A refused cleanup does not block source
+delivery; it stays visible in the handoff with its receipt and retry command
+(`CLEANUP_PENDING` after delivered source). No task is described as cleaned
+while owned disposable files remain. On resumption, finish any pending scratch
+cleanup before allocating more temporary storage. Rebuild from retained inputs
+when needed; cleanup is not an instruction to restart parked work.
+
 ## Accept a scoped commit
 
 Direct work: finish actual decisive checks and diff review, stage only the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "3.1.1",
+  "version": "3.1.2",
   "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": {