devlyn-cli 2.7.0 → 2.8.1

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

@@ -1,15 +1,31 @@
 # Shared — Codex Invocation
 
-Single source of truth for how every skill calls Codex. **MCP is not used.** Skills shell out via the wrapper at `_shared/codex-monitored.sh`, which fronts the local Codex CLI (shipped by the `openai-codex` Claude Code plugin).
+Single source of truth for how every skill calls Codex. **MCP is not used.** Skills shell out via the wrapper at `$CODEX_MONITORED_PATH`, resolved from the invoked skill's sibling `_shared/codex-monitored.sh`, which fronts the local Codex CLI.
 
 ## Canonical invocations
 
 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.
 
+Before the first Codex call, resolve the wrapper from the invoked skill directory:
+
+```bash
+DEVLYN_SKILL_DIR="${CLAUDE_SKILL_DIR:-__DEVLYN_SKILL_DIR__}"
+if [ "$DEVLYN_SKILL_DIR" = "__DEVLYN_SKILL_DIR__" ] || [ ! -d "$DEVLYN_SKILL_DIR/../_shared" ]; then
+  echo "BLOCKED:shared-dir-unresolved: $DEVLYN_SKILL_DIR/../_shared" >&2
+  exit 1
+fi
+DEVLYN_SHARED_DIR="$(cd "$DEVLYN_SKILL_DIR/../_shared" && pwd)"
+CODEX_MONITORED_PATH="$DEVLYN_SHARED_DIR/codex-monitored.sh"
+if [ ! -f "$CODEX_MONITORED_PATH" ]; then
+  echo "BLOCKED:shared-dir-unresolved: $CODEX_MONITORED_PATH" >&2
+  exit 1
+fi
+```
+
 **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
-CODEX_MONITORED_ISOLATED=1 bash .claude/skills/_shared/codex-monitored.sh \
+CODEX_MONITORED_ISOLATED=1 bash "$CODEX_MONITORED_PATH" \
   -C <project-root> \
   -s read-only \
   -c model_reasoning_effort=xhigh \
@@ -19,16 +35,16 @@ CODEX_MONITORED_ISOLATED=1 bash .claude/skills/_shared/codex-monitored.sh \
 **Workspace-write implementation** (`/devlyn:resolve` IMPLEMENT phase when `--engine codex` or `--engine auto` routes to Codex, plus codex-routed `/devlyn:ideate` phases):
 
 ```bash
-bash .claude/skills/_shared/codex-monitored.sh \
+bash "$CODEX_MONITORED_PATH" \
   -C <project-root> \
-  --full-auto \
+  -s workspace-write \
   -c model_reasoning_effort=xhigh \
   "<inlined-prompt>"
 ```
 
 Notes:
 - `-C` — project root so Codex's working directory matches.
-- `-s read-only` / `--full-auto` — sandbox policy. `--full-auto` = `-s workspace-write` with auto-approval of sandboxed commands.
+- `-s read-only` / `-s workspace-write` — sandbox policy. Use workspace-write for implementation/probe phases that write tracked files or `.devlyn` artifacts.
 - `-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, hooks, and project rules cannot add hidden context, tool calls, or transcript side effects. Do not set it for workspace-write implementation phases.
@@ -52,4 +68,4 @@ The local Codex CLI (fronted by `codex-monitored.sh`) is the primary (and only)
 
 Skills write the invocation as a Bash command the runtime executes. Example shape from `/devlyn:resolve` PHASE 2 IMPLEMENT when routed to Codex:
 
-> Run `bash .claude/skills/_shared/codex-monitored.sh -C <state.base_ref.repo_root> --full-auto -c model_reasoning_effort=xhigh "<IMPLEMENT prompt>"`. Omit `-m` so the CLI flagship is auto-selected. Capture stdout as the IMPLEMENT reply; non-zero exit → treat as subagent failure. The wrapper emits `[codex-monitored]` heartbeat and lifecycle lines on **stderr** — stdout stays clean for Codex output, so the orchestrator can parse the reply without filtering. Heartbeat-on-stderr keeps the orchestrator's combined-output stream non-silent (defeats the iter-0008 byte-watchdog kill) without polluting the codex-reply view of stdout. Do not pipe the wrapper; direct capture or file redirection preserves streaming and avoids the pipe-refusal exit.
+> Run `bash "$CODEX_MONITORED_PATH" -C <state.base_ref.repo_root> -s workspace-write -c model_reasoning_effort=xhigh "<IMPLEMENT prompt>"`. Omit `-m` so the CLI flagship is auto-selected. Capture stdout as the IMPLEMENT reply; non-zero exit → treat as subagent failure. The wrapper emits `[codex-monitored]` heartbeat and lifecycle lines on **stderr** — stdout stays clean for Codex output, so the orchestrator can parse the reply without filtering. Heartbeat-on-stderr keeps the orchestrator's combined-output stream non-silent (defeats the iter-0008 byte-watchdog kill) without polluting the codex-reply view of stdout. Do not pipe the wrapper; direct capture or file redirection preserves streaming and avoids the pipe-refusal exit.

package/config/skills/_shared/engine-doctor.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# engine-doctor.sh — read-only detection for /devlyn:engines' no-arg output.
+#
+# WHY (iter-0050): users need to see what's actually on the machine, not
+# just what's pinned. This script never writes .devlyn/engines.json, never
+# installs anything, never changes pin validation — it only reports.
+#
+# CATALOG NOTE: `pi` (bin/devlyn.js's Pi/earendil-works install target) has
+# no verified CLI binary name anywhere in this repo — its own installer
+# detect() only checks project marker files, never shells out to a binary.
+# Fabricating a `command -v pi` check would be a guess this repo's evidence
+# rule forbids, so its binary column reports "unknown" rather than "no".
+#
+# macOS-safe bash 3.2: no associative arrays, no mapfile/readarray.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+ADAPTERS_DIR="$SCRIPT_DIR/adapters"
+
+TARGETS=(claude codex omp pi)
+KINDS=(cli-engine cli-engine cli-engine orchestrator-only)
+BINARIES=(claude codex omp "")
+INSTALL_HINTS=(
+  "see https://docs.anthropic.com/en/docs/claude-code"
+  "npm install -g @openai/codex"
+  "brew install can1357/tap/omp"
+  ""
+)
+
+check_binary() {
+  # $1 = binary name, "" means no known binary to probe
+  [ -n "$1" ] || { printf 'unknown'; return; }
+  if command -v "$1" >/dev/null 2>&1; then printf 'yes'; else printf 'no'; fi
+}
+
+check_adapter() {
+  # $1 = target name
+  if [ -f "$ADAPTERS_DIR/$1.md" ]; then printf 'yes'; else printf 'no'; fi
+}
+
+check_role() {
+  # $1 = adapter file path. Reads the optional `## Role eligibility` fixed
+  # ASCII fields (_shared/adapters/README.md); absent file or section = both
+  # roles eligible by default (every adapter shipped before iter-0051).
+  [ -f "$1" ] || { printf 'n/a'; return; }
+  local exec_ok='yes' judge_ok='yes'
+  grep -q '^executor: no' "$1" 2>/dev/null && exec_ok='no'
+  grep -q '^pair_judge: no' "$1" 2>/dev/null && judge_ok='no'
+  if [ "$exec_ok" = 'yes' ] && [ "$judge_ok" = 'yes' ]; then printf 'executor+judge'
+  elif [ "$judge_ok" = 'yes' ]; then printf 'judge-only'
+  elif [ "$exec_ok" = 'yes' ]; then printf 'executor-only'
+  else printf 'none'
+  fi
+}
+
+printf '%-8s %-17s %-8s %-8s %-14s %-12s %s\n' \
+  'target' 'kind' 'binary' 'adapter' 'role' 'pin_eligible' 'note'
+
+pin_eligible_count=0
+missing_hints=()
+
+for i in "${!TARGETS[@]}"; do
+  target="${TARGETS[$i]}"
+  kind="${KINDS[$i]}"
+  binary="$(check_binary "${BINARIES[$i]}")"
+  adapter="$(check_adapter "$target")"
+  role="$(check_role "$ADAPTERS_DIR/$target.md")"
+
+  pin_eligible='no'
+  case "$kind" in
+    cli-engine) [ "$binary" = 'yes' ] && [ "$adapter" = 'yes' ] && pin_eligible='yes' ;;
+  esac
+
+  note='-'
+  case "$kind" in
+    cli-engine)
+      if [ "$pin_eligible" = 'yes' ]; then
+        pin_eligible_count=$((pin_eligible_count + 1))
+      elif [ "$binary" = 'no' ]; then
+        note="not installed; ${INSTALL_HINTS[$i]}"
+        missing_hints+=("$target: ${INSTALL_HINTS[$i]}")
+      else
+        note="binary present, no adapter — ship _shared/adapters/$target.md"
+      fi
+      ;;
+    orchestrator-only)
+      note='informational only; not a routable role engine — no verified CLI binary or adapter'
+      ;;
+  esac
+
+  printf '%-8s %-17s %-8s %-8s %-14s %-12s %s\n' \
+    "$target" "$kind" "$binary" "$adapter" "$role" "$pin_eligible" "$note"
+done
+
+printf '\n'
+if [ "$pin_eligible_count" -lt 2 ]; then
+  printf 'Recommendation: only %d adapter-valid engine(s) available. VERIFY pair-judge and\n' "$pin_eligible_count"
+  printf 'risk-probe escalation need a second, genuinely different model to check against —\n'
+  printf 'iter-0045 found different model tiers hit different failure-mode blind spots (not\n'
+  printf 'that any arbitrary second model helps); with fewer than 2, those routes can never\n'
+  printf 'fire and every run stays solo. Add one of:\n'
+  for hint in "${missing_hints[@]}"; do
+    printf '  - %s\n' "$hint"
+  done
+else
+  printf 'Pair-judge diversity: %d adapter-valid engines available.\n' "$pin_eligible_count"
+fi

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

@@ -11,21 +11,28 @@ Engine requirements have two classes:
 - **Explicit routes** — `--engine`, `--risk-probes`, `--pair-verify`. These are promises. If the required engine is unavailable, fail closed with `BLOCKED:<engine>-unavailable` and never downgrade to solo.
 - **Automatic escalations** — auto high-risk risk-probes and auto VERIFY pair-JUDGE inferred from the spec. These are candidate routes, selected only when their preconditions hold, OTHER-engine availability included. If an auto candidate would fire but the OTHER engine is absent, do not select the cross-engine route: proceed solo and report the skipped escalation and its reason. This is route selection, not a fallback.
 
-When a run or phase requires Codex, before spawning that phase:
+## Role resolution
 
-1. Check if the Codex CLI is installed: `command -v codex >/dev/null 2>&1` (or equivalent bash test).
-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.
+Two configurable roles; the orchestrator role is whichever CLI the user opened and is not configurable here.
+
+- **Executor** (IMPLEMENT / CLEANUP / primary VERIFY judge): explicit `--engine` flag > `cwd/.devlyn/engines.json` `executor` > built-in default `claude`. No parent-directory or global config lookup. Requires an adapter that is executor-eligible (below).
+- **Pair judge** (VERIFY pair-JUDGE, risk-probe derivation): first entry of `engines.json` `pair_judge_priority` that is (a) adapter-valid, (b) pair-judge-eligible (below), (c) not the primary judge engine, (d) available. When the key or file is absent: the binary claude↔codex complement.
+
+Validation is fail-closed: malformed JSON, any engine name without a `_shared/adapters/<name>.md` adapter file under `DEVLYN_SHARED_DIR`, or an adapter that declares itself ineligible for the requested role, halts with report-level `BLOCKED:invalid-engine-config` naming the offending entry. This is the plug-in point for new engines — ship an adapter file and the name becomes valid with zero skill-body changes. Availability probe default is `command -v <name>`; an adapter may declare a different probe. A pin is an explicit route (same promise class as `--engine`): pinned-but-unavailable → `BLOCKED:<engine>-unavailable`, never a silent downgrade. `engines.json` is machine-local config — not committed, not archived (`archive_run.py` moves only `PER_RUN_PATTERNS`).
 
-When a run or phase requires Claude, before spawning that phase:
+**Role eligibility** — an adapter's optional `## Role eligibility` section (`_shared/adapters/README.md`) declares `executor: yes|no` / `pair_judge: yes|no` as fixed ASCII fields. Absent section = eligible for both roles (every adapter shipped before iter-0051). A completion-only local backend with no tool/file-edit access declares `executor: no`: an `executor <name>` pin against it is invalid config, not an availability gap, and fails the same `BLOCKED:invalid-engine-config` path above rather than `BLOCKED:<name>-unavailable`.
 
-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.
+The explicit-vs-automatic split above applies unchanged to resolved engines: explicit routes (`--engine`, `--risk-probes`, `--pair-verify`, config pins) fail closed; automatic escalations select a cross-engine route only when the resolved pair-judge engine is available, else proceed solo and report the skip.
+
+When a run or phase requires engine `<name>` (claude, codex, omp, or any adapter-backed engine), before spawning that phase:
+
+1. Run the adapter's availability probe — default `command -v <name> >/dev/null 2>&1`; an adapter's `## Invocation` section may declare a stricter contract (e.g. `adapters/claude.md`: the probe is necessary but not sufficient under a network-denying sandbox, so a failed spawn is handled identically to a failed probe).
+2. On failure -> set the current phase/run verdict to `BLOCKED:<name>-unavailable`, preserve the failed check evidence, and show the adapter's setup guidance: install/configure that CLI, run its auth/login flow, verify `<name> --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 mid-pipeline. Missing engines for explicit routes are BLOCKED states, not silent fallbacks. Missing OTHER engines for automatic escalations are reported solo-skips, not fallbacks — the auto route was never selected.
 
-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.
+Per-skill defaults: `/devlyn:resolve` uses Claude for PLAN/IMPLEMENT when the orchestrator has Claude Code's native Agent primitive; Codex CLI and oh-my-pi orchestrators use their own fresh worker as the default route (Codex child process, omp native `task`) so the pipeline still has structural phase isolation. 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 report after a BLOCKED engine check
 
@@ -39,6 +46,6 @@ Setup: install/configure Codex CLI; run the current Codex auth/login flow; verif
 
 Do not report a downgraded successful run when a required engine is missing.
 
-## Canonical Codex invocation
+## Canonical cross-engine invocations
 
-See `config/skills/_shared/codex-config.md` for the canonical wrapper invocation and flag set skills should use after the availability check passes.
+After the availability check passes: a Claude-side orchestrator spawning a Codex judge/worker uses `config/skills/_shared/codex-config.md` (monitored wrapper, canonical flag set); a non-Claude orchestrator spawning a Claude judge uses `_shared/adapters/claude.md` `## Invocation` (headless `claude -p`, locked-down allowlist, hermetic settings).

package/config/skills/_shared/expected.schema.json

@@ -106,6 +106,32 @@
       "description": "Hard cap on new entries under dependencies/devDependencies in package.json. Exceeds → DQ.",
       "minimum": 0,
       "default": 0
+    },
+    "pure_design": {
+      "type": "boolean",
+      "description": "Declares that every Requirement is pure-design (no observable runtime check). Lets verification_commands stay empty without failing shape validation. Contradictory (and rejected) when true alongside a non-empty verification_commands.",
+      "default": false
+    },
+    "required_risk_probe_requirements": {
+      "type": "array",
+      "description": "Language-neutral replacement for prose-keyword risk-probe classification: explicit {tag, derived_from} obligations the spec author declares directly. When `--risk-probes` is enabled, risk-probes.jsonl must include a probe whose tags include `tag` and whose derived_from exactly equals `derived_from` for each entry.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["tag", "derived_from"],
+        "properties": {
+          "tag": {
+            "type": "string",
+            "description": "One of the risk-probe tags defined in _shared/spec-verify-check.py:RISK_PROBE_TAGS (e.g. ordering_inversion, rollback_state, shape_contract)."
+          },
+          "derived_from": {
+            "type": "string",
+            "description": "Exact substring of the sibling spec.md's visible verification section that demands this tag.",
+            "minLength": 1
+          }
+        }
+      },
+      "default": []
     }
   }
 }

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

@@ -51,7 +51,7 @@ This rule exists because LLMs (including you) are trained to be helpful, compreh
 **The five drift patterns you must refuse to execute on:**
 
 1. **Unrequested work.** "While I'm here, I noticed X is broken/ugly/inefficient" → **stop**. The user did not ask for X. If X is a real defect, surface it as a finding, a follow-up suggestion, or an entry in a TODO list — do NOT fix it inside the current change. Mixing unrequested work with requested work is what makes diffs unreviewable and PRs eternal. **Pre-existing dead code → mention only, do NOT delete; orphans YOUR change created (now-unused imports, variables, functions) → clean them up.**
-2. **Tangential cleanup.** "This file looks messy, let me also tidy..." → **stop**. The current task is the only task. Unrelated cleanup is a separate change requiring its own justification, scope, and pre-flight 0 check. **Match existing style even if you'd write it differently; do NOT touch comments, formatting, or code orthogonal to your real change** — silent side-effects on neighboring lines are the most common Karpathy-observed regression class.
+2. **Tangential cleanup.** "This file looks messy, let me also tidy..." → **stop**. The current task is the only task. Unrelated cleanup is a separate change requiring its own justification, scope, and pre-flight 0 check. **Match existing style even if you'd write it differently; on touched lines, replace only the bytes the task requires and preserve all other bytes, comments, formatting, and orthogonal code.**
 3. **Speculative robustness.** "Just adding a check / fallback / handler for the case where..." → **stop**. If the case has not been observed (in production, in tests, in a finding), it does not belong in this change. Defensive code added for unobserved cases is the most common form of accretion debt — it never gets removed because nobody can prove the case never happens.
 4. **Re-scoping mid-flight.** "Actually, the better way to do this is to also restructure / rename / migrate..." → **stop**. If you discover the requested approach is wrong, surface that to the user with evidence and let them adjudicate. Do NOT silently expand scope. The user's explicit redirect is the only authorization to enlarge a task.
 5. **Curiosity detours.** "Let me also explore how Y works to understand this better..." → **stop**, unless Y is provably on the goal's critical path. Curiosity-driven exploration is creative-mode; default is execution-mode.