specfuse-loop 0.3.2__tar.gz → 0.3.4__tar.gz

{specfuse_loop-0.3.2/specfuse_loop.egg-info → specfuse_loop-0.3.4}/PKG-INFO

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

{specfuse_loop-0.3.2 → specfuse_loop-0.3.4}/pyproject.toml

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

specfuse_loop-0.3.4/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.4

{specfuse_loop-0.3.2 → specfuse_loop-0.3.4}/specfuse/loop/data/docs/getting-started.md

@@ -109,7 +109,16 @@ A feature folder holds:
 | `GATE-NN.md` | one gate's status and definition of done | you / the planner |
 | `WU-*.md` | a single work unit: frontmatter + the prompt a fresh session receives | you / `draft-feature` / `plan-next` |
 
-Then create the branch named in `PLAN.md`'s frontmatter (`branch:`).
+`draft-feature` writes the folder but doesn't commit it or switch branches, so
+the loop will refuse to start until the folder is on its branch and committed.
+Let the driver do both for you:
+
+```bash
+specfuse-loop --prepare      # create the PLAN.md `branch:`, commit the folder, then run
+```
+
+(Or by hand: `git checkout -b <branch>` from `PLAN.md`'s frontmatter, then
+`git add` + `git commit` the feature folder.)
 
 ## 4. Validate before running
 

{specfuse_loop-0.3.2 → specfuse_loop-0.3.4}/specfuse/loop/loop.py

@@ -62,7 +62,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.2"
+DRIVER_VERSION = "0.3.4"
 # 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
@@ -709,7 +709,40 @@ def untracked_feature_files(feature_dir: "Path") -> list[str]:
     return [ln.strip() for ln in out.splitlines() if ln.strip()]
 
 
-def require_feature_folder_committed(feature_dir: "Path") -> None:
+def _current_branch() -> str:
+    """The checked-out branch name ('' when detached)."""
+    return git("branch", "--show-current")
+
+
+def _branch_prep_hint(feature_dir: "Path", feat_fm: dict, feature_id: str) -> str:
+    """Actionable next-step block for the two pre-flight guards.
+
+    `draft-feature` writes the feature folder but neither creates the feature's
+    branch nor commits — so the loop refuses to start. The fix is two steps when
+    you're not yet on the feature's branch (create it, then commit), and the
+    `--prepare` flag does both for you. Build a hint that names the real branch
+    and only includes the checkout line when it's actually needed.
+    """
+    branch = feat_fm.get("branch") or f"feat/{feature_id}"
+    on_branch = _current_branch() == branch
+    lines = [
+        "",
+        "Easiest — let the loop create the branch and commit for you:",
+        "    specfuse-loop --prepare        # …then run",
+        "    specfuse-loop --prepare-only   # …then stop, so you can review first",
+        "",
+        "Or do it manually:",
+    ]
+    if not on_branch:
+        lines.append(f"    git checkout -b {branch}")
+    lines.append(f"    git add {feature_dir}")
+    lines.append(f"    git commit -m 'chore: scaffold feature {feature_id}'")
+    return "\n".join(lines)
+
+
+def require_feature_folder_committed(
+    feature_dir: "Path", feat_fm: dict, feature_id: str,
+) -> None:
     """Hard-stop if the dispatched feature folder has untracked files (#71).
 
     The per-attempt `git reset --hard head_before` rolls tracked files back to
@@ -726,12 +759,11 @@ def require_feature_folder_committed(feature_dir: "Path") -> None:
         listed = "\n  ".join(sorted(untracked))
         sys.exit(
             f"loop.py: feature folder '{feature_dir}' has untracked files — "
-            f"commit them before running the loop, or the per-attempt "
-            f"`git reset --hard` will delete the folder mid-run (and the driver "
-            f"will crash reading a WU file that no longer exists). Untracked:\n"
-            f"  {listed}\n"
-            f"Fix: `git add {feature_dir} && git commit -m "
-            f"'chore: commit feature folder'`, then re-run."
+            f"create the feature branch and commit them before running, or the "
+            f"per-attempt `git reset --hard` will delete the folder mid-run (and "
+            f"the driver will crash reading a WU file that no longer exists). "
+            f"Untracked:\n  {listed}\n"
+            + _branch_prep_hint(feature_dir, feat_fm, feature_id)
         )
 
 
@@ -786,7 +818,9 @@ def feature_folder_tracked_modifications(feature_dir: "Path") -> list[str]:
     return mods
 
 
-def require_feature_folder_unmodified(feature_dir: "Path") -> None:
+def require_feature_folder_unmodified(
+    feature_dir: "Path", feat_fm: dict, feature_id: str,
+) -> None:
     """Hard-stop on uncommitted arm-gate / WU-revision edits before dispatch (#74).
 
     arm-gate (and any manual WU-body revision at a gate boundary) writes
@@ -808,11 +842,30 @@ def require_feature_folder_unmodified(feature_dir: "Path") -> None:
             f"`git reset --hard` will discard them (your armed WU statuses and "
             f"any acceptance-criteria revisions would silently revert). "
             f"Modified:\n  {listed}\n"
-            f"Fix: `git add {feature_dir} && git commit -m "
-            f"'chore(arm): commit gate edits'`, then re-run."
+            + _branch_prep_hint(feature_dir, feat_fm, feature_id)
         )
 
 
+def prepare_feature(feat_fm: dict, feature_dir: "Path", feature_id: str) -> None:
+    """`--prepare`: put the feature folder on its declared branch and commit it.
+
+    `draft-feature` leaves the folder uncommitted on whatever branch you were on
+    (usually the default). This creates/checks out the feature's branch (from
+    PLAN.md `branch:`, carrying the untracked folder along) and commits the
+    folder, so the pre-flight guards pass and the run can start. Idempotent: a
+    no-op commit when there is nothing to commit.
+    """
+    branch = feat_fm.get("branch")
+    ensure_feature_branch(feat_fm, feature_dir)
+    git("add", "--", str(feature_dir))
+    staged = git("status", "--porcelain", "--", str(feature_dir))
+    if staged:
+        git("commit", "-m", f"chore: scaffold feature {feature_id}")
+        print(f"Prepared: committed feature folder on branch '{branch}'.")
+    else:
+        print(f"Prepare: feature folder already committed on branch '{branch}'.")
+
+
 def _checked_checkout(checkout_args: list[str], action: str) -> str:
     """Run a `git checkout ...` guarded: on non-zero exit raise FeatureBranchError
     carrying git's stderr, instead of a bare CalledProcessError that hides it.
@@ -874,9 +927,15 @@ def ensure_feature_branch(feat_fm: dict, feature_dir: "Path | None" = None) -> N
         ).returncode == 0
         if not is_ancestor:
             raise FeatureBranchError(
-                f"branch '{branch}' exists and diverges from HEAD (not an "
-                f"ancestor). Refusing to silently check out a stale branch; "
-                f"resolve manually (rebase, recreate, or delete it) and re-run."
+                f"branch '{branch}' already exists and has diverged from your "
+                f"current branch '{current}' (it carries commits HEAD does not). "
+                f"Refusing to silently check it out — that could build on a stale "
+                f"base or lose work. Pick one, then re-run:\n"
+                f"  - resume that branch's work:    git checkout {branch}\n"
+                f"  - rebase it onto here:          git checkout {branch} && "
+                f"git rebase {current}\n"
+                f"  - discard it (work not needed): git branch -D {branch}   "
+                f"(the loop recreates it from HEAD)"
             )
         _checked_checkout(["checkout", branch], f"checkout of existing branch '{branch}'")
         print(f"Switched to feature branch '{branch}' (was on '{current}').")
@@ -2921,6 +2980,8 @@ def run(
     feature_arg: str | None,
     dry_run: bool,
     force_full_close: str | None = None,
+    prepare: bool = False,
+    prepare_only: bool = False,
 ) -> int:
     # Fail-fast on a malformed verification.yml BEFORE we touch any WU state.
     # The per-gate `verify()` call lazy-loads the same file; if it's malformed,
@@ -2974,6 +3035,16 @@ def run(
             )
             return 1
         require_git_ready()
+        # --prepare / --prepare-only: create the feature branch + commit the
+        # folder up front so the guards below pass (the do-it-for-me path
+        # draft-feature can't take). --prepare-only stops after, so you can
+        # review the commit before the loop dispatches anything.
+        if prepare or prepare_only:
+            prepare_feature(feat_fm, feature_dir, feature_id)
+        if prepare_only:
+            print("Prepared: feature is on its branch and committed. "
+                  "Re-run `specfuse-loop` to start the gate.")
+            return 0
         # Pre-flight guards — both run BEFORE ensure_feature_branch so the
         # refusal happens before any branch mutation, and both protect against
         # the per-attempt `git reset --hard` destroying uncommitted state:
@@ -2981,8 +3052,8 @@ def run(
         #         deleted by the reset (and crash the next frontmatter write).
         #   #74 — uncommitted arm-gate / WU-revision edits (armed statuses, AC
         #         revisions) would be silently discarded by the reset.
-        require_feature_folder_committed(feature_dir)
-        require_feature_folder_unmodified(feature_dir)
+        require_feature_folder_committed(feature_dir, feat_fm, feature_id)
+        require_feature_folder_unmodified(feature_dir, feat_fm, feature_id)
         ensure_feature_branch(feat_fm, feature_dir)
 
     try:
@@ -3952,11 +4023,21 @@ def main() -> int:
                     "path for the named feature. Must match the feature being processed.")
     ap.add_argument("--no-autosync", action="store_true",
                     help="Skip auto-sync entirely (no scaffold create or overlay).")
+    ap.add_argument("--prepare", action="store_true",
+                    help="Create the active feature's branch (from PLAN.md "
+                    "'branch:') and commit its folder, then run — the do-it-for-me "
+                    "path after /draft-feature, which leaves the folder "
+                    "uncommitted on the current branch.")
+    ap.add_argument("--prepare-only", action="store_true",
+                    help="Like --prepare (create branch + commit the folder) but "
+                    "STOP afterwards without dispatching — review the commit, then "
+                    "re-run `specfuse-loop` to start.")
     args = ap.parse_args()
     if not FEATURES_DIR.exists():
         sys.exit(f"No {FEATURES_DIR}. Run from your repo root.")
     auto_sync(dry_run=args.dry_run, no_autosync=args.no_autosync)
-    return run(args.feature, args.dry_run, force_full_close=args.force_full_close)
+    return run(args.feature, args.dry_run, force_full_close=args.force_full_close,
+               prepare=args.prepare, prepare_only=args.prepare_only)
 
 
 if __name__ == "__main__":

{specfuse_loop-0.3.2 → specfuse_loop-0.3.4/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.3.2 → specfuse_loop-0.3.4}/specfuse_loop.egg-info/SOURCES.txt

@@ -101,6 +101,7 @@ tests/test_migrate_legacy.py
 tests/test_miniyaml_equivalence.py
 tests/test_miniyaml_negative.py
 tests/test_planned_cost_lint.py
+tests/test_prepare_feature.py
 tests/test_produces_field.py
 tests/test_result_block.py
 tests/test_roadmap_add_skill.py

{specfuse_loop-0.3.2 → specfuse_loop-0.3.4}/tests/test_arm_gate_edits_uncommitted.py

@@ -81,7 +81,7 @@ class TestFeatureFolderTrackedModifications(unittest.TestCase):
             mods = loop.feature_folder_tracked_modifications(rel)
             self.assertTrue(any("WU-05.md" in m for m in mods))
             with self.assertRaises(SystemExit):
-                loop.require_feature_folder_unmodified(rel)
+                loop.require_feature_folder_unmodified(rel, {"branch": "feat/t"}, "FEAT-2026-9999")
 
     def test_clean_folder_passes(self):
         with tempfile.TemporaryDirectory() as tmp:
@@ -91,7 +91,7 @@ class TestFeatureFolderTrackedModifications(unittest.TestCase):
             os.chdir(root)
             rel = fdir.relative_to(root)
             self.assertEqual(loop.feature_folder_tracked_modifications(rel), [])
-            loop.require_feature_folder_unmodified(rel)  # must not raise
+            loop.require_feature_folder_unmodified(rel, {"branch": "feat/t"}, "FEAT-2026-9999")  # must not raise
 
     def test_plan_md_flip_does_not_block(self):
         """pick-feature's PLAN.md status flip is expected, not an arm edit."""
@@ -106,7 +106,7 @@ class TestFeatureFolderTrackedModifications(unittest.TestCase):
             os.chdir(root)
             rel = fdir.relative_to(root)
             self.assertEqual(loop.feature_folder_tracked_modifications(rel), [])
-            loop.require_feature_folder_unmodified(rel)  # must not raise
+            loop.require_feature_folder_unmodified(rel, {"branch": "feat/t"}, "FEAT-2026-9999")  # must not raise
 
     def test_events_jsonl_change_does_not_block(self):
         """events.jsonl is driver-managed (preserved across reset), not an arm edit."""
@@ -118,7 +118,7 @@ class TestFeatureFolderTrackedModifications(unittest.TestCase):
             os.chdir(root)
             rel = fdir.relative_to(root)
             self.assertEqual(loop.feature_folder_tracked_modifications(rel), [])
-            loop.require_feature_folder_unmodified(rel)  # must not raise
+            loop.require_feature_folder_unmodified(rel, {"branch": "feat/t"}, "FEAT-2026-9999")  # must not raise
 
 
 class TestRunRefusesUncommittedArmEdits(unittest.TestCase):

{specfuse_loop-0.3.2 → specfuse_loop-0.3.4}/tests/test_loop_orchestration.py

@@ -706,7 +706,7 @@ class TestMainArgparse(unittest.TestCase):
                 with patch.object(sys, "argv", ["loop", "--feature", "my-feature"]):
                     result = loop.main()
         self.assertEqual(result, 0)
-        mock_run.assert_called_once_with("my-feature", False, force_full_close=None)
+        mock_run.assert_called_once_with("my-feature", False, force_full_close=None, prepare=False, prepare_only=False)
 
     def test_dry_run_flag_forwarded_to_run(self):
         """--dry-run is forwarded as dry_run=True to run()."""
@@ -718,7 +718,7 @@ class TestMainArgparse(unittest.TestCase):
             with patch.object(loop, "run", return_value=0) as mock_run:
                 with patch.object(sys, "argv", ["loop", "--dry-run"]):
                     loop.main()
-        mock_run.assert_called_once_with(None, True, force_full_close=None)
+        mock_run.assert_called_once_with(None, True, force_full_close=None, prepare=False, prepare_only=False)
 
     def test_multi_active_error_propagates_from_run(self):
         """main() with no args propagates the find_feature multi-active SystemExit."""

specfuse_loop-0.3.4/tests/test_prepare_feature.py

@@ -0,0 +1,159 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""--prepare and the branch-aware guard hints.
+
+`draft-feature` writes the feature folder but neither creates the feature's
+branch nor commits, so the loop refuses to start (#71/#74). The refusal must
+tell you to create the branch first (when you're on the default branch), and
+`--prepare` must do branch-create + commit for you.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import subprocess
+import tempfile
+import unittest
+from contextlib import redirect_stderr
+from pathlib import Path
+
+from tests._loop_loader import load_loop
+
+loop = load_loop()
+
+_FEAT_ID = "FEAT-2026-9999"
+_BRANCH = "feat/FEAT-2026-9999-thing"
+
+
+def _init_git(root: Path) -> None:
+    subprocess.run(["git", "init", "-q", "-b", "main", str(root)], check=True)
+    subprocess.run(["git", "-C", str(root), "config", "user.email", "t@example.com"],
+                   check=True)
+    subprocess.run(["git", "-C", str(root), "config", "user.name", "Test"], check=True)
+    subprocess.run(["git", "-C", str(root), "config", "commit.gpgSign", "false"],
+                   check=True)
+    (root / "README.md").write_text("# fixture\n")
+    specfuse = root / ".specfuse"
+    specfuse.mkdir()
+    (specfuse / "verification.yml").write_text(
+        "code:\n  - name: noop\n    command: \"true\"\n"
+        "doc:\n  - name: noop\n    command: \"true\"\n"
+        "plannext:\n  - name: noop\n    command: \"true\"\n"
+    )
+    subprocess.run(["git", "-C", str(root), "add", "."], check=True)
+    subprocess.run(["git", "-C", str(root), "commit", "-q", "-m", "init"], check=True)
+
+
+def _write_uncommitted_feature(root: Path) -> Path:
+    """A freshly-drafted, UNcommitted feature folder on the current branch."""
+    fdir = root / ".specfuse" / "features" / f"{_FEAT_ID}-thing"
+    fdir.mkdir(parents=True)
+    (fdir / "PLAN.md").write_text(
+        f"---\nfeature_id: {_FEAT_ID}\ntitle: T\nbranch: {_BRANCH}\n"
+        f"roadmap_goal: t\nstatus: active\n---\n\n# Plan\n\n```yaml\n"
+        f"gates:\n  - gate: 1\n    file: GATE-01.md\n    work_units:\n"
+        f"      - id: {_FEAT_ID}/T01\n        file: WU-01.md\n"
+        f"        depends_on: []\n```\n"
+    )
+    (fdir / "GATE-01.md").write_text("---\ngate: 1\nstatus: open\n---\n\n# Gate 1\n")
+    (fdir / "WU-01.md").write_text(
+        f"---\nid: {_FEAT_ID}/T01\ntype: implementation\n"
+        "status: pending\nattempts: 0\n---\n\n# WU\n"
+    )
+    return fdir
+
+
+def _feat_fm() -> dict:
+    return {"feature_id": _FEAT_ID, "branch": _BRANCH}
+
+
+class TestPrepareFeature(unittest.TestCase):
+
+    def setUp(self):
+        self._cwd = os.getcwd()
+
+    def tearDown(self):
+        os.chdir(self._cwd)
+
+    def test_prepare_creates_branch_and_commits(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _init_git(root)
+            fdir = _write_uncommitted_feature(root)
+            os.chdir(root)
+            rel = fdir.relative_to(root)
+            loop.prepare_feature(_feat_fm(), rel, _FEAT_ID)
+            # on the feature branch now
+            self.assertEqual(loop._current_branch(), _BRANCH)
+            # folder is tracked + tree clean (committed)
+            self.assertEqual(loop.untracked_feature_files(rel), [])
+            self.assertEqual(loop.feature_folder_tracked_modifications(rel), [])
+            tracked = subprocess.run(["git", "ls-files", str(rel)],
+                                     capture_output=True, text=True).stdout
+            self.assertIn("PLAN.md", tracked)
+
+    def test_prepare_only_prepares_then_stops(self):
+        """--prepare-only branches + commits but does NOT dispatch (rc=0)."""
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _init_git(root)
+            _write_uncommitted_feature(root)
+            os.chdir(root)
+
+            called = {"dispatch": False}
+
+            def _no_dispatch(*a, **k):
+                called["dispatch"] = True
+                raise AssertionError("must not dispatch under --prepare-only")
+
+            orig = loop.dispatch
+            loop.dispatch = _no_dispatch
+            try:
+                rc = loop.run(None, dry_run=False, prepare_only=True)
+            finally:
+                loop.dispatch = orig
+
+            self.assertEqual(rc, 0)
+            self.assertFalse(called["dispatch"])
+            self.assertEqual(loop._current_branch(), _BRANCH)
+            # folder committed (tree clean)
+            rel = Path(".specfuse/features") / f"{_FEAT_ID}-thing"
+            self.assertEqual(loop.untracked_feature_files(rel), [])
+
+    def test_committed_guard_message_suggests_prepare_and_branch(self):
+        """On the default branch, the untracked-folder refusal names --prepare
+        AND the `git checkout -b <branch>` step."""
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _init_git(root)
+            fdir = _write_uncommitted_feature(root)
+            os.chdir(root)
+            rel = fdir.relative_to(root)
+            err = io.StringIO()
+            with self.assertRaises(SystemExit) as cm, redirect_stderr(err):
+                loop.require_feature_folder_committed(rel, _feat_fm(), _FEAT_ID)
+            msg = str(cm.exception)
+            self.assertIn("specfuse-loop --prepare", msg)
+            self.assertIn(f"git checkout -b {_BRANCH}", msg)
+
+    def test_guard_message_omits_checkout_when_on_feature_branch(self):
+        """When already on the feature branch, no checkout line — just commit."""
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            _init_git(root)
+            fdir = _write_uncommitted_feature(root)
+            os.chdir(root)
+            subprocess.run(["git", "checkout", "-q", "-b", _BRANCH], check=True)
+            rel = fdir.relative_to(root)
+            with self.assertRaises(SystemExit) as cm:
+                loop.require_feature_folder_committed(rel, _feat_fm(), _FEAT_ID)
+            msg = str(cm.exception)
+            self.assertIn("specfuse-loop --prepare", msg)
+            self.assertNotIn("git checkout -b", msg)
+
+
+if __name__ == "__main__":
+    unittest.main()

{specfuse_loop-0.3.2 → specfuse_loop-0.3.4}/tests/test_untracked_feature_folder.py

@@ -78,7 +78,7 @@ class TestRequireFeatureFolderCommitted(unittest.TestCase):
             files = loop.untracked_feature_files(rel)
             self.assertTrue(files, "the freshly written folder must read as untracked")
             with self.assertRaises(SystemExit):
-                loop.require_feature_folder_committed(rel)
+                loop.require_feature_folder_committed(rel, {"branch": "feat/t"}, "FEAT-2026-9999")
 
     def test_committed_folder_passes(self):
         """A committed feature folder is a no-op (no exit)."""
@@ -92,7 +92,7 @@ class TestRequireFeatureFolderCommitted(unittest.TestCase):
             os.chdir(root)
             rel = fdir.relative_to(root)
             self.assertEqual(loop.untracked_feature_files(rel), [])
-            loop.require_feature_folder_committed(rel)  # must not raise
+            loop.require_feature_folder_committed(rel, {"branch": "feat/t"}, "FEAT-2026-9999")  # must not raise
 
     def test_gitignored_work_dir_does_not_block(self):
         """Driver-managed gitignored paths (work/) must not count as untracked."""
@@ -111,7 +111,7 @@ class TestRequireFeatureFolderCommitted(unittest.TestCase):
             rel = fdir.relative_to(root)
             self.assertEqual(loop.untracked_feature_files(rel), [],
                              "gitignored work/ must not be flagged")
-            loop.require_feature_folder_committed(rel)  # must not raise
+            loop.require_feature_folder_committed(rel, {"branch": "feat/t"}, "FEAT-2026-9999")  # must not raise
 
 
 class TestWriteFrontmatterFieldHardening(unittest.TestCase):

specfuse_loop-0.3.2/specfuse/loop/data/VERSION

@@ -1 +0,0 @@
-0.3.2