specfuse-loop 0.23.2__tar.gz → 0.24.0__tar.gz

{specfuse_loop-0.23.2/specfuse_loop.egg-info → specfuse_loop-0.24.0}/PKG-INFO

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

{specfuse_loop-0.23.2 → specfuse_loop-0.24.0}/pyproject.toml

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

{specfuse_loop-0.23.2 → specfuse_loop-0.24.0}/specfuse/agent/providers/triage.py

@@ -40,7 +40,11 @@ from specfuse.agent.invoke import run_claude, usage_spend
 from specfuse.agent.state import AgentSnapshot
 from specfuse.agent.triage_invoke import build_invocation, classify_result, classify_severity
 from specfuse.loop.escalation import CATEGORY_LABELS
-from specfuse.loop.labels import read_severity_rubric
+from specfuse.loop.labels import (
+    list_existing_labels,
+    read_severity_rubric,
+    severity_label_projection,
+)
 from specfuse.loop.triage import CATEGORIES, apply_triage, list_untriaged
 
 _ITEM_ID_PREFIX = "triage-"
@@ -188,6 +192,7 @@ class TriageProvider:
         self._rows: dict = {}
         self._auto = False
         self._rubric: Any = _RUBRIC_UNSET
+        self._projection: Any = _RUBRIC_UNSET
 
     def _rubric_for_run(self) -> dict:
         """The repository's severity rubric, read at most once per run
@@ -195,14 +200,40 @@ class TriageProvider:
         `execute()` call after an `advertise()`, so a run that classifies
         nothing issues no `gh label list` at all."""
         if self._rubric is _RUBRIC_UNSET:
-            self._rubric = read_severity_rubric(
-                self._working_dir, runner=self._runner, repo=self._repo
-            )
+            self._read_labels_once()
         return self._rubric
 
+    def _projection_for_run(self) -> dict:
+        """`{canonical value: the label this repository spells it with}` (#3386).
+
+        Triage wrote canonical labels a repository may never have defined; the
+        write failed, and because the bug lane reads severity from the label
+        rather than the marker, triage removed from the lane the issues it had
+        just classified for it. Derived from the same listing as the rubric —
+        one `gh label list` per run, which is the invariant that accessor
+        already carried."""
+        if self._projection is _RUBRIC_UNSET:
+            self._read_labels_once()
+        return self._projection
+
+    def _read_labels_once(self) -> None:
+        existing, _reason = list_existing_labels(
+            self._working_dir, runner=self._runner, repo=self._repo
+        )
+        self._rubric = read_severity_rubric(
+            self._working_dir, runner=self._runner, repo=self._repo,
+            existing=existing,
+        )
+        try:
+            names = [item["name"] for item in (existing or [])]
+        except (TypeError, KeyError):
+            names = []
+        self._projection = severity_label_projection(names)
+
     def advertise(self, snapshot: AgentSnapshot) -> Sequence[ActionItem]:
         self._auto = snapshot.triage_auto
         self._rubric = _RUBRIC_UNSET
+        self._projection = _RUBRIC_UNSET
         rows = list_untriaged(self._runner, self._repo)
 
         self._rows = {}
@@ -250,7 +281,9 @@ class TriageProvider:
                     "labels": row.get("labels") or [],
                 }
             ]
-            results = apply_triage(self._runner, self._repo, decisions, auto=self._auto)
+            results = apply_triage(
+                self._runner, self._repo, decisions, auto=self._auto,
+                label_projection=self._projection_for_run())
             row_result = results[0]
             if row_result.get("label_written"):
                 return ActionOutcome(
@@ -337,7 +370,9 @@ class TriageProvider:
                 "severity": severity,
             }
         ]
-        results = apply_triage(self._runner, self._repo, decisions, auto=self._auto)
+        results = apply_triage(
+            self._runner, self._repo, decisions, auto=self._auto,
+            label_projection=self._projection_for_run())
         row_result = results[0]
 
         if row_result.get("skipped"):

{specfuse_loop-0.23.2 → specfuse_loop-0.24.0}/specfuse/agent/run.py

@@ -76,6 +76,13 @@ STATUS_ESCALATED = "escalated"
 #: (FEAT-2026-0108/T02). Not one of `budget.py`'s stop reasons -- nothing was
 #: budgeted, because nothing was dispatched.
 STOP_DIRTY_TREE = "dirty_tree"
+#: The run could not read the queue it was meant to work through (#3392).
+#: Distinct from `STOP_DRAINED`, which means the opposite: a drained run saw
+#: everything there was and finished it. Reported identically, they are
+#: indistinguishable in the summary — the part an operator reads and the only
+#: part automation parses — so a nightly run whose credentials broke looks like
+#: a quiet backlog.
+STOP_SNAPSHOT_UNREADABLE = "snapshot_unreadable"
 
 KIND_BUG = "bug"
 KIND_FEATURE = "feature"
@@ -706,6 +713,43 @@ def _refuse_dirty_tree(reason: str, report: Callable[[str], None]) -> RunSummary
     )
 
 
+def _refuse_unreadable_snapshot(reason: str, *, report) -> "RunSummary":
+    """Refuse a run whose issue listing failed, rather than draining it (#3392).
+
+    Every provider that matters reads `snapshot.issues`, so a run without it
+    can do nothing except mislead. Shaped like `_refuse_dirty_tree`: zero
+    attempted, zero completed, one escalation carrying the reason, and a
+    distinct stop reason so the summary cannot be mistaken for a healthy run
+    against an empty queue.
+
+    Refusing is the conservative direction here for the same reason it is
+    there. A blind run that dispatches nothing has cost nothing; a blind run
+    reported as `drained` costs the operator their belief that the queue is
+    empty.
+    """
+    report(f"run refused to start — {reason}")
+    return RunSummary(
+        items_attempted=0,
+        items_completed=0,
+        items_escalated=1,
+        stop_reason=STOP_SNAPSHOT_UNREADABLE,
+        elapsed_minutes=0.0,
+        tokens_spent=0,
+        escalations=(Escalation(item_id="run:snapshot", reason=reason),),
+    )
+
+
+def exit_code_for(stop_reason: str) -> int:
+    """The process exit code a run ending in *stop_reason* should report.
+
+    Non-zero only for a refusal — a run that did not happen. Every outcome,
+    including `drained`, keeps 0: those are runs that ran. Narrow on purpose,
+    so a new stop reason does not silently become a failing exit code for
+    whatever automation is watching.
+    """
+    return 1 if stop_reason == STOP_SNAPSHOT_UNREADABLE else 0
+
+
 def _dirty_tree_reason(paths) -> str:
     shown = ", ".join(paths[:10])
     if len(paths) > 10:
@@ -799,6 +843,31 @@ def run_agent(
             if error:
                 report(f"snapshot: {section} unreadable — {error}")
 
+        # #3392: an unreadable issue listing is not an empty queue. Every
+        # provider that matters reads `snapshot.issues`, so continuing here
+        # finds no candidates and stops with `drained` — "worked through
+        # everything there was" reported for "could not see anything". Measured
+        # with nine dispatchable bugs in the queue at the time.
+        if snapshot.issues_error:
+            return _refuse_unreadable_snapshot(
+                f"the issue listing failed, so the queue could not be read: "
+                f"{snapshot.issues_error}",
+                report=report,
+            )
+
+        # The PR listing failing is NOT a refusal: `max_open_prs` deliberately
+        # reads an unreadable listing as zero rather than firing on a number
+        # the run could not measure. But that leaves the cap silently disabled
+        # for this run, so the summary says so rather than the operator finding
+        # it in the log. Whether it should refuse instead is a live question
+        # (#3392 item 3) and not decided here.
+        if snapshot.prs_error:
+            report(
+                "snapshot: max_open_prs is NOT enforced this run — the PR "
+                "listing could not be read, so the cap has no number to "
+                "measure against"
+            )
+
         budget_kwargs = {}
         if pause_marker is not None:
             budget_kwargs["pause_marker"] = pause_marker
@@ -1294,7 +1363,9 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
         worktree.restore_branch(started_on, report=_default_reporter)
 
     print(_format_summary(summary))
-    return 0
+    # #3392: a refusal exits non-zero so a scheduled run's exit status is
+    # self-describing without its log. Outcomes — `drained` included — keep 0.
+    return exit_code_for(summary.stop_reason)
 
 
 if __name__ == "__main__":

specfuse_loop-0.24.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.24.0

{specfuse_loop-0.23.2 → specfuse_loop-0.24.0}/specfuse/loop/data/docs/methodology.md

@@ -759,7 +759,17 @@ when and how these get created.
 | State backend  | WU / GATE file frontmatter          | GitHub issue labels + feature registry |
 | Dispatch       | driver shells out (`claude -p`)     | inbox files + polling loop             |
 | Branch / merge | one branch, squash per WU            | branch + PR per task, merge watcher    |
-| Spec front-end | optional; task graph authored directly | spec-first (specs agent + codegen)  |
+| Spec front-end | one of: **none** (task graph authored directly), **consumed** (specs authored upstream, the loop implements against a handoff manifest), or **authored** (the spec tree is the deliverable — work units author spec files) | spec-first (specs agent + codegen), from a dossier **or** from an upstream handoff manifest |
+
+The loop's spec front-end is three-valued because a repository whose entire
+deliverable **is** the spec tree fits neither of the two values this row
+carried before (#3407): it is not "optional", and the task graph is not
+"authored directly" — the work units author spec files. One consumer carried
+that third case in about forty lines of project `CLAUDE.md` because the row
+could not express it. In the **authored** mode the work-unit contract picks up
+two constraints that do not apply to code units — see
+`authoring-work-units` §6 (the whole tree validates) and §12 (a structural
+assertion substitutes for the red test).
 
 Everything above those rows — the unit hierarchy, ownership split, WU contract,
 verification-as-oracle, the gate cycle, plan-next, LEARNINGS, and autonomy — is

{specfuse_loop-0.23.2 → specfuse_loop-0.24.0}/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.23.2"
+DRIVER_VERSION = "0.24.0"
 # 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
@@ -9488,6 +9488,15 @@ def capture_gate_diff(
     return "\n\n".join(parts)
 
 
+def _is_relative_to(path: Path, other: Path) -> bool:
+    """`Path.is_relative_to`, tolerant of paths that do not resolve."""
+    try:
+        path.relative_to(other)
+    except ValueError:
+        return False
+    return True
+
+
 def write_judge_followups(
     feature_dir: Path, gate_number: int, findings: list,
 ) -> Path:
@@ -9644,6 +9653,32 @@ def judge_close(
             feature_dir, gate_number, result.findings)
         payload["lowered"] = True
         payload["verdict"] = "not_met"
+        # Say WHERE the findings went (#3406). They are written verbatim to
+        # FOLLOW-UPS.md above and committed below, but the event said only
+        # `findings: N` with `reason: null` — so a reader of events.jsonl had
+        # nothing pointing out of it. One operator searched events.jsonl,
+        # `work/` and for a repository-level judge artifact, concluded the text
+        # did not exist, and priced a third close at ~$12 to re-derive a
+        # finding that was sitting in a committed file.
+        #
+        # The criteria go in; the finding TEXT deliberately does not. It is
+        # already recorded verbatim in one place, and copying it into a second
+        # invites the two to disagree — `write_judge_followups` exists so the
+        # judge's words are not reformatted by the driver.
+        payload["findings_path"] = str(
+            Path(followups).relative_to(Path(feature_dir).parent.parent)
+            if _is_relative_to(Path(followups), Path(feature_dir).parent.parent)
+            else Path(followups)
+        )
+        payload["finding_criteria"] = [
+            f.criterion for f in result.findings if getattr(f, "criterion", None)
+        ]
+        _named = ", ".join(payload["finding_criteria"]) or "no named criterion"
+        payload["reason"] = (
+            f"judge lowered the verdict on {payload['findings']} finding(s) "
+            f"({_named}); the judge's own words are in "
+            f"{payload['findings_path']}"
+        )
         commit_bookkeeping(
             [wu.file, followups],
             f"chore(loop): {wu.wu_id} judge lowered verdict to not_met"

{specfuse_loop-0.23.2 → specfuse_loop-0.24.0}/specfuse/loop/red_on_base.py

@@ -52,6 +52,12 @@ from pathlib import Path
 from typing import Any, Callable, Optional
 
 
+#: POSIX reserves these for the shell's own failure to run the command: 126 is
+#: "found but not executable", 127 is "not found". Neither says anything about
+#: the test, so neither may be read as a verdict on it (#3403).
+_COULD_NOT_EXECUTE = frozenset({126, 127})
+
+
 def select_test_files(changed_files: Any, test_paths: Any) -> list:
     """The changed files that live under a declared test root.
 
@@ -126,6 +132,19 @@ def test_was_red_on_base(
         code = getattr(result, "returncode", None)
         if not isinstance(code, int):
             return None
+        if code in _COULD_NOT_EXECUTE:
+            # The shell could not run the command at all. That is "the check
+            # never ran", not "the test failed" -- and the difference is the
+            # whole point of keeping those two declining reasons apart.
+            #
+            # Measured: an operator whose command is a committed script hits
+            # this on every PR whose merge base predates that script. The
+            # worktree is the BASE tree, so the script is simply absent there,
+            # `sh` exits 127, and reading that as red would let the merge
+            # through on the strength of a command that never ran. Fail-open,
+            # in the one guardrail whose entire job is to be harder to satisfy
+            # than the others.
+            return None
         # Non-zero at the base is the proof we want: the test the PR adds does
         # not hold on the tree the fix was written against.
         return code != 0

{specfuse_loop-0.23.2 → specfuse_loop-0.24.0}/specfuse/loop/triage.py

@@ -182,7 +182,10 @@ def _list_open_issues(runner: Callable, repo: str, *, limit: int) -> list:
         return []
 
 
-def apply_triage(runner: Callable, repo: str, decisions: list, *, auto: bool = False) -> list:
+def apply_triage(
+    runner: Callable, repo: str, decisions: list, *,
+    auto: bool = False, label_projection: "dict | None" = None,
+) -> list:
     """Record each decision in `decisions` against its GitHub issue.
 
     Each decision is a mapping carrying at least `number`, `body` (the
@@ -195,6 +198,18 @@ def apply_triage(runner: Callable, repo: str, decisions: list, *, auto: bool = F
     marker. But a marker with no matching label on the issue (the label
     write failed on an earlier pass, e.g. because the label did not exist
     yet) is not fully idempotent -- it is missing its projection, so this
+    `label_projection` maps a canonical severity value to the label this
+    repository actually spells it with (`labels.severity_label_projection`,
+    #3386). Without it `severity_aliases` was one-directional: the bug lane
+    translated a repository's own words inbound while triage wrote canonical
+    words outbound, which that repository may never have defined. The write then
+    failed, and since the lane reads severity from the LABEL rather than the
+    marker, triage removed from the lane the very issues it had just classified
+    for it. The marker always records the canonical value, so it stays
+    comparable across repositories; only the label takes the operator's word.
+    Absent, or missing a value, the canonical label is written — the behaviour
+    before the projection existed.
+
     retries only the label write. `decision["labels"]` (as returned by
     `gh issue list --json ...,labels`, i.e. a list of `{"name": ...}`
     mappings) is what `labels` is checked against; a decision with no
@@ -226,7 +241,10 @@ def apply_triage(runner: Callable, repo: str, decisions: list, *, auto: bool = F
             marked_severity = (parse_marker_fields(body) or {}).get("severity")
             target_labels = labels_for(marked_category) if marked_category in CATEGORIES else ()
             if marked_severity:
-                target_labels = tuple(target_labels) + (severity_label_for(marked_severity),)
+                target_labels = tuple(target_labels) + (
+                    (label_projection or {}).get(
+                        marked_severity, severity_label_for(marked_severity)),
+                )
             existing_labels = {
                 label.get("name") for label in decision.get("labels") or []
             }
@@ -288,7 +306,9 @@ def apply_triage(runner: Callable, repo: str, decisions: list, *, auto: bool = F
 
         labels_to_add = list(labels_for(applied_category))
         if severity:
-            labels_to_add.append(severity_label_for(severity))
+            labels_to_add.append(
+                (label_projection or {}).get(
+                    severity, severity_label_for(severity)))
 
         try:
             runner(

{specfuse_loop-0.23.2 → specfuse_loop-0.24.0/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.23.2 → specfuse_loop-0.24.0}/specfuse_loop.egg-info/SOURCES.txt

@@ -224,6 +224,7 @@ tests/test_binary_verdict.py
 tests/test_binding_block_advisory.py
 tests/test_binding_block_allocation.py
 tests/test_binding_block_budget.py
+tests/test_blind_run_is_not_drained.py
 tests/test_bookkeeping_commit_crash_run.py
 tests/test_bookkeeping_commit_hook_crash.py
 tests/test_bookkeeping_no_verify.py
@@ -382,6 +383,7 @@ tests/test_judge_cost_fold_committed.py
 tests/test_judge_module.py
 tests/test_judge_path_registry.py
 tests/test_judge_terminal_flip_state.py
+tests/test_judged_event_points_at_findings.py
 tests/test_label_description_length.py
 tests/test_label_provisioning_runner_contract.py
 tests/test_label_registry.py
@@ -571,6 +573,7 @@ tests/test_severity_rubric.py
 tests/test_shipped_templates_parse.py
 tests/test_skill_discovery_links.py
 tests/test_skills_vendored_in_sync.py
+tests/test_spec_work_unit_rules.py
 tests/test_spinning_rearm_gate.py
 tests/test_spinout_brief_end_to_end.py
 tests/test_spinout_brief_replan_option.py
@@ -587,6 +590,7 @@ tests/test_tiered_verification_e2e.py
 tests/test_timeout_kill_portable.py
 tests/test_triage.py
 tests/test_triage_apply.py
+tests/test_triage_projects_severity_label.py
 tests/test_triage_severity_classify.py
 tests/test_triage_severity_end_to_end.py
 tests/test_triage_severity_write.py

specfuse_loop-0.24.0/tests/test_blind_run_is_not_drained.py

@@ -0,0 +1,105 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+"""A run that could not see the queue does not report `drained` (#3392).
+
+When the snapshot's issue listing failed, `run_agent` reported the failure,
+treated the listing as empty, found no candidates and stopped with `drained` —
+exit 0, zero attempted, zero escalated.
+
+Observed with nine dispatchable bugs in the queue, two of them deliberately
+ranked first for that run:
+
+    snapshot: 0 open issues, 0 open PRs, 115 features, queue=0
+    snapshot: issues unreadable — gh issue list ... tls: failed to verify certificate
+    run finished — drained after 0.00 minutes
+    stop reason:      drained
+
+`drained` means "worked through everything there was". Here it meant "could not
+see anything". The two are opposite, and the summary — the part an operator
+reads, and the only part automation parses — rendered them identically.
+
+This is the shape this project keeps finding: **a failure reported in the
+grammar of success.** An unattended runner is where it costs most; a scheduled
+run reporting `drained` every night while its credentials are broken looks like
+a quiet backlog.
+
+Refusing rather than draining follows `STOP_DIRTY_TREE`'s precedent: nothing was
+budgeted because nothing was dispatched, and every provider that matters reads
+`snapshot.issues`, so a run without it can do nothing except mislead.
+"""
+
+from __future__ import annotations
+
+import unittest
+
+from specfuse.agent.run import (
+    STOP_DRAINED,
+    STOP_SNAPSHOT_UNREADABLE,
+    _refuse_unreadable_snapshot,
+    exit_code_for,
+)
+
+
+class _Snapshot:
+    def __init__(self, issues_error=None, prs_error=None):
+        self.issues_error = issues_error
+        self.prs_error = prs_error
+
+
+class TheRefusal(unittest.TestCase):
+
+    def _refuse(self, reason="gh issue list exited 1: tls: failed to verify"):
+        lines = []
+        summary = _refuse_unreadable_snapshot(reason, report=lines.append)
+        return summary, lines
+
+    def test_it_does_not_report_drained(self):
+        summary, _ = self._refuse()
+
+        self.assertEqual(STOP_SNAPSHOT_UNREADABLE, summary.stop_reason)
+        self.assertNotEqual(STOP_DRAINED, summary.stop_reason)
+
+    def test_nothing_is_attempted_or_completed(self):
+        summary, _ = self._refuse()
+
+        self.assertEqual(0, summary.items_attempted)
+        self.assertEqual(0, summary.items_completed)
+
+    def test_it_escalates_so_the_summary_is_not_silent(self):
+        summary, _ = self._refuse()
+
+        self.assertEqual(1, summary.items_escalated)
+        self.assertEqual(1, len(summary.escalations))
+
+    def test_the_escalation_carries_which_listing_failed(self):
+        summary, _ = self._refuse("gh issue list exited 1: tls: bad cert")
+
+        self.assertIn("tls: bad cert", summary.escalations[0].reason)
+
+    def test_it_says_so_on_the_way_out(self):
+        _, lines = self._refuse()
+
+        self.assertTrue(
+            any("refused" in line for line in lines),
+            f"the run must say it refused, not finish quietly: {lines}",
+        )
+
+
+class TheExitCode(unittest.TestCase):
+    """A scheduled run's output must be self-describing without its log."""
+
+    def test_a_blind_run_exits_non_zero(self):
+        self.assertNotEqual(0, exit_code_for(STOP_SNAPSHOT_UNREADABLE))
+
+    def test_a_genuinely_drained_run_still_exits_zero(self):
+        self.assertEqual(0, exit_code_for(STOP_DRAINED))
+
+    def test_an_unknown_reason_does_not_invent_a_failure(self):
+        # Every other stop reason kept exit 0; this narrows to the one case
+        # that is a refusal rather than an outcome.
+        self.assertEqual(0, exit_code_for("some_future_reason"))
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()

specfuse_loop-0.24.0/tests/test_judged_event_points_at_findings.py

@@ -0,0 +1,137 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+"""The `judged` event says where the judge's findings went (#3406).
+
+The issue reported that a judge lowering a terminal verdict "persists no
+findings". It does persist them: `write_judge_followups` writes each finding
+verbatim into `FOLLOW-UPS.md` and `commit_bookkeeping` commits it. Verified in
+the reporting repository's own history — `chore(loop): FEAT-2026-0168/G1-CLOSE
+judge lowered verdict to not_met` contains "Filed by the judge for gate 1. Each
+entry is the judge's own words."
+
+What is missing is the pointer. The `judged` event records `findings: 1` and
+`reason: null`, and names nothing. The reporter looked in `events.jsonl`, in
+`<feature>/work/`, and for a repository-level judge artifact — the three places
+the event gave them no reason to leave — and concluded the text was nowhere.
+They then priced a third close at ~$12 to re-derive a finding that was sitting
+in a committed file.
+
+So the event becomes self-describing: it names the file the findings were
+written to and the criteria they were raised against, and its `reason` stops
+being `null` on the one path where something specific was found.
+
+The finding TEXT deliberately stays out of the event. It is already recorded
+verbatim in one place; copying it into a second invites the two to disagree,
+and `write_judge_followups` exists precisely so the judge's words are not
+reformatted by the driver.
+"""
+
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+from tempfile import TemporaryDirectory
+from types import SimpleNamespace
+from unittest import mock
+
+from tests._loop_loader import load_loop
+
+loop = load_loop()
+
+
+class _Finding:
+    def __init__(self, criterion, text):
+        self.criterion = criterion
+        self.text = text
+
+
+class TheLoweredEventNamesTheRecord(unittest.TestCase):
+
+    def _payload_for(self, findings):
+        """Drive judge_close's lowered branch with the file writes stubbed."""
+        tmp = TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        feature_dir = Path(tmp.name)
+        (feature_dir / "PLAN.md").write_text("---\nfeature_id: FEAT-2026-9999\n---\n")
+        wu_file = feature_dir / "WU-90-close.md"
+        wu_file.write_text("---\nid: FEAT-2026-9999/G1-CLOSE\nverdict: met\n---\n")
+        wu = SimpleNamespace(
+            file=wu_file, wu_id="FEAT-2026-9999/G1-CLOSE", verdict="met")
+
+        result = SimpleNamespace(verdict="not_met", findings=findings, reason=None)
+
+        with mock.patch.object(loop, "_gate_identity",
+                               return_value=(1, feature_dir / "GATE-01.md")), \
+             mock.patch.object(loop, "_judge_disabled", return_value=False), \
+             mock.patch.object(loop, "resolve_gate_start_sha",
+                               return_value=("abc123", "gate frontmatter")), \
+             mock.patch.object(loop, "capture_gate_diff", return_value="diff"), \
+             mock.patch.object(loop, "build_judge_bundle", return_value={}), \
+             mock.patch.object(loop, "render_judge_prompt", return_value="prompt"), \
+             mock.patch.object(loop, "parse_judge_result", return_value=result), \
+             mock.patch.object(loop, "write_frontmatter_field"), \
+             mock.patch.object(loop, "commit_bookkeeping"):
+            return loop.judge_close(
+                wu, feature_dir, feature_dir,
+                runner=lambda prompt, timeout=None: ("raw", {}),
+            )
+
+    def test_it_names_the_file_the_findings_were_written_to(self):
+        payload = self._payload_for([_Finding("T11#3", "### T11#3\n\nThe thing.")])
+
+        self.assertTrue(payload["lowered"])
+        self.assertIn("FOLLOW-UPS.md", payload.get("findings_path", ""))
+
+    def test_it_names_the_criteria(self):
+        payload = self._payload_for([
+            _Finding("T11#3", "### T11#3\n\nOne."),
+            _Finding("T06#2", "### T06#2\n\nTwo."),
+        ])
+
+        self.assertEqual(["T11#3", "T06#2"], payload.get("finding_criteria"))
+        self.assertEqual(2, payload["findings"])
+
+    def test_the_reason_is_no_longer_null_when_something_was_found(self):
+        payload = self._payload_for([_Finding("T11#3", "### T11#3\n\nThe thing.")])
+
+        self.assertIsNotNone(
+            payload["reason"],
+            "`findings: 1` with `reason: null` is what sent a reader looking "
+            "in three places that do not hold the text (#3406)",
+        )
+        self.assertIn("FOLLOW-UPS.md", payload["reason"])
+        self.assertIn("T11#3", payload["reason"])
+
+    def test_the_finding_text_is_not_copied_into_the_event(self):
+        # One verbatim record, not two that can disagree.
+        payload = self._payload_for([
+            _Finding("T11#3", "### T11#3\n\nA sentence only in the file.")])
+
+        self.assertNotIn("A sentence only in the file", repr(payload))
+
+
+class ThePathsThatFoundNothingAreUnchanged(unittest.TestCase):
+
+    def test_a_disabled_judge_still_explains_itself(self):
+        tmp = TemporaryDirectory()
+        self.addCleanup(tmp.cleanup)
+        feature_dir = Path(tmp.name)
+        (feature_dir / "PLAN.md").write_text(
+            "---\nfeature_id: FEAT-2026-9999\njudge_disabled: true\n---\n")
+        wu_file = feature_dir / "WU-90-close.md"
+        wu_file.write_text("---\nid: X/G1-CLOSE\nverdict: met\n---\n")
+        wu = SimpleNamespace(file=wu_file, wu_id="X/G1-CLOSE", verdict="met")
+
+        with mock.patch.object(loop, "_gate_identity",
+                               return_value=(1, feature_dir / "GATE-01.md")):
+            payload = loop.judge_close(wu, feature_dir, feature_dir)
+
+        self.assertFalse(payload["lowered"])
+        self.assertEqual(0, payload["findings"])
+        self.assertIsNotNone(payload["reason"])
+        self.assertNotIn("findings_path", payload)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    unittest.main()