devlyn-cli 3.1.1 → 3.1.3

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

@@ -21,7 +21,8 @@ Default mode (BUILD_GATE invocation, no args):
   (3) For generated criteria and legacy handwritten specs without a sibling,
       source markdown extract reads `pipeline.state.json:
       source.{spec_path | criteria_path}` and extracts a `## Verification`
-      ```json``` block. If present, overwrite `.devlyn/spec-verify.json`.
+      ```json``` block. Stage executable commands; an explicit pure-design
+      contract removes stale `.devlyn/spec-verify.json` instead.
   (4) If no json block in source AND source.type=="generated": emit
       CRITICAL `correctness.spec-verify-malformed` so the fix-loop reruns
       BUILD.
@@ -38,14 +39,13 @@ Default mode (BUILD_GATE invocation, no args):
   run-fixture.sh's combined-stream matching semantics.
 
 Check mode (`--check <markdown_path>`):
-- Used by /devlyn:ideate after writing each item spec to validate that the
-  generated `## Verification` ```json``` block parses + matches the schema,
-  and that present `complexity` frontmatter has a supported value.
-- Exits 0 if the block is well-formed (or absent — ideate's check applies
-  to both new specs that include the block and pre-carrier handwritten
-  specs that omit it; absence is not failure here, only malformed JSON or
-  shape error is). Exits 2 on malformed json, shape error, or unsupported
-  `complexity` value.
+- Spec-source authoring preflight: a present sibling `spec.expected.json`
+  takes precedence; otherwise validate the legacy inline carrier. Validate
+  metadata against the given Markdown path, including non-canonical names.
+- Exits 2 on malformed carrier or metadata, without falling back from a bad
+  sibling to inline content. An absent sibling and sentinel retain opt-in
+  success. Never stages or executes commands. Generated-source runtime has
+  its own inline validation and must not use this sibling-precedence route.
 
 Expected-contract check mode (`--check-expected <json_path>`):
 - Used by /devlyn:ideate after writing sibling `spec.expected.json`.
@@ -844,10 +844,28 @@ 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", "pure_design"})
+        if unknown:
+            return (
+                f"unsupported inline key(s): {', '.join(unknown)}; inline carriers "
+                "support only verification_commands and pure_design. Encode these checks as commands, "
+                "or use a real spec with sibling spec.expected.json."
+            )
+    error = validate_expected_shape(data)
+    if error:
+        return error
+    if isinstance(data, dict) and data.get("pure_design") is True:
+        if data.get("verification_commands") != []:
+            return "inline pure_design: true requires an explicit empty verification_commands list"
+        return None
+    return validate_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 +899,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:
@@ -1149,9 +1166,11 @@ def risk_probes_state_error(state: dict) -> str | None:
 
 
 def source_integrity_error(src_type: str | None, state: dict, source_md: Path | None) -> str | None:
+    src = state.get("source") if isinstance(state.get("source"), dict) else {}
     if source_md is None:
+        if src_type == "generated":
+            return f"source.criteria_path must identify an existing generated criteria file; declared path: {src.get('criteria_path')!r}."
         return None
-    src = state.get("source") if isinstance(state.get("source"), dict) else {}
     if src_type == "generated":
         field = "criteria_sha256"
         required = True
@@ -1188,33 +1207,33 @@ def load_expected_contract(expected_path: Path) -> tuple[dict | None, str | None
     return (data, None)
 
 
-def stage_from_source(md: Path, devlyn_dir: Path) -> tuple[bool, str | None]:
+def stage_from_source(md: Path, devlyn_dir: Path) -> tuple[bool, bool, str | None]:
     """Materialize .devlyn/spec-verify.json from the json block in `md`.
 
-    Returns (staged, error). staged=True → wrote spec-verify.json. error
-    non-None → carrier was found but malformed (caller emits CRITICAL) —
-    this now also covers a `<!-- devlyn:verification -->` sentinel present
-    with no fenced ```json``` block inside it (the author clearly intended a
-    contract; a missing fence is a mistake, not a no-op). staged=False,
-    error=None → the sentinel is absent entirely (handwritten spec or
-    generated source missing the contract).
+    Returns (found, staged, error). found=False means no sentinel. A present
+    sentinel without a valid fenced JSON contract returns an error. A valid
+    pure-design contract removes stale staging and returns (True, False, None);
+    executable commands return (True, True, None) after writing spec-verify.json.
     """
     section_found, block = extract_verification_block(md.read_text(encoding="utf-8"))
     if not section_found:
-        return (False, None)
+        return (False, False, None)
     if block is None:
-        return (False, f"`<!-- devlyn:verification -->` section in {md} has no fenced ```json``` block")
+        return (True, False, f"`<!-- devlyn:verification -->` section in {md} has no fenced ```json``` block")
     try:
         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)
+        return (True, False, f"`<!-- devlyn:verification -->` ```json``` block in {md} has invalid JSON: {e}")
+    err = validate_inline_shape(data)
     if err:
-        return (False, f"`<!-- devlyn:verification -->` ```json``` block in {md}: {err}")
+        return (True, False, f"`<!-- devlyn:verification -->` ```json``` block in {md}: {err}")
+    if data["verification_commands"] == []:
+        (devlyn_dir / "spec-verify.json").unlink(missing_ok=True)
+        return (True, False, None)
     normalized = {"verification_commands": data["verification_commands"]}
     devlyn_dir.mkdir(parents=True, exist_ok=True)
     (devlyn_dir / "spec-verify.json").write_text(json.dumps(normalized, indent=2) + "\n", encoding="utf-8")
-    return (True, None)
+    return (True, True, None)
 
 
 def stage_from_expected(
@@ -1236,6 +1255,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"
@@ -1322,7 +1344,7 @@ def diff_text_for_expected(work: Path, devlyn_dir: Path, state: dict) -> tuple[s
     external_diff = devlyn_dir / "external-diff.patch"
     if external_diff.is_file():
         try:
-            return (external_diff.read_text(encoding="utf-8"), None)
+            return (external_diff.read_text(encoding="utf-8", errors="surrogateescape"), None)
         except OSError as e:
             return ("", f"cannot read {external_diff}: {e}")
     base_sha = ((state.get("base_ref") or {}).get("sha") or "").strip()
@@ -1361,28 +1383,46 @@ def count_deps_added(work: Path, state: dict) -> int:
     return count
 
 
-def changed_files(work: Path, state: dict, devlyn_dir: Path) -> list[str]:
+def changed_files(work: Path, state: dict, devlyn_dir: Path) -> tuple[list[str], str | None]:
     external_diff = devlyn_dir / "external-diff.patch"
     if external_diff.is_file():
         names: list[str] = []
         try:
-            external_text = external_diff.read_text(encoding="utf-8")
-        except OSError:
-            return []
-        for line in external_text.splitlines():
-            if line.startswith("diff --git "):
-                parts = line.split()
-                if len(parts) >= 4:
-                    names.append(parts[3].removeprefix("b/"))
-        return names
+            external_bytes = external_diff.read_bytes()
+        except OSError as error:
+            return ([], f"cannot read {external_diff}: {error}")
+        if not external_bytes:
+            return ([], None)
+        # Prefix depth is otherwise ambiguous (src/x becomes x with -p1).
+        headers = [line for line in external_bytes.split(b"\n") if line.startswith(b"diff --git ")]
+        if not headers or any(not re.fullmatch(
+            rb'diff --git (a/[^"\r]*|"a/(?:[^"\\]|\\.)*") (b/[^"\r]*|"b/(?:[^"\\]|\\.)*")\r?', line,
+        ) for line in headers):
+            return ([], "external diff requires Git a/ and b/ path prefixes; regenerate with git diff --binary --src-prefix=a/ --dst-prefix=b/")
+        # Statistics mode never applies the patch. Reverse parsing includes
+        # rename sources as well as destinations without parsing quoted headers.
+        for direction in ([], ["--reverse"]):
+            proc = subprocess.run(
+                ["git", "apply", "--numstat", "-z", "-p1", "--whitespace=nowarn", *direction], cwd=str(work),
+                input=external_bytes, capture_output=True,
+            )
+            if proc.returncode != 0:
+                return ([], (proc.stderr or proc.stdout).decode("utf-8", "replace").strip() or "git apply --numstat failed")
+            for record in proc.stdout.split(b"\0"):
+                if record:
+                    fields = record.split(b"\t", 2)
+                    if len(fields) != 3 or not fields[2]:
+                        return ([], "invalid git apply --numstat path record")
+                    names.append(fields[2].decode("utf-8", "surrogateescape"))
+        return (list(dict.fromkeys(names)), None)
     base_sha = ((state.get("base_ref") or {}).get("sha") or "").strip()
-    cmd = ["git", "diff", "--name-only"]
+    cmd = ["git", "diff", "--name-only", "-z", "--no-renames"]
     if base_sha:
         cmd.append(base_sha)
-    proc = subprocess.run(cmd, cwd=str(work), capture_output=True, text=True, encoding="utf-8")
+    proc = subprocess.run(cmd, cwd=str(work), capture_output=True)
     if proc.returncode != 0:
-        return []
-    return [line.strip() for line in (proc.stdout or "").splitlines() if line.strip()]
+        return ([], (proc.stderr or proc.stdout).decode("utf-8", "replace").strip() or "git diff --name-only failed")
+    return ([path.decode("utf-8", "surrogateescape") for path in proc.stdout.split(b"\0") if path], None)
 
 
 def expected_contract_findings(
@@ -1398,6 +1438,8 @@ def expected_contract_findings(
     findings: list[dict] = []
     seq = finding_start
     diff_text, diff_error = diff_text_for_expected(work, devlyn_dir, state)
+    paths, paths_error = changed_files(work, state, devlyn_dir) if expected_data.get("forbidden_files") else ([], None)
+    diff_error = diff_error or paths_error
     if diff_error and (
         expected_data.get("forbidden_patterns") or expected_data.get("forbidden_files")
     ):
@@ -1407,12 +1449,12 @@ def expected_contract_findings(
             "level": "error",
             "severity": "CRITICAL",
             "confidence": 1.0,
-            "message": f"Cannot compute diff for forbidden_patterns: {diff_error}",
+            "message": f"Cannot compute diff for expected contract: {diff_error}",
             "file": str(expected_path or "spec.expected.json"),
             "line": 1,
             "phase": output_phase(),
-            "criterion_ref": "spec.expected.json/forbidden_patterns",
-            "fix_hint": "Ensure pipeline.state.json has base_ref.sha or provide .devlyn/external-diff.patch.",
+            "criterion_ref": "spec.expected.json/forbidden_files" if paths_error else "spec.expected.json/forbidden_patterns",
+            "fix_hint": "Ensure base_ref.sha is valid and any external-diff.patch is a readable Git patch with a/ and b/ prefixes.",
             "blocking": True,
             "status": "open",
         })
@@ -1438,7 +1480,7 @@ def expected_contract_findings(
             "status": "open",
         })
         seq += 1
-    changed = set(changed_files(work, state, devlyn_dir))
+    changed = set(paths)
     for i, required in enumerate(expected_data.get("required_files", []) or []):
         if (work / required).exists():
             continue
@@ -1757,7 +1799,16 @@ def authorized_surface_findings(
 
     findings: list[dict] = []
     seq = finding_start
-    for path in changed_files(work, state, devlyn_dir):
+    paths, paths_error = changed_files(work, state, devlyn_dir)
+    if paths_error is not None:
+        return ([scope_finding(
+            finding_start,
+            "scope.authorized-surface-malformed",
+            f"Cannot read changed files: {paths_error}",
+            ".devlyn/external-diff.patch" if (devlyn_dir / "external-diff.patch").is_file() else ".devlyn/pipeline.state.json",
+            "Ensure base_ref.sha is valid and any external-diff.patch is a readable Git patch with a/ and b/ prefixes.",
+        )], finding_start + 1)
+    for path in paths:
         if path_matches_surface(path, surface):
             continue
         findings.append(scope_finding(
@@ -1846,13 +1897,8 @@ def run_write_untracked_baseline(work: Path, devlyn_dir: Path) -> int:
 
 
 def run_check_mode(md_path: Path) -> int:
-    """`--check <markdown>` — validate the verification carrier without
-    running any commands. Used by /devlyn:ideate after item-spec write.
-
-    Exit 0: `<!-- devlyn:verification -->` sentinel absent OR section present
-    and well-formed.
-    Exit 2: sentinel present but the section is malformed — no fenced json
-    block, invalid JSON, or bad shape (so ideate can re-prompt).
+    """Validate a spec's authoritative sibling or legacy inline carrier;
+    return 0/2 without staging or execution. This is not generated-mode staging.
     """
     if not md_path.is_file():
         print(f"[spec-verify --check] error: {md_path} not found", file=sys.stderr)
@@ -1870,6 +1916,14 @@ def run_check_mode(md_path: Path) -> int:
     if solo_ceiling_err:
         print(f"[spec-verify --check] {md_path}: {solo_ceiling_err}", file=sys.stderr)
         return 2
+    expected_path = md_path.with_name("spec.expected.json")
+    if expected_path.is_file():
+        data, err = load_expected_contract(expected_path)
+        err = err or validate_expected_against_sibling_spec(md_path, data)
+        if err:
+            print(f"[spec-verify --check] {md_path}: sibling {expected_path}: {err}", file=sys.stderr)
+            return 2
+        return 0
     section_found, block = extract_verification_block(text)
     if not section_found:
         # Sentinel absent entirely — opt-in nature preserved for ideate (a
@@ -1892,7 +1946,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 +1969,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
@@ -2047,7 +2101,7 @@ def run_self_test() -> int:
                 + "\n```\n",
                 encoding="utf-8",
             )
-            staged, inline_error = stage_from_source(
+            _found, staged, inline_error = stage_from_source(
                 inline_timeout_spec, inline_timeout_devlyn
             )
             if staged or not inline_error or "timeout_sec" not in inline_error:
@@ -2067,7 +2121,7 @@ def run_self_test() -> int:
             + "\n```\n",
             encoding="utf-8",
         )
-        staged, inline_error = stage_from_source(
+        _found, staged, inline_error = stage_from_source(
             inline_timeout_spec, inline_timeout_devlyn
         )
         inline_staged = loads_strict_json(
@@ -3628,6 +3682,56 @@ def run_self_test() -> int:
             "```\n",
             encoding="utf-8",
         )
+        generated_raw = generated_criteria.read_bytes()
+        generated_criteria.unlink()
+        missing_source_marker = generated_user / "missing-source-command-ran"
+        for pointer, bench, phase in (
+            ({}, False, "build_gate"),
+            ({"criteria_path": None}, False, "build_gate"),
+            ({"criteria_path": ""}, False, "build_gate"),
+            ({"criteria_path": ".devlyn/criteria.generated.md"}, False, "build_gate"),
+            ({"criteria_path": str(generated_criteria)}, False, "build_gate"),
+            ({"criteria_path": str(generated_user)}, False, "build_gate"),
+            ({"criteria_path": str(generated_criteria)}, True, "build_gate"),
+            ({"criteria_path": str(generated_criteria)}, False, "verify_mechanical"),
+        ):
+            (generated_devlyn / "pipeline.state.json").write_text(json.dumps({
+                "source": {"type": "generated", "criteria_sha256": hashlib.sha256(generated_raw).hexdigest(), **pointer},
+                "risk_profile": {"risk_probes_enabled": True},
+            }), encoding="utf-8")
+            (generated_devlyn / "spec-verify.json").write_text(json.dumps({
+                "verification_commands": [{"cmd": "printf unexpected > missing-source-command-ran"}],
+            }), encoding="utf-8")
+            (generated_devlyn / "spec-verify.results.json").unlink(missing_ok=True)
+            missing_source_env = dict(os.environ, SPEC_VERIFY_PHASE=phase)
+            if bench:
+                missing_source_env["BENCH_WORKDIR"] = str(generated_user)
+            missing_source_run = subprocess.run(
+                [sys.executable, script_path, "--include-risk-probes"],
+                cwd=generated_user, env=missing_source_env,
+                capture_output=True, text=True, encoding="utf-8",
+            )
+            if (
+                missing_source_run.returncode != 1
+                or "source.criteria_path" not in missing_source_run.stderr
+                or f"declared path: {pointer.get('criteria_path')!r}" not in missing_source_run.stderr
+            ):
+                print(f"missing generated source was not rejected: {pointer}, {bench}, {phase}: {missing_source_run.stderr}", file=sys.stderr)
+                return 1
+            missing_findings = [loads_strict_json(line) for line in
+                                (generated_devlyn / output_findings_name()).read_text(encoding="utf-8").splitlines()]
+            if (
+                len(missing_findings) != 1
+                or missing_findings[0]["rule_id"] != "correctness.spec-verify-malformed"
+                or missing_findings[0]["severity"] != "CRITICAL"
+                or missing_findings[0]["file"] != ".devlyn/pipeline.state.json"
+                or missing_findings[0]["phase"] != phase
+                or missing_source_marker.exists()
+                or (generated_devlyn / "spec-verify.results.json").exists() != (phase == "build_gate")
+            ):
+                print(f"missing generated source lost its finding or executed a stale command: {missing_findings}", file=sys.stderr)
+                return 1
+        generated_criteria.write_bytes(generated_raw)
         (generated_devlyn / "pipeline.state.json").write_text(json.dumps({
             "source": {"type": "generated", "criteria_path": str(generated_criteria)}
         }), encoding="utf-8")
@@ -3691,6 +3795,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",
@@ -3735,6 +3887,13 @@ def run_self_test() -> int:
         (real_devlyn / "pipeline.state.json").write_text(json.dumps({
             "source": {"type": "spec", "spec_path": str(real_spec)}
         }), encoding="utf-8")
+        sibling_check = subprocess.run(
+            [sys.executable, script_path, "--check", str(real_spec)],
+            cwd=real_user, capture_output=True, text=True, encoding="utf-8",
+        )
+        if sibling_check.returncode != 0 or (real_devlyn / "spec-verify.json").exists():
+            print(f"sibling authoring failed or staged commands: {sibling_check.stderr}", file=sys.stderr)
+            return 1
         sibling_run = subprocess.run(
             [sys.executable, script_path],
             cwd=real_user,
@@ -3750,6 +3909,140 @@ 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"
+        pure_contract = {"pure_design": True, "verification_commands": []}
+        for name, filename, source, contract, expected_rule, source_type in (
+            ("pure-prose", "spec.md", pure_prose, {"pure_design": True}, None, "spec"),
+            ("pure-inline", "design-notes.md", pure_inline, {"pure_design": True, "verification_commands": []}, None, "spec"),
+            ("pure-bad-inline", "design-notes.md", pure_prose + "\n```json\n{broken\n```\n", {"pure_design": True}, None, "spec"),
+            ("empty-runtime", "design-notes.md", pure_inline, {"verification_commands": []}, "correctness.spec-verify-malformed", "spec"),
+            ("contradictory-pure", "spec.md", pure_inline, {"pure_design": True, **stale_command}, "correctness.spec-verify-malformed", "spec"),
+            ("pure-required-file", "spec.md", pure_inline, {"pure_design": True, "required_files": ["missing.md"]}, "correctness.required-file-missing", "spec"),
+            ("generated-pure", ".devlyn/criteria.generated.md", pure_contract, None, None, "generated"),
+            ("legacy-inline-pure", "design-notes.md", pure_contract, None, None, "spec"),
+            ("generated-empty-section", ".devlyn/criteria.generated.md", pure_prose, None, "correctness.spec-verify-malformed", "generated"),
+            ("generated-unmarked-empty", ".devlyn/criteria.generated.md", {"verification_commands": []}, None, "correctness.spec-verify-malformed", "generated"),
+            ("generated-false-empty", ".devlyn/criteria.generated.md", {**pure_contract, "pure_design": False}, None, "correctness.spec-verify-malformed", "generated"),
+            ("generated-missing-list", ".devlyn/criteria.generated.md", {"pure_design": True}, None, "correctness.spec-verify-malformed", "generated"),
+            ("generated-nonboolean-pure", ".devlyn/criteria.generated.md", {**pure_contract, "pure_design": 1}, None, "correctness.spec-verify-malformed", "generated"),
+            ("generated-contradictory-pure", ".devlyn/criteria.generated.md", {**stale_command, "pure_design": True}, None, "correctness.spec-verify-malformed", "generated"),
+            ("generated-unsupported-field", ".devlyn/criteria.generated.md", {**pure_contract, "required_files": ["missing.md"]}, None, "correctness.spec-verify-malformed", "generated"),
+        ):
+            case_root = work / name
+            case_root.mkdir()
+            case_devlyn = case_root / ".devlyn"
+            case_devlyn.mkdir()
+            case_spec = case_root / filename
+            if isinstance(source, dict):
+                source = pure_prose + "\n```json\n" + json.dumps(source) + "\n```\n"
+            case_spec.write_text(source, encoding="utf-8")
+            if contract is not None:
+                (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")
+            pointer = "criteria" if source_type == "generated" else "spec"
+            (case_devlyn / "pipeline.state.json").write_text(json.dumps({
+                "source": {"type": source_type, pointer + "_path": str(case_spec),
+                           pointer + "_sha256": hashlib.sha256(case_spec.read_bytes()).hexdigest()},
+            }), encoding="utf-8")
+            case_check = subprocess.run(
+                [sys.executable, script_path, "--check", str(case_spec)],
+                cwd=case_root, capture_output=True, text=True, encoding="utf-8",
+            )
+            if case_check.returncode != (2 if expected_rule == "correctness.spec-verify-malformed" else 0):
+                print(f"{name}: authoring returned {case_check.returncode}: {case_check.stderr}", file=sys.stderr)
+                return 1
+            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}: contract 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 contract findings: {case_findings}", file=sys.stderr)
+                return 1
+            case_results = case_devlyn / "spec-verify.results.json"
+            if expected_rule == "correctness.spec-verify-malformed":
+                rejected_results = loads_strict_json(case_results.read_text(encoding="utf-8"))
+                if (rejected_results["commands"] != [] or rejected_results["process_evidence"] is not None
+                    or "preflight_failure" not in rejected_results):
+                    print(f"{name}: malformed contract 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 contract ran or retained a stale command", file=sys.stderr)
+                return 1
+
+        generated_root = work / "generated-pure"
+        generated_devlyn = generated_root / ".devlyn"
+        for prestaged in (False, True):
+            if prestaged:
+                (generated_devlyn / "spec-verify.json").write_text(json.dumps(pure_contract), encoding="utf-8")
+            bench_pure = subprocess.run(
+                [sys.executable, script_path], cwd=generated_root,
+                env=dict(os.environ, BENCH_WORKDIR=str(generated_root)),
+                capture_output=True, text=True, encoding="utf-8",
+            )
+            if bench_pure.returncode != (1 if prestaged else 0):
+                print(f"pure-design benchmark precedence changed: {bench_pure.stderr}", file=sys.stderr)
+                return 1
+            if prestaged and "verification_commands must contain at least one entry" not in bench_pure.stderr:
+                print(f"prestaged empty benchmark did not fail command validation: {bench_pure.stderr}", file=sys.stderr)
+                return 1
+
+        generated_state_path = generated_devlyn / "pipeline.state.json"
+        generated_state = loads_strict_json(generated_state_path.read_text(encoding="utf-8"))
+        generated_state["risk_profile"] = {"risk_probes_enabled": True, "risk_probes_explicit": True}
+        generated_state_path.write_text(json.dumps(generated_state), encoding="utf-8")
+        missing_pure_probe = subprocess.run(
+            [sys.executable, script_path, "--include-risk-probes"], cwd=generated_root,
+            capture_output=True, text=True, encoding="utf-8",
+        )
+        if missing_pure_probe.returncode != 1 or "risk probes integrity failed" not in missing_pure_probe.stderr:
+            print(f"pure-design contract bypassed required probes: {missing_pure_probe.stderr}", file=sys.stderr)
+            return 1
+
+        generated_source = generated_devlyn / "criteria.generated.md"
+        generated_source.write_text(
+            generated_source.read_text(encoding="utf-8") + "\n- probe must pass visible marker.\n",
+            encoding="utf-8",
+        )
+        generated_state["source"]["criteria_sha256"] = hashlib.sha256(generated_source.read_bytes()).hexdigest()
+        (generated_devlyn / "probes").mkdir()
+        (generated_devlyn / "probes/P1.py").write_bytes(probe_script.read_bytes())
+        (generated_devlyn / "risk-probes.jsonl").write_text(json.dumps(risk_probe_payload) + "\n", encoding="utf-8")
+        generated_state["risk_probes_digest"], pure_probe_error = risk_probes_digest(generated_devlyn)
+        if pure_probe_error:
+            print(pure_probe_error, file=sys.stderr)
+            return 1
+        generated_state_path.write_text(json.dumps(generated_state), encoding="utf-8")
+        valid_pure_probe = subprocess.run(
+            [sys.executable, script_path, "--include-risk-probes"], cwd=generated_root,
+            capture_output=True, text=True, encoding="utf-8",
+        )
+        if valid_pure_probe.returncode != 0:
+            print(f"pure-design contract did not execute valid probe: {valid_pure_probe.stderr}", file=sys.stderr)
+            return 1
+        pure_probe_results = loads_strict_json((generated_devlyn / "spec-verify.results.json").read_text(encoding="utf-8"))
+        if (
+            len(pure_probe_results["commands"]) != 1
+            or pure_probe_results["commands"][0]["evidence_id"] != "risk-probe-0001"
+            or not pure_probe_results["commands"][0]["pass"]
+            or pure_probe_results["process_evidence"] is None
+            or (generated_devlyn / "spec-verify.json").exists()
+        ):
+            print("pure-design probe did not retain exactly one verified process result", file=sys.stderr)
+            return 1
+
         malformed = work / "malformed-sibling"
         malformed.mkdir()
         malformed_devlyn = malformed / ".devlyn"
@@ -3788,7 +4081,7 @@ def run_self_test() -> int:
         }), encoding="utf-8")
         (devlyn / "spec-verify.json").write_text(json.dumps({
             "verification_commands": [
-                {"cmd": "printf bench-staged", "stdout_contains": ["bench-staged"]}
+                {"cmd": "printf bench-staged", "stdout_contains": ["bench-staged"], "contract_refs": ["R1"]}
             ]
         }) + "\n", encoding="utf-8")
         bench_pre_staged = subprocess.run(
@@ -3807,6 +4100,38 @@ def run_self_test() -> int:
             print("benchmark pre-staged contract was overwritten", file=sys.stderr)
             return 1
 
+        bench_marker = work / "bench-command-ran"
+        bench_command = {"cmd": "printf bad > bench-command-ran; printf bad"}
+        for phase in ("build_gate", "verify_mechanical"):
+            for carrier, diagnostic in (
+                ({"verification_commands": [{**bench_command, "stdout_not_contians": ["bad"]}]}, "unknown key(s): stdout_not_contians"),
+                ({"verification_commands": [{**bench_command, "contract_refs": [""]}]}, "contract_refs must be a list of non-empty strings"),
+                ({"verification_commands": [bench_command], "required_files": ["missing.txt"]}, "unsupported inline key(s): required_files"),
+                ({"verification_commands": [bench_command], "pure_design": True}, "requires an explicit empty verification_commands list"),
+                ({"verification_commands": [], "pure_design": True}, "must contain at least one entry"),
+            ):
+                (devlyn / "spec-verify.json").write_text(json.dumps(carrier), encoding="utf-8")
+                old_bench_results = (devlyn / "spec-verify.results.json").read_bytes()
+                rejected_bench = subprocess.run(
+                    [sys.executable, script_path], cwd=work,
+                    env={**env, "SPEC_VERIFY_PHASE": phase},
+                    capture_output=True, text=True, encoding="utf-8",
+                )
+                rejected_findings = [loads_strict_json(line) for line in
+                                     (devlyn / output_findings_name()).read_text(encoding="utf-8").splitlines()]
+                if (
+                    rejected_bench.returncode != 1 or diagnostic not in rejected_bench.stderr
+                    or bench_marker.exists()
+                    or (phase == "verify_mechanical" and
+                        (devlyn / "spec-verify.results.json").read_bytes() != old_bench_results)
+                    or len(rejected_findings) != 1
+                    or rejected_findings[0]["rule_id"] != "correctness.spec-verify-malformed"
+                    or rejected_findings[0]["severity"] != "CRITICAL"
+                    or rejected_findings[0]["phase"] != phase
+                ):
+                    print(f"benchmark {phase} failed closed incorrectly for {carrier}: {rejected_bench.stderr}", file=sys.stderr)
+                    return 1
+
         verify_output = work / "verify-output"
         verify_output.mkdir()
         verify_devlyn = verify_output / ".devlyn"
@@ -4442,6 +4767,84 @@ def run_self_test() -> int:
             print("atomic_batch_state without success-order evidence was accepted", file=sys.stderr)
             return 1
 
+        # Literal diff paths must survive Git quoting, renames and both consumers.
+        literal_root = work / "literal-paths"
+        literal_root.mkdir()
+        literal_devlyn = literal_root / ".devlyn"
+        literal_devlyn.mkdir()
+        (literal_root / ".gitignore").write_text(".devlyn/\n", encoding="utf-8")
+        literal_names = ["plain.txt", "설정.txt", "my file.txt"]
+        if os.name != "nt":
+            literal_names += ["a\tb.txt", "a\nb.txt", " leading.txt", "trailing.txt ", 'quote".txt', "back\\slash.txt", "literal*.txt"]
+        for name in literal_names + ["old name.txt"]:
+            (literal_root / name).write_text("original\n", encoding="utf-8")
+        subprocess.run(["git", "init", "-q"], cwd=literal_root, check=True)
+        subprocess.run(["git", "add", "-A"], cwd=literal_root, check=True)
+        subprocess.run(["git", "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-qm", "base"], cwd=literal_root, check=True)
+        for name in literal_names:
+            (literal_root / name).write_text("updated\n", encoding="utf-8")
+        subprocess.run(["git", "mv", "old name.txt", "new name.txt"], cwd=literal_root, check=True)
+        literal_names += ["old name.txt", "new name.txt"]
+        literal_state = {"base_ref": {"sha": "HEAD"}}
+        literal_expected = {"forbidden_files": literal_names}
+        (literal_devlyn / "untracked.baseline").write_text("", encoding="utf-8")
+        (literal_devlyn / "plan.md").write_text(
+            "<!-- devlyn:authorized-surface -->\n## Files to touch\n\n```json\n"
+            + json.dumps({"authorized_surface": literal_names}) + "\n```\n", encoding="utf-8",
+        )
+        literal_patch = subprocess.check_output(
+            ["git", "diff", "--binary", "--src-prefix=a/", "--dst-prefix=b/", "HEAD"], cwd=literal_root,
+        )
+        literal_external = literal_devlyn / "external-diff.patch"
+        for external in (False, True):
+            if external:
+                literal_external.write_bytes(literal_patch)
+            hits, _ = expected_contract_findings(literal_expected, None, literal_root, literal_devlyn, literal_state, 1)
+            assert len(hits) == len(literal_names) and all(hit["rule_id"] == "scope.forbidden-file-touched" for hit in hits), hits
+            scope_hits, _ = authorized_surface_findings(literal_root, literal_devlyn, literal_state, 1)
+            assert not scope_hits, scope_hits
+        edit = b"diff --git a/plain.txt b/plain.txt\n--- a/plain.txt\n+++ b/plain.txt\n@@ -1 +1 @@\n-original\n+updated\n"
+        (literal_devlyn / "plan.md").write_text(
+            '<!-- devlyn:authorized-surface -->\n## Files to touch\n\n```json\n{"authorized_surface":["untouched.txt"]}\n```\n', encoding="utf-8",
+        )
+        literal_external.write_bytes(edit)
+        scope_hits, _ = authorized_surface_findings(literal_root, literal_devlyn, literal_state, 1)
+        assert len(scope_hits) == 1 and scope_hits[0]["rule_id"] == "scope.out-of-scope-file", scope_hits
+        literal_external.write_bytes(edit.replace(b"+updated", b"+updated  "))
+        subprocess.run(["git", "config", "apply.whitespace", "error"], cwd=literal_root, check=True)
+        try:
+            names, error = changed_files(literal_root, literal_state, literal_devlyn)
+            assert names == ["plain.txt"] and error is None, (names, error)
+        finally:
+            subprocess.run(["git", "config", "--unset", "apply.whitespace"], cwd=literal_root, check=True)
+        for patch, paths in (
+            (b"", []),
+            (edit.replace(b"\n", b"\r\n"), ["plain.txt"]),
+            (b"diff --git a/logo.png b/logo.png\nindex 1111111..2222222 100644\nBinary files a/logo.png and b/logo.png differ\n", ["logo.png"]),
+            (b"diff --git a/script b/script\nold mode 100644\nnew mode 100755\n", ["script"]),
+            (b"diff --git a/keep.py b/new.py\nsimilarity index 100%\ncopy from keep.py\ncopy to new.py\n", ["new.py", "keep.py"]),
+        ):
+            literal_external.write_bytes(patch)
+            names, error = changed_files(literal_root, literal_state, literal_devlyn)
+            assert names == paths and error is None, (names, error)
+        for bad_patch in (
+            b"not a patch\n", b"\n", edit[:-5],
+            edit.replace(b"a/plain.txt", b"plain.txt").replace(b"b/plain.txt", b"plain.txt"),
+            edit.replace(b"a/plain.txt", b"src/plain.txt").replace(b"b/plain.txt", b"src/plain.txt"),
+            edit.replace(b"a/plain.txt", b"i/plain.txt").replace(b"b/plain.txt", b"w/plain.txt"),
+        ):
+            literal_external.write_bytes(bad_patch)
+            hits, _ = expected_contract_findings(literal_expected, None, literal_root, literal_devlyn, literal_state, 1)
+            assert len(hits) == 1 and hits[0]["rule_id"] == "correctness.expected-contract-unverifiable", hits
+            scope_hits, _ = authorized_surface_findings(literal_root, literal_devlyn, literal_state, 1)
+            assert len(scope_hits) == 1 and scope_hits[0]["file"] == ".devlyn/external-diff.patch", scope_hits
+        literal_external.unlink()
+        names, error = changed_files(literal_root, {"base_ref": {"sha": "missing-literal-ref"}}, literal_devlyn)
+        assert not names and error, (names, error)
+        assert subprocess.check_output(
+            ["git", "diff", "--binary", "--src-prefix=a/", "--dst-prefix=b/", "HEAD"], cwd=literal_root,
+        ) == literal_patch
+
         # iter-0046: PLAN-declared authorized_surface enforced at BUILD_GATE.
         scope_root = work / "scope-gate"
         scope_root.mkdir()
@@ -4856,7 +5259,8 @@ def main() -> int:
     #      continue to legacy source-extract.
     #   3. Source-extract reads
     #      `pipeline.state.json:source.{spec_path | criteria_path}`. If it has
-    #      a json block, overwrite .devlyn/spec-verify.json with it.
+    #      a json block, stage its commands or clear stale staging for an
+    #      explicit pure-design contract.
     #   4. If source has no json block AND source.type=="generated":
     #      CRITICAL spec-verify-malformed — generated criteria must ship a
     #      verifiable contract per the generated-criteria output contract.
@@ -4871,6 +5275,39 @@ def main() -> int:
     trust_bench_staged = bench_mode and pre_staged
     src_type, source_md = read_source(work, devlyn_dir)
     state = read_state(devlyn_dir)
+
+    def reject_preflight() -> int:
+        # A completed rejection is not an interrupted checker. Preserve actual
+        # earlier gate observations without inventing an executed command.
+        if validate_risk_probes_only or output_phase() != "build_gate":
+            return 1
+        runner = process_evidence_module()
+        phase, run_id, round_, relative = mechanical_evidence_identity(state, runner)
+        carrier = None
+        try:
+            if os.path.lexists(work / relative):
+                carrier = runner.validate_manifest(
+                    work, relative, run_id, phase, round_, require_expectations=False,
+                )
+            findings = devlyn_dir / output_findings_name()
+            result = {
+                "commands": runner.bound_carrier_summary_commands(work, carrier) if carrier else [],
+                "process_evidence": carrier,
+                "preflight_failure": {
+                    "run_id": run_id, "phase": phase, "round": round_,
+                    "findings": {
+                        "path": findings.relative_to(work).as_posix(),
+                        "sha256": hashlib.sha256(findings.read_bytes()).hexdigest(),
+                    },
+                },
+            }
+            (devlyn_dir / "spec-verify.results.json").write_text(
+                json.dumps(result, indent=2) + "\n", encoding="utf-8",
+            )
+        except (runner.EvidenceError, OSError, UnicodeError, ValueError) as exc:
+            print(f"[spec-verify] rejection evidence could not be finalized: {exc}", file=sys.stderr)
+        return 1
+
     external_diff = devlyn_dir / "external-diff.patch"
     if external_diff.is_file() and state.get("mode") != "verify-only":
         error = (
@@ -4888,14 +5325,15 @@ def main() -> int:
                 "intentionally verifying an external patch."
             ),
         )
-        return 1
+        return reject_preflight()
     integrity_error = source_integrity_error(src_type, state, source_md)
     if integrity_error:
         print(f"[spec-verify] carrier malformed: {integrity_error}", file=sys.stderr)
         write_malformed_finding(devlyn_dir, integrity_error, source_md)
-        return 1
+        return reject_preflight()
     expected_data: dict | None = None
     expected_path: Path | None = None
+    contract_found = False
     if validate_risk_probes_only:
         _risk_probes, risk_error = load_risk_probes(
             devlyn_dir, source_md, require_present=True
@@ -4903,29 +5341,29 @@ def main() -> int:
         if risk_error:
             print(f"[spec-verify] risk probes malformed: {risk_error}", file=sys.stderr)
             write_malformed_finding(devlyn_dir, risk_error, devlyn_dir / "risk-probes.jsonl")
-            return 1
+            return reject_preflight()
         print("[spec-verify] risk probes valid", file=sys.stderr)
         return 0
     if source_md is not None and not trust_bench_staged:
         if src_type == "spec":
-            expected_found, expected_staged, expected_error, expected_path, expected_data = stage_from_expected(
+            contract_found, _staged, expected_error, expected_path, expected_data = stage_from_expected(
                 source_md, devlyn_dir
             )
             if expected_error is not None:
                 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)
+                return reject_preflight()
+            if contract_found:
+                error = None
             else:
-                staged, error = stage_from_source(source_md, devlyn_dir)
+                contract_found, _staged, error = stage_from_source(source_md, devlyn_dir)
         else:
-            staged, error = stage_from_source(source_md, devlyn_dir)
+            contract_found, _staged, error = stage_from_source(source_md, devlyn_dir)
         if error is not None:
             print(f"[spec-verify] carrier malformed: {error}", file=sys.stderr)
             write_malformed_finding(devlyn_dir, error, source_md)
-            return 1
-        if not staged:
+            return reject_preflight()
+        if not contract_found:
             if src_type == "generated":
                 msg = (
                     f"generated {source_md.name} must include a "
@@ -4934,9 +5372,9 @@ def main() -> int:
                 )
                 print(f"[spec-verify] {msg}", file=sys.stderr)
                 write_malformed_finding(devlyn_dir, msg, source_md)
-                return 1
+                return reject_preflight()
             # source.type=="spec", no block in spec markdown.
-            if not bench_mode and expected_data is None:
+            if not bench_mode:
                 # Real-user handwritten spec: silent no-op. Drop any stale
                 # pre-staged file so a killed prior run cannot poison this
                 # run's gate.
@@ -4958,11 +5396,10 @@ def main() -> int:
 
     commands: list[dict] = []
     if not spec_path.exists():
-        # No source markdown carrier AND no pre-staged file. Silent no-op
-        # for benchmark misconfigurations (no fixture to gate against) and
-        # for real-user runs without spec/criteria. Generated source case
-        # is handled above.
-        if expected_data is None:
+        # A declared pure-design contract continues through probes/results.
+        # Missing handwritten/benchmark contracts remain an opt-in no-op;
+        # missing generated contracts were rejected above.
+        if not contract_found:
             return 0
     else:
         try:
@@ -4971,27 +5408,26 @@ def main() -> int:
             print(f"[spec-verify] error: cannot parse {spec_path}: {e}", file=sys.stderr)
             return 2
 
-        # iter-0019.8 (Codex R2 #2): apply full shape validation to pre-staged
-        # carriers too — bool exit_code, empty list, whitespace-only cmd were
-        # silently accepted on the benchmark path. Empty list is rejected
-        # because "all 0 commands passed" is vacuously true.
-        shape_err = validate_shape(spec)
+        # Pre-staged commands need the strict carrier vocabulary too: unknown
+        # expectations were silently ignored. Keep the nonempty shape gate;
+        # a benchmark's staged empty list must not become a pure-design pass.
+        shape_err = validate_shape(spec) or validate_inline_shape(spec)
         if shape_err:
             print(f"[spec-verify] error: {spec_path}: {shape_err}", file=sys.stderr)
             write_malformed_finding(devlyn_dir, f"{spec_path}: {shape_err}", None)
-            return 1
+            return reject_preflight()
         commands = list(spec["verification_commands"])
     if include_risk_probes:
         risk_state_error = risk_probes_state_error(state)
         if risk_state_error:
             print(f"[spec-verify] risk probes malformed: {risk_state_error}", file=sys.stderr)
             write_malformed_finding(devlyn_dir, risk_state_error, Path("pipeline.state.json"))
-            return 1
+            return reject_preflight()
         integrity_error = risk_probe_integrity_error(state, devlyn_dir)
         if integrity_error:
             print(f"[spec-verify] risk probes integrity failed: {integrity_error}", file=sys.stderr)
             write_risk_probe_integrity_finding(devlyn_dir, integrity_error)
-            return 1
+            return reject_preflight()
         risk_probes, risk_error = load_risk_probes(
             devlyn_dir,
             source_md,
@@ -5000,7 +5436,7 @@ def main() -> int:
         if risk_error:
             print(f"[spec-verify] risk probes malformed: {risk_error}", file=sys.stderr)
             write_malformed_finding(devlyn_dir, risk_error, devlyn_dir / "risk-probes.jsonl")
-            return 1
+            return reject_preflight()
         commands.extend(risk_probes)
 
     devlyn_dir.mkdir(parents=True, exist_ok=True)