devlyn-cli 2.8.0 → 2.9.0

package/config/skills/_shared/state-phase-write.py

@@ -5,13 +5,12 @@ Usage:
     python3 state-phase-write.py --devlyn-dir .devlyn --phase implement spawn \
         --round 1 --triggered-by verify [--pre-sha <sha>] [--engine claude] [--model <id>]
     python3 state-phase-write.py --devlyn-dir .devlyn --phase implement complete \
-        --verdict PASS [--findings-file <path>] [--log-file <path>] [--engine claude] [--model <id>]
+        --verdict PASS [--post-sha <sha>] [--findings-file <path>] [--log-file <path>] [--engine claude] [--model <id>]
 
 references/state-schema.md#write-protocol is the contract this implements.
-iter-0042 (autoresearch/iterations/0042-compliance-drift-probes.md) found a
-hand-edited fix-loop respawn left `started_at` at its original round's value
-while `completed_at`/`duration_ms`/`round`/`triggered_by` advanced to the new
-round, producing an internally inconsistent phase timeline. `spawn` always
+A prior hand-edited fix-loop respawn left `started_at` at its original round's
+value while `completed_at`/`duration_ms`/`round`/`triggered_by` advanced to the
+new round, producing an internally inconsistent phase timeline. `spawn` always
 resets `started_at` fresh and nulls the completion fields; `complete` derives
 `duration_ms` from the phase's own recorded `started_at`, so the two can never
 drift apart again.
@@ -95,6 +94,24 @@ def clear_verify_round_artifacts(devlyn: pathlib.Path) -> None:
     (devlyn / "verify-merge.summary.json").unlink(missing_ok=True)
 
 
+def append_round_history(entry: dict) -> None:
+    if entry.get("started_at") is None:
+        return
+    history = entry.get("rounds_history")
+    if not isinstance(history, list):
+        history = []
+    history.append({
+        "round": entry.get("round"),
+        "started_at": entry.get("started_at"),
+        "completed_at": entry.get("completed_at"),
+        "duration_ms": entry.get("duration_ms"),
+        "verdict": entry.get("verdict"),
+        "triggered_by": entry.get("triggered_by"),
+        "engine": entry.get("engine"),
+    })
+    entry["rounds_history"] = history
+
+
 def do_spawn(state: dict, phase: str, round_: int, triggered_by: str | None,
              pre_sha: str | None, engine: str | None, model: str | None) -> None:
     # Merge, don't replace: a phase-gated large run's `exec` progress (or any
@@ -104,6 +121,7 @@ def do_spawn(state: dict, phase: str, round_: int, triggered_by: str | None,
     if not isinstance(entry, dict):
         entry = {}
         phases[phase] = entry
+    append_round_history(entry)
     entry["started_at"] = now_iso()
     entry["completed_at"] = None
     entry["duration_ms"] = None
@@ -121,7 +139,7 @@ def do_spawn(state: dict, phase: str, round_: int, triggered_by: str | None,
 
 
 def do_complete(state: dict, phase: str, verdict: str | None,
-                 findings_file: str | None, log_file: str | None,
+                 post_sha: str | None, findings_file: str | None, log_file: str | None,
                  engine: str | None, model: str | None) -> None:
     phases = state.setdefault("phases", {})
     entry = phases.get(phase)
@@ -156,6 +174,8 @@ def do_complete(state: dict, phase: str, verdict: str | None,
         entry["engine"] = engine
     if model is not None:
         entry["model"] = model
+    if post_sha is not None:
+        entry["post_sha"] = post_sha
 
 
 def self_test() -> int:
@@ -174,7 +194,7 @@ def self_test() -> int:
 
         time.sleep(0.05)
         state = read_state(state_path)
-        do_complete(state, "implement", "NEEDS_WORK", None, None, None, "test-model-id")
+        do_complete(state, "implement", "NEEDS_WORK", None, None, None, None, "test-model-id")
         write_state(state_path, state)
         entry = read_state(state_path)["phases"]["implement"]
         assert entry["completed_at"] is not None
@@ -196,10 +216,19 @@ def self_test() -> int:
         assert respawned["engine"] == "claude", "engine preserved when not re-supplied"
         assert respawned["round"] == 1
         assert respawned["triggered_by"] == "verify"
+        assert len(respawned["rounds_history"]) == 1
+        history0 = respawned["rounds_history"][0]
+        assert history0["round"] == 0
+        assert history0["started_at"] == round0_started
+        assert history0["completed_at"] == entry["completed_at"]
+        assert history0["duration_ms"] == entry["duration_ms"]
+        assert history0["verdict"] == "NEEDS_WORK"
+        assert history0["triggered_by"] is None
+        assert history0["engine"] == "claude"
 
         time.sleep(0.05)
         state = read_state(state_path)
-        do_complete(state, "implement", "PASS", ".devlyn/x.jsonl", None, None, None)
+        do_complete(state, "implement", "PASS", None, ".devlyn/x.jsonl", None, None, None)
         write_state(state_path, state)
         final = read_state(state_path)["phases"]["implement"]
         assert final["verdict"] == "PASS"
@@ -211,12 +240,32 @@ def self_test() -> int:
         write_state(state_path, {"phases": {}})
         state = read_state(state_path)
         try:
-            do_complete(state, "build_gate", "PASS", None, None, None, None)
+            do_complete(state, "build_gate", "PASS", None, None, None, None, None)
         except SystemExit as e:
             assert "never spawned" in str(e)
         else:
             raise AssertionError("complete() without a prior spawn() must raise")
 
+        # A completed FAIL round must be retained before a fix-loop respawn
+        # resets the live record.
+        write_state(state_path, {"phases": {}})
+        state = read_state(state_path)
+        do_spawn(state, "build_gate", 0, None, None, "claude", None)
+        write_state(state_path, state)
+        time.sleep(0.05)
+        state = read_state(state_path)
+        do_complete(state, "build_gate", "FAIL", None, None, None, None, None)
+        write_state(state_path, state)
+        failed_round = read_state(state_path)["phases"]["build_gate"]
+        state = read_state(state_path)
+        do_spawn(state, "build_gate", 1, "build_gate", None, None, None)
+        write_state(state_path, state)
+        respawned_fail = read_state(state_path)["phases"]["build_gate"]
+        assert respawned_fail["verdict"] is None
+        assert len(respawned_fail["rounds_history"]) == 1
+        assert respawned_fail["rounds_history"][0]["verdict"] == "FAIL"
+        assert respawned_fail["rounds_history"][0]["completed_at"] == failed_round["completed_at"]
+
         # VERIFY flow: verify-merge-findings.py already wrote verdict; complete()
         # must preserve it when --verdict is omitted.
         write_state(state_path, {"phases": {}})
@@ -226,7 +275,7 @@ def self_test() -> int:
         state["phases"]["verify"]["sub_verdicts"] = {"mechanical": "PASS", "judge": "PASS"}
         write_state(state_path, state)
         state = read_state(state_path)
-        do_complete(state, "verify", None, None, None, None, None)
+        do_complete(state, "verify", None, None, None, None, None, None)
         write_state(state_path, state)
         verify_entry = read_state(state_path)["phases"]["verify"]
         assert verify_entry["verdict"] == "PASS", "complete() must preserve pre-set verdict when omitted"
@@ -237,7 +286,7 @@ def self_test() -> int:
         # owned exclusively by verify-merge-findings.py --write-state.
         state = read_state(state_path)
         try:
-            do_complete(state, "verify", "PASS", None, None, None, None)
+            do_complete(state, "verify", "PASS", None, None, None, None, None)
         except SystemExit as e:
             assert "owned by verify-merge-findings.py" in str(e)
         else:
@@ -252,7 +301,7 @@ def self_test() -> int:
         write_state(state_path, state)
         state = read_state(state_path)
         try:
-            do_complete(state, "plan", None, None, None, None, None)
+            do_complete(state, "plan", None, None, None, None, None, None)
         except SystemExit as e:
             assert "is required" in str(e)
         else:
@@ -266,7 +315,7 @@ def self_test() -> int:
         write_state(state_path, state)
         state = read_state(state_path)
         try:
-            do_complete(state, "verify", None, None, None, None, None)
+            do_complete(state, "verify", None, None, None, None, None, None)
         except SystemExit as e:
             assert "still null" in str(e)
         else:
@@ -311,7 +360,7 @@ def self_test() -> int:
         }
         write_state(state_path, state)
         state = read_state(state_path)
-        do_complete(state, "implement", "PASS", None, None, None, None)
+        do_complete(state, "implement", "PASS", None, None, None, None, None)
         write_state(state_path, state)
         state = read_state(state_path)
         do_spawn(state, "implement", 1, "verify", None, None, None)
@@ -319,6 +368,54 @@ def self_test() -> int:
         respawned_exec = read_state(state_path)["phases"]["implement"]
         assert respawned_exec["exec"]["current"] == 3, "spawn must not clobber unowned fields like exec"
         assert respawned_exec["verdict"] is None, "respawn still nulls owned fields even with exec present"
+        assert len(respawned_exec["rounds_history"]) == 1
+        assert respawned_exec["rounds_history"][0]["verdict"] == "PASS"
+
+        # Existing history is append-only; a respawn must not clobber prior
+        # entries that were already preserved from older rounds.
+        write_state(state_path, {
+            "phases": {
+                "implement": {
+                    "started_at": "2026-01-01T00:00:02.000Z",
+                    "completed_at": "2026-01-01T00:00:03.000Z",
+                    "duration_ms": 1000,
+                    "round": 2,
+                    "triggered_by": "verify",
+                    "verdict": "FAIL",
+                    "engine": "codex",
+                    "rounds_history": [{
+                        "round": 1,
+                        "started_at": "2026-01-01T00:00:00.000Z",
+                        "completed_at": "2026-01-01T00:00:01.000Z",
+                        "duration_ms": 1000,
+                        "verdict": "FAIL",
+                        "triggered_by": "build_gate",
+                        "engine": "claude",
+                    }],
+                }
+            }
+        })
+        state = read_state(state_path)
+        do_spawn(state, "implement", 3, "verify", None, None, None)
+        write_state(state_path, state)
+        history_preserved = read_state(state_path)["phases"]["implement"]["rounds_history"]
+        assert len(history_preserved) == 2
+        assert history_preserved[0]["round"] == 1
+        assert history_preserved[1]["round"] == 2
+        assert history_preserved[1]["engine"] == "codex"
+
+        # complete() records a post-state commit when a bounded phase needs an
+        # exact diff window for later mechanical checks.
+        write_state(state_path, {"phases": {}})
+        state = read_state(state_path)
+        do_spawn(state, "cleanup", 0, None, "pre-sha", None, None)
+        write_state(state_path, state)
+        state = read_state(state_path)
+        do_complete(state, "cleanup", "PASS", "post-sha", None, None, None, None)
+        write_state(state_path, state)
+        cleanup_entry = read_state(state_path)["phases"]["cleanup"]
+        assert cleanup_entry["pre_sha"] == "pre-sha"
+        assert cleanup_entry["post_sha"] == "post-sha"
 
     return 0
 
@@ -339,6 +436,7 @@ def main() -> int:
 
     complete_p = sub.add_parser("complete")
     complete_p.add_argument("--verdict", choices=sorted(VALID_VERDICTS), default=None)
+    complete_p.add_argument("--post-sha", default=None)
     complete_p.add_argument("--findings-file", default=None)
     complete_p.add_argument("--log-file", default=None)
     complete_p.add_argument("--engine", default=None)
@@ -363,7 +461,7 @@ def main() -> int:
             clear_verify_round_artifacts(devlyn)
         do_spawn(state, args.phase, args.round, args.triggered_by, args.pre_sha, args.engine, args.model)
     else:
-        do_complete(state, args.phase, args.verdict, args.findings_file, args.log_file, args.engine, args.model)
+        do_complete(state, args.phase, args.verdict, args.post_sha, args.findings_file, args.log_file, args.engine, args.model)
 
     write_state(state_path, state)
     sys.stdout.write(f"ok: phases.{args.phase}.{args.event}\n")

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

@@ -27,6 +27,7 @@ SOURCE_FILES = (
 
 VERDICT_RANK = {
     "PASS": 0,
+    "TIMEOUT": 0,
     "PASS_WITH_ISSUES": 1,
     "FAIL": 2,
     "NEEDS_WORK": 2,
@@ -627,6 +628,45 @@ def pair_blocker(id_: str, message: str, file_: str | None = None) -> dict[str,
     }
 
 
+def read_pair_timeout_marker(devlyn: pathlib.Path) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
+    path = devlyn / "verify.pair.timeout.json"
+    if not path.is_file():
+        return None, None
+    try:
+        marker = loads_strict_json(path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        return None, {
+            "id": "verify-pair-timeout-marker-malformed",
+            "message": f"verify.pair.timeout.json is malformed JSON: {exc}",
+            "file": "verify.pair.timeout.json",
+        }
+    if not isinstance(marker, dict):
+        return None, {
+            "id": "verify-pair-timeout-marker-malformed",
+            "message": "verify.pair.timeout.json must be a JSON object.",
+            "file": "verify.pair.timeout.json",
+        }
+    engine = marker.get("engine")
+    budget_seconds = marker.get("budget_seconds")
+    if not isinstance(engine, str) or not engine:
+        return None, {
+            "id": "verify-pair-timeout-marker-malformed",
+            "message": "verify.pair.timeout.json engine must be a non-empty string.",
+            "file": "verify.pair.timeout.json",
+        }
+    if (
+        not isinstance(budget_seconds, int)
+        or isinstance(budget_seconds, bool)
+        or budget_seconds <= 0
+    ):
+        return None, {
+            "id": "verify-pair-timeout-marker-malformed",
+            "message": "verify.pair.timeout.json budget_seconds must be a positive integer.",
+            "file": "verify.pair.timeout.json",
+        }
+    return {"engine": engine, "budget_seconds": budget_seconds}, None
+
+
 def detect_pair_stdout_contract_violations(
     devlyn: pathlib.Path,
     source_verdicts: dict[str, str | None],
@@ -635,6 +675,16 @@ def detect_pair_stdout_contract_violations(
     # claude-judge.stdout — adapters/claude.md ## Invocation). The emission
     # contract is engine-neutral.
     stdout_paths = sorted(devlyn.glob("*-judge.stdout"))
+    timeout_marker, timeout_violation = read_pair_timeout_marker(devlyn)
+    if timeout_violation is not None:
+        source_verdicts["pair_judge"] = "BLOCKED"
+        return [
+            pair_blocker(
+                timeout_violation["id"],
+                timeout_violation["message"],
+                timeout_violation["file"],
+            )
+        ]
     flag_violation = pair_flag_contract_violation(devlyn)
     if flag_violation is not None:
         source_verdicts["pair_judge"] = "BLOCKED"
@@ -699,6 +749,9 @@ def detect_pair_stdout_contract_violations(
     if has_pair_findings(devlyn):
         return []
     if not stdout_paths:
+        if timeout_marker is not None:
+            source_verdicts["pair_judge"] = "TIMEOUT"
+            return []
         if required:
             source_verdicts["pair_judge"] = "BLOCKED"
             return [
@@ -709,11 +762,13 @@ def detect_pair_stdout_contract_violations(
                 )
             ]
         return []
-    if source_verdicts["pair_judge"] is None:
+    if source_verdicts["pair_judge"] is None and timeout_marker is None:
         source_verdicts["pair_judge"] = "PASS"
     for stdout_path in stdout_paths:
         raw_text = stdout_path.read_text(encoding="utf-8")
         if not raw_text.strip():
+            if timeout_marker is not None:
+                continue
             source_verdicts["pair_judge"] = "BLOCKED"
             return [
                 pair_blocker(
@@ -761,6 +816,8 @@ def detect_pair_stdout_contract_violations(
                     stdout_path.name,
                 )
             ]
+    if timeout_marker is not None:
+        source_verdicts["pair_judge"] = "TIMEOUT"
     return []
 
 
@@ -783,6 +840,11 @@ def write_outputs(
         "findings_count": len(findings),
         "findings_file": str(merged_path),
     }
+    if source_verdicts.get("pair_judge") == "TIMEOUT":
+        timeout_marker, _timeout_violation = read_pair_timeout_marker(devlyn)
+        if timeout_marker is not None:
+            summary["pair_timeout"] = timeout_marker
+            summary["report_header_note"] = "solo verdict after pair TIMEOUT"
     summary_path.write_text(json.dumps(summary, indent=2, sort_keys=True) + "\n", encoding="utf-8")
     return summary
 
@@ -972,6 +1034,140 @@ def self_test() -> int:
             for finding in findings
         ), findings
         (devlyn / "claude-judge.stdout").unlink()
+
+        # iter-0065 case 1: a valid pair timeout marker plus empty pair output
+        # records TIMEOUT and leaves the merged verdict to mechanical+primary.
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "phases": {
+                    "verify": {
+                        "verdict": "PASS",
+                        "sub_verdicts": {},
+                        "pair_trigger": {
+                            "eligible": True,
+                            "reasons": ["judge.warning"],
+                            "skipped_reason": None,
+                        },
+                    }
+                }
+            }),
+            encoding="utf-8",
+        )
+        (devlyn / "verify.findings.jsonl").write_text(
+            json.dumps({"id": "j-timeout-low", "severity": "LOW"}) + "\n",
+            encoding="utf-8",
+        )
+        (devlyn / "verify.pair.findings.jsonl").write_text("", encoding="utf-8")
+        (devlyn / "claude-judge.stdout").write_text("", encoding="utf-8")
+        (devlyn / "verify.pair.timeout.json").write_text(
+            json.dumps({"engine": "claude", "budget_seconds": 600}),
+            encoding="utf-8",
+        )
+        findings, source_verdicts = read_findings(devlyn)
+        summary = write_outputs(devlyn, findings, source_verdicts)
+        write_state(devlyn, summary)
+        state = loads_strict_json((devlyn / "pipeline.state.json").read_text(encoding="utf-8"))
+        assert summary["verdict"] == "PASS_WITH_ISSUES", summary
+        assert summary["source_verdicts"]["pair_judge"] == "TIMEOUT", summary
+        assert summary["pair_timeout"] == {"engine": "claude", "budget_seconds": 600}, summary
+        assert summary["report_header_note"] == "solo verdict after pair TIMEOUT", summary
+        assert state["phases"]["verify"]["sub_verdicts"]["pair_judge"] == "TIMEOUT", state
+        (devlyn / "claude-judge.stdout").unlink()
+        (devlyn / "verify.pair.timeout.json").unlink()
+        (devlyn / "verify.findings.jsonl").write_text("", encoding="utf-8")
+
+        # iter-0065 case 2: canonical pair findings still bind after timeout.
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({"phases": {"verify": {"verdict": "PASS", "sub_verdicts": {}}}}),
+            encoding="utf-8",
+        )
+        (devlyn / "verify.pair.findings.jsonl").write_text(
+            json.dumps({"id": "p-timeout-high", "severity": "HIGH"}) + "\n",
+            encoding="utf-8",
+        )
+        (devlyn / "verify.pair.timeout.json").write_text(
+            json.dumps({"engine": "codex", "budget_seconds": 600}),
+            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"] == "NEEDS_WORK", summary
+        assert "pair_timeout" not in summary, summary
+        (devlyn / "verify.pair.timeout.json").unlink()
+        (devlyn / "verify.pair.findings.jsonl").write_text("", encoding="utf-8")
+
+        # iter-0065 case 2b: stdout-only HIGH still blocks on emission contract;
+        # timeout never converts an observed finding into a solo pass.
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({"phases": {"verify": {"verdict": "PASS", "sub_verdicts": {}}}}),
+            encoding="utf-8",
+        )
+        (devlyn / "codex-judge.stdout").write_text(
+            json.dumps({"id": "cj-timeout-high", "severity": "HIGH"}) + "\n",
+            encoding="utf-8",
+        )
+        (devlyn / "verify.pair.timeout.json").write_text(
+            json.dumps({"engine": "codex", "budget_seconds": 600}),
+            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("id") == "verify-pair-emission-contract-violated"
+            for finding in findings
+        ), findings
+        (devlyn / "codex-judge.stdout").unlink()
+        (devlyn / "verify.pair.timeout.json").unlink()
+
+        # iter-0065 case 3: without a marker, required empty pair output remains BLOCKED.
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({
+                "phases": {
+                    "verify": {
+                        "verdict": "PASS",
+                        "sub_verdicts": {},
+                        "pair_trigger": {
+                            "eligible": True,
+                            "reasons": ["risk.high"],
+                            "skipped_reason": None,
+                        },
+                    }
+                }
+            }),
+            encoding="utf-8",
+        )
+        (devlyn / "claude-judge.stdout").write_text("", 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-empty-output"
+            for finding in findings
+        ), findings
+        (devlyn / "claude-judge.stdout").unlink()
+
+        # iter-0065 malformed timeout markers fail closed as a CRITICAL pair blocker.
+        (devlyn / "pipeline.state.json").write_text(
+            json.dumps({"phases": {"verify": {"verdict": "PASS", "sub_verdicts": {}}}}),
+            encoding="utf-8",
+        )
+        (devlyn / "verify.pair.timeout.json").write_text(
+            json.dumps({"engine": "claude", "budget_seconds": 0}),
+            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("id") == "verify-pair-timeout-marker-malformed"
+            and finding.get("severity") == "CRITICAL"
+            for finding in findings
+        ), findings
+        (devlyn / "verify.pair.timeout.json").unlink()
         (devlyn / "pipeline.state.json").write_text(
             json.dumps({
                 "phases": {