specfuse-loop 0.3.13__tar.gz → 0.3.14__tar.gz

{specfuse_loop-0.3.13/specfuse_loop.egg-info → specfuse_loop-0.3.14}/PKG-INFO

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

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14}/pyproject.toml

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

specfuse_loop-0.3.14/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.14

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14}/specfuse/loop/gh_backend.py

@@ -13,9 +13,14 @@ from typing import Callable, Optional
 from . import loop as _loop
 
 
-def _default_runner(args: list) -> None:
-    """Shell out to gh with the given argument list. Not called in tests."""
-    subprocess.run(args, check=True, capture_output=True, text=True)
+def _default_runner(args: list, check: bool = True):
+    """Shell out to gh with the given argument list. Not called in tests.
+
+    Returns the completed process so probing callers (e.g. the `gh pr view`
+    idempotency check) can inspect `.returncode` without raising; side-effecting
+    callers pass no `check` override and get the prior raise-on-failure behavior.
+    """
+    return subprocess.run(args, check=check, capture_output=True, text=True)
 
 
 class GitHubBackend(_loop.Backend):
@@ -55,9 +60,9 @@ class GitHubBackend(_loop.Backend):
         title = feat_fm.get("title", feature_id)
 
         # Idempotent: skip PR creation if one already exists for this branch.
-        check = subprocess.run(
+        check = self._runner(
             ["gh", "pr", "view", branch, "--repo", self.repo, "--json", "number"],
-            capture_output=True, text=True,
+            check=False,
         )
         if check.returncode != 0:
             body = (
@@ -70,7 +75,7 @@ class GitHubBackend(_loop.Backend):
                 "gh", "pr", "create",
                 "--title", f"[{feature_id}] {title}",
                 "--body", body,
-                "--base", "main",
+                "--base", _loop.resolve_base(feat_fm),
                 "--head", branch,
             ])
 

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14}/specfuse/loop/lint_plan.py

@@ -249,6 +249,15 @@ def lint(feature_dir: Path) -> list[str]:
     if missing:
         errs.append(f"PLAN.md frontmatter missing keys: {sorted(missing)}")
 
+    if "base" in fm:
+        base_val = fm["base"]
+        feature_id_val = fm.get("feature_id", feature_dir.name)
+        if not isinstance(base_val, str) or not base_val.strip():
+            errs.append(
+                f"{feature_id_val}: PLAN.md frontmatter 'base' key is present but "
+                f"empty/whitespace-only/non-string: {base_val!r}"
+            )
+
     graph = _find_task_graph_block(body)
     if graph is None:
         return errs + ["PLAN.md has no ```yaml graph block"]

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14}/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.13"
+DRIVER_VERSION = "0.3.14"
 # 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
@@ -719,14 +719,34 @@ class FeatureBranchError(RuntimeError):
     """
 
 
+def untracked_paths() -> set[str]:
+    """Repo-relative paths git reports as untracked, honoring .gitignore.
+
+    Snapshotted per-WU immediately before dispatch so `squash_commit` can tell
+    "the operator already had this file" from "this run created it" — only the
+    latter belongs in the WU's commit. See issue #150 and `squash_commit`.
+    """
+    out = subprocess.run(
+        ["git", "ls-files", "--others", "--exclude-standard"],
+        capture_output=True, text=True, check=True,
+    ).stdout
+    return {line.strip() for line in out.splitlines() if line.strip()}
+
+
 def _tracked_dirty_paths() -> set[str]:
     """Paths with TRACKED, uncommitted changes (staged or unstaged), repo-relative.
 
     Untracked files (porcelain `??`) are excluded: they never block a create
-    (`checkout -B`) and carry harmlessly, so counting them would spuriously
-    flag a leftover events.jsonl as an "unexpected" change. The dirty-tree
-    failure in #48 is tracked local modifications ("your local changes would
-    be overwritten by checkout"), which is exactly what this set captures.
+    (`checkout -B`), so counting them would spuriously flag a leftover
+    events.jsonl as an "unexpected" change. The dirty-tree failure in #48 is
+    tracked local modifications ("your local changes would be overwritten by
+    checkout"), which is exactly what this set captures.
+
+    This exclusion means untracked files DO carry onto a freshly created feature
+    branch. That is safe only because `squash_commit` refuses to stage untracked
+    paths that pre-date the WU's dispatch (#150) — before that fix, its
+    `git add -A` committed them, so this guard was strictly narrower than the
+    commit that followed it.
     """
     out = subprocess.run(
         ["git", "status", "--porcelain"],
@@ -790,6 +810,78 @@ def _default_branch() -> "str | None":
     return None
 
 
+def resolve_base(feat_fm: dict) -> "str | None":
+    """The ref a feature's branch/PR should sit on top of.
+
+    Frontmatter `base` wins when set and non-empty (after stripping
+    whitespace). Absent, empty, or whitespace-only falls back to
+    `_default_branch()`; if that too is undeterminable, falls back to the
+    current branch. Callers (T02, T03) are responsible for wiring this in —
+    this function only resolves the name, it does not touch git state.
+    """
+    base = feat_fm.get("base")
+    if isinstance(base, str) and base.strip():
+        return base.strip()
+    default = _default_branch()
+    if default:
+        return default
+    return _current_branch()
+
+
+class BaseBranchError(RuntimeError):
+    """Raised when a feature's declared `base` ref cannot be made available.
+
+    Carries an actionable, human-readable message distinguishing a probable
+    typo (remote confirms the ref does not exist) from an unreachable remote
+    (network/auth failure — the ref's existence is simply unknown), so the two
+    cases are never mistaken for each other.
+    """
+
+
+def ensure_base_ref(base: str) -> None:
+    """Make sure git ref *base* is resolvable locally, fetching it if needed.
+
+    No-ops (no network call) when `git rev-parse --verify base` already
+    succeeds locally. Otherwise asks origin via `git ls-remote --exit-code`:
+    if origin has it, fetches it and prints one line naming what and why; if
+    origin explicitly does not have it, raises BaseBranchError naming likely
+    local-branch candidates (probable typo); if ls-remote itself fails
+    (offline/auth), raises a distinctly-worded BaseBranchError instead of
+    conflating "does not exist" with "could not check".
+    """
+    local = subprocess.run(
+        ["git", "rev-parse", "--verify", base],
+        capture_output=True, text=True,
+    )
+    if local.returncode == 0:
+        return
+    remote = subprocess.run(
+        ["git", "ls-remote", "--exit-code", "origin", base],
+        capture_output=True, text=True,
+    )
+    if remote.returncode == 0:
+        subprocess.run(["git", "fetch", "origin", base], capture_output=True, text=True, check=True)
+        print(f"ensure_base_ref: fetched '{base}' from origin (declared feature base, not present locally).")
+        return
+    if remote.returncode == 2:
+        # ls-remote's documented exit code for "ref not found on that remote".
+        branches = subprocess.run(
+            ["git", "branch", "--list", "--format=%(refname:short)"],
+            capture_output=True, text=True,
+        ).stdout.splitlines()
+        candidates = [b.strip() for b in branches if b.strip()]
+        listed = ", ".join(sorted(candidates)) if candidates else "(no local branches)"
+        raise BaseBranchError(
+            f"base '{base}' does not exist locally or on origin — probable typo. "
+            f"Local branches: {listed}"
+        )
+    stderr = remote.stderr.strip() or remote.stdout.strip() or "(no git output)"
+    raise BaseBranchError(
+        f"base '{base}' could not be verified against origin — remote unreachable "
+        f"(offline or auth failure), not confirmed missing: {stderr}"
+    )
+
+
 # Paths the scaffold overlay owns — auto_sync writes these on upgrade. They are
 # the driver's, not the user's edits: they may carry onto a feature branch and
 # are folded into the --prepare scaffold commit. Mirrors scaffold.py's versioned
@@ -1059,34 +1151,41 @@ def ensure_feature_branch(feat_fm: dict, feature_dir: "Path | None" = None) -> N
     ).stdout.strip()
     if current == branch:
         return
+    # A declared `base` (T01's resolve_base/ensure_base_ref) is the branch's
+    # true starting point, not wherever HEAD happens to be standing. Resolving
+    # and fetching it here — before any checkout — lets both branch creation
+    # and the staleness check below anchor on the base instead of HEAD.
+    # BaseBranchError is intentionally left to propagate uncaught: the base
+    # cause must reach the operator, not be reshaped into a FeatureBranchError.
+    base = resolve_base(feat_fm)
+    if base:
+        ensure_base_ref(base)
+    else:
+        base = current
     exists = subprocess.run(
         ["git", "rev-parse", "--verify", branch],
         capture_output=True, text=True,
     ).returncode == 0
     if exists:
-        # Surface a stale branch that diverged from the current base instead of
-        # silently reusing it. `merge-base --is-ancestor B HEAD` exits 0 iff B
-        # is an ancestor of HEAD (i.e. HEAD already contains B — safe to reuse).
+        # Surface a stale branch that diverged from the declared base instead
+        # of silently reusing it. `merge-base --is-ancestor B <base>` exits 0
+        # iff B is an ancestor of base (i.e. base already contains B — safe).
         is_ancestor = subprocess.run(
-            ["git", "merge-base", "--is-ancestor", branch, "HEAD"],
+            ["git", "merge-base", "--is-ancestor", branch, base],
             capture_output=True, text=True,
         ).returncode == 0
         if not is_ancestor:
             raise FeatureBranchError(
-                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)"
+                f"branch '{branch}' has diverged from '{base}' — it carries "
+                f"commits '{base}' does not, likely because it was created "
+                f"from a different starting point or '{base}' has since moved "
+                f"on. The safe action is to bring it up to date with the base:\n"
+                f"  git checkout {branch} && git rebase {base}"
             )
         _checked_checkout(["checkout", branch], f"checkout of existing branch '{branch}'")
         print(f"Switched to feature branch '{branch}' (was on '{current}').")
     else:
-        # Create-from-HEAD carries the working tree onto the new branch. Only
+        # Create-from-base carries the working tree onto the new branch. Only
         # the expected /pick-feature flips may ride along; anything else stops.
         dirty = _tracked_dirty_paths()
         # Scaffold-overlay files (auto_sync's own upgrade writes) ride along too:
@@ -1101,8 +1200,8 @@ def ensure_feature_branch(feat_fm: dict, feature_dir: "Path | None" = None) -> N
                 + f". Refusing to carry them onto new branch '{branch}'. "
                 "Commit or stash them first, then re-run."
             )
-        _checked_checkout(["checkout", "-B", branch], f"create of branch '{branch}'")
-        print(f"Created feature branch '{branch}' from '{current}'.")
+        _checked_checkout(["checkout", "-B", branch, base], f"create of branch '{branch}'")
+        print(f"Created feature branch '{branch}' from '{base}'.")
 
 
 def acquire_tree_lock(specfuse_dir: Path):
@@ -1344,12 +1443,38 @@ class SquashCommitError(RuntimeError):
     """
 
 
-def squash_commit(wu: WorkUnit, head_before: str) -> str | None:
+def squash_commit(
+    wu: WorkUnit,
+    head_before: str,
+    untracked_before: "set[str] | frozenset[str]" = frozenset(),
+) -> str | None:
+    """Squash the WU's work into one commit; return its sha, or None if nothing.
+
+    `untracked_before` is the set of untracked paths captured immediately before
+    this WU was dispatched (see `untracked_paths`). Those are the operator's —
+    scratch notes, another harness's config, a local script — and are unstaged
+    after `add -A` so they are not absorbed into the WU's commit (#150). Files
+    the run itself created are still committed: the distinction is "did this
+    dispatch create it", not "is it tracked".
+
+    Callers that omit the snapshot keep the legacy stage-everything behavior.
+    """
     if git("rev-parse", "HEAD") != head_before:
         git("reset", "--soft", head_before)  # fold away any commits the agent made
     if not git("status", "--porcelain"):
         return None
     git("add", "-A")
+    if untracked_before:
+        # Unstage the operator's pre-existing untracked files. Paths the agent
+        # deleted during dispatch are skipped — `git reset -- <missing>` is fine,
+        # but pathspec-matching nothing errors on some git versions.
+        stale = sorted(p for p in untracked_before if Path(p).exists())
+        if stale:
+            git("reset", "-q", "--", *stale)
+        # `add -A` may have had nothing else to stage: a WU whose only tree
+        # change was the operator's WIP must not manufacture a commit from it.
+        if not git("diff", "--cached", "--name-only"):
+            return None
     msg = f"feat: {wu.title}\n\nFeature: {wu.wu_id}"
     res = subprocess.run(
         ["git", "commit", "-m", msg], capture_output=True, text=True,
@@ -3414,6 +3539,11 @@ def run(
                     # Fall through to existing close-WU dispatch path
 
                 head_before = git("rev-parse", "HEAD")
+                # Snapshot the operator's untracked files alongside head_before:
+                # squash_commit must not absorb WIP that pre-dates this dispatch
+                # (#150). Captured here, not inside squash_commit, because by
+                # then the agent's own new files are indistinguishable from it.
+                untracked_before = untracked_paths()
                 _is_rearm = detect_rearm_dispatch(wu)
                 if _is_rearm:
                     fold_cumulative_on_rearm(wu, backend)
@@ -3553,7 +3683,8 @@ def run(
                         backend.set_wu(wu, "status", DONE)
                         write_cost_to_wu(backend, wu, cum_usage)
                         try:
-                            sha = squash_commit(wu, head_before)
+                            sha = squash_commit(wu, head_before,
+                                                untracked_before=untracked_before)
                         except SquashCommitError as exc:
                             # The squash commit was rejected (typically a
                             # pre-commit hook). Treat as a failed attempt rather

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14}/specfuse_loop.egg-info/SOURCES.txt

@@ -62,6 +62,7 @@ tests/test_driver_lock.py
 tests/test_duration_tracking.py
 tests/test_empty_files_escalation.py
 tests/test_ensure_feature_branch.py
+tests/test_ensure_feature_branch_base.py
 tests/test_events_redaction.py
 tests/test_extra_gates.py
 tests/test_force_full_close.py
@@ -115,6 +116,7 @@ tests/test_planned_cost_lint.py
 tests/test_prepare_feature.py
 tests/test_prepare_scaffold_sync.py
 tests/test_produces_field.py
+tests/test_resolve_base.py
 tests/test_result_block.py
 tests/test_roadmap_add_skill.py
 tests/test_roadmap_archive_skill.py
@@ -134,6 +136,7 @@ tests/test_template_closing_shapes.py
 tests/test_terminal_flip_ownership.py
 tests/test_terminal_flips.py
 tests/test_untracked_feature_folder.py
+tests/test_untracked_file_absorption.py
 tests/test_upgrade_integration.py
 tests/test_upgrade_merge_gate.py
 tests/test_validate_event.py

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14}/tests/test_backend.py

@@ -17,7 +17,7 @@ import unittest
 from pathlib import Path
 
 from tests._loop_loader import load_loop
-from tests._workspace import integration_workspace
+from tests._workspace import integration_workspace, with_deliverable
 
 loop = load_loop()
 
@@ -154,6 +154,11 @@ class TestBackendLifecycleIntegration(unittest.TestCase):
 
     def _patch(self, name: str, replacement):
         self._patches.append((name, getattr(loop, name)))
+        # Dispatch stubs must write a deliverable or the presence gate
+        # (FEAT-2026-0022) rejects the WU as hollow. See #150 —
+        # `.specfuse/.loop.lock` used to stand in as the deliverable.
+        if name == "dispatch":
+            replacement = with_deliverable(replacement)
         setattr(loop, name, replacement)
 
     def test_on_feature_start_fires_before_dispatch_on_blocked_run(self):

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14}/tests/test_cost_tracking.py

@@ -22,6 +22,7 @@ import unittest
 from pathlib import Path
 
 from tests._loop_loader import load_loop
+from tests._workspace import with_deliverable
 from tests.test_driver_integration import (
     integration_workspace,
     write_minimal_feature,
@@ -125,6 +126,11 @@ class TestCostTrackingIntegration(unittest.TestCase):
 
     def _patch(self, name: str, replacement):
         self._patches.append((name, getattr(loop, name)))
+        # Dispatch stubs must write a deliverable or the presence gate
+        # (FEAT-2026-0022) rejects the WU as hollow. See #150 —
+        # `.specfuse/.loop.lock` used to stand in as the deliverable.
+        if name == "dispatch":
+            replacement = with_deliverable(replacement)
         setattr(loop, name, replacement)
 
     def test_enabled_writes_cost_to_wu_frontmatter_and_events(self):

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14}/tests/test_driver_integration.py

@@ -26,7 +26,7 @@ import unittest
 from pathlib import Path
 
 from tests._loop_loader import load_loop
-from tests._workspace import integration_workspace
+from tests._workspace import integration_workspace, with_deliverable
 
 loop = load_loop()
 
@@ -90,6 +90,13 @@ gates:
             f"---\nid: {wu_id}\ntype: {wu_type}\nmodel: claude-haiku-4-5-20251001\n"
             f"status: {wu_status}\nattempts: 0\n---\n\n# {tnn}{body}"
         )
+    # Mirror the real repo's .gitignore for driver-owned runtime files. Without
+    # this the fixture repo leaves `.specfuse/.loop.lock` untracked, and before
+    # #150 `squash_commit`'s `git add -A` committed it — where it silently
+    # satisfied the deliverable-presence guard for stub dispatches that write
+    # nothing. The lock file is not a deliverable; the real .gitignore has always
+    # excluded it, so the fixture models reality by doing the same.
+    (root / ".gitignore").write_text(".specfuse/.loop.lock\n")
     # Stage and commit the scaffold so the driver starts from a clean tree.
     subprocess.run(["git", "-C", str(root), "add", "."], check=True)
     subprocess.run(["git", "-C", str(root), "commit", "-q", "-m",
@@ -147,6 +154,11 @@ class TestBug1StatusFlipSurvivesReset(unittest.TestCase):
 
     def _patch(self, name: str, replacement):
         self._patches.append((name, getattr(loop, name)))
+        # Dispatch stubs must write a deliverable or the presence gate
+        # (FEAT-2026-0022) rejects the WU as hollow. See #150 —
+        # `.specfuse/.loop.lock` used to stand in as the deliverable.
+        if name == "dispatch":
+            replacement = with_deliverable(replacement)
         setattr(loop, name, replacement)
 
     def test_passed_then_blocked_flips_persist(self):
@@ -253,6 +265,11 @@ class TestBug2FeatureBranchCheckout(unittest.TestCase):
 
     def _patch(self, name: str, replacement):
         self._patches.append((name, getattr(loop, name)))
+        # Dispatch stubs must write a deliverable or the presence gate
+        # (FEAT-2026-0022) rejects the WU as hollow. See #150 —
+        # `.specfuse/.loop.lock` used to stand in as the deliverable.
+        if name == "dispatch":
+            replacement = with_deliverable(replacement)
         setattr(loop, name, replacement)
 
     def test_driver_switches_to_declared_branch(self):

{specfuse_loop-0.3.13 → specfuse_loop-0.3.14}/tests/test_duration_tracking.py

@@ -20,6 +20,7 @@ import os
 import unittest
 
 from tests._loop_loader import load_loop
+from tests._workspace import with_deliverable
 from tests.test_driver_integration import (
     integration_workspace,
     write_minimal_feature,
@@ -44,6 +45,11 @@ class TestDurationTracking(unittest.TestCase):
 
     def _patch(self, name: str, replacement):
         self._patches.append((name, getattr(loop, name)))
+        # Dispatch stubs must write a deliverable or the presence gate
+        # (FEAT-2026-0022) rejects the WU as hollow. See #150 —
+        # `.specfuse/.loop.lock` used to stand in as the deliverable.
+        if name == "dispatch":
+            replacement = with_deliverable(replacement)
         setattr(loop, name, replacement)
 
     # ------------------------------------------------------------------ #

specfuse_loop-0.3.14/tests/test_ensure_feature_branch_base.py

@@ -0,0 +1,159 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""ensure_feature_branch cut from the resolved base (FEAT-2026-0031/T02).
+
+Before this WU, ensure_feature_branch always created and staleness-checked
+branches against HEAD/the current branch. With a declared `base` in PLAN.md
+frontmatter, that is wrong: the feature branch must be cut from the declared
+base (via resolve_base/ensure_base_ref, T01), and the staleness guard must
+measure divergence against that base — not against wherever the operator
+happens to be standing. These tests use real git in a tmpdir; no mocking.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import unittest
+from contextlib import contextmanager
+from pathlib import Path
+from tempfile import TemporaryDirectory
+
+from tests._loop_loader import load_loop
+
+loop = load_loop()
+
+
+def _git(root: Path, *args: str) -> str:
+    return subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True, text=True, check=True,
+    ).stdout.strip()
+
+
+@contextmanager
+def _chdir(path: Path):
+    prev = Path.cwd()
+    os.chdir(path)
+    try:
+        yield
+    finally:
+        os.chdir(prev)
+
+
+@contextmanager
+def _repo_no_remote():
+    """A temp git repo on `main` with one commit, no origin configured."""
+    with TemporaryDirectory(ignore_cleanup_errors=True) as tmp:
+        root = Path(tmp)
+        subprocess.run(["git", "init", "-q", "-b", "main", str(root)], check=True)
+        _git(root, "config", "user.email", "test@example.com")
+        _git(root, "config", "user.name", "Test")
+        _git(root, "config", "commit.gpgSign", "false")
+        (root / "README.md").write_text("# fixture\n")
+        _git(root, "add", ".")
+        _git(root, "commit", "-q", "-m", "init")
+        yield root
+
+
+def _commit_file(root: Path, rel: str, content: str, msg: str) -> None:
+    p = root / rel
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(content)
+    _git(root, "add", rel)
+    _git(root, "commit", "-q", "-m", msg)
+
+
+class TestEnsureFeatureBranchBase(unittest.TestCase):
+    # AC 1/4/12 — RED on HEAD (resolve_base/ensure_base_ref not wired in yet):
+    # with `base: release/2.0` declared and HEAD standing on `main`, the
+    # created feature branch must be cut from release/2.0, not from HEAD/main.
+    def test_branch_is_cut_from_declared_base(self):
+        with _repo_no_remote() as root:
+            _git(root, "checkout", "-q", "-b", "release/2.0")
+            _commit_file(root, "release_only.txt", "1\n", "release-only commit")
+            release_tip = _git(root, "rev-parse", "release/2.0")
+
+            _git(root, "checkout", "-q", "main")
+            _commit_file(root, "main_only.txt", "1\n", "main-only commit")
+
+            with _chdir(root):
+                loop.ensure_feature_branch({"branch": "feat/x", "base": "release/2.0"})
+                current = _git(root, "branch", "--show-current")
+                merge_base = _git(root, "merge-base", "feat/x", "release/2.0")
+
+            self.assertEqual(current, "feat/x")
+            self.assertEqual(merge_base, release_tip)
+
+    # AC 6 — no-regression path: a feature with no `base` key still resolves
+    # via _default_branch() and is cut from the default branch (main).
+    def test_no_base_key_still_cuts_from_default_branch(self):
+        with _repo_no_remote() as root:
+            main_tip = _git(root, "rev-parse", "main")
+
+            with _chdir(root):
+                loop.ensure_feature_branch({"branch": "feat/no-base"})
+                current = _git(root, "branch", "--show-current")
+                merge_base = _git(root, "merge-base", "feat/no-base", "main")
+
+            self.assertEqual(current, "feat/no-base")
+            self.assertEqual(merge_base, main_tip)
+
+    # AC 5/7/8/9/10 — staleness guard re-anchored to the resolved base: a
+    # branch that diverges from the declared base (even while being an
+    # ancestor of HEAD) is surfaced with an operator-readable message that
+    # names the branch and base, offers the rebase-onto-base hint, and never
+    # offers `git branch -D`.
+    def test_stale_branch_surfaced_against_base_not_head(self):
+        with _repo_no_remote() as root:
+            _git(root, "checkout", "-q", "-b", "release/2.0")
+            _commit_file(root, "release_only.txt", "1\n", "release-only commit")
+
+            _git(root, "checkout", "-q", "main")
+            _git(root, "checkout", "-q", "-b", "feat/x")
+            _commit_file(root, "feat_only.txt", "1\n", "feat-only commit")
+            _git(root, "checkout", "-q", "main")
+
+            with _chdir(root):
+                with self.assertRaises(loop.FeatureBranchError) as ctx:
+                    loop.ensure_feature_branch({"branch": "feat/x", "base": "release/2.0"})
+                current = _git(root, "branch", "--show-current")
+
+            self.assertEqual(current, "main")  # not silently switched
+            msg = str(ctx.exception)
+            self.assertIn("feat/x", msg)
+            self.assertIn("release/2.0", msg)
+            self.assertIn("git rebase release/2.0", msg)
+            self.assertNotIn("-D", msg)
+
+    # AC 11 — regression: the dirty-tree allowlist (_expected_flip_paths |
+    # _scaffold_managed_dirty) is unchanged; unexpected tracked edits still
+    # block branch creation even with a declared base.
+    def test_unexpected_dirty_paths_still_block_with_base(self):
+        with _repo_no_remote() as root:
+            _git(root, "checkout", "-q", "-b", "release/2.0")
+            _git(root, "checkout", "-q", "main")
+            _commit_file(root, "src/app.py", "x = 1\n", "app")
+            (root / "src/app.py").write_text("x = 2\n")
+
+            with _chdir(root):
+                with self.assertRaises(loop.FeatureBranchError) as ctx:
+                    loop.ensure_feature_branch({"branch": "feat/x", "base": "release/2.0"})
+                exists = subprocess.run(
+                    ["git", "rev-parse", "--verify", "feat/x"],
+                    capture_output=True, text=True,
+                ).returncode == 0
+
+            self.assertFalse(exists)
+            self.assertIn("src/app.py", str(ctx.exception))
+
+    # AC 13 — a BaseBranchError raised by ensure_base_ref (declared base does
+    # not exist, no origin to check it against) propagates unchanged, not
+    # reshaped into a FeatureBranchError.
+    def test_base_branch_error_propagates_unwrapped(self):
+        with _repo_no_remote() as root:
+            with _chdir(root):
+                with self.assertRaises(loop.BaseBranchError):
+                    loop.ensure_feature_branch({"branch": "feat/x", "base": "nonexistent/base"})