specfuse-loop 0.3.1__tar.gz → 0.3.3__tar.gz

{specfuse_loop-0.3.1/specfuse_loop.egg-info → specfuse_loop-0.3.3}/PKG-INFO

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

{specfuse_loop-0.3.1 → specfuse_loop-0.3.3}/pyproject.toml

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

specfuse_loop-0.3.3/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.3

{specfuse_loop-0.3.1 → specfuse_loop-0.3.3}/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.1 → specfuse_loop-0.3.3}/specfuse/loop/data/templates/GATE.template.md

@@ -14,12 +14,6 @@ status: open        # open | awaiting_review | passed
 # set it in the successor gate to exercise the brake for the first time.
 ---
 
-<!--
-Copyright 2026 Specfuse Contributors
-Licensed under the Apache License, Version 2.0. See LICENSE.
--->
-
-
 # Gate 1 — <name of the milestone this gate proves>
 
 ## Definition of done

{specfuse_loop-0.3.1 → specfuse_loop-0.3.3}/specfuse/loop/data/templates/PLAN.template.md

@@ -11,12 +11,6 @@ status: active                  # active | done | abandoned
 # planned_cost_usd: 0.00        # OPTIONAL — sum of WU planned costs; lint warns when missing or when delta from WU sum > 10%
 ---
 
-<!--
-Copyright 2026 Specfuse Contributors
-Licensed under the Apache License, Version 2.0. See LICENSE.
--->
-
-
 # Plan: <short feature title>
 
 <One or two paragraphs of human-facing intent. The work units carry the executable

{specfuse_loop-0.3.1 → specfuse_loop-0.3.3}/specfuse/loop/data/templates/WU.template.md

@@ -10,12 +10,6 @@ generated_surfaces: []     # OPTIONAL — paths to generated files this unit's a
 # oracle_env: macos_local  # OPTIONAL — environment where this WU's verifying oracle runs; see frontmatter notes
 ---
 
-<!--
-Copyright 2026 Specfuse Contributors
-Licensed under the Apache License, Version 2.0. See LICENSE.
--->
-
-
 <!--
 Frontmatter notes (single-repo):
 
@@ -48,6 +42,9 @@ DRIVER-OWNED FIELDS — the driver writes these at outcome time; authors leave t
 <!-- driver-owned: attempts, cost_usd, input_tokens, output_tokens, duration_seconds,
      cumulative_cost_usd, cumulative_duration_seconds, cumulative_input_tokens,
      cumulative_output_tokens, re_arm_count, re_arm_history -->
+<!-- driver-stamped at dispatch (resolved execution metadata, visible in this .md):
+     model, effort (override or type default), gate_set (the verification.yml set
+     that is this WU's exit oracle), driver_version, started_at (UTC ISO). -->
 <!-- Full field semantics in docs/methodology.md §2 and events.jsonl outcome payloads. -->
 
 Dependencies live in PLAN.md's `gates[].work_units[].depends_on` graph, not

{specfuse_loop-0.3.1 → specfuse_loop-0.3.3}/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.1"
+DRIVER_VERSION = "0.3.3"
 # 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,39 @@ 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",
+        "",
+        "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 +758,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 +817,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 +841,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.
@@ -2921,6 +2973,7 @@ def run(
     feature_arg: str | None,
     dry_run: bool,
     force_full_close: str | None = None,
+    prepare: 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 +3027,10 @@ def run(
             )
             return 1
         require_git_ready()
+        # --prepare: 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).
+        if prepare:
+            prepare_feature(feat_fm, feature_dir, feature_id)
         # 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 +3038,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:
@@ -3156,6 +3213,20 @@ def run(
                 if _is_rearm:
                     fold_cumulative_on_rearm(wu, backend)
                 backend.set_wu(wu, "status", "in_progress")
+                # Stamp the resolved execution metadata into the WU frontmatter so
+                # it is visible when you read the .md (not only on the console /
+                # in events.jsonl): the model + effort it runs with (override or
+                # type default), which verification gate set is its exit oracle,
+                # the driver version that executed it, and when it was dispatched.
+                # Written after head_before so they ride the WU's squash commit;
+                # idempotent on retries/re-arms (same values overwrite cleanly,
+                # started_at refreshes to the latest dispatch).
+                backend.set_wu(wu, "model", wu.model)
+                backend.set_wu(wu, "effort", wu.effort)
+                backend.set_wu(wu, "gate_set", GATES_FOR_TYPE.get(wu.type, "code"))
+                backend.set_wu(wu, "driver_version", DRIVER_VERSION)
+                backend.set_wu(wu, "started_at",
+                               dt.datetime.now(dt.timezone.utc).isoformat())
                 # Events and per-attempt notes are buffered in memory during the
                 # WU's lifecycle and flushed at outcome time. This prevents the
                 # `git reset --hard` between failed attempts from silently
@@ -3938,11 +4009,17 @@ 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.")
     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)
 
 
 if __name__ == "__main__":

{specfuse_loop-0.3.1 → specfuse_loop-0.3.3/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.3.1 → specfuse_loop-0.3.3}/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
@@ -124,4 +125,5 @@ tests/test_validate_event.py
 tests/test_verdict_coupling.py
 tests/test_verify_empty_gate_set.py
 tests/test_version_consistency.py
-tests/test_version_skew.py
+tests/test_version_skew.py
+tests/test_wu_execution_metadata.py

{specfuse_loop-0.3.1 → specfuse_loop-0.3.3}/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.1 → specfuse_loop-0.3.3}/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)
 
     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)
 
     def test_multi_active_error_propagates_from_run(self):
         """main() with no args propagates the find_feature multi-active SystemExit."""

specfuse_loop-0.3.3/tests/test_prepare_feature.py

@@ -0,0 +1,121 @@
+#
+# 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")
+    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"
+    )
+    (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_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.1 → specfuse_loop-0.3.3}/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.3/tests/test_wu_execution_metadata.py

@@ -0,0 +1,115 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""The driver stamps resolved execution metadata into a WU's frontmatter.
+
+So the planned/effective model, effort, exit-oracle gate set, driver version,
+and dispatch time are visible when you read the WU `.md` — not only on the
+console or in events.jsonl. Written at dispatch (after status -> in_progress),
+so they ride the WU's squash commit.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import unittest
+from pathlib import Path
+
+from tests._loop_loader import load_loop
+from tests.test_driver_integration import (
+    integration_workspace,
+    write_minimal_feature,
+    _read_frontmatter,
+)
+
+loop = load_loop()
+
+
+def _write_verification_yml(root: Path) -> None:
+    (root / ".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", ".specfuse/verification.yml"],
+                   check=True)
+    subprocess.run(["git", "-C", str(root), "commit", "-q", "-m", "verif"], check=True)
+
+
+class TestWUExecutionMetadata(unittest.TestCase):
+
+    def setUp(self):
+        self._cwd = os.getcwd()
+        self._patches: list[tuple[str, object]] = []
+
+    def tearDown(self):
+        os.chdir(self._cwd)
+        for name, original in self._patches:
+            setattr(loop, name, original)
+
+    def _patch(self, name: str, replacement) -> None:
+        self._patches.append((name, getattr(loop, name)))
+        setattr(loop, name, replacement)
+
+    def test_dispatch_stamps_model_effort_gateset_driver_started(self):
+        with integration_workspace() as root:
+            os.chdir(root)
+            _write_verification_yml(root)
+            write_minimal_feature(
+                root, "FEAT-2026-9301", "exec-meta", "feat/exec-meta",
+                [("FEAT-2026-9301/T01", "implementation", "pending")],
+            )
+            self._patch("dispatch", lambda wu, fn, cost_tracking=True: ("(stub)\n", None))
+            self._patch("verify", lambda wu, fd, cfg=None: (True, "(stub)"))
+
+            rc = loop.run(None, dry_run=False)
+            self.assertEqual(rc, 0)
+
+            fdir = root / ".specfuse/features/FEAT-2026-9301-exec-meta"
+            fm = _read_frontmatter(fdir / "WU-T01.md")
+
+            # model = the WU's resolved model (the integration helper authors a
+            # concrete haiku id); effort defaults to EFFORT_BY_TYPE[implementation]
+            # = medium (helper sets no effort); gate_set = GATES_FOR_TYPE = code.
+            self.assertEqual(fm.get("model"), "claude-haiku-4-5-20251001")
+            self.assertEqual(fm.get("effort"), "medium")
+            self.assertEqual(fm.get("gate_set"), "code")
+            self.assertEqual(fm.get("driver_version"), loop.DRIVER_VERSION)
+            # started_at is a UTC ISO timestamp.
+            self.assertIn("started_at", fm)
+            self.assertRegex(fm["started_at"], r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}")
+
+    def test_author_model_effort_override_is_preserved(self):
+        """An explicit model/effort override survives the stamp (same value)."""
+        with integration_workspace() as root:
+            os.chdir(root)
+            _write_verification_yml(root)
+            write_minimal_feature(
+                root, "FEAT-2026-9302", "exec-ovr", "feat/exec-ovr",
+                [("FEAT-2026-9302/T01", "implementation", "pending")],
+            )
+            # Override the helper's default model with an alias + set effort.
+            wu_path = root / ".specfuse/features/FEAT-2026-9302-exec-ovr/WU-T01.md"
+            text = wu_path.read_text()
+            text = text.replace("model: claude-haiku-4-5-20251001\n",
+                                "model: opus\neffort: high\n", 1)
+            wu_path.write_text(text)
+            subprocess.run(["git", "-C", str(root), "add", "."], check=True)
+            subprocess.run(["git", "-C", str(root), "commit", "-q", "-m", "override"],
+                           check=True)
+
+            self._patch("dispatch", lambda wu, fn, cost_tracking=True: ("(stub)\n", None))
+            self._patch("verify", lambda wu, fd, cfg=None: (True, "(stub)"))
+            rc = loop.run(None, dry_run=False)
+            self.assertEqual(rc, 0)
+
+            fm = _read_frontmatter(
+                root / ".specfuse/features/FEAT-2026-9302-exec-ovr/WU-T01.md")
+            self.assertEqual(fm.get("model"), "opus")
+            self.assertEqual(fm.get("effort"), "high")
+
+
+if __name__ == "__main__":
+    unittest.main()

specfuse_loop-0.3.1/specfuse/loop/data/VERSION

@@ -1 +0,0 @@
-0.3.1