devlyn-cli 2.10.1 → 3.0.0

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

@@ -11,19 +11,28 @@ Independent quality layer. You answer one question: did the diff deliver what th
 - `spec.expected.json` — the mechanical acceptance contract per `_shared/expected.schema.json`.
 - The cumulative diff against `state.base_ref.sha`.
 - 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.
+- `.devlyn/spec-verify.results.json` plus the validated VERIFY
+  process-evidence manifest and raw stdout/stderr streams named by its
+  `process_evidence` carrier. These are immutable MECHANICAL results; rehash
+  every named byte before JUDGE spawn and again during merge.
 
-You do NOT receive: PLAN, IMPLEMENT's reasoning, BUILD_GATE's findings, CLEANUP's allowlist negotiations. Reading those would compromise independence.
+You do NOT receive: PLAN, IMPLEMENT's reasoning, BUILD_GATE's findings, CLEANUP's allowlist negotiations. Reading those would compromise independence. Inspect authorized source, diff and sealed evidence using native read/search tools or non-mutating shell commands; executable verification belongs exclusively to MECHANICAL.
 </input>
 
 <sub_phases>
 
 ### MECHANICAL (deterministic)
 
-Re-run the mechanical checks fresh, independent of BUILD_GATE's earlier run:
+The orchestrator completes these checks before spawning either JUDGE,
+independent of BUILD_GATE's earlier run:
 
-1. `SPEC_VERIFY_PHASE=verify_mechanical SPEC_VERIFY_FINDINGS_FILE=verify-mechanical.findings.jsonl SPEC_VERIFY_FINDING_PREFIX=VERIFY-MECH python3 "$DEVLYN_SHARED_DIR/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`.
+1. `SPEC_VERIFY_PHASE=verify_mechanical SPEC_VERIFY_FINDINGS_FILE=verify-mechanical.findings.jsonl SPEC_VERIFY_FINDING_PREFIX=VERIFY-MECH python3 "$DEVLYN_SHARED_DIR/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`, and writes `.devlyn/spec-verify.results.json` with a VERIFY process-evidence carrier.
 
-Emit findings to `.devlyn/verify-mechanical.findings.jsonl`. Each match = one finding. Severity from the pattern's `severity` field (disqualifier → CRITICAL, warning → MEDIUM).
+2. Validate the carrier and every named raw stream. A missing, altered,
+escaping, duplicate, or expectation-mismatched record is a CRITICAL mechanical
+blocker. Freeze the validated results, manifest, and streams as JUDGE inputs.
+
+Emit findings to `.devlyn/verify-mechanical.findings.jsonl`. Each match = one finding. Severity from the pattern's `severity` field (disqualifier → CRITICAL, warning → MEDIUM). A verdict-binding MECHANICAL result skips both JUDGEs.
 
 ### JUDGE (fresh-context grading)
 
@@ -34,6 +43,14 @@ Grade the diff against the spec on rubric axes:
 - **Quality** — does the implementation follow the framework's idiomatic patterns, or are there hand-rolled helpers replacing standard primitives? `design.unidiomatic-pattern` MEDIUM if so.
 - **Consistency** — internal style (naming, error shape, module boundaries) consistent with the surrounding code.
 
+**Bounded primary review**: the primary JUDGE makes one broad pass over the
+source contract, sealed MECHANICAL carrier, and cumulative diff, covering all
+four rubric axes and every binding Requirement clause. It then makes one
+targeted interaction pass over the clauses the broad pass left unresolved.
+Before any third pass, emit the required terminal result. If R1–R8 or another
+spec axis remains uncovered, emit a verdict-binding BLOCKED coverage finding
+instead of continuing or assuming PASS.
+
 For each finding, write file:line evidence. Do not paraphrase code; quote it.
 
 **Clause-level check**: split each Requirement into its binding clauses before
@@ -54,8 +71,9 @@ coexist, compose them in the stated order instead of inventing a stronger global
 ordering. A finding based on a widened invariant is a false positive and must
 not drive the fix loop.
 
-**Interaction check**: for high-complexity specs, one-axis examples are not
-enough. Construct at least one adversarial scenario that combines two or more
+**Targeted interaction pass**: trace interactions among the clauses the broad
+pass left unresolved. For high-complexity specs, one-axis examples are not
+enough: construct at least one adversarial scenario that combines two or more
 explicit verification bullets. Prioritize combinations such as
 ordering/priority + blocked interval/failure, ordering/priority +
 all-or-nothing rollback + later entity state, validation/error-priority +
@@ -63,22 +81,29 @@ stdout/stderr contract, or auth/idempotency + duplicate/replay ordering. If the
 implementation only passes isolated examples but fails the combined scenario,
 emit a HIGH finding tied to all relevant spec clauses.
 
-For high-complexity specs, execute at least one combined adversarial check with
-the repo's existing CLI/API/test runner before declaring PASS. Use a temporary
-script or inline command that leaves no tracked files behind. The check must
-cross two or more explicit verification bullets, not merely repeat the visible
-acceptance command. If the command exposes a mismatch, emit a HIGH finding with
-the command, expected output/state, and actual output/state.
-
-**Coverage check**: before declaring done, confirm you have evidence for every spec axis. If you could not exercise an axis (the spec asks for behavior X but the diff does not touch the code that produces X), set `state.verify.coverage_failed: true` and surface the missing-evidence finding rather than passing on assumption.
-
-**Verdict-binding severity check**: HIGH/CRITICAL findings are always
-verdict-binding. A MEDIUM finding is also verdict-binding when it identifies a
-concrete behavioral regression against the visible spec, an existing public
-contract, or an existing test contract. Examples: a previously valid input now
-errors, duplicate/idempotent handling regresses, warning/error semantics change
-for a real API path, or a focused existing regression test would fail. Advisory
-design/style concerns remain non-binding MEDIUM and produce `PASS_WITH_ISSUES`.
+JUDGE does not execute literal verification, lint, test, build, risk-probe, or
+newly invented interaction commands. For high-complexity behavior, executable
+coverage must already be declared in sibling `spec.expected.json` or derived
+risk probes and present in the sealed MECHANICAL evidence. Missing coverage is
+a verdict-binding finding; review the implementation's clause and code order
+without inventing a replacement command.
+
+**Coverage check**: before declaring done, confirm you have sealed evidence and code-order support for every spec axis. If an axis lacks declared MECHANICAL coverage, or the diff does not touch the code that produces it, set `state.verify.coverage_failed: true` and surface the missing-evidence finding rather than passing on assumption.
+
+**Verdict-binding check**: a demonstrated violation of an applicable mandatory
+task, public, or existing test contract is binding, including unmet new
+requirements and incorrect customer documentation. Quote the exact applicable
+clause and concrete file:line evidence. Small impact, rare inputs, or a
+pre-existing defect do not excuse that violation. A changed line or requirement
+reference alone does not establish applicability.
+
+Emit HIGH/CRITICAL as appropriate, or MEDIUM with literal `verdict_binding: true`.
+Do not label a binding finding LOW/INFO: the merge honors HIGH/CRITICAL and
+MEDIUM/true; confidence is reported but adds no merge threshold. Preferences,
+style, stronger inferred invariants, genuinely ambiguous clauses, and unrelated
+pre-existing issues are not demonstrated mandatory violations. Name the actual
+ambiguity or evidence limitation; do not substitute an impact argument.
+Advisory MEDIUM findings remain non-binding and produce `PASS_WITH_ISSUES`.
 
 **Anti-self-filter rule**: report every finding you observe, including ones you consider low-severity or low-confidence. Tag each with `confidence: high|medium|low` and let the harness's downstream filter rank them. Filtering at this stage suppresses recall.
 
@@ -99,7 +124,8 @@ round and merge by worst source verdict without vote counting. An orchestrator
 without foreground parallel dispatch runs the same two required judges
 sequentially, with no flag or extra state marker. This is a dispatch-shape
 fallback, not outcome-dependent escalation; the primary cannot skip the pair.
-Prefer read-only checks and serialize probes requiring exclusive shared state.
+Both JUDGEs inspect the same immutable evidence; neither runs probes or mutates
+shared state.
 
 Keep these reasons as telemetry; they no longer gate the second spawn:
 `mode.pair-verify`, `mode.verify-only`, `complexity.high`,
@@ -148,74 +174,80 @@ solo. Never 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.
-- Any high-confidence MEDIUM finding either model surfaces is also
-  verdict-binding when it identifies a concrete behavioral regression against
-  the spec, public contract, or existing test contract. This includes
-  duplicate/idempotent/order-preservation regressions and real warning/error
-  behavior changes. Do not downgrade these to advisory simply because they are
-  not HIGH.
+- Any MEDIUM finding with literal `verdict_binding: true` is also binding.
+  Apply the same mandatory-clause, applicability and evidence check above;
+  neither impact nor pre-existing origin makes an applicable violation advisory.
 - Other lower-severity disagreements are logged but do not change the verdict.
 - The orchestrator handles merge; you only emit your own findings.
 - The second judge's job is adversarial complement, not a duplicate summary:
-  prioritize the two highest-risk explicit `## Verification` bullets that cross
+  review the two highest-risk explicit `## Verification` bullets that cross
   state mutation, all-or-nothing rollback, ordering, idempotency, auth, or
   error-priority clauses. The primary judge owns broad coverage; the pair judge
   is a bounded adversarial complement. Do not read `.claude/skills`,
   `.codex/skills`, `CLAUDE.md`, `AGENTS.md`, or other harness docs unless the
   orchestrator pasted a specific excerpt into the prompt. Use only the spec,
-  diff, implementation files, tests, and the repo's CLI/API/test runner.
-  Execute at most two targeted probes before first output. Stop immediately
-  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. The mandatory dominance-loss anchor must run as a single command
-  with no shell chain operators. Chains used only to re-capture exit status are
-  forbidden because the tool result already carries it; this does not ban
-  compound shell generally or multi-step probes issued as separate tool calls.
-  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
-  `inside a warehouse`, `per resource`, or line-scoped rules as global rules.
-  If a candidate finding depends on that widening, emit PASS for that probe and
-  use the second bounded probe for a different explicit clause.
-  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 the complete output ordering for both accepted
-  (or scheduled) and rejected rows.
-
-The resolved pair-JUDGE is read-only. Codex keeps the monitored
+  diff, implementation files, tests, and sealed MECHANICAL evidence. Complete at
+  most two targeted reviews before first output; inspection remains read-only.
+  Pair-JUDGE output: emit JSONL findings then a bare terminal verdict line, or
+  emit only `PASS` when clean. `_shared/judge-output-parser.py` is the single
+  acceptance rule for pair output: JSONL findings, then a `# SUMMARY {json}`
+  line or a bare verdict line (`PASS` alone when clean); it ignores bare
+  code-fence lines and unwraps the registered Codex JSON envelope including its
+  narrated-preamble recovery (iter-0082), and binds a whole-message NDJSON
+  capture only through its uniquely attested terminal `end_turn` assistant
+  message (iter-0106); every other non-empty line blocks the pair source.
+  If the spec includes a solo-headroom hypothesis, one targeted review must use
+  the hypothesis's backticked observable command as its exact anchor and inspect
+  the complete sealed result (stdout/stderr/exit plus the full parsed output
+  object). Missing matching evidence is a coverage finding; do not substitute or
+  run a neighboring edge case. When the spec names exact keys, row shapes, JSON
+  object shape, or an exact error body, compare the sealed parsed key sets/deep
+  equality so aliased keys, missing keys, and extra keys are verdict-binding
+  failures. For priority/stateful specs, trace implementation code order for 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. Scope
+  qualifiers are binding for the pair judge too: do not reinterpret `inside a
+  warehouse`, `per resource`, or line-scoped rules as global rules. When both
+  priority ordering and rollback/blocked-interval behavior appear, perform this
+  dominance-loss code-order review first and confirm the sealed evidence covers
+  complete accepted/scheduled and rejected output ordering.
+
+Both resolved JUDGEs are read-only. Capture the primary reply as
+`.devlyn/<primary-engine>-judge.stdout` and its stderr sibling; never write the
+generic `.devlyn/verify-judge.stdout`. When the primary engine is Codex, invoke
+it only through this distinct monitored route:
+
+```bash
+CODEX_MONITORED_ISOLATED=1 CODEX_MONITORED_TIMEOUT_SEC=600 bash "$CODEX_MONITORED_PATH" -C "$PWD" -s read-only -c model_reasoning_effort=high "<primary prompt>" >.devlyn/codex-judge.stdout 2>.devlyn/codex-judge.stderr
+```
+
+This command supplies unconfigured defaults. Explicit judge profiles use
+`SKILL.md#explicit-role-dispatch` for validated model/effort options and
+round-scoped evidence. Omit bypass flags; do not pipe either stream. On primary exit
+124, write `.devlyn/verify.primary.timeout.json` with exactly
+`{"engine": "<resolved-primary-engine>", "budget_seconds": 600}` before merge. The
+marker is primary-only authority: malformed, wrong-engine, or wrong-budget
+content BLOCKs; a valid marker preserves all canonical primary findings and
+floors `judge` at `BLOCKED`, including when findings/stdout are empty. It never
+produces `PASS`, a solo verdict, or pair-style `TIMEOUT`; without the marker,
+existing missing/invalid primary-output behavior remains fail-closed.
+
+Codex pair-JUDGE keeps the monitored
 `codex-monitored.sh` route with
 `CODEX_MONITORED_ISOLATED=1 CODEX_MONITORED_TIMEOUT_SEC=600` and
-`-c model_reasoning_effort=medium`; isolation blocks user config, AGENTS.md,
+unconfigured default `-c model_reasoning_effort=medium`; isolation blocks user config, AGENTS.md,
 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.
 Every other resolved OTHER engine follows `_shared/adapters/<name>.md`
-`## Invocation`. Capture the result as `.devlyn/<name>-judge.stdout`, then run
+`## Invocation`. Capture the pair reply as `.devlyn/<other-engine>-judge.stdout`, then run
 `python3 "$DEVLYN_SHARED_DIR/collect-codex-findings.py" --devlyn-dir
-"<abs repo>/.devlyn" --stdout-file <name>-judge.stdout` before merge.
+"<abs repo>/.devlyn" --stdout-file <other-engine>-judge.stdout` before merge.
 The orchestrator writes the canonical `.devlyn/verify.pair.findings.jsonl`.
 The pair 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.
+read-only inspection, maximum two targeted reviews before first output, stop on
+the first verdict-binding finding, and emit PASS immediately after the bounded
+reviews pass.
 Raw stdout is diagnostic-only. A non-zero collector exit must write no
 canonical findings file: set the pair source to `BLOCKED` for
 `verify.pair.emission-contract`, and do not merge as though unparsed stdout were
@@ -228,12 +260,14 @@ nested inside, normalized string `sub_verdicts`. A judge subprocess exit
 124 is a budget abort: before merge, the orchestrator writes
 `.devlyn/verify.pair.timeout.json` with `{"engine": "<resolved name>",
 "budget_seconds": 600}`. Three cases are binding: marker plus no canonical pair
-findings and no parseable stdout findings records `pair_judge: "TIMEOUT"`,
-computes the merged verdict from mechanical plus primary judge, and surfaces
-`solo verdict after pair TIMEOUT` in the report header; marker plus canonical
-findings or parseable stdout findings binds those findings exactly as today,
-including the stdout emission contract; no marker preserves the existing
-`BLOCKED` contract for missing, empty, or uncaptured pair output. A budget
+findings and no stdout findings — including a capture the parser rejects solely
+because its message stream was truncated before the terminal result — records
+`pair_judge: "TIMEOUT"`, computes the merged verdict from mechanical plus
+primary judge, and surfaces `solo verdict after pair TIMEOUT` in the report
+header; marker plus canonical findings or parseable stdout findings binds those
+findings exactly as today, and every other parser rejection stays `BLOCKED`
+under the stdout emission contract; no marker preserves the existing `BLOCKED`
+contract for missing, empty, or uncaptured pair output. A budget
 abort is not an availability fallback; explicit-route availability still fails
 closed.
 
@@ -247,8 +281,8 @@ This deterministic merge is the routing source of truth for VERIFY. It writes
 `.devlyn/verify-merged.findings.jsonl`, `.devlyn/verify-merge.summary.json`, and
 updates `state.phases.verify.{verdict,sub_verdicts,merged}`. Branch on the
 merged state verdict, not on either model's prose verdict. Any HIGH/CRITICAL
-finding from either judge is `NEEDS_WORK`; a high-confidence MEDIUM must set
-`verdict_binding: true` to become `NEEDS_WORK`.
+finding from either judge is `NEEDS_WORK`; a MEDIUM must set literal
+`verdict_binding: true` to become `NEEDS_WORK`, regardless of confidence.
 
 Do not create, edit, truncate, or summarize `.devlyn/verify-merged.findings.jsonl`
 or `.devlyn/verify-merge.summary.json` by hand. Those files have exactly one
@@ -259,13 +293,15 @@ VERIFY to `BLOCKED`; do not synthesize merge artifacts in prose.
 
 <output>
 - `.devlyn/verify-mechanical.findings.jsonl` — MECHANICAL findings.
+- `.devlyn/spec-verify.results.json` plus its sealed VERIFY process-evidence manifest/raw streams — immutable JUDGE inputs.
 - `.devlyn/verify.findings.jsonl` — JUDGE findings.
 - `.devlyn/verify-merged.findings.jsonl` and `.devlyn/verify-merge.summary.json` — deterministic merge artifacts.
-- `phases.verify.{verdict, sub_verdicts, merged}` are written by `verify-merge-findings.py --write-state`, never by you (VERIFY agents have no code-mutation tools). `completed_at`/`duration_ms`/`artifacts` are recorded by the orchestrator via `state-phase-write.py` after this phase returns. `PASS` requires zero CRITICAL/HIGH findings, zero verdict-binding MEDIUM regressions, and coverage met.
+- `phases.verify.{verdict, sub_verdicts, merged}` are written by `verify-merge-findings.py --write-state`, never by you (VERIFY agents have no code-mutation tools). `completed_at`/`duration_ms`/`artifacts` are recorded by the orchestrator via `state-phase-write.py` after this phase returns. `PASS` requires zero CRITICAL/HIGH findings, zero verdict-binding MEDIUM findings, and coverage met.
 </output>
 
 <quality_bar>
 - Independence is structural (fresh context) and behavioral (no code mutation). Both must hold.
+- MECHANICAL is the sole verification executor; JUDGE performs sealed-evidence and clause/code-order review only.
 - Quote, do not paraphrase. Findings without quoted file:line evidence are excluded.
 - Coverage > confidence. Missing-evidence findings outrank a confident "looks fine."
 </quality_bar>

package/config/skills/devlyn:resolve/references/state-schema.md

@@ -15,6 +15,7 @@ Single authoritative verdict source for `/devlyn:resolve`. The orchestrator bran
   "complexity": null,
   "risk_profile": { "high_risk": false, "reasons": [], "risk_probes_enabled": false, "risk_probes_explicit": false, "pair_default_enabled": true },
   "risk_probes_digest": null,
+  "process_evidence": null,
   "base_ref": { "branch": "main", "sha": "abc123..." },
   "rounds": { "max_rounds": 4, "global": 0 },
   "bypasses": [],
@@ -53,8 +54,11 @@ Single authoritative verdict source for `/devlyn:resolve`. The orchestrator bran
 - **engine** — any engine name with a shipped adapter (`_shared/adapters/<name>.md`); `"claude"` and `"codex"` today. A required unavailable engine stops the run with `BLOCKED:<engine>-unavailable`.
 - **engine_source** — `"flag" | "engines.json" | "default"` — provenance of the resolved executor engine (`_shared/engine-preflight.md#role-resolution`). Optional on archived pre-iter-0038 runs; absent means `default`.
 - **source** — downstream contract provenance. Spec/verify-only set `type: "spec"`, `spec_path`, and `spec_sha256`. Free-form sets `type: "generated"`, `goal_path: ".devlyn/goal.raw.txt"` + exact-byte `goal_sha256`, and `criteria_path: ".devlyn/criteria.generated.md"` + raw-byte `criteria_sha256`. VERIFY re-checks its contract hash.
+- **`.devlyn/external-diff.patch` artifact** — verify-only input; the verifier consumes it only when `mode` is `"verify-only"` and fails closed if it exists in any other mode.
 - **risk_profile** — PHASE 0 routing state. `high_risk` controls automatic risk probes; `risk_probes_enabled` / `risk_probes_explicit` preserve their current semantics; `pair_default_enabled` is false only for explicit `--no-pair`. `risk_profile` must remain an object with boolean `high_risk`, `risk_probes_enabled`, `risk_probes_explicit`, and `pair_default_enabled` fields when present, plus `reasons` as a string list. Malformed state blocks VERIFY because it can hide required routes.
 - **risk_probes_digest** — top-level sha256 written by PHASE 1.5 after probe validation; BUILD_GATE/VERIFY replay semantics live in `phases/build-gate.md` step 4.
+- **process_evidence** — absent or JSON null for legacy runs and new runs with no captured obligation; otherwise an append-only array of `{phase, round, manifest: {path, sha256}, streams: [{id, stdout: {path, sha256}, stderr: {path, sha256}}]}` carriers. Paths are worktree-relative and live under `.devlyn/process-evidence/<run_id>/<phase>/round-<round>/`. A successful IMPLEMENT completion/transition validates every sibling `spec.expected.json.process_evidence[]` item declared for `phase: "implement"`, rehashes both raw streams (including zero-byte files), and appends the carrier before accepting the checkpoint. Missing, altered, escaping, duplicate-id, or expectation-mismatched evidence blocks without a state mutation. Later phases reuse the same carrier shape; no schema-major bump is required because readers must accept absent/null legacy state.
+- **base_ref.branch** — checked-out branch name, or `null` for a detached HEAD; `base_ref.sha` remains the exact immutable base in both states.
 - **rounds.global** — incremented every fix-loop pass (BUILD_GATE → fix-loop, VERIFY → fix-loop, OR a phase-gate fix respawn inside phase-gated IMPLEMENT).
 - **phases.implement.exec** — only on phase-gated large runs (plan.md has `## Execution phases` with >1 phase): `{ "total": N, "current": k, "statuses": ["PASS"|"FAIL"|null, ...], "commits": ["<sha>", ...] }`. Phase definitions live in plan.md (immutable contract); progress lives here (routing truth — never route on plan.md checkboxes). Absent on single-phase runs. `cumulative.patch` for such runs is `git diff <base_ref.sha>...HEAD`.
 - **phases.probe_derive** — optional PHASE 1.5 entry when `--risk-probes` is enabled. Artifacts include `.devlyn/risk-probes.jsonl`. Probe failures later surface through BUILD_GATE/VERIFY as `correctness.risk-probe-failed`, or as `correctness.verification-timeout` when the probe exceeds its verification budget.
@@ -88,10 +92,12 @@ Each entry under `phases.<name>` (for `plan`, `probe_derive`, `implement`, `surf
 }
 ```
 
-`history` is absent until a phase is re-entered. Immediately before re-entry overwrites the live `started_at`, `verdict`, `completed_at`, and `duration_ms`, `state-phase-write.py` appends those prior values as one object to `history[]`, creating the append-only array on first re-entry.
+`history` is absent until a phase is re-entered. Immediately before re-entry overwrites the live lifecycle, `state-phase-write.py` appends those prior values as one object to `history[]`, creating the append-only array on first re-entry. Codex worker history also retains its state-bound `invocation_receipt`; PLAN history retains the complete prompt/output receipt.
 
 - `verdict` — `"PASS" | "PASS_WITH_ISSUES" | "FAIL" | "NEEDS_WORK" | "BLOCKED"`. PHASE 6 (FINAL_REPORT) writes its own verdict per the terminal-verdict precedence.
-- `model_requested` / `model_effective` — `model_requested` is supplied by the orchestrator through `--model`; `model_effective` is parsed only from completion-time engine session evidence. Codex evidence accepts the `model: <id>` exec header or, for `.jsonl`, rollout `turn_context.payload.model`; Claude JSON output accepts a singleton `modelUsage` key or, for multiple entries, the sole key whose `inputTokens`, `outputTokens`, `cacheReadInputTokens`, and `cacheCreationInputTokens` exactly match top-level `usage.input_tokens`, `usage.output_tokens`, `usage.cache_read_input_tokens`, and `usage.cache_creation_input_tokens`. Missing or malformed counters, zero or multiple matches, and requested/effective mismatch fail closed: the phase verdict becomes `BLOCKED` and the completion command fails. For mutation phases, omission of `--engine-session-log` also fails closed when `.devlyn/<artifact-phase>.worker-session.<round>.jsonl` exists; the error names that retained file. Otherwise omission records `model_effective: null` and attests that the engine class exposed no session log for that invocation.
+- `model_requested` / `model_effective` — `model_requested` is supplied by the orchestrator through `--model`; schema-v3 completion cannot replace the spawn engine or requested model. Schema-v3 Codex PLAN/mutation/BUILD_GATE phases validate requested dispatch using the canonical `.devlyn/<phase>.invocation.<round>.json`; state rehashes the receipt, round-scoped prompt and worker session and cross-checks model, sandbox, prompt, run, phase, round and exit. A structured native model-reroute event or malformed JSONL blocks completion, even at exit0. The receipt proves argv delivery, so `model_effective` remains null; absence of a reroute is not positive model attestation. Arbitrary paths and plaintext `model:` headers are not evidence. Claude JSON output accepts a singleton `modelUsage` key or, for multiple entries, the sole key whose token counters exactly match top-level usage. Missing/malformed evidence and requested/effective mismatch fail closed: the phase verdict becomes `BLOCKED` and completion fails.
+- `output_sha256` — on schema-v3 PLAN completion, SHA-256 of exact `.devlyn/plan.md` bytes. Only caller-verdict BLOCKED with a lexically absent, never-bound plan records null; receipt/session attestation still applies. This terminal null permits only FINAL_REPORT lifecycle operations while the path remains lexically absent. Bound bytes are rehashed on later spawn/completion/transition, including BLOCKED; legal PLAN re-entry replaces the digest only at the new PLAN completion. FINAL_REPORT completion binds exact `.devlyn/final-report.md` bytes here and its canonical path in `artifacts.log_file`.
+- `invocation_receipt` — state-bound `{path, sha256, sandbox, sandbox_network_access, argv_sha256, exit_code}` for schema-v3 Codex PLAN/IMPLEMENT/BUILD_GATE/CLEANUP. Receipt schema 2.0 makes `sandbox` exactly `workspace-write`; `sandbox_network_access` is exactly `true` for BUILD_GATE and `false` for the other mutation phases. A missing CI capability or wider phase authority blocks before launch. Pre-2.0 receipts are intentionally rejected rather than migrated because they did not attest this capability; do not rewrite in-flight evidence. Continue through the owning session or start in a distinct worktree; restarting via explicit manual archive requires the operator to establish that prior writers stopped, never automatic archival to defeat admission refusal. A completed final report does not prove all interactive writers exited. The receipt is retained in history and rehashed before archive.
 - `triggered_by` — null on first run; one of `"build_gate" | "verify"` when the phase is a fix-loop respawn.
 - `pre_sha` — captured before SURFACE_CLOSE or CLEANUP. It bounds that phase's post-spawn diff and rollback.
 - `post_sha` — captured when SURFACE_CLOSE or CLEANUP completes; finish-gate subtracts CLEANUP's `pre_sha..post_sha` window.
@@ -105,10 +111,10 @@ Each entry under `phases.<name>` (for `plan`, `probe_derive`, `implement`, `surf
 
 Phase lifecycle (`started_at`/`completed_at`/`duration_ms`/`round`/`triggered_by`/`verdict`) is written by a deterministic script, never hand-edited JSON — a prior hand-edited fix-loop respawn left `started_at` stale, corrupting cross-phase ordering because `completed_at`/`round`/`triggered_by` advanced to the new round while `started_at` didn't. Phase workers report their verdict and artifact paths in their reply; they never edit `pipeline.state.json` themselves.
 
-1. **Spawn**: `state-phase-write.py --devlyn-dir .devlyn --phase <name> spawn --round <N> [--triggered-by build_gate|verify] [--pre-sha <sha>] [--engine <e>] [--model <requested-model>]`. Re-entry preserves lifecycle in `history[]`, resets owned fields, and leaves fields such as `phases.implement.exec`; VERIFY also clears prior-round files. SURFACE_CLOSE additionally requires `--model <requested-model> --input-patch-sha256 <hex> --prompt-sha256 <hex> --untracked-before-json <array>`; use `surface-check --authorized-surface-json <array>`, `surface-adjudication-recover --authorized-surface-json <array>` only after its adjudication-malformed result, `surface-rollback` for other failures, or `surface-skip` only for automatic Claude unavailability.
-2. **Transition** (normal direct handoff): `state-phase-write.py ... --phase <current> transition` takes the same completion/attestation arguments plus caller-specified `--next-phase`, `--next-round`, `--next-triggered-by`, `--next-engine`, `--next-model`, and next-phase metadata. It validates a fixed legal edge, applies complete plus spawn to a detached candidate, and replaces state once; either both lifecycle writes land or neither. The verb returns JSON paths/digests/state facts only and never chooses a phase, engine, branch, prompt, or agent.
-3. **Complete** (after the orchestrator reads the phase's reply and determines the verdict, when no next phase opens): `python3 "$DEVLYN_SHARED_DIR/state-phase-write.py" --devlyn-dir .devlyn --phase <name> complete --verdict <V> [--post-sha <sha>] [--findings-file <path>] [--log-file <path>] [--engine-session-log <path>]`. Pass the invocation's own session evidence whenever it exists; SURFACE_CLOSE passes `.devlyn/surface-close.output.json` as `--engine-session-log` so its `modelUsage` attests completion. Omission records `model_effective: null` only when the current phase/round has no retained worker-session file. Before completing a mutation phase (`implement`, `surface_close` when present, or `cleanup`), copy the exact session JSONL identified by that phase's dispatch receipt to `.devlyn/<artifact-phase>.worker-session.<round>.jsonl`, where `<artifact-phase>` is `implement`, `surface-close`, or `cleanup`; multiple rounds remain separate. Never discover or copy sessions by scanning an engine-global session directory. If that current-round file exists but `--engine-session-log` is omitted, completion fails closed and names the file. `duration_ms` is derived from the phase's own recorded `started_at` — it cannot drift from `completed_at`. `--verdict` is required for every phase except VERIFY: `verify-merge-findings.py --write-state` is the sole normal writer of `phases.verify.verdict`, so `complete verify` is always called without `--verdict` (an explicit one is rejected) and preserves what's already on disk; model-attestation failure still forces the phase to `BLOCKED`.
-4. **Before archive** (PHASE 6 step 5): `phases.final_report.verdict` must be non-null. Archive prune skips runs whose final_report verdict is null (treated as in-flight).
+1. **Spawn**: `state-phase-write.py --devlyn-dir .devlyn --phase <name> spawn --round <N> [--triggered-by build_gate|verify] [--pre-sha <sha>] [--engine <e>] [--model <requested-model>] [--prompt-sha256 <hex>]`. Re-entry preserves lifecycle/receipts in `history[]`, resets owned fields, and leaves fields such as `phases.implement.exec`; VERIFY also clears prior-round files. Schema-v3 Codex IMPLEMENT/BUILD_GATE/CLEANUP requires the requested model and prompt digest; an inherited top-level Codex engine is persisted into the phase rather than becoming an unattested null route. SURFACE_CLOSE inherits native Claude model settings when `--model` is omitted and rejects explicit blank models; it additionally requires `--input-patch-sha256 <hex> --prompt-sha256 <hex> --untracked-before-json <array>`; use `surface-check --authorized-surface-json <array>`, `surface-adjudication-recover --authorized-surface-json <array>` only after its adjudication-malformed result, `surface-rollback` for other failures, or `surface-skip` only for automatic Claude unavailability.
+2. **Transition** (normal direct handoff): `state-phase-write.py ... --phase <current> transition` takes the same completion/attestation arguments plus caller-specified `--next-phase`, `--next-round`, `--next-triggered-by`, `--next-engine`, `--next-model`, and next-phase metadata. It validates a fixed legal edge, applies complete plus spawn to a detached candidate, and replaces state once; either both lifecycle writes land or neither. A passing IMPLEMENT edge first validates and binds all declared process evidence through `_shared/process-evidence.py`. The verb returns JSON paths/digests/state facts only and never chooses a phase, engine, branch, prompt, or agent.
+3. **Complete** (after the orchestrator reads the phase's reply and determines the verdict, when no next phase opens): `python3 "$DEVLYN_SHARED_DIR/state-phase-write.py" --devlyn-dir .devlyn --phase <name> complete --verdict <V> [--post-sha <sha>] [--findings-file <path>] [--log-file <path>] [--engine-session-log <path>]`. Pass only the phase/round canonical worker session. SURFACE_CLOSE requires `.devlyn/surface-close.output.json` even for inherited model selection (`model_requested=null`); native JSON supplies `model_effective`, and missing/malformed evidence or an explicit model mismatch blocks completion; schema-v3 Codex PLAN/IMPLEMENT/BUILD_GATE/CLEANUP passes the wrapper-captured `.devlyn/<phase>.worker-session.<round>.jsonl` and requires its sibling invocation receipt plus `.devlyn/<phase>.prompt.<round>`. Never scan an engine-global session directory or synthesize a model header. `duration_ms` is derived from the phase's own `started_at`. `--verdict` is required except VERIFY, whose verdict remains owned by `verify-merge-findings.py --write-state`.
+4. **Before archive** (PHASE 6 step 5): write `.devlyn/final-report.md` with exactly one first-line `<!-- devlyn:final-report run_id=<current state.run_id> -->` and a non-whitespace body, then complete FINAL_REPORT with `--log-file .devlyn/final-report.md`. Missing, unsafe, empty or mismatched report input fails before completion; the marker proves run identity, not semantic completeness. This also applies to BLOCKED missing-PLAN-output closure. Archive rehashes a present FINAL_REPORT `output_sha256` binding before any move; missing/altered files or malformed/null bindings fail without moving artifacts. Historical states with that field absent retain existing archive behavior. Archive prune skips runs whose final_report verdict is null (treated as in-flight).
 
 ## Terminal verdict (PHASE 6)
 
@@ -116,7 +122,7 @@ Precedence:
 
 1. finish-gate exit 1 or 2 → `BLOCKED:finish-gate-unclean`; `phases.<any>.verdict == "BLOCKED"` → terminal `BLOCKED:<reason>`.
 2. `phases.verify.verdict == "NEEDS_WORK"` after fix-loop exhaustion → terminal `NEEDS_WORK`.
-3. `phases.verify.verdict == "PASS_WITH_ISSUES"` or finish-gate findings file present → terminal `PASS_WITH_ISSUES`.
+3. `phases.verify.verdict == "PASS_WITH_ISSUES"` → terminal `PASS_WITH_ISSUES`; any finish-gate offender → `BLOCKED:finish-gate-unclean` under precedence 1.
 4. `phases.verify.verdict == "PASS"` → terminal `PASS`.
 5. Verify-only mode: terminal = `phases.verify.verdict` directly (PHASE 1-4 are skipped).
 
@@ -132,4 +138,12 @@ Follow-up notes: when `phases.surface_close.continued_after_block` is true, exac
 
 ## Archive contract
 
-PHASE 6 step 4 moves `PER_RUN_PATTERNS` into `.devlyn/runs/<run_id>/`, including Goal, SURFACE_CLOSE patch/prompt/reply, and mutation worker-session JSONL; it never scans engine-global sessions. Machine config stays; the last 10 completed runs remain. Archive/prune failure does not change verdict.
+PHASE 6 step 4 moves `PER_RUN_PATTERNS` plus every state-bound process manifest/raw stream and invocation receipt into `.devlyn/runs/<run_id>/`, preserving relative layout and rehashing each bound digest first. It includes every phase/round prompt and worker session, including BUILD_GATE, and revalidates the receipt's internal prompt/session digests; it never scans engine-global sessions. Unsafe paths, symlinks, missing files, digest mismatches, and destination collisions block archive visibly without changing the already-derived product verdict. Machine config stays; the last 10 completed runs remain.
+
+## Explicit role configuration
+
+PHASE0 `state-phase-write.py --freeze-roles --default-engine <orchestrator-default>` freezes `role_resolution` (legacy engine/source, three role entries, input paths/digests, snapshot digest). `role_config_input` holds only the validated per-run roles object and provenance; `role_no_pair` records that flag. No config reread after freezing. Missing legacy snapshots are compatible; present null/malformed snapshots fail. The helper does not launch models.
+
+`state.engine` remains the legacy executor for unchanged PLAN/BUILD/probe routing. IMPLEMENT/CLEANUP spawn enforce frozen worker engine/model. VERIFY spawn explicitly records the primary in `phases.verify.engine`; merge, timeout and OTHER exclusion use it, falling back only when absent. Requested settings are distinct from native-observed fields. Explicit Codex worker effort binds `role_argv` against the existing invocation argv digest; effort remains dispatch evidence, not provider-internal attestation.
+
+Successful explicit judges retain `<engine>-judge.r<round>.*` raw/prompt/argv/derived/evidence files; `verify.role_evidence` binds their hashes, observed model/nullable effort and named evidence basis. VERIFY history preserves those bindings. Merge alone binds successful evidence; archive rehashes every bound artifact. Canonical `<engine>-judge.stdout` is the current collector input and is never substituted for the immutable round raw. Failed raw remains diagnostic and cannot become a successful binding.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "2.10.1",
+  "version": "3.0.0",
   "description": "Loop & harness engineering for AI coding agents (Claude Code, Codex, and any AGENTS.md-driven agent) — take intent to shipped, engineer-quality software hands-free with phase-gated pipelines and agent orchestration",
   "homepage": "https://github.com/fysoul17/devlyn-cli#readme",
   "bin": {
@@ -33,10 +33,14 @@
     "benchmark/auto-resolve/results/20260510-f16-f23-f25-combined-proof/headroom-gate.json",
     "benchmark/auto-resolve/results/20260510-f16-f23-f25-combined-proof/full-pipeline-pair-gate.md",
     "benchmark/auto-resolve/results/20260510-f16-f23-f25-combined-proof/full-pipeline-pair-gate.json",
+    "benchmark/auto-resolve/results/20260510-f16-f23-f25-combined-proof/F16-cli-quote-tax-rules/l2_risk_probes/result.json",
+    "benchmark/auto-resolve/results/20260510-f16-f23-f25-combined-proof/F23-cli-fulfillment-wave/l2_risk_probes/result.json",
+    "benchmark/auto-resolve/results/20260510-f16-f23-f25-combined-proof/F25-cli-cart-promotion-rules/l2_risk_probes/result.json",
     "benchmark/auto-resolve/results/20260511-f21-current-riskprobes-v1/headroom-gate.md",
     "benchmark/auto-resolve/results/20260511-f21-current-riskprobes-v1/headroom-gate.json",
     "benchmark/auto-resolve/results/20260511-f21-current-riskprobes-v1/full-pipeline-pair-gate.md",
     "benchmark/auto-resolve/results/20260511-f21-current-riskprobes-v1/full-pipeline-pair-gate.json",
+    "benchmark/auto-resolve/results/20260511-f21-current-riskprobes-v1/F21-cli-scheduler-priority/l2_risk_probes/result.json",
     "benchmark/auto-resolve/results/20260507-f10-f11-tier1-full-pipeline/headroom-gate.md",
     "benchmark/auto-resolve/results/20260507-f10-f11-tier1-full-pipeline/headroom-gate.json",
     "benchmark/auto-resolve/results/20260508-f22-exact-error-headroom/headroom-gate.md",