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

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

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

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

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

specfuse_loop-0.3.19/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.19

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

@@ -40,6 +40,14 @@ VALID_TYPES = {"implementation", "retrospective", "lessons", "docs", "plan-next"
                "close-intermediate"}
 VALID_STATUS = {"draft", "pending", "ready", "in_progress", "in_review", "done",
                 "blocked_human", "abandoned"}
+# Feature (PLAN.md) and gate status vocabularies the DRIVER branches on. Kept
+# here (duplicated from loop.py's status literals, like VALID_TYPES/VALID_STATUS
+# above) so the linter validates the same set the driver acts on — an
+# unrecognized status that passes lint and then behaves differently at dispatch
+# is the class #183 (deferred) and #185 exist to close. Keep in sync with
+# find_feature / the gate-status transitions in loop.py.
+VALID_FEATURE_STATUS = {"planned", "active", "deferred", "done", "abandoned"}
+VALID_GATE_STATUS = {"open", "awaiting_review", "passed"}
 CLOSING_SEQUENCE = ["retrospective", "lessons", "docs", "plan-next"]
 # New compact closing shapes (FEAT-2026-0015):
 #   non-terminal gate: close-intermediate → plan-next
@@ -312,6 +320,17 @@ def lint(feature_dir: Path) -> list[str]:
     if missing:
         errs.append(f"PLAN.md frontmatter missing keys: {sorted(missing)}")
 
+    # Feature status must be a value the driver recognizes (#185). An
+    # unrecognized status passes every other check and then behaves
+    # differently at dispatch — the shape #183 (deferred passed lint,
+    # dispatched anyway) exposed. Only validate when present; the missing-key
+    # check above already covers absence.
+    if "status" in fm and fm["status"] not in VALID_FEATURE_STATUS:
+        errs.append(
+            f"PLAN.md frontmatter status {fm['status']!r} is not a recognized "
+            f"feature status {sorted(VALID_FEATURE_STATUS)}"
+        )
+
     # 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`.
@@ -351,6 +370,12 @@ def lint(feature_dir: Path) -> list[str]:
             gate_path = feature_dir / gate_file_rel
             if gate_path.exists():
                 gfm, _ = read_frontmatter(gate_path)
+                # Gate status must be a value the driver recognizes (#185).
+                if "status" in gfm and gfm["status"] not in VALID_GATE_STATUS:
+                    errs.append(
+                        f"{gate_file_rel}: gate status {gfm['status']!r} is not "
+                        f"a recognized gate status {sorted(VALID_GATE_STATUS)}"
+                    )
                 if "cost_budget_usd" in gfm:
                     val = gfm["cost_budget_usd"]
                     if isinstance(val, bool) or not isinstance(val, (int, float)):

{specfuse_loop-0.3.18 → specfuse_loop-0.3.19}/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.18"
+DRIVER_VERSION = "0.3.19"
 # 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
@@ -266,11 +266,28 @@ def write_frontmatter_field(path: Path, key: str, value) -> None:
 def find_feature(arg: str | None) -> Path:
     if arg:
         d = FEATURES_DIR / arg if not arg.startswith(".") else Path(arg)
-        if not (d / "PLAN.md").exists():
+        plan = d / "PLAN.md"
+        if not plan.exists():
             sys.exit(f"No PLAN.md under {d}")
+        # A `deferred` feature is parked — non-dispatchable by contract (the
+        # gate-status skill documents it as "non-dispatchable but resumable;
+        # the loop does not auto-resume it"). Refuse an explicit --feature
+        # targeting one instead of dispatching it anyway (#183). Malformed
+        # frontmatter is left to fail later where the graph is parsed.
+        try:
+            _fm, _ = read_frontmatter(plan)
+        except _miniyaml.MiniYAMLError:
+            _fm = {}
+        if _fm.get("status") == "deferred":
+            sys.exit(
+                f"{d.name} is deferred (parked) — the loop does not dispatch "
+                f"deferred features. Flip its PLAN.md status back to `active` "
+                f"when the blocker clears, then re-run."
+            )
         return d
     actives = []
     done_pending_wrap = []
+    deferred = []
     for d in sorted(FEATURES_DIR.glob("*/")):
         plan = d / "PLAN.md"
         if plan.exists():
@@ -293,10 +310,23 @@ def find_feature(arg: str | None) -> Path:
                 # push + PR are pending.
                 if (d / "RETROSPECTIVE.md").is_file():
                     done_pending_wrap.append(d)
+            elif fm.get("status") == "deferred":
+                # Parked — non-dispatchable (#183). Never enters `actives`, so
+                # a bare invocation won't pick it up; surfaced below so a lone
+                # deferred feature reads as parked, not silently absent.
+                deferred.append(d)
     if len(actives) == 1:
         return actives[0]
     if not actives:
         msg = "No active feature. Set a feature's PLAN.md status to 'active'.\n"
+        if deferred:
+            names = ", ".join(d.name for d in deferred[-3:])
+            msg += (
+                f"  - {len(deferred)} deferred (parked) feature(s), skipped: "
+                f"{names}\n"
+                f"                    Flip one's PLAN.md status to `active` to "
+                f"resume it.\n"
+            )
         if done_pending_wrap:
             names = ", ".join(d.name for d in done_pending_wrap[-3:])
             msg += (
@@ -1917,6 +1947,22 @@ def verify_files_changed(result: dict, head_before: str) -> list[str]:
     return unchanged
 
 
+def _annotate_unchanged_paths(paths: "list[str]") -> str:
+    """Format files_changed-mismatch paths, distinguishing missing from unchanged.
+
+    Each declared-but-non-diffing path is labeled ``(missing)`` when it does
+    not exist on disk or ``(no diff)`` when it exists but is byte-identical to
+    head_before. Prior wording listed paths bare, which conflated the two —
+    an existing, unchanged file could read as a deletion claim and seed a
+    wrong root-cause diagnosis (#182). The labels say exactly what was found.
+    """
+    lines = []
+    for p in paths:
+        label = "no diff" if Path(str(p)).exists() else "missing"
+        lines.append(f"  - ({label}) {p}")
+    return "\n".join(lines)
+
+
 # Smoke-import runner (FEAT-2026-0008/T03). The conservative pattern matches
 # ONLY a `python3 -c "from X import Y"` line. The agent-authored WU body may
 # declare an existence check naming new symbols this WU just minted; the
@@ -4274,17 +4320,33 @@ def run(
                         # against head_before. Treat as a failed attempt: skip
                         # squash, reset the tree, record evidence, retry within
                         # budget. payload is the list of unchanged paths.
+                        _mm_paths = list(payload)
                         note = (
-                            "RESULT block declared `files_changed` paths that "
-                            "show NO diff against HEAD before this attempt:\n"
-                            + "\n".join(f"  - {p}" for p in payload)
-                            + "\nEither actually modify them, or correct the "
-                              "files_changed list to match what you really edited."
+                            "The RESULT block declared these `files_changed` "
+                            "paths, but each shows NO diff against HEAD before "
+                            "this attempt:\n"
+                            + _annotate_unchanged_paths(_mm_paths)
+                            + "\n\nDeclaring an unchanged path is what fails this "
+                              "guard. For each path: if it did NOT need changing, "
+                              "OMIT it from `files_changed` (declare only files you "
+                              "actually edit); if it SHOULD have changed, make the "
+                              "edit this attempt. A `(missing)` path was never "
+                              "created; a `(no diff)` path exists but is unchanged."
                         )
+                        # Populate failure_class/signature/excerpt (#182): a
+                        # driver-side rejection previously emitted all-null, so
+                        # events.jsonl — and gate-status, which reads only it —
+                        # showed empty columns exactly where the diagnosis lives.
+                        _mm_sig = ", ".join(
+                            sorted({Path(str(p)).name for p in _mm_paths})
+                        )[:100] or "unchanged"
                         wu_events.append(emit_attempt_outcome(
                             wu, attempt, "files_changed_mismatch",
                             attempts_usage[-1],
-                            extras={"unchanged_paths": list(payload)},
+                            failure_class="files_changed_mismatch",
+                            failure_signature=_mm_sig,
+                            failure_excerpt=extract_failure_excerpt(note),
+                            extras={"unchanged_paths": _mm_paths},
                         ))
                         attempt_notes.append((attempt, note))
                         failure_note = note

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

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

{specfuse_loop-0.3.18 → specfuse_loop-0.3.19}/tests/test_lint_plan_errors.py

@@ -104,6 +104,46 @@ class TestLintErrorArms(unittest.TestCase):
         self.assertTrue(any("frontmatter missing keys" in e for e in errs),
                         f"expected missing-keys error; errs={errs}")
 
+    def test_unknown_feature_status_errors(self):
+        """#185: a feature status outside the driver's enum is a lint error."""
+        with tempfile.TemporaryDirectory() as tmp:
+            feat = _build_minimal_feature(Path(tmp))
+            plan = feat / "PLAN.md"
+            plan.write_text(plan.read_text().replace(
+                "status: active", "status: paused", 1))
+            errs = lint_plan.lint(feat)
+        self.assertTrue(
+            any("'paused'" in e and "feature status" in e for e in errs),
+            f"expected feature-status error; errs={errs}")
+
+    def test_known_feature_statuses_do_not_error(self):
+        """Every documented feature status passes the vocabulary check."""
+        for status in ("planned", "active", "deferred", "done", "abandoned"):
+            with tempfile.TemporaryDirectory() as tmp:
+                feat = _build_minimal_feature(Path(tmp))
+                plan = feat / "PLAN.md"
+                plan.write_text(plan.read_text().replace(
+                    "status: active", f"status: {status}", 1))
+                errs = lint_plan.lint(feat)
+            self.assertFalse(
+                any("feature status" in e for e in errs),
+                f"{status!r} should be a valid feature status; errs={errs}")
+
+    def test_unknown_gate_status_errors(self):
+        """#185: a gate status outside the driver's enum is a lint error."""
+        with tempfile.TemporaryDirectory() as tmp:
+            feat = _build_minimal_feature(Path(tmp))
+            (feat / "GATE-01.md").write_text(
+                "---\nstatus: reviewing\n---\n\n# Gate 1\n")
+            # Point the graph's gate at the file so lint reads it.
+            plan = feat / "PLAN.md"
+            plan.write_text(plan.read_text().replace(
+                "  - gate: 1\n", "  - gate: 1\n    file: GATE-01.md\n", 1))
+            errs = lint_plan.lint(feat)
+        self.assertTrue(
+            any("'reviewing'" in e and "gate status" in e for e in errs),
+            f"expected gate-status error; errs={errs}")
+
     def test_plan_no_yaml_block(self):
         """Line 91: PLAN.md has valid frontmatter but no fenced yaml graph block."""
         with tempfile.TemporaryDirectory() as tmp:

{specfuse_loop-0.3.18 → specfuse_loop-0.3.19}/tests/test_loop_files_changed_guard.py

@@ -133,6 +133,15 @@ class TestVerifyFilesChanged(unittest.TestCase):
         self.assertEqual(
             loop.verify_files_changed(result, self.head), ["ignored.log"])
 
+    def test_annotate_distinguishes_missing_from_no_diff(self):
+        # #182: never label an existing-but-unchanged file as deleted. An
+        # on-disk path → "(no diff)"; an absent path → "(missing)".
+        (self.root / "present.py").write_text("x\n")
+        out = loop._annotate_unchanged_paths(["present.py", "gone.py"])
+        self.assertIn("(no diff) present.py", out)
+        self.assertIn("(missing) gone.py", out)
+        self.assertNotIn("deleted", out)
+
 
 def write_minimal_feature(root: Path, feature_id: str, slug: str,
                           branch: str, wus: list) -> Path:
@@ -302,6 +311,13 @@ class TestFilesChangedMismatchSpinsIntegration(unittest.TestCase):
                 self.assertEqual(ev["payload"]["unchanged_paths"],
                                  ["sentinel.py"],
                                  "payload must name the sentinel path")
+                # #182: driver-side rejections must populate the diagnosis
+                # fields, not emit all-null — gate-status reads only events.jsonl.
+                self.assertEqual(ev["payload"]["failure_class"],
+                                 "files_changed_mismatch")
+                self.assertIn("sentinel.py", ev["payload"]["failure_signature"])
+                self.assertTrue(ev["payload"]["failure_excerpt"],
+                                "failure_excerpt must not be null/empty")
 
             types = [e["event_type"] for e in events]
             self.assertNotIn("task_completed", types,

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

@@ -343,6 +343,31 @@ class TestFindFeatureSelection(unittest.TestCase):
         # The bad one is skipped; the good active feature still resolves.
         self.assertEqual(loop.find_feature(None), good)
 
+    def test_explicit_deferred_feature_is_refused(self):
+        """#183: `--feature` on a deferred feature must refuse, not dispatch."""
+        self._write_plan("FEAT-2026-9502-parked", "deferred")
+        with self.assertRaises(SystemExit) as ctx:
+            loop.find_feature("FEAT-2026-9502-parked")
+        msg = str(ctx.exception.code).lower()
+        self.assertIn("deferred", msg)
+        self.assertIn("active", msg)  # points at the fix
+
+    def test_deferred_not_treated_as_active_in_scan(self):
+        """#183: a lone deferred feature yields 'no active', named as parked."""
+        self._write_plan("FEAT-2026-9502-parked", "deferred")
+        with self.assertRaises(SystemExit) as ctx:
+            loop.find_feature(None)
+        msg = str(ctx.exception.code)
+        self.assertIn("No active feature", msg)
+        self.assertIn("parked", msg.lower())
+        self.assertIn("FEAT-2026-9502-parked", msg)
+
+    def test_deferred_does_not_block_a_real_active(self):
+        """A deferred feature alongside one active resolves to the active."""
+        self._write_plan("FEAT-2026-9502-parked", "deferred")
+        good = self._write_plan("FEAT-2026-9502-live", "active")
+        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."""
@@ -370,11 +395,13 @@ class TestFindFeatureSelection(unittest.TestCase):
         self._write_plan("FEAT-2026-9502-parked", "deferred")
         self.assertEqual(loop.find_feature(None), active_dir)
 
-    def test_deferred_still_selectable_by_explicit_arg(self):
-        """A human can still target a `deferred` feature explicitly (e.g. to
-        inspect it); only auto-selection skips it."""
-        fdir = self._write_plan("FEAT-2026-9502-parked", "deferred")
-        self.assertEqual(loop.find_feature("FEAT-2026-9502-parked"), fdir)
+    # NOTE (#183): the prior test asserted a `deferred` feature was still
+    # dispatchable via an explicit --feature (only auto-selection skipped it,
+    # from #106). That contradicted the shipped contract — the PLAN template,
+    # methodology.md, and the gate-status skill all document `deferred` as
+    # "non-dispatchable". #183 resolves the contradiction in favor of the docs:
+    # explicit dispatch is now refused (see test_explicit_deferred_feature_is_
+    # refused above), so that assertion is intentionally removed.
 
     def test_explicit_arg_without_plan_exits(self):
         """Lines 188-190: explicit dir name with no PLAN.md → sys.exit."""

specfuse_loop-0.3.18/specfuse/loop/data/VERSION

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