specfuse-loop 0.3.23__tar.gz → 0.3.24__tar.gz

{specfuse_loop-0.3.23/specfuse_loop.egg-info → specfuse_loop-0.3.24}/PKG-INFO

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

{specfuse_loop-0.3.23 → specfuse_loop-0.3.24}/pyproject.toml

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

specfuse_loop-0.3.24/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.24

{specfuse_loop-0.3.23 → specfuse_loop-0.3.24}/specfuse/loop/data/docs/skills.md

@@ -48,6 +48,11 @@ roadmap ──/pick-feature──▶ active ──/draft-feature──▶ gate 1
   `/draft-feature`.
 - **`/roadmap-add`** — add a new feature row to the roadmap before it's ready to
   pick.
+- **`/block-feature`** — flip a roadmap feature to `blocked` (or clear it) with a
+  linked `**Blocked by.**` blocker — an ADR awaiting approval or an upstream
+  FEAT-ID that must complete first. Writes the row status, the detail block, and
+  PLAN frontmatter, keeping intra-page feature links resolvable.
+  `/block-feature FEAT-ID --unblock` clears the block and restores the status.
 
 ### 2. Draft — turn a picked feature into a runnable gate
 

{specfuse_loop-0.3.23 → specfuse_loop-0.3.24}/specfuse/loop/data/roadmap.template.md

@@ -23,8 +23,24 @@ the canonical column order below.
 |----------------|-------|--------|--------|--------|
 
 Status: `planned` → `active` → `done` (or `abandoned`). `deferred` = parked
-pending an external decision/dependency; resumable (a human flips it back to
-`active` when the blocker clears), distinct from `abandoned` (dead).
+by choice pending an external decision/dependency; resumable (a human flips it
+back to `active` when the blocker clears), distinct from `abandoned` (dead).
+`blocked` = cannot proceed because a *named* dependency is unmet — an ADR
+awaiting approval, or an upstream feature that must complete first. Resumable
+like `deferred`, but where `deferred` is a voluntary park with no named blocker,
+`blocked` always names its blocker so the roadmap shows what it waits on and
+links to it.
+
+A `blocked` feature's detail section carries a `**Blocked by.**` block — blank
+line above it, one linked blocker per clause:
+
+**Blocked by.** [ADR-0007: event-schema versioning](../docs/adr/0007-event-schema-versioning.md) — awaiting approval; [FEAT-2026-0011](#feat-2026-0011) — scoring data must land first.
+
+Each blocker is a Markdown link: an ADR points at its `.md` file (kept under
+`docs/adr/` by convention, so from `.specfuse/roadmap.md` the link is
+`../docs/adr/…`); a feature dependency points at the blocking
+feature's roadmap anchor (`#feat-yyyy-nnnn`). When every blocker clears, a human
+flips `blocked` → `active` (or `planned`) and removes the `**Blocked by.**` block.
 
 ## Notes
 

{specfuse_loop-0.3.23 → specfuse_loop-0.3.24}/specfuse/loop/data/templates/PLAN.template.md

@@ -7,7 +7,7 @@ roadmap_goal: <one line copied from the roadmap — the north star this feature
   plan-next anchors every drafted gate to this and flags if a retrospective implies
   it should change>
 autonomy_default: review        # auto | review | supervised
-status: active                  # active | deferred | done | abandoned
+status: active                  # active | blocked | deferred | done | abandoned
                                 # deferred = parked pending an external decision/dependency; resumable, non-dispatchable
 # planned_cost_usd: 0.00        # OPTIONAL — sum of WU planned costs; lint warns when missing or when delta from WU sum > 10%
 ---

{specfuse_loop-0.3.23 → specfuse_loop-0.3.24}/specfuse/loop/lint_plan.py

@@ -46,7 +46,7 @@ VALID_STATUS = {"draft", "pending", "ready", "in_progress", "in_review", "done",
 # 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_FEATURE_STATUS = {"planned", "active", "blocked", "deferred", "done", "abandoned"}
 VALID_GATE_STATUS = {"open", "awaiting_review", "passed"}
 CLOSING_SEQUENCE = ["retrospective", "lessons", "docs", "plan-next"]
 # New compact closing shapes (FEAT-2026-0015):

{specfuse_loop-0.3.23 → specfuse_loop-0.3.24}/specfuse/loop/loop.py

@@ -64,7 +64,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.23"
+DRIVER_VERSION = "0.3.24"
 # 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
@@ -285,10 +285,22 @@ def find_feature(arg: str | None) -> Path:
                 f"deferred features. Flip its PLAN.md status back to `active` "
                 f"when the blocker clears, then re-run."
             )
+        # A `blocked` feature waits on a named unmet dependency (an ADR or an
+        # upstream feature — see its roadmap `**Blocked by.**` block). Like
+        # `deferred` it is non-dispatchable; refuse an explicit --feature
+        # targeting one rather than dispatching it anyway.
+        if _fm.get("status") == "blocked":
+            sys.exit(
+                f"{d.name} is blocked — the loop does not dispatch blocked "
+                f"features. Clear its blocker(s), then run "
+                f"`/block-feature {_fm.get('feature_id', d.name)} --unblock` "
+                f"(or flip its PLAN.md status back to `active`) and re-run."
+            )
         return d
     actives = []
     done_pending_wrap = []
     deferred = []
+    blocked = []
     for d in sorted(FEATURES_DIR.glob("*/")):
         plan = d / "PLAN.md"
         if plan.exists():
@@ -316,6 +328,11 @@ def find_feature(arg: str | None) -> Path:
                 # a bare invocation won't pick it up; surfaced below so a lone
                 # deferred feature reads as parked, not silently absent.
                 deferred.append(d)
+            elif fm.get("status") == "blocked":
+                # Waiting on a named unmet dependency — non-dispatchable, same
+                # as deferred. Surfaced below so a lone blocked feature reads as
+                # parked-on-a-blocker, not silently absent.
+                blocked.append(d)
     if len(actives) == 1:
         return actives[0]
     if not actives:
@@ -328,6 +345,13 @@ def find_feature(arg: str | None) -> Path:
                 f"                    Flip one's PLAN.md status to `active` to "
                 f"resume it.\n"
             )
+        if blocked:
+            names = ", ".join(d.name for d in blocked[-3:])
+            msg += (
+                f"  - {len(blocked)} blocked feature(s), skipped: {names}\n"
+                f"                    Clear the blocker, then /block-feature "
+                f"<id> --unblock to resume.\n"
+            )
         if done_pending_wrap:
             names = ", ".join(d.name for d in done_pending_wrap[-3:])
             msg += (
@@ -2669,7 +2693,14 @@ def auto_archive_feature(feature_id: str, repo_root: Path) -> str:
         section_m2 = section_re.search(roadmap_text)
         if section_m2:
             roadmap_text = roadmap_text[:section_m2.start()] + roadmap_text[section_m2.end():]
-            roadmap_text = re.sub(r'\n{3,}', '\n\n', roadmap_text)
+    # A feature that was ever `blocked` via /block-feature carries an explicit
+    # `<a id="feat-…"></a>` line above its heading (so intra-page `#feat-…`
+    # links resolve). The section regex above does not span it, so removing the
+    # section would strand the anchor pointing at a section that has moved to the
+    # archive. Strip the now-orphaned anchor line; Step 3 already re-emitted the
+    # canonical anchor in roadmap-archive.md, so the link target travels with it.
+    roadmap_text = roadmap_text.replace(f"{anchor}\n", "")
+    roadmap_text = re.sub(r'\n{3,}', '\n\n', roadmap_text)
     roadmap_path.write_text(roadmap_text)
 
     return "archived"

{specfuse_loop-0.3.23 → specfuse_loop-0.3.24/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.3.23 → specfuse_loop-0.3.24}/tests/test_loop_auto_archive.py

@@ -42,6 +42,27 @@ _ROADMAP_DONE = textwrap.dedent("""\
     Some content here.
     """)
 
+_ROADMAP_DONE_WITH_ANCHOR = textwrap.dedent("""\
+    ---
+    project: test
+    ---
+
+    # Roadmap
+
+    | Feature ID | Title | Status | Folder | Detail |
+    |------------|-------|--------|--------|--------|
+    | FEAT-2026-9999 | Test feature | done | — | — |
+
+    <a id="feat-2026-9999"></a>
+    ## FEAT-2026-9999 — Test feature
+
+    Some content here.
+
+    ## Notes
+
+    Trailing content.
+    """)
+
 _ROADMAP_DONE_NO_SECTION = textwrap.dedent("""\
     ---
     project: test
@@ -122,6 +143,25 @@ class TestAutoArchiveFeature(unittest.TestCase):
                             "anchor must appear before section heading in archive")
             self.assertIn('Some content here.', archive_text)
 
+    def test_preexisting_anchor_not_orphaned(self):
+        """A feature blocked via /block-feature carries an explicit <a id> above
+        its heading; archiving must remove it, not strand it in roadmap.md."""
+        with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as tmp:
+            repo = _make_repo(tmp, roadmap=_ROADMAP_DONE_WITH_ANCHOR)
+            result = loop.auto_archive_feature("FEAT-2026-9999", repo)
+            self.assertEqual(result, "archived")
+
+            roadmap_text = (repo / ".specfuse" / "roadmap.md").read_text()
+            archive_text = (repo / ".specfuse" / "roadmap-archive.md").read_text()
+
+            # No orphan anchor left behind in roadmap.md.
+            self.assertNotIn('<a id="feat-2026-9999"></a>', roadmap_text)
+            self.assertNotIn('## FEAT-2026-9999 — ', roadmap_text)
+            # Unrelated content survives.
+            self.assertIn('## Notes', roadmap_text)
+            # Archive carries exactly one anchor for the feature.
+            self.assertEqual(archive_text.count('<a id="feat-2026-9999"></a>'), 1)
+
     def test_idempotent_second_call(self):
         """Second call returns 'already archived' and makes zero file edits."""
         with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as tmp:

{specfuse_loop-0.3.23 → specfuse_loop-0.3.24}/tests/test_loop_orchestration.py

@@ -368,6 +368,31 @@ class TestFindFeatureSelection(unittest.TestCase):
         good = self._write_plan("FEAT-2026-9502-live", "active")
         self.assertEqual(loop.find_feature(None), good)
 
+    def test_explicit_blocked_feature_is_refused(self):
+        """`--feature` on a blocked feature must refuse, not dispatch."""
+        self._write_plan("FEAT-2026-9502-stuck", "blocked")
+        with self.assertRaises(SystemExit) as ctx:
+            loop.find_feature("FEAT-2026-9502-stuck")
+        msg = str(ctx.exception.code).lower()
+        self.assertIn("blocked", msg)
+        self.assertIn("unblock", msg)  # points at the fix
+
+    def test_blocked_not_treated_as_active_in_scan(self):
+        """A lone blocked feature yields 'no active', named as blocked."""
+        self._write_plan("FEAT-2026-9502-stuck", "blocked")
+        with self.assertRaises(SystemExit) as ctx:
+            loop.find_feature(None)
+        msg = str(ctx.exception.code)
+        self.assertIn("No active feature", msg)
+        self.assertIn("blocked", msg.lower())
+        self.assertIn("FEAT-2026-9502-stuck", msg)
+
+    def test_blocked_does_not_block_a_real_active(self):
+        """A blocked feature alongside one active resolves to the active."""
+        self._write_plan("FEAT-2026-9502-stuck", "blocked")
+        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."""

specfuse_loop-0.3.23/specfuse/loop/data/VERSION

@@ -1 +0,0 @@
-0.3.23