devlyn-cli 2.2.2 → 2.3.1

package/config/skills/_shared/archive_run.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Archive auto-resolve run artifacts per references/pipeline-state.md#archive-contract.
+"""Archive devlyn:resolve run artifacts per references/pipeline-state.md#archive-contract.
 
 Usage:
     python3 scripts/archive_run.py [--devlyn-dir .devlyn]
@@ -16,8 +16,10 @@ from __future__ import annotations
 import argparse
 import json
 import pathlib
+import re
 import shutil
 import sys
+import tempfile
 
 
 PER_RUN_PATTERNS = (
@@ -57,18 +59,30 @@ PER_RUN_PATTERNS = (
     "codex-judge.*",
 )
 
+SAFE_RUN_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+
+def reject_json_constant(token: str) -> None:
+    raise ValueError(f"invalid JSON numeric constant: {token}")
+
+
+def loads_strict_json(text: str):
+    return json.loads(text, parse_constant=reject_json_constant)
+
 
 def read_run_id(devlyn: pathlib.Path) -> str:
     state_path = devlyn / "pipeline.state.json"
     if not state_path.is_file():
         raise SystemExit(f"error: {state_path} not found")
     try:
-        state = json.loads(state_path.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as e:
+        state = loads_strict_json(state_path.read_text(encoding="utf-8"))
+    except ValueError as e:
         raise SystemExit(f"error: {state_path} is not valid JSON: {e}")
     run_id = state.get("run_id")
-    if not run_id:
+    if not isinstance(run_id, str) or not run_id:
         raise SystemExit(f"error: {state_path} has no run_id")
+    if not SAFE_RUN_ID_RE.fullmatch(run_id):
+        raise SystemExit(f"error: {state_path} run_id must match [A-Za-z0-9_.-]+")
     return run_id
 
 
@@ -91,8 +105,8 @@ def prune(runs_dir: pathlib.Path, keep: int = 10) -> int:
         if not state_file.is_file():
             continue
         try:
-            s = json.loads(state_file.read_text(encoding="utf-8"))
-        except json.JSONDecodeError:
+            s = loads_strict_json(state_file.read_text(encoding="utf-8"))
+        except ValueError:
             # Can't decide flight-state safely; skip (never prune)
             continue
         verdict = s.get("phases", {}).get("final_report", {}).get("verdict")
@@ -109,11 +123,69 @@ def prune(runs_dir: pathlib.Path, keep: int = 10) -> int:
     return pruned
 
 
+def self_test() -> int:
+    with tempfile.TemporaryDirectory() as tmp:
+        devlyn = pathlib.Path(tmp) / ".devlyn"
+        devlyn.mkdir()
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "run_id": "run-1",
+                "phases": {"final_report": {"verdict": "PASS"}},
+            }) + "\n",
+            encoding="utf-8",
+        )
+        for name in (
+            "risk-probes.jsonl",
+            "verify.pair.findings.jsonl",
+            "verify-merge.summary.json",
+            "codex-judge.stdout",
+            "codex-judge.summary.json",
+        ):
+            (devlyn / name).write_text("{}\n", encoding="utf-8")
+        run_id = read_run_id(devlyn)
+        assert run_id == "run-1", run_id
+        moved = move_artifacts(devlyn, devlyn / "runs" / run_id)
+        assert moved >= 6, moved
+        for name in (
+            "pipeline.state.json",
+            "risk-probes.jsonl",
+            "verify.pair.findings.jsonl",
+            "verify-merge.summary.json",
+            "codex-judge.stdout",
+            "codex-judge.summary.json",
+        ):
+            assert (devlyn / "runs" / run_id / name).is_file(), name
+
+        bad = pathlib.Path(tmp) / "bad"
+        bad.mkdir()
+        (bad / "pipeline.state.json").write_text('{"run_id": "../escape"}\n', encoding="utf-8")
+        try:
+            read_run_id(bad)
+        except SystemExit as exc:
+            assert "run_id must match" in str(exc)
+        else:
+            raise AssertionError("unsafe archive run_id was accepted")
+
+        nan = pathlib.Path(tmp) / "nan"
+        nan.mkdir()
+        (nan / "pipeline.state.json").write_text('{"run_id": NaN}\n', encoding="utf-8")
+        try:
+            read_run_id(nan)
+        except SystemExit as exc:
+            assert "invalid JSON numeric constant: NaN" in str(exc)
+        else:
+            raise AssertionError("NaN archive run_id was accepted")
+    return 0
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
     ap.add_argument("--devlyn-dir", default=".devlyn")
     ap.add_argument("--keep", type=int, default=10, help="keep N most recent completed runs")
+    ap.add_argument("--self-test", action="store_true")
     args = ap.parse_args()
+    if args.self_test:
+        return self_test()
 
     devlyn = pathlib.Path(args.devlyn_dir)
     if not devlyn.is_dir():

package/config/skills/_shared/codex-config.md

@@ -6,10 +6,10 @@ Single source of truth for how every skill calls Codex. **MCP is not used.** Ski
 
 All long-running Codex calls go through `codex-monitored.sh` — a thin wrapper that closes stdin (codex 0.124.0 hangs when both stdin is open and a prompt arg is given), streams Codex stdout fully (no `tail -n` truncation), and prints a `[codex-monitored] heartbeat` line every 30s so the outer `claude -p` byte-watchdog stays fed during long reasoning gaps. The wrapper passes its arguments through verbatim to the underlying CLI, so the canonical flag set is unchanged from a raw call — only the launcher differs.
 
-**Read-only critique / adversarial review / debate** (ideate CHALLENGE phase, `/devlyn:resolve` VERIFY pair-mode when triggered). Security review is delegated to the native `security-review` Claude Code skill, invoked from `/devlyn:resolve` BUILD_GATE rather than from Codex. Read-only critique returns findings on stdout; the orchestrator writes any files.
+**Read-only critique / adversarial review / debate** (`/devlyn:resolve` VERIFY pair-mode, plus any future ideate read-only critique). Security review stays native to Claude Code BUILD_GATE. Codex returns findings on stdout; the orchestrator writes files.
 
 ```bash
-bash .claude/skills/_shared/codex-monitored.sh \
+CODEX_MONITORED_ISOLATED=1 bash .claude/skills/_shared/codex-monitored.sh \
   -C <project-root> \
   -s read-only \
   -c model_reasoning_effort=xhigh \
@@ -31,6 +31,7 @@ Notes:
 - `-s read-only` / `--full-auto` — sandbox policy. `--full-auto` = `-s workspace-write` with auto-approval of sandboxed commands.
 - `-c model_reasoning_effort=xhigh` — config override for reasoning depth. Required for deep critique; skills may choose `high` or `medium` when thoroughness doesn't warrant xhigh.
 - **Omit `-m <model>`** — Codex CLI uses its configured flagship (currently `gpt-5.5`, automatically whatever ships next). This is the zero-touch mechanism. Only name `-m` when a role explicitly needs a different model (e.g., `gpt-5.3-codex` for SWE-bench-heavy coding tasks, `gpt-5.3-codex-spark` for speed).
+- `CODEX_MONITORED_ISOLATED=1` — required for bounded read-only critique/probe/judge calls. The wrapper adds `--ignore-user-config --ignore-rules --ephemeral --disable codex_hooks --disable hooks` so user config, AGENTS.md, pyx-memory, hooks, and project rules cannot add hidden context, tool calls, or transcript side effects. Do not set it for workspace-write implementation phases.
 - Raw `codex exec ...` invocations are **forbidden** in skill prompts. The benchmark variant arm runs a PATH shim (`scripts/codex-shim/codex`) that transparently re-routes any raw `codex exec` to the wrapper as a safety net, but skills should always emit the wrapper form directly so the orchestrator's first-attempt has the right shape. Two prior iterations (iter-0006 universal foreground ban, iter-0008 prompt-level kill-shape contract) failed because the orchestrator picked starvation-prone shapes (`codex exec ... 2>&1 | tail -200`) from its own pattern prior — the wrapper plus the shim is the runtime binding layer those iters lacked. See `autoresearch/iterations/0009-wrapper-and-hook.md`.
 
 ## Availability check
@@ -41,11 +42,11 @@ Before the first Codex call in a run, verify the CLI is on PATH:
 command -v codex >/dev/null 2>&1
 ```
 
-If the check fails, the skill follows the `_shared/engine-preflight.md` downgrade rule — silently switch to Claude for this run and log `engine downgraded: codex-unavailable` in the final report. Never prompt, never abort.
+If the check fails while Codex is explicitly selected or conditionally required by pair/risk-probe VERIFY, follow `_shared/engine-preflight.md`: stop with `BLOCKED:codex-unavailable`, preserve run evidence, and print setup guidance. Do not convert the run to Claude. `--no-pair` and `--no-risk-probes` are explicit user opt-outs for reruns, not automatic fallbacks.
 
 ## Why CLI over other paths
 
-The local Codex CLI (fronted by `codex-monitored.sh`) is the primary (and only) integration. It beats alternatives on three dimensions: the model is inherited from the CLI's own default so no skill edits are needed when OpenAI ships a new flagship; flags compose on the command line and the skill docs stay grep-friendly; the invocation has one failure mode (the binary is on PATH or it isn't), which the shared availability check covers cleanly.
+The local Codex CLI (fronted by `codex-monitored.sh`) is the primary (and only) integration. It beats alternatives on three dimensions: the model is inherited from the CLI's own default so no skill edits are needed when OpenAI ships a new flagship; flags compose on the command line and the skill docs stay grep-friendly; the invocation has one failure mode (the binary is on PATH or it isn't), which the shared availability check reports explicitly.
 
 ## Invocation from inside a skill prompt
 

package/config/skills/_shared/codex-monitored.sh

@@ -47,6 +47,10 @@
 #                                     CODEX_REAL_BIN when set, else `codex`.
 #                                     Set this when the shim has put us first
 #                                     on PATH.
+#   CODEX_MONITORED_ISOLATED       — set non-empty for bounded read-only
+#                                     probe/judge calls that must ignore
+#                                     user config, project rules, session
+#                                     persistence, and hook side effects.
 #   CODEX_MONITORED_ALLOW_PIPED    — set non-empty to skip the pipe-stdout
 #                                     refusal. Reserved for tests; don't use
 #                                     in skill prompts.
@@ -70,6 +74,44 @@ TIMEOUT_SEC="${CODEX_MONITORED_TIMEOUT_SEC:-0}"
 CODEX_BIN="${CODEX_BIN:-${CODEX_REAL_BIN:-codex}}"
 START=$(date +%s)
 TIMEOUT_FLAG=""
+CODEX_ARGS=("$@")
+
+require_nonnegative_int() {
+  local name="$1"
+  local value="$2"
+  case "$value" in
+    ''|*[!0-9]*)
+      printf '[codex-monitored] error: %s must be a non-negative integer (got %s)\n' \
+        "$name" "$value" >&2
+      exit 64
+      ;;
+  esac
+}
+
+require_positive_int() {
+  local name="$1"
+  local value="$2"
+  require_nonnegative_int "$name" "$value"
+  if [ "$value" -le 0 ]; then
+    printf '[codex-monitored] error: %s must be > 0 (got %s)\n' \
+      "$name" "$value" >&2
+    exit 64
+  fi
+}
+
+require_positive_int CODEX_MONITORED_HEARTBEAT "$HEARTBEAT_SEC"
+require_nonnegative_int CODEX_MONITORED_TIMEOUT_SEC "$TIMEOUT_SEC"
+
+if [ -n "${CODEX_MONITORED_ISOLATED:-}" ]; then
+  CODEX_ARGS=(
+    --ignore-user-config
+    --ignore-rules
+    --ephemeral
+    --disable codex_hooks
+    --disable hooks
+    "${CODEX_ARGS[@]}"
+  )
+fi
 
 # --- Pipe-stdout refusal (iter-0009 R2 finding #1) -------------------------
 # `[ -p /dev/stdout ]` is the POSIX test for "is fd 1 a FIFO/pipe". Verified
@@ -169,10 +211,13 @@ trap cleanup EXIT
 
 printf '[codex-monitored] start: ts=%s heartbeat=%ds timeout=%ss bin=%s\n' \
   "$(date -u +%FT%TZ)" "$HEARTBEAT_SEC" "$TIMEOUT_SEC" "$CODEX_BIN" >&2
+if [ -n "${CODEX_MONITORED_ISOLATED:-}" ]; then
+  printf '[codex-monitored] isolated=1\n' >&2
+fi
 
 # Launch codex with stdin closed; output streams directly to OUR stdout/stderr.
 set -m
-"$CODEX_BIN" exec "$@" < /dev/null &
+"$CODEX_BIN" exec "${CODEX_ARGS[@]}" < /dev/null &
 CODEX_PID=$!
 set +m
 printf '[codex-monitored] codex pid=%d\n' "$CODEX_PID" >&2

package/config/skills/_shared/collect-codex-findings.py

@@ -14,6 +14,14 @@ from typing import Any
 FINDING_SEVERITIES = {"CRITICAL", "HIGH", "MEDIUM", "LOW", "INFO"}
 
 
+def reject_json_constant(token: str) -> None:
+    raise ValueError(f"invalid JSON numeric constant: {token}")
+
+
+def loads_strict_json(text: str) -> Any:
+    return json.loads(text, parse_constant=reject_json_constant)
+
+
 def atomic_write(path: pathlib.Path, text: str) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     with tempfile.NamedTemporaryFile(
@@ -34,8 +42,8 @@ def collect(stdout_path: pathlib.Path) -> tuple[list[dict[str, Any]], dict[str,
                 continue
             if raw.startswith("# SUMMARY "):
                 try:
-                    item = json.loads(raw.removeprefix("# SUMMARY ").strip())
-                except json.JSONDecodeError as exc:
+                    item = loads_strict_json(raw.removeprefix("# SUMMARY ").strip())
+                except ValueError as exc:
                     raise SystemExit(f"error: invalid SUMMARY JSON at {stdout_path}:{line_no}: {exc}")
                 if not isinstance(item, dict):
                     raise SystemExit(f"error: SUMMARY is not an object at {stdout_path}:{line_no}")
@@ -44,8 +52,8 @@ def collect(stdout_path: pathlib.Path) -> tuple[list[dict[str, Any]], dict[str,
             if raw.startswith("#"):
                 continue
             try:
-                item = json.loads(raw)
-            except json.JSONDecodeError as exc:
+                item = loads_strict_json(raw)
+            except ValueError as exc:
                 raise SystemExit(f"error: invalid JSONL at {stdout_path}:{line_no}: {exc}")
             if not isinstance(item, dict):
                 raise SystemExit(f"error: JSONL item is not an object at {stdout_path}:{line_no}")
@@ -74,7 +82,14 @@ def self_test() -> int:
         findings, summary = collect(stdout_path)
         write_outputs(findings, summary, out_path, summary_path)
         assert out_path.read_text(encoding="utf-8").count("\n") == 1
-        assert json.loads(summary_path.read_text(encoding="utf-8"))["verdict"] == "NEEDS_WORK"
+        assert loads_strict_json(summary_path.read_text(encoding="utf-8"))["verdict"] == "NEEDS_WORK"
+        stdout_path.write_text('{"id":"nan","severity":NaN}\n', encoding="utf-8")
+        try:
+            collect(stdout_path)
+        except SystemExit as exc:
+            assert "invalid JSON numeric constant: NaN" in str(exc)
+        else:
+            raise AssertionError("NaN Codex stdout finding must not normalize")
         stdout_path.write_text("", encoding="utf-8")
         try:
             collect(stdout_path)

package/config/skills/_shared/engine-preflight.md

@@ -1,34 +1,38 @@
-# Shared — `--engine` Pre-flight
+# Shared — Engine Pre-flight
 
 Used by `/devlyn:resolve` and `/devlyn:ideate`. One shared availability rule so every skill routes identically.
 
 ## Rule
 
-Each skill resolves the effective engine from its own SKILL.md default plus any explicit `--engine` flag passed by the user. This pre-flight runs **only when the resolved engine is `auto` or `codex`** — when the resolved engine is `claude` (whether by skill default or explicit flag), the Codex check is skipped entirely.
+Each skill resolves the effective engine from its own SKILL.md default plus any explicit `--engine` flag passed by the user. `/devlyn:resolve` also computes conditional pair/risk-probe requirements before the phase that needs the OTHER engine.
 
-When the resolved engine is `auto` or `codex`, on entry (before spawning any phase that could route to Codex):
+When a run or phase requires Codex, before spawning that phase:
 
 1. Check if the Codex CLI is installed: `command -v codex >/dev/null 2>&1` (or equivalent bash test).
-2. On failure → silently set `engine = "claude"` for the remainder of this run AND log `engine downgraded: codex-unavailable` into the skill's final summary/report header.
-3. On success → proceed with the original engine value.
+2. On failure -> set the current phase/run verdict to `BLOCKED:codex-unavailable`, preserve the failed check evidence, and show setup guidance: install/configure the Codex CLI, run the current Codex auth/login flow, verify `codex --version`, then rerun. If the user intentionally wants solo VERIFY, they may rerun with `--no-pair`.
+3. On success -> proceed with the original engine value.
 
-Never prompt the user. Never abort the run on missing CLI.
+When a run or phase requires Claude, before spawning that phase:
 
-Per-skill defaults: `/devlyn:resolve` defaults to `claude` for PLAN/IMPLEMENT (post iter-0020 close-out — Codex BUILD/IMPLEMENT below quality floor; iter-0033g + iter-0034 close-out — PLAN-pair research-only until container/sandbox infra justifies a measurement). `/devlyn:resolve` VERIFY is the exception: gated pair-JUDGE may invoke the OTHER engine when its SKILL.md trigger policy fires. `/devlyn:ideate` defaults to `auto` for the CHALLENGE phase's cross-model GAN-critic dynamic. Each skill's SKILL.md flag block is the source of truth for that skill's default.
+1. Confirm the runtime can spawn Claude agents. Where the CLI is the launcher, `command -v claude >/dev/null 2>&1` is the equivalent check.
+2. On failure -> set the current phase/run verdict to `BLOCKED:claude-unavailable` and show setup guidance: install/configure Claude Code, verify `claude --version` where available, then rerun.
+3. On success -> proceed.
 
-## Why this is the one permitted silent fallback
+Never prompt the user mid-pipeline. Missing required engines are explicit BLOCKED states, not silent fallbacks.
 
-`CLAUDE.md` sets the no-silent-fallback rule for this repo. This downgrade is documented there as the single explicit exception because the hands-free contract — skills the user walks away from — would otherwise fail every run whenever the Codex CLI is absent. The user-visible behavior is identical to an explicit `--engine claude` invocation, and the banner in the final report removes the silence. Any other silent fallback in skills code is a bug.
+Per-skill defaults: `/devlyn:resolve` uses Claude for PLAN/IMPLEMENT; VERIFY may invoke the OTHER engine when its pair-JUDGE trigger fires. `/devlyn:ideate` defaults to Claude; `--engine` selects the elicitation/normalization adapter, not an automatic cross-model challenge phase. Any future ideate read-only critique must follow `_shared/codex-config.md` isolation rules. Each SKILL.md flag block is source of truth for that skill's default.
 
-## What a skill must log after downgrade
+## What a skill must report after a BLOCKED engine check
 
-When the resolved engine was `auto` / `codex` and the Codex CLI was absent, the final user-facing report/summary shows both the requested and effective mode:
+When an engine required by the selected route or conditional pair trigger is absent, the final user-facing report/summary shows the requested route, the missing engine, and setup steps:
 
 ```
-Engine: claude (downgraded from auto — codex-unavailable)
+Engine: claude + codex pair required
+Verdict: BLOCKED:codex-unavailable
+Setup: install/configure Codex CLI; run the current Codex auth/login flow; verify `codex --version`; rerun. Use `--no-pair` only for an intentional solo VERIFY run.
 ```
 
-If no downgrade happened (either Codex was available, or the resolved engine was already `claude`), omit the parenthetical. That single line is the contract — the user can always see why Codex did or did not participate.
+Do not report a downgraded successful run when a required engine is missing.
 
 ## Canonical Codex invocation
 

package/config/skills/_shared/runtime-principles.md

@@ -1,6 +1,6 @@
 # Runtime principles — sub-agent contract
 
-The runtime contract every sub-agent inside `/devlyn:resolve` (PLAN / IMPLEMENT / BUILD_GATE / CLEANUP / VERIFY) and `/devlyn:ideate` (FRAME / EXPLORE / SPEC / CHALLENGE) must satisfy. Source of truth for sub-agent behavior on user tasks. NOT for autoresearch-loop / harness-developer concerns (see `autoresearch/PRINCIPLES.md`).
+The runtime contract every sub-agent inside `/devlyn:resolve` (PLAN / IMPLEMENT / BUILD_GATE / CLEANUP / VERIFY) and `/devlyn:ideate` must satisfy. Source of truth for sub-agent behavior on user tasks. NOT for autoresearch-loop / harness-developer concerns (see `autoresearch/PRINCIPLES.md`).
 
 The four sections below mirror the corresponding CLAUDE.md sections (Subtractive-first editing, Goal-locked execution, No-workaround discipline, Evidence over claim). Each section is wrapped in `<!-- runtime-principles:section=NAME:begin -->` / `:end -->` markers in BOTH this file and CLAUDE.md; lint Check 12 (added in iter-0019.A Step 5) extracts each named block from both files and diffs to detect drift.
 
@@ -79,7 +79,7 @@ No `any`, no `@ts-ignore`, no silent `catch`, no hardcoded values, no helper scr
 
 **Permitted exceptions** (explicitly carved out):
 - CSS fallback fonts, CDN failover, image placeholders — widely-accepted best practices.
-- Codex CLI availability downgrade — the one documented silent fallback in this repo. Fires when the resolved engine is `auto` or `codex` (either via skill default or explicit `--engine` flag) and the Codex CLI is absent. Banner `engine downgraded: codex-unavailable` always prints; verdict identical to `--engine claude`. Any other silent fallback in skills code is a bug — file it against the skill that introduced it.
+- No engine-availability fallback is permitted for `/devlyn:resolve` pair/risk-probe routes. If Codex or Claude is required and unavailable, the run stops with `BLOCKED:codex-unavailable` or `BLOCKED:claude-unavailable` plus setup guidance. `--no-pair` / `--no-risk-probes` are explicit user opt-outs, not fallbacks.
 <!-- runtime-principles:section=no-workaround:end -->
 
 ## Evidence over claim
@@ -97,14 +97,11 @@ A finding without one of these forms is excluded. Vague findings produce vague f
 <!-- runtime-principles:contract:end -->
 
 <!-- runtime-principles:consumption:begin -->
-## Consumption (as of iter-0019.A)
+## Consumption
 
 **Consumers**:
-- `auto-resolve/SKILL.md` `<harness_principles>` block points here as the contract source. Phase prompt bodies (`phase-1-build.md`, `phase-2-evaluate.md`, `phase-3-critic.md`) inline a compact operational excerpt derived from the contract — phase-specific rule_id mappings + the four section names — not the full text.
-- `preflight/SKILL.md` PHASE 3 (Synthesize) and PHASE 3.5 (RND2) reference this file. Auditor prompts (`code-auditor.md`, `browser-auditor.md`) emit `principle.*` rule_ids derived from the rules above.
+- `devlyn:resolve/SKILL.md` `<harness_principles>` points here as the contract source. Phase prompt bodies inline or reference the operational excerpt needed for each phase.
+- `devlyn:ideate/SKILL.md` consumes this file for spec-shaping and conversation discipline through its own `<harness_principles>` block.
 
-**Codex routing**: skills that route to Codex (auto-resolve fix-loop on `--engine auto`/`codex`, preflight code-auditor on `--engine auto`/`codex`) MUST inline the contract excerpt directly into the Codex prompt — Codex has no filesystem access under `read-only` sandbox.
-
-**Non-consumers**:
-- `ideate/SKILL.md` does NOT consume this file. Ideate is planning-layer; its CHALLENGE rubric (`references/challenge-rubric.md`) covers analogous concerns at planning scope, with deliberate one-shot Codex critic discipline.
+**Codex routing**: Codex-routed phases must inline the contract excerpt directly into the prompt body. Bounded read-only Codex critique, probe, or judge calls must also follow `_shared/codex-config.md` isolation rules.
 <!-- runtime-principles:consumption:end -->