devlyn-cli 2.10.0 → 3.0.0

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

@@ -31,10 +31,11 @@ Default mode (BUILD_GATE invocation, no args):
       mis-config). Real-user mode silent no-op + drops any stale
       pre-staged file (preserves iter-0019.6 backward compat for
       handwritten specs without the carrier).
-- For each verification_commands entry, runs the command in the work-dir,
-  captures combined stdout+stderr, and asserts exit_code matches +
-  stdout_contains all required literals + stdout_not_contains none of the
-  forbidden literals. Mirrors run-fixture.sh's post-run verifier semantics.
+- For each verification_commands entry and included risk probe, routes the
+  command through the sibling `process-evidence.py` runner. Raw stdout/stderr,
+  execution outcome, classification, and byte digests are written under the
+  authenticated run/phase/round manifest; expectations retain
+  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
@@ -60,6 +61,8 @@ Output routing:
   `SPEC_VERIFY_FINDINGS_FILE=verify-mechanical.findings.jsonl`, and
   `SPEC_VERIFY_FINDING_PREFIX=VERIFY-MECH` so `verify-merge-findings.py` consumes
   deterministic blockers directly.
+- `.devlyn/spec-verify.results.json` points each result at its sealed raw
+  streams and includes the validated process-evidence carrier.
 
 Why: iter-0018.5's prompt-only contract enforcement was empirically dead
 (F9 verify=0.4 across all engines in iter-0019). Same lesson as iter-0008
@@ -80,11 +83,13 @@ Exit codes:
   `SPEC_VERIFY_FINDINGS_FILE` (for example, VERIFY uses
   `.devlyn/verify-mechanical.findings.jsonl`).
 - 2: invocation error (unreadable spec-verify.json, missing markdown in
-  --check mode, etc.)
+  --check mode, etc.) or explicit evidence-backed
+  `BLOCKED:build-env-underprovisioned` capability denial.
 """
 
 from __future__ import annotations
 
+import importlib.util
 import json
 import hashlib
 import os
@@ -99,8 +104,21 @@ def reject_json_constant(token: str) -> None:
     raise ValueError(f"invalid JSON numeric constant: {token}")
 
 
+def reject_duplicate_keys(pairs: list[tuple[str, object]]) -> dict:
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError(f"duplicate JSON key: {key}")
+        result[key] = value
+    return result
+
+
 def loads_strict_json(text: str):
-    return json.loads(text, parse_constant=reject_json_constant)
+    return json.loads(
+        text,
+        parse_constant=reject_json_constant,
+        object_pairs_hook=reject_duplicate_keys,
+    )
 
 
 def output_phase() -> str:
@@ -115,6 +133,95 @@ def output_finding_prefix() -> str:
     return os.environ.get("SPEC_VERIFY_FINDING_PREFIX", "BGATE")
 
 
+_PROCESS_EVIDENCE_MODULE = None
+RUNNER_ENV_KEYS = (
+    "SPEC_VERIFY_PHASE",
+    "SPEC_VERIFY_FINDINGS_FILE",
+    "SPEC_VERIFY_FINDING_PREFIX",
+)
+
+
+def process_evidence_module():
+    global _PROCESS_EVIDENCE_MODULE
+    if _PROCESS_EVIDENCE_MODULE is None:
+        module_path = Path(__file__).with_name("process-evidence.py")
+        spec = importlib.util.spec_from_file_location("devlyn_process_evidence", module_path)
+        if spec is None or spec.loader is None:
+            raise RuntimeError(f"cannot load process evidence runner: {module_path}")
+        module = importlib.util.module_from_spec(spec)
+        previous_bytecode_setting = sys.dont_write_bytecode
+        sys.dont_write_bytecode = True
+        try:
+            spec.loader.exec_module(module)
+        finally:
+            sys.dont_write_bytecode = previous_bytecode_setting
+        _PROCESS_EVIDENCE_MODULE = module
+    return _PROCESS_EVIDENCE_MODULE
+
+
+def mechanical_evidence_identity(state: dict, runner) -> tuple[str, str, int, str]:
+    phase = "verify" if output_phase() == "verify_mechanical" else "build_gate"
+    run_id = state.get("run_id")
+    phase_state = (state.get("phases") or {}).get(phase)
+    round_ = phase_state.get("round") if isinstance(phase_state, dict) else None
+    invalid_identity = (
+        not isinstance(run_id, str)
+        or runner.ID_RE.fullmatch(run_id) is None
+        or isinstance(round_, bool)
+        or not isinstance(round_, int)
+        or round_ < 0
+    )
+    if invalid_identity and state.get("version") == "3.0":
+        raise runner.EvidenceError(
+            f"schema-v3 MECHANICAL evidence identity is invalid for phase {phase}"
+        )
+    if invalid_identity:
+        # Standalone/benchmark invocations predate pipeline run identity. Keep
+        # them evidence-backed without letting one process reuse another's
+        # manifest. Real pipeline runs always take the authenticated branch.
+        run_id = f"standalone-{os.getpid()}"
+        round_ = 0
+    identity = {"run_id": run_id, "phases": {phase: {"round": round_}}}
+    return phase, run_id, round_, runner.manifest_relative_path(identity, phase)
+
+
+def mechanical_obligation(vc: dict, idx: int, phase: str) -> dict:
+    evidence_id = (
+        f"risk-probe-{idx + 1:04d}"
+        if vc.get("_risk_probe")
+        else f"verification-command-{idx + 1:04d}"
+    )
+    return {
+        "id": evidence_id,
+        "phase": phase,
+        "cmd": vc["cmd"],
+        "exit_code": vc.get("exit_code", 0),
+        "timeout_sec": verification_timeout_sec(vc),
+        "stdout_contains": vc.get("stdout_contains", []) or [],
+        "stdout_not_contains": vc.get("stdout_not_contains", []) or [],
+    }
+
+
+def capture_mechanical_command(
+    runner, work: Path, manifest_path: Path, run_id: str, phase: str,
+    round_: int, obligation: dict,
+) -> dict:
+    saved = {key: os.environ.get(key) for key in (*RUNNER_ENV_KEYS, "BENCH_WORKDIR")}
+    for key in RUNNER_ENV_KEYS:
+        os.environ.pop(key, None)
+    os.environ["BENCH_WORKDIR"] = str(work)
+    try:
+        return runner.capture_process(
+            work, manifest_path, run_id, phase, round_, obligation,
+        )
+    finally:
+        for key, value in saved.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
 VERIFICATION_SECTION_RE = re.compile(
     r'(?ms)^<!--[ \t]*devlyn:verification[ \t]*-->[ \t]*\n(#{1,6}[ \t]+[^\n]*\n.*?)(?=^#{1,6}[ \t]+|\Z)'
 )
@@ -127,8 +234,9 @@ FORBIDDEN_RISK_PROBE_CMD_RE = re.compile(
 )
 EXTERNAL_URL_RE = re.compile(r"https?://([^/\s\"']+)", re.IGNORECASE)
 RISK_PROBE_SCRIPT_RE = re.compile(
-    r'(?<![\w./-])(\.devlyn/probes/[A-Za-z0-9][A-Za-z0-9._/-]*)'
+    r'(?<![\w./-])(?:\./)?(\.devlyn/probes/[A-Za-z0-9][A-Za-z0-9._/-]*)'
 )
+RISK_PROBE_RAW_REF = ".devlyn/probes/"
 RISK_PROBE_INTEGRITY_FIX_HINT = (
     "Probe artifacts changed after PHASE 1.5. Only the orchestrator may regenerate probes: "
     "re-run probe validation and re-write state.risk_probes_digest; workers must never modify "
@@ -260,13 +368,19 @@ EXPECTED_TOP_LEVEL_KEYS = {
 EXPECTED_VERIFICATION_COMMAND_KEYS = {
     "cmd",
     "exit_code",
+    "timeout_sec",
     "stdout_contains",
     "stdout_not_contains",
     "contract_refs",
 }
+DEFAULT_TIMEOUT_SEC = 60
 SPEC_COMPLEXITY_VALUES = {"trivial", "medium", "high", "large"}
 
 
+def verification_timeout_sec(command: dict) -> int:
+    return command.get("timeout_sec", DEFAULT_TIMEOUT_SEC)
+
+
 def extract_verification_block(text: str) -> tuple[bool, str | None]:
     """Locate the verification section via the `<!-- devlyn:verification -->`
     sentinel (language-neutral — the human-readable heading after it may be
@@ -474,7 +588,28 @@ def referenced_risk_probe_scripts(cmd: str) -> list[str]:
     return scripts
 
 
+def unrecognized_risk_probe_reference(cmd: str) -> str | None:
+    command = cmd or ""
+    matches = list(RISK_PROBE_SCRIPT_RE.finditer(command))
+    offset = command.find(RISK_PROBE_RAW_REF)
+    while offset >= 0:
+        if not any(
+            match.start() <= offset and offset + len(RISK_PROBE_RAW_REF) <= match.end()
+            for match in matches
+        ):
+            tail = command[offset:].split(maxsplit=1)[0][:80]
+            return (
+                f"unrecognized probe script reference {tail!r}; write it as "
+                ".devlyn/probes/<file> (a ./ prefix is the only alias)"
+            )
+        offset = command.find(RISK_PROBE_RAW_REF, offset + len(RISK_PROBE_RAW_REF))
+    return None
+
+
 def validate_risk_probe_scripts(cmd: str, index: int, work: Path) -> str | None:
+    unrecognized = unrecognized_risk_probe_reference(cmd)
+    if unrecognized:
+        return f"risk-probes[{index}].cmd has {unrecognized}"
     for rel_path in referenced_risk_probe_scripts(cmd):
         path = Path(rel_path)
         if ".." in path.parts:
@@ -534,6 +669,9 @@ def risk_probes_digest(devlyn_dir: Path) -> tuple[str | None, str | None]:
         except ValueError as e:
             return (None, f"risk-probes[{index}] invalid JSON: {e}")
         cmd = probe.get("cmd") if isinstance(probe, dict) else ""
+        unrecognized = unrecognized_risk_probe_reference(cmd)
+        if unrecognized:
+            return (None, f"risk-probes[{index}].cmd has {unrecognized}")
         scripts.update(referenced_risk_probe_scripts(cmd))
 
     digest = hashlib.sha256()
@@ -579,10 +717,12 @@ def validate_shape(data) -> str | None:
     Schema (iter-0019.8): top-level object with a non-empty
     `verification_commands` list of objects. Each object requires a
     non-empty string `cmd`; `exit_code` defaults to 0 and must be a
-    non-bool int; `stdout_contains` and `stdout_not_contains` default to
-    empty list and must be lists of strings. Bool is rejected explicitly
-    because Python's `bool` subclasses `int` — `isinstance(True, int) is
-    True` would otherwise let `exit_code: true` slip through.
+    non-bool int; `timeout_sec` defaults to DEFAULT_TIMEOUT_SEC and must be a
+    non-bool int from 1 through 600; `stdout_contains` and
+    `stdout_not_contains` default to empty list and must be lists of strings.
+    Bool is rejected explicitly because Python's `bool` subclasses `int` —
+    `isinstance(True, int) is True` would otherwise let numeric fields accept
+    true.
     """
     if not isinstance(data, dict):
         return "top-level must be a JSON object"
@@ -600,6 +740,13 @@ def validate_shape(data) -> str | None:
         ec = c.get("exit_code", 0)
         if isinstance(ec, bool) or not isinstance(ec, int):
             return f"verification_commands[{i}].exit_code must be int (not bool)"
+        timeout_sec = c.get("timeout_sec", DEFAULT_TIMEOUT_SEC)
+        if (
+            isinstance(timeout_sec, bool)
+            or not isinstance(timeout_sec, int)
+            or not 1 <= timeout_sec <= 600
+        ):
+            return f"verification_commands[{i}].timeout_sec must be int from 1 to 600 (not bool)"
         for k in ("stdout_contains", "stdout_not_contains"):
             v = c.get(k, [])
             if not isinstance(v, list) or not all(isinstance(s, str) for s in v):
@@ -810,7 +957,7 @@ def validate_risk_probe(
         if not isinstance(actual, list) or not all(isinstance(item, str) for item in actual):
             return f"risk-probes[{index}].tag_evidence.shape_contract must be a list of strings"
         required_shape = set(SHAPE_CONTRACT_REQUIRED_EVIDENCE)
-        if {"error_contract", "http_error_contract"} & set(tags):
+        if "visible_text_names_exact_json_error_object" in set(actual):
             required_shape.add("asserts_exact_error_object")
         missing_shape = sorted(required_shape - set(actual))
         if missing_shape:
@@ -1100,7 +1247,13 @@ def stage_from_expected(
     return (True, True, None, expected_path, data)
 
 
-def write_malformed_finding(devlyn_dir: Path, error: str, source_path: Path | None) -> None:
+def write_malformed_finding(
+    devlyn_dir: Path,
+    error: str,
+    source_path: Path | None,
+    *,
+    fix_hint: str | None = None,
+) -> None:
     """Emit a single CRITICAL finding for a malformed verification carrier."""
     devlyn_dir.mkdir(parents=True, exist_ok=True)
     findings_path = devlyn_dir / output_findings_name()
@@ -1116,7 +1269,7 @@ def write_malformed_finding(devlyn_dir: Path, error: str, source_path: Path | No
         "line": 1,
         "phase": output_phase(),
         "criterion_ref": "spec-verify://carrier",
-        "fix_hint": (
+        "fix_hint": fix_hint if fix_hint is not None else (
             "Fix the sibling `spec.expected.json` file or the `## Verification` "
             "```json``` block: a JSON object with a non-empty `verification_commands` array of "
             "{cmd, exit_code?, stdout_contains?, stdout_not_contains?} "
@@ -1345,6 +1498,24 @@ def expected_contract_findings(
     return (findings, seq)
 
 
+def validate_surface_brace_glob(entry: str) -> str | None:
+    if "{" not in entry and "}" not in entry:
+        return None
+    brace = re.search(r"\{([^{}]*)\}", entry)
+    alternatives = brace.group(1).split(",") if brace else []
+    if (
+        entry.count("{") != 1
+        or entry.count("}") != 1
+        or len(alternatives) < 2
+        or any(not value or any(char in value for char in "{},/*") for value in alternatives)
+    ):
+        return (
+            f"unsupported brace glob {entry!r}; supported form is {{alt1,alt2,...}} "
+            "with at least two non-empty plain alternatives"
+        )
+    return None
+
+
 def validate_authorized_surface_shape(data: object) -> str | None:
     if not isinstance(data, dict):
         return "top-level must be a JSON object"
@@ -1369,17 +1540,34 @@ def validate_authorized_surface_shape(data: object) -> str | None:
             return f"authorized_surface directory grant needs a non-empty prefix before '/**': {entry!r}"
         if ".." in stem.split("/"):
             return f"authorized_surface entry must not contain '..': {entry!r}"
+        brace_error = validate_surface_brace_glob(entry)
+        if brace_error is not None:
+            return brace_error
     return None
 
 
 def path_matches_surface(path: str, surface: list[str]) -> bool:
     for entry in surface:
-        if entry.endswith("/**"):
-            prefix = entry[:-3]
-            if path == prefix or path.startswith(prefix + "/"):
+        brace_error = validate_surface_brace_glob(entry)
+        if brace_error is not None:
+            raise ValueError(brace_error)
+        if "{" in entry:
+            brace = re.search(r"\{([^{}]*)\}", entry)
+            assert brace is not None
+            alternatives = brace.group(1).split(",")
+            entries = tuple(
+                entry[:brace.start()] + value + entry[brace.end():]
+                for value in alternatives
+            )
+        else:
+            entries = (entry,)
+        for expanded in entries:
+            if expanded.endswith("/**"):
+                prefix = expanded[:-3].rstrip("/")
+                if path == prefix or path.startswith(f"{prefix}/"):
+                    return True
+            elif path == expanded:
                 return True
-        elif path == entry:
-            return True
     return False
 
 
@@ -1738,11 +1926,67 @@ def run_check_expected_mode(expected_path: Path) -> int:
 
 
 def run_self_test() -> int:
+    try:
+        loads_strict_json('{"verification_commands":[],"verification_commands":[{}]}')
+    except ValueError as exc:
+        assert "duplicate JSON key" in str(exc)
+    else:
+        raise AssertionError("duplicate expected-contract key was accepted")
+    # Hermeticity: a pipeline replay exports BENCH_WORKDIR at the live repo;
+    # inherited into scenario children it wins over their tmp cwd (the
+    # default-mode work resolution below) and re-executes the LIVE
+    # .devlyn/spec-verify.json — with lint as the live command this mutually
+    # recursed (lint runs this self-test) into an unbounded spawn storm
+    # (observed 2026-08-03, iter-0089 canary).
+    os.environ.pop("BENCH_WORKDIR", None)
     script_path = str(Path(__file__).resolve())
+    with tempfile.TemporaryDirectory() as help_tmp:
+        for help_flag in ("--help", "-h"):
+            help_result = subprocess.run(
+                [sys.executable, script_path, help_flag],
+                cwd=help_tmp,
+                capture_output=True,
+                text=True,
+            )
+            if help_result.returncode != 0 or "usage:" not in help_result.stdout:
+                print(f"{help_flag} did not return usage successfully", file=sys.stderr)
+                return 1
+            if (Path(help_tmp) / ".devlyn").exists():
+                print(f"{help_flag} mutated .devlyn", file=sys.stderr)
+                return 1
+        unknown_result = subprocess.run(
+            [sys.executable, script_path, "--not-a-real-option"],
+            cwd=help_tmp,
+            capture_output=True,
+            text=True,
+        )
+        if unknown_result.returncode != 2 or "unknown argument" not in unknown_result.stderr:
+            print("unknown option did not fail closed", file=sys.stderr)
+            return 1
+        if (Path(help_tmp) / ".devlyn").exists():
+            print("unknown option mutated .devlyn", file=sys.stderr)
+            return 1
+    runner = process_evidence_module()
+    try:
+        mechanical_evidence_identity({"version": "3.0", "phases": {}}, runner)
+    except runner.EvidenceError as exc:
+        assert "schema-v3 MECHANICAL evidence identity is invalid" in str(exc)
+    else:
+        raise AssertionError("schema-v3 MECHANICAL evidence accepted missing run identity")
     with tempfile.TemporaryDirectory() as td:
         work = Path(td)
         devlyn = work / ".devlyn"
         devlyn.mkdir()
+        assert path_matches_surface("src/a/example.py", ["src/{a,b}/**"])
+        assert path_matches_surface("src/b/example.py", ["src/{a,b}/**"])
+        assert not path_matches_surface("src/c/example.py", ["src/{a,b}/**"])
+        for entry in ("src/{a,b", "src/{a,}/**", "src/{a,{b,c}}", "src/{a,**}"):
+            try:
+                path_matches_surface("src/a/example.py", [entry])
+            except ValueError as exc:
+                assert entry in str(exc) and "supported form" in str(exc)
+            else:
+                raise AssertionError(f"malformed brace glob accepted: {entry}")
         spec_md = work / "spec.md"
         spec_md.write_text("# Spec\n\n<!-- devlyn:verification -->\n## Verification\n\n- probe must pass visible marker.\n")
         (devlyn / "pipeline.state.json").write_text(json.dumps({
@@ -1762,6 +2006,7 @@ def run_self_test() -> int:
             "derived_from": "probe must pass visible marker.",
             "cmd": "python3 .devlyn/probes/P1.py",
             "exit_code": 0,
+            "timeout_sec": 5,
             "stdout_contains": ["probe-ok"],
             "stdout_not_contains": [],
             "tags": ["shape_contract"],
@@ -1774,6 +2019,264 @@ def run_self_test() -> int:
             },
         }
         (devlyn / "risk-probes.jsonl").write_text(json.dumps(risk_probe_payload) + "\n")
+        loaded_probes, loaded_probe_error = load_risk_probes(
+            devlyn, spec_md, require_present=True
+        )
+        if loaded_probe_error or loaded_probes[0].get("timeout_sec") != 5:
+            print("risk-probe timeout_sec was not preserved", file=sys.stderr)
+            print(loaded_probe_error, file=sys.stderr)
+            return 1
+
+        if verification_timeout_sec({"cmd": "printf default"}) != DEFAULT_TIMEOUT_SEC:
+            print("absent timeout_sec did not resolve to DEFAULT_TIMEOUT_SEC", file=sys.stderr)
+            return 1
+
+        inline_timeout_spec = work / "inline-timeout-spec.md"
+        inline_timeout_devlyn = work / "inline-timeout-devlyn"
+        for invalid_timeout in (True, 0, -1, 601, "60"):
+            inline_timeout_spec.write_text(
+                "# Timeout validation\n\n<!-- devlyn:verification -->\n## Verification\n\n```json\n"
+                + json.dumps({
+                    "verification_commands": [
+                        {"cmd": "printf ok", "timeout_sec": invalid_timeout}
+                    ]
+                })
+                + "\n```\n",
+                encoding="utf-8",
+            )
+            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:
+                print(
+                    f"inline carrier accepted invalid timeout_sec={invalid_timeout!r}",
+                    file=sys.stderr,
+                )
+                return 1
+
+        inline_timeout_spec.write_text(
+            "# Timeout preservation\n\n<!-- devlyn:verification -->\n## Verification\n\n```json\n"
+            + json.dumps({
+                "verification_commands": [
+                    {"cmd": "printf ok", "timeout_sec": 5}
+                ]
+            })
+            + "\n```\n",
+            encoding="utf-8",
+        )
+        staged, inline_error = stage_from_source(
+            inline_timeout_spec, inline_timeout_devlyn
+        )
+        inline_staged = loads_strict_json(
+            (inline_timeout_devlyn / "spec-verify.json").read_text()
+        )
+        if (
+            not staged
+            or inline_error
+            or inline_staged["verification_commands"][0].get("timeout_sec") != 5
+        ):
+            print("inline carrier did not preserve timeout_sec", file=sys.stderr)
+            return 1
+
+        sibling_timeout_root = work / "sibling-timeout"
+        sibling_timeout_root.mkdir()
+        sibling_timeout_devlyn = sibling_timeout_root / ".devlyn"
+        sibling_timeout_spec = sibling_timeout_root / "spec.md"
+        sibling_timeout_spec.write_text("# Sibling timeout\n", encoding="utf-8")
+        sibling_timeout_expected = sibling_timeout_root / "spec.expected.json"
+        for invalid_timeout in (True, 601):
+            sibling_timeout_expected.write_text(json.dumps({
+                "verification_commands": [
+                    {"cmd": "printf ok", "timeout_sec": invalid_timeout}
+                ]
+            }) + "\n")
+            found, staged, sibling_error, _path, _data = stage_from_expected(
+                sibling_timeout_spec, sibling_timeout_devlyn
+            )
+            if not found or staged or not sibling_error or "timeout_sec" not in sibling_error:
+                print(
+                    f"sibling carrier accepted invalid timeout_sec={invalid_timeout!r}",
+                    file=sys.stderr,
+                )
+                return 1
+
+        sibling_timeout_expected.write_text(json.dumps({
+            "verification_commands": [
+                {"cmd": "printf ok", "timeout_sec": 5}
+            ]
+        }) + "\n")
+        found, staged, sibling_error, _path, _data = stage_from_expected(
+            sibling_timeout_spec, sibling_timeout_devlyn
+        )
+        sibling_staged = loads_strict_json(
+            (sibling_timeout_devlyn / "spec-verify.json").read_text()
+        )
+        if (
+            not found
+            or not staged
+            or sibling_error
+            or sibling_staged["verification_commands"][0].get("timeout_sec") != 5
+        ):
+            print("sibling carrier did not preserve timeout_sec", file=sys.stderr)
+            return 1
+
+        timeout_run_root = work / "timeout-run"
+        timeout_run_root.mkdir()
+        timeout_run_devlyn = timeout_run_root / ".devlyn"
+        timeout_run_devlyn.mkdir()
+        timeout_run_spec = timeout_run_root / "spec.md"
+        timeout_run_spec.write_text(
+            "# Timeout execution\n\n<!-- devlyn:verification -->\n## Verification\n\n```json\n"
+            + json.dumps({
+                "verification_commands": [
+                    {
+                        "cmd": "python3 -c \"import time; time.sleep(2)\"",
+                        "timeout_sec": 1,
+                    },
+                    {
+                        "cmd": "python3 -c \"import time; time.sleep(1)\"",
+                        "timeout_sec": 5,
+                    },
+                    {
+                        "cmd": "printf 'Operation not permitted' >&2; exit 1",
+                    },
+                ]
+            })
+            + "\n```\n",
+            encoding="utf-8",
+        )
+        (timeout_run_devlyn / "pipeline.state.json").write_text(json.dumps({
+            "run_id": "rs-timeout-run",
+            "source": {"type": "spec", "spec_path": str(timeout_run_spec)},
+            "phases": {"build_gate": {"round": 2}},
+        }))
+        timeout_run = subprocess.run(
+            [sys.executable, script_path],
+            cwd=timeout_run_root,
+            capture_output=True,
+            text=True,
+        )
+        if timeout_run.returncode == 0:
+            print("declared one-second timeout did not fail", file=sys.stderr)
+            return 1
+        timeout_document = loads_strict_json(
+            (timeout_run_devlyn / "spec-verify.results.json").read_text()
+        )
+        timeout_results = timeout_document["commands"]
+        timeout_findings = [
+            loads_strict_json(line)
+            for line in (timeout_run_devlyn / output_findings_name()).read_text().splitlines()
+            if line.strip()
+        ]
+        if (
+            timeout_results[0].get("reason") != "timeout"
+            or timeout_results[0].get("timeout_sec") != 1
+            or not timeout_results[1].get("pass")
+            or timeout_results[2].get("reason") != "exit"
+            or timeout_results[2].get("classification") != {
+                "kind": "product_result", "operation": None,
+            }
+        ):
+            print("declared timeout budgets were not honored", file=sys.stderr)
+            print(timeout_results, file=sys.stderr)
+            return 1
+        timeout_carrier = timeout_document.get("process_evidence") or {}
+        timeout_manifest_path = (
+            ".devlyn/process-evidence/rs-timeout-run/build_gate/round-2/manifest.json"
+        )
+        timeout_manifest = loads_strict_json(
+            (timeout_run_root / timeout_manifest_path).read_text()
+        )
+        if (
+            timeout_carrier.get("manifest", {}).get("path") != timeout_manifest_path
+            or [entry.get("id") for entry in timeout_manifest.get("entries", [])] != [
+                "verification-command-0001",
+                "verification-command-0002",
+                "verification-command-0003",
+            ]
+            or any(
+                not (timeout_run_root / entry[stream]["path"]).is_file()
+                for entry in timeout_manifest.get("entries", [])
+                for stream in ("stdout", "stderr")
+            )
+        ):
+            print("literal commands did not emit sealed BUILD_GATE evidence", file=sys.stderr)
+            print(timeout_document, file=sys.stderr)
+            return 1
+        timeout_finding = timeout_findings[0] if timeout_findings else {}
+        if (
+            timeout_finding.get("rule_id") != "correctness.verification-timeout"
+            or "after 1s" not in timeout_finding.get("message", "")
+            or "timeout_sec" not in timeout_finding.get("message", "")
+            or "600" not in timeout_finding.get("fix_hint", "")
+        ):
+            print("timeout finding did not carry the distinct budget contract", file=sys.stderr)
+            print(timeout_finding, file=sys.stderr)
+            return 1
+        if (
+            not any(
+                finding.get("rule_id") == "correctness.spec-literal-mismatch"
+                for finding in timeout_findings
+            )
+            or "BLOCKED:build-env-underprovisioned" in timeout_run.stderr
+        ):
+            print("ordinary restricted-looking stderr did not remain a product finding", file=sys.stderr)
+            print(timeout_findings, file=sys.stderr)
+            print(timeout_run.stderr, file=sys.stderr)
+            return 1
+
+        runner_env_root = work / "runner-env-isolation"
+        runner_env_root.mkdir()
+        runner_env_devlyn = runner_env_root / ".devlyn"
+        runner_env_devlyn.mkdir()
+        runner_env_spec = runner_env_root / "spec.md"
+        runner_env_spec.write_text(
+            "# Runner environment isolation\n\n<!-- devlyn:verification -->\n"
+            "## Verification\n\n```json\n"
+            + json.dumps({
+                "verification_commands": [{
+                    "cmd": (
+                        "python3 -c \"import os, sys; sys.exit(any(name in os.environ "
+                        "for name in ('SPEC_VERIFY_PHASE', 'SPEC_VERIFY_FINDINGS_FILE', "
+                        "'SPEC_VERIFY_FINDING_PREFIX')))\""
+                    )
+                }]
+            })
+            + "\n```\n",
+            encoding="utf-8",
+        )
+        (runner_env_devlyn / "pipeline.state.json").write_text(json.dumps({
+            "run_id": "rs-runner-env",
+            "source": {"type": "spec", "spec_path": str(runner_env_spec)},
+            "phases": {"verify": {"round": 3}},
+        }))
+        runner_env = os.environ.copy()
+        runner_env.update({
+            "SPEC_VERIFY_PHASE": "verify_mechanical",
+            "SPEC_VERIFY_FINDINGS_FILE": "runner-env.findings.jsonl",
+            "SPEC_VERIFY_FINDING_PREFIX": "RUNNER-ENV",
+        })
+        runner_env_run = subprocess.run(
+            [sys.executable, script_path],
+            cwd=runner_env_root,
+            env=runner_env,
+            capture_output=True,
+            text=True,
+        )
+        runner_env_document = loads_strict_json(
+            (runner_env_devlyn / "spec-verify.results.json").read_text()
+        )
+        runner_env_results = runner_env_document["commands"]
+        if runner_env_run.returncode != 0 or not runner_env_results[0].get("pass"):
+            print("runner-directed environment leaked into a verification command", file=sys.stderr)
+            print(runner_env_run.stderr, file=sys.stderr)
+            return 1
+        if runner_env_document.get("process_evidence", {}).get("manifest", {}).get("path") != (
+            ".devlyn/process-evidence/rs-runner-env/verify/round-3/manifest.json"
+        ):
+            print("VERIFY MECHANICAL evidence used the wrong phase identity", file=sys.stderr)
+            print(runner_env_document, file=sys.stderr)
+            return 1
         env = os.environ.copy()
         env["BENCH_WORKDIR"] = str(work)
         validate_without_digest = subprocess.run(
@@ -1804,9 +2307,11 @@ def run_self_test() -> int:
             print(repr(digest_run.stdout), file=sys.stderr)
             return 1
         (devlyn / "pipeline.state.json").write_text(json.dumps({
+            "run_id": "rs-risk-probes",
             "source": {"type": "spec", "spec_path": str(spec_md)},
             "risk_profile": {"risk_probes_enabled": True},
             "risk_probes_digest": risk_digest,
+            "phases": {"build_gate": {"round": 4}},
         }))
         good = subprocess.run(
             [sys.executable, script_path, "--include-risk-probes"],
@@ -1818,6 +2323,24 @@ def run_self_test() -> int:
         if good.returncode != 0:
             print(good.stderr, file=sys.stderr)
             return 1
+        good_document = loads_strict_json(
+            (devlyn / "spec-verify.results.json").read_text()
+        )
+        good_manifest_path = good_document.get("process_evidence", {}).get("manifest", {}).get("path")
+        good_manifest = (
+            loads_strict_json((work / good_manifest_path).read_text())
+            if isinstance(good_manifest_path, str)
+            else {}
+        )
+        if (
+            good_manifest_path != ".devlyn/process-evidence/rs-risk-probes/build_gate/round-4/manifest.json"
+            or [entry.get("id") for entry in good_manifest.get("entries", [])] != [
+                "verification-command-0001", "risk-probe-0002",
+            ]
+        ):
+            print("literal command and risk probe did not share the sealed manifest", file=sys.stderr)
+            print(good_document, file=sys.stderr)
+            return 1
 
         probe_script.write_text("print('mutated-probe')\n", encoding="utf-8")
         mutated_script = subprocess.run(
@@ -1830,7 +2353,7 @@ def run_self_test() -> int:
         if mutated_script.returncode == 0:
             print("--include-risk-probes accepted mutated probe script bytes", file=sys.stderr)
             return 1
-        integrity_findings = (devlyn / "spec-verify-findings.jsonl").read_text(encoding="utf-8")
+        integrity_findings = (devlyn / output_findings_name()).read_text(encoding="utf-8")
         if "correctness.risk-probe-integrity" not in integrity_findings:
             print("mutated probe script did not emit correctness.risk-probe-integrity", file=sys.stderr)
             print(integrity_findings, file=sys.stderr)
@@ -1850,7 +2373,7 @@ def run_self_test() -> int:
         if mutated_jsonl.returncode == 0:
             print("--include-risk-probes accepted mutated risk-probes.jsonl bytes", file=sys.stderr)
             return 1
-        integrity_findings = (devlyn / "spec-verify-findings.jsonl").read_text(encoding="utf-8")
+        integrity_findings = (devlyn / output_findings_name()).read_text(encoding="utf-8")
         if "correctness.risk-probe-integrity" not in integrity_findings:
             print("mutated risk-probes.jsonl did not emit correctness.risk-probe-integrity", file=sys.stderr)
             print(integrity_findings, file=sys.stderr)
@@ -1871,7 +2394,7 @@ def run_self_test() -> int:
         if missing_digest.returncode == 0:
             print("--include-risk-probes accepted enabled risk probes with missing digest", file=sys.stderr)
             return 1
-        integrity_findings = (devlyn / "spec-verify-findings.jsonl").read_text(encoding="utf-8")
+        integrity_findings = (devlyn / output_findings_name()).read_text(encoding="utf-8")
         if "correctness.risk-probe-integrity" not in integrity_findings:
             print("missing risk_probes_digest did not emit correctness.risk-probe-integrity", file=sys.stderr)
             print(integrity_findings, file=sys.stderr)
@@ -2196,22 +2719,13 @@ def run_self_test() -> int:
         probes_dir = devlyn / "probes"
         probes_dir.mkdir(exist_ok=True)
         (probes_dir / "Pscript.py").write_text("print('script-ok')\n", encoding="utf-8")
-        (devlyn / "risk-probes.jsonl").write_text(json.dumps({
+        script_probe_payload = {
+            **risk_probe_payload,
             "id": "Pscript",
-            "derived_from": "probe must pass visible marker.",
             "cmd": "python3 .devlyn/probes/Pscript.py",
-            "exit_code": 0,
             "stdout_contains": ["script-ok"],
-            "stdout_not_contains": [],
-            "tags": ["shape_contract"],
-            "tag_evidence": {
-                "shape_contract": [
-                    "uses_visible_input_key_names",
-                    "asserts_visible_output_key_names",
-                    "asserts_no_unexpected_output_keys",
-                ],
-            },
-        }) + "\n")
+        }
+        (devlyn / "risk-probes.jsonl").write_text(json.dumps(script_probe_payload) + "\n")
         good_script_probe = subprocess.run(
             [sys.executable, script_path, "--validate-risk-probes"],
             cwd=work,
@@ -2224,10 +2738,47 @@ def run_self_test() -> int:
             print(good_script_probe.stderr, file=sys.stderr)
             return 1
 
+        mixed_script_payload = {
+            **script_probe_payload,
+            "id": "Pmixed",
+            "cmd": "python3 .devlyn/probes/Pscript.py && python3 ./.devlyn/probes/P1.py",
+        }
+        (devlyn / "risk-probes.jsonl").write_text(json.dumps(mixed_script_payload) + "\n")
+        mixed_script_probe = subprocess.run(
+            [sys.executable, script_path, "--validate-risk-probes"],
+            cwd=work,
+            env=env,
+            capture_output=True,
+            text=True,
+        )
+        if mixed_script_probe.returncode != 0:
+            print("canonical and ./-alias probe script references were rejected", file=sys.stderr)
+            print(mixed_script_probe.stderr, file=sys.stderr)
+            return 1
+        mixed_digest, mixed_digest_error = risk_probes_digest(devlyn)
+        if mixed_digest_error:
+            print(mixed_digest_error, file=sys.stderr)
+            return 1
+        (probes_dir / "Pscript.py").write_text("print('script-mutated')\n", encoding="utf-8")
+        canonical_mutated_digest, canonical_mutated_error = risk_probes_digest(devlyn)
+        (probes_dir / "Pscript.py").write_text("print('script-ok')\n", encoding="utf-8")
+        if canonical_mutated_error:
+            print(canonical_mutated_error, file=sys.stderr)
+            return 1
+        probe_script.write_text("print('probe-mutated')\n", encoding="utf-8")
+        alias_mutated_digest, alias_mutated_error = risk_probes_digest(devlyn)
+        probe_script.write_text("print('probe-ok')\n", encoding="utf-8")
+        if alias_mutated_error:
+            print(alias_mutated_error, file=sys.stderr)
+            return 1
+        if len({mixed_digest, canonical_mutated_digest, alias_mutated_digest}) != 3:
+            print("probe digest did not change for both canonical and ./-alias scripts", file=sys.stderr)
+            return 1
+
         (devlyn / "risk-probes.jsonl").write_text(json.dumps({
             "id": "Pmissing",
             "derived_from": "probe must pass visible marker.",
-            "cmd": "python3 .devlyn/probes/missing.py",
+            "cmd": "python3 ./.devlyn/probes/missing.py",
             "exit_code": 0,
         }) + "\n")
         missing_script_probe = subprocess.run(
@@ -2260,6 +2811,45 @@ def run_self_test() -> int:
             print(missing_script_digest.stderr, file=sys.stderr)
             return 1
 
+        for bad_form in (
+            "../.devlyn/probes/Pscript.py",
+            "/tmp/.devlyn/probes/Pscript.py",
+            "$PWD/.devlyn/probes/Pscript.py",
+            "././.devlyn/probes/Pscript.py",
+        ):
+            (devlyn / "risk-probes.jsonl").write_text(json.dumps({
+                "id": "Pbadref",
+                "derived_from": "probe must pass visible marker.",
+                "cmd": f"python3 {bad_form}",
+                "exit_code": 0,
+            }) + "\n")
+            bad_ref_probe = subprocess.run(
+                [sys.executable, script_path, "--validate-risk-probes"],
+                cwd=work,
+                env=env,
+                capture_output=True,
+                text=True,
+            )
+            bad_ref_digest = subprocess.run(
+                [sys.executable, script_path, "--print-risk-probes-digest"],
+                cwd=work,
+                env=env,
+                capture_output=True,
+                text=True,
+            )
+            unrecognized = unrecognized_risk_probe_reference(f"python3 {bad_form}")
+            expected_error = f"risk-probes[0].cmd has {unrecognized}"
+            if (
+                bad_ref_probe.returncode == 0
+                or expected_error not in bad_ref_probe.stderr
+                or bad_ref_digest.returncode == 0
+                or expected_error not in bad_ref_digest.stderr
+            ):
+                print(f"bad probe script reference was not rejected: {bad_form}", file=sys.stderr)
+                print(bad_ref_probe.stderr, file=sys.stderr)
+                print(bad_ref_digest.stderr, file=sys.stderr)
+                return 1
+
         (probes_dir / "Phidden.py").write_text("print('benchmark/auto-resolve/fixtures')\n", encoding="utf-8")
         (devlyn / "risk-probes.jsonl").write_text(json.dumps({
             "id": "Phidden",
@@ -2810,6 +3400,103 @@ def run_self_test() -> int:
             print(expected_nan_json.stderr, file=sys.stderr)
             return 1
 
+        external_diff_root = work / "external-diff-mode-authority"
+        external_diff_root.mkdir()
+        external_diff_devlyn = external_diff_root / ".devlyn"
+        external_diff_devlyn.mkdir()
+        external_diff_spec = external_diff_root / "spec.md"
+        external_diff_spec.write_text(
+            "# Spec\n\n<!-- devlyn:verification -->\n## Verification\n\n"
+            "- external diff remains verify-only.\n",
+            encoding="utf-8",
+        )
+        (external_diff_root / "spec.expected.json").write_text(json.dumps({
+            "verification_commands": [
+                {"cmd": "printf external-diff-ok", "stdout_contains": ["external-diff-ok"]}
+            ]
+        }) + "\n", encoding="utf-8")
+        (external_diff_root / "external-only.txt").write_text("base\n", encoding="utf-8")
+        (external_diff_root / "outside.txt").write_text("base\n", encoding="utf-8")
+        subprocess.run(["git", "init", "-q"], cwd=external_diff_root, check=True)
+        subprocess.run(["git", "add", "-A"], cwd=external_diff_root, check=True)
+        subprocess.run(
+            ["git", "-c", "user.email=t@t", "-c", "user.name=t", "commit", "-q", "-m", "base"],
+            cwd=external_diff_root,
+            check=True,
+        )
+        external_diff_base_sha = subprocess.check_output(
+            ["git", "rev-parse", "HEAD"], cwd=external_diff_root, text=True,
+        ).strip()
+        (external_diff_root / "outside.txt").write_text("worktree-only\n", encoding="utf-8")
+        (external_diff_devlyn / "external-diff.patch").write_text(
+            "diff --git a/external-only.txt b/external-only.txt\n"
+            "--- a/external-only.txt\n"
+            "+++ b/external-only.txt\n"
+            "@@ -1 +1 @@\n"
+            "-base\n"
+            "+external\n",
+            encoding="utf-8",
+        )
+        (external_diff_devlyn / "plan.md").write_text(
+            "<!-- devlyn:authorized-surface -->\n## Files to touch\n\n"
+            "```json\n{\"authorized_surface\": [\"external-only.txt\"]}\n```\n",
+            encoding="utf-8",
+        )
+        (external_diff_devlyn / "untracked.baseline").write_text("", encoding="utf-8")
+        external_diff_state = {
+            "mode": "free-form",
+            "source": {"type": "spec", "spec_path": str(external_diff_spec)},
+            "base_ref": {"sha": external_diff_base_sha},
+        }
+        external_diff_state_path = external_diff_devlyn / "pipeline.state.json"
+        external_diff_state_path.write_text(json.dumps(external_diff_state) + "\n")
+        external_diff_free_form = subprocess.run(
+            [sys.executable, script_path],
+            cwd=external_diff_root,
+            capture_output=True,
+            text=True,
+        )
+        external_diff_findings_path = external_diff_devlyn / output_findings_name()
+        external_diff_free_form_findings = (
+            external_diff_findings_path.read_text()
+            if external_diff_findings_path.is_file()
+            else ""
+        )
+        external_diff_state["mode"] = "verify-only"
+        external_diff_state_path.write_text(json.dumps(external_diff_state) + "\n")
+        external_diff_verify_only = subprocess.run(
+            [sys.executable, script_path],
+            cwd=external_diff_root,
+            capture_output=True,
+            text=True,
+        )
+        if external_diff_free_form.returncode != 1:
+            print("non-verify-only mode accepted .devlyn/external-diff.patch", file=sys.stderr)
+            print(external_diff_free_form.stderr, file=sys.stderr)
+            return 1
+        if (
+            '"rule_id": "correctness.spec-verify-malformed"'
+            not in external_diff_free_form_findings
+            or '"severity": "CRITICAL"' not in external_diff_free_form_findings
+            or ".devlyn/external-diff.patch" not in external_diff_free_form_findings
+            or "free-form" not in external_diff_free_form_findings
+            or "verify-only" not in external_diff_free_form_findings
+            or "Remove `.devlyn/external-diff.patch` for ordinary runs"
+            not in external_diff_free_form_findings
+            or "only when intentionally verifying an external patch"
+            not in external_diff_free_form_findings
+        ):
+            print(
+                "non-verify-only external diff did not emit the named CRITICAL finding and remediation",
+                file=sys.stderr,
+            )
+            print(external_diff_free_form_findings, file=sys.stderr)
+            return 1
+        if external_diff_verify_only.returncode != 0:
+            print("verify-only external diff was rejected or not consumed", file=sys.stderr)
+            print(external_diff_verify_only.stderr, file=sys.stderr)
+            return 1
+
         spec_integrity = work / "spec-integrity"
         spec_integrity.mkdir()
         spec_integrity_devlyn = spec_integrity / ".devlyn"
@@ -3132,7 +3819,7 @@ def run_self_test() -> int:
         if contract_run.returncode == 0:
             print("expected contract violations were accepted", file=sys.stderr)
             return 1
-        findings_text = (contract_devlyn / "spec-verify-findings.jsonl").read_text()
+        findings_text = (contract_devlyn / output_findings_name()).read_text()
         for rule_id in (
             "correctness.forbidden-pattern",
             "correctness.required-file-missing",
@@ -3169,7 +3856,8 @@ def run_self_test() -> int:
         error_spec = error_root / "spec.md"
         error_spec.write_text(
             "# Spec\n\n<!-- devlyn:verification -->\n## Verification\n\n"
-            "- Invalid input must print a JSON error object to stderr and exit 2.\n"
+            "- Invalid input must print JSON error object `{ \"error\": \"bad_input\" }` to stderr and exit 2.\n"
+            "- Malformed input must exit 2 and print stderr JSON with keys `code` and `detail`; values are implementation-defined.\n"
         )
         (error_devlyn / "pipeline.state.json").write_text(json.dumps({
             "source": {"type": "spec", "spec_path": str(error_spec)}
@@ -3221,7 +3909,7 @@ def run_self_test() -> int:
 
         (error_devlyn / "risk-probes.jsonl").write_text(json.dumps({
             "id": "P7c",
-            "derived_from": "Invalid input must print a JSON error object to stderr and exit 2.",
+            "derived_from": "Invalid input must print JSON error object `{ \"error\": \"bad_input\" }` to stderr and exit 2.",
             "cmd": "printf json-error-shape-contract-missing-exact",
             "exit_code": 2,
             "tags": ["stdout_stderr_contract", "error_contract", "shape_contract"],
@@ -3235,6 +3923,7 @@ def run_self_test() -> int:
                     "uses_visible_input_key_names",
                     "asserts_visible_output_key_names",
                     "asserts_no_unexpected_output_keys",
+                    "visible_text_names_exact_json_error_object",
                 ],
             },
         }) + "\n")
@@ -3246,7 +3935,7 @@ def run_self_test() -> int:
         )
         if missing_exact_error_object.returncode == 0:
             print(
-                "shape_contract co-occurring with error_contract without "
+                "shape_contract claiming visible exact error object without "
                 "asserts_exact_error_object was accepted",
                 file=sys.stderr,
             )
@@ -3254,7 +3943,7 @@ def run_self_test() -> int:
 
         (error_devlyn / "risk-probes.jsonl").write_text(json.dumps({
             "id": "P7d",
-            "derived_from": "Invalid input must print a JSON error object to stderr and exit 2.",
+            "derived_from": "Invalid input must print JSON error object `{ \"error\": \"bad_input\" }` to stderr and exit 2.",
             "cmd": "printf json-error-shape-contract",
             "exit_code": 2,
             "tags": ["stdout_stderr_contract", "error_contract", "shape_contract"],
@@ -3268,6 +3957,7 @@ def run_self_test() -> int:
                     "uses_visible_input_key_names",
                     "asserts_visible_output_key_names",
                     "asserts_no_unexpected_output_keys",
+                    "visible_text_names_exact_json_error_object",
                     "asserts_exact_error_object",
                 ],
             },
@@ -3283,6 +3973,38 @@ def run_self_test() -> int:
             print(strong_json_error_shape_contract.stderr, file=sys.stderr)
             return 1
 
+        (error_devlyn / "risk-probes.jsonl").write_text(json.dumps({
+            "id": "P7e",
+            "derived_from": (
+                "Malformed input must exit 2 and print stderr JSON with keys `code` and `detail`; "
+                "values are implementation-defined."
+            ),
+            "cmd": "printf error-exit-shape-contract",
+            "exit_code": 2,
+            "tags": ["error_contract", "shape_contract"],
+            "tag_evidence": {
+                "error_contract": [
+                    "asserts_error_payload_or_stderr",
+                    "asserts_nonzero_or_exit_2",
+                ],
+                "shape_contract": [
+                    "uses_visible_input_key_names",
+                    "asserts_visible_output_key_names",
+                    "asserts_no_unexpected_output_keys",
+                ],
+            },
+        }) + "\n")
+        error_exit_shape_contract = subprocess.run(
+            [sys.executable, script_path, "--validate-risk-probes"],
+            cwd=error_root,
+            capture_output=True,
+            text=True,
+        )
+        if error_exit_shape_contract.returncode != 0:
+            print("error-exit shape_contract without visible exact error object was rejected", file=sys.stderr)
+            print(error_exit_shape_contract.stderr, file=sys.stderr)
+            return 1
+
         http_error_root = work / "http-error-contract-risk-probe"
         http_error_root.mkdir()
         http_error_devlyn = http_error_root / ".devlyn"
@@ -3336,6 +4058,7 @@ def run_self_test() -> int:
                     "uses_visible_input_key_names",
                     "asserts_visible_output_key_names",
                     "asserts_no_unexpected_output_keys",
+                    "visible_text_names_exact_json_error_object",
                 ],
             },
         }) + "\n")
@@ -3367,6 +4090,7 @@ def run_self_test() -> int:
                     "uses_visible_input_key_names",
                     "asserts_visible_output_key_names",
                     "asserts_no_unexpected_output_keys",
+                    "visible_text_names_exact_json_error_object",
                     "asserts_exact_error_object",
                 ],
             },
@@ -3670,12 +4394,15 @@ def run_self_test() -> int:
             print("--write-untracked-baseline wrote wrong content", file=sys.stderr)
             print(repr(baseline_lines), file=sys.stderr)
             return 1
-        scope_findings_path = scope_devlyn / "spec-verify-findings.jsonl"
+        scope_findings_path = scope_devlyn / output_findings_name()
+        scope_build_gate_env = os.environ.copy()
+        scope_build_gate_env["SPEC_VERIFY_PHASE"] = "build_gate"
 
         # Test 1: no .devlyn/plan.md at all -> fail-closed CRITICAL, not a no-op.
         (scope_root / "bin" / "cli.js").write_text("module.exports = { ok: true };\n")
         missing_plan_run = subprocess.run(
-            [sys.executable, script_path], cwd=scope_root, capture_output=True, text=True,
+            [sys.executable, script_path], cwd=scope_root, env=scope_build_gate_env,
+            capture_output=True, text=True,
         )
         if missing_plan_run.returncode == 0:
             print("BUILD_GATE accepted a run with no plan.md", file=sys.stderr)
@@ -3689,7 +4416,8 @@ def run_self_test() -> int:
             "# PLAN\n\n<!-- devlyn:authorized-surface -->\n## 1. Files to touch\n\n- `bin/cli.js` (edit): ship the fix.\n"
         )
         malformed_block_run = subprocess.run(
-            [sys.executable, script_path], cwd=scope_root, capture_output=True, text=True,
+            [sys.executable, script_path], cwd=scope_root, env=scope_build_gate_env,
+            capture_output=True, text=True,
         )
         if malformed_block_run.returncode == 0:
             print("BUILD_GATE accepted plan.md with no authorized_surface block", file=sys.stderr)
@@ -3706,6 +4434,32 @@ def run_self_test() -> int:
             print("--print-authorized-surface accepted malformed plan.md", file=sys.stderr)
             return 1
 
+        for entry in ("src/{a,b", "src/{a,}/**", "src/{a,{b,c}}", "src/{a,**}"):
+            (scope_devlyn / "plan.md").write_text(
+                "# PLAN\n\n<!-- devlyn:authorized-surface -->\n## 1. Files to touch\n\n"
+                "```json\n"
+                + json.dumps({"authorized_surface": [entry]}) + "\n```\n"
+            )
+            brace_build_gate = subprocess.run(
+                [sys.executable, script_path], cwd=scope_root, env=scope_build_gate_env,
+                capture_output=True, text=True,
+            )
+            brace_print_surface = subprocess.run(
+                [sys.executable, script_path, "--print-authorized-surface"], cwd=scope_root,
+                capture_output=True, text=True,
+            )
+            findings_text = scope_findings_path.read_text(encoding="utf-8")
+            if (
+                brace_build_gate.returncode == 0
+                or brace_print_surface.returncode == 0
+                or "scope.authorized-surface-malformed" not in findings_text
+                or "supported form" not in findings_text
+                or "supported form" not in brace_print_surface.stderr
+                or "Traceback" in brace_build_gate.stderr + brace_print_surface.stderr
+            ):
+                print(f"malformed brace glob escaped the authorized-surface carrier: {entry}", file=sys.stderr)
+                return 1
+
         # Test 3: valid surface, in-scope-only diff -> no scope findings, exit 0.
         (scope_devlyn / "plan.md").write_text(
             "# PLAN\n\n<!-- devlyn:authorized-surface -->\n## 1. Files to touch\n\n"
@@ -3734,7 +4488,8 @@ def run_self_test() -> int:
             return 1
         (scope_devlyn / "untracked.baseline").unlink()
         missing_baseline_run = subprocess.run(
-            [sys.executable, script_path], cwd=scope_root, capture_output=True, text=True,
+            [sys.executable, script_path], cwd=scope_root, env=scope_build_gate_env,
+            capture_output=True, text=True,
         )
         if missing_baseline_run.returncode == 0:
             print("BUILD_GATE accepted missing .devlyn/untracked.baseline", file=sys.stderr)
@@ -3750,7 +4505,8 @@ def run_self_test() -> int:
             print("--write-untracked-baseline re-run failed", file=sys.stderr)
             return 1
         in_scope_run = subprocess.run(
-            [sys.executable, script_path], cwd=scope_root, capture_output=True, text=True,
+            [sys.executable, script_path], cwd=scope_root, env=scope_build_gate_env,
+            capture_output=True, text=True,
         )
         if in_scope_run.returncode != 0:
             print("in-scope-only diff was rejected", file=sys.stderr)
@@ -3767,7 +4523,8 @@ def run_self_test() -> int:
         (scope_root / "data" / "usage-stats.json").write_text('{"leaked": true}\n')
         (scope_root / "data" / "scratch.json").write_text('{"untracked": true}\n')
         out_of_scope_run = subprocess.run(
-            [sys.executable, script_path], cwd=scope_root, capture_output=True, text=True,
+            [sys.executable, script_path], cwd=scope_root, env=scope_build_gate_env,
+            capture_output=True, text=True,
         )
         if out_of_scope_run.returncode == 0:
             print("out-of-scope file was accepted", file=sys.stderr)
@@ -3803,7 +4560,8 @@ def run_self_test() -> int:
         # (directory-prefix boundary, not a bare string-prefix match).
         (scope_root / "lib2" / "keep.js").write_text("module.exports = { touched: true };\n")
         subprocess.run(
-            [sys.executable, script_path], cwd=scope_root, capture_output=True, text=True,
+            [sys.executable, script_path], cwd=scope_root, env=scope_build_gate_env,
+            capture_output=True, text=True,
         )
         boundary_flagged = {
             loads_strict_json(line)["file"]
@@ -3834,12 +4592,16 @@ def run_self_test() -> int:
             print(verify_mech_findings, file=sys.stderr)
             return 1
 
-        # Test 7: shape validation rejects absolute paths, `..`, and duplicates.
+        # Test 7: shape validation rejects absolute paths, `..`, duplicates, and malformed braces.
         for bad_surface in (
             {"authorized_surface": ["/etc/passwd"]},
             {"authorized_surface": ["bin/../etc/passwd"]},
             {"authorized_surface": ["bin/cli.js", "bin/cli.js"]},
             {"authorized_surface": []},
+            {"authorized_surface": ["src/{a,b"]},
+            {"authorized_surface": ["src/{a,}/**"]},
+            {"authorized_surface": ["src/{a,{b,c}}"]},
+            {"authorized_surface": ["src/{a,**}"]},
         ):
             err = validate_authorized_surface_shape(bad_surface)
             if err is None:
@@ -3893,6 +4655,14 @@ def run_self_test() -> int:
 
 
 def main() -> int:
+    if "--help" in sys.argv[1:] or "-h" in sys.argv[1:]:
+        print(
+            "usage: spec-verify-check.py [-h | --help | --include-risk-probes | "
+            "--validate-risk-probes | --print-risk-probes-digest | "
+            "--print-authorized-surface | --write-untracked-baseline | "
+            "--check <markdown-path> | --check-expected <json-path> | --self-test]"
+        )
+        return 0
     include_risk_probes = False
     validate_risk_probes_only = False
     print_risk_probes_digest = False
@@ -3929,6 +4699,10 @@ def main() -> int:
             return 2
         return run_check_expected_mode(Path(sys.argv[2]))
 
+    if len(sys.argv) != 1:
+        print(f"unknown argument(s): {' '.join(sys.argv[1:])}", file=sys.stderr)
+        return 2
+
     bench_mode = "BENCH_WORKDIR" in os.environ
     work = Path(os.environ.get("BENCH_WORKDIR") or os.getcwd())
     devlyn_dir = work / ".devlyn"
@@ -3981,6 +4755,24 @@ 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)
+    external_diff = devlyn_dir / "external-diff.patch"
+    if external_diff.is_file() and state.get("mode") != "verify-only":
+        error = (
+            ".devlyn/external-diff.patch requires pipeline.state.json mode "
+            f"'verify-only'; actual mode is {state.get('mode')!r}"
+        )
+        print(f"[spec-verify] carrier malformed: {error}", file=sys.stderr)
+        write_malformed_finding(
+            devlyn_dir,
+            error,
+            external_diff,
+            fix_hint=(
+                "Remove `.devlyn/external-diff.patch` for ordinary runs, or use "
+                "`/devlyn:resolve --verify-only <diff-or-PR-ref> --spec <path>` only when "
+                "intentionally verifying an external patch."
+            ),
+        )
+        return 1
     integrity_error = source_integrity_error(src_type, state, source_md)
     if integrity_error:
         print(f"[spec-verify] carrier malformed: {integrity_error}", file=sys.stderr)
@@ -4099,12 +4891,17 @@ def main() -> int:
     results_path = devlyn_dir / "spec-verify.results.json"
     findings_path = devlyn_dir / output_findings_name()
 
-    verify_env = os.environ.copy()
-    verify_env["BENCH_WORKDIR"] = str(work)
-
     results: list[dict] = []
     findings: list[dict] = []
     finding_seq = 1
+    runner = process_evidence_module()
+    evidence_phase, evidence_run_id, evidence_round, manifest_relative = (
+        mechanical_evidence_identity(state, runner)
+    )
+    manifest_path = work / manifest_relative
+    obligations: list[dict] = []
+    capability_denials: list[dict] = []
+    evidence_error: str | None = None
 
     for idx, vc in enumerate(commands):
         cmd = vc.get("cmd")
@@ -4117,180 +4914,186 @@ def main() -> int:
         expected_exit = vc.get("exit_code", 0)
         stdout_contains = vc.get("stdout_contains", []) or []
         stdout_not_contains = vc.get("stdout_not_contains", []) or []
+        timeout_sec = verification_timeout_sec(vc)
+        obligation = mechanical_obligation(vc, idx, evidence_phase)
+        obligations.append(obligation)
+        criterion_ref = (
+            f"risk-probe:{vc.get('id')}"
+            if is_risk_probe
+            else f"spec-verify://verification_commands/{idx}"
+        )
+        file_ref = (
+            ".devlyn/risk-probes.jsonl"
+            if is_risk_probe
+            else ".devlyn/spec-verify.json"
+        )
 
         try:
-            proc = subprocess.run(
-                cmd,
-                cwd=str(work),
-                shell=True,
-                env=verify_env,
-                capture_output=True,
-                text=True,
-                timeout=60,
+            entry = capture_mechanical_command(
+                runner, work, manifest_path, evidence_run_id, evidence_phase,
+                evidence_round, obligation,
             )
-            # Mirror run-fixture.sh post-run verifier: combined stdout+stderr.
-            out = (proc.stdout or "") + (proc.stderr or "")
-            ok_exit = proc.returncode == expected_exit
-            ok_contains = all(s in out for s in stdout_contains)
-            ok_not = not any(s in out for s in stdout_not_contains)
-            passed = bool(ok_exit and ok_contains and ok_not)
-
-            if passed:
-                reason = None
-            elif not ok_exit:
-                reason = "exit"
-            elif not ok_contains:
-                reason = "missing_contains"
-            else:
-                reason = "unexpected_text"
-
+            stdout = (work / entry["stdout"]["path"]).read_bytes()
+            stderr = (work / entry["stderr"]["path"]).read_bytes()
+        except (runner.EvidenceError, OSError, UnicodeError, ValueError) as exc:
+            evidence_error = str(exc)
             results.append({
                 "index": idx,
                 "cmd": cmd,
-                "expected_exit": expected_exit,
-                "actual_exit": proc.returncode,
-                "stdout_contains": stdout_contains,
-                "stdout_not_contains": stdout_not_contains,
-                "pass": passed,
-                "reason": reason,
-                "stdout_tail": out[-500:],
+                "pass": False,
+                "reason": "process_evidence_invalid",
             })
-
-            if not passed:
-                # Construct fine-grained message naming the specific failure.
-                if not ok_exit:
-                    msg = (
-                        f"Verification command #{idx + 1} failed: expected exit "
-                        f"{expected_exit}, got {proc.returncode}."
-                    )
-                elif not ok_contains:
-                    missing = [s for s in stdout_contains if s not in out]
-                    msg = (
-                        f"Verification command #{idx + 1} failed: expected "
-                        f"output to contain {missing!r}."
-                    )
-                else:
-                    forbidden = [s for s in stdout_not_contains if s in out]
-                    msg = (
-                        f"Verification command #{idx + 1} failed: output "
-                        f"contained forbidden literal(s) {forbidden!r}."
-                    )
-
-                fix_hint = (
-                    f"See .devlyn/spec-verify.results.json for the captured "
-                    f"output. Update implementation so `{cmd}` matches the "
-                    f"contract (exit_code={expected_exit}, "
-                    f"contains={stdout_contains}, not_contains={stdout_not_contains})."
-                )
-
-                rule_id = (
-                    "correctness.risk-probe-failed"
-                    if is_risk_probe
-                    else "correctness.spec-literal-mismatch"
-                )
-                criterion_ref = (
-                    f"risk-probe:{vc.get('id')}"
-                    if is_risk_probe
-                    else f"spec-verify://verification_commands/{idx}"
-                )
-                file_ref = (
-                    ".devlyn/risk-probes.jsonl"
-                    if is_risk_probe
-                    else ".devlyn/spec-verify.json"
-                )
-                if is_risk_probe:
-                    fix_hint = (
-                        f"Risk probe `{vc.get('id')}` derived from "
-                        f"{vc.get('derived_from')!r} failed. See "
-                        ".devlyn/spec-verify.results.json for captured output "
-                        "and update the implementation to satisfy the visible "
-                        "verification bullet."
-                    )
-
-                findings.append({
-                    "id": f"{output_finding_prefix()}-{finding_seq:04d}",
-                    "rule_id": rule_id,
-                    "level": "error",
-                    "severity": "CRITICAL",
-                    "confidence": 1.0,
-                    "message": msg,
-                    "file": file_ref,
-                    "line": 1,
-                    "phase": output_phase(),
-                    "criterion_ref": criterion_ref,
-                    "fix_hint": fix_hint,
-                    "blocking": True,
-                    "status": "open",
-                })
-                finding_seq += 1
-
-        except subprocess.TimeoutExpired:
-            results.append({"index": idx, "cmd": cmd, "pass": False,
-                            "reason": "timeout"})
-            rule_id = (
-                "correctness.risk-probe-failed"
-                if vc.get("_risk_probe")
-                else "correctness.spec-literal-mismatch"
-            )
             findings.append({
                 "id": f"{output_finding_prefix()}-{finding_seq:04d}",
-                "rule_id": rule_id,
+                "rule_id": "invariant.process-evidence-invalid",
                 "level": "error",
                 "severity": "CRITICAL",
                 "confidence": 1.0,
-                "message": (
-                    f"Verification command #{idx + 1} timed out after 60s."
-                ),
-                "file": ".devlyn/risk-probes.jsonl" if vc.get("_risk_probe") else ".devlyn/spec-verify.json",
+                "message": f"MECHANICAL process evidence is invalid: {exc}.",
+                "file": manifest_relative,
                 "line": 1,
                 "phase": output_phase(),
-                "criterion_ref": (
-                    f"risk-probe:{vc.get('id')}"
-                    if vc.get("_risk_probe")
-                    else f"spec-verify://verification_commands/{idx}"
-                ),
+                "criterion_ref": "process-evidence://mechanical",
                 "fix_hint": (
-                    f"Command `{cmd}` exceeded 60s. Reduce work or fix a "
-                    f"hang in the implementation."
+                    "Preserve the existing manifest and raw streams, then fix the "
+                    "runner identity or evidence mutation before rerunning this phase."
                 ),
                 "blocking": True,
                 "status": "open",
             })
             finding_seq += 1
-        except Exception as e:  # noqa: BLE001 — surface any harness error explicitly
-            results.append({"index": idx, "cmd": cmd, "pass": False,
-                            "reason": f"error:{e.__class__.__name__}:{e}"})
-            rule_id = (
-                "correctness.risk-probe-failed"
-                if vc.get("_risk_probe")
-                else "correctness.spec-literal-mismatch"
-            )
+            break
+
+        outcome = entry["outcome"]
+        classification = entry["classification"]
+        combined = stdout + stderr
+        actual_exit = outcome["exit_code"] if outcome["kind"] == "exit" else None
+        ok_exit = outcome["kind"] == "exit" and actual_exit == expected_exit
+        ok_contains = all(s.encode("utf-8") in combined for s in stdout_contains)
+        ok_not = not any(s.encode("utf-8") in combined for s in stdout_not_contains)
+        passed = entry["expectation_met"]
+        if classification["kind"] == "capability_denied":
+            reason = "capability_denied"
+            capability_denials.append({
+                "cmd": cmd,
+                "operation": classification["operation"],
+                "evidence_id": entry["id"],
+            })
+        elif passed:
+            reason = None
+        elif outcome["kind"] == "timeout":
+            reason = "timeout"
+        elif not ok_exit:
+            reason = "exit"
+        elif not ok_contains:
+            reason = "missing_contains"
+        else:
+            reason = "unexpected_text"
+
+        results.append({
+            "index": idx,
+            "cmd": cmd,
+            "expected_exit": expected_exit,
+            "actual_exit": actual_exit,
+            "timeout_sec": timeout_sec,
+            "stdout_contains": stdout_contains,
+            "stdout_not_contains": stdout_not_contains,
+            "pass": passed,
+            "reason": reason,
+            "evidence_id": entry["id"],
+            "outcome": outcome,
+            "classification": classification,
+            "stdout": entry["stdout"],
+            "stderr": entry["stderr"],
+        })
+
+        if classification["kind"] == "capability_denied" or passed:
+            continue
+
+        if outcome["kind"] == "timeout":
             findings.append({
                 "id": f"{output_finding_prefix()}-{finding_seq:04d}",
-                "rule_id": rule_id,
+                "rule_id": "correctness.verification-timeout",
                 "level": "error",
                 "severity": "CRITICAL",
                 "confidence": 1.0,
                 "message": (
-                    f"Verification command #{idx + 1} raised "
-                    f"{e.__class__.__name__}: {e}."
+                    f"Verification command #{idx + 1} timed out after {timeout_sec}s "
+                    f"(timeout_sec={timeout_sec}, maximum 600)."
                 ),
-                "file": ".devlyn/risk-probes.jsonl" if vc.get("_risk_probe") else ".devlyn/spec-verify.json",
+                "file": file_ref,
                 "line": 1,
                 "phase": output_phase(),
-                "criterion_ref": (
-                    f"risk-probe:{vc.get('id')}"
-                    if vc.get("_risk_probe")
-                    else f"spec-verify://verification_commands/{idx}"
-                ),
+                "criterion_ref": criterion_ref,
                 "fix_hint": (
-                    f"Command `{cmd}` could not be executed. Check the work-dir "
-                    f"state and any environment setup the command requires."
+                    f"Command `{cmd}` exceeded its {timeout_sec}s timeout_sec budget. "
+                    "Increase timeout_sec up to 600 when the verification legitimately "
+                    "needs more time, or fix a hang in the implementation."
                 ),
                 "blocking": True,
                 "status": "open",
             })
             finding_seq += 1
+            continue
+
+        if not ok_exit:
+            actual = (
+                str(actual_exit)
+                if outcome["kind"] == "exit"
+                else f"{outcome['kind']}"
+                + (f" signal {outcome['signal']}" if outcome["kind"] == "signal" else "")
+            )
+            msg = (
+                f"Verification command #{idx + 1} failed: expected exit "
+                f"{expected_exit}, got {actual}."
+            )
+        elif not ok_contains:
+            missing = [s for s in stdout_contains if s.encode("utf-8") not in combined]
+            msg = (
+                f"Verification command #{idx + 1} failed: expected "
+                f"output to contain {missing!r}."
+            )
+        else:
+            forbidden = [s for s in stdout_not_contains if s.encode("utf-8") in combined]
+            msg = (
+                f"Verification command #{idx + 1} failed: output "
+                f"contained forbidden literal(s) {forbidden!r}."
+            )
+
+        rule_id = (
+            "correctness.risk-probe-failed"
+            if is_risk_probe
+            else "correctness.spec-literal-mismatch"
+        )
+        fix_hint = (
+            f"Inspect `{manifest_relative}` entry `{entry['id']}` and its sealed raw "
+            f"streams. Update implementation so `{cmd}` matches the contract "
+            f"(exit_code={expected_exit}, contains={stdout_contains}, "
+            f"not_contains={stdout_not_contains})."
+        )
+        if is_risk_probe:
+            fix_hint = (
+                f"Risk probe `{vc.get('id')}` derived from {vc.get('derived_from')!r} "
+                f"failed. Inspect `{manifest_relative}` entry `{entry['id']}` and "
+                "update the implementation to satisfy the visible verification bullet."
+            )
+
+        findings.append({
+            "id": f"{output_finding_prefix()}-{finding_seq:04d}",
+            "rule_id": rule_id,
+            "level": "error",
+            "severity": "CRITICAL",
+            "confidence": 1.0,
+            "message": msg,
+            "file": file_ref,
+            "line": 1,
+            "phase": output_phase(),
+            "criterion_ref": criterion_ref,
+            "fix_hint": fix_hint,
+            "blocking": True,
+            "status": "open",
+        })
+        finding_seq += 1
 
     expected_findings, finding_seq = expected_contract_findings(
         expected_data,
@@ -4309,7 +5112,40 @@ def main() -> int:
         )
         findings.extend(surface_findings)
 
-    results_path.write_text(json.dumps({"commands": results}, indent=2) + "\n")
+    evidence_carrier = None
+    if evidence_error is None and obligations:
+        try:
+            evidence_carrier = runner.validate_manifest(
+                work, manifest_relative, evidence_run_id, evidence_phase,
+                evidence_round, obligations, require_expectations=False,
+            )
+            results = runner.bound_carrier_summary_commands(work, evidence_carrier)
+        except (runner.EvidenceError, OSError, UnicodeError, ValueError) as exc:
+            evidence_error = str(exc)
+            findings.append({
+                "id": f"{output_finding_prefix()}-{finding_seq:04d}",
+                "rule_id": "invariant.process-evidence-invalid",
+                "level": "error",
+                "severity": "CRITICAL",
+                "confidence": 1.0,
+                "message": f"MECHANICAL process evidence validation failed: {exc}.",
+                "file": manifest_relative,
+                "line": 1,
+                "phase": output_phase(),
+                "criterion_ref": "process-evidence://mechanical",
+                "fix_hint": (
+                    "Preserve the manifest and raw streams, then correct the "
+                    "missing, altered, or path-escaping evidence before rerunning."
+                ),
+                "blocking": True,
+                "status": "open",
+            })
+            finding_seq += 1
+
+    results_path.write_text(json.dumps({
+        "commands": results,
+        "process_evidence": evidence_carrier,
+    }, indent=2) + "\n")
 
     # Append findings (jsonl). BUILD_GATE merge step concatenates this onto
     # build_gate.findings.jsonl; never overwrite the orchestrator's own gate
@@ -4320,6 +5156,15 @@ def main() -> int:
 
     failed = [r for r in results if r.get("pass") is False]
     blocking_findings = [f for f in findings if f.get("severity") in {"CRITICAL", "HIGH"}]
+    if capability_denials:
+        denial = capability_denials[0]
+        print(
+            "BLOCKED:build-env-underprovisioned: "
+            f"{denial['operation']} denied for `{denial['cmd']}`; "
+            f"evidence {manifest_relative}#{denial['evidence_id']}",
+            file=sys.stderr,
+        )
+        return 2
     if failed or blocking_findings:
         print(
             f"[spec-verify] {len(failed)}/{len(results)} command(s) failed; "