devlyn-cli 2.3.0 → 2.3.2

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

@@ -82,7 +82,7 @@ The elicitation agent:
 5. Stops when the structural lint passes AND user confirms, or 8 turns elapsed.
 
 Structural lint (inline check, no script needed):
-- Frontmatter has `id`, `title`, `kind`, `status: planned`.
+- Frontmatter has `id`, `title`, `kind`, `status: planned`, `complexity`.
 - `## Context` non-empty (≥ 1 sentence).
 - `## Requirements` has ≥ 1 `- [ ]` bullet.
 - `## Out of Scope` present (may list "none" if truly nothing).
@@ -91,8 +91,9 @@ Structural lint (inline check, no script needed):
 After lint passes:
 1. Write `<spec-dir>/<id>-<slug>/spec.md` (the spec).
 2. Generate `<spec-dir>/<id>-<slug>/spec.expected.json` from the spec's `## Verification` block + any `forbidden_patterns` / `required_files` / `forbidden_files` / `max_deps_added` the conversation surfaced.
-3. Run `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` to validate the verification carrier shape. If exit 2, fix the carrier and re-run.
-4. Print: `spec ready — /devlyn:resolve --spec <spec-path>`.
+3. Run `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` to validate the verification carrier shape, supported `complexity` frontmatter, and any present actionable solo-headroom hypothesis; if the spec uses a legacy inline `## Verification` JSON carrier, any solo-headroom hypothesis command must match that carrier's `verification_commands[].cmd`. If exit 2, fix the carrier/frontmatter/hypothesis and re-run.
+4. Run `python3 .claude/skills/_shared/spec-verify-check.py --check-expected <expected-path>` to validate sibling `spec.expected.json` against `_shared/expected.schema.json` plus sibling spec `complexity` frontmatter and any present actionable solo-headroom hypothesis; if the spec has a solo-headroom hypothesis, its observable command must match `spec.expected.json.verification_commands[].cmd`. If exit 2, fix the JSON/frontmatter/hypothesis and re-run.
+5. Print: `spec ready — /devlyn:resolve --spec <spec-path>`.
 
 ## PHASE 1Q: QUICK MODE
 
@@ -103,6 +104,7 @@ Single-turn assume-and-confirm. Prompt body: see `references/elicitation.md` §
 3. User responds with "go" / "fix X" / "no, different".
 4. On "go": write spec + spec.expected.json + lint + announce.
 5. On "fix X": apply correction, re-show, ask again. Maximum 3 correction rounds before escalating to default mode.
+6. Exception: for benchmark, risk-probe, or pair-evidence goals, do not infer a solo-headroom hypothesis. Ask for the actionable hypothesis first; if unavailable, exit with `spec not ready — solo-headroom hypothesis required`. For new unmeasured benchmark, shadow-fixture, golden-fixture, risk-probe, or pair-evidence candidates, also do not infer solo ceiling avoidance; ask for the concrete difference from rejected or solo-saturated controls such as `S2`-`S6`, and exit with `spec not ready — solo ceiling avoidance required` if unavailable.
 
 ## PHASE 1F: FROM-SPEC MODE
 
@@ -114,7 +116,8 @@ Prompt body: `references/from-spec-mode.md`.
 4. Apply structural fixes only — do NOT reshape Requirements / Out-of-Scope content. The user's substantive intent is preserved.
 5. Generate `spec.expected.json` if absent (best-effort from `## Verification` block).
 6. Write the normalized spec back to `<spec-dir>/<id>-<slug>/` (preserves original at `<path>` untouched unless user passes `--in-place`).
-7. Lint pass → announce. Lint fail → surface the unfixable issue and exit non-zero.
+7. Run both lint checks: `--check <spec-path>` and `--check-expected <expected-path>`.
+8. Lint pass → announce. Lint fail → surface the unfixable issue and exit non-zero. If the source is a pair-evidence candidate without an actionable solo-headroom hypothesis, the announcement must say `pair-evidence not ready` instead of implying measurement readiness.
 
 ## PHASE 1P: PROJECT MODE
 

package/config/skills/devlyn:ideate/references/elicitation.md

@@ -30,7 +30,37 @@ For most coding tasks, the under-specified blanks are:
 3. **Failure shape**: what happens on bad input? Exit code, error message format, fallback behavior (silent vs visible)?
 4. **Scope boundary**: which files are in-scope, which are out-of-scope? "Don't touch the auth module" is a boundary worth surfacing.
 5. **Constraints**: dependency policy (new deps allowed?), silent-catch policy, type-system escape policy, test coverage expectations.
-6. **Verification**: how does the user know it worked? Pick the smallest concrete check.
+6. **Complexity signal**: set spec frontmatter `complexity` to `high` when
+   the spec needs a compound scenario crossing state mutation with ordering,
+   idempotency, auth/error priority, rollback/failure handling, or exact output
+   shape. This is a downstream VERIFY pair-trigger signal, not a vague
+   difficulty label.
+7. **Verification**: how does the user know it worked? Pick the smallest concrete check.
+   If the goal combines state mutation with ordering/priority, idempotency,
+   auth/error priority, or exact output shape, ask for one concrete compound
+   scenario that exercises the interaction end-to-end instead of accepting only
+   isolated happy-path checks.
+8. **Pair-candidate headroom**: when the user is creating a benchmark, risk
+   probe, or pair-evidence candidate, ask for one solo-headroom hypothesis in
+   actionable form: the spec must literally contain `solo-headroom hypothesis`,
+   `solo_claude`, `miss`, and a backticked observable command while naming the
+   visible behavior a capable `solo_claude` baseline should miss; the backticked
+   line itself must contain `miss` and be framed as the command/observable that exposes it. If the
+   answer is only "the task is hard", rework the candidate before spending provider
+   calls. Do not write a benchmark/risk-probe/pair-evidence spec until this
+   hypothesis is actionable; if the user cannot provide it, stop with
+   `spec not ready — solo-headroom hypothesis required` and ask them to return
+   with the visible behavior `solo_claude` is expected to miss.
+9. **Solo ceiling avoidance**: for a new unmeasured benchmark, shadow-fixture,
+   golden-fixture, risk-probe, or pair-evidence candidate, ask how this candidate
+   differs from rejected or solo-saturated controls such as `S2`-`S6`. The note
+   must literally contain `solo ceiling avoidance`, mention `solo_claude`, and
+   name the concrete difference expected to preserve `solo_claude` headroom.
+   Benchmark fixture directories put this in `NOTES.md` as
+   `## Solo ceiling avoidance`; ordinary specs keep it in `## Verification`
+   next to the solo-headroom hypothesis. Do not write or measure the candidate
+   if this answer is missing; stop with
+   `spec not ready — solo ceiling avoidance required`.
 
 Walk through these in roughly this order. Skip the ones already clear from the user's initial text.
 </missing_decisions_to_surface>
@@ -56,14 +86,18 @@ When you're about to ask the user a question, look at the draft first — if the
 
 <lint>
 Before declaring the spec ready, verify structurally:
-- Frontmatter has `id`, `title`, `kind`, `status: planned`.
+- Frontmatter has `id`, `title`, `kind`, `status: planned`, `complexity`.
 - All 5 H2 sections present (`## Context`, `## Requirements`, `## Constraints`, `## Out of Scope`, `## Verification`).
 - Requirements ≥ 1 bullet.
 - Verification has either ≥ 1 named command OR the explicit pure-design escape phrase.
 
 If the lint fails, fix the missing piece (ask one focused question if needed) before announcing.
 
-After lint passes, also run `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` to validate the verification carrier shape. If exit 2: read the stderr message, fix the carrier, re-run. Exit 0 = ready.
+After lint passes, run both mechanical checks:
+1. `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` validates the spec's verification carrier shape, supported `complexity` frontmatter, and any present actionable solo-headroom hypothesis; if the spec uses a legacy inline `## Verification` JSON carrier, any solo-headroom hypothesis command must match that carrier's `verification_commands[].cmd`.
+2. `python3 .claude/skills/_shared/spec-verify-check.py --check-expected <expected-path>` validates sibling `spec.expected.json` against `_shared/expected.schema.json` plus sibling spec `complexity` frontmatter and any present actionable solo-headroom hypothesis; if the spec has a solo-headroom hypothesis, its observable command must match `spec.expected.json.verification_commands[].cmd`.
+
+If either exits 2: read the stderr message, fix the malformed carrier or JSON, and re-run the failed command. Both commands must exit 0 before ready.
 </lint>
 
 <output>
@@ -83,9 +117,21 @@ When `--quick` is set:
 1. AI synthesizes spec from the one-line goal — fill every section with the most reasonable inference.
 2. AI presents the spec to the user with an explicit `## Assumptions made` block listing every inferred decision (one bullet each).
 3. User responds with "go" / "fix X to be Y" / "no, different".
-4. On "go": write the spec + spec.expected.json, run lint, announce.
+4. On "go": write the spec + spec.expected.json, run both lint checks, announce.
 5. On "fix X": apply correction, re-present, ask again. Maximum 3 correction rounds before escalating to default mode.
 
+Exception: quick mode must not infer a solo-headroom hypothesis for benchmark,
+risk-probe, or pair-evidence goals. If the one-line goal lacks the actionable
+`solo-headroom hypothesis` / `solo_claude` / `miss` / backticked-command
+contract, ask exactly one focused follow-up for that hypothesis before showing a
+draft; if the user cannot provide it, exit with
+`spec not ready — solo-headroom hypothesis required`. For a new unmeasured
+benchmark, shadow-fixture, golden-fixture, risk-probe, or pair-evidence
+candidate, quick mode also must not infer the `solo ceiling avoidance` note; ask
+for the concrete difference from rejected or solo-saturated controls such as
+`S2`-`S6`, and exit with `spec not ready — solo ceiling avoidance required` if
+the user cannot provide it.
+
 Quick mode trades thoroughness for speed. Use it for trivial-medium tasks where the user has a clear-enough goal that one round of inference + correction is sufficient.
 
 ## Anti-patterns

package/config/skills/devlyn:ideate/references/from-spec-mode.md

@@ -14,7 +14,7 @@ The user already wrote a spec (or has one from elsewhere — a teammate, a previ
 
 <allowed_changes>
 You may:
-1. Add missing frontmatter fields (id from filename, kind=feature default, status=planned).
+1. Add missing frontmatter fields (id from filename, kind=feature default, status=planned, complexity=medium default; set complexity=high only when preserved Requirements clearly combine state/order/failure/output-shape risks).
 2. Rename non-canonical section headings to canonical (`## Goals` → `## Requirements`, `## Notes` ignored unless they clearly belong in Constraints).
 3. Add a missing `## Out of Scope` section with `- (no explicit non-goals provided by author)`.
 4. Add a missing `## Verification` section if Requirements imply observable runtime checks — best-effort one-command-per-Requirement, then surface to user for review.
@@ -37,14 +37,36 @@ You must NOT:
 3. For each missing/malformed piece: apply the smallest allowed fix.
 4. Write the normalized spec. Default location: `<spec-dir>/<id>-<slug>/spec.md`. With `--in-place` flag: write to `<path>` directly (overwrites the original).
 5. Generate or fix `spec.expected.json` per the rules above. Same dir as the spec.
-6. Run `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` to validate.
-7. If lint still fails after allowed fixes (e.g. Requirements section is empty in the source), surface the issue and exit non-zero — do NOT invent Requirements.
+6. Run `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>` to validate the spec carrier and supported `complexity` frontmatter; if the spec uses a legacy inline `## Verification` JSON carrier, any solo-headroom hypothesis command must match that carrier's `verification_commands[].cmd`.
+7. Run `python3 .claude/skills/_shared/spec-verify-check.py --check-expected <expected-path>` to validate sibling `spec.expected.json` plus sibling spec `complexity` frontmatter and any present solo-headroom hypothesis command against `spec.expected.json.verification_commands[].cmd`.
+8. If lint still fails after allowed fixes (e.g. Requirements section is empty in the source), surface the issue and exit non-zero — do NOT invent Requirements.
+9. If the preserved Requirements combine state mutation with ordering/priority,
+   idempotency, auth/error priority, or exact output shape but the Verification
+   section lacks a compound end-to-end scenario, do not rewrite the author's
+   content. Add a final warning that `/devlyn:resolve` may need default-mode
+   ideation or a stronger Verification section before pair-relevant risks are
+   measurable.
+10. If the source is a benchmark, risk probe, or pair-evidence candidate and it
+    lacks an actionable solo-headroom hypothesis, do not invent one. Add a final
+    warning that the candidate may be solo-saturated until Context or
+    Verification literally contains `solo-headroom hypothesis`, `solo_claude`,
+    `miss`, and a backticked observable command while naming the visible
+    behavior a capable `solo_claude` baseline is expected to miss; the
+    backticked line itself must contain `miss` and be framed as the
+    command/observable that exposes it. Do not call the normalized spec pair-evidence ready.
+11. If the source is a new unmeasured benchmark, shadow-fixture, golden-fixture,
+    risk-probe, or pair-evidence candidate and it lacks a solo ceiling avoidance
+    note, do not invent one. Add a final warning that the candidate may replay
+    rejected or solo-saturated controls until Context, Verification, or fixture
+    `NOTES.md` literally contains `solo ceiling avoidance`, mentions
+    `solo_claude`, and names a concrete difference from rejected controls such
+    as `S2`-`S6`. Do not call the normalized spec pair-evidence ready.
 </flow>
 
 <output>
 Same as default mode: `<spec-dir>/<id>-<slug>/spec.md` + `<spec-dir>/<id>-<slug>/spec.expected.json`.
 
-Final announcement: `spec normalized — /devlyn:resolve --spec <spec-path>`. If the spec was lint-passing with no changes needed, announce: `spec already canonical — /devlyn:resolve --spec <spec-path>`.
+Final announcement: `spec normalized — /devlyn:resolve --spec <spec-path>`. If the spec was lint-passing with no changes needed, announce: `spec already canonical — /devlyn:resolve --spec <spec-path>`. If step 9 applies, append: `warning: Verification may need one compound end-to-end scenario before pair-relevant risks are measurable`. If step 10 applies, append: `pair-evidence not ready — Pair-candidate headroom is unproven until the spec states a solo-headroom hypothesis`. If step 11 applies, append: `pair-evidence not ready — Pair-candidate headroom is unproven until the spec states solo ceiling avoidance`.
 
 If lint failed unfixably: print the specific failure, exit non-zero. Do not write a partial output.
 </output>

package/config/skills/devlyn:ideate/references/project-mode.md

@@ -11,6 +11,25 @@ The user wants to build a project, not a single feature. Your job is to elicit t
 2. Ask the same question categories as default mode (input/output/failure/scope/constraints/verification) but at the project level first, then drill into each feature.
 3. Decompose into 3-7 features. Fewer = the project is actually one big feature; recommend default mode. More = the project is too large; recommend splitting into separate ideate runs.
 4. Each feature must be independently shippable: a feature whose verification depends on another feature's runtime behavior is a dependency, not a feature.
+5. When a feature combines state mutation with ordering/priority, idempotency,
+   auth/error priority, or exact output shape, its per-feature Verification must
+   include one compound end-to-end scenario; do not hide the interaction in
+   project-level prose.
+6. When a feature is intended as a benchmark, risk probe, or pair-evidence
+   candidate, its per-feature Verification must include a solo-headroom
+   hypothesis. The feature spec must literally contain
+   `solo-headroom hypothesis`, `solo_claude`, `miss`, and a backticked
+   observable command while naming the visible behavior a capable
+   `solo_claude` baseline is expected to miss; the backticked line itself must
+   contain `miss` and be framed as the command/observable that exposes it. Do not defer that to
+   project-level prose, and rework the feature spec if the hypothesis is only
+   "the task is hard".
+7. When a feature is a new unmeasured benchmark, shadow-fixture, golden-fixture,
+   risk-probe, or pair-evidence candidate, its per-feature Verification must also include a solo ceiling avoidance note. The feature spec must literally
+   contain `solo ceiling avoidance`, mention `solo_claude`, and name a concrete
+   difference from rejected or solo-saturated controls such as `S2`-`S6`. Do not
+   defer that to project-level prose; benchmark fixture directories mirror the
+   same note in `NOTES.md` as `## Solo ceiling avoidance`.
 </conversation_rules>
 
 <decomposition_rules>
@@ -63,7 +82,7 @@ Anything binding all features (e.g. "no new top-level dependencies", "all CLI ou
 - `<spec-dir>/<id-N>/spec.md` for each feature (per `references/spec-template.md`).
 - `<spec-dir>/<id-N>/spec.expected.json` for each feature (per `_shared/expected.schema.json`).
 
-Each per-feature spec is structurally lint-validated using `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>`.
+Each per-feature spec is structurally lint-validated using `python3 .claude/skills/_shared/spec-verify-check.py --check <spec-path>`, including supported `complexity` frontmatter and any present actionable solo-headroom hypothesis, and each sibling expected contract plus sibling spec `complexity` frontmatter and any present actionable solo-headroom hypothesis is validated using `python3 .claude/skills/_shared/spec-verify-check.py --check-expected <expected-path>`; if the spec has a solo-headroom hypothesis, its observable command must match `spec.expected.json.verification_commands[].cmd`.
 
 Final announcement: `project ready — N specs at <spec-dir>/. Start with /devlyn:resolve --spec <first-spec-path>`.
 </output>

package/config/skills/devlyn:ideate/references/spec-template.md

@@ -10,6 +10,7 @@ id: "<spec-id>"          # kebab-case, unique per spec-dir; auto-generated if us
 title: "<short title>"    # one line, descriptive
 kind: feature             # feature | spike | prototype
 status: planned           # planned → in_progress → done. ideate writes "planned"; resolve's CLEANUP flips to "done".
+complexity: medium        # trivial | medium | high. Use high when Verification needs compound state/order/failure checks.
 depends_on: []            # list of spec ids this depends on (empty for standalone). project mode populates this.
 ---
 ```
@@ -78,7 +79,11 @@ If all Requirements are pure-design (no observable runtime check), the body of t
 
 ## Sibling file: `spec.expected.json`
 
-Schema: `_shared/expected.schema.json`. Required when Requirements have observable checks; optional when all Requirements are pure-design.
+Schema: `_shared/expected.schema.json`. Required when Requirements have observable checks; optional when all Requirements are pure-design. Validate before announcing ready:
+
+```bash
+python3 .claude/skills/_shared/spec-verify-check.py --check-expected <expected-path>
+```
 
 Generated by ideate from the conversation:
 - `verification_commands` ← parsed from `## Verification` body + any commands the conversation surfaced.
@@ -99,4 +104,8 @@ Substantive (ideate's job during elicitation):
 - Each Constraint has a reasoning clause.
 - Out of Scope explicitly enumerates non-goals.
 - Verification commands actually verify the Requirement they map to (no "looks plausible" verification).
+- Frontmatter `complexity` reflects verification shape: `high` when the spec combines state mutation with ordering/priority, idempotency, auth/error priority, rollback/failure handling, or exact output shape; `medium` for ordinary multi-step work; `trivial` only for a single localized behavior.
+- When Requirements combine state mutation, ordering/priority, idempotency, auth/error priority, or exact output shape, Verification includes at least one compound scenario that exercises the interaction end-to-end; isolated happy paths are insufficient.
+- For benchmark, risk-probe, or pair-evidence specs, include a solo-headroom hypothesis inside `## Verification`: the artifact must literally contain `solo-headroom hypothesis`, `solo_claude`, `miss`, and a backticked observable command while naming the visible behavior a capable `solo_claude` baseline is expected to miss; the backticked line itself must contain `miss`, be framed as the command/observable that exposes it, and match a `spec.expected.json.verification_commands[].cmd` entry. For regenerated pair evidence, this hypothesis is the source for VERIFY's canonical `spec.solo_headroom_hypothesis` trigger reason and must pass `benchmark audit --require-hypothesis-trigger`. If the hypothesis is only "the task is hard", rework the spec before measurement.
+- For new unmeasured benchmark, shadow-fixture, golden-fixture, risk-probe, or pair-evidence candidates, include a solo ceiling avoidance note before measurement: the artifact must literally contain `solo ceiling avoidance`, mention `solo_claude`, and name a concrete difference from rejected or solo-saturated controls such as `S2`-`S6`. If the note cannot say why the candidate should preserve `solo_claude` headroom, rework the candidate instead of spending provider calls. Benchmark fixture directories put this in `NOTES.md` as `## Solo ceiling avoidance`; ordinary specs keep the note in `## Verification` next to the solo-headroom hypothesis.
 - Spec text is plain language — no jargon walls, no "for future flexibility" hedging.

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

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

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

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

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

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

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

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