devlyn-cli 2.10.0 → 3.0.0

package/config/skills/_shared/judge-output-parser.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python3
+"""Parse the one permitted pair-JUDGE stdout emission contract."""
+
+from __future__ import annotations
+
+import json
+import pathlib
+from typing import Any
+
+
+FINDING_SEVERITIES = {"CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"}
+VERDICTS = {"PASS", "PASS_WITH_ISSUES", "FAIL", "NEEDS_WORK", "BLOCKED"}
+ENVELOPE_KEYS = {"text", "stopReason", "sessionId", "requestId"}
+IGNORABLE_FENCES = {"```", "```json", "```jsonl"}
+NARRATIVE_PREAMBLE_BYTES = frozenset(
+    b"\t\n\r !\"$%&'()*+,-./0123456789:;<=>?@"
+    b"ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_abcdefghijklmnopqrstuvwxyz|}~"
+) | frozenset(range(0x80, 0x100))
+STREAM_RECORD_TYPES = {"system", "assistant", "user", "result"}
+
+
+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) -> Any:
+    return json.loads(
+        text,
+        parse_constant=reject_json_constant,
+        object_pairs_hook=reject_duplicate_keys,
+    )
+
+
+def collect_text(text: str, source: pathlib.Path) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
+    findings: list[dict[str, Any]] = []
+    summary: dict[str, Any] | None = None
+    for line_no, line in enumerate(text.splitlines(), 1):
+        raw = line.strip()
+        if not raw or raw in IGNORABLE_FENCES:
+            continue
+        if raw.startswith("# SUMMARY "):
+            if summary is not None:
+                raise SystemExit(f"error: record after terminal verdict at {source}:{line_no}")
+            try:
+                item = loads_strict_json(raw.removeprefix("# SUMMARY ").strip())
+            except ValueError as exc:
+                raise SystemExit(f"error: invalid SUMMARY JSON at {source}:{line_no}: {exc}")
+            if not isinstance(item, dict) or item.get("verdict") not in VERDICTS:
+                raise SystemExit(f"error: verdict has unknown value at {source}:{line_no}")
+            summary = item
+            continue
+        if summary is not None:
+            raise SystemExit(f"error: record after terminal verdict at {source}:{line_no}")
+        if raw in VERDICTS:
+            summary = {"verdict": raw}
+            continue
+        try:
+            item = loads_strict_json(raw)
+        except ValueError as exc:
+            raise SystemExit(f"error: invalid JSONL at {source}:{line_no}: {exc}")
+        if not isinstance(item, dict):
+            raise SystemExit(f"error: JSONL item is not an object at {source}:{line_no}")
+        severity = str(item.get("severity") or "").upper()
+        if severity not in FINDING_SEVERITIES:
+            raise SystemExit(f"error: finding missing valid severity at {source}:{line_no}")
+        findings.append(item)
+    return findings, summary
+
+
+def recover_envelope_text(text: str, source: pathlib.Path) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
+    encoded = text.encode("utf-8")
+    for cut, byte in enumerate(encoded[:-1], 1):
+        if byte not in NARRATIVE_PREAMBLE_BYTES:
+            break
+        try:
+            findings, summary = collect_text(encoded[cut:].decode("utf-8"), source)
+        except (UnicodeDecodeError, SystemExit):
+            continue
+        if summary is not None and summary.get("verdict") == "NEEDS_WORK" and findings:
+            return findings, summary
+    raise SystemExit("error: no admissible envelope recovery")
+
+
+def collect_message_stream(
+    text: str, source: pathlib.Path
+) -> tuple[list[dict[str, Any]], dict[str, Any] | None] | None:
+    """Bind adjudication to a whole-message NDJSON stream's terminal assistant turn.
+
+    Returns None when the first record does not declare that stream. Once it does,
+    this returns or rejects: tool and narration turns are never forwarded, and no
+    envelope recovery is attempted.
+    """
+    lines = [(no, raw) for no, line in enumerate(text.splitlines(), 1) if (raw := line.strip())]
+    if not lines:
+        return None
+    try:
+        first = loads_strict_json(lines[0][1])
+    except ValueError:
+        return None
+    if (
+        not isinstance(first, dict)
+        or first.get("type") != "system"
+        or str(first.get("severity") or "").upper() in FINDING_SEVERITIES
+    ):
+        return None
+    if first.get("subtype") != "init":
+        raise SystemExit(f"error: stream must open with system/init at {source}:{lines[0][0]}")
+    records = [first]
+    for line_no, raw in lines[1:]:
+        try:
+            item = loads_strict_json(raw)
+        except ValueError as exc:
+            raise SystemExit(f"error: invalid stream NDJSON at {source}:{line_no}: {exc}")
+        if not isinstance(item, dict) or item.get("type") not in STREAM_RECORD_TYPES:
+            raise SystemExit(f"error: unknown stream record at {source}:{line_no}")
+        if item["type"] == "system":
+            raise SystemExit(f"error: stream has a second system record at {source}:{line_no}")
+        records.append(item)
+
+    results = [item for item in records if item["type"] == "result"]
+    if len(results) != 1 or results[0] is not records[-1]:
+        raise SystemExit(f"error: stream needs exactly one terminal result at {source}")
+    result = results[0]
+    if (
+        result.get("subtype") != "success"
+        or result.get("is_error") is not False
+        or result.get("stop_reason") != "end_turn"
+    ):
+        raise SystemExit(f"error: stream result is not a successful end_turn at {source}")
+
+    assistants = [item for item in records if item["type"] == "assistant"]
+    terminals = [
+        item
+        for item in assistants
+        if isinstance(item.get("message"), dict) and item["message"].get("stop_reason") == "end_turn"
+    ]
+    if (
+        len(terminals) != 1
+        or terminals[0] is not assistants[-1]
+        or terminals[0] is not records[-2]
+    ):
+        raise SystemExit(f"error: stream needs exactly one final end_turn assistant message at {source}")
+
+    session = first.get("session_id")
+    if not isinstance(session, str) or any(
+        item.get("session_id") != session for item in (terminals[0], result)
+    ):
+        raise SystemExit(f"error: stream session identity does not agree at {source}")
+
+    blocks = terminals[0]["message"].get("content")
+    if not isinstance(blocks, list):
+        raise SystemExit(f"error: stream terminal message has no content blocks at {source}")
+    parts: list[str] = []
+    for block in blocks:
+        if not isinstance(block, dict):
+            raise SystemExit(f"error: stream content block is not an object at {source}")
+        if block.get("type") == "text":
+            if not isinstance(block.get("text"), str):
+                raise SystemExit(f"error: stream text block is not a string at {source}")
+            parts.append(block["text"])
+    message_text = "".join(parts)
+    if result.get("result") != message_text:
+        raise SystemExit(f"error: stream result text does not match the terminal message at {source}")
+    return collect_text(message_text, source)
+
+
+def collect_stdout(stdout_path: pathlib.Path) -> tuple[list[dict[str, Any]], dict[str, Any] | None]:
+    stdout_text = stdout_path.read_text(encoding="utf-8")
+    try:
+        candidate = loads_strict_json(stdout_text)
+    except ValueError:
+        candidate = None
+    if isinstance(candidate, dict) and ENVELOPE_KEYS.issubset(candidate) and "severity" not in candidate:
+        if candidate["stopReason"] != "EndTurn":
+            raise SystemExit(
+                f"error: envelope stopReason must be 'EndTurn' at {stdout_path}; "
+                f"got {candidate['stopReason']!r}"
+            )
+        if not isinstance(candidate["text"], str):
+            raise SystemExit(f"error: envelope text must be a string at {stdout_path}")
+        try:
+            return collect_text(candidate["text"], stdout_path)
+        except SystemExit as exc:
+            try:
+                return recover_envelope_text(candidate["text"], stdout_path)
+            except SystemExit:
+                raise SystemExit(f"error: envelope text rejected: {exc}") from None
+    stream = collect_message_stream(stdout_text, stdout_path)
+    if stream is not None:
+        return stream
+    return collect_text(stdout_text, stdout_path)

package/config/skills/_shared/judge-role-evidence.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""Authenticate explicit read-only judge transport; never accept mutation receipts."""
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import re
+import runpy
+import sys
+import tempfile
+
+sys.dont_write_bytecode = True
+ROLE = runpy.run_path(Path(__file__).with_name("role-config.py"))
+loads, encoded, digest = (ROLE[key] for key in ("loads", "encoded", "digest"))
+
+
+def require(ok, detail):
+    if not ok:
+        raise ValueError("BLOCKED:judge-role-evidence: " + detail)
+
+
+def option(argv, *names):
+    values = []
+    for index, item in enumerate(argv):
+        for name in names:
+            if item == name:
+                require(index + 1 < len(argv), f"missing {name}")
+                values.append(argv[index + 1])
+            elif item.startswith(name + "="):
+                values.append(item[len(name) + 1:])
+    require(len(values) <= 1, f"duplicate {names[0]}")
+    return values[0] if values else None
+
+
+def seal(devlyn, name):
+    path = devlyn / name
+    require(path.parent == devlyn and not path.is_symlink() and path.is_file(), f"not a regular canonical artifact: {name}")
+    raw = path.read_bytes()
+    return {"path": ".devlyn/" + name, "sha256": digest(raw), "bytes": len(raw)}, raw
+
+
+def claude_result(raw, exit_code):
+    value = loads(raw)
+    require(type(exit_code) is int and exit_code == 0 and isinstance(value, dict), "unsuccessful Claude execution")
+    require(value.get("type") == "result" and value.get("subtype") == "success"
+            and value.get("is_error") is False and value.get("stop_reason") == "end_turn"
+            and isinstance(value.get("session_id"), str) and bool(value["session_id"].strip())
+            and isinstance(value.get("result"), str), "unsuccessful or malformed Claude terminal envelope")
+    model = runpy.run_path(Path(__file__).with_name("state-phase-write.py"))["select_claude_primary_model"](value)
+    return value["result"].encode(), model, value["session_id"]
+
+
+def codex_header(stderr):
+    prefix, separator, _ = stderr.partition("\nuser\n")
+    require(bool(separator), "native header must precede the echoed user prompt")
+    starts = list(re.finditer(r"^OpenAI Codex v[^\n]+\n--------\n", prefix, re.M))
+    require(len(starts) == 1, "missing or conflicting first native Codex header")
+    header = prefix[starts[0].end():]
+    require(header.endswith("\n--------"), "malformed native Codex header boundary")
+    fields = {"cli_version": "codex-cli " + starts[0].group(0).splitlines()[0].removeprefix("OpenAI Codex v")}
+    for key in ("model", "workdir", "sandbox", "session id", "reasoning effort"):
+        values = re.findall(r"^" + re.escape(key) + r": (.+)$", header, re.M)
+        require(len(values) == 1 and bool(values[0].strip()), f"missing/conflicting native {key}")
+        fields[key] = values[0]
+    return fields
+
+
+def describe(devlyn, state, role, exit_code):
+    require(type(exit_code) is int and exit_code == 0, "judge process did not complete successfully")
+    resolution = ROLE["snapshot"](state)
+    require(resolution is not None and role in ("primary_judge", "pair_judge"), "missing frozen judge selection")
+    entry = resolution["roles"][role]
+    engine = entry["engine"]
+    require(engine in {"codex", "claude"}, "this judge channel has no explicit-field evidence contract")
+    require(not entry.get("skipped_reason"), "cannot authenticate a skipped judge")
+    verify = state.get("phases", {}).get("verify", {})
+    require(isinstance(verify, dict) and type(verify.get("round")) is int, "missing VERIFY round")
+    require(ROLE["primary_engine"](state) == resolution["roles"]["primary_judge"]["engine"], "primary differs from frozen selection")
+    stem = engine + "-judge.r" + str(verify["round"])
+    artifacts = {}
+    for key, suffix in (("argv", ".argv.json"), ("prompt", ".prompt"), ("stderr", ".stderr")):
+        artifacts[key], raw = seal(devlyn, stem + suffix)
+        if key == "argv":
+            argv = loads(raw)
+        elif key == "prompt":
+            prompt = raw.decode()
+        else:
+            stderr = raw.decode()
+    require(isinstance(argv, list) and all(isinstance(x, str) for x in argv), "argv must be an array of strings")
+    require(prompt in argv, "canonical prompt is not an exact dispatched argument")
+    diagnostics = stderr.partition("\nuser\n")[0] if engine == "codex" else stderr
+    require(not re.search(r"(?im)^.*(?:model|effort).*\b(?:ignor\w*|clamp\w*|unsupported|not supported)\b", diagnostics), "native diagnostic rejected or ignored an explicit option")
+    requested_model, requested_effort = entry.get("model_requested"), entry.get("effort_requested")
+    supplied_model = option(argv, "-m", "--model")
+    if requested_model is not None:
+        require(supplied_model == requested_model, "requested model differs from argv")
+    if engine == "claude":
+        for flag, expected in (("--permission-mode", "dontAsk"), ("--tools", "Read,Grep,Glob"),
+                               ("--allowedTools", "Read,Grep,Glob"), ("--setting-sources", "project"), ("--output-format", "json")):
+            require(option(argv, flag) == expected, f"Claude {flag} differs from read-only contract")
+        require("--strict-mcp-config" in argv and loads(option(argv, "--mcp-config") or "null") == {"mcpServers": {}}, "Claude MCP isolation missing")
+        require(any(Path(arg).name == "run-bounded.py" and argv[i + 1:i + 3] == ["600", "--"] for i, arg in enumerate(argv)), "Claude 600s bound missing")
+        if requested_effort:
+            require(option(argv, "--effort") == requested_effort, "requested effort differs from argv")
+        artifacts["raw"], raw = seal(devlyn, stem + ".output.json")
+        derived, observed, session = claude_result(raw, exit_code)
+        effort = None
+        basis = "native-Claude-result-modelUsage"
+    else:
+        require(option(argv, "-s", "--sandbox") == "read-only", "judge sandbox is not read-only")
+        cwd = option(argv, "-C", "--cd")
+        require(isinstance(cwd, str) and Path(cwd).is_absolute() and Path(cwd).resolve() == devlyn.parent.resolve(), "judge cwd differs from actual worktree")
+        require(not any(arg in argv for arg in ("--dangerously-bypass-approvals-and-sandbox", "--yolo", "--full-auto")), "judge bypass is forbidden")
+        flags = [argv[i + 1] for i, item in enumerate(argv[:-1]) if item in {"-c", "--config"}]
+        efforts = [flag.split("=", 1)[1].strip('"') for flag in flags if flag.startswith("model_reasoning_effort=")]
+        require(len(efforts) == 1 and (not requested_effort or efforts[0] == requested_effort), "missing/conflicting requested effort")
+        require("[codex-monitored] isolated=1\n" in diagnostics, "missing actual isolation marker")
+        require(re.search(r"^\[codex-monitored\] start: .* timeout=600s ", diagnostics, re.M) is not None, "missing actual 600s bound")
+        header = codex_header(stderr)
+        require(Path(header["workdir"]).is_absolute() and Path(header["workdir"]).resolve() == devlyn.parent.resolve()
+                and header["sandbox"] == "read-only", "observed workdir/sandbox mismatch")
+        observed, effort, session = header["model"], header["reasoning effort"], header["session id"]
+        require(effort == efforts[0], "native effort differs from dispatched effort")
+        artifacts["raw"], derived = seal(devlyn, stem + ".stdout")
+        basis = "native-Codex-configuration-header"
+    require(requested_model is None or observed == requested_model, "observed model differs from explicit requested model")
+    artifacts["stdout"] = {"path": ".devlyn/" + stem + ".stdout", "sha256": digest(derived), "bytes": len(derived)}
+    record = {"schema": 1, "run_id": state.get("run_id"), "round": verify["round"], "role": role,
+              "engine": engine, "model_requested": requested_model, "effort_requested": requested_effort,
+              "model_observed": observed, "effort_observed": effort, "session_id": session,
+              "identity_basis": basis, "exit_code": exit_code, "resolution_sha256": resolution["sha256"], "artifacts": artifacts}
+    return record, derived
+
+
+def authenticate(devlyn, state, role):
+    resolution = ROLE["snapshot"](state)
+    engine = resolution["roles"][role]["engine"]
+    stem = engine + "-judge.r" + str(state["phases"]["verify"]["round"])
+    binding, raw = seal(devlyn, stem + ".role-evidence.json")
+    document = loads(raw)
+    actual, derived = describe(devlyn, state, role, document.get("exit_code"))
+    require(actual == document, "retained role evidence differs from current raw/selection")
+    _, stdout = seal(devlyn, stem + ".stdout")
+    require(stdout == derived, "derived stdout differs from retained native result")
+    _, canonical = seal(devlyn, engine + "-judge.stdout")
+    require(canonical == derived, "canonical collector stdout differs from retained native result")
+    return {**binding, "model_observed": actual["model_observed"], "effort_observed": actual["effort_observed"],
+            "identity_basis": actual["identity_basis"], "artifacts": list(actual["artifacts"].values())}
+
+
+def required_roles(state):
+    resolution = ROLE["snapshot"](state)
+    if resolution is None:
+        return []
+    return [role for role in ("primary_judge", "pair_judge")
+            if not resolution["roles"][role].get("skipped_reason")
+            and any(resolution["roles"][role].get(key) is not None for key in ("model_requested", "effort_requested"))]
+
+
+def self_test():
+    with tempfile.TemporaryDirectory() as temp:
+        work = Path(temp).resolve(); devlyn = work / ".devlyn"; devlyn.mkdir()
+        config = {"roles": {"primary_judge": {"engine": "claude", "model": "fixture-claude-model", "effort": "high"},
+                            "pair_judge": {"engine": "codex", "model": "gpt-6-astra", "effort": "high"}}}
+        (devlyn / "engines.json").write_bytes(encoded(config))
+        selection = ROLE["resolve"](work, "codex", available=lambda e: True)
+        state = {"run_id": "fixture", "role_resolution": selection, "engine": "codex", "phases": {"verify": {"engine": "claude", "round": 0}}}
+        envelope = {"type": "result", "subtype": "success", "is_error": False, "stop_reason": "end_turn",
+                    "session_id": "fixture-claude", "result": "PASS", "modelUsage": {"fixture-claude-model": {}}}
+        argv = ["python3", "run-bounded.py", "600", "--", "claude", "-p", "review", "--model", "fixture-claude-model", "--effort", "high", "--permission-mode", "dontAsk", "--tools", "Read,Grep,Glob", "--allowedTools", "Read,Grep,Glob", "--setting-sources", "project", "--output-format", "json", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}']
+        for suffix, raw in (("argv.json", encoded(argv)), ("prompt", b"review"), ("stderr", b""), ("output.json", encoded(envelope))):
+            (devlyn / ("claude-judge.r0." + suffix)).write_bytes(raw)
+        receipt, text = describe(devlyn, state, "primary_judge", 0)
+        assert text == b"PASS" and receipt["effort_observed"] is None
+        (devlyn / "claude-judge.stdout").write_bytes(text)
+        (devlyn / "claude-judge.r0.stdout").write_bytes(text)
+        (devlyn / "claude-judge.r0.role-evidence.json").write_bytes(encoded(receipt))
+        authenticate(devlyn, state, "primary_judge")
+        for field, value in (("subtype", "error_max_turns"), ("stop_reason", "tool_use"), ("is_error", True), ("session_id", ""), ("result", None)):
+            bad = {**envelope, field: value}
+            try:
+                claude_result(encoded(bad), 0)
+            except ValueError:
+                pass
+            else:
+                raise AssertionError(field)
+        for status in (1, 124, True):
+            try:
+                describe(devlyn, state, "primary_judge", status)
+            except ValueError:
+                pass
+            else:
+                raise AssertionError("failed exit accepted")
+        (devlyn / "claude-judge.stdout").write_bytes(b"forged PASS")
+        try:
+            authenticate(devlyn, state, "primary_judge")
+        except ValueError:
+            pass
+        else:
+            raise AssertionError("derived tampering accepted")
+        prompt = "review unsupported model/effort warning handling\n"
+        argv = ["bash", "codex-monitored.sh", "-C", str(work), "-s", "read-only", "-m", "gpt-6-astra", "-c", "model_reasoning_effort=high", prompt]
+        header = f"[codex-monitored] start: ts=fixture timeout=600s bin=codex\n[codex-monitored] isolated=1\nOpenAI Codex v0.153.4\n--------\nworkdir: {work}\nmodel: gpt-6-astra\nsandbox: read-only\nreasoning effort: high\nsession id: fixture-codex\n--------\nuser\nreview\n"
+        header = header.replace("\nuser\nreview\n", "\nuser\n" + prompt)
+        for suffix, raw in (("argv.json", encoded(argv)), ("prompt", prompt.encode()), ("stderr", header.encode()), ("stdout", b"PASS\n")):
+            (devlyn / ("codex-judge.r0." + suffix)).write_bytes(raw)
+        receipt, _ = describe(devlyn, state, "pair_judge", 0)
+        assert receipt["model_observed"] == "gpt-6-astra"
+        alias = work / "logical-cwd"
+        alias.symlink_to(work, target_is_directory=True)
+        alias_argv = [str(alias) if arg == str(work) else arg for arg in argv]
+        alias_header = header.replace(f"workdir: {work}\n", f"workdir: {alias}\n")
+        (devlyn / "codex-judge.r0.argv.json").write_bytes(encoded(alias_argv))
+        (devlyn / "codex-judge.r0.stderr").write_text(alias_header)
+        receipt, _ = describe(devlyn, state, "pair_judge", 0)
+        assert receipt["artifacts"]["argv"]["sha256"] == digest(encoded(alias_argv))
+        assert (devlyn / "codex-judge.r0.stderr").read_text() == alias_header
+        elsewhere = work / "elsewhere"; elsewhere.mkdir()
+        (devlyn / "codex-judge.r0.argv.json").write_bytes(encoded([str(elsewhere) if arg == str(work) else arg for arg in argv]))
+        try:
+            describe(devlyn, state, "pair_judge", 0)
+        except ValueError:
+            pass
+        else:
+            raise AssertionError("different physical worktree accepted")
+        (devlyn / "codex-judge.r0.argv.json").write_bytes(encoded(argv))
+        for bad in ("Warning: model effort unsupported and ignored\n" + header, "\nuser\n" + header, header.replace("\nmodel:", "\nmodel: gpt-5.6-sol\nmodel:"), header.replace("sandbox: read-only", "sandbox: workspace-write"), header.replace("model: gpt-6-astra", "model: gpt-5.6-sol"), header.replace("[codex-monitored] isolated=1\n", ""), header.replace("timeout=600s", "timeout=300s")):
+            (devlyn / "codex-judge.r0.stderr").write_text(bad)
+            try:
+                describe(devlyn, state, "pair_judge", 0)
+            except ValueError:
+                pass
+            else:
+                raise AssertionError("invalid native header accepted")
+    print("PASS judge-role-evidence self-test: success/error/timeout, raw derivation, tampering and native header identity")
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--self-test", action="store_true")
+    parser.add_argument("--devlyn-dir", type=Path, default=Path(".devlyn"))
+    parser.add_argument("--role", choices=("primary_judge", "pair_judge"))
+    parser.add_argument("--exit-code", type=int)
+    args = parser.parse_args()
+    if args.self_test:
+        return self_test()
+    if args.role is None or args.exit_code is None:
+        parser.error("--role and --exit-code are required")
+    try:
+        devlyn = args.devlyn_dir.resolve()
+        state = loads((devlyn / "pipeline.state.json").read_bytes())
+        record, derived = describe(devlyn, state, args.role, args.exit_code)
+        stem = record["engine"] + "-judge.r" + str(record["round"])
+        target = devlyn / (stem + ".role-evidence.json")
+        require(not target.exists(), "role evidence already exists for this round")
+        stdout = devlyn / (record["engine"] + "-judge.stdout")
+        require(not stdout.exists(), "canonical stdout already exists")
+        if record["engine"] == "claude":
+            require(not (devlyn / (stem + ".stdout")).exists(), "derived stdout already exists")
+            (devlyn / (stem + ".stdout")).write_bytes(derived)
+        stdout.write_bytes(derived)
+        target.write_bytes(encoded(record))
+        print(json.dumps(authenticate(devlyn, state, args.role), sort_keys=True))
+        return 0
+    except (OSError, ValueError, TypeError, KeyError) as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/config/skills/_shared/phase-prompt-render.py

@@ -0,0 +1,181 @@
+#!/usr/bin/env python3
+"""Render exact phase-prompt bytes and print their SHA-256 digest."""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import os
+import pathlib
+import re
+import tempfile
+
+
+EXCLUDED_ADAPTER_SECTION = re.compile(
+    rb"^## (?:Role eligibility|Invocation)(?:\r?\n|\Z).*?(?=^## |\Z)",
+    re.MULTILINE | re.DOTALL,
+)
+EXCLUDED_ADAPTER_HEADING = re.compile(
+    rb"^## (?:Role eligibility|Invocation)\r?$", re.MULTILINE
+)
+
+
+def project_adapter(content: bytes) -> bytes:
+    projected = EXCLUDED_ADAPTER_SECTION.sub(b"", content)
+    assert EXCLUDED_ADAPTER_HEADING.search(projected) is None
+    return projected
+
+
+def validate_plan_context(task_context: pathlib.Path, content: bytes) -> None:
+    if task_context.name != "plan.task-context":
+        return
+    working_directory = pathlib.Path.cwd()
+    expected = (
+        b"Working directory: "
+        + os.fsencode(working_directory)
+        + b"\nPlan output: "
+        + os.fsencode(working_directory / ".devlyn" / "plan.md")
+        + b"\n"
+    )
+    if not content.startswith(expected):
+        raise SystemExit("error: invalid PLAN task-context header")
+
+
+def render_prompt(
+    adapter: pathlib.Path,
+    canonical_body: pathlib.Path,
+    task_context: pathlib.Path,
+    output: pathlib.Path,
+) -> str:
+    try:
+        adapter_bytes = adapter.read_bytes()
+        body_bytes = canonical_body.read_bytes()
+        context_bytes = task_context.read_bytes()
+    except OSError as exc:
+        raise SystemExit(f"error: prompt input unreadable: {exc}") from exc
+    projected_adapter = project_adapter(adapter_bytes)
+    validate_plan_context(task_context, context_bytes)
+    rendered = projected_adapter + body_bytes + context_bytes
+    rendered = rendered.rstrip(b"\n")
+    if not output.parent.is_dir():
+        raise SystemExit(f"error: prompt output parent is not a directory: {output.parent}")
+    fd, temporary = tempfile.mkstemp(dir=output.parent, prefix=output.name + ".tmp.")
+    temporary_path = pathlib.Path(temporary)
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(rendered)
+            handle.flush()
+            os.fsync(handle.fileno())
+        temporary_path.replace(output)
+    except BaseException:
+        temporary_path.unlink(missing_ok=True)
+        raise
+    return hashlib.sha256(rendered).hexdigest()
+
+
+def self_test() -> int:
+    with tempfile.TemporaryDirectory(prefix="phase-prompt-render-") as raw:
+        root = pathlib.Path(raw)
+        adapter = root / "adapter.md"
+        body = root / "plan.md"
+        context = root / "plan.task-context"
+        output = root / ".devlyn" / "plan.prompt"
+        output.parent.mkdir()
+        original_directory = pathlib.Path.cwd()
+        os.chdir(root)
+        try:
+            working_directory = pathlib.Path.cwd()
+            adapter_bytes = (
+                b"# Claude adapter\r\n"
+                b"## Identity\r\nkept-identity-\xff\r\n"
+                b"## Role eligibility\nremove-role\r\n"
+                b"## Output discipline\r\nkept-output-\x80\n"
+                b"## Invocation\r\nremove-invocation\n"
+                b"## Anti-patterns\nkept-tail-without-newline"
+            )
+            projected_adapter = (
+                b"# Claude adapter\r\n"
+                b"## Identity\r\nkept-identity-\xff\r\n"
+                b"## Output discipline\r\nkept-output-\x80\n"
+                b"## Anti-patterns\nkept-tail-without-newline"
+            )
+            for metadata_free in (
+                b"# Codex adapter\r\n## Identity\nkept-\xfe",
+                b"# omp adapter\n## Output discipline\r\nkept\x81",
+            ):
+                assert project_adapter(metadata_free) == metadata_free
+
+            body_bytes = b"# PHASE 1 \xe2\x80\x94 PLAN\n"
+            context_bytes = (
+                b"Working directory: "
+                + os.fsencode(working_directory)
+                + b"\nPlan output: "
+                + os.fsencode(working_directory / ".devlyn" / "plan.md")
+                + b"\ncontext-without-newline"
+            )
+            for path, content in (
+                (adapter, adapter_bytes),
+                (body, body_bytes),
+                (context, context_bytes),
+            ):
+                path.write_bytes(content)
+            expected = projected_adapter + body_bytes + context_bytes
+            digest = render_prompt(adapter, body, context, output)
+            assert output.read_bytes() == expected
+            assert digest == hashlib.sha256(expected).hexdigest()
+            assert render_prompt(adapter, body, context, output) == digest
+            assert output.read_bytes() == expected
+
+            context_prefix = context_bytes.removesuffix(b"context-without-newline")
+            for terminal_lfs in (b"", b"\n", b"\n\n"):
+                case_context = context_prefix + b"context-terminal-lf-case" + terminal_lfs
+                context.write_bytes(case_context)
+                expected = (projected_adapter + body_bytes + case_context).rstrip(b"\n")
+                digest = render_prompt(adapter, body, context, output)
+                written = output.read_bytes()
+                assert not written.endswith(b"\n")
+                assert digest == hashlib.sha256(written).hexdigest()
+                assert written == expected
+
+            invalid_contexts = (
+                b"context-without-header",
+                b"Working directory: relative\nPlan output: relative/.devlyn/plan.md\n",
+                b"Working directory: /mismatch\nPlan output: /mismatch/.devlyn/plan.md\n",
+            )
+            for invalid_context in invalid_contexts:
+                context.write_bytes(invalid_context)
+                output.write_bytes(b"unchanged")
+                try:
+                    render_prompt(adapter, body, context, output)
+                except SystemExit:
+                    pass
+                else:
+                    raise AssertionError("invalid PLAN task-context header accepted")
+                assert output.read_bytes() == b"unchanged"
+        finally:
+            os.chdir(original_directory)
+    print("SELFTEST PASS: projected exact bytes + PLAN context validation")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--adapter", type=pathlib.Path)
+    parser.add_argument("--canonical-body", type=pathlib.Path)
+    parser.add_argument("--task-context", type=pathlib.Path)
+    parser.add_argument("--output", type=pathlib.Path)
+    parser.add_argument("--self-test", action="store_true")
+    args = parser.parse_args()
+    if args.self_test:
+        if any((args.adapter, args.canonical_body, args.task_context, args.output)):
+            parser.error("render paths are not allowed with --self-test")
+        return self_test()
+    if not all((args.adapter, args.canonical_body, args.task_context, args.output)):
+        parser.error(
+            "--adapter, --canonical-body, --task-context, and --output are required"
+        )
+    print(render_prompt(args.adapter, args.canonical_body, args.task_context, args.output))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())