devlyn-cli 2.9.2 → 2.10.0

package/config/skills/_shared/verify-merge-findings.py

@@ -41,6 +41,7 @@ ALLOWED_PAIR_SKIP_REASONS = {
     "auto_pair_other_engine_unavailable",
 }
 KNOWN_PAIR_TRIGGER_REASONS = {
+    "pair.default",
     "mode.verify-only",
     "mode.pair-verify",
     "complexity.high",
@@ -109,6 +110,10 @@ def all_known_pair_trigger_reasons(reasons: list[str]) -> bool:
     return all(is_known_pair_trigger_reason(reason) for reason in reasons)
 
 
+def state_uses_default_pair_contract(state: dict[str, Any]) -> bool:
+    return state.get("version") == "3.0"
+
+
 def finding_rank(finding: dict[str, Any]) -> int:
     severity = str(finding.get("severity") or "").upper()
     if severity in {"CRITICAL", "HIGH"}:
@@ -338,6 +343,63 @@ def risk_profile_contract_violation(devlyn: pathlib.Path) -> dict[str, Any] | No
     return None
 
 
+def verify_state_contract_violation(devlyn: pathlib.Path) -> dict[str, Any] | None:
+    state_path = devlyn / "pipeline.state.json"
+    if not state_path.is_file():
+        return None
+    try:
+        state = loads_strict_json(state_path.read_text(encoding="utf-8"))
+    except ValueError:
+        return None
+    if not isinstance(state, dict) or not state_uses_default_pair_contract(state):
+        return None
+    source = state.get("source")
+    if not isinstance(source, dict) or source.get("type") != "generated":
+        return None
+    goal_path = source.get("goal_path")
+    goal_sha256 = source.get("goal_sha256")
+    if (
+        not isinstance(goal_path, str)
+        or not goal_path
+        or not isinstance(goal_sha256, str)
+        or re.fullmatch(r"[0-9a-f]{64}", goal_sha256) is None
+    ):
+        rule = "verify.state.goal-persistence-missing"
+        return {
+            "id": rule,
+            "rule_id": rule,
+            "message": (
+                "schema-v3 generated runs require source.goal_path as a non-empty string "
+                "and source.goal_sha256 as 64 lowercase hexadecimal characters."
+            ),
+            "file": "pipeline.state.json",
+        }
+    if state.get("complexity") in {"trivial", "medium"}:
+        phases = state.get("phases")
+        surface_close = phases.get("surface_close") if isinstance(phases, dict) else None
+        skipped = (
+            isinstance(surface_close, dict)
+            and surface_close.get("verdict") is None
+            and surface_close.get("started_at") is None
+            and surface_close.get("skipped_reason") == "auto_surface_close_claude_unavailable"
+        )
+        if (
+            not isinstance(surface_close, dict)
+            or (surface_close.get("verdict") is None and not skipped)
+        ):
+            rule = "verify.state.surface-close-skipped"
+            return {
+                "id": rule,
+                "rule_id": rule,
+                "message": (
+                    "schema-v3 generated trivial/medium runs require completed SURFACE_CLOSE "
+                    "or its canonical automatic Claude-unavailable skip before VERIFY merge."
+                ),
+                "file": "pipeline.state.json",
+            }
+    return None
+
+
 def source_spec_text(state: dict[str, Any]) -> str | None:
     source = state.get("source") if isinstance(state.get("source"), dict) else {}
     for key in ("spec_path", "criteria_path"):
@@ -424,6 +486,11 @@ def state_pair_trigger_reasons(
     verify_state = state.get("verify") if isinstance(state.get("verify"), dict) else {}
     risk_profile = state.get("risk_profile") if isinstance(state.get("risk_profile"), dict) else {}
     reasons: list[str] = []
+    if (
+        state_uses_default_pair_contract(state)
+        and risk_profile.get("pair_default_enabled") is not False
+    ):
+        reasons.append("pair.default")
     if state.get("mode") == "verify-only":
         reasons.append("mode.verify-only")
     if state.get("pair_verify") is True:
@@ -455,11 +522,19 @@ def state_pair_trigger_reasons(
     return reasons
 
 
+def outcome_independent_reasons(devlyn: pathlib.Path) -> list[str]:
+    return [
+        reason
+        for reason in state_pair_trigger_reasons(devlyn, {})
+        if reason not in ("coverage.failed", "mechanical.warning", "judge.warning")
+    ]
+
+
 def pair_trigger_missing_contract_violation(
     devlyn: pathlib.Path,
     source_verdicts: dict[str, str | None],
 ) -> dict[str, Any] | None:
-    if rank(source_verdicts.get("mechanical")) >= 2 or rank(source_verdicts.get("judge")) >= 2:
+    if rank(source_verdicts.get("mechanical")) >= 2:
         return None
     reasons = state_pair_trigger_reasons(devlyn, source_verdicts)
     if not reasons:
@@ -558,15 +633,36 @@ def pair_trigger_skip_contract_violation(
             ),
             "file": "pipeline.state.json",
         }
-    if skipped_reason == "primary_judge_blocker" and rank(source_verdicts.get("judge")) < 2:
-        return {
-            "id": "verify-pair-trigger-primary-judge-blocker-unsupported",
-            "message": (
-                "pair_trigger skipped_reason primary_judge_blocker requires a "
-                "verdict-binding primary JUDGE finding."
-            ),
-            "file": "pipeline.state.json",
-        }
+    if skipped_reason == "primary_judge_blocker":
+        if state_uses_default_pair_contract(state):
+            return {
+                "id": "verify-pair-trigger-primary-judge-blocker-retired",
+                "message": (
+                    "pair_trigger skipped_reason primary_judge_blocker is archived-v2.0 "
+                    "state only; schema-v3 runs must dispatch the pair-JUDGE."
+                ),
+                "file": "pipeline.state.json",
+            }
+        if rank(source_verdicts.get("judge")) < 2:
+            return {
+                "id": "verify-pair-trigger-primary-judge-blocker-unsupported",
+                "message": (
+                    "pair_trigger skipped_reason primary_judge_blocker requires a "
+                    "verdict-binding primary JUDGE finding."
+                ),
+                "file": "pipeline.state.json",
+            }
+        preknown_reasons = outcome_independent_reasons(devlyn)
+        if preknown_reasons:
+            return {
+                "id": "verify-pair-trigger-primary-judge-blocker-preknown",
+                "message": (
+                    "pair_trigger cannot skip the pair-JUDGE for a primary JUDGE blocker "
+                    "when outcome-independent reasons applied at spawn: "
+                    + ", ".join(preknown_reasons)
+                ),
+                "file": "pipeline.state.json",
+            }
     return None
 
 
@@ -574,7 +670,7 @@ def pair_trigger_reason_completeness_violation(
     devlyn: pathlib.Path,
     source_verdicts: dict[str, str | None],
 ) -> dict[str, Any] | None:
-    if rank(source_verdicts.get("mechanical")) >= 2 or rank(source_verdicts.get("judge")) >= 2:
+    if rank(source_verdicts.get("mechanical")) >= 2:
         return None
     state_path = devlyn / "pipeline.state.json"
     if not state_path.is_file():
@@ -614,10 +710,15 @@ def pair_trigger_reason_completeness_violation(
     }
 
 
-def pair_blocker(id_: str, message: str, file_: str | None = None) -> dict[str, Any]:
+def pair_blocker(
+    id_: str,
+    message: str,
+    file_: str | None = None,
+    rule_id: str = "verify.pair.emission-contract",
+) -> dict[str, Any]:
     return {
         "id": id_,
-        "rule_id": "verify.pair.emission-contract",
+        "rule_id": rule_id,
         "severity": "CRITICAL",
         "confidence": "high",
         "file": file_,
@@ -715,6 +816,17 @@ def detect_pair_stdout_contract_violations(
                 risk_profile_violation["file"],
             )
         ]
+    state_violation = verify_state_contract_violation(devlyn)
+    if state_violation is not None:
+        source_verdicts["pair_judge"] = "BLOCKED"
+        return [
+            pair_blocker(
+                state_violation["id"],
+                state_violation["message"],
+                state_violation["file"],
+                state_violation["rule_id"],
+            )
+        ]
     if not required and not pair_trigger_present(devlyn):
         missing_violation = pair_trigger_missing_contract_violation(devlyn, source_verdicts)
         if missing_violation is not None:
@@ -892,7 +1004,15 @@ def self_test() -> int:
         # the real shape write_state() sees on every VERIFY completion, not
         # the pre-populated {} the other scenarios below seed for brevity.
         (devlyn / "pipeline.state.json").write_text(
-            json.dumps({"phases": {"verify": {"verdict": None, "sub_verdicts": None}}}),
+            json.dumps({
+                "phases": {
+                    "verify": {
+                        "verdict": None,
+                        "sub_verdicts": None,
+                        "judge_durations_ms": {"judge": 23, "pair_judge": 31},
+                    }
+                }
+            }),
             encoding="utf-8",
         )
         (devlyn / "verify.findings.jsonl").write_text("", encoding="utf-8")
@@ -904,13 +1024,130 @@ def self_test() -> int:
         assert state["phases"]["verify"]["sub_verdicts"] == {
             "mechanical": "PASS", "judge": "PASS", "pair_judge": None,
         }, state
+        assert state["phases"]["verify"]["judge_durations_ms"] == {
+            "judge": 23, "pair_judge": 31,
+        }, state
+
+        # iter-0072 Amendment 3: generated schema-v3 runs mechanically prove
+        # raw-goal persistence and required SURFACE_CLOSE dispatch.
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "version": "3.0",
+                "complexity": "large",
+                "source": {"type": "generated"},
+                "phases": {"verify": {"verdict": None, "sub_verdicts": None}},
+            }),
+            encoding="utf-8",
+        )
+        findings, source_verdicts = read_findings(devlyn)
+        summary = write_outputs(devlyn, findings, source_verdicts)
+        assert summary["verdict"] == "BLOCKED", summary
+        assert summary["source_verdicts"]["pair_judge"] == "BLOCKED", summary
+        assert any(
+            finding.get("rule_id") == "verify.state.goal-persistence-missing"
+            for finding in findings
+        ), findings
+
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "version": "3.0",
+                "complexity": "large",
+                "source": {"type": "generated", "goal_path": "", "goal_sha256": "A" * 64},
+            }),
+            encoding="utf-8",
+        )
+        violation = verify_state_contract_violation(devlyn)
+        assert violation is not None, violation
+        assert violation["rule_id"] == "verify.state.goal-persistence-missing", violation
+
+        generated_source = {
+            "type": "generated",
+            "goal_path": ".devlyn/goal.raw.txt",
+            "goal_sha256": "a" * 64,
+        }
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "version": "3.0",
+                "complexity": "medium",
+                "source": generated_source,
+                "phases": {
+                    "surface_close": None,
+                    "verify": {"verdict": None, "sub_verdicts": None},
+                },
+            }),
+            encoding="utf-8",
+        )
+        findings, source_verdicts = read_findings(devlyn)
+        summary = write_outputs(devlyn, findings, source_verdicts)
+        assert summary["verdict"] == "BLOCKED", summary
+        assert any(
+            finding.get("rule_id") == "verify.state.surface-close-skipped"
+            for finding in findings
+        ), findings
+
+        for surface_entry in (
+            {"verdict": "PASS"},
+            {
+                "verdict": None,
+                "started_at": None,
+                "skipped_reason": "auto_surface_close_claude_unavailable",
+            },
+        ):
+            (devlyn / "pipeline.state.json").write_text(
+                json.dumps({
+                    "version": "3.0",
+                    "complexity": "medium",
+                    "source": generated_source,
+                    "phases": {"surface_close": surface_entry},
+                }),
+                encoding="utf-8",
+            )
+            assert verify_state_contract_violation(devlyn) is None
+
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "version": "3.0",
+                "complexity": "medium",
+                "source": generated_source,
+                "phases": {
+                    "surface_close": {
+                        "verdict": None,
+                        "started_at": None,
+                        "skipped_reason": "claude-unavailable",
+                    },
+                },
+            }),
+            encoding="utf-8",
+        )
+        assert verify_state_contract_violation(devlyn)["rule_id"] == "verify.state.surface-close-skipped"
+
+        for state_shape in (
+            {
+                "version": "3.0", "complexity": "medium",
+                "source": {"type": "spec"}, "phases": {"surface_close": None},
+            },
+            {
+                "version": "3.0", "complexity": "large",
+                "source": generated_source, "phases": {"surface_close": None},
+            },
+            {
+                "version": "2.0", "complexity": "medium",
+                "source": {"type": "generated"}, "phases": {"surface_close": None},
+            },
+        ):
+            (devlyn / "pipeline.state.json").write_text(
+                json.dumps(state_shape), encoding="utf-8",
+            )
+            assert verify_state_contract_violation(devlyn) is None
 
         # 2026-07-04 field bug (iter-0060 G1): an AUTO pair trigger skipped on
         # OTHER-engine unavailability spawns no second judge — pair_judge must
         # be recorded null, never a synthesized PASS.
         (devlyn / "pipeline.state.json").write_text(
             json.dumps({
+                "version": "3.0",
                 "mode": "spec",
+                "risk_profile": {"pair_default_enabled": True},
                 "phases": {
                     "verify": {
                         "verdict": None,
@@ -1936,18 +2173,128 @@ def self_test() -> int:
             for finding in findings
         ), findings
 
+        # Self-test: preknown_primary_blocker_requires_pair.
+        (devlyn / "verify.pair.findings.jsonl").unlink(missing_ok=True)
         (devlyn / "verify.findings.jsonl").write_text(
-            json.dumps({"id": "j2", "severity": "HIGH"}) + "\n",
+            json.dumps({"id": "j-preknown", "severity": "HIGH"}) + "\n",
+            encoding="utf-8",
+        )
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "version": "2.0",
+                "mode": "spec",
+                "pair_verify": True,
+                "phases": {
+                    "verify": {
+                        "verdict": "PASS",
+                        "sub_verdicts": {},
+                        "pair_trigger": {
+                            "eligible": False,
+                            "reasons": [],
+                            "skipped_reason": "primary_judge_blocker",
+                        },
+                    }
+                },
+            }),
+            encoding="utf-8",
+        )
+        findings, source_verdicts = read_findings(devlyn)
+        summary = write_outputs(devlyn, findings, source_verdicts)
+        assert summary["verdict"] == "BLOCKED", summary
+        assert any(
+            finding.get("id") == "verify-pair-trigger-primary-judge-blocker-preknown"
+            and "mode.pair-verify" in str(finding.get("message"))
+            for finding in findings
+        ), findings
+
+        # Self-test: schema-v3 default pair reason is required before merge.
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "version": "3.0",
+                "mode": "spec",
+                "pair_verify": True,
+                "phases": {
+                    "verify": {
+                        "verdict": "PASS",
+                        "sub_verdicts": {},
+                        "pair_trigger": {
+                            "eligible": True,
+                            "reasons": ["mode.pair-verify"],
+                            "skipped_reason": None,
+                        },
+                    }
+                },
+            }),
+            encoding="utf-8",
+        )
+        (devlyn / "verify.pair.findings.jsonl").write_text(
+            json.dumps({"id": "p-preknown", "severity": "LOW"}) + "\n",
+            encoding="utf-8",
+        )
+        findings, source_verdicts = read_findings(devlyn)
+        summary = write_outputs(devlyn, findings, source_verdicts)
+        assert summary["verdict"] == "BLOCKED", summary
+        assert any(
+            finding.get("id") == "verify-pair-trigger-reasons-incomplete"
+            and "pair.default" in str(finding.get("message"))
+            for finding in findings
+        ), findings
+        state = loads_strict_json((devlyn / "pipeline.state.json").read_text(encoding="utf-8"))
+        state["phases"]["verify"]["pair_trigger"]["reasons"].insert(0, "pair.default")
+        (devlyn / "pipeline.state.json").write_text(json.dumps(state), encoding="utf-8")
+        findings, source_verdicts = read_findings(devlyn)
+        summary = write_outputs(devlyn, findings, source_verdicts)
+        assert summary["verdict"] == "NEEDS_WORK", summary
+        assert summary["source_verdicts"]["judge"] == "NEEDS_WORK", summary
+        assert summary["source_verdicts"]["pair_judge"] == "PASS_WITH_ISSUES", summary
+        assert '"id":"p-preknown"' in (
+            devlyn / "verify-merged.findings.jsonl"
+        ).read_text(encoding="utf-8"), findings
+
+        # Self-test: archived-v2 sequential primary blocker remains legal.
+        (devlyn / "verify.pair.findings.jsonl").unlink()
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "version": "2.0",
+                "mode": "spec",
+                "phases": {
+                    "verify": {
+                        "verdict": "PASS",
+                        "sub_verdicts": {},
+                        "pair_trigger": {
+                            "eligible": False,
+                            "reasons": [],
+                            "skipped_reason": "primary_judge_blocker",
+                        },
+                    }
+                },
+            }),
             encoding="utf-8",
         )
         findings, source_verdicts = read_findings(devlyn)
         summary = write_outputs(devlyn, findings, source_verdicts)
         assert summary["verdict"] == "NEEDS_WORK", summary
+        assert summary["source_verdicts"]["pair_judge"] is None, summary
         assert not any(
-            finding.get("id") == "verify-pair-trigger-primary-judge-blocker-unsupported"
+            finding.get("id") in {
+                "verify-pair-trigger-primary-judge-blocker-unsupported",
+                "verify-pair-trigger-primary-judge-blocker-preknown",
+            }
+            for finding in findings
+        ), findings
+        # Replay the same state as schema v3 and require the retired-skip blocker.
+        state = loads_strict_json((devlyn / "pipeline.state.json").read_text(encoding="utf-8"))
+        state["version"] = "3.0"
+        (devlyn / "pipeline.state.json").write_text(json.dumps(state), encoding="utf-8")
+        findings, source_verdicts = read_findings(devlyn)
+        summary = write_outputs(devlyn, findings, source_verdicts)
+        assert summary["verdict"] == "BLOCKED", summary
+        assert any(
+            finding.get("id") == "verify-pair-trigger-primary-judge-blocker-retired"
             for finding in findings
         ), findings
         (devlyn / "verify.findings.jsonl").write_text("", encoding="utf-8")
+        (devlyn / "verify.pair.findings.jsonl").write_text("", encoding="utf-8")
 
         (devlyn / "pipeline.state.json").write_text(
             json.dumps({

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

@@ -25,7 +25,7 @@ DEVLYN_SHARED_DIR="$(cd "$DEVLYN_SKILL_DIR/../_shared" && pwd)"
 ## No args — status + how to choose
 
 1. Read `cwd/.devlyn/engines.json`. Absent → report "no pins — auto-detection active".
-2. Run `bash "$DEVLYN_SHARED_DIR/engine-doctor.sh"` — read-only; never installs anything or writes `.devlyn/engines.json`. It detects, per target (`claude`, `codex`, `omp`, `pi`), whether its binary is present, whether `_shared/adapters/<name>.md` exists, and whether that makes it `pin_eligible` today. Its trailing line is either a pair-judge-diversity confirmation or a recommendation to add a second adapter-valid engine (`autoresearch/iterations/0045-model-arm-drift.md`: different model tiers hit different failure-mode blind spots, so VERIFY pair-judge/risk-probes need ≥2 to ever fire).
+2. Run `bash "$DEVLYN_SHARED_DIR/engine-doctor.sh"` — read-only; never installs anything or writes `.devlyn/engines.json`. It detects, per target in the doctor's catalog, whether its binary is present, whether `_shared/adapters/<name>.md` exists, and whether that makes it `pin_eligible` today. Its trailing line is either a pair-judge-diversity confirmation or a recommendation to add a second adapter-valid engine (`autoresearch/iterations/0045-model-arm-drift.md`: different model tiers hit different failure-mode blind spots, so VERIFY pair-judge/risk-probes need ≥2 to ever fire).
 3. Print the role table. Executor's "Available engines" = rows where `pin_eligible: yes` and `role` includes `executor` (i.e. not `judge-only`). Pair judge's "Available engines" = rows where `pin_eligible: yes` and `role` includes `judge` (`executor+judge` or `judge-only`):
 
 ```

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

@@ -9,6 +9,17 @@ Utility front-end for the intent-queue contract in the project instructions ("In
 $ARGUMENTS
 </args>
 
+For `drain`, resolve the installed shared scripts before the first item:
+
+```bash
+DEVLYN_SKILL_DIR="${CLAUDE_SKILL_DIR:-__DEVLYN_SKILL_DIR__}"
+if [ "$DEVLYN_SKILL_DIR" = "__DEVLYN_SKILL_DIR__" ] || [ ! -d "$DEVLYN_SKILL_DIR/../_shared" ]; then
+  echo "BLOCKED:shared-dir-unresolved: $DEVLYN_SKILL_DIR/../_shared" >&2
+  exit 1
+fi
+DEVLYN_SHARED_DIR="$(cd "$DEVLYN_SKILL_DIR/../_shared" && pwd)"
+```
+
 ## No args — status
 
 Read `docs/specs/queue.md` (absent → report "queue empty — nothing staged" and how to add). Print pending `[ ]`, done `[x]`, and blocked `[F]` counts, the next item up, and one usage line per subcommand.
@@ -19,6 +30,7 @@ Read `docs/specs/queue.md` (absent → report "queue empty — nothing staged" a
 - `drain` — serial drain per the project-instructions contract. For each pending item, in order:
   1. Spec it if unspecced (the queue entry is the user's go-ahead). Unattended assumptions may only take scope-narrowing, reversible, non-user-visible defaults; material ambiguity (user-visible behavior, data/state semantics, new files/scripts/flags, implementation surface) → mark `[F] needs-review: <question>` and continue to the next item.
   2. Run `/devlyn:resolve --spec <path>` hands-free.
+     After every resolve invocation, run `python3 "$DEVLYN_SHARED_DIR/terminal-claim-check.py" .`; exit 79 marks `[F] FAILED-INCOMPLETE` from the predicate, never from the session self-report.
   3. Outer loop on the terminal verdict: PASS → mark `[x]`. Findings-backed verdicts (NEEDS_WORK, verify/build-gate exhaustion) → amend the spec (recorded in the spec file), re-run — at most 3 outer iterations. Infrastructure / invalid-input / engine-availability / implement-empty BLOCKED verdicts are not spec-amendable → mark `[F] <verdict>` immediately.
   4. A blocked item never halts the queue; continue.
   5. When the queue is drained (or the session must stop), emit the drain report: per-item verdict, every logged assumption, and the commit range produced.