devlyn-cli 2.9.2 → 2.10.0

package/AGENTS.md

@@ -10,7 +10,7 @@ This contract serves one goal: any capable engine — Claude, GPT/Codex, or a fu
 
 Seven rules govern every change. Cite them by name when a decision touches one.
 
-1. **No workaround** — fix the root cause, never the symptom. No `any`, no `@ts-ignore`, no silent `catch`, no hardcoded fallback that hides a broken contract.
+1. **No workaround** — fix the root cause, never the symptom. No `any`, no `@ts-ignore`, no silent `catch`, no hardcoded fallback that hides a broken contract. Explicit `--engine`, `--risk-probes`, and `--pair-verify` routes fail closed; automatic VERIFY pair is capability-gated and reports an unavailable-engine solo route.
 2. **No overengineering** — smallest change that closes the goal. New abstractions require an observed failure mode they prevent. Subtractive-first: ask "what can I delete instead?" before writing anything new.
 3. **No guesswork** — verify with the actual files, logs, diffs, and run output before forming conclusions. State the falsifiable prediction BEFORE the experiment; record raw results AFTER.
 4. **Worldclass** — code that survives review at a non-trivial codebase. Zero CRITICAL, zero HIGH security/design findings on the shippable path.
@@ -36,7 +36,7 @@ ideate (optional)  ->  resolve  ->  ship
 
 Each skill's `SKILL.md` is the source of truth for flags and workflow. Do not duplicate.
 
-Engine roles: orchestrator = whichever CLI the user opened (this contract is symmetric with CLAUDE.md; measured status 2026-07-05: Claude Code + omp run the full phase-gated pipeline; in the iter-0061 minimal-repo trivial-add shape on this machine, Codex CLI also ran it when this AGENTS.md was present in the project (ordinary invocation, 4/4); without project AGENTS.md, the same shape silently skipped the pipeline (iter-0040 F6, 4/4). If you are Codex orchestrating `/devlyn:resolve`, the phase machinery is mandatory regardless of task size; if you will not run it, say so explicitly and stop — do not silently degrade to ad-hoc execution); executor (PLAN/IMPLEMENT/CLEANUP) defaults to `claude`, overridable per run with `--engine <name>` or durably via machine-local `.devlyn/engines.json` `{"executor": "<name>", "pair_judge_priority": ["<name>", ...]}`; pair judge = first available OTHER engine. Pins fail closed (`BLOCKED:<engine>-unavailable` / `BLOCKED:invalid-engine-config`); new engines plug in by shipping `_shared/adapters/<name>.md`. `/devlyn:engines` (no args) shows the role table + detected engines; `executor <name>` / `pair <name>,...` / `clear` manage the pins. The executor pin binds the orchestrator in plain conversation too, not only inside a skill run: when you would implement directly and executor is pinned to a non-default engine, route that work through the pin — via `/devlyn:resolve` (reads it at PHASE 0) or by delegating to that engine — instead of editing as `claude`; no pin / no file → unchanged (`claude`). The pair-judge pin stays pipeline-scoped.
+Engine roles: orchestrator = whichever CLI the user opened (this contract is symmetric with CLAUDE.md; measured status 2026-07-05: Claude Code + omp run the full phase-gated pipeline; in the iter-0061 minimal-repo trivial-add shape on this machine, Codex CLI also ran it when this AGENTS.md was present in the project (ordinary invocation, 4/4); without project AGENTS.md, the same shape silently skipped the pipeline (iter-0040 F6, 4/4). If you are Codex orchestrating `/devlyn:resolve`, the phase machinery is mandatory regardless of task size; if you will not run it, say so explicitly and stop — do not silently degrade to ad-hoc execution); executor (PLAN/IMPLEMENT/CLEANUP) defaults to `claude`, overridable per run with `--engine <name>` or durably via machine-local `.devlyn/engines.json` `{"executor": "<name>", "pair_judge_priority": ["<name>", ...]}`; pair judge = first available OTHER engine, default for VERIFY whenever available; risk probes remain conditional and --no-pair opts out. Pins fail closed (`BLOCKED:<engine>-unavailable` / `BLOCKED:invalid-engine-config`); new engines plug in by shipping `_shared/adapters/<name>.md`. `/devlyn:engines` (no args) shows the role table + detected engines; `executor <name>` / `pair <name>,...` / `clear` manage the pins. The executor pin binds the orchestrator in plain conversation too, not only inside a skill run: when you would implement directly and executor is pinned to a non-default engine, route that work through the pin — via `/devlyn:resolve` (reads it at PHASE 0) or by delegating to that engine — instead of editing as `claude`; no pin / no file → unchanged (`claude`). The pair-judge pin stays pipeline-scoped.
 
 Conversational handoff + loop engineering (default entry): the orchestrating model — not the user — invokes the skills. `/devlyn:queue` fronts the intent queue (`docs/specs/queue.md`): no args = status, `add <intent>`, `drain` = serial unattended drain per the contract below. Large agreed work is written to `docs/specs/<id>/spec.md` (always a spec file — the user's reviewed contract; free-form large assumes-and-logs instead of halting, zero-scope-signal goals still halt to ideate), summarized once for user review, then run hands-free via `--spec`. Outer loop per task: findings-backed verdicts (NEEDS_WORK, verify/build-gate exhaustion) get spec amendment + re-run, max 3 iterations; infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts surface immediately. Unattended queue drain (`docs/specs/queue.md`, strictly serial): assumptions may only take scope-narrowing, reversible, non-user-visible defaults — material ambiguity marks the item `[F] needs-review` and the drain continues.
 
@@ -81,7 +81,7 @@ No silent fallbacks.
 - Fallbacks allowed only when widely accepted and harmless (CSS fallback fonts, CDN failover, image placeholders).
 - Silent `catch` blocks are bugs.
 - Logging is not user-visible error handling.
-- No engine-availability fallback for EXPLICITLY-requested routes (`--engine`, `--risk-probes`, `--pair-verify`): if the required engine is unavailable, emit `BLOCKED:codex-unavailable` or `BLOCKED:claude-unavailable` with setup guidance; never downgrade an explicit route to solo. Automatic high-risk escalations (auto risk-probes / auto VERIFY pair) are capability-gated: they activate only when the OTHER engine is available, else the run proceeds solo and reports the skip (route selection, not a fallback — keeps single-LLM users first-class). `--no-pair` and `--no-risk-probes` remain explicit opt-outs.
+- Engine availability follows **No workaround** principle 1: explicit routes fail closed; automatic routes are capability-gated and report a solo skip when OTHER is unavailable. No fallback.
 
 ## Evidence Over Claim
 

package/CLAUDE.md

@@ -10,7 +10,7 @@ This contract serves one goal: any capable engine — Claude, GPT/Codex, or a fu
 
 Seven rules govern every change. Cite them by name when a decision touches one.
 
-1. **No workaround** — fix the root cause, never the symptom. Blocked patterns: `any`, `@ts-ignore`, silent `catch`, hardcoded fallback hiding a broken contract, config-level skip bypassing the real issue, helper script that routes around it. **Permitted exceptions** (widely-accepted defaults only): CSS fallback fonts, CDN failover, image placeholders. **No engine-availability fallback** for EXPLICITLY-requested `/devlyn:resolve` routes (`--engine`, `--risk-probes`, `--pair-verify`) — if the required engine is unavailable, stop with `BLOCKED:codex-unavailable` or `BLOCKED:claude-unavailable` and setup guidance; never downgrade an explicit route to solo. AUTOMATIC high-risk escalations (auto risk-probes / auto VERIFY pair) are capability-gated: they activate only when the OTHER engine is available; otherwise the run proceeds solo and reports the skip — route selection, not a fallback, and the reason single-LLM users stay first-class. `--no-pair` / `--no-risk-probes` remain explicit opt-outs.
+1. **No workaround** — fix the root cause, never the symptom. No `any`, no `@ts-ignore`, no silent `catch`, no hardcoded fallback that hides a broken contract. No config bypasses. Explicit `--engine`, `--risk-probes`, and `--pair-verify` routes fail closed when a required engine is unavailable. Automatic risk probes remain high-risk-gated; VERIFY pair is default-when-available. An unavailable OTHER engine routes automatic VERIFY solo with a reported skip. `--no-pair` and `--no-risk-probes` remain explicit opt-outs.
 2. **No overengineering** — smallest change that closes the goal. New abstractions require an observed failure mode they prevent. Subtractive-first: ask "what can I delete instead?" before writing anything new.
 3. **No guesswork** — verify with the actual files, logs, diffs, and run output before forming conclusions. State the falsifiable prediction BEFORE the experiment; record raw results AFTER. Retroactive prediction edits are dishonest.
 4. **Worldclass** — code that survives review at a non-trivial codebase. Zero CRITICAL, zero HIGH security/design findings on the shippable path.
@@ -41,7 +41,7 @@ Each skill's `SKILL.md` is the source of truth for its flags and workflow — do
 |---|---|---|
 | Orchestrator — conversation, handoff, loop driving | whichever CLI you open (contract is symmetric: CLAUDE.md ↔ AGENTS.md). Measured status 2026-07-05: Claude Code + omp run the full phase-gated pipeline; in the iter-0061 minimal-repo trivial-add shape on this machine, Codex CLI also ran it when the project carried the devlyn AGENTS.md (ordinary invocation, 4/4); without project AGENTS.md, the same shape silently skipped the pipeline (iter-0040 F6, 4/4) | switch CLIs; the file artifacts (spec/queue/state) carry over |
 | Executor — PLAN/IMPLEMENT/CLEANUP + primary VERIFY judge | `claude` | `--engine <name>` per run, or `/devlyn:engines executor <name>` (durable pin) |
-| Pair judge — VERIFY pair-JUDGE, risk probes | first available OTHER engine (claude↔codex) | `/devlyn:engines pair <name>,...`; `--no-pair` opts out |
+| Pair judge — default for VERIFY; conditional for risk probes | first available OTHER engine (claude↔codex) | `/devlyn:engines pair <name>,...`; `--no-pair` opts out |
 
 `/devlyn:engines` with no args shows the current role table, detected engines, and how to pin or clear — the pins live in `.devlyn/engines.json`.
 
@@ -158,14 +158,14 @@ A finding without one of these forms is excluded. Vague findings produce vague f
 
 ## Codex invocation
 
-When `/devlyn:resolve` or `/devlyn:ideate` route a phase to Codex (`--engine codex` or conditional VERIFY pair/risk-probe routing), the wrapper-form contract lives in `config/skills/_shared/codex-config.md` (or `.claude/skills/_shared/codex-config.md` once installed). Omit `-m <model>` — the CLI's current flagship is used automatically. MCP is not in the loop. If Codex is required and unavailable, stop with `BLOCKED:codex-unavailable` and setup guidance.
+When `/devlyn:resolve` or `/devlyn:ideate` route a phase to Codex (`--engine codex`, default VERIFY pair, or conditional risk-probe routing), the wrapper-form contract lives in `config/skills/_shared/codex-config.md` (or `.claude/skills/_shared/codex-config.md` once installed). Omit `-m <model>` — the CLI's current flagship is used automatically. MCP is not in the loop. If Codex is required and unavailable, stop with `BLOCKED:codex-unavailable` and setup guidance.
 
 ## Working Mode
 
 - **Checkpoint with TaskCreate / TaskUpdate.** Long investigations or multi-phase work: create tasks at start, mark completed as each one closes — don't batch.
 - **Don't stop early on token-budget concerns.** Context auto-compacts; the model resumes after compaction. Run the work to a real stopping point.
 - **Persist across context windows via disk.** `/devlyn:resolve` writes `.devlyn/pipeline.state.json` plus per-phase log/findings under `.devlyn/runs/<run_id>/`; for ad-hoc long work use `HANDOFF.md` and resume with `@HANDOFF.md continue`.
-- **Parallelize independent tool calls; reserve `Agent` subagents for independent fan-out or isolated-context verification** — a single perspective is the default on the resolve hot path.
+- **Parallelize independent tool calls; reserve `Agent` subagents for independent fan-out or isolated-context verification** — a single perspective is the default outside VERIFY's dual-judge path.
 
 ## Skill Boundary Policy
 

package/README.md

@@ -27,7 +27,7 @@ If devlyn-cli saved you time, [give it a star](https://github.com/fysoul17/devly
 npx devlyn-cli
 ```
 
-That's it. The installer opens with a single **agent selector** — pick any combination of **Claude Code**, **Codex CLI**, **oh-my-pi (omp)**, or **Pi**, and devlyn installs into every one you choose in a single pass. Claude Code and any agent already present on your machine are pre-checked, so the common case is just Enter. Skill-capable agents receive the `devlyn:resolve`, `devlyn:ideate`, and `devlyn:design-ui` skills — plus the `devlyn:engines` and `devlyn:queue` utilities — in the directory each one loads from: Codex → `~/.codex/skills/`, while **omp and Pi share `~/.agents/skills/`** — the cross-agent standard both read — so the bundle is written there once, not duplicated per agent. In Codex / omp / Pi, invoke them as skills (`$devlyn:resolve`, `$devlyn:ideate`, `$devlyn:design-ui`); in Claude Code they're slash commands (`/devlyn:resolve`). Run it again anytime to update. (`npx devlyn-cli -y` installs the Claude core non-interactively; `npx devlyn-cli agents <cli>` adds one agent later.)
+That's it. The installer opens with a single **agent selector** — pick any combination of **Claude Code**, **Codex CLI**, **oh-my-pi (omp)**, **Pi**, or **Grok Build CLI**, and devlyn installs into every one you choose in a single pass. Claude Code and any agent already present on your machine are pre-checked, so the common case is just Enter. Skill-capable agents receive the `devlyn:resolve`, `devlyn:ideate`, and `devlyn:design-ui` skills — plus the `devlyn:engines` and `devlyn:queue` utilities — in the directory each one loads from: Codex → `~/.codex/skills/`, Grok → `~/.grok/skills/`, while **omp and Pi share `~/.agents/skills/`** — the cross-agent standard both read — so the bundle is written there once, not duplicated per agent. In Codex / omp / Pi, invoke them as skills (`$devlyn:resolve`, `$devlyn:ideate`, `$devlyn:design-ui`); in Claude Code and Grok Build CLI they're slash commands (`/devlyn:resolve`). Run it again anytime to update. (`npx devlyn-cli -y` installs the Claude core non-interactively; `npx devlyn-cli agents <cli>` adds one agent later.)
 
 ---
 
@@ -39,7 +39,7 @@ devlyn-cli turns your AI coding agent into a hands-free development pipeline. Th
 ideate (optional)  →  resolve  →  ship
 ```
 
-Non-Claude agents (Codex / omp / Pi): when one of these is selected, the workflows install as that agent's skills. Use `$devlyn:ideate`, `$devlyn:resolve`, or `$devlyn:design-ui`; the `/devlyn:*` slash-command form is for Claude Code.
+Non-Claude agents (Codex / omp / Pi / Grok): when one of these is selected, the workflows install as that agent's skills. In Codex / omp / Pi, use `$devlyn:ideate`, `$devlyn:resolve`, or `$devlyn:design-ui`; in Grok, use `/devlyn:ideate`, `/devlyn:resolve`, or `/devlyn:design-ui`, the same slash-command form as Claude Code.
 
 ### Step 1 (optional) — Plan with `/devlyn:ideate`
 
@@ -107,9 +107,9 @@ devlyn separates three engine roles:
 
 - **Orchestrator** — the CLI you opened (Claude Code, Codex, or omp) that drives the conversation and loop. The contract is symmetric (`CLAUDE.md` ↔ `AGENTS.md`), so the same phase-gated pipeline runs whichever you launch; the file artifacts (spec, queue, state) carry over if you switch.
 - **Executor** — PLAN / IMPLEMENT / CLEANUP plus the primary VERIFY judge. Defaults to `claude`.
-- **Pair judge** — the first available *other* engine, for conditional VERIFY pair-JUDGE and risk probes.
+- **Pair judge** — the first available *other* engine, default for VERIFY and conditional for risk probes.
 
-`--engine claude` (default) is the canonical implementation surface for PLAN, IMPLEMENT, BUILD_GATE, and CLEANUP. VERIFY/JUDGE conditionally runs pair mode for verify-only runs, high-risk specs, risk probes, mechanical warnings, coverage gaps, or explicit `--pair-verify`.
+`--engine claude` (default) is the canonical implementation surface for PLAN, IMPLEMENT, BUILD_GATE, and CLEANUP. VERIFY/JUDGE runs pair mode by default when the OTHER engine is available.
 
 Pin roles durably with `/devlyn:engines` (no args shows the role table + detected engines; `executor <name>` / `pair <name>,...` / `clear` manage the pins, stored machine-local in `.devlyn/engines.json`). Pins fail closed: an unavailable pinned engine stops with `BLOCKED:<engine>-unavailable`, and a name with no `_shared/adapters/<name>.md` adapter stops with `BLOCKED:invalid-engine-config`. New engines plug in by shipping an adapter file — no skill changes.
 
@@ -119,7 +119,7 @@ Pin roles durably with `/devlyn:engines` (no args shows the role table + detecte
 /devlyn:resolve "fix the auth bug" --engine codex   # research-only
 ```
 
-If Codex or Claude is absent when explicitly selected or conditionally required, the harness stops with `BLOCKED:codex-unavailable` or `BLOCKED:claude-unavailable` and prints setup guidance. Use `--no-pair` only when intentionally accepting solo VERIFY; use `--no-risk-probes` only when intentionally disabling automatic high-risk probes.
+If Codex or Claude is absent when explicitly selected, or OTHER engine is absent under `--pair-verify`, the harness stops with `BLOCKED:<engine>-unavailable` and prints setup guidance. Automatic VERIFY absence is a reported solo route. Use `--no-pair` only when intentionally accepting solo VERIFY; use `--no-risk-probes` only when intentionally disabling automatic high-risk probes.
 
 ### Benchmark score runs
 
@@ -259,7 +259,7 @@ Selected during install. Run `npx devlyn-cli` again to add more.
 |---|---|
 | `playwright` | Playwright MCP — powers `/devlyn:resolve` BUILD_GATE browser tier (Chrome MCP → Playwright → curl fallback) |
 
-> `--engine codex` and conditional VERIFY pair mode use the local `codex` CLI binary, not MCP. Install from https://platform.openai.com/docs/codex, run the current Codex auth/login flow, verify `codex --version`, then rerun.
+> `--engine codex` and default-when-available VERIFY pair mode use the local `codex` CLI binary, not MCP. Install from https://platform.openai.com/docs/codex, run the current Codex auth/login flow, verify `codex --version`, then rerun.
 
 </details>
 

package/benchmark/auto-resolve/fixtures/SCHEMA.md

@@ -123,7 +123,7 @@ Machine-readable acceptance criteria used by both `run-fixture.sh` verification
 
 Fixtures with `metadata.json` `category: "high-risk"` must include at least
 one resolve risk-trigger term in `metadata.intent` or `spec.md`, matching the
-conditional pair/risk-probe triggers used by `/devlyn:resolve`: security/auth,
+conditional risk-probe triggers used by `/devlyn:resolve`: security/auth,
 money/pricing/tax/ledger, persistence/data mutation, idempotency/replay,
 API/webhook/signature, allocation/scheduling/inventory/rollback/transaction,
 priority, or output/response-shape contracts. This keeps future pair-evidence

package/benchmark/auto-resolve/scripts/pair_evidence_contract.py

@@ -10,6 +10,7 @@ from typing import Any
 
 ALLOWED_PAIR_ARMS = {"l2_risk_probes", "l2_gated"}
 CANONICAL_PAIR_TRIGGER_REASONS = {
+    "pair.default",
     "mode.verify-only",
     "mode.pair-verify",
     "complexity.high",

package/bin/devlyn.js

@@ -58,6 +58,19 @@ const CLI_TARGETS = {
     // 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')),
   },
+  grok: {
+    name: 'Grok Build CLI (xAI)',
+    instructionsFile: 'AGENTS.md',
+    baseInstructionsFile: 'AGENTS.md',
+    // Grok discovers same-format SKILL.md skills from ./.grok/skills >
+    // <repo_root>/.grok/skills > ~/.grok/skills > ~/.claude/skills
+    // (Claude-compatible); skills are slash-invocable in the Grok TUI.
+    skillsDir: path.join(os.homedir(), '.grok', 'skills'),
+    skillsToInstall: DEVLYN_CORE_SKILLS,
+    // Project-scoped only: machine-level ~/.grok must not auto-trigger a project
+    // AGENTS.md write via `npx devlyn-cli agents` in an unrelated repo.
+    detect: () => fs.existsSync(path.join(process.cwd(), '.grok')),
+  },
 };
 
 // Files removed in previous versions that should be cleaned up on upgrade
@@ -757,14 +770,37 @@ function installClaudeCore() {
   if (fs.existsSync(settingsPath)) {
     try {
       settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-    } catch {
-      settings = {};
+    } catch (error) {
+      throw new Error(`Cannot merge .claude/settings.json: ${error.message}`);
     }
   }
-  if (!settings.env) settings.env = {};
+  if (!settings || typeof settings !== 'object' || Array.isArray(settings)) {
+    throw new Error('Cannot merge .claude/settings.json: root must be a JSON object');
+  }
+  const hasOwnSetting = (key) => Object.prototype.hasOwnProperty.call(settings, key);
+  let settingsChanged = false;
+  if (!hasOwnSetting('env')) {
+    settings.env = {};
+    settingsChanged = true;
+  }
+  if (!settings.env || typeof settings.env !== 'object' || Array.isArray(settings.env)) {
+    throw new Error('Cannot merge .claude/settings.json: env must be a JSON object');
+  }
   // Auto-allow pipeline state directory and common git commands so resolve doesn't prompt
-  if (!settings.permissions) settings.permissions = {};
-  if (!settings.permissions.allow) settings.permissions.allow = [];
+  if (!hasOwnSetting('permissions')) {
+    settings.permissions = {};
+    settingsChanged = true;
+  }
+  if (!settings.permissions || typeof settings.permissions !== 'object' || Array.isArray(settings.permissions)) {
+    throw new Error('Cannot merge .claude/settings.json: permissions must be a JSON object');
+  }
+  if (!Object.prototype.hasOwnProperty.call(settings.permissions, 'allow')) {
+    settings.permissions.allow = [];
+    settingsChanged = true;
+  }
+  if (!Array.isArray(settings.permissions.allow)) {
+    throw new Error('Cannot merge .claude/settings.json: permissions.allow must be an array');
+  }
   const pipelinePermissions = [
     'Write(.devlyn/**)',
     'Edit(.devlyn/**)',
@@ -774,7 +810,6 @@ function installClaudeCore() {
     'Bash(git status *)',
     'Bash(git log *)',
   ];
-  let settingsChanged = false;
   for (const perm of pipelinePermissions) {
     if (!settings.permissions.allow.includes(perm)) {
       settings.permissions.allow.push(perm);
@@ -785,9 +820,35 @@ function installClaudeCore() {
     settings.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS = '1';
     settingsChanged = true;
   }
+  if (!hasOwnSetting('hooks')) {
+    settings.hooks = {};
+    settingsChanged = true;
+  }
+  if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) {
+    throw new Error('Cannot merge .claude/settings.json: hooks must be a JSON object');
+  }
+  if (!Object.prototype.hasOwnProperty.call(settings.hooks, 'Stop')) {
+    settings.hooks.Stop = [];
+    settingsChanged = true;
+  }
+  if (!Array.isArray(settings.hooks.Stop)) {
+    throw new Error('Cannot merge .claude/settings.json: hooks.Stop must be an array');
+  }
+  const stopHookCommand = 'python3 "$CLAUDE_PROJECT_DIR/.claude/skills/_shared/resolve-stop-hook.py"';
+  const stopHookInstalled = settings.hooks.Stop.some((entry) => (
+    entry && Array.isArray(entry.hooks) && entry.hooks.some((hook) => (
+      hook && hook.type === 'command' && hook.command === stopHookCommand
+    ))
+  ));
+  if (!stopHookInstalled) {
+    settings.hooks.Stop.push({
+      hooks: [{ type: 'command', command: stopHookCommand, timeout: 30 }],
+    });
+    settingsChanged = true;
+  }
   if (settingsChanged) {
     fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
-    log('  → settings.json (agent teams + pipeline permissions)', 'dim');
+    log('  → settings.json (agent teams + pipeline permissions + Stop hook)', 'dim');
   }
 
   // Configure global Claude Code settings (~/.claude/settings.json)

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

@@ -46,8 +46,8 @@ Keep each section to ≤ 8 lines. Adapters are deltas, not full prompts. If an a
 
 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).
+- **`## 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 or not certified for 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 or CLI backends with non-default invocation contracts: 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
 

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

@@ -0,0 +1,77 @@
+# Grok adapter
+
+## Role eligibility
+
+executor: no
+pair_judge: yes
+
+Certification status: the pair-judge seat is wired, isolated, reachable, and probe-capable, but not emission-certified; P-0079-B measured 4/6, and P-0079-F failed emission because a narration preamble was welded to output line 1; a durable `pair grok` pin remains gated on follow-up emission registration and the standing seat-fitness rule.
+
+## Invocation
+
+**Availability probe**: `command -v grok >/dev/null 2>&1`; record
+`grok --version` as evidence. The probe is necessary, not sufficient: auth or
+wrapper failures after it passes are the same fail-closed availability class as
+a failed probe (`BLOCKED:grok-unavailable` for an explicit route; an automatic
+escalation remains a reported solo skip).
+
+```bash
+# $ISO_HOME = ephemeral dir seeded with a copied auth.json + agent_id, and a
+#   config.toml containing:
+#   [plugins]
+#   disabled = ["telegram", "vercel"]
+#   enabled = []
+#
+#   [skills]
+#   ignore = ["~/.agents", "~/.claude", "~/.cursor"]
+# $NEUTRAL  = empty dir outside any git repo
+# $REPO     = absolute repo root (redirects MUST be absolute — cwd is $NEUTRAL)
+cd "$NEUTRAL"
+GROK_HOME="$ISO_HOME" \
+GROK_CLAUDE_MCPS_ENABLED=false GROK_CURSOR_MCPS_ENABLED=false \
+GROK_CLAUDE_SKILLS_ENABLED=false GROK_CURSOR_SKILLS_ENABLED=false \
+GROK_CLAUDE_HOOKS_ENABLED=false GROK_CURSOR_HOOKS_ENABLED=false \
+GROK_CLAUDE_AGENTS_ENABLED=false GROK_CLAUDE_RULES_ENABLED=false \
+GROK_MEMORY=0 \
+python3 "$DEVLYN_SHARED_DIR/run-bounded.py" 600 -- grok -p "<judge prompt>" \
+  --permission-mode dontAsk --no-memory \
+  --tools "read_file,grep,list_dir,run_terminal_cmd" \
+  --disallowed-tools "Agent,use_tool,search_tool" \
+  --allow 'Bash(<repo probe command family>)' \
+  --reasoning-effort medium \
+  > "$REPO/.devlyn/grok-judge.stdout" 2> "$REPO/.devlyn/grok-judge.stderr"
+```
+
+Copy `auth.json` into `$ISO_HOME` for every run and seed its `config.toml` with
+the shown `[plugins]` and `[skills] ignore` entries.
+`$NEUTRAL` and `$ISO_HOME` must be on paths that do not embed a project or repo identifier.
+`--permission-mode plan` is forbidden headless because it silently blocks
+all tools and returns an empty review; `--always-approve` is banned because it
+auto-approves writes. `--tools` and `--disallowed-tools` are headless-only (the
+TUI warns and ignores them); when both are present, the disallow list wins and
+removes tools entirely rather than merely gating execution.
+
+The `--allow` rule must cover the full probe-command family the judge may need,
+and the judge prompt must name the exact permitted command(s). Derive the prompt
+anchor and allow-list string identically from one source, in this precedence:
+the solo-headroom hypothesis's backticked observable command when present;
+otherwise the backticked commands in the spec's `## Verification` bullets;
+otherwise the repo's existing test/CLI runner. If none exists, the probe
+obligation does not arise and a static review is correct for that spec.
+The documented `Bash(<command>)` form matches the exact command or its prefix;
+the trailing ` *` form fails a no-argument command.
+
+Grok's deny semantics are not Claude-parity: an out-of-allowlist command silently
+truncates the review at exit 0. Treat the resulting collector rejection as
+`BLOCKED` for `verify.pair.emission-contract`, never PASS. After a non-timeout
+spawn, run:
+
+```bash
+python3 "$DEVLYN_SHARED_DIR/collect-codex-findings.py" \
+  --devlyn-dir "$REPO/.devlyn" \
+  --stdout-file grok-judge.stdout \
+  --summary-out grok-judge.summary.json
+```
+
+On exit 124, write `.devlyn/verify.pair.timeout.json` with
+`{"engine": "grok", "budget_seconds": 600}` before merge.

package/config/skills/_shared/archive_run.py

@@ -27,7 +27,19 @@ PER_RUN_PATTERNS = (
     "*.findings.jsonl",
     "*.log.md",
     "fix-batch.round-*.json",
+    "closure-durability.round-*.json",
+    "resolve-stop-hook.*.json",
     "criteria.generated.md",
+    "goal.raw.txt",
+    "surface-close.input.patch",
+    "surface-close.prompt",
+    "surface-close.output.json",
+    "surface-close.stdout",
+    # Mutation workers retain the exact session JSONL identified by their
+    # dispatch receipt. Round-scoped root files avoid engine-global scans.
+    "implement.worker-session.*.jsonl",
+    "surface-close.worker-session.*.jsonl",
+    "cleanup.worker-session.*.jsonl",
     "risk-probes.jsonl",
     # Probe scripts referenced by risk-probes.jsonl are archived by
     # move_probe_scripts() to preserve probes/<file> layout.
@@ -159,6 +171,15 @@ def self_test() -> int:
         )
         for name in (
             "risk-probes.jsonl",
+            "goal.raw.txt",
+            "surface-close.input.patch",
+            "surface-close.prompt",
+            "surface-close.output.json",
+            "surface-close.stdout",
+            "implement.worker-session.0.jsonl",
+            "surface-close.worker-session.0.jsonl",
+            "cleanup.worker-session.1.jsonl",
+            "resolve-stop-hook.run-1.123.456.json",
             "verify.pair.findings.jsonl",
             "verify-merge.summary.json",
             "codex-judge.stdout",
@@ -169,13 +190,24 @@ def self_test() -> int:
             (devlyn / name).write_text("{}\n", encoding="utf-8")
         (devlyn / "probes").mkdir()
         (devlyn / "probes" / "P1.py").write_text("print('probe')\n", encoding="utf-8")
+        global_rollout = devlyn / "engine-sessions" / "rollout-global.jsonl"
+        global_rollout.parent.mkdir()
+        global_rollout.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 >= 9, moved
+        assert moved >= 12, moved
         for name in (
             "pipeline.state.json",
             "risk-probes.jsonl",
+            "goal.raw.txt",
+            "surface-close.input.patch",
+            "surface-close.prompt",
+            "surface-close.output.json",
+            "surface-close.stdout",
+            "implement.worker-session.0.jsonl",
+            "surface-close.worker-session.0.jsonl",
+            "cleanup.worker-session.1.jsonl",
             "probes/P1.py",
             "verify.pair.findings.jsonl",
             "verify-merge.summary.json",
@@ -185,6 +217,8 @@ def self_test() -> int:
             "claude-judge.stderr",
         ):
             assert (devlyn / "runs" / run_id / name).is_file(), name
+        assert global_rollout.is_file(), "engine-global session files must stay untouched"
+        assert not (devlyn / "runs" / run_id / global_rollout.name).exists()
 
         bad = pathlib.Path(tmp) / "bad"
         bad.mkdir()

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

@@ -61,9 +61,7 @@ def collect(stdout_path: pathlib.Path) -> tuple[list[dict[str, Any]], dict[str,
             if severity not in FINDING_SEVERITIES:
                 raise SystemExit(f"error: finding missing valid severity at {stdout_path}:{line_no}")
             findings.append(item)
-    if not findings and summary is None:
-        raise SystemExit("error: Codex pair-JUDGE stdout contained no JSONL findings or PASS line")
-    if summary and summary.get("verdict") in {"NEEDS_WORK", "FAIL", "BLOCKED"} and not findings:
+    if not findings and (summary is None or summary.get("verdict") != "PASS"):
         raise SystemExit("error: non-PASS SUMMARY without JSONL findings")
     return findings, summary
 
@@ -90,13 +88,20 @@ def self_test() -> int:
             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)
-        except SystemExit as exc:
-            assert "no JSONL findings" in str(exc)
-        else:
-            raise AssertionError("empty Codex stdout must not normalize to PASS")
+        rejection_cases = (
+            ("", "no SUMMARY line"),
+            ('# SUMMARY {}\n', "empty SUMMARY object"),
+            ('# SUMMARY {"verdict":"pass"}\n', "lowercase pass"),
+            ('# SUMMARY {"verdict":"UNKNOWN"}\n', "unknown verdict"),
+        )
+        for text, label in rejection_cases:
+            stdout_path.write_text(text, encoding="utf-8")
+            try:
+                collect(stdout_path)
+            except SystemExit as exc:
+                assert str(exc) == "error: non-PASS SUMMARY without JSONL findings"
+            else:
+                raise AssertionError(f"{label} must not normalize to PASS")
     return 0
 
 

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

@@ -17,12 +17,13 @@ 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 "")
+TARGETS=(claude codex grok omp pi)
+KINDS=(cli-engine cli-engine cli-engine cli-engine orchestrator-only)
+BINARIES=(claude codex grok omp "")
 INSTALL_HINTS=(
   "see https://docs.anthropic.com/en/docs/claude-code"
   "npm install -g @openai/codex"
+  "see https://docs.x.ai/build/overview (install + browser auth)"
   "brew install can1357/tap/omp"
   ""
 )
@@ -88,6 +89,8 @@ for i in "${!TARGETS[@]}"; do
       ;;
   esac
 
+  [ "$target" = 'grok' ] && note='not emission-certified; BLOCKED pair source'
+
   printf '%-8s %-17s %-8s %-8s %-14s %-12s %s\n' \
     "$target" "$kind" "$binary" "$adapter" "$role" "$pin_eligible" "$note"
 done

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

@@ -4,12 +4,12 @@ Used by `/devlyn:resolve` and `/devlyn:ideate`. One shared availability rule so
 
 ## Rule
 
-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.
+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 the default VERIFY-pair route and conditional risk-probe requirements before the phase that needs the OTHER engine.
 
 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.
+- **Automatic routes** — high-risk risk-probes remain conditional; VERIFY pair-JUDGE is selected by default unless `--no-pair` was passed. Both require an available OTHER engine. If it is absent, proceed solo and report the skipped route and reason. This is route selection, not a fallback.
 
 ## Role resolution
 
@@ -32,11 +32,11 @@ When a run or phase requires engine `<name>` (claude, codex, omp, or any adapter
 
 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 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.
+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 invokes the OTHER engine by default when available unless `--no-pair` was passed. `/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
 
-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:
+When an engine required by the selected route or default VERIFY pair route is absent, the final user-facing report/summary shows the requested route, the missing engine, and setup steps:
 
 ```
 Engine: claude + codex pair required
@@ -48,4 +48,11 @@ Do not report a downgraded successful run when a required engine is missing.
 
 ## Canonical cross-engine invocations
 
-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).
+After the availability check passes, Codex keeps the monitored `codex-monitored.sh`
+path; every other resolved OTHER engine follows `_shared/adapters/<name>.md`
+`## Invocation`. Capture `.devlyn/<name>-judge.stdout`, then normalize it with
+`collect-codex-findings.py --devlyn-dir "<abs repo>/.devlyn" --stdout-file
+<name>-judge.stdout`. A non-zero collector exit writes no canonical findings:
+the pair source is `BLOCKED` for `verify.pair.emission-contract`, and unparsed
+stdout remains diagnostic-only rather than being merged. On exit 124, the
+timeout marker's `engine` field is the resolved `<name>`.