devlyn-cli 4.1.0 → 4.2.0

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

@@ -1,310 +0,0 @@
-# PHASE 5 — VERIFY (canonical body, fresh worker context)
-
-Per-engine adapter header is prepended at runtime. **You are spawned with empty conversation context.** No carry-over from PLAN / IMPLEMENT / BUILD_GATE / CLEANUP. This is the structural guarantee of independence — the prompt body reinforces it but the spawn is what makes it real. If the orchestrator cannot provide a fresh worker, VERIFY must be `BLOCKED:fresh-context-unavailable`; same-context review is forbidden.
-
-<role>
-Independent quality layer. You answer one question: did the diff deliver what the spec said it would, with no scope creep, no quality regression, and no constraint violation? You produce findings only — you have no code-mutation tools.
-</role>
-
-<input>
-- `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 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, emit a verdict-binding finding with reason `source_sha256_mismatch` and terminal verdict `BLOCKED`, then stop reviewing without editing state.
-- `.devlyn/spec-verify.results.json` plus any required 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. Valid pure-design
-  contracts with no executable obligations have `commands: []` and
-  `process_evidence: null`.
-
-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)
-
-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`, and writes `.devlyn/spec-verify.results.json` with a VERIFY process-evidence carrier.
-
-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)
-
-On the constrained Windows read route, the orchestrator supplies the complete spec/expected contract, accepted source SHA/diff, relevant source/tests with file:line locators, and validated sealed MECHANICAL results/manifests/required raw streams inline. Judge that supplied evidence without running tools. Missing, truncated or unbound inputs produce a verdict-binding BLOCKED finding. Retain fresh context, read-only sandbox, isolation, model/effort and bounded output; never widen permissions. This route addresses observed policy-denied reads, not a universal Windows sandbox limitation.
-
-Grade the diff against the spec on rubric axes:
-
-- **Spec compliance** — does cited evidence show how every applicable Requirement and Constraint is satisfied?
-- **Scope** — does the diff touch only files PLAN listed (or the cleanup allowlist)? Out-of-scope file = HIGH finding `scope.out-of-scope-violation`.
-- **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 and Constraint 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 and Constraint into its binding clauses before
-you pass it. Words like `before`, `after`, `once`, `always`, `never`,
-`regardless`, `irrelevant`, `permanent`, `idempotent`, `duplicate`, `raw`, and
-`signature` usually encode a separate invariant. A passing verification command
-proves only the case it actually exercises; it does not prove neighboring
-clauses. For stateful, auth, parsing, idempotency, rollback, and error-priority
-flows, construct at least one counterexample in your head and trace the code
-order, including failed-operation rollback and the next entity's state. If the
-code order can return the wrong status/body/output for a binding clause, emit a
-HIGH spec-compliance finding even when the provided verifier passes.
-
-Respect each clause's scope qualifiers. Do not widen an invariant beyond the
-words in the spec: `inside a warehouse`, `per resource`, `for this line`,
-`after validation`, and similar qualifiers are binding. When two ordering rules
-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.
-
-**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 +
-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.
-
-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**: account for every applicable Requirement and Constraint using sealed MECHANICAL evidence for required executable checks and cited source/design evidence for pure-design clauses or explicitly retained source-review obligations. Inspect applicable unchanged code and documentation; absence of a code change alone is not missing coverage. Source review never substitutes for required executable coverage. For any unsupported clause, emit a verdict-binding coverage finding identifying the missing evidence. JUDGE does not run checks or edit state; the orchestrator records `state.verify.coverage_failed: true` from coverage findings before merge.
-
-**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.
-
-### Pair-mode (default when OTHER engine is available)
-
-MECHANICAL runs first. A verdict-binding blocker routes to the fix loop without
-either judge and records `pair_judge: null`. After it passes, honor `--no-pair`;
-otherwise resolve the OTHER-engine route. An explicit `--pair-verify` is an
-availability promise: an unavailable OTHER engine BLOCKs. An automatic route
-with no OTHER engine records `auto_pair_other_engine_unavailable` and continues
-solo.
-
-When the OTHER engine is available, write `pair_trigger` at judge-spawn time
-with `pair.default` plus every applicable outcome-independent canonical reason,
-then dispatch the primary and pair JUDGEs concurrently against the same frozen
-diff via foreground parallel dispatch, never background shells. A primary blocker does not cancel the pair-JUDGE; both finding sets join the same VERIFY invocation 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.
-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`,
-`complexity.large`, `spec.complexity.high`, `spec.complexity.large`,
-`spec.solo_headroom_hypothesis`, `risk.high`, `risk_probes.enabled`,
-`risk_probes.present`, `coverage.failed`, `mechanical.warning`, and
-`judge.warning`.
-
-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. The merge
-blocks malformed state because it can hide a required route.
-
-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`.
-
-When the OTHER engine is available, persist this before either judge starts:
-
-```json
-"pair_trigger": {
-  "eligible": true,
-  "reasons": ["pair.default", "complexity.high"],
-  "skipped_reason": null
-}
-```
-
-After both judges return, append every applicable outcome-dependent reason
-(`coverage.failed`, `mechanical.warning`, `judge.warning`) before merge. Eligible schema-v3 state must contain `pair.default` and every other applicable canonical
-reason. The OTHER-engine judge is mandatory; missing output is a contract
-violation.
-
-`pair_trigger` remains strict: eligible state has canonical reasons and no skip;
-ineligible state has empty reasons and one of `user_no_pair`,
-`mechanical_blocker`, `auto_pair_other_engine_unavailable`, or null.
-`primary_judge_blocker` is parser-recognized only for archived v2.0 replay and
-retains the existing rejection when a pre-known reason applied. New runs never
-write it. The `--engine` flag does not disable default pairing.
-
-Run the shared availability pre-flight before spawn. Explicit `--pair-verify`
-unavailability stays `BLOCKED:<engine>-unavailable` with setup guidance.
-Automatic unavailability records `auto_pair_other_engine_unavailable` and runs
-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 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:
-  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`, `.agents/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 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.
-  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
-DEVLYN_CODEX_PROMPT_FILE="<primary-prompt-file>" CODEX_MONITORED_ISOLATED=1 CODEX_MONITORED_TIMEOUT_SEC=600 bash "$CODEX_MONITORED_PATH" -C "$PWD" -s read-only -c model_reasoning_effort=high - >.devlyn/codex-judge.stdout 2>.devlyn/codex-judge.stderr
-```
-
-Write the complete prompt to the named file as exact UTF-8 bytes before launch and retain its generated `.transport.json` carrier. 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 sets `DEVLYN_CODEX_PROMPT_FILE="<pair-prompt-file>"` with sole prompt `-` and keeps the monitored
-`codex-monitored.sh` route with
-`CODEX_MONITORED_ISOLATED=1 CODEX_MONITORED_TIMEOUT_SEC=600` and
-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 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 <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,
-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
-only a diagnostic. Do not ask the judge to edit `.devlyn`.
-
-Both pair-judge directions are wall-budgeted at 600s. The orchestrator records
-`state.phases.verify.judge_durations_ms: {"judge": <int>, "pair_judge": <int|null>}`
-as it collects each judge result; these wall durations are siblings of, never
-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 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.
-
-After all VERIFY findings files are written, run:
-
-```bash
-python3 "$DEVLYN_SHARED_DIR/verify-merge-findings.py" --write-state
-```
-
-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. Absent a BLOCKED source, any HIGH/CRITICAL
-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
-writer: `verify-merge-findings.py`. If that command fails, preserve stderr and set
-VERIFY to `BLOCKED`; do not synthesize merge artifacts in prose.
-
-</sub_phases>
-
-<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 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>
-
-<runtime_principles>
-VERIFY's discipline is "the spec is the contract, the diff is the evidence, the verdict is the comparison."
-</runtime_principles>

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

@@ -1,152 +0,0 @@
-# pipeline.state.json schema
-
-Single authoritative verdict source for `/devlyn-resolve`. The orchestrator branches on `state.phases.<name>.verdict` directly — never parses `.devlyn/*.findings.jsonl` for routing. Living document; bump `version` on a breaking change.
-
-## Top-level shape
-
-```json
-{
-  "version": "3.0",
-  "run_id": "rs-<UTC-timestamp>-<12-hex>",
-  "started_at": "2026-04-30T12:00:00Z",
-  "engine": "claude",
-  "mode": "spec",
-  "pair_verify": false,
-  "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": [],
-  "implement_passed_sha": null,
-  "source": {
-    "type": "spec",
-    "spec_path": "docs/roadmap/phase-1/X.md",
-    "spec_sha256": "...",
-    "criteria_path": null,
-    "criteria_sha256": null
-  },
-  "criteria": [
-    { "id": "C1", "ref": "spec://requirements/0", "status": "pending", "evidence": [], "failed_by_finding_ids": [] }
-  ],
-  "phases": {
-    "plan": null,
-    "probe_derive": null,
-    "implement": null,
-    "surface_close": null,
-    "build_gate": null,
-    "cleanup": null,
-    "verify": null,
-    "final_report": null
-  },
-  "verify": { "coverage_failed": false, "pair_trigger": null }
-}
-```
-
-## Field rules
-
-- **version** — string. Bump major on a breaking schema change.
-- **session_id** — optional string or null stamped from `CLAUDE_CODE_SESSION_ID`; a missing/null value leaves Stop-hook pressure inert.
-- **mode** — `"free-form" | "spec" | "verify-only"`.
-- **pair_verify** — boolean. True only for `--pair-verify`. Pairing is already default-when-available; this flag makes OTHER-engine availability an explicit fail-closed promise and adds `mode.pair-verify` telemetry. It is mutually exclusive with `risk_profile.pair_default_enabled == false` from `--no-pair`.
-- **complexity** — `null | "trivial" | "medium" | "large"`. Free-form mode populates this; spec/verify-only mode leaves it null.
-- **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 Git patch with `a/` and `b/` path prefixes (`git diff --binary --src-prefix=a/ --dst-prefix=b/`). A zero-byte file means no changes; file-path checks reject malformed or other-prefix input. File exclusions cover both names in rename/copy headers. The verifier fails closed if the artifact exists outside `"verify-only"` 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** — repair IMPLEMENT admissions committed by `state-phase-write.py`, independent of invocation `round`; `max_rounds` defaults to 4. Normal phased advancement uses a fresh IMPLEMENT invocation round without a repair charge. Downstream phases carry the current IMPLEMENT round, or zero before 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>", ...] }`. Persist the current status as FAIL on every failed gate and retain current until PASS. 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.
-- **phases.surface_close** — generated trivial/medium one-shot: `pre_sha`, `input_patch_sha256`, assembled-byte `prompt_sha256`, `untracked_before`; spawn requires Claude plus a requested model, and `surface-check` gates PASS. `.devlyn/surface-close.output.json` retains the Claude JSON wrapper used for completion attestation while the round JSONL remains the execution-audit backstop. Automatic Claude unavailability alone records null verdict plus `skipped_reason: "auto_surface_close_claude_unavailable"`. After an adjudication-malformed reply only, successful rollback plus transcript write-audit records the two nonterminal fields `skipped_reason: "surface_close_rolled_back_adjudication_malformed"` and `continued_after_block: true`; neither creates a terminal floor. Other failures store bare `"BLOCKED"`. `durability[]` is append-only: `{round, origin_phase, receipt_path, receipt_sha256, restore_commit_sha}` per `.devlyn/closure-durability.round-<n>.json`.
-- **bypasses** — array of phase names from `--bypass`. Valid: `"build-gate" | "cleanup"`. PLAN, IMPLEMENT, VERIFY are non-bypassable (orchestrator rejects at parse time).
-- **implement_passed_sha** — captured at end of PHASE 2; null until then. Activates the post-implement invariant for SURFACE_CLOSE, CLEANUP, and VERIFY.
-- **criteria** — generated from spec's `## Requirements` checklist (one per `- [ ]`). `status: pending → implemented` is the legal transition. `failed_by_finding_ids` populates when VERIFY surfaces a finding tied to a criterion.
-- **`.devlyn/untracked.baseline` artifact** — written at PHASE 0 (`spec-verify-check.py --write-untracked-baseline`); BUILD_GATE flags created-during-run unauthorized untracked files against it (`.devlyn/` exempt; semantics in `phases/build-gate.md` step 4).
-- **verify.coverage_failed** — outcome-dependent telemetry set by the orchestrator when JUDGE reports missing clause evidence. It no longer gates pair dispatch: after MECHANICAL passes, `pair.default` dispatches both judges concurrently whenever `pair_default_enabled != false` and the OTHER engine is available. An orchestrator without foreground parallel dispatch runs the same two required judges sequentially; a primary blocker never skips the pair. A verdict-binding MECHANICAL blocker still skips both. Legacy complexity values remain accepted only for archived compatibility.
-- **verify.pair_trigger** — strict decision state: `{ "eligible": boolean, "reasons": string[], "skipped_reason": string|null }`. Schema v3.0 eligible state requires `pair.default` plus every applicable telemetry reason and `skipped_reason: null`; outcome-dependent reasons are appended after both judges return. Canonical reasons are `pair.default`, `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`, and `judge.warning`. Ineligible new-run state has empty reasons and only `user_no_pair`, `mechanical_blocker`, `auto_pair_other_engine_unavailable`, or null; `primary_judge_blocker` remains parser-recognized only for archived v2.0 replay and retains its existing pre-known-reason rejection. Explicit `mode.pair-verify` cannot use the unavailable-engine skip. Missing, contradictory, incomplete, or unknown trigger state BLOCKs VERIFY.
-
-## Per-phase shape
-
-Each entry under `phases.<name>` (for `plan`, `probe_derive`, `implement`, `surface_close`, `build_gate`, `cleanup`, `verify`, `final_report`):
-
-```json
-{
-  "started_at": "2026-04-30T12:00:01Z",
-  "completed_at": "2026-04-30T12:00:30Z",
-  "duration_ms": 29000,
-  "round": 0,
-  "triggered_by": null,
-  "verdict": "PASS",
-  "engine": "claude",
-  "model_requested": "<orchestrator-selected model id or null>",
-  "model_effective": "<session-attested model id or null>",
-  "pre_sha": null,
-  "post_sha": null,
-  "artifacts": { "findings_file": null, "log_file": null },
-  "sub_verdicts": null
-}
-```
-
-`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. Owner phase history preserves output/checkpoint digests, its round and present execution kind/worker provenance; historical absence of the kind remains absent.
-
-- `verdict` — ordinary phases use `"PASS" | "PASS_WITH_ISSUES" | "FAIL" | "NEEDS_WORK" | "BLOCKED"`; FINAL_REPORT persists the full terminal verdict, including `BLOCKED:<reason>`.
-- `execution_kind` — owner PLAN uses `"orchestrator_context"`; owner BUILD_GATE/CLEANUP use `"orchestrator_commands"`, null engine/model fields and no worker prompt, receipt or role identity. Worker claims and current-round worker artifacts are rejected. Already-open absent-kind spans retain historical receipt validation; unknown or null kinds fail closed.
-- `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 IMPLEMENT and historical worker PLAN/CLEANUP/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 IMPLEMENT and historical worker PLAN/CLEANUP/BUILD_GATE. 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 IMPLEMENT, phased advancement and phase-gate repair; an IMPLEMENT re-entry already carrying `"cleanup"` retains it when either path supplies null. Downstream repair records `"build_gate" | "cleanup" | "verify"`.
-- `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.
-- `sub_verdicts` — only populated for VERIFY: `{ "mechanical": "PASS|FAIL", "judge": "PASS|...", "pair_judge": "PASS|..." | "TIMEOUT" | null }`. Values are normalized by `verify-merge-findings.py`; model prose verdicts cannot upgrade or downgrade the deterministic findings-derived verdict. `sub_verdicts.pair_judge` is `"TIMEOUT"` when a pair judge exceeded its wall budget and a valid `.devlyn/verify.pair.timeout.json` marker was read — semantics in `references/phases/verify.md` (pair budget section).
-- `judge_durations_ms` — only populated for VERIFY: `{ "judge": <non-negative int>, "pair_judge": <non-negative int|null> }`. The orchestrator writes each wall duration when it collects that judge's result; values remain a sibling of `sub_verdicts`, whose values stay normalized strings. VERIFY spawn resets this key to null so re-entry cannot retain prior-round timings.
-- `merged` — only populated for VERIFY after `verify-merge-findings.py --write-state`: `{ "verdict": "...", "findings_file": ".devlyn/verify-merged.findings.jsonl", "summary_file": ".devlyn/verify-merge.summary.json" }`.
-- `pair_trigger` — only populated for VERIFY; same shape as top-level `verify.pair_trigger` when the phase stores it locally.
-- `correctness.risk-probe-failed` — emitted by `spec-verify-check.py --include-risk-probes` when an executable probe derived from the visible `## Verification` section fails.
-
-## Write protocol
-
-Every non-self-test writer command, including role freezing, holds `.devlyn/pipeline.state.lock` before state read through final write or artifact clearing. `verify-merge-findings.py --write-state` holds the same lock across findings read, merge and state write. Use one Python command to acquire `platform-support.py.file_lock(..., blocking=True)`, reread state, update `exec`, atomically replace state, and release before invoking the CLI. No nested lock or unlocked fallback.
-
-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**: IMPLEMENT admission selects the greatest started `(round, phase-order)` among IMPLEMENT, BUILD_GATE, CLEANUP, VERIFY. A complete BUILD_GATE/CLEANUP FAIL, merged VERIFY NEEDS_WORK, or current IMPLEMENT gate FAIL admits one charged repair with the exact trigger; a completed phased IMPLEMENT with all preceding statuses PASS and current status null admits uncharged advancement. Both paths require the next invocation round. Counter validation and increment happen under the state lock, and refusal preserves original state bytes. `state-phase-write.py --devlyn-dir .devlyn --phase <name> spawn --round <N> [--triggered-by build_gate|cleanup|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. Owner PLAN/BUILD_GATE/CLEANUP spans omit engine/model/prompt arguments. Metadata-bearing PLAN/CLEANUP calls retain the legacy worker API; owner spans cannot be relabeled as workers. Successful owner CLEANUP requires pre/post SHA equality, unchanged HEAD/tracked source and no new untracked files versus the baseline; failure closure preserves the observed delta; code/doc cleanup belongs to the selected IMPLEMENT invocation. Schema-v3 Codex IMPLEMENT and historical worker 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 IMPLEMENT and historical worker PLAN/BUILD_GATE/CLEANUP pass 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)
-
-Precedence:
-
-1. finish-gate exit 1 or 2 → `BLOCKED:finish-gate-unclean`; `phases.<any>.verdict == "BLOCKED"` → terminal `BLOCKED:<reason>`.
-2. A refused shared repair admission with exhausted counters and current failing predecessor: VERIFY `NEEDS_WORK` → terminal `NEEDS_WORK`; BUILD_GATE/CLEANUP/phase-gate FAIL → `BLOCKED:repair-budget-exhausted`. Close a still-open predecessor after refused transition (`FAIL` for pre-VERIFY, no `--verdict` for VERIFY), preserve findings, then open FINAL_REPORT. Evaluate current-round exhaustion before any older VERIFY result.
-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).
-
-## Final-report shape
-
-Header: `run_id | engine | mode | complexity | verdict | wall_time_s`.
-
-Per-phase summary table: `phase | verdict | duration_ms | round | triggered_by | findings_count`; include SURFACE_CLOSE when run or skipped and identify new BUILD_GATE as orchestrator commands with no separate model.
-
-Findings table: each emitted finding's `severity | rule_id | file:line | message | confidence`.
-
-Follow-up notes: when `phases.surface_close.continued_after_block` is true, exactly one explicit `pipeline continued to BUILD_GATE — surface_close_rolled_back_adjudication_malformed` line (never a terminal floor); any large-mode assumptions; any pair-judge TIMEOUT surfaced as `solo verdict after pair TIMEOUT`; pair/risk-probe opt-out state; engine setup guidance for `BLOCKED:<engine>-unavailable`; and any `state.verify.coverage_failed` axes.
-
-## Archive contract
-
-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; PLAN stays orchestrator-fixed, BUILD runs orchestrator commands, and probe routing is unchanged. IMPLEMENT (including code/doc cleanup) and historical worker CLEANUP enforce frozen worker engine/model. Owner CLEANUP does not claim that identity. 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.