specfuse-loop 0.3.17__tar.gz → 0.3.18__tar.gz

{specfuse_loop-0.3.17/specfuse_loop.egg-info → specfuse_loop-0.3.18}/PKG-INFO

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

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18}/pyproject.toml

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

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18}/specfuse/loop/_miniyaml.py

@@ -53,7 +53,9 @@ on a missing gate set — silent misparses are worse than crashes.
         fields that the driver writes to WU frontmatter.
       - **booleans** — exact lowercase `true` / `false` only. `True`, `yes`,
         `on`, etc. are errors.
-      - **empty value** — a key followed by `:` with nothing after is `None`.
+      - **empty value / explicit null** — a key followed by `:` with nothing
+        after is `None`; so are the explicit YAML null spellings `null`,
+        `Null`, `NULL`, and `~` (matching yaml.safe_load).
   * **Inline (flow) lists** — `[]`, `[a]`, `[a, b]`. Items are scalars only;
     nested brackets are an error. Real usage is correlation-ID lists.
   * **Comments** — `#` starting a line (after optional whitespace), or
@@ -73,8 +75,9 @@ on a missing gate set — silent misparses are worse than crashes.
   * Mixed / inconsistent indentation.
   * Nested brackets inside a flow list.
   * Escape sequences other than `\\` and `\"` in double-quoted strings.
-  * Boolean spellings other than exact lowercase `true` / `false`.
-  * Explicit null markers (`null`, `Null`, `NULL`, `~`).
+  * Boolean spellings other than exact lowercase `true` / `false` (the YAML
+    1.1 "Norway problem" — `yes`/`no`/`on`/`off`/`True` — stays rejected on
+    purpose; only `null` is accepted as a non-lowercase-keyword idiom).
   * Integers with sign, leading zeros, floats, hex, or underscores.
 
 A file using any of those raises `MiniYAMLError` with a line number and a
@@ -108,7 +111,7 @@ _FORBIDDEN_BOOLS = {
     "yes", "Yes", "YES", "no", "No", "NO",
     "on", "On", "ON", "off", "Off", "OFF",
 }
-_FORBIDDEN_NULLS = {"null", "Null", "NULL", "~"}
+_NULL_SCALARS = {"null", "Null", "NULL", "~"}
 
 
 # --------------------------------------------------------------------------- #
@@ -363,9 +366,13 @@ def _parse_scalar(text: str, lineno: int) -> Any:
         # forgiving result-block parse path on real agent output.
         raise MiniYAMLError(
             f"line {lineno}: flow mappings unsupported — use a block mapping")
-    if text in _FORBIDDEN_NULLS:
-        raise MiniYAMLError(
-            f"line {lineno}: explicit null marker unsupported — leave value empty")
+    if text in _NULL_SCALARS:
+        # Explicit YAML null spellings map to None, same as an empty value.
+        # Accepting them (rather than failing loud) removes a foot-gun for
+        # hand-authored frontmatter and for anything generated by a real YAML
+        # library, which emits `null` for None — and matches yaml.safe_load,
+        # tightening the equivalence guarantee (#177).
+        return None
     if text in _FORBIDDEN_BOOLS:
         raise MiniYAMLError(
             f"line {lineno}: only lowercase `true`/`false` accepted as "

specfuse_loop-0.3.18/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.18

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18}/specfuse/loop/data/verification.yml.example

@@ -28,6 +28,15 @@
 #
 # cost_tracking: true
 
+# PER-GATE `wu_must_reference: true` (optional, default false). Flag a gate
+# whose fix is MECHANICAL over a work unit's own output — a formatter, an
+# auto-fixable linter (`spotless:check`, `black --check`, `gofmt -l`,
+# `prettier --check`). The plan linter (specfuse-lint) then WARNs when an
+# implementation WU's Verification section names none of that gate's command —
+# catching, at authoring time and zero model cost, the case where a WU forgets
+# a mechanical gate and the driver spins retries on the identical failure until
+# the attempt budget is exhausted. Leave it off for project-global gates
+# (leak-scan, hygiene checks) that an individual WU has no reason to name.
 code:
   - name: tests
     command: "pytest -q"
@@ -37,6 +46,9 @@ code:
     command: "python3 -W error -c 'pass'"    # replace with your build's -Werror equivalent
   - name: lint
     command: "ruff check ."
+  - name: format
+    command: "black --check ."               # deterministic formatter: fix with `black .`
+    wu_must_reference: true                   # WUs must name it (see note above)
   - name: security
     command: "bandit -r src -ll"             # or your OWASP-aligned scanner
 

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18}/specfuse/loop/lint_plan.py

@@ -138,6 +138,69 @@ def _slice_section(body: str, section_name: str) -> str:
     return after[:em.start()] if em else after
 
 
+# Interpreters / super-generic words that don't distinguish one gate command
+# from another — excluded from a command's signature tokens (#176).
+_GATE_TOKEN_STOP = {
+    "python", "python3", "bash", "sh", "run", "exec", "discover",
+    "report", "source", "true", "false",
+}
+_GATE_TOKEN_RE = re.compile(r"[A-Za-z][A-Za-z0-9_.:+-]{2,}")
+# Verification prose that delegates to the whole gate set — treat as
+# referencing every gate so a legitimate "all gates pass" phrasing is not
+# flagged.
+_UMBRELLA_GATES_RE = re.compile(r"(?i)\b(all|every|entire|full|the)\b[^.\n]{0,24}\bgate")
+
+
+def _must_reference_gate_signatures(feature_dir: Path) -> list[tuple[str, set[str]]]:
+    """Return [(gate_name, signature_tokens)] for OPT-IN must-reference gates (#176).
+
+    Reads ``<project>/.specfuse/verification.yml`` (``feature_dir`` is
+    ``.../.specfuse/features/<name>``) and includes only `code` gates that set
+    ``wu_must_reference: true``. This is deliberately opt-in: warning on every
+    declared gate is noise on real multi-gate projects (leak-scan, hygiene
+    bats, etc. that an individual WU has no business naming). A project flags
+    the gates whose fix is mechanical over a WU's own output — formatters,
+    auto-fixable linters — the class #175 shows can burn the whole attempt
+    budget when a WU forgets them. Empty list (the check no-ops) when the file
+    is absent, unparseable, or no gate opts in. Each gate's token set is the
+    distinctive words of its command plus the gate name, lowercased.
+    """
+    vpath = feature_dir.parent.parent / "verification.yml"
+    if not vpath.is_file():
+        return []
+    try:
+        cfg = _miniyaml.parse(vpath.read_text()) or {}
+    except _miniyaml.MiniYAMLError:
+        return []
+    out: list[tuple[str, set[str]]] = []
+    for gate in cfg.get("code") or []:
+        if not isinstance(gate, dict) or gate.get("wu_must_reference") is not True:
+            continue
+        name = str(gate.get("name") or "").strip()
+        command = str(gate.get("command") or "")
+        tokens = {t.lower() for t in _GATE_TOKEN_RE.findall(command)
+                  if t.lower() not in _GATE_TOKEN_STOP}
+        if name:
+            tokens.add(name.lower())
+        if tokens:
+            out.append((name or command[:40], tokens))
+    return out
+
+
+def _unreferenced_code_gates(
+    verification_text: str, signatures: list[tuple[str, set[str]]],
+) -> list[str]:
+    """Names of code gates whose tokens *verification_text* references none of.
+
+    An umbrella "all gates" phrasing short-circuits to [] (author delegated).
+    """
+    if _UMBRELLA_GATES_RE.search(verification_text):
+        return []
+    low = verification_text.lower()
+    return [name for name, tokens in signatures
+            if not any(tok in low for tok in tokens)]
+
+
 def detect_oracle_verbs(ac_section_text: str) -> list[str]:
     """Return matched oracle-verb strings found in the AC section text."""
     found = []
@@ -249,6 +312,11 @@ def lint(feature_dir: Path) -> list[str]:
     if missing:
         errs.append(f"PLAN.md frontmatter missing keys: {sorted(missing)}")
 
+    # Opt-in must-reference gate signatures, loaded once for the
+    # Verification-reference WARN below (#176). Empty unless the project flags
+    # gates with `wu_must_reference: true`.
+    must_ref_gate_sigs = _must_reference_gate_signatures(feature_dir)
+
     if "base" in fm:
         base_val = fm["base"]
         feature_id_val = fm.get("feature_id", feature_dir.name)
@@ -400,6 +468,25 @@ def lint(feature_dir: Path) -> list[str]:
                         f"driver. See authoring-work-units §9 + FEAT-2026-0017."
                     )
 
+            # Verification ↔ must-reference gate WARN (#176). For gates a
+            # project has flagged `wu_must_reference: true` — those whose fix is
+            # mechanical over a WU's own output (formatters, auto-fixable
+            # linters) — the driver enforces them regardless of what a WU's
+            # Verification names. A session not told to run one writes code that
+            # fails it and, per #175, can burn the whole attempt budget on the
+            # mechanical failure. Flag at lint time, at zero model cost. Opt-in,
+            # so no noise on projects that don't flag any gate.
+            if wu_type_val == "implementation" and must_ref_gate_sigs:
+                verif_text = _slice_section(wbody, "Verification")
+                unref = _unreferenced_code_gates(verif_text, must_ref_gate_sigs)
+                if unref:
+                    print(
+                        f"WARN: {wfile}: Verification references none of the "
+                        f"must-reference gate(s): {', '.join(unref)}. The driver "
+                        f"runs them regardless; name each so the session knows to "
+                        f"satisfy it before finishing (#176)."
+                    )
+
             # Deliverable-presence declaration WARN (FEAT-2026-0022/T01).
             # Advisory: an implementation WU should declare the file path(s) it
             # is contracted to yield via `produces:`, which T02's presence gate

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18}/specfuse/loop/loop.py

@@ -63,7 +63,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.3.17"
+DRIVER_VERSION = "0.3.18"
 # 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
@@ -190,14 +190,27 @@ FM = re.compile(r"^---\s*$")
 
 
 def read_frontmatter(path: Path) -> tuple[dict, str]:
-    """Return (frontmatter_dict, body_text)."""
+    """Return (frontmatter_dict, body_text).
+
+    A parse failure is re-raised with the file path attached and the line
+    clarified as frontmatter-relative (add 1 for the file line, since the
+    opening `---` is line 1). Without this a `_miniyaml.MiniYAMLError` carries
+    only a block-relative line number, so locating the offending file across
+    many feature folders meant grepping by hand (#177).
+    """
     lines = path.read_text().splitlines()
     if not lines or not FM.match(lines[0]):
         return {}, path.read_text()
     j = 1
     while j < len(lines) and not FM.match(lines[j]):
         j += 1
-    fm = _miniyaml.parse("\n".join(lines[1:j])) or {}
+    try:
+        fm = _miniyaml.parse("\n".join(lines[1:j])) or {}
+    except _miniyaml.MiniYAMLError as exc:
+        raise _miniyaml.MiniYAMLError(
+            f"{path}: {exc} (line is relative to the frontmatter block; "
+            f"add 1 for the file line)"
+        ) from exc
     body = "\n".join(lines[j + 1 :])
     return fm, body
 
@@ -261,7 +274,16 @@ def find_feature(arg: str | None) -> Path:
     for d in sorted(FEATURES_DIR.glob("*/")):
         plan = d / "PLAN.md"
         if plan.exists():
-            fm, _ = read_frontmatter(plan)
+            try:
+                fm, _ = read_frontmatter(plan)
+            except _miniyaml.MiniYAMLError as exc:
+                # One feature's malformed frontmatter must not block dispatch of
+                # every OTHER feature. Feature lookup is the earliest and least
+                # relevant failure point; skip the bad candidate with a warning
+                # rather than aborting the whole scan (#177).
+                print(f"warning: skipping {d.name} — unparseable PLAN.md "
+                      f"frontmatter: {exc}", file=sys.stderr)
+                continue
             if fm.get("status") == "active":
                 actives.append(d)
             elif fm.get("status") == "done":
@@ -655,7 +677,56 @@ def extract_failure_excerpt(stdout: str, max_chars: int = 500) -> str:
     encoded = text.encode("utf-8")
     if len(encoded) <= max_chars:
         return text
-    return encoded[-max_chars:].decode("utf-8", errors="ignore")
+    # Head+tail, not tail-only (#175): build-tool output puts the actionable
+    # part (the list of offending files) up top and boilerplate (help URLs,
+    # stack-trace hints) at the bottom. A tail-only slice reliably keeps the
+    # noise; splitting the budget preserves both ends.
+    marker = "\n...\n"
+    budget = max_chars - len(marker.encode("utf-8"))
+    if budget <= 0:
+        return encoded[-max_chars:].decode("utf-8", errors="ignore")
+    head_bytes = budget // 2
+    tail_bytes = budget - head_bytes
+    head = encoded[:head_bytes].decode("utf-8", errors="ignore")
+    tail = encoded[-tail_bytes:].decode("utf-8", errors="ignore")
+    return head + marker + tail
+
+
+# Forward-looking retry directives keyed by failure_class (#175 fix 1). The
+# gate output replayed into a retry describes files the per-attempt reset
+# already discarded, and reads as stale advice about a prior attempt. These
+# reframe it as a standing requirement for the fresh attempt and name the
+# mechanical remedy per class — no per-tool knowledge.
+_RETRY_CLASS_HINT: dict[str, str] = {
+    "lint": "This was a lint/format gate — its fix is mechanical: run the "
+            "formatter / linter's fix command over your changes and re-run the "
+            "gate before declaring done, rather than only rewriting the code.",
+    "tests": "Run the failing tests and make them pass before declaring done.",
+    "coverage": "Add tests covering the new or changed code to clear the "
+                "coverage gate before declaring done.",
+    "security": "Resolve the flagged security findings (or add a narrowly "
+                "scoped, justified suppression) before declaring done.",
+}
+
+
+def synthesize_retry_directive(failure_class: "str | None") -> str:
+    """Return a forward-looking retry instruction for *failure_class* (#175).
+
+    Prepended to the failure note fed into the next attempt. The note itself
+    is raw gate output about files the reset discarded; without this lead a
+    fresh session reads it as stale advice and reproduces the same omission
+    (e.g. never running the formatter), failing identically until attempts
+    exhaust. The lead reframes the output as a standing requirement and the
+    per-class hint names the remedy generically.
+    """
+    lead = ("The previous attempt's work was DISCARDED before this retry, so "
+            "the gate output below refers to files that no longer exist. Do "
+            "not read it as stale advice about a past attempt — treat it as a "
+            "standing requirement for THIS fresh attempt. ")
+    hint = _RETRY_CLASS_HINT.get(
+        failure_class or "",
+        "Satisfy every declared gate before declaring done.")
+    return lead + hint
 
 
 def emit_attempt_outcome(
@@ -4241,9 +4312,16 @@ def run(
                             + "```diff\n" + _diff + "\n```\n"
                         )
                     attempt_notes.append((attempt, _evidence))
-                    failure_note = payload
                     _fc, _fs = parse_gate_failure_signature(payload)
                     _ex = extract_failure_excerpt(payload)
+                    # Prepend a forward-looking directive so the retry reads the
+                    # gate output as a standing requirement, not stale advice
+                    # about the discarded attempt (#175 fix 1).
+                    failure_note = (
+                        synthesize_retry_directive(_fc)
+                        + "\n\n## Gate output from the discarded attempt\n\n"
+                        + payload
+                    )
                     wu_events.append(emit_attempt_outcome(
                         wu, attempt, "failed",
                         attempts_usage[-1],

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18}/specfuse_loop.egg-info/SOURCES.txt

@@ -102,6 +102,7 @@ tests/test_lint_plan_relative_import.py
 tests/test_lint_produces_driver_helper.py
 tests/test_lint_sections.py
 tests/test_lint_task_graph_yaml_selection.py
+tests/test_lint_verification_reference.py
 tests/test_loop_attempt_evidence.py
 tests/test_loop_auto_archive.py
 tests/test_loop_caveman_preamble.py

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18}/tests/test_attempt_outcome_emission.py

@@ -304,6 +304,49 @@ class TestExtractFailureExcerpt(unittest.TestCase):
             self.fail(f"UnicodeDecodeError raised: {e}")
         self.assertIsInstance(excerpt, str)
 
+    def test_keeps_head_and_tail_on_truncation(self):
+        # #175: build-tool output puts the offending-file list up top and
+        # boilerplate (help URLs, stack hints) at the bottom. A tail-only
+        # slice keeps the noise; head+tail must preserve both ends.
+        lines = ["Error: HEAD_MARKER offending file list here"]
+        lines += [f"Error: filler line {i} " + "x" * 40 for i in range(400)]
+        lines += ["Error: TAIL_MARKER re-run with -X for debug"]
+        excerpt = loop.extract_failure_excerpt("\n".join(lines), max_chars=500)
+        self.assertLessEqual(len(excerpt.encode("utf-8")), 500)
+        self.assertIn("HEAD_MARKER", excerpt)
+        self.assertIn("TAIL_MARKER", excerpt)
+
+
+class TestSynthesizeRetryDirective(unittest.TestCase):
+    """#175 fix 1: the retry note must carry a forward-looking lesson, not
+    just replay output about files the reset already discarded."""
+
+    def test_lint_directive_is_forward_looking(self):
+        d = loop.synthesize_retry_directive("lint")
+        self.assertIn("discard", d.lower())
+        # Names the mechanical remedy without per-tool knowledge.
+        self.assertIn("format", d.lower())
+        self.assertIn("before", d.lower())
+
+    def test_tests_directive_mentions_tests(self):
+        d = loop.synthesize_retry_directive("tests")
+        self.assertIn("test", d.lower())
+        self.assertIn("before", d.lower())
+
+    def test_coverage_and_security_have_specific_hints(self):
+        self.assertIn("coverage", loop.synthesize_retry_directive("coverage").lower())
+        self.assertIn(
+            "finding", loop.synthesize_retry_directive("security").lower())
+
+    def test_unknown_class_falls_back_to_generic_non_empty(self):
+        d = loop.synthesize_retry_directive("other")
+        self.assertTrue(d.strip())
+        self.assertIn("discard", d.lower())
+
+    def test_none_class_does_not_crash(self):
+        d = loop.synthesize_retry_directive(None)
+        self.assertTrue(d.strip())
+
 
 # --------------------------------------------------------------------------- #
 # TestCumulativeFoldOnRearm                                                    #

specfuse_loop-0.3.18/tests/test_lint_verification_reference.py

@@ -0,0 +1,177 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""#176: warn when an implementation WU's Verification omits a declared code gate.
+
+The driver enforces the full `code` gate set regardless of what a WU's
+Verification names, so the two can silently disagree — the authoring-side
+trigger of #175. This lint catches it before dispatch at zero model cost.
+"""
+
+from __future__ import annotations
+
+import io
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from pathlib import Path
+
+from tests._loop_loader import load_lint
+
+lint_plan = load_lint()
+
+# Only `format` opts in via wu_must_reference; tests/lint are NOT checked.
+_VERIFICATION = """\
+code:
+  - name: tests
+    command: "python3 -m unittest discover -s tests -v"
+  - name: lint
+    command: "ruff check specfuse tests"
+  - name: format
+    command: "./mvnw spotless:check"
+    wu_must_reference: true
+"""
+
+
+class TestMustReferenceGateSignatureHelpers(unittest.TestCase):
+
+    def _feature_with_verification(self, tmp: str, yml: str | None) -> Path:
+        root = Path(tmp)
+        fdir = root / ".specfuse" / "features" / "FEAT-2026-9401-x"
+        fdir.mkdir(parents=True)
+        if yml is not None:
+            (root / ".specfuse" / "verification.yml").write_text(yml)
+        return fdir
+
+    def test_only_flagged_gate_is_included(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fdir = self._feature_with_verification(tmp, _VERIFICATION)
+            sigs = dict(lint_plan._must_reference_gate_signatures(fdir))
+            # tests/lint are NOT flagged → excluded; only format opts in.
+            self.assertEqual(set(sigs), {"format"})
+            self.assertIn("spotless:check", sigs["format"])
+            self.assertIn("format", sigs["format"])  # gate name is a token
+
+    def test_no_flag_anywhere_returns_empty(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            plain = ("code:\n  - name: tests\n"
+                     "    command: \"pytest -q\"\n")
+            fdir = self._feature_with_verification(tmp, plain)
+            self.assertEqual(lint_plan._must_reference_gate_signatures(fdir), [])
+
+    def test_no_verification_file_returns_empty(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fdir = self._feature_with_verification(tmp, None)
+            self.assertEqual(lint_plan._must_reference_gate_signatures(fdir), [])
+
+    def test_unparseable_verification_returns_empty(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fdir = self._feature_with_verification(tmp, "code: {bad: flow}\n")
+            self.assertEqual(lint_plan._must_reference_gate_signatures(fdir), [])
+
+    def test_unreferenced_detects_omitted_gate(self):
+        sigs = [("tests", {"tests", "unittest"}),
+                ("format", {"format", "spotless:check"})]
+        # Names tests but not the formatter → only 'format' is unreferenced.
+        text = "Run the unittest suite; all tests pass."
+        self.assertEqual(lint_plan._unreferenced_code_gates(text, sigs),
+                         ["format"])
+
+    def test_umbrella_phrase_short_circuits(self):
+        sigs = [("format", {"format", "spotless:check"})]
+        for phrase in ("all declared gates pass", "every gate is green",
+                       "the full gate set runs clean"):
+            self.assertEqual(
+                lint_plan._unreferenced_code_gates(phrase, sigs), [],
+                f"{phrase!r} should short-circuit")
+
+    def test_all_referenced_is_empty(self):
+        sigs = [("tests", {"tests"}), ("format", {"spotless:check"})]
+        text = "tests pass; ran spotless:check clean."
+        self.assertEqual(lint_plan._unreferenced_code_gates(text, sigs), [])
+
+
+class TestVerificationReferenceLintWarn(unittest.TestCase):
+
+    def _make_feature(self, tmp: str, verification_body: str,
+                      yml: str | None = _VERIFICATION) -> Path:
+        root = Path(tmp)
+        fdir = root / ".specfuse" / "features" / "FEAT-2026-9401-x"
+        fdir.mkdir(parents=True)
+        if yml is not None:
+            (root / ".specfuse" / "verification.yml").write_text(yml)
+        (fdir / "PLAN.md").write_text(
+            "---\n"
+            "feature_id: FEAT-2026-9401\n"
+            "title: verification-reference lint\n"
+            "branch: feat/vref\n"
+            "roadmap_goal: Check the Verification-reference WARN.\n"
+            "status: active\n"
+            "---\n\n# Plan\n\n```yaml\n"
+            "gates:\n"
+            "  - gate: 1\n"
+            "    file: GATE-01.md\n"
+            "    work_units:\n"
+            "      - id: FEAT-2026-9401/T01\n"
+            "        file: WU-01-impl.md\n"
+            "        depends_on: []\n"
+            "      - id: FEAT-2026-9401/G1-CLOSE\n"
+            "        file: WU-90-close.md\n"
+            "        depends_on: [FEAT-2026-9401/T01]\n"
+            "```\n"
+        )
+        (fdir / "WU-01-impl.md").write_text(
+            "---\nid: FEAT-2026-9401/T01\ntype: implementation\n"
+            "status: done\nattempts: 1\nproduces: [src/x.py]\n---\n\n"
+            "# Title\n\n**Context.**\nAdd a file.\n\n"
+            "**Acceptance criteria.**\nThe code works.\n\n"
+            "**Do not touch.**\nNothing.\n\n"
+            f"**Verification.**\n{verification_body}\n\n"
+            "**Escalation triggers.**\nEmit blocked if wrong.\n"
+        )
+        (fdir / "WU-90-close.md").write_text(
+            "---\nid: FEAT-2026-9401/G1-CLOSE\ntype: close\n"
+            "status: done\nattempts: 1\n---\n\n# Close\n"
+        )
+        (fdir / "GATE-01.md").write_text("---\nstatus: open\n---\n\n# Gate 1\n")
+        return fdir
+
+    def _lint(self, fdir: Path) -> str:
+        buf = io.StringIO()
+        with redirect_stdout(buf):
+            lint_plan.lint(fdir)
+        return buf.getvalue()
+
+    def test_warns_when_formatter_gate_omitted(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fdir = self._make_feature(
+                tmp, "Run the unittest suite and ruff; all pass.")
+            out = self._lint(fdir)
+            self.assertIn("WARN", out)
+            # Only the omitted formatter gate is named; the referenced
+            # tests/lint gates are not listed as unreferenced.
+            listed = out.split("gate(s):", 1)[1].split("\n", 1)[0]
+            self.assertIn("format", listed)
+            self.assertNotIn("tests", listed)
+            self.assertNotIn("lint", listed)
+
+    def test_silent_when_all_gates_named(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fdir = self._make_feature(
+                tmp, "unittest suite passes; ruff clean; spotless:check clean.")
+            self.assertNotIn("references none", self._lint(fdir))
+
+    def test_silent_on_umbrella_phrase(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fdir = self._make_feature(tmp, "All declared code gates pass.")
+            self.assertNotIn("references none", self._lint(fdir))
+
+    def test_silent_when_no_verification_yml(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            fdir = self._make_feature(tmp, "anything at all", yml=None)
+            self.assertNotIn("references none", self._lint(fdir))
+
+
+if __name__ == "__main__":
+    unittest.main()

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18}/tests/test_loop_orchestration.py

@@ -320,6 +320,41 @@ class TestFindFeatureSelection(unittest.TestCase):
         result = loop.find_feature("FEAT-2026-9502-explicit")
         self.assertEqual(result, fdir)
 
+    def test_null_in_frontmatter_does_not_crash_lookup(self):
+        """#177 fix 3: an explicit null in frontmatter parses fine now."""
+        fdir = self._features_dir / "FEAT-2026-9502-nullkey"
+        fdir.mkdir(parents=True)
+        (fdir / "PLAN.md").write_text(
+            "---\nfeature_id: FEAT-2026-9502\nstatus: active\n"
+            "supersedes_gate_of: null\n---\n\n# Plan\n"
+        )
+        self.assertEqual(loop.find_feature(None), fdir)
+
+    def test_unparseable_candidate_is_skipped_not_fatal(self):
+        """#177 fix 2: a malformed PLAN.md in one feature must not block
+        dispatch of a different, valid active feature."""
+        bad = self._features_dir / "FEAT-2026-9502-bad"
+        bad.mkdir(parents=True)
+        # Single-quoted scalar is unsupported → MiniYAMLError on this file only.
+        (bad / "PLAN.md").write_text(
+            "---\nfeature_id: FEAT-2026-9502\nstatus: 'active'\n---\n\n# Plan\n"
+        )
+        good = self._write_plan("FEAT-2026-9502-good", "active")
+        # The bad one is skipped; the good active feature still resolves.
+        self.assertEqual(loop.find_feature(None), good)
+
+    def test_read_frontmatter_error_names_the_file(self):
+        """#177 fix 1: a parse error carries the file path, not just a
+        block-relative line number."""
+        bad = self._features_dir / "FEAT-2026-9502-badfm"
+        bad.mkdir(parents=True)
+        plan = bad / "PLAN.md"
+        plan.write_text("---\nstatus: 'active'\n---\n\n# Plan\n")
+        with self.assertRaises(loop._miniyaml.MiniYAMLError) as ctx:
+            loop.read_frontmatter(plan)
+        self.assertIn("PLAN.md", str(ctx.exception))
+        self.assertIn(str(plan), str(ctx.exception))
+
     def test_deferred_feature_is_not_auto_selected(self):
         """Issue #106: a `deferred` foldered feature is non-dispatchable — the
         driver skips it exactly like a non-active feature (parked, resumable)."""

{specfuse_loop-0.3.17 → specfuse_loop-0.3.18}/tests/test_miniyaml_negative.py

@@ -98,13 +98,16 @@ class TestUnsupportedConstructsFailLoudly(unittest.TestCase):
     def test_top_level_indent_nonzero_rejected(self):
         self._expect_error("  foo: 1\n", "indent 0")
 
-    # --- explicit nulls / forbidden boolean spellings ---
-
-    def test_explicit_null_marker_rejected(self):
-        self._expect_error("foo: null\n", "explicit null marker")
-
-    def test_tilde_null_marker_rejected(self):
-        self._expect_error("foo: ~\n", "explicit null marker")
+    # --- explicit nulls now ACCEPTED (#177); forbidden boolean spellings ---
+
+    def test_explicit_null_spellings_accepted_as_none(self):
+        # #177: null/~/Null/NULL map to None, matching yaml.safe_load — the
+        # explicit-null rejection used to crash feature lookup with a
+        # traceback. Boolean spellings below stay rejected (Norway problem).
+        for spelling in ("null", "Null", "NULL", "~"):
+            self.assertEqual(
+                miniyaml.parse(f"foo: {spelling}\n"), {"foo": None},
+                f"{spelling!r} should parse to None")
 
     def test_titlecase_boolean_rejected(self):
         self._expect_error("foo: True\n", "lowercase", "true")

specfuse_loop-0.3.17/specfuse/loop/data/VERSION

@@ -1 +0,0 @@
-0.3.17