devlyn-cli 2.6.1 → 2.8.0

package/bin/devlyn.js

@@ -7,7 +7,6 @@ const readline = require('readline');
 const { execSync } = require('child_process');
 
 const CONFIG_SOURCE = path.join(__dirname, '..', 'config');
-const AGENTS_SOURCE = path.join(__dirname, '..', 'agents-config');
 const OPTIONAL_SKILLS_SOURCE = path.join(__dirname, '..', 'optional-skills');
 const PKG = require('../package.json');
 
@@ -15,7 +14,8 @@ const PKG = require('../package.json');
 // directory. Single source of truth so codex/omp/pi stay in lockstep — adding a
 // skill here installs it everywhere. Standards skills (code-*, root-cause-*,
 // ui-*) stay Claude-core-only, matching the pre-existing Codex bundle.
-const DEVLYN_CORE_SKILLS = ['devlyn:resolve', 'devlyn:ideate', 'devlyn:design-ui', '_shared'];
+const DEVLYN_CORE_SKILLS = ['devlyn:resolve', 'devlyn:ideate', 'devlyn:design-ui', 'devlyn:engines', 'devlyn:queue', '_shared'];
+const DEVLYN_SKILL_DIR_STAMP = '__DEVLYN_SKILL_DIR__';
 
 // Cross-agent shared skills directory read by BOTH oh-my-pi and Pi. Verified
 // from the omp binary's skill-provider strings ("skills from .agents/skills —
@@ -31,7 +31,6 @@ const CLI_TARGETS = {
     name: 'Codex CLI (OpenAI)',
     instructionsFile: 'AGENTS.md',
     baseInstructionsFile: 'AGENTS.md',
-    configDir: null, // Codex uses AGENTS.md at project root
     // Codex auto-loads skills from ~/.codex/skills/ (user-global). Same
     // SKILL.md format as Claude Code; descriptions must stay ≤1024 chars.
     skillsDir: path.join(os.homedir(), '.codex', 'skills'),
@@ -42,7 +41,6 @@ const CLI_TARGETS = {
     name: 'oh-my-pi (omp)',
     instructionsFile: 'AGENTS.md',
     baseInstructionsFile: 'AGENTS.md',
-    configDir: null, // omp discovers AGENTS.md at project root + user home
     // omp loads skills from ~/.agents/skills (user home) — shared with Pi.
     skillsDir: SHARED_AGENTS_SKILLS_DIR,
     skillsToInstall: DEVLYN_CORE_SKILLS,
@@ -54,37 +52,12 @@ const CLI_TARGETS = {
     name: 'Pi (earendil-works)',
     instructionsFile: 'AGENTS.md',
     baseInstructionsFile: 'AGENTS.md',
-    configDir: null, // Pi reads AGENTS.md / CLAUDE.md walking up from cwd
     // Pi loads skills from ~/.agents/skills — shared with oh-my-pi.
     skillsDir: SHARED_AGENTS_SKILLS_DIR,
     skillsToInstall: DEVLYN_CORE_SKILLS,
     // Project-scoped only (see omp): machine-level ~/.pi must not auto-trigger.
     detect: () => fs.existsSync(path.join(process.cwd(), '.pi')) || fs.existsSync(path.join(process.cwd(), '.agents')),
   },
-  gemini: {
-    name: 'Gemini CLI (Google)',
-    instructionsFile: 'GEMINI.md',
-    configDir: null, // Gemini uses GEMINI.md at project root
-    detect: () => fs.existsSync(path.join(process.cwd(), 'GEMINI.md')) || fs.existsSync(path.join(process.cwd(), '.gemini')),
-  },
-  cursor: {
-    name: 'Cursor',
-    instructionsFile: '.cursorrules',
-    configDir: '.cursor/rules',
-    detect: () => fs.existsSync(path.join(process.cwd(), '.cursorrules')) || fs.existsSync(path.join(process.cwd(), '.cursor')),
-  },
-  copilot: {
-    name: 'GitHub Copilot',
-    instructionsFile: '.github/copilot-instructions.md',
-    configDir: '.github/copilot/agents',
-    detect: () => fs.existsSync(path.join(process.cwd(), '.github', 'copilot-instructions.md')) || fs.existsSync(path.join(process.cwd(), '.github', 'copilot')),
-  },
-  windsurf: {
-    name: 'Windsurf',
-    instructionsFile: '.windsurfrules',
-    configDir: '.windsurf/rules',
-    detect: () => fs.existsSync(path.join(process.cwd(), '.windsurfrules')) || fs.existsSync(path.join(process.cwd(), '.windsurf')),
-  },
 };
 
 // Files removed in previous versions that should be cleaned up on upgrade
@@ -214,7 +187,7 @@ const OPTIONAL_ADDONS = [
   { name: 'asset-creator', desc: 'AI pixel art game asset pipeline — generate, chroma-key, catalog', type: 'local' },
   { name: 'cloudflare-nextjs-setup', desc: 'Cloudflare Workers + Next.js deployment with OpenNext', type: 'local' },
   { name: 'generate-skill', desc: 'Create well-structured Claude Code skills following Anthropic best practices', type: 'local' },
-  { name: 'prompt-engineering', desc: 'Claude 4 prompt optimization using Anthropic best practices', type: 'local' },
+  { name: 'prompt-engineering', desc: 'Claude prompt optimization using Anthropic best practices', type: 'local' },
   { name: 'better-auth-setup', desc: 'Production-ready Better Auth + Hono + Drizzle + PostgreSQL auth setup', type: 'local' },
   { name: 'polar-billing-setup', desc: 'Polar usage-based / metered billing — correct setup + diagnose silent $0-billing failures', type: 'local' },
   { name: 'pyx-scan', desc: 'Check whether an AI agent skill is safe before installing', type: 'local' },
@@ -368,6 +341,40 @@ function copyRecursive(src, dest, baseDir) {
   }
 }
 
+function shellDoubleQuoteDefault(value) {
+  if (value.includes('\n')) {
+    throw new Error(`Cannot stamp skill path with newline: ${value}`);
+  }
+  return value.replace(/[\\$"`}]/g, '\\$&');
+}
+
+function stampInstalledSkillDir(rootDir, skillDir) {
+  // Stamp ONLY the assignment-default occurrence. The sentinel comparison
+  // literal on the guard line must stay intact: stamping it makes the guard
+  // compare the stamped default to itself and false-positive
+  // BLOCKED:shared-dir-unresolved on every codex/omp run that executes the
+  // block (CLAUDE_SKILL_DIR unset) — iter-0040 R3 latent finding.
+  const assignmentStamp = '${CLAUDE_SKILL_DIR:-' + DEVLYN_SKILL_DIR_STAMP + '}';
+  const stampedAssignment = '${CLAUDE_SKILL_DIR:-' + shellDoubleQuoteDefault(skillDir) + '}';
+
+  function visit(current) {
+    const stats = fs.statSync(current);
+    if (stats.isDirectory()) {
+      for (const item of fs.readdirSync(current)) {
+        visit(path.join(current, item));
+      }
+      return;
+    }
+    if (path.extname(current) !== '.md') return;
+
+    const content = fs.readFileSync(current, 'utf8');
+    if (!content.includes(assignmentStamp)) return;
+    fs.writeFileSync(current, content.split(assignmentStamp).join(stampedAssignment));
+  }
+
+  visit(rootDir);
+}
+
 // Dev artifacts that live under config/skills/ but must never ship or install.
 // Mirrors the `!` exclusions in package.json files[].
 const UNSHIPPED_SKILL_DIRS = new Set([
@@ -579,6 +586,11 @@ function installSkillsForCLI(cliKey) {
     fs.mkdirSync(cli.skillsDir, { recursive: true });
   }
 
+  const removed = cleanupDeprecated(path.dirname(cli.skillsDir));
+  if (removed > 0) {
+    log(`\n🧹 Cleaned up ${removed} deprecated file${removed > 1 ? 's' : ''}`, 'yellow');
+  }
+
   let copied = 0;
   for (const skillName of cli.skillsToInstall) {
     const src = path.join(sourceSkillsDir, skillName);
@@ -590,21 +602,20 @@ function installSkillsForCLI(cliKey) {
       fs.rmSync(dest, { recursive: true, force: true });
     }
     copyRecursive(src, dest, cli.skillsDir);
+    stampInstalledSkillDir(dest, dest);
     copied++;
     log(`  → ${cli.skillsDir.replace(os.homedir(), '~')}/${skillName}`, 'dim');
   }
   return copied;
 }
 
-// Strip devlyn's previously-appended "# Devlyn Agent Instructions" block from an
-// instruction file (or the packaged base) before re-appending, so installs stay
-// idempotent and never duplicate the block. Anchors on the LAST marker, not the
-// first: the packaged AGENTS.md ships its own "# Devlyn Agent Instructions"
-// section, so indexOf would truncate that real content — lastIndexOf targets the
-// devlyn-appended block (always last) and preserves everything above it.
+// Strip the legacy "# Devlyn Agent Instructions" block (the retired evaluator
+// agent) that earlier installs appended to instruction files, so upgrades scrub
+// it instead of carrying it forever. Anchors on the LAST marker so user content
+// above a stray copy of the block is preserved.
+const DEVLYN_AGENTS_MARKER = '# Devlyn Agent Instructions';
 function stripManagedBlock(content) {
-  const marker = '# Devlyn Agent Instructions';
-  const markerIdx = content.lastIndexOf(marker);
+  const markerIdx = content.lastIndexOf(DEVLYN_AGENTS_MARKER);
   if (markerIdx > 0) {
     const sepIdx = content.lastIndexOf('\n---', markerIdx);
     return content.slice(0, sepIdx > 0 ? sepIdx : markerIdx).trimEnd();
@@ -613,63 +624,40 @@ function stripManagedBlock(content) {
 }
 
 // One-line description of exactly what selecting a CLI target installs, so the
-// unified selector stays honest — "Gemini" (instructions only) must not look
-// identical to "Codex" (instructions + skills).
+// unified selector stays honest.
 function targetDesc(cli) {
   if (cli.skillsDir) {
     return `${cli.instructionsFile} + devlyn skills → ${cli.skillsDir.replace(os.homedir(), '~')}`;
   }
-  if (cli.configDir) return `Agent instructions → ${cli.configDir}/`;
   return `${cli.instructionsFile} instructions only`;
 }
 
-// Install only the instruction file(s) for a CLI (no skills). Returns true when
-// instruction content was written. Split from skills so the de-dup driver can
-// write a shared destination (e.g. project AGENTS.md for codex/omp/pi) once.
+// Install the packaged base instruction file for a CLI (project AGENTS.md for
+// codex/omp/pi). Creates it from the packaged base when missing; on existing
+// files, scrubs the legacy appended block and otherwise leaves user content
+// untouched. Returns true when the destination was written.
 function installInstructionsForCLI(cliKey) {
   const cli = CLI_TARGETS[cliKey];
-  if (!cli) return false;
-
-  const agents = fs.existsSync(AGENTS_SOURCE)
-    ? fs.readdirSync(AGENTS_SOURCE).filter((f) => f.endsWith('.md'))
-    : [];
-  if (agents.length === 0) return false;
-
-  log(`\n🤖 Installing agent instructions for ${cli.name}...`, 'cyan');
-
-  if (cli.configDir) {
-    // CLI supports an agents directory — copy agent files there
-    const destDir = path.join(process.cwd(), cli.configDir);
-    if (!fs.existsSync(destDir)) {
-      fs.mkdirSync(destDir, { recursive: true });
-    }
-    for (const file of agents) {
-      const src = path.join(AGENTS_SOURCE, file);
-      const dest = path.join(destDir, file);
-      fs.copyFileSync(src, dest);
-      log(`  → ${cli.configDir}/${file}`, 'dim');
+  if (!cli || !cli.baseInstructionsFile) return false;
+
+  const destFile = path.join(process.cwd(), cli.instructionsFile);
+  let content = null;
+  if (fs.existsSync(destFile)) {
+    const current = fs.readFileSync(destFile, 'utf8');
+    if (current.includes(DEVLYN_AGENTS_MARKER)) {
+      content = stripManagedBlock(current) + '\n';
     }
   } else {
-    // CLI uses a single instructions file — append agent content
-    const destFile = path.join(process.cwd(), cli.instructionsFile);
-    const separator = '\n\n---\n\n# Devlyn Agent Instructions\n\n';
-    const agentContent = agents.map((file) => {
-      return fs.readFileSync(path.join(AGENTS_SOURCE, file), 'utf8');
-    }).join('\n\n---\n\n');
-
-    let existing = '';
-    if (fs.existsSync(destFile)) {
-      existing = stripManagedBlock(fs.readFileSync(destFile, 'utf8'));
-    } else if (cli.baseInstructionsFile) {
-      const baseInstructionsSrc = path.join(__dirname, '..', cli.baseInstructionsFile);
-      if (fs.existsSync(baseInstructionsSrc)) {
-        existing = stripManagedBlock(fs.readFileSync(baseInstructionsSrc, 'utf8'));
-      }
+    const baseInstructionsSrc = path.join(__dirname, '..', cli.baseInstructionsFile);
+    if (fs.existsSync(baseInstructionsSrc)) {
+      content = fs.readFileSync(baseInstructionsSrc, 'utf8');
     }
-
-    fs.writeFileSync(destFile, existing + separator + agentContent + '\n');
-    log(`  → ${cli.instructionsFile} (agent instructions appended)`, 'dim');
   }
+  if (content === null) return false;
+
+  log(`\n🤖 Installing instructions for ${cli.name}...`, 'cyan');
+  fs.writeFileSync(destFile, content);
+  log(`  → ${cli.instructionsFile}`, 'dim');
   return true;
 }
 
@@ -696,7 +684,7 @@ function installSelectedCLITargets(cliKeys) {
   for (const cliKey of cliKeys) {
     const cli = CLI_TARGETS[cliKey];
     if (!cli) continue;
-    const instrKey = cli.configDir ? `dir:${cli.configDir}` : `file:${cli.instructionsFile}`;
+    const instrKey = cli.instructionsFile;
     if (!instrDone.has(instrKey)) {
       installInstructionsForCLI(cliKey);
       instrDone.add(instrKey);

package/config/skills/_shared/adapters/README.md

@@ -42,6 +42,13 @@ Specific patterns the official guide warns about for this model.
 
 Keep each section to ≤ 8 lines. Adapters are deltas, not full prompts. If an adapter grows past ~80 lines, the content probably belongs in canonical body.
 
+## Role-scoped and non-agentic adapters
+
+Adapters may add two more sections beyond the base format:
+
+- **`## Role eligibility`** — fixed ASCII fields, one per line: `executor: yes|no`, `pair_judge: yes|no`. Absent section = eligible for both roles (every adapter shipped before iter-0051). Present only when a backend is structurally unable to fill a role — e.g. a completion-only local model has no tool/file-edit access, so it declares `executor: no`. `_shared/engine-preflight.md` and `/devlyn:engines` read this section as a structured marker, not prose, so it validates mechanically.
+- **`## Invocation`** — for backends called over an API instead of a CLI: the concrete request shape (endpoint, JSON body, timeout) and the adapter-declared availability probe (`_shared/engine-preflight.md#role-resolution`'s "an adapter may declare a different probe" hook).
+
 ## When to add a new adapter
 
 A new adapter file ships when:

package/config/skills/_shared/adapters/claude.md

@@ -1,10 +1,57 @@
-# Claude Opus adapter
+# Claude adapter
 
 > Source: <https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices>
 
+## Invocation
+
+Orchestrator-side contract for spawning a Claude judge from a non-Claude
+orchestrator (Codex CLI, oh-my-pi) — the reverse-direction counterpart of
+`_shared/codex-config.md`. Source: <https://code.claude.com/docs/en/headless>
+and <https://code.claude.com/docs/en/cli-reference>.
+
+**Availability probe**: `command -v claude >/dev/null 2>&1`; record
+`claude --version` as evidence. The probe is necessary, not sufficient:
+`claude -p` needs network access to the Anthropic API, so a network-denying
+sandbox (e.g. Codex CLI's default `workspace-write`) fails the spawn even
+though the binary resolves. A failed spawn is the same fail-closed class as a
+failed probe (`_shared/engine-preflight.md`): explicit route →
+`BLOCKED:claude-unavailable`; automatic escalation → solo + reported skip.
+
+**Read-only pair-JUDGE call** (bounded by the VERIFY pair contract — at most
+two targeted probes; the invoking phase sets `--effort`, pair-JUDGE uses
+`medium`):
+
+```bash
+claude -p "<judge prompt>" \
+  --permission-mode dontAsk \
+  --allowedTools "Read,Grep,Glob,Bash(<repo test command> *)" \
+  --setting-sources project --strict-mcp-config --mcp-config '{"mcpServers":{}}' \
+  --effort medium \
+  > .devlyn/claude-judge.stdout 2> .devlyn/claude-judge.stderr
+```
+
+- Omit `--model` — the CLI's configured default is used (zero-touch, same
+  rule as codex-config.md's "omit `-m`").
+- `dontAsk` denies anything not allowlisted (official guide: "denies
+  anything not in your permissions.allow rules or the read-only command
+  set — useful for locked-down CI runs"); in `-p` mode a denied tool call
+  fails without prompting, so the child can never hang on a permission ask.
+- The `--setting-sources project --strict-mcp-config --mcp-config
+  '{"mcpServers":{}}'` trio is the hermetic-child pattern: no user-global
+  settings, hooks, or MCP servers. `--bare` is NOT used — it skips
+  OAuth/keychain reads and requires `ANTHROPIC_API_KEY`, which
+  subscription-auth machines do not have.
+- Findings come back as JSONL on stdout (same emission shape as the Codex
+  direction); the orchestrator writes the canonical
+  `.devlyn/verify.pair.findings.jsonl`. Raw stdout stays diagnostic at
+  `.devlyn/claude-judge.stdout`; `verify-merge-findings.py` blocks the run
+  if stdout contains findings the canonical file lacks.
+- Do not pipe stdout (`| tail`, `| grep`); capture to file. Non-zero exit or
+  empty stdout → spawn failure, fail closed per the probe rule above.
+
 ## Identity
 
-You are Claude Opus by Anthropic. Anthropic's prompt-engineering guide for this model governs your behavior on top of the canonical phase prompt below. When the canonical body and this header conflict on tactics, the canonical body wins on what to deliver; this header wins on how to deliver it.
+You are Claude by Anthropic. Anthropic's prompt-engineering guide for this model governs your behavior on top of the canonical phase prompt below. When the canonical body and this header conflict on tactics, the canonical body wins on what to deliver; this header wins on how to deliver it.
 
 ## Output discipline
 

package/config/skills/_shared/adapters/omp.md

@@ -0,0 +1,17 @@
+# oh-my-pi adapter
+
+## Identity
+
+You are the model running behind the `omp` CLI. Follow the canonical phase prompt exactly; this adapter exists so oh-my-pi can be selected as a first-class native task worker by `/devlyn:resolve`.
+
+## Output Discipline
+
+Keep phase output machine-consumable and concise. Write the artifacts the canonical body names, update `.devlyn/pipeline.state.json` only where that phase owns the state write, and avoid narrative outside the required phase result.
+
+## Validation Pattern
+
+When the canonical body names deterministic commands, run those commands and trust their exit codes. Do not replace BUILD_GATE, phase gates, or VERIFY mechanical checks with same-context judgment.
+
+## Fresh Context
+
+Each native `task` tool invocation with a fresh `context` is a fresh phase worker. Do not call `/devlyn:resolve` recursively from inside a phase prompt; execute only the phase body you received.

package/config/skills/_shared/archive_run.py

@@ -56,7 +56,9 @@ PER_RUN_PATTERNS = (
     # ("pair_judge findings archive distinguishable") would false-fail on
     # every paired fixture without this glob.
     "verify-judge-*.md",
-    "codex-judge.*",
+    # *-judge.*: every engine's pair-judge stdout/stderr capture
+    # (codex-judge.*, claude-judge.* — adapters/claude.md ## Invocation).
+    "*-judge.*",
 )
 
 SAFE_RUN_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
@@ -140,12 +142,14 @@ def self_test() -> int:
             "verify-merge.summary.json",
             "codex-judge.stdout",
             "codex-judge.summary.json",
+            "claude-judge.stdout",
+            "claude-judge.stderr",
         ):
             (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
+        assert moved >= 8, moved
         for name in (
             "pipeline.state.json",
             "risk-probes.jsonl",
@@ -153,6 +157,8 @@ def self_test() -> int:
             "verify-merge.summary.json",
             "codex-judge.stdout",
             "codex-judge.summary.json",
+            "claude-judge.stdout",
+            "claude-judge.stderr",
         ):
             assert (devlyn / "runs" / run_id / name).is_file(), name
 

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": []
     }
   }
 }