devlyn-cli 2.2.2 → 2.3.1

package/config/skills/devlyn:resolve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: devlyn:resolve
-description: Hands-free pipeline for any coding task — bug fix, feature, refactor, debug, modify, PR review. Free-form goal or formal spec input. Plan → Implement → Build-gate → Cleanup → Verify (fresh subagent, findings-only). Mechanical-first verification; pair-mode is gated in Verify. Use when the user says "resolve this", "fix this", "implement this", "refactor this", "debug this", "review this PR", or wants hands-off completion.
+description: Hands-free pipeline for any coding task — bug fix, feature, refactor, debug, modify, PR review. Free-form goal or formal spec input. Plan → Implement → Build-gate → Cleanup → Verify (fresh subagent, findings-only). Mechanical-first verification; pair-mode is conditional-default in Verify. Use when the user says "resolve this", "fix this", "implement this", "refactor this", "debug this", "review this PR", or wants hands-off completion.
 ---
 
 Orchestrator for the 2-skill harness pipeline. One subagent per phase; file-based handoff via `.devlyn/pipeline.state.json`. VERIFY spawns a fresh-context subagent so independence is structural — not advisory.
@@ -17,7 +17,7 @@ Long-horizon agentic work; context auto-compacts. State lives in `.devlyn/pipeli
 Hands-free. Measured by how far we get without human intervention.
 
 1. Do not prompt the user mid-pipeline. When tempted to ask, pick the safe default, proceed, and log it in the final report.
-2. Codex availability: on `--engine auto`/`codex`, follow `_shared/engine-preflight.md`. On failure, silently fall back to Claude and log `engine downgraded: codex-unavailable` in the final report.
+2. Engine availability: follow `_shared/engine-preflight.md`. When a selected or conditionally-required engine is unavailable, fail closed with `BLOCKED:<engine>-unavailable` and setup guidance; do not convert a pair-required or explicitly requested engine into a solo run.
 3. Phases run in declared order. No extra phases.
 4. Orchestrator does not write code. It parses input, spawns phases, reads state, branches on verdicts, emits the report.
 5. Continue by default. Halt only on (a) unrecoverable subagent failure, (b) IMPLEMENT producing zero code changes, (c) BUILD_GATE or VERIFY fix-loop exhausting `max_rounds`.
@@ -32,7 +32,7 @@ Each phase routes to an engine and prepends the per-engine adapter header from `
 
 - Claude phases: spawn `Agent` (`mode: "bypassPermissions"`); prompt = adapter-header + canonical-body + task-context.
 - Codex phases: shell out via `bash _shared/codex-monitored.sh` with the same compounded prompt. The wrapper closes stdin and emits a heartbeat. No MCP.
-- Default engine: Claude. `--engine codex` routes IMPLEMENT to Codex; orchestration stays Claude. Pair-mode (only in VERIFY/JUDGE) selects a different engine for the fresh subagent than IMPLEMENT used.
+- Default engine: Claude for PLAN / IMPLEMENT / BUILD_GATE / CLEANUP. `--engine codex` routes IMPLEMENT to Codex; orchestration stays Claude. Pair-mode is conditional-default in VERIFY/JUDGE and selects the OTHER engine for the fresh subagent when the trigger policy fires.
 - Multi-LLM evolution: when a new model adapter ships in `_shared/adapters/`, that engine becomes selectable via `--engine <model>` without further skill changes (NORTH-STAR.md "Multi-LLM evolution direction").
 </engine_routing>
 
@@ -40,7 +40,7 @@ Each phase routes to an engine and prepends the per-engine adapter header from `
 Three input shapes:
 
 1. **Free-form**: `/devlyn:resolve "fix the login bug"`. PHASE 0 runs the complexity classifier and either proceeds with an internal mini-spec (trivial), drafts focused questions for in-prompt resolution (medium), or escalates to `/devlyn:ideate` (large/ambiguous). No mid-pipeline prompts in any branch.
-2. **Spec**: `/devlyn:resolve --spec docs/roadmap/phase-N/X.md`. Spec is read-only. Verification commands pre-staged from spec's `## Verification` block.
+2. **Spec**: `/devlyn:resolve --spec docs/roadmap/phase-N/X.md`. Spec is read-only. Stage verification commands from sibling `spec.expected.json`; if absent, use the legacy `## Verification` JSON block.
 3. **Verify-only**: `/devlyn:resolve --verify-only <diff-or-PR-ref> --spec <path>`. Skips PHASE 1-4. Runs PHASE 5 (VERIFY) on the supplied diff against the spec.
 </modes>
 
@@ -59,20 +59,26 @@ Once `state.implement_passed_sha` is non-null (PHASE 2 returned and produced a d
    - `--spec <path>` — switches to spec mode.
    - `--verify-only <ref>` — switches to verify-only mode. Requires `--spec`.
    - `--pair-verify` — force pair-mode JUDGE in PHASE 5 even when not auto-triggered.
+   - `--no-pair` — disable conditional VERIFY pair-JUDGE for this run. Record `pair_trigger.skipped_reason: "user_no_pair"` whenever a trigger would otherwise fire.
    - `--risk-probes` — insert PHASE 1.5 cross-engine probe derivation. The OTHER engine converts visible `## Verification` bullets into bounded executable probes before IMPLEMENT; BUILD_GATE and VERIFY replay them mechanically.
+   - `--no-risk-probes` — disable automatic high-risk risk probes. Explicit `--risk-probes` wins over `--no-risk-probes`.
    - `--bypass <phase>[,...]` — skip specific phases. Valid: `build-gate`, `cleanup`. PLAN, IMPLEMENT, VERIFY are non-bypassable.
    - `--perf` — opt in to per-phase timing.
 
-2. Engine pre-flight: follow `_shared/engine-preflight.md`. The downgrade banner surfaces in the final report.
+2. Engine pre-flight: follow `_shared/engine-preflight.md`. If a required engine is unavailable, halt with a BLOCKED verdict and setup instructions instead of downgrading.
 
-3. Initialize `.devlyn/pipeline.state.json` per `references/state-schema.md`. Set `state.run_id`, `started_at`, `engine`, `base_ref.{branch, sha}`, `rounds.{max_rounds, global: 0}`, `bypasses`, empty `phases`, empty `criteria`.
+   `--pair-verify` and `--no-pair` are mutually exclusive; if both are present, stop with `BLOCKED:invalid-flags`.
+
+3. Initialize `.devlyn/pipeline.state.json` per `references/state-schema.md`. Set `state.run_id`, `started_at`, `engine`, `pair_verify: true` only when `--pair-verify` was passed and `false` otherwise, `base_ref.{branch, sha}`, `rounds.{max_rounds, global: 0}`, `bypasses`, empty `phases`, empty `criteria`, and `risk_profile: { high_risk: false, reasons: [], risk_probes_enabled: false, pair_default_enabled: true }`. `risk_profile` is strict typed state: keep it an object, keep the three flags as JSON booleans, and keep `reasons` as a string array; never serialize booleans as strings.
 
 4. **Mode-specific init**:
-   - **Free-form**: read `references/free-form-mode.md`. Run the complexity classifier deterministically (rules over keyword density / file count / spec-shape signals). Set `state.complexity ∈ {trivial, medium, large}`. Trivial: write internal mini-spec to `.devlyn/criteria.generated.md` and proceed. Medium: synthesize a minimal spec from the goal + add 1-2 context anchors from the codebase, write to `.devlyn/criteria.generated.md`, proceed. Large: log `recommend: /devlyn:ideate first` in the final report and either halt (default) or proceed with assumed defaults if `--continue-on-large` flag set.
-   - **Spec**: validate spec exists + `## Verification` block parses (run `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` to validate carrier shape). Compute `state.source.spec_sha256`. Stage `.devlyn/spec-verify.json` from the spec's verification block.
+   - **Free-form**: read `references/free-form-mode.md`. Run the complexity classifier deterministically (rules over keyword density / file count / spec-shape signals, plus pair-evidence intent). Set `state.complexity ∈ {trivial, medium, large}`. Trivial: write internal mini-spec to `.devlyn/criteria.generated.md` and proceed. Medium: synthesize a minimal spec from the goal + add 1-2 context anchors from the codebase, write to `.devlyn/criteria.generated.md`, proceed. Every free-form branch that writes criteria must set `state.source.type = "generated"`, `state.source.criteria_path = ".devlyn/criteria.generated.md"`, and `state.source.criteria_sha256` from the raw file bytes. Large: log `recommend: /devlyn:ideate first` in the final report and either halt (default) or proceed with assumed defaults if `--continue-on-large` flag set, except pair-evidence intent without an actionable solo-headroom hypothesis must halt with `BLOCKED:solo-headroom-hypothesis-required`, and unmeasured pair-candidate intent without solo ceiling avoidance must halt with `BLOCKED:solo-ceiling-avoidance-required`.
+   - **Spec**: validate spec exists. If sibling `spec.expected.json` exists, run `--check-expected <expected-path>` to validate both the expected contract, sibling spec `complexity` frontmatter, and any present actionable solo-headroom hypothesis; if the spec has a solo-headroom hypothesis, its observable command must match `spec.expected.json.verification_commands[].cmd`. Then stage `.devlyn/spec-verify.json` from `verification_commands`. Otherwise run `--check <spec-path>` to validate the legacy inline carrier plus supported `complexity` frontmatter and any present actionable solo-headroom hypothesis; if the spec uses an inline `## Verification` JSON carrier, any solo-headroom hypothesis command must match that carrier's `verification_commands[].cmd`. Then stage from the legacy inline carrier. Compute `state.source.spec_sha256`.
    - **Verify-only**: skip to PHASE 5 with `state.source.spec_path` set, the supplied diff captured at `.devlyn/external-diff.patch`.
 
-5. Announce one line: `resolve starting — run <run_id> — engine <engine> — mode <mode> — complexity <complexity-or-na>`.
+5. Compute `state.risk_profile` from the user goal plus spec/criteria text. Mark `high_risk: true` when the work touches any of: auth/authz, permissions, security, token/session, payment/money/billing/invoice/pricing/tax/ledger, persistence/data mutation/deletion/migration, idempotency/replay/duplicate, API/webhook/raw-body/signature, allocation/scheduling/inventory/rollback/transaction, or explicit error-priority/output-shape contracts. If high-risk and `--no-risk-probes` is absent, set `risk_probes_enabled: true`; explicit `--risk-probes` also sets it true. If `--no-pair` is present, set `pair_default_enabled: false`. Add concise string reasons for the classification, but do not use reasons as substitutes for the boolean fields.
+
+6. Announce one line: `resolve starting — run <run_id> — engine <engine> — mode <mode> — complexity <complexity-or-na> — pair <conditional|disabled> — risk_probes <on|off>`.
 
 ## PHASE 1: PLAN
 
@@ -90,8 +96,11 @@ After return:
 
 ## PHASE 1.5: RISK_PROBES
 
-Skip unless `--risk-probes` is set. This phase is findings-as-executable-checks,
-not a second plan and not debate.
+Skip unless `--risk-probes` is set OR `state.risk_profile.risk_probes_enabled`
+is true. This phase is findings-as-executable-checks, not a second plan and not
+debate. If this phase is required and the OTHER engine is unavailable, halt with
+`BLOCKED:codex-unavailable` or `BLOCKED:claude-unavailable` plus setup guidance;
+do not silently continue without probes.
 
 Engine: OTHER engine from PHASE 2's selected IMPLEMENT engine. Prompt body:
 `references/phases/probe-derive.md`.
@@ -108,14 +117,41 @@ a JSON object keyed by tag, with marker arrays as values; a top-level array or
 tag-only probe is malformed. `ordering_inversion` must include
 `input_order_would_choose_wrong_winner` and `asserts_processing_order_result`;
 `prior_consumption` must include `same_resource_consumed_first` and
-`later_entity_fails_or_reroutes`; `stdout_stderr_contract` and `shape_contract`
-do not require marker strings. Cart/pricing success probes should use
+`later_entity_fails_or_reroutes`; `stdout_stderr_contract` must include
+`asserts_named_stream_output`; `error_contract` must include
+`asserts_error_payload_or_stderr` and `asserts_nonzero_or_exit_2`.
+`http_error_contract` must include `asserts_http_error_status` and
+`asserts_error_payload_body`.
+`auth_signature_contract` must include `asserts_signature_over_exact_bytes` and
+`asserts_tampered_or_missing_signature_rejected`; `idempotency_replay` must
+include `first_delivery_then_duplicate` and
+`duplicate_id_rejected_regardless_of_body`; `concurrent_state_consistency` must
+include `overlapping_mutations_exercised`,
+`all_successful_responses_reflected`, and `distinct_identifiers_asserted`;
+`atomic_batch_state` must include `mixed_valid_invalid_batch`,
+`asserts_store_unchanged_after_failure`, and
+`asserts_success_order_and_distinct_ids`.
+When visible text names exact keys, fields, row shapes, JSON objects, response
+bodies, stdout/stderr objects, or exact error bodies, `shape_contract` must
+include `uses_visible_input_key_names`, `asserts_visible_output_key_names`, and
+`asserts_no_unexpected_output_keys`; exact JSON error objects/bodies must also
+include `asserts_exact_error_object`. Cart/pricing success probes should use
 `shape_contract` unless they satisfy the `ordering_inversion` markers. The probe
 command must not reference external network URLs; use only worktree-local or
 localhost resources.
 For high-complexity specs with multiple behavior bullets, at least one probe
 must be compound: it must exercise two or more visible verification bullets in a
 single command. Empty output is invalid when `--risk-probes` is set.
+When the visible spec includes a solo-headroom hypothesis, the first probe must
+exercise that hypothesis with the visible command/input shape and full
+observable assertion; its `cmd` must contain the hypothesis's backticked
+observable command, and its `derived_from` must reference the hypothesis bullet,
+so deterministic validation can prove the probe targets the stated expected
+`solo_claude` miss. Otherwise the probe set is too weak for pair-evidence work.
+The same actionable solo-headroom hypothesis is a VERIFY pair-trigger reason,
+so a candidate spec that explicitly predicts a `solo_claude` miss cannot finish
+on solo VERIFY alone unless `--no-pair` was explicitly set or an earlier
+verdict-binding blocker already decides the run.
 
 State write: `phases.probe_derive.{started_at, verdict, completed_at, duration_ms, artifacts}`.
 
@@ -123,7 +159,9 @@ Invocation contract when OTHER engine is Codex:
 
 - Invoke Codex only through the monitored wrapper path in `CODEX_MONITORED_PATH`,
   or `.claude/skills/_shared/codex-monitored.sh` when the env var is absent:
-  `bash "$CODEX_MONITORED_PATH" -C "$PWD" --full-auto -c model_reasoning_effort=high "<probe prompt>"`.
+  `CODEX_MONITORED_ISOLATED=1 bash "$CODEX_MONITORED_PATH" -C "$PWD" --full-auto -c model_reasoning_effort=high "<probe prompt>"`.
+  Isolation keeps user config, AGENTS.md, pyx-memory, hooks, and project rules
+  from adding hidden context, tool calls, or transcript side effects.
 - Do not run `codex`, `codex exec`, `/Users/.../codex`, or a plugin-provided
   Codex binary directly. A raw Codex child can outlive the phase and makes the
   benchmark run invalid even if `.devlyn/risk-probes.jsonl` is written.
@@ -159,8 +197,8 @@ Skip in verify-only mode OR when `build-gate` in `state.bypasses`. Deterministic
 Spawn Claude `Agent` (`mode: "bypassPermissions"`) with prompt body `references/phases/build-gate.md`. The agent:
 1. Detects language/framework via project files (`package.json`, `pyproject.toml`, etc.).
 2. Runs language-specific gates (tsc / lint / test).
-3. Always runs `python3 .claude/skills/_shared/spec-verify-check.py --include-risk-probes` (verification_commands literal-match plus `.devlyn/risk-probes.jsonl` when present).
-4. If `spec.expected.json.browser_flows` declared OR diff touches web-surface files: invokes the browser runner (Chrome MCP → Playwright → curl tier as available).
+3. Always runs `python3 .claude/skills/_shared/spec-verify-check.py --include-risk-probes` (verification_commands literal-match plus `.devlyn/risk-probes.jsonl` when present). If `state.risk_profile.risk_probes_enabled == true`, the script requires `.devlyn/risk-probes.jsonl`; a missing file is a CRITICAL mechanical blocker, not a silent solo run.
+4. If diff touches web-surface files: run the browser tier with the repo's available toolchain (for example Playwright or curl).
 5. Emits `.devlyn/build_gate.findings.jsonl` + `.devlyn/build_gate.log.md`.
 
 State write: `phases.build_gate.{started_at, verdict, completed_at, duration_ms, artifacts}`.
@@ -192,25 +230,39 @@ Independent quality layer. **Spawned with empty conversation context** — no ca
 
 Two sub-phases:
 
-1. **MECHANICAL** (deterministic): re-run `python3 .claude/skills/_shared/spec-verify-check.py --include-risk-probes` against the post-CLEANUP code (independent of BUILD_GATE's earlier run). Re-scan `spec.expected.json.forbidden_patterns` against the diff. Re-check `required_files` and `forbidden_files`. Emit `.devlyn/verify-mechanical.findings.jsonl`.
+1. **MECHANICAL** (deterministic): re-run `SPEC_VERIFY_PHASE=verify_mechanical SPEC_VERIFY_FINDINGS_FILE=verify-mechanical.findings.jsonl SPEC_VERIFY_FINDING_PREFIX=VERIFY-MECH python3 .claude/skills/_shared/spec-verify-check.py --include-risk-probes` against the post-CLEANUP code (independent of BUILD_GATE's earlier run). If `state.risk_profile.risk_probes_enabled == true`, missing `.devlyn/risk-probes.jsonl` is a CRITICAL mechanical blocker. This emits `.devlyn/verify-mechanical.findings.jsonl` for `verify-merge-findings.py`.
 
-2. **JUDGE** (fresh-context Agent): grade the diff against the spec on rubric axes (spec compliance, scope, quality, consistency). Split each Requirement into binding clauses and trace code-order counterexamples; a passing verifier proves only the case it exercises, not neighboring `once` / `regardless` / `duplicate` / auth-order / rollback invariants. Respect scope qualifiers such as `inside a warehouse`, `per resource`, `for this line`, and `after validation`; do not widen a scoped clause into a global invariant, and compose multiple ordering rules in the stated order. For stateful flows, explicitly trace failed-operation rollback and the next entity's state before hunting broader edge cases. For high-complexity specs, construct at least one interaction counterexample that combines ordering/priority with failure handling and state mutation, then execute at least one such scenario through the repo's existing CLI/API/test runner without leaving tracked files behind; one-axis examples and pure mental tracing are insufficient. Default engine = same as IMPLEMENT (solo). Pair-mode (cross-model JUDGE) is eligible only when MECHANICAL has no HIGH/CRITICAL findings; deterministic blockers already decide the verdict and route to the fix loop. Pair-mode fires when eligible and:
+2. **JUDGE** (fresh-context Agent): grade the diff against the spec on rubric axes (spec compliance, scope, quality, consistency). Split each Requirement into binding clauses and trace code-order counterexamples; a passing verifier proves only the case it exercises, not neighboring `once` / `regardless` / `duplicate` / auth-order / rollback invariants. Respect scope qualifiers such as `inside a warehouse`, `per resource`, `for this line`, and `after validation`; do not widen a scoped clause into a global invariant, and compose multiple ordering rules in the stated order. For stateful flows, explicitly trace failed-operation rollback and the next entity's state before hunting broader edge cases. For high-complexity specs, construct at least one interaction counterexample that combines ordering/priority with failure handling and state mutation, then execute at least one such scenario through the repo's existing CLI/API/test runner without leaving tracked files behind; one-axis examples and pure mental tracing are insufficient. Default engine = same as IMPLEMENT (solo). Pair-mode (cross-model JUDGE) is eligible only after MECHANICAL and the primary JUDGE have no verdict-binding findings; deterministic blockers and primary JUDGE blockers already decide the verdict and route to the fix loop. Pair-mode fires when eligible and:
    - `--pair-verify` flag set, OR
-   - spec frontmatter has `complexity: high`, OR `state.complexity` is `"high"` or `"large"`, OR
-   - MECHANICAL emits findings flagged `severity: warning` (not disqualifier — those route to fix loop directly), OR
+   - `state.mode == "verify-only"`, OR
+   - `state.risk_profile.high_risk == true`, OR
+   - `.devlyn/risk-probes.jsonl` exists or `state.risk_profile.risk_probes_enabled == true`, OR
+   - spec frontmatter has `complexity: high` (legacy/external spec `complexity: large` is accepted for compatibility; new specs use `high`), OR current free-form `state.complexity` is `"large"` (legacy `"high"` state is accepted only for archived runs), OR
+   - MECHANICAL or the primary JUDGE emits findings flagged `severity: warning` (not verdict-binding — those route to fix loop directly), OR
    - `state.verify.coverage_failed == true` (judge could not exercise a required spec axis from available evidence).
 
-Before spawning JUDGE, compute `pair_trigger = { eligible, reasons[] }` and write it into `state.phases.verify`. If `eligible == true` and `reasons` is non-empty, you MUST spawn the second OTHER-engine judge. Skipping that second judge is a VERIFY contract violation, not a discretion call.
+After MECHANICAL and the primary JUDGE finish, compute `pair_trigger = { eligible, reasons[], skipped_reason }`, write it into `state.phases.verify`, and then spawn the second OTHER-engine judge when eligible. If `eligible == true`, `reasons` must be non-empty, include every applicable canonical reason, and every reason must be one of these canonical values: `mode.verify-only`, `mode.pair-verify`, `complexity.high`, `complexity.large`, `spec.complexity.high`, `spec.complexity.large`, `spec.solo_headroom_hypothesis`, `risk.high`, `risk_probes.enabled`, `risk_probes.present`, `coverage.failed`, `mechanical.warning`, or `judge.warning`; `skipped_reason` must be null; and you MUST spawn the second OTHER-engine judge. If `eligible == false`, `reasons` must be empty and `skipped_reason` must be a string or null. Contradictory, incomplete, or unknown trigger state is a VERIFY contract violation, not advisory metadata; `verify-merge-findings.py` blocks malformed trigger state. Pair reasons derive `risk.high` and `risk_probes.enabled` from `state.risk_profile`; malformed `risk_profile` is also a VERIFY contract violation because it can hide a required pair decision.
 
 The `--engine` flag never suppresses this rule. Explicit `--engine claude`
 means "Claude is the primary judge"; it does not mean "do not run Codex as the
 second pair judge." The only valid skip reasons after a non-empty eligible
-trigger are deterministic MECHANICAL HIGH/CRITICAL blockers or Codex
-unavailability proven by the invocation layer.
+trigger are deterministic MECHANICAL HIGH/CRITICAL blockers or an explicit
+`--no-pair`. Engine unavailability is a `BLOCKED:<engine>-unavailable` verdict,
+not a skip reason.
+
+Pair-mode JUDGE: spawn a second Agent with the OTHER engine's adapter; the second judge is a bounded adversarial complement, not a duplicate broad audit. The primary judge owns broad coverage; pair-JUDGE targets the two highest-risk explicit `## Verification` bullets that cross state mutation, all-or-nothing rollback, ordering, idempotency, auth, or error-priority clauses. If the spec includes a solo-headroom hypothesis, one of those targeted probes must exercise that hypothesis with the visible command/input shape and full externally visible result, using the hypothesis's backticked observable command as its command anchor before adding bounded input variations. It must not read `.claude/skills`, `.codex/skills`, `CLAUDE.md`, `AGENTS.md`, or other harness docs unless the orchestrator pasted a specific excerpt into the prompt. It may use only the spec, diff, implementation files, tests, and the repo's existing CLI/API/test runner. It may execute at most two targeted probes before first output, and each probe must compare the full externally visible result (exit/stdout/stderr plus full parsed output object, including accepted/scheduled rows, rejected rows, and remaining state when present), not just a single property. When the spec names exact keys, row shapes, JSON object shape, or an exact error body, pair-JUDGE must compare parsed key sets/deep equality so aliased keys, missing keys, and extra keys are verdict-binding failures, and it must construct inputs with the spec's visible key names. For priority/stateful specs, at least one probe must include an earlier input entity that would succeed under input-order processing, a later higher-priority entity that consumes or blocks the critical resource, and a failure/blocked/rollback edge that determines a later entity's state. For cart/pricing specs where visible verification combines duplicate items, line promotions, tax, coupon, and shipping, the success-path probe must include interleaved duplicates plus taxable and non-taxable items and assert full output rows. Scope qualifiers are binding: pair-JUDGE must not reinterpret `inside a warehouse`, `per resource`, or line-scoped rules as global rules. When both priority ordering and rollback/blocked-interval behavior appear in the spec, this dominance-loss probe is mandatory and comes before any other probe: an earlier lower-priority entity that would succeed alone or under input-order processing must lose because a later higher-priority entity is processed first; a failed/blocked middle entity must not corrupt later state; and the assertion must cover complete accepted/scheduled and rejected output ordering. It must stop and emit JSONL immediately on the first verdict-binding finding, and must emit PASS immediately if both probes plus static scope/dependency checks pass. Both judgments merge with the rule "any HIGH/CRITICAL finding either model surfaces is verdict-binding; high-confidence MEDIUM findings are also verdict-binding when they identify a concrete behavioral regression against the spec, public contract, or existing test contract." Cross-model disagreement on advisory lower-severity findings is logged but does not change the verdict. If MECHANICAL or the primary JUDGE has a verdict-binding finding, skip the second judge and record `pair_judge: null`; the fix loop needs the blocker, not duplicate review.
+
+If pair-mode is triggered and the OTHER engine is unavailable, do not downgrade
+or skip the required judge. Set VERIFY to `BLOCKED:<engine>-unavailable`, preserve the
+failed availability check evidence, and print setup guidance:
 
-Pair-mode JUDGE: spawn a second Agent with the OTHER engine's adapter; the second judge is a bounded adversarial complement, not a duplicate broad audit. The primary judge owns broad coverage; pair-JUDGE targets the two highest-risk explicit `## Verification` bullets that cross state mutation, all-or-nothing rollback, ordering, idempotency, auth, or error-priority clauses. It must not read `.claude/skills`, `.codex/skills`, `CLAUDE.md`, `AGENTS.md`, or other harness docs unless the orchestrator pasted a specific excerpt into the prompt. It may use only the spec, diff, implementation files, tests, and the repo's existing CLI/API/test runner. It may execute at most two targeted probes before first output, and each probe must compare the full externally visible result (exit/stdout/stderr plus full parsed output object, including accepted/scheduled rows, rejected rows, and remaining state when present), not just a single property. For priority/stateful specs, at least one probe must include an earlier input entity that would succeed under input-order processing, a later higher-priority entity that consumes or blocks the critical resource, and a failure/blocked/rollback edge that determines a later entity's state. For cart/pricing specs where visible verification combines duplicate items, line promotions, tax, coupon, and shipping, the success-path probe must include interleaved duplicates plus taxable and non-taxable items and assert full output rows. Scope qualifiers are binding: pair-JUDGE must not reinterpret `inside a warehouse`, `per resource`, or line-scoped rules as global rules. When both priority ordering and rollback/blocked-interval behavior appear in the spec, this dominance-loss probe is mandatory and comes before any other probe: an earlier lower-priority entity that would succeed alone or under input-order processing must lose because a later higher-priority entity is processed first; a failed/blocked middle entity must not corrupt later state; and the assertion must cover complete accepted/scheduled and rejected output ordering. It must stop and emit JSONL immediately on the first verdict-binding finding, and must emit PASS immediately if both probes plus static scope/dependency checks pass. Both judgments merge with the rule "any HIGH/CRITICAL finding either model surfaces is verdict-binding; high-confidence MEDIUM findings are also verdict-binding when they identify a concrete behavioral regression against the spec, public contract, or existing test contract." Cross-model disagreement on advisory lower-severity findings is logged but does not change the verdict. If MECHANICAL has a HIGH/CRITICAL finding, skip the second judge and record `pair_judge: null`; the fix loop needs the deterministic finding, not duplicate review.
+- Codex: install/configure the Codex CLI, run `codex auth` or the current login
+  flow, verify `codex --version`, then rerun. Use `--no-pair` only when the user
+  intentionally accepts solo VERIFY for this run.
+- Claude: install/configure Claude Code, run `claude --version` when available,
+  confirm the host can spawn Claude agents, then rerun.
 
-Findings written to `.devlyn/verify.findings.jsonl`. **VERIFY agents have no code-mutation tools.** Codex pair-JUDGE is read-only: invoke `codex-monitored.sh` directly with `-c model_reasoning_effort=medium` for this bounded two-probe review, without piping to `tail`/`head`/`grep`, capture stdout/stderr by direct tool capture or file redirection, require JSONL findings on stdout, and have the orchestrator write `.devlyn/verify.pair.findings.jsonl`. If stdout is first captured as `.devlyn/codex-judge.stdout`, run `python3 .claude/skills/_shared/collect-codex-findings.py` before merge; that script is the deterministic boundary writer for `.devlyn/verify.pair.findings.jsonl`. Raw stdout remains diagnostic only: if stdout contains findings or a non-PASS summary while `.devlyn/verify.pair.findings.jsonl` is empty, `verify-merge-findings.py` blocks VERIFY for `verify.pair.emission-contract`. Do not ask Codex to `apply_patch` or edit `.devlyn`. After primary and pair findings are written, run `python3 .claude/skills/_shared/verify-merge-findings.py --write-state`. Branch only on the merged `state.phases.verify.verdict`; a HIGH/CRITICAL finding from either judge must mechanically become `NEEDS_WORK`. Never write `.devlyn/verify-merged.findings.jsonl` or `.devlyn/verify-merge.summary.json` by hand; `verify-merge-findings.py` is their only writer. State write: `phases.verify.{started_at, verdict, completed_at, duration_ms, sub_verdicts: {mechanical, judge, pair_judge?}, artifacts}`.
+Findings written to `.devlyn/verify.findings.jsonl`. **VERIFY agents have no code-mutation tools.** Codex pair-JUDGE is read-only: invoke `codex-monitored.sh` with `CODEX_MONITORED_ISOLATED=1` and `-c model_reasoning_effort=medium`, no `tail`/`head`/`grep` pipes, direct stdout/stderr capture, JSONL findings on stdout, and orchestrator-written `.devlyn/verify.pair.findings.jsonl`. Isolation blocks user config, AGENTS.md, pyx-memory, hooks, and project rules from hidden context/tool/transcript side effects. If stdout is captured as `.devlyn/codex-judge.stdout`, run `python3 .claude/skills/_shared/collect-codex-findings.py` before merge; raw stdout is diagnostic only. If stdout contains findings or a non-PASS summary while `.devlyn/verify.pair.findings.jsonl` is empty, `verify-merge-findings.py` blocks VERIFY for `verify.pair.emission-contract`. Do not ask Codex to `apply_patch` or edit `.devlyn`. After primary and pair findings are written, run `python3 .claude/skills/_shared/verify-merge-findings.py --write-state`. Branch only on the merged `state.phases.verify.verdict`; a HIGH/CRITICAL finding from either judge must mechanically become `NEEDS_WORK`. Never write `.devlyn/verify-merged.findings.jsonl` or `.devlyn/verify-merge.summary.json` by hand; `verify-merge-findings.py` is their only writer. State write: `phases.verify.{started_at, verdict, completed_at, duration_ms, sub_verdicts: {mechanical, judge, pair_judge?}, artifacts}`.
 
 Branch:
 - `PASS` → PHASE 6.
@@ -223,7 +275,7 @@ State write: `phases.final_report.started_at` at the top of this phase.
 
 1. **Terminal verdict** — derive from `state.phases.{plan, implement, build_gate, cleanup, verify}.verdict` per the precedence rules in `references/state-schema.md#terminal-verdict`. Verify-only mode short-circuits to `state.phases.verify.verdict`.
 
-2. **Render report** — sections: header (run_id, engine, mode, verdict, wall-time), per-phase summary, findings table (verify findings only — post-IMPLEMENT phases are findings-only), follow-up notes (any `--continue-on-large` assumptions, any silent fallbacks).
+2. **Render report** — sections: header (run_id, engine, mode, verdict, wall-time), per-phase summary, pair/risk-probe status, findings table (verify findings only — post-IMPLEMENT phases are findings-only), follow-up notes (any `--continue-on-large` assumptions, any `--no-pair` / `--no-risk-probes` opt-out, any engine setup guidance after BLOCKED, `/devlyn:ideate` guidance after `BLOCKED:solo-headroom-hypothesis-required` that asks for the visible behavior `solo_claude` is expected to miss, and `/devlyn:ideate` guidance after `BLOCKED:solo-ceiling-avoidance-required` that asks for the concrete difference from rejected or solo-saturated controls such as `S2`-`S6`).
 
 3. State write: `phases.final_report.{verdict, completed_at, duration_ms}` BEFORE archive runs (archive prune logic skips runs whose `final_report.verdict` is null).
 

package/config/skills/devlyn:resolve/references/free-form-mode.md

@@ -13,6 +13,14 @@ Compute these signals from the goal text + project state:
 3. **verb_class** — primary verb of the goal: `fix | add | refactor | debug | review | rewrite | migrate | ...`.
 4. **codebase_size** — `git ls-files | wc -l`. Coarse buckets: `<50` / `<500` / `≥500`.
 5. **has_failing_test** — does the goal mention a specific failing test or include a stack trace?
+6. **pair_evidence_intent** — does the goal ask for benchmark evidence, pair-evidence, risk-probe measurement, solo<pair proof, or solo-headroom work?
+7. **has_actionable_solo_headroom** — does the goal itself include the actionable contract: literal `solo-headroom hypothesis`, `solo_claude`, `miss`, and a backticked observable command line that itself contains `miss` and is framed as the command/observable that exposes it?
+8. **unmeasured_pair_candidate_intent** — does the goal ask to add, create,
+   promote, or run a new unmeasured benchmark, shadow fixture, golden fixture,
+   risk-probe, or pair-evidence candidate?
+9. **has_solo_ceiling_avoidance** — does the goal itself include the literal
+   phrase `solo ceiling avoidance`, mention `solo_claude`, and name a concrete
+   difference from rejected or solo-saturated controls such as `S2`-`S6`?
 
 ### Trivial branch
 
@@ -46,10 +54,14 @@ Conditions (any one):
 - `file_scope_signals > 10` OR zero signals (vague enough that the classifier cannot pick scope).
 - `verb_class ∈ {rewrite, migrate}` and scope is multi-subsystem.
 - The goal mentions a new feature whose surface area requires design decisions the harness cannot make from a one-shot prompt.
+- `pair_evidence_intent == true` and `has_actionable_solo_headroom == false`.
+- `unmeasured_pair_candidate_intent == true` and `has_solo_ceiling_avoidance == false`.
 
 Action: log `recommend: /devlyn:ideate first` in `.devlyn/criteria.generated.md` plus the final report. Two policies:
 - Default: halt with terminal verdict `BLOCKED:large-needs-ideation`.
 - `--continue-on-large` flag: synthesize a best-effort spec from the goal with explicit "assumptions made" block; proceed to PHASE 1; the final report flags every assumption for user review.
+- Exception: if the large classification came from pair-evidence intent without an actionable solo-headroom hypothesis, halt with `BLOCKED:solo-headroom-hypothesis-required` even when `--continue-on-large` is set. Do not invent a hypothesis; recommend `/devlyn:ideate` so the user can supply the visible behavior `solo_claude` is expected to miss.
+- Exception: if the large classification came from unmeasured pair-candidate intent without solo ceiling avoidance, halt with `BLOCKED:solo-ceiling-avoidance-required` even when `--continue-on-large` is set. Do not invent the note; recommend `/devlyn:ideate` so the user can supply the concrete difference from rejected or solo-saturated controls such as `S2`-`S6`.
 
 ## Anti-pattern: drift to LLM judgment
 
@@ -63,6 +75,9 @@ The internal mini-spec written for trivial / medium / `--continue-on-large` path
 
 - `## Requirements` non-empty, each bullet testable (CLI command, test command, observable file change).
 - `## Verification` non-empty if the goal implies any runnable acceptance check. Empty Verification is allowed only when all Requirements are pure-design (e.g. "follow existing pattern X").
+- If a free-form goal includes pair-evidence intent and already includes an actionable solo-headroom hypothesis, preserve that literal hypothesis in `.devlyn/criteria.generated.md` unchanged enough for VERIFY to detect `solo-headroom hypothesis`, `solo_claude`, `miss`, and the backticked observable command line that itself contains `miss`, emit the canonical `spec.solo_headroom_hypothesis` pair trigger reason, and satisfy regenerated-evidence checks such as `benchmark audit --require-hypothesis-trigger`.
+- If a free-form goal includes unmeasured pair-candidate intent and already includes solo ceiling avoidance, preserve that literal note in `.devlyn/criteria.generated.md` unchanged enough for reviewers to see `solo ceiling avoidance`, `solo_claude`, and the concrete difference from rejected or solo-saturated controls such as `S2`-`S6`.
 - Free-form mode mini-specs are written to `.devlyn/criteria.generated.md` (not to a roadmap path) — this is run-scoped artifact, not a documented spec.
+- After writing `.devlyn/criteria.generated.md`, set `state.source.type = "generated"`, `state.source.spec_path = null`, `state.source.spec_sha256 = null`, `state.source.criteria_path = ".devlyn/criteria.generated.md"`, and `state.source.criteria_sha256` to the raw-byte SHA-256 of the generated criteria file. Downstream PLAN/IMPLEMENT/VERIFY phases and `spec-verify-check.py --include-risk-probes` depend on this pointer; do not rely on the file existing by convention.
 
 PLAN reads the mini-spec the same way it reads a real spec. The downstream pipeline cannot tell the difference.

package/config/skills/devlyn:resolve/references/phases/build-gate.md

@@ -22,8 +22,8 @@ Run in this order; each emits findings into `.devlyn/build_gate.findings.jsonl`:
 1. **Type check** (TypeScript / mypy / etc.). Each error → one finding, severity `HIGH`, rule `correctness.type-check`.
 2. **Lint** (eslint / ruff / clippy / etc.). Each error → finding, severity `MEDIUM`, rule `quality.lint`. Warnings stay LOW unless the spec elevates them.
 3. **Test suite** (npm test / pytest / go test / cargo test). Each failing test → finding, severity `HIGH`, rule `correctness.test-failure`. Include the failing test's file:line and the assertion.
-4. **Spec literal verification + risk probes**: `python3 .claude/skills/_shared/spec-verify-check.py --include-risk-probes`. The script reads `.devlyn/spec-verify.json` (pre-staged from spec or self-staged from `state.source.spec_path`) and appends `.devlyn/risk-probes.jsonl` when present. Each verification command mismatch → finding `correctness.spec-literal-mismatch`, severity `CRITICAL`. Each risk-probe mismatch → finding `correctness.risk-probe-failed`, severity `CRITICAL`. Missing/malformed carrier on a generated source → finding `correctness.spec-verify-malformed`, severity `CRITICAL`.
-5. **Browser** (only when `spec.expected.json.browser_flows` declared OR diff touches `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `page.*`, `layout.*`, `route.*`, `*.css`, `*.html`): start dev server, run declared flows via Chrome MCP if available, falling back to Playwright, falling back to curl. Each failed flow → finding, severity `HIGH`, rule `correctness.browser-flow-failed`.
+4. **Spec literal verification + risk probes**: `python3 .claude/skills/_shared/spec-verify-check.py --include-risk-probes`. The script self-stages from sibling `spec.expected.json` next to `state.source.spec_path`, or the legacy inline carrier when the sibling is absent; benchmark-prestaged `.devlyn/spec-verify.json` still wins. It appends `.devlyn/risk-probes.jsonl` when present, and requires that file when `state.risk_profile.risk_probes_enabled == true`. Malformed `state.risk_profile` is also CRITICAL because it can hide enabled risk probes. Command or risk-probe mismatch → CRITICAL finding. Missing required risk probes, missing/malformed generated carrier, or malformed sibling expected file → `correctness.spec-verify-malformed` CRITICAL.
+5. **Browser** (only when diff touches `*.tsx`, `*.jsx`, `*.vue`, `*.svelte`, `page.*`, `layout.*`, `route.*`, `*.css`, `*.html`): start the dev server and run the repo's existing browser checks, or a minimal curl/HTML check when no browser test harness exists. Each failed check → finding, severity `HIGH`, rule `correctness.browser-flow-failed`.
 
 Append all findings; do not stop on the first failure.
 </gates>

package/config/skills/devlyn:resolve/references/phases/implement.md

@@ -33,7 +33,7 @@ Read `_shared/runtime-principles.md`. Codex-routed phases receive the inlined ex
 
 - Subtractive-first: every accretion-shaped change is visible in the commit message or a flagged finding. Net-deletion is the default; pure-addition needs a citation.
 - Goal-locked: implement only the listed Requirements. Adjacent code that "looks fixable" is drift unless the spec or plan listed it.
-- No-workaround: no `any`, no `@ts-ignore`, no silent `catch`, no hardcoded values, no helper scripts that bypass root cause. The only documented exception is the Codex CLI availability downgrade.
+- No-workaround: no `any`, no `@ts-ignore`, no silent `catch`, no hardcoded values, no helper scripts that bypass root cause. Required unavailable engines stop with `BLOCKED:<engine>-unavailable`; they do not downgrade.
 - Evidence: every claim cites file:line you opened. Hallucinated APIs are excluded.
 </runtime_principles>
 

package/config/skills/devlyn:resolve/references/phases/probe-derive.md

@@ -25,7 +25,23 @@ Read the visible `## Verification` section. Emit 1 to 3 executable probes
 that cover the highest-risk bullets whose failure would change observable
 behavior. Prefer bullets that combine ordering/priority, rollback/state
 mutation, idempotency, auth/error priority, stdout/stderr, or exact output
-shape.
+shape. Treat CLI/process errors and HTTP error responses as different contracts:
+CLI errors must prove exit/stderr behavior, while HTTP errors must prove the
+status code and response body. When the visible verification text names concurrent or near-concurrent
+mutations, the probe must overlap the operations and assert the complete
+externally-visible state, not just that every request returned a success code.
+When a batch/import operation must be all-or-nothing, the probe must exercise a
+mixed valid/invalid batch and prove the externally-visible state is unchanged
+after the failure.
+
+If the visible spec includes a solo-headroom hypothesis, the first probe must
+target that hypothesis: use the visible command/input shape it names, exercise
+the behavior the spec says `solo_claude` is expected to miss, and assert the
+full observable result. The emitted probe `cmd` must contain the hypothesis's
+backticked observable command so `.devlyn/risk-probes.jsonl` can be validated
+mechanically, and `derived_from` must be an exact substring of that hypothesis
+bullet. Do not replace the hypothesis with a neighboring easier edge case, and
+do not cite hidden or benchmark-only verifier files.
 
 For high-complexity specs with two or more behavior bullets, at least one probe
 must be compound: one command must exercise two or more visible verification
@@ -101,7 +117,9 @@ Rules:
 - `tags` is required. Use only these shape tags:
   `ordering_inversion`, `boundary_overlap`, `prior_consumption`,
   `rollback_state`, `positive_remaining`, `stdout_stderr_contract`,
-  `error_contract`, `shape_contract`.
+  `error_contract`, `http_error_contract`, `auth_signature_contract`,
+  `idempotency_replay`, `concurrent_state_consistency`,
+  `atomic_batch_state`, `shape_contract`.
 - `tag_evidence` is required and must be a JSON object keyed by tag, never a
   top-level array. For these tags, include every listed evidence marker in the
   tag's array and make the command actually exercise it:
@@ -119,6 +137,26 @@ Rules:
     `later_entity_uses_released_state`.
   - `positive_remaining`: `asserts_full_remaining_state`,
     `zero_quantity_rows_absent`.
+  - `stdout_stderr_contract`: `asserts_named_stream_output`.
+  - `error_contract`: `asserts_error_payload_or_stderr`,
+    `asserts_nonzero_or_exit_2`.
+  - `http_error_contract`: `asserts_http_error_status`,
+    `asserts_error_payload_body`.
+  - `auth_signature_contract`: `asserts_signature_over_exact_bytes`,
+    `asserts_tampered_or_missing_signature_rejected`.
+  - `idempotency_replay`: `first_delivery_then_duplicate`,
+    `duplicate_id_rejected_regardless_of_body`.
+  - `concurrent_state_consistency`: `overlapping_mutations_exercised`,
+    `all_successful_responses_reflected`, `distinct_identifiers_asserted`.
+  - `atomic_batch_state`: `mixed_valid_invalid_batch`,
+    `asserts_store_unchanged_after_failure`,
+    `asserts_success_order_and_distinct_ids`.
+  - `shape_contract` when the visible text names exact keys, fields, row
+    shapes, JSON objects, response bodies, stdout/stderr objects, or exact error
+    bodies: `uses_visible_input_key_names`,
+    `asserts_visible_output_key_names`, `asserts_no_unexpected_output_keys`.
+    If it names an exact JSON error object/body, also include
+    `asserts_exact_error_object`.
   Tags not listed here may use an empty evidence list or be omitted from
   `tag_evidence`.
 - `cmd` must not reference `BENCH_FIXTURE_DIR`, `verifiers/`, benchmark fixture
@@ -128,6 +166,10 @@ Rules:
 - Match the spec's visible input and output key names literally; do not invent
   aliases such as `stock` for `lots`, `order_id` for `id`, or `warehouse_id`
   for `warehouse`.
+- When a verification bullet names exact keys, fields, row shapes, JSON object
+  shape, or an exact error body, the probe must use `shape_contract` and assert
+  exact key sets with parsed JSON/deep equality. A substring check is too weak:
+  the command must fail on aliased keys, missing keys, and extra keys.
 - For cart/pricing specs whose visible verification covers duplicate combining,
   multiple line-promotion types, tax, coupon, and shipping, the compound success
   probe must include interleaved duplicate SKUs plus taxable and non-taxable
@@ -148,6 +190,10 @@ Rules:
   full test suite.
 - Coverage over cleverness: mirror the verification bullet literally before
   inventing an edge case.
+- If the spec includes a solo-headroom hypothesis and the emitted probes do not
+  exercise the stated `solo_claude` miss with a `cmd` containing the hypothesis's
+  backticked observable command and `derived_from` pointing at the hypothesis
+  bullet, the artifact is too weak for pair-evidence work.
 - If a probe passes while an implementation processes entities in input order
   instead of the required priority/order, or emits extra zero-value state rows,
   the probe is too weak.
@@ -175,6 +221,32 @@ Rules:
 - If `remaining` state appears in the visible contract, at least one probe must
   carry `positive_remaining` and assert that zero-quantity/zero-value rows are
   absent unless the visible spec explicitly requires them.
+- If webhook signatures, raw-body signatures, HMAC, or `X-Signature` appear in
+  the visible contract, at least one probe must carry
+  `auth_signature_contract` and prove exact-byte signature verification plus a
+  tampered or missing signature rejection.
+- If replay, duplicate delivery, same id, already-seen ids, or idempotency
+  appear in the visible contract, at least one probe must carry
+  `idempotency_replay` and cover first delivery followed by duplicate rejection,
+  including the case where the duplicate body would otherwise fail validation
+  when the spec says duplicate wins.
+- If an HTTP status error such as `400`, `401`, `409`, or `422` appears with a
+  JSON error body, error object, or named error field, at least one probe must
+  carry `http_error_contract` and assert both the exact status code and parsed
+  response body. Do not use CLI `error_contract` for these HTTP-only checks
+  unless the visible text also names process exit or stderr behavior.
+- If concurrent, close-together, simultaneous, parallel, race, lost update, or
+  many-at-once mutation semantics appear in the visible contract, at least one
+  probe must carry `concurrent_state_consistency`. It must trigger overlapping
+  mutations, then compare every successful response against the final
+  externally-visible state and assert the identifiers are distinct. Do not use
+  this tag for ordinary batch success cases that only require distinct ids.
+- If a batch/import contract says one valid plus one invalid item fails while
+  the later state remains the same as before, or otherwise says all-or-nothing /
+  no partial updates / 0 inserts on failure, at least one probe must carry
+  `atomic_batch_state`. It must execute a mixed valid/invalid batch, assert the
+  store/list is unchanged after failure, and include an all-valid success case
+  proving order and distinct ids.
 </quality_bar>
 
 <runtime_principles>

package/config/skills/devlyn:resolve/references/phases/verify.md

@@ -10,7 +10,7 @@ Independent quality layer. You answer one question: did the diff deliver what th
 - `spec.md` (or `.devlyn/criteria.generated.md` for free-form mode) — the contract.
 - `spec.expected.json` — the mechanical acceptance contract per `_shared/expected.schema.json`.
 - The cumulative diff against `state.base_ref.sha`.
-- The spec hash (`state.source.spec_sha256`) — re-read the spec from disk and confirm the hash matches; if it does not, write `state.phases.verify.verdict: "BLOCKED"` with reason `spec_sha256_mismatch` and stop.
+- The source hash (`state.source.spec_sha256` for spec mode, `state.source.criteria_sha256` for generated free-form mode) — re-read the source contract from disk and confirm the hash matches; if it does not, write `state.phases.verify.verdict: "BLOCKED"` with reason `source_sha256_mismatch` and stop.
 
 You do NOT receive: PLAN, IMPLEMENT's reasoning, BUILD_GATE's findings, CLEANUP's allowlist negotiations. Reading those would compromise independence.
 </input>
@@ -21,10 +21,7 @@ You do NOT receive: PLAN, IMPLEMENT's reasoning, BUILD_GATE's findings, CLEANUP'
 
 Re-run the mechanical checks fresh, independent of BUILD_GATE's earlier run:
 
-1. `python3 .claude/skills/_shared/spec-verify-check.py --include-risk-probes` against the post-CLEANUP code.
-2. Re-scan `spec.expected.json.forbidden_patterns` against the diff (Python re.search; honor each pattern's `files` allowlist).
-3. Confirm `required_files` exist post-diff; confirm `forbidden_files` do not appear in the diff.
-4. Confirm `max_deps_added` is not exceeded (`git diff -- package.json` for Node; equivalent for other ecosystems).
+1. `SPEC_VERIFY_PHASE=verify_mechanical SPEC_VERIFY_FINDINGS_FILE=verify-mechanical.findings.jsonl SPEC_VERIFY_FINDING_PREFIX=VERIFY-MECH python3 .claude/skills/_shared/spec-verify-check.py --include-risk-probes` against the post-CLEANUP code. In spec mode, sibling `spec.expected.json` wins; a malformed sibling is CRITICAL, not a fallback. When `state.risk_profile.risk_probes_enabled == true`, missing `.devlyn/risk-probes.jsonl` is also CRITICAL. The script also checks `forbidden_patterns`, `required_files`, `forbidden_files`, and `max_deps_added`.
 
 Emit findings to `.devlyn/verify-mechanical.findings.jsonl`. Each match = one finding. Severity from the pattern's `severity` field (disqualifier → CRITICAL, warning → MEDIUM).
 
@@ -87,20 +84,40 @@ design/style concerns remain non-binding MEDIUM and produce `PASS_WITH_ISSUES`.
 
 ### Pair-mode (when triggered by orchestrator)
 
-Pair-mode is eligible only after MECHANICAL has no HIGH/CRITICAL findings.
-Deterministic blockers already decide the verdict and route to the fix loop; a
-second judge there duplicates evidence and wastes wall-time. If MECHANICAL has
-a HIGH/CRITICAL finding, record `pair_judge: null` and do not spawn the second
-VERIFY agent.
+Pair-mode is eligible only after MECHANICAL and the primary JUDGE have no
+verdict-binding findings. Deterministic blockers and primary JUDGE blockers
+already decide the verdict and route to the fix loop; a second judge there
+duplicates evidence and wastes wall-time. If MECHANICAL or the primary JUDGE
+has a verdict-binding finding, record `pair_judge: null` and do not spawn the
+second VERIFY agent.
 
 When eligible, trigger pair-mode if any of these are true:
-- `--pair-verify` was set.
-- The spec frontmatter has `complexity: high`.
-- `state.complexity` is `"high"` or `"large"`.
-- MECHANICAL emitted warning-level findings but no HIGH/CRITICAL blockers.
+- `state.pair_verify == true` (`--pair-verify` was set).
+- `state.mode == "verify-only"`.
+- The spec frontmatter has `complexity: high`; legacy/external spec
+  `complexity: large` is accepted for compatibility, but new specs use `high`.
+- Current free-form `state.complexity` is `"large"`; legacy `"high"` state remains accepted by the merge validator only for archived run compatibility.
+- `state.risk_profile.high_risk == true`.
+- `.devlyn/risk-probes.jsonl` exists or `state.risk_profile.risk_probes_enabled == true`.
+- The spec includes an actionable solo-headroom hypothesis.
+- MECHANICAL or the primary JUDGE emitted warning-level findings but no
+  verdict-binding blockers.
 - `state.verify.coverage_failed == true`.
 
-Before JUDGE spawn, compute and persist:
+Malformed `state.risk_profile` is a VERIFY contract violation: it must be an
+object, `high_risk` / `risk_probes_enabled` / `pair_default_enabled` must be
+JSON booleans when present, and `reasons` must be a string array. Do not treat
+missing or malformed risk state as low-risk; `verify-merge-findings.py` blocks
+it because it can hide `risk.high` or `risk_probes.enabled` pair triggers.
+
+If `--no-pair` was set, do not spawn the OTHER-engine judge. Record
+`pair_trigger: { eligible: false, reasons: [], skipped_reason: "user_no_pair" }`
+and continue with solo VERIFY. This is an explicit user opt-out, not an engine
+availability fallback. `--pair-verify` and `--no-pair` are mutually exclusive;
+if both are present, stop with `BLOCKED:invalid-flags`.
+
+After MECHANICAL and the primary JUDGE finish, compute and persist this before
+spawning the OTHER-engine pair judge:
 
 ```json
 "pair_trigger": {
@@ -110,16 +127,39 @@ Before JUDGE spawn, compute and persist:
 }
 ```
 
-If `eligible == true` and `reasons` is non-empty, the OTHER-engine judge is
-mandatory. Skipping it is a VERIFY contract violation. If ineligible, record the
-reason, e.g. `"mechanical_blocker"`.
+If `eligible == true`, `reasons` must be non-empty and include every applicable canonical reason; for example, a spec with an actionable solo-headroom
+hypothesis must include `spec.solo_headroom_hypothesis` even when another reason
+such as `risk.high` also applies. The OTHER-engine judge is mandatory. Skipping
+it is a VERIFY contract violation. If ineligible, record the
+reason, e.g. `"mechanical_blocker"` or `"primary_judge_blocker"`.
+
+`pair_trigger` is a strict contract, not advisory metadata. `eligible: true`
+requires a non-empty `reasons` list and `skipped_reason: null`; `eligible: false`
+requires an empty `reasons` list and a string/null `skipped_reason`. Do not emit
+contradictory states such as `eligible: true` with `skipped_reason`, or
+`eligible: false` with trigger reasons. `verify-merge-findings.py` blocks VERIFY
+on malformed trigger state. Eligible triggers must contain only canonical
+reasons and at least one reason: `mode.verify-only`, `complexity.high`, `complexity.large`,
+`mode.pair-verify`, `spec.complexity.high`, `spec.complexity.large`,
+`spec.solo_headroom_hypothesis`, `risk.high`, `risk_probes.enabled`,
+`risk_probes.present`, `coverage.failed`, `mechanical.warning`, or
+`judge.warning`.
 
 The `--engine` flag never disables this rule. Explicit `--engine claude` means
 Claude is the primary judge; if pair-mode triggers, Codex is still the mandatory
 OTHER-engine judge. Do not record "explicit --engine claude" as a skip reason.
 The only valid skip reasons after a non-empty eligible trigger are deterministic
-MECHANICAL HIGH/CRITICAL blockers or Codex unavailability proven by the
-invocation layer.
+MECHANICAL HIGH/CRITICAL blockers or an explicit `--no-pair`. Engine
+unavailability is not a skip reason; it is `BLOCKED:<engine>-unavailable`.
+
+Before invoking the OTHER-engine judge, run the shared availability pre-flight
+for that engine. If Codex is required and unavailable, set VERIFY to
+`BLOCKED:codex-unavailable` and tell the user to install/configure the Codex CLI,
+run the current Codex auth/login flow, verify `codex --version`, and rerun. If
+Claude is required and the host cannot spawn a Claude agent, set VERIFY to
+`BLOCKED:claude-unavailable` and tell the user to install/configure Claude Code,
+verify `claude --version` where available, and rerun. Do not convert this to a
+solo pass, and do not synthesize pair findings.
 
 When eligible and the orchestrator spawns a second VERIFY agent with the OTHER engine's adapter, both judgments are merged:
 - Any HIGH/CRITICAL finding either model surfaces is verdict-binding.
@@ -143,12 +183,22 @@ When eligible and the orchestrator spawns a second VERIFY agent with the OTHER e
   after the first verdict-binding finding and emit JSONL. If both probes pass
   and static scope/dependency checks show no blocker, emit PASS; do not continue
   exhaustive exploration.
+  If the spec includes a solo-headroom hypothesis, one of the two targeted
+  probes must exercise that hypothesis with the visible command/input shape and
+  compare the full externally visible result. The probe must use the
+  hypothesis's backticked observable command as its command anchor before adding
+  bounded input variations. Do not substitute a neighboring easier edge case;
+  the pair judge exists to test the stated expected solo miss.
   A targeted probe must compare the full externally visible result
   (stdout/stderr/exit and full parsed output object, including accepted/scheduled
   rows, rejected rows, and remaining state when present), not just a single
-  property. For priority/stateful specs, at least one probe must include an
-  earlier input entity that would succeed under input-order processing, a later
-  higher-priority entity that consumes or blocks the critical resource, and a
+  property. When the spec names exact keys, row shapes, JSON object shape, or an
+  exact error body, compare parsed key sets/deep equality so aliased keys,
+  missing keys, and extra keys are verdict-binding failures. Use the spec's
+  visible input key names literally when constructing the probe input. For
+  priority/stateful specs, at least one probe must include an earlier input
+  entity that would succeed under input-order processing, a later higher-priority
+  entity that consumes or blocks the critical resource, and a
   failure/blocked/rollback edge that determines a later entity's state. This is
   the minimum compound shape for priority + failure/state-mutation bugs.
   Scope qualifiers are binding for the pair judge too: do not reinterpret
@@ -164,12 +214,13 @@ When eligible and the orchestrator spawns a second VERIFY agent with the OTHER e
   (or scheduled) and rejected rows.
 
 Codex pair-JUDGE is read-only. Invoke `codex-monitored.sh` directly with
-`-c model_reasoning_effort=medium`; this phase is a bounded two-probe review,
-not an unbounded implementation task. Do not pipe it to `tail`, `head`, `grep`,
-`sed`, or `awk`. Capture stdout/stderr by direct tool capture or file
-redirection. The Codex judge must return JSONL
-findings on stdout; the orchestrator writes `.devlyn/verify.pair.findings.jsonl`
-and merges verdicts. Do not ask Codex to `apply_patch` or edit `.devlyn`.
+`CODEX_MONITORED_ISOLATED=1` and `-c model_reasoning_effort=medium`; this is a
+bounded two-probe review, not implementation. Isolation blocks user config,
+AGENTS.md, pyx-memory, hooks, and project rules from hidden context/tool
+side effects. Do not pipe it to `tail`, `head`, `grep`, `sed`, or `awk`.
+Capture stdout/stderr directly. The Codex judge must return JSONL findings on
+stdout; the orchestrator writes `.devlyn/verify.pair.findings.jsonl` and merges
+verdicts. Do not ask Codex to `apply_patch` or edit `.devlyn`.
 The Codex prompt must include a bounded-output contract: no harness-doc reads,
 maximum two targeted probes before first output, stop on the first
 verdict-binding finding, and emit PASS immediately after the bounded checks pass.