specfuse-loop 0.9.1__tar.gz → 0.9.2__tar.gz

{specfuse_loop-0.9.1/specfuse_loop.egg-info → specfuse_loop-0.9.2}/PKG-INFO

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

{specfuse_loop-0.9.1 → specfuse_loop-0.9.2}/pyproject.toml

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

specfuse_loop-0.9.2/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.9.2

specfuse_loop-0.9.2/specfuse/loop/gate_commands.py

@@ -0,0 +1,94 @@
+#
+# Copyright 2026 Specfuse Contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""Read the gate sets out of `.specfuse/verification.yml` (#592).
+
+`verification.yml` is the source of truth for what gets verified. Anything
+that runs gates should derive its list from here rather than keeping a copy.
+
+`scripts/smoke-test.sh` used to carry a hand-maintained mirror under the
+comment "Keep in sync". It drifted by six gates, and two of them
+(`roadmap-link-gate`, `arm-sweep-gate`) shipped with features that week and
+were never once executed by CI. A declared-but-unrun gate is worse than an
+absent one, because the declaration reads as coverage.
+
+Deliberately not a YAML dependency: `_miniyaml` already parses this project's
+files, and adding a third-party parser to a path CI depends on would trade one
+drift risk for an install risk.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_SET_RE = re.compile(r"^([a-z_][a-z0-9_]*):\s*$", re.M)
+_NAME_RE = re.compile(r"^  - name:\s*(\S+)\s*$", re.M)
+_COMMAND_RE = re.compile(r'^\s+command:\s*"(.*?)"\s*$', re.M | re.S)
+
+
+def _set_block(text: str, set_name: str) -> str:
+    """Return the raw text of one top-level gate set, without its siblings."""
+    starts = [(m.group(1), m.start()) for m in _SET_RE.finditer(text)]
+    for i, (name, pos) in enumerate(starts):
+        if name != set_name:
+            continue
+        end = starts[i + 1][1] if i + 1 < len(starts) else len(text)
+        return text[pos:end]
+    return ""
+
+
+def iter_code_gates(
+    verification_yml: "Path | str", set_name: str = "code"
+) -> list[tuple[str, str]]:
+    """Yield `(name, command)` for every gate in *set_name*, in declared order.
+
+    Order is preserved because gate order is a real signal: the cheap,
+    fast-failing gates are declared first so a broken build reports in seconds
+    rather than after the full suite.
+    """
+    text = Path(verification_yml).read_text(encoding="utf-8")
+    block = _set_block(text, set_name)
+    if not block:
+        return []
+
+    gates: list[tuple[str, str]] = []
+    entries = re.split(r"^  - name:\s*", block, flags=re.M)[1:]
+    for entry in entries:
+        name = entry.split("\n", 1)[0].strip()
+        m = _COMMAND_RE.search(entry)
+        command = m.group(1).strip() if m else ""
+        gates.append((name, command))
+    return gates
+
+
+def code_gate_names(
+    verification_yml: "Path | str", set_name: str = "code"
+) -> list[str]:
+    """Names only, for parity checks."""
+    text = Path(verification_yml).read_text(encoding="utf-8")
+    return _NAME_RE.findall(_set_block(text, set_name))
+
+
+def main() -> int:
+    """Print `name<TAB>command` per gate, for shell consumption.
+
+    Used by `scripts/smoke-test.sh`, which substitutes its own interpreter for
+    a leading `python3`: the declared commands name `python3` because that is
+    what a target project's driver invokes, while the smoke test must use the
+    virtualenv interpreter that actually has the dependencies installed.
+    """
+    import argparse
+
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("verification_yml")
+    ap.add_argument("--set", default="code", dest="set_name")
+    args = ap.parse_args()
+    for name, command in iter_code_gates(args.verification_yml, args.set_name):
+        print(f"{name}\t{command}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{specfuse_loop-0.9.1 → specfuse_loop-0.9.2}/specfuse/loop/lint_plan.py

@@ -240,6 +240,15 @@ def read_frontmatter(path: Path) -> tuple[dict, str]:
     j = 1
     while j < len(lines) and not FM.match(lines[j]):
         j += 1
+    if j >= len(lines):
+        # See loop.read_frontmatter: an opening `---` with no closing one made
+        # the scan run off the end and parse the document as frontmatter,
+        # reporting the failure against an arbitrary body line (#306).
+        raise _miniyaml.MiniYAMLError(
+            f"{path}: frontmatter block opened with `---` on line 1 but is "
+            f"never closed — add a `---` line to end it. Every line after it "
+            f"was read as frontmatter, so no check could evaluate this file."
+        )
     return _miniyaml.parse("\n".join(lines[1:j])) or {}, "\n".join(lines[j + 1:])
 
 
@@ -659,6 +668,60 @@ def _match_dnt_boundary(
     return None
 
 
+def check_produces_shape(feature_dir: Path, gates: list) -> list[str]:
+    """ERROR when a WU's `produces:` entry is a directory rather than a file
+    or glob.
+
+    Same family as `check_produces_boundary` below, and the same argument: the
+    driver refuses this outright, but only after a full `claude -p` session.
+    Since the agent cannot edit its own frontmatter, every retry is
+    byte-identical -- a real feature paid $6.42 and 20.6 minutes across three
+    of them before `spinning_detected` fired, while `specfuse-lint` reported
+    `OK - structurally valid` throughout (#593).
+
+    Every input is static, so this belongs in the pre-dispatch checklist. The
+    message is rendered by `loop.produces_shape_error`, the same function the
+    driver's guards call, so all three surfaces read identically rather than
+    drifting into three descriptions of one rule.
+
+    Applies to every WU with a `produces:` entry regardless of status: a `done`
+    WU with a directory entry is a folder authored against the pre-0.9.0
+    contract, and reporting it is how a migrating project finds them all at
+    once instead of one dispatch at a time.
+    """
+    from .loop import produces_shape_error
+
+    found: list[str] = []
+    for gate in gates:
+        for entry in gate.get("work_units") or []:
+            wid, wfile = entry.get("id"), entry.get("file")
+            if not wid or not wfile:
+                continue
+            wpath = feature_dir / wfile
+            if not wpath.exists():
+                continue
+            wfm, _ = read_frontmatter(wpath)
+            produces_raw = wfm.get("produces")
+            if not produces_raw:
+                continue
+            raw_entries = (
+                produces_raw if isinstance(produces_raw, list) else [produces_raw]
+            )
+            for p in raw_entries:
+                p_s = str(p).strip()
+                if not p_s:
+                    continue
+                err = produces_shape_error(p_s)
+                if err:
+                    found.append(
+                        f"ERROR: {wfile}: {wid} {err}. assert_declared_"
+                        f"deliverables refuses this after a full dispatch "
+                        f"attempt, and a retry cannot help — the agent cannot "
+                        f"edit its own frontmatter. See #593."
+                    )
+    return found
+
+
 def check_produces_boundary(feature_dir: Path, gates: list) -> list[str]:
     """ERROR when a WU's own `produces:` path (or `produces_driver_helper`
     surface) falls inside its own Do-not-touch section's paths.
@@ -893,6 +956,21 @@ def check_planning_sections(
 
 
 def lint(feature_dir: Path) -> list[str]:
+    """Lint a feature folder, converting an unparseable file into a finding.
+
+    A malformed WU used to abort the whole run with a traceback, which made
+    the folder unevaluable by *every* check rather than one (#306). The lint's
+    job is to report what is wrong with a folder; a file it cannot parse is
+    the most basic thing that can be wrong with one, so it is a finding like
+    any other. Callers still get a non-empty error list and a non-zero exit.
+    """
+    try:
+        return _lint_impl(feature_dir)
+    except _miniyaml.MiniYAMLError as exc:
+        return [f"ERROR: unparseable frontmatter — {exc}"]
+
+
+def _lint_impl(feature_dir: Path) -> list[str]:
     errs: list[str] = []
     plan = feature_dir / "PLAN.md"
     if not plan.exists():
@@ -1212,6 +1290,7 @@ def lint(feature_dir: Path) -> list[str]:
     check_closing_guard_literals(feature_dir, gates)
     check_autoclose_debt_prediction(feature_dir, gates)
     check_produces_satisfiability(feature_dir, gates)
+    errs.extend(check_produces_shape(feature_dir, gates))
     errs.extend(check_produces_boundary(feature_dir, gates))
     errs.extend(check_done_feature_gates(feature_dir, fm))
 

{specfuse_loop-0.9.1 → specfuse_loop-0.9.2}/specfuse/loop/loop.py

@@ -105,7 +105,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.9.1"
+DRIVER_VERSION = "0.9.2"
 # 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
@@ -245,6 +245,17 @@ def read_frontmatter(path: Path) -> tuple[dict, str]:
     j = 1
     while j < len(lines) and not FM.match(lines[j]):
         j += 1
+    if j >= len(lines):
+        # Unterminated block: an opening `---` with no closing one. Without
+        # this check the scan runs off the end, the whole document is parsed
+        # as frontmatter, and the failure is reported against whatever body
+        # line happens to be first — which sent #306 chasing an HTML comment
+        # that was never the problem. Name the actual defect instead.
+        raise _miniyaml.MiniYAMLError(
+            f"{path}: frontmatter block opened with `---` on line 1 but is "
+            f"never closed — add a `---` line to end it. Every line after it "
+            f"was read as frontmatter, so no check could evaluate this file."
+        )
     try:
         fm = _miniyaml.parse("\n".join(lines[1:j])) or {}
     except _miniyaml.MiniYAMLError as exc:
@@ -4800,6 +4811,52 @@ def assert_implementation_touched_files(
     )
 
 
+def produces_shape_error(path: str) -> "str | None":
+    """Return why *path* is an invalid ``produces:`` entry, or None if it is fine.
+
+    Shape only -- never presence. A path that does not exist yet is perfectly
+    valid at draft time; whether it was actually produced is the dispatch
+    gate's question, asked after the session.
+
+    Split out of ``assert_declared_deliverables`` so the one fact that needs no
+    session output can be checked by every surface that has the frontmatter:
+    ``lint_plan`` at draft/arm/conformance time, and the driver before it
+    spends a token (#593). A real feature paid $6.42 across three byte-identical
+    refusals for a ``Path.is_dir()`` call, with ``specfuse-lint`` reporting
+    ``OK - structurally valid`` the whole time.
+
+    The three surfaces must read identically, so all render this one string.
+    """
+    if path.endswith("/") or Path(path).is_dir():
+        return (
+            f"declared deliverable is a directory: {path} — directories "
+            "are not valid produces: entries under the unified "
+            "literal/glob contract (a directory always passed presence "
+            "while failing assert_produces_in_diff's diff match); declare "
+            "the specific file(s) or a glob instead"
+        )
+    return None
+
+
+def assert_produces_shape(wu: WorkUnit) -> tuple[bool, str]:
+    """Pre-dispatch half of ``assert_declared_deliverables`` (#593).
+
+    Every input is static: the WU's own frontmatter and the filesystem. None
+    of it depends on what a session did, so refusing here converts a $2.46
+    attempt into a $0.00 refusal -- the lever ``planning-discipline.md`` §5
+    already names, where ``assert_verdict_well_formed`` fired 10 times for
+    nothing because it is checked before the agent spends anything.
+
+    The agent cannot edit its own frontmatter, so a WU that fails this cannot
+    be fixed by retrying it; escalating immediately is the only honest move.
+    """
+    for raw in wu.produces or []:
+        err = produces_shape_error(str(raw))
+        if err:
+            return False, err
+    return True, ""
+
+
 def assert_declared_deliverables(wu: WorkUnit) -> tuple[bool, str]:
     """Deliverable-presence gate (FEAT-2026-0022/T02), unified with
     ``assert_produces_in_diff``'s literal/glob contract (FEAT-2026-0055/T03).
@@ -4831,14 +4888,11 @@ def assert_declared_deliverables(wu: WorkUnit) -> tuple[bool, str]:
     for raw in wu.produces:
         path = str(raw)
         p = Path(path)
-        if path.endswith("/") or p.is_dir():
-            return False, (
-                f"declared deliverable is a directory: {path} — directories "
-                "are not valid produces: entries under the unified "
-                "literal/glob contract (a directory always passed presence "
-                "while failing assert_produces_in_diff's diff match); declare "
-                "the specific file(s) or a glob instead"
-            )
+        # Shape refusal is shared with the pre-dispatch guard and lint_plan so
+        # all three surfaces render one message (#593).
+        shape_err = produces_shape_error(path)
+        if shape_err:
+            return False, shape_err
         if any(ch in path for ch in "*?["):
             matches = [
                 m for m in glob.glob(path)
@@ -5516,6 +5570,34 @@ def run(
                     blocked = True
                     continue
 
+                # produces: shape gate (#593). Same posture as the re-arm gate
+                # above: fires BEFORE any dispatch state change, so a WU the
+                # driver is guaranteed to refuse costs $0.00 instead of a full
+                # session. Every input is static frontmatter plus the
+                # filesystem, and the agent cannot edit its own frontmatter --
+                # so retrying is provably useless. A real feature paid $6.42
+                # across three byte-identical refusals before spinning fired.
+                shape_ok, shape_reason = assert_produces_shape(wu)
+                if not shape_ok:
+                    backend.set_wu(wu, "status", "blocked_human")
+                    flush_events(events_path, [build_event(
+                        "human_escalation", wu.wu_id, {
+                            "reason": "produces_shape_invalid",
+                            "blocked_reason": shape_reason,
+                            "attempts": 0,
+                            "failure_class": "guard_refusal",
+                            "failure_signature": "assert_produces_shape",
+                        })])
+                    commit_bookkeeping(
+                        [wu.file, events_path],
+                        f"chore(loop): {wu.wu_id} blocked "
+                        f"(produces: shape invalid)"
+                        f"\n\nFeature: {wu.wu_id}",
+                    )
+                    print(f"   BLOCKED before dispatch (no cost) — {shape_reason}")
+                    blocked = True
+                    continue
+
                 head_before = git("rev-parse", "HEAD")
                 # Snapshot the operator's untracked files alongside head_before:
                 # squash_commit must not absorb WIP that pre-dates this dispatch

{specfuse_loop-0.9.1 → specfuse_loop-0.9.2/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.9.1 → specfuse_loop-0.9.2}/specfuse_loop.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ specfuse/loop/closing_requirements.py
 specfuse/loop/cost.py
 specfuse/loop/escalation.py
 specfuse/loop/events_stats.py
+specfuse/loop/gate_commands.py
 specfuse/loop/gate_eval.py
 specfuse/loop/gh_backend.py
 specfuse/loop/gh_features.py
@@ -129,6 +130,7 @@ tests/test_bookkeeping_no_verify.py
 tests/test_changelog_collection.py
 tests/test_changelog_release_wiring.py
 tests/test_changelog_schema.py
+tests/test_ci_runs_every_gate.py
 tests/test_claude_resolution.py
 tests/test_close_wu_self_reference.py
 tests/test_closing_deliverable_guard.py
@@ -258,6 +260,7 @@ tests/test_prepare_scaffold_sync.py
 tests/test_produces_field.py
 tests/test_produces_in_diff.py
 tests/test_produces_semantics_unified.py
+tests/test_produces_shape.py
 tests/test_provision_labels.py
 tests/test_queue_stalled_adapter.py
 tests/test_redaction_windows_home.py
@@ -288,6 +291,7 @@ tests/test_template_closing_shapes.py
 tests/test_terminal_flip_ownership.py
 tests/test_terminal_flips.py
 tests/test_timeout_kill_portable.py
+tests/test_unterminated_frontmatter.py
 tests/test_untracked_feature_folder.py
 tests/test_untracked_file_absorption.py
 tests/test_upgrade_integration.py

specfuse_loop-0.9.2/tests/test_ci_runs_every_gate.py

@@ -0,0 +1,74 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""#592 — CI must run every gate `verification.yml` declares.
+
+`scripts/smoke-test.sh` carried a hand-maintained copy of the `code` gate set
+under the comment "Keep in sync". It drifted by six: `roadmap-link-gate`,
+`arm-sweep-gate`, `monitoring-example-lint`, `sync-scaffold-symlinks-bats`,
+`init-sh-shim-bats`, and `hookspath-conflict-bats` were declared and never
+executed.
+
+A declared-but-unrun gate is worse than no gate: `verification.yml` is the
+source of truth for what gets verified, so an unrun entry reads as coverage.
+`sync_scaffold_symlinks.bats` sat red through two merges because of this, and
+its silence made a one-PR-old regression look environmental.
+
+`init-skills-bats` already carried the comment "Was silently red + un-run
+before #121" — the same problem, fixed once for one gate.
+"""
+
+from __future__ import annotations
+
+import unittest
+from pathlib import Path
+
+from specfuse.loop.gate_commands import code_gate_names, iter_code_gates
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SMOKE = REPO_ROOT / "scripts" / "smoke-test.sh"
+VERIFICATION = REPO_ROOT / ".specfuse" / "verification.yml"
+
+
+class TestGateParity(unittest.TestCase):
+    def test_declared_gates_were_found(self):
+        """Guard the guard: an empty parse would make every check vacuous."""
+        names = code_gate_names(VERIFICATION)
+        self.assertGreaterEqual(len(names), 10, names)
+        self.assertIn("tests", names)
+        self.assertIn("roadmap-link-gate", names)
+
+    def test_every_declared_gate_has_a_command(self):
+        for name, command in iter_code_gates(VERIFICATION):
+            with self.subTest(gate=name):
+                self.assertTrue(command.strip(), f"{name} declares no command")
+
+    def test_smoke_test_derives_gates_rather_than_listing_them(self):
+        """The drift is structural: any hand-copied list can fall behind.
+
+        Asserts the runner iterates the declared set instead of naming gates
+        one by one, so a gate added to verification.yml is run without anyone
+        remembering to touch the shell script.
+        """
+        sh = SMOKE.read_text()
+        self.assertIn("gate_commands", sh,
+                      "smoke-test.sh does not derive its gates from "
+                      "verification.yml; a seventh drift is a matter of time")
+
+    def test_no_declared_gate_is_hardcoded_out_of_the_run(self):
+        """Every declared gate must be reachable by the runner's iteration.
+
+        Catches the specific failure this issue is about: a gate present in
+        verification.yml that the CI runner never executes.
+        """
+        declared = set(code_gate_names(VERIFICATION))
+        emitted = {name for name, _ in iter_code_gates(VERIFICATION)}
+        self.assertEqual(
+            declared - emitted, set(),
+            "declared gates the runner would skip",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

specfuse_loop-0.9.2/tests/test_produces_shape.py

@@ -0,0 +1,160 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""#593 — a directory in `produces:` must be caught before a session runs.
+
+`assert_declared_deliverables` refuses a `produces:` entry that resolves to a
+directory. The verdict is right; the timing was not. It ran after a full
+`claude -p` session, three times, for a fact that is a `Path.is_dir()` call on
+static frontmatter: $6.42 and 20.6 minutes observed on a real feature, with
+`specfuse-lint` reporting `OK — structurally valid` throughout.
+
+Two surfaces, one contract:
+  - `lint_plan` must ERROR at draft/arm/conformance time, before the loop runs;
+  - the driver must refuse at dispatch, before a token is spent.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import tempfile
+import unittest
+from pathlib import Path
+
+from specfuse.loop.loop import produces_shape_error
+from tests._loop_loader import load_lint
+from tests.test_lint_boundary_consistency import _build_feature
+
+lint_plan = load_lint()
+
+
+class TestProducesShapeError(unittest.TestCase):
+    """The shared predicate both surfaces call — pure, no session input."""
+
+    def test_trailing_slash_is_refused_without_touching_the_filesystem(self):
+        err = produces_shape_error("src/main/java/dev/example/regression/")
+        self.assertIsNotNone(err)
+        self.assertIn("directory", err)
+
+    def test_existing_directory_is_refused(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            d = Path(tmp) / "pkg"
+            d.mkdir()
+            self.assertIsNotNone(produces_shape_error(str(d)))
+
+    def test_plain_file_path_is_accepted(self):
+        self.assertIsNone(produces_shape_error("specfuse/loop/loop.py"))
+
+    def test_glob_is_accepted(self):
+        self.assertIsNone(produces_shape_error("src/**/Regression*.java"))
+
+    def test_nonexistent_file_path_is_accepted(self):
+        """Shape only. Presence is the dispatch gate's job, not this one."""
+        self.assertIsNone(produces_shape_error("does/not/exist/yet.py"))
+
+
+class TestLintCatchesProducesShape(unittest.TestCase):
+    """Surface 1: the pre-dispatch checklist must not pass a doomed WU."""
+
+    def _lint(self, produces: str) -> list[str]:
+        with tempfile.TemporaryDirectory() as tmp:
+            feat = _build_feature(
+                Path(tmp),
+                [{
+                    "id": "FEAT-2026-0099/T01", "file": "WU-01.md",
+                    "type": "implementation", "status": "pending",
+                    "do_not_touch": "- nothing relevant.",
+                    "produces": [produces],
+                }],
+            )
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                errs = lint_plan.lint(feat)
+            return [str(e) for e in errs] + buf.getvalue().splitlines()
+
+    def test_directory_produces_is_an_error_finding(self):
+        found = [f for f in self._lint("src/regression/") if "directory" in f]
+        self.assertTrue(
+            found,
+            "lint passed a produces: entry the driver is guaranteed to refuse "
+            "- that is the $6.42 in #593",
+        )
+        self.assertTrue(
+            any(f.startswith("ERROR") for f in found),
+            f"directory produces: must be ERROR, not WARN: {found}",
+        )
+
+    def test_the_error_names_the_guard_it_preempts(self):
+        """Earlier-enforcer-names-the-later-one, per FEAT-2026-0070."""
+        found = [f for f in self._lint("src/regression/") if "directory" in f]
+        self.assertTrue(any("assert_declared_deliverables" in f for f in found))
+
+    def test_file_produces_is_not_flagged(self):
+        self.assertEqual(
+            [f for f in self._lint("src/Regression.java") if "directory" in f], [],
+        )
+
+    def test_glob_produces_is_not_flagged(self):
+        self.assertEqual(
+            [f for f in self._lint("src/**/*.java") if "directory" in f], [],
+        )
+
+
+
+class TestDispatchRefusesBeforeSpending(unittest.TestCase):
+    """Surface 2: the driver must refuse without opening a session."""
+
+    def test_shape_gate_is_wired_before_the_attempt_loop(self):
+        """The guard is worthless if it is defined but never reached.
+
+        Asserts the call site sits BEFORE `head_before = git("rev-parse",
+        "HEAD")`, which is where dispatch state starts changing. A guard
+        placed after that point would still cost the session it exists to
+        prevent.
+        """
+        src = (
+            Path(__file__).resolve().parents[1]
+            / "specfuse" / "loop" / "loop.py"
+        ).read_text()
+        call = src.index("shape_ok, shape_reason = assert_produces_shape(wu)")
+        head = src.index('head_before = git("rev-parse", "HEAD")')
+        attempt_loop = src.index("for attempt in range(1, MAX_ATTEMPTS + 1):")
+        self.assertLess(call, head, "shape gate runs after dispatch begins")
+        self.assertLess(call, attempt_loop, "shape gate runs inside the attempt loop")
+
+    def test_refusal_escalates_immediately_rather_than_retrying(self):
+        """A retry cannot help: the agent cannot edit its own frontmatter."""
+        src = (
+            Path(__file__).resolve().parents[1]
+            / "specfuse" / "loop" / "loop.py"
+        ).read_text()
+        block = src[src.index("shape_ok, shape_reason = assert_produces_shape(wu)"):][:1200]
+        self.assertIn('backend.set_wu(wu, "status", "blocked_human")', block)
+        self.assertIn("produces_shape_invalid", block)
+
+    def test_refusal_carries_a_failure_class_so_it_clusters(self):
+        """#593's smaller finding: guard refusals were invisible to
+        learnings-suggest because failure_class/failure_signature were null."""
+        src = (
+            Path(__file__).resolve().parents[1]
+            / "specfuse" / "loop" / "loop.py"
+        ).read_text()
+        block = src[src.index("shape_ok, shape_reason = assert_produces_shape(wu)"):][:1200]
+        self.assertIn('"failure_class": "guard_refusal"', block)
+        self.assertIn('"failure_signature": "assert_produces_shape"', block)
+
+    def test_shape_guard_and_dispatch_guard_render_one_message(self):
+        """Three surfaces, one wording -- they must not drift apart."""
+        from specfuse.loop.loop import WorkUnit, assert_produces_shape
+        wu = WorkUnit.__new__(WorkUnit)
+        object.__setattr__(wu, "produces", ["src/regression/"]) if hasattr(
+            WorkUnit, "__slots__") else setattr(wu, "produces", ["src/regression/"])
+        ok, reason = assert_produces_shape(wu)
+        self.assertFalse(ok)
+        self.assertEqual(reason, produces_shape_error("src/regression/"))
+
+
+if __name__ == "__main__":
+    unittest.main()