specfuse-loop 0.22.0__tar.gz → 0.22.1__tar.gz

{specfuse_loop-0.22.0/specfuse_loop.egg-info → specfuse_loop-0.22.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.22.0
+Version: 0.22.1
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0

{specfuse_loop-0.22.0 → specfuse_loop-0.22.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.22.0"
+version = "0.22.1"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"

{specfuse_loop-0.22.0 → specfuse_loop-0.22.1}/specfuse/agent/providers/bugs.py

@@ -788,7 +788,18 @@ class BugsProvider:
                 label_written=result.label_written,
             )
 
-        return ActionOutcome(status=STATUS_ESCALATED, detail=detail, escalation=escalation)
+        # #3372: only a session that produced NO outcome marker can have an
+        # environmental cause — a dispatch that failed, an empty result, a
+        # crash. `outcome_named` is exactly that distinction, already carried
+        # from the session's own text (#3343). A `refused` is `/fix-bug`
+        # reading the issue and judging it out of scope; three of those say the
+        # queue holds three feature-scoped issues, not that anything is broken.
+        return ActionOutcome(
+            status=STATUS_ESCALATED,
+            detail=detail,
+            escalation=escalation,
+            environmental=not result.outcome_named,
+        )
 
     def reconcile(self, item: ActionItem, outcome: ActionOutcome) -> None:
         return None

{specfuse_loop-0.22.0 → specfuse_loop-0.22.1}/specfuse/agent/run.py

@@ -220,6 +220,24 @@ class ActionOutcome:
     #: same shape as `NON_JUDGE_MODULES` and
     #: `DEPENDENCY_MANIFEST_NAMED_UNCOVERED`.
     escalation_waived: str = ""
+    #: Whether this escalation could have an environmental cause (#3372).
+    #:
+    #: Only an outcome reached WITHOUT reading the item can be about the run's
+    #: environment: a dispatch that failed, a session that produced no outcome
+    #: marker, a crash. An outcome reached BY reading the item is a judgement
+    #: about that item — `/fix-bug`'s `refused` says the work is not bug-sized,
+    #: `ci_not_green` and `pr_not_found` are facts about that issue's PR — and
+    #: three in a row says the queue holds three such issues, not that anything
+    #: is broken.
+    #:
+    #: #3343's breaker counted every escalation and stopped a run that was
+    #: working: two fixes merged, one held on red CI, six correctly declined,
+    #: 19 items never reached, and an escalation asserting an environment
+    #: cause a human then had to disprove.
+    #:
+    #: **Defaults False so a provider must opt in.** A provider that says
+    #: nothing never trips the breaker, rather than tripping it by omission.
+    environmental: bool = False
 
 
 class ActionProvider(Protocol):
@@ -1003,12 +1021,22 @@ def run_agent(
                 # #3343: an escalation whose cause keeps repeating is not about
                 # the item. Counted here rather than in a provider, because only
                 # the run can see that the SAME thing failed N times.
-                signature = failure_signature(item, outcome)
-                if signature == last_failure_signature:
-                    consecutive_identical_failures += 1
+                #
+                # #3372: but only an outcome the provider marks `environmental`
+                # can have an environmental cause. A per-item judgement —
+                # `refused`, `ci_not_green`, `pr_not_found` — RESETS the count
+                # rather than being ignored: a lane still reaching verdicts on
+                # items is not one whose environment is broken.
+                if not outcome.environmental:
+                    last_failure_signature = None
+                    consecutive_identical_failures = 0
                 else:
-                    last_failure_signature = signature
-                    consecutive_identical_failures = 1
+                    signature = failure_signature(item, outcome)
+                    if signature == last_failure_signature:
+                        consecutive_identical_failures += 1
+                    else:
+                        last_failure_signature = signature
+                        consecutive_identical_failures = 1
 
                 if consecutive_identical_failures >= IDENTICAL_FAILURE_LIMIT:
                     run_reason = (

{specfuse_loop-0.22.0 → specfuse_loop-0.22.1}/specfuse/loop/agent_policy.py

@@ -46,6 +46,7 @@ __all__ = (
     "SEVERITY_VALUES",
     "read_severity_label",
     "resolve_severity_aliases",
+    "resolve_required_checks",
     "DEFAULT_SEVERITY_ALIASES",
     "AUTOMERGE_VALUES",
     "GATE_REVIEW_VALUES",
@@ -295,6 +296,45 @@ def resolve_max_items(flag: "int | None",
     return _positive_int_budget(path, "max_items_per_day")
 
 
+def resolve_required_checks(path: "str | Path | None" = None) -> tuple:
+    """`rules.bugs.required_checks` as a tuple of check names, or `()` (#3373).
+
+    The names that must be **present and passing** before the bug lane may
+    auto-merge. Empty when absent or unusable, so a deployment that never
+    declared it behaves exactly as before: any `success` conclusion is accepted.
+
+    Why it exists. `evaluate_merge_guardrails` accepted any `success`, and a
+    repository whose PR job is a deliberate fast lane — excluding a test group
+    that guards committed expectations — gave a `success` that **could not
+    fail** on that class of defect. A bug-lane PR merged under `automerge: "on"`
+    and left `main` red for an hour.
+
+    The split those repositories rely on assumes every change already passed
+    the full gate set before its PR opened. That holds for driver work-unit
+    PRs and does **not** hold for bug-lane PRs, where a headless session
+    chooses which tests to run. This key is how a repository points the lane at
+    the complete check rather than the fast one.
+
+    A string is accepted as a one-element list — the common single-check case —
+    and anything else unusable resolves to `()`. Requiring nothing is the
+    pre-existing behaviour; inventing a requirement from a malformed value
+    would block every merge on a typo.
+    """
+    try:
+        policy = load_policy(path)
+    except (FileNotFoundError, OSError):
+        return ()
+    rules = policy.get("rules") if isinstance(policy, dict) else None
+    bugs = rules.get("bugs") if isinstance(rules, dict) else None
+    raw = bugs.get("required_checks") if isinstance(bugs, dict) else None
+    if isinstance(raw, str):
+        name = raw.strip()
+        return (name,) if name else ()
+    if not isinstance(raw, list):
+        return ()
+    return tuple(str(n).strip() for n in raw if str(n).strip())
+
+
 def resolve_max_open_prs(path: "str | Path | None" = None) -> "int | None":
     """`budgets.max_open_prs`, or None when unset or unusable (#3340).
 

{specfuse_loop-0.22.0 → specfuse_loop-0.22.1}/specfuse/loop/bug_lane_run.py

@@ -38,6 +38,7 @@ from typing import Any, Callable, Optional
 
 from specfuse.loop.agent_policy import (
     bug_lane_ci_wait_seconds,
+    resolve_required_checks,
     bug_lane_limits,
     resolve_bug_automerge,
 )
@@ -197,7 +198,40 @@ _BUCKET_PENDING = "pending"
 _CI_FAILING = "fail"
 
 
-def _read_ci_conclusion_once(runner: Callable, repo: str, pr_number: int) -> str:
+def _required_checks_verdict(rows: list, required) -> str:
+    """`""` when every required check is present and passing, else why not.
+
+    A required check that **never ran** is the case #3373 is about: the
+    repository's PR job was green and the check that would have caught the
+    defect was not in the list at all. It is not a failure — nothing failed —
+    and it is equally not the green the operator asked the lane to require.
+
+    A required check that was **skipped** is treated the same way. Skipping is
+    not a failure in general, which is why `_BUCKETS_OK` tolerates it, but a
+    check an operator named as required and that did not run cannot establish
+    what it was required to establish.
+    """
+    if not required:
+        return ""
+    by_name = {}
+    for row in rows:
+        name = row.get("name")
+        if isinstance(name, str):
+            by_name[name] = str(row.get("bucket") or "").lower()
+    for name in required:
+        bucket = by_name.get(name)
+        if bucket is None:
+            return f"required check never ran: {name}"
+        if bucket == _BUCKET_PENDING:
+            return _CI_PENDING
+        if bucket != "pass":
+            return f"required check not passing: {name} ({bucket})"
+    return ""
+
+
+def _read_ci_conclusion_once(
+    runner: Callable, repo: str, pr_number: int, required=()
+) -> str:
     """One `gh pr checks` read, mapped through `bucket`.
 
     `_CI_PENDING` when any check is queued or running, or when no check is
@@ -244,6 +278,14 @@ def _read_ci_conclusion_once(runner: Callable, repo: str, pr_number: int) -> str
 
     if _BUCKET_PENDING in buckets:
         return _CI_PENDING
+
+    # #3373: the operator's own list, checked before the aggregate verdict.
+    # A repository whose PR job deliberately excludes a test group can point
+    # the lane at the complete check instead of the fast one.
+    verdict = _required_checks_verdict(rows, required)
+    if verdict:
+        return verdict
+
     if buckets <= _BUCKETS_OK:
         return "success"
     return _CI_FAILING
@@ -258,6 +300,7 @@ def pr_ci_conclusion(
     clock: Callable = time.monotonic,
     deadline_seconds: float = CI_WAIT_SECONDS,
     poll_seconds: float = CI_POLL_SECONDS,
+    required_checks=(),
 ) -> str:
     """Wait for `pr_number`'s CI to reach a conclusion, then return it.
 
@@ -284,7 +327,9 @@ def pr_ci_conclusion(
     """
     started = clock()
     while True:
-        conclusion = _read_ci_conclusion_once(runner, repo, pr_number)
+        conclusion = _read_ci_conclusion_once(
+            runner, repo, pr_number, required_checks
+        )
         if conclusion != _CI_PENDING:
             return conclusion
         if clock() - started >= deadline_seconds:
@@ -720,6 +765,11 @@ def run_bug_lane(
     ci_conclusion = pr_ci_conclusion(
         runner, repo, pr_number,
         sleep=ci_sleep, clock=ci_clock, deadline_seconds=deadline_seconds,
+        # #3373: the checks this repository says must be green before the lane
+        # may merge unattended. Empty unless declared, so behaviour is
+        # unchanged for anyone who has not pointed the lane at a complete
+        # check.
+        required_checks=resolve_required_checks(policy_path),
     )
     state_reader = GitHubMergeCapState(runner=runner, repo=repo, now=now)
 

specfuse_loop-0.22.1/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.22.1

{specfuse_loop-0.22.0 → specfuse_loop-0.22.1}/specfuse/loop/loop.py

@@ -125,7 +125,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.22.0"
+DRIVER_VERSION = "0.22.1"
 # Oldest scaffold layout this driver can drive. init.sh stamps the scaffold's own
 # version into `.specfuse/VERSION`; check_scaffold_version() fails loud at startup if
 # the consumer's scaffold is older than this, pointing at `specfuse upgrade`. Bump

{specfuse_loop-0.22.0 → specfuse_loop-0.22.1/specfuse_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.22.0
+Version: 0.22.1
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0

{specfuse_loop-0.22.0 → specfuse_loop-0.22.1}/specfuse_loop.egg-info/SOURCES.txt

@@ -516,6 +516,7 @@ tests/test_replan_note_collision.py
 tests/test_replan_trigger.py
 tests/test_replan_turn_contract.py
 tests/test_replay_spin.py
+tests/test_required_checks.py
 tests/test_resolve_base.py
 tests/test_restart_cap_counts_progress.py
 tests/test_result_block.py

specfuse_loop-0.22.1/tests/test_required_checks.py

@@ -0,0 +1,161 @@
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+"""`rules.bugs.required_checks` — the lane states what green it requires (#3373).
+
+`automerge` merged a PR that left `main` red for an hour. All six guardrails
+passed and `ci_conclusion` was `success`, because that repository's PR job is
+deliberately a fast lane excluding the `regression` group — and both tests the
+fix broke carry `@Tag("regression")`. The check the lane read **could not
+fail** on that class of defect.
+
+The nightly's own header states the assumption the split rests on: *"every
+change had already passed it in the loop's `code` gate before its PR was
+opened"*. True for driver work-unit PRs. **Not** true for bug-lane PRs, where a
+headless session chooses which tests to run and reports the ones it chose.
+"""
+
+from __future__ import annotations
+
+import json
+import textwrap
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from types import SimpleNamespace
+
+from specfuse.loop.agent_policy import resolve_required_checks
+from specfuse.loop.bug_lane_run import pr_ci_conclusion
+
+_BASE = """\
+version: 1
+queue: []
+rules:
+  bugs:
+    preempt: true
+    min_severity: medium
+    automerge: "on"
+{extra}  features:
+    gate_review: human
+    wip_limit: 1
+  triage:
+    auto: false
+budgets:
+  max_tokens_per_run: 100000
+  max_open_prs: 5
+  max_items_per_day: 10
+escalation:
+  provider: none
+  webhook_env: ""
+  assignee: ""
+  quiet_hours: ""
+  sla_hours: 24
+  silence_hours: 24
+"""
+
+
+def _runner_for(rows):
+    def runner(argv, check=False):
+        if argv[:3] == ["gh", "pr", "checks"]:
+            return SimpleNamespace(returncode=0, stdout=json.dumps(rows), stderr="")
+        return SimpleNamespace(returncode=0, stdout="", stderr="")
+    return runner
+
+
+def _conclusion(rows, required=()):
+    return pr_ci_conclusion(
+        _runner_for(rows), "acme/widget", 7,
+        sleep=lambda _s: None, clock=lambda: 0.0,
+        deadline_seconds=0.0, poll_seconds=0.0,
+        required_checks=required,
+    )
+
+
+class ResolvingTheKey(unittest.TestCase):
+
+    def setUp(self):
+        self._tmp = TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+
+    def _write(self, extra: str = "") -> str:
+        p = Path(self._tmp.name) / "agent-policy.yml"
+        p.write_text(_BASE.format(extra=extra), encoding="utf-8")
+        return str(p)
+
+    def test_absent_key_requires_nothing(self):
+        self.assertEqual(resolve_required_checks(self._write()), ())
+
+    def test_a_declared_list_resolves(self):
+        block = textwrap.indent("required_checks:\n  - full-suite\n  - nightly\n", "    ")
+        self.assertEqual(resolve_required_checks(self._write(block)), ("full-suite", "nightly"))
+
+    def test_a_string_is_the_single_check_case(self):
+        block = textwrap.indent("required_checks: full-suite\n", "    ")
+        self.assertEqual(resolve_required_checks(self._write(block)), ("full-suite",))
+
+    def test_a_malformed_value_requires_nothing_rather_than_blocking_everything(self):
+        block = textwrap.indent("required_checks: 7\n", "    ")
+        self.assertEqual(resolve_required_checks(self._write(block)), ())
+
+    def test_a_missing_file_requires_nothing(self):
+        self.assertEqual(resolve_required_checks("/nonexistent/agent-policy.yml"), ())
+
+
+class TheGreenTheLaneReads(unittest.TestCase):
+
+    def test_without_required_checks_behaviour_is_unchanged(self):
+        rows = [{"bucket": "pass", "name": "build", "state": "SUCCESS"}]
+        self.assertEqual(_conclusion(rows), "success")
+
+    def test_a_required_check_that_passed_is_success(self):
+        rows = [
+            {"bucket": "pass", "name": "build", "state": "SUCCESS"},
+            {"bucket": "pass", "name": "full-suite", "state": "SUCCESS"},
+        ]
+        self.assertEqual(_conclusion(rows, ("full-suite",)), "success")
+
+    def test_a_required_check_that_never_ran_is_not_success(self):
+        # THE MEASURED CASE: the PR job is green and the check that would have
+        # caught the defect is not in the list at all.
+        rows = [{"bucket": "pass", "name": "build", "state": "SUCCESS"}]
+        got = _conclusion(rows, ("full-suite",))
+        self.assertNotEqual(got, "success")
+        self.assertIn("full-suite", got)
+
+    def test_a_required_check_that_failed_is_not_success(self):
+        rows = [
+            {"bucket": "pass", "name": "build", "state": "SUCCESS"},
+            {"bucket": "fail", "name": "full-suite", "state": "FAILURE"},
+        ]
+        self.assertNotEqual(_conclusion(rows, ("full-suite",)), "success")
+
+    def test_a_required_check_that_was_skipped_is_not_success(self):
+        # Skipping is not a failure in general, which is why _BUCKETS_OK
+        # tolerates it — but a check an operator NAMED as required and that did
+        # not run cannot establish what it was required to establish.
+        rows = [
+            {"bucket": "pass", "name": "build", "state": "SUCCESS"},
+            {"bucket": "skipping", "name": "full-suite", "state": "SKIPPED"},
+        ]
+        got = _conclusion(rows, ("full-suite",))
+        self.assertNotEqual(got, "success")
+        self.assertIn("full-suite", got)
+
+
+class TheDeclineIsStillADecline(unittest.TestCase):
+
+    def test_a_non_success_conclusion_declines_the_merge(self):
+        from specfuse.loop.bug_lane import REASON_CI_NOT_GREEN, evaluate_merge_guardrails
+
+        decision = evaluate_merge_guardrails(
+            changed_files=["src/a.py", "tests/test_a.py"],
+            ci_conclusion="required check never ran: full-suite",
+            diff_lines=10, max_diff_lines=400,
+            provenance="issue", max_merges_per_day=3,
+            state_reader=lambda: 0,
+        )
+        self.assertFalse(decision.eligible)
+        self.assertEqual(decision.reason, REASON_CI_NOT_GREEN)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

{specfuse_loop-0.22.0 → specfuse_loop-0.22.1}/tests/test_run_level_failure_breaker.py

@@ -62,6 +62,10 @@ class _AlwaysFailsTheSameWay:
             status=STATUS_ESCALATED,
             detail=self._template.format(n=number),
             escalation=None,
+            # The #3342 scenario these tests model — a dispatched command that
+            # did not resolve — is environmental, and since #3372 a provider
+            # must say so for the breaker to count it.
+            environmental=True,
             escalation_waived="test double: the escalation trace is not this test's subject",
         )
 
@@ -150,6 +154,7 @@ class TheBreakerStopsTheRun(unittest.TestCase):
                 return ActionOutcome(
                     status=STATUS_ESCALATED,
                     detail=f"could_not_proceed: {words[len(self.executed) - 1]}",
+                    environmental=True,
                     escalation_waived="test double",
                 )
 
@@ -210,3 +215,111 @@ class TheTemplateStopsAssertingARefusal(unittest.TestCase):
             "the promote-to-feature advice must not appear when the skill "
             "never ran — that is what would have promoted 55 bugs",
         )
+
+
+class OnlyEnvironmentalFailuresCount(unittest.TestCase):
+    """#3372: the breaker counted `refused`, which is a per-item judgement.
+
+    `/fix-bug` refuses when it reads an issue and decides the work is not
+    bug-sized — SKILL.md: "Refuses if the work is large/complex/risky and
+    proposes promoting to a feature instead". Three in a row means the queue
+    holds three feature-scoped issues, which is unremarkable in a backlog.
+
+    Measured: a run worked 10 of 29 items — two fixes merged, one held on red
+    CI, six declined — and the breaker stopped the remaining 19, reporting
+    "the cause is this run's environment" about a lane that was working.
+
+    The distinction #3343 failed to draw: some outcomes are reached WITHOUT
+    reading the item (dispatch failed, no session ran) and some are reached BY
+    reading it. Only the first can be environmental.
+    """
+
+    def _provider(self, outcomes):
+        """outcomes: list of (detail, environmental)."""
+        seq = list(outcomes)
+
+        class _Scripted:
+            def __init__(self):
+                self.executed = []
+                self._items = [
+                    ActionItem(item_id=f"bug-{i}", kind="bug", summary="", queue_key=None)
+                    for i in range(1, len(seq) + 1)
+                ]
+
+            def advertise(self, snapshot):
+                return tuple(i for i in self._items if i.item_id not in self.executed)
+
+            def execute(self, item):
+                detail, env = seq[len(self.executed)]
+                self.executed.append(item.item_id)
+                return ActionOutcome(
+                    status=STATUS_ESCALATED, detail=detail,
+                    environmental=env,
+                    escalation_waived="test double",
+                )
+
+            def reconcile(self, item, outcome):
+                return None
+
+        return _Scripted()
+
+    def test_consecutive_refusals_never_stop_the_run(self):
+        provider = self._provider([("refused", False)] * 6)
+        summary = _run(provider, [])
+        self.assertEqual(len(provider.executed), 6)
+        self.assertNotEqual(summary.stop_reason, STOP_RUN_LEVEL_FAILURE)
+
+    def test_consecutive_environmental_failures_still_stop_it(self):
+        provider = self._provider([("could_not_proceed: Unknown command", True)] * 9)
+        summary = _run(provider, [])
+        self.assertEqual(len(provider.executed), IDENTICAL_FAILURE_LIMIT)
+        self.assertEqual(summary.stop_reason, STOP_RUN_LEVEL_FAILURE)
+
+    def test_a_per_item_judgement_between_them_resets_the_count(self):
+        # A lane that successfully judges an item in between is not one whose
+        # environment is broken.
+        provider = self._provider([
+            ("could_not_proceed: Unknown command", True),
+            ("could_not_proceed: Unknown command", True),
+            ("refused", False),
+            ("could_not_proceed: Unknown command", True),
+            ("could_not_proceed: Unknown command", True),
+        ])
+        summary = _run(provider, [])
+        self.assertEqual(len(provider.executed), 5)
+        self.assertNotEqual(summary.stop_reason, STOP_RUN_LEVEL_FAILURE)
+
+    def test_environmental_defaults_false_so_a_provider_must_opt_in(self):
+        # Fail-safe direction: a provider that says nothing never trips the
+        # breaker, rather than tripping it by omission.
+        self.assertFalse(ActionOutcome(status=STATUS_ESCALATED, detail="x").environmental)
+
+
+class TheProviderActuallySetsIt(unittest.TestCase):
+    """Without this the breaker never fires in production and #3372's fix
+    would be one hollow guard replacing another."""
+
+    def _run_execute(self, *, outcome_named: bool, outcome: str):
+        from unittest.mock import patch
+        from specfuse.agent.providers.bugs import BugsProvider
+        from specfuse.loop.bug_lane_run import BugLaneResult
+
+        provider = BugsProvider(repo="acme/widget", runner=lambda *a, **k: None)
+        item = ActionItem(item_id="bug-7", kind="bug", summary="", queue_key=None)
+        result = BugLaneResult(
+            outcome=outcome, reason=None, pr_number=None,
+            stop_rationale="whatever", outcome_named=outcome_named,
+        )
+        with patch("specfuse.agent.providers.bugs.run_bug_lane", return_value=result), \
+             patch("specfuse.agent.providers.bugs._wip_ref_for_item", return_value=None):
+            return provider.execute(item)
+
+    def test_a_session_that_named_no_outcome_is_environmental(self):
+        self.assertTrue(self._run_execute(outcome_named=False, outcome="could_not_proceed").environmental)
+
+    def test_a_refusal_the_session_named_is_not(self):
+        self.assertFalse(self._run_execute(outcome_named=True, outcome="refused").environmental)
+
+    def test_a_named_could_not_proceed_is_not_either(self):
+        # The skill ran, read the issue, and could not proceed on ITS terms.
+        self.assertFalse(self._run_execute(outcome_named=True, outcome="could_not_proceed").environmental)

specfuse_loop-0.22.0/specfuse/loop/data/VERSION

@@ -1 +0,0 @@
-0.22.0