devlyn-cli 3.1.1 → 3.1.3

package/config/skills/_shared/state-phase-write.py

@@ -308,6 +308,36 @@ def bind_process_evidence(
                 raise runner.EvidenceError(
                     "spec-verify.results.json commands must be an array"
                 )
+            preflight_failure = "preflight_failure" in results
+            if preflight_failure:
+                failure = results["preflight_failure"]
+                if (
+                    not isinstance(failure, dict)
+                    or set(failure) != {"run_id", "phase", "round", "findings"}
+                    or failure["run_id"] != state.get("run_id")
+                    or failure["phase"] != phase
+                    or type(failure["round"]) is not int
+                    or failure["round"] != runner.phase_round(state, phase)
+                ):
+                    raise runner.EvidenceError("BUILD_GATE preflight failure identity is invalid")
+                record = failure["findings"]
+                if not isinstance(record, dict) or set(record) != {"path", "sha256"}:
+                    raise runner.EvidenceError("BUILD_GATE preflight failure findings binding is invalid")
+                path = runner._checked_file(work, record["path"], "preflight failure findings")
+                raw = path.read_bytes()
+                if hashlib.sha256(raw).hexdigest() != record["sha256"]:
+                    raise runner.EvidenceError("BUILD_GATE preflight failure findings digest mismatch")
+                findings = [loads_strict_json(line) for line in raw.decode("utf-8").splitlines() if line.strip()]
+                if len(findings) != 1 or not isinstance(findings[0], dict) or (
+                    findings[0].get("phase") != phase
+                    or findings[0].get("severity") != "CRITICAL"
+                    or findings[0].get("rule_id") not in {
+                        "correctness.spec-verify-malformed", "correctness.risk-probe-integrity",
+                    }
+                ):
+                    raise runner.EvidenceError("BUILD_GATE preflight failure requires its CRITICAL finding")
+                if verdict not in {"FAIL", "BLOCKED"}:
+                    raise runner.EvidenceError("BUILD_GATE preflight failure requires FAIL or BLOCKED verdict")
             carrier = results.get("process_evidence")
             if carrier is None:
                 if commands:
@@ -315,43 +345,42 @@ def bind_process_evidence(
                         "BUILD_GATE commands exist without a process-evidence carrier"
                     )
                 manifest_path = work / runner.manifest_relative_path(state, phase)
-                if manifest_path.exists():
+                if os.path.lexists(manifest_path):
                     raise runner.EvidenceError(
                         "BUILD_GATE manifest exists without a process-evidence carrier"
                     )
-                if runner.mechanical_evidence_required(work, state):
+                if not preflight_failure and runner.mechanical_evidence_required(work, state):
                     raise runner.EvidenceError(
                         "required BUILD_GATE evidence has no process-evidence carrier"
                     )
-                state.setdefault("process_evidence", None)
-                return
-            round_ = runner.phase_round(state, phase)
-            manifest = carrier.get("manifest") if isinstance(carrier, dict) else None
-            if (
-                not isinstance(carrier, dict)
-                or carrier.get("phase") != phase
-                or carrier.get("round") != round_
-                or not isinstance(manifest, dict)
-                or manifest.get("path") != runner.manifest_relative_path(state, phase)
-            ):
-                raise runner.EvidenceError(
-                    "BUILD_GATE process-evidence carrier does not match the active run/round"
-                )
-            outcome = runner.validate_summary_commands(work, commands, carrier)
-            if outcome["verdict"] == "BLOCKED" and verdict != "BLOCKED":
-                denial = outcome["capability_denials"][0]
-                raise runner.EvidenceError(
-                    "BUILD_GATE capability denial requires BLOCKED verdict: "
-                    f"{denial['id']}:{denial['operation']}"
-                )
-            if (
-                outcome["verdict"] == "NEEDS_WORK"
-                and verdict in {"PASS", "PASS_WITH_ISSUES"}
-            ):
-                raise runner.EvidenceError(
-                    "BUILD_GATE process evidence mismatch cannot complete as "
-                    f"{verdict}: {','.join(outcome['failed_ids'])}"
-                )
+            else:
+                round_ = runner.phase_round(state, phase)
+                manifest = carrier.get("manifest") if isinstance(carrier, dict) else None
+                if (
+                    not isinstance(carrier, dict)
+                    or carrier.get("phase") != phase
+                    or carrier.get("round") != round_
+                    or not isinstance(manifest, dict)
+                    or manifest.get("path") != runner.manifest_relative_path(state, phase)
+                ):
+                    raise runner.EvidenceError(
+                        "BUILD_GATE process-evidence carrier does not match the active run/round"
+                    )
+                outcome = runner.validate_summary_commands(work, commands, carrier)
+                if outcome["verdict"] == "BLOCKED" and verdict != "BLOCKED":
+                    denial = outcome["capability_denials"][0]
+                    raise runner.EvidenceError(
+                        "BUILD_GATE capability denial requires BLOCKED verdict: "
+                        f"{denial['id']}:{denial['operation']}"
+                    )
+                if (
+                    outcome["verdict"] == "NEEDS_WORK"
+                    and verdict in {"PASS", "PASS_WITH_ISSUES"}
+                ):
+                    raise runner.EvidenceError(
+                        "BUILD_GATE process evidence mismatch cannot complete as "
+                        f"{verdict}: {','.join(outcome['failed_ids'])}"
+                    )
     except (runner.EvidenceError, OSError, UnicodeError, ValueError) as exc:
         raise SystemExit(f"BLOCKED:process-evidence-invalid: {exc}") from exc
     existing = state.get("process_evidence")
@@ -362,8 +391,11 @@ def bind_process_evidence(
     try:
         for prior in existing:
             runner.validate_bound_carrier(work, prior)
-    except runner.EvidenceError as exc:
+    except (runner.EvidenceError, OSError, UnicodeError, ValueError) as exc:
         raise SystemExit(f"BLOCKED:process-evidence-invalid: {exc}") from exc
+    if carrier is None:
+        state.setdefault("process_evidence", None)
+        return
     if any(
         isinstance(item, dict)
         and item.get("phase") == carrier["phase"]
@@ -2996,6 +3028,144 @@ def self_test() -> int:
 
         test_interrupted_build_gate()
 
+        def test_preflight_build_gate() -> None:
+            work = (devlyn / "preflight-build-gate").resolve()
+            active = work / ".devlyn"
+            active.mkdir(parents=True)
+            state_file = active / "pipeline.state.json"
+            results_file = active / "spec-verify.results.json"
+            checker = pathlib.Path(__file__).with_name("spec-verify-check.py")
+            env = {key: value for key, value in os.environ.items() if key not in {
+                "BENCH_WORKDIR", "SPEC_VERIFY_PHASE", "SPEC_VERIFY_FINDINGS_FILE",
+                "SPEC_VERIFY_FINDING_PREFIX",
+            } and not key.startswith("DEVLYN_INVOCATION_")}
+            runner = process_evidence_module()
+
+            def complete(verdict: str) -> subprocess.CompletedProcess[str]:
+                return subprocess.run(
+                    [sys.executable, str(pathlib.Path(__file__).resolve()),
+                     "--devlyn-dir", ".devlyn", "--phase", "build_gate", "complete",
+                     "--verdict", verdict, "--findings-file", ".devlyn/spec-verify-findings.jsonl"],
+                    cwd=work, env=env, capture_output=True, text=True, encoding="utf-8",
+                )
+
+            history = []
+            for round_, scenario in enumerate(("fresh", "language", "stale", "denied")):
+                fixture = {
+                    "version": "3.0", "run_id": "rs-preflight-build-gate",
+                    "source": {"type": "generated", "criteria_path": ".devlyn/criteria.generated.md"},
+                    "phases": {"build_gate": None}, "process_evidence": copy.deepcopy(history) or None,
+                }
+                do_spawn(fixture, "build_gate", round_, None, None, "claude", None)
+                write_state(state_file, fixture)
+                original_state = state_file.read_bytes()
+                results_file.unlink(missing_ok=True)
+                relative = runner.manifest_relative_path(fixture, "build_gate")
+                manifest = work / relative
+                obligation = {"id": "type-check", "phase": "build_gate",
+                              "argv": [sys.executable, "-c", "raise SystemExit(7)"]}
+                if scenario == "language":
+                    runner.capture_process(work, manifest, fixture["run_id"], "build_gate", round_, obligation)
+                elif scenario == "denied":
+                    runner.record_capability_denial(
+                        work, manifest, fixture["run_id"], "build_gate", round_, obligation,
+                        "subprocess", b"route denied subprocess",
+                    )
+                elif scenario == "stale":
+                    results_file.write_bytes(prior_results)
+                observed = {path: path.read_bytes() for path in manifest.parent.iterdir()} if manifest.exists() else {}
+                rejected = subprocess.run(
+                    [sys.executable, str(checker), "--include-risk-probes"],
+                    cwd=work, env=env, capture_output=True, text=True, encoding="utf-8",
+                )
+                assert rejected.returncode == 1 and "source.criteria_path" in rejected.stderr, rejected.stderr
+                results = loads_strict_json(results_file.read_text(encoding="utf-8"))
+                assert results["preflight_failure"]["round"] == round_
+                prior_results = results_file.read_bytes()
+                finding = active / "spec-verify-findings.jsonl"
+                finding_bytes = finding.read_bytes()
+                for verdict in ("PASS", "PASS_WITH_ISSUES", "NEEDS_WORK"):
+                    denied = complete(verdict)
+                    assert denied.returncode != 0 and "preflight failure requires" in denied.stderr, denied.stderr
+                    assert state_file.read_bytes() == original_state
+                if scenario == "denied":
+                    denied = complete("FAIL")
+                    assert denied.returncode != 0 and "capability denial requires BLOCKED" in denied.stderr
+                    assert state_file.read_bytes() == original_state
+                completed = complete("BLOCKED" if scenario == "denied" else "FAIL")
+                assert completed.returncode == 0, completed.stderr
+                bound = read_state(state_file)
+                assert bound["phases"]["build_gate"]["verdict"] == ("BLOCKED" if scenario == "denied" else "FAIL")
+                assert finding.read_bytes() == finding_bytes and results_file.read_bytes() == prior_results
+                assert {path: path.read_bytes() for path in observed} == observed
+                if observed:
+                    assert bound["process_evidence"] == [*history, results["process_evidence"]]
+                else:
+                    assert bound["process_evidence"] == (history or None) and results["commands"] == []
+                history = bound["process_evidence"] or []
+                for mutation in ("run", "phase", "round", "bool-round", "digest", "escape", "finding", "null"):
+                    state_file.write_bytes(original_state)
+                    altered = copy.deepcopy(results)
+                    failure = altered["preflight_failure"]
+                    if mutation in {"run", "phase", "round", "bool-round"}:
+                        field, value = {"run": ("run_id", "rs-other"), "phase": ("phase", "verify"),
+                                        "round": ("round", round_ + 1), "bool-round": ("round", True)}[mutation]
+                        failure[field] = value
+                    elif mutation == "null":
+                        altered["preflight_failure"] = None
+                    elif mutation == "finding":
+                        finding.write_bytes(b"{}\n")
+                        failure["findings"]["sha256"] = hashlib.sha256(finding.read_bytes()).hexdigest()
+                    else:
+                        failure["findings"]["path" if mutation == "escape" else "sha256"] = (
+                            "../outside.jsonl" if mutation == "escape" else "0" * 64
+                        )
+                    results_file.write_text(json.dumps(altered), encoding="utf-8")
+                    result = complete("FAIL")
+                    assert result.returncode != 0 and "BLOCKED:process-evidence-invalid" in result.stderr, (mutation, result.stderr)
+                    assert state_file.read_bytes() == original_state
+                    finding.write_bytes(finding_bytes)
+                results_file.write_bytes(prior_results)
+                if scenario in {"fresh", "stale"}:
+                    state_file.write_bytes(original_state)
+                    malformed_prior = read_state(state_file)
+                    malformed_prior["process_evidence"] = {}
+                    write_state(state_file, malformed_prior)
+                    before = state_file.read_bytes()
+                    invalid = complete("FAIL")
+                    assert invalid.returncode != 0 and "null or an array" in invalid.stderr, invalid.stderr
+                    assert state_file.read_bytes() == before
+                    state_file.write_bytes(original_state)
+                if scenario == "stale":
+                    prior_stream = work / history[0]["streams"][0]["stdout"]["path"]
+                    saved = prior_stream.read_bytes()
+                    prior_stream.write_bytes(b"altered prior observation")
+                    invalid = complete("FAIL")
+                    assert invalid.returncode != 0 and "mismatch" in invalid.stderr, invalid.stderr
+                    assert state_file.read_bytes() == original_state
+                    prior_stream.write_bytes(saved)
+                    from unittest.mock import patch
+                    read_bytes = pathlib.Path.read_bytes
+
+                    def unreadable_prior(path):
+                        if path == prior_stream:
+                            raise PermissionError("prior stream unreadable")
+                        return read_bytes(path)
+
+                    fixture = read_state(state_file)
+                    unchanged = copy.deepcopy(fixture)
+                    with patch.object(pathlib.Path, "read_bytes", unreadable_prior):
+                        try:
+                            bind_process_evidence(fixture, "build_gate", "FAIL", active, work)
+                        except SystemExit as exc:
+                            assert str(exc) == "BLOCKED:process-evidence-invalid: prior stream unreadable", exc
+                        else:
+                            raise AssertionError("unreadable prior evidence completed")
+                    assert fixture == unchanged and state_file.read_bytes() == original_state
+            print("PASS preflight rejection: actual checker-to-completion, success floors, identity/digest controls")
+
+        test_preflight_build_gate()
+
         # complete() before spawn() must fail loudly, not silently invent data.
         write_state(state_path, {"phases": {}})
         state = read_state(state_path)

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
 
@@ -686,6 +779,14 @@ else:
     raise SystemExit('unexpected gh arguments: '+str(a))
 '''
 
+GIT_DISPATCH = r'''#!/bin/sh
+for arg do
+    case "$arg" in push|fetch|ls-remote|remove) exec python3 "$0.py" "$@";; esac
+done
+exec "$REAL_GIT" "$@"
+'''
+
+
 GIT_WRAPPER = r'''#!/usr/bin/env python3
 import json, os, pathlib, subprocess, sys
 a = sys.argv[1:]
@@ -729,7 +830,7 @@ class CompletionTests(unittest.TestCase):
         for key in list(self.env):
             if key in {"GIT_DIR", "GIT_WORK_TREE", "GIT_INDEX_FILE", "GIT_COMMON_DIR"}:
                 del self.env[key]
-        for name, body in (("gh", FAKE_GH), ("git", GIT_WRAPPER)):
+        for name, body in (("gh", FAKE_GH), ("git.py", GIT_WRAPPER), ("git", GIT_DISPATCH)):
             path = self.bin / name
             path.write_text(body, encoding="utf-8")
             path.chmod(0o755)
@@ -770,11 +871,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 +1030,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 +1395,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"]()