specfuse-loop 0.3.10__tar.gz → 0.3.12__tar.gz

{specfuse_loop-0.3.10/specfuse_loop.egg-info → specfuse_loop-0.3.12}/PKG-INFO

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

{specfuse_loop-0.3.10 → specfuse_loop-0.3.12}/pyproject.toml

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

specfuse_loop-0.3.12/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.12

{specfuse_loop-0.3.10 → specfuse_loop-0.3.12}/specfuse/loop/data/docs/concepts/architecture-addendum-gates-and-iterative-planning.md

@@ -24,7 +24,7 @@ implementation feature == a loop feature**: the receiving component's loop decom
 So gates are **internal to the loop**, not orchestrator state. The orchestrator owns
 `initiative → feature` decomposition, cross-repo dependency ordering, and the spec/generated
 interface contracts between features; it does **not** identify gates, run `plan-next`, or hold a
-per-gate `plan_review`. The loop owns all of that, per [`methodology.md`](methodology.md).
+per-gate `plan_review`. The loop owns all of that, per [`methodology.md`](../methodology.md).
 
 **Why Model B (summary).** The loop is single-repo + edit-and-commit; codegen freezes the
 cross-repo interface (generated `emit-*`/`on-*` contracts are immutable `_generated/`), so
@@ -60,7 +60,7 @@ gates were placed in the loop instead.
 
 ## 3. What the loop owns (the gate layer)
 
-Per [`methodology.md`](methodology.md): the gate cycle (plan → execute → close → review&arm), the
+Per [`methodology.md`](../methodology.md): the gate cycle (plan → execute → close → review&arm), the
 four-type closing sequence (`retrospective → lessons → docs → plan-next`), `plan-next` drafting
 the next gate (never arming it), `LEARNINGS.md`, and per-gate autonomy. These are **loop-internal**
 to each dispatched feature; the orchestrator sees only the feature's overall state (via issue

{specfuse_loop-0.3.10 → specfuse_loop-0.3.12}/specfuse/loop/data/docs/concepts/ralph-lineage.md

@@ -50,7 +50,7 @@ independently-adoptable projects live under it:
   for multi-repo, spec-first feature delivery.
 
 The loop and the orchestrator are two execution surfaces of **one** methodology
-(see [`methodology.md`](methodology.md)); they share the gate cycle, the
+(see [`methodology.md`](../methodology.md)); they share the gate cycle, the
 work-unit contract, the correlation-ID scheme, and the verification discipline.
 The loop is the right home for work that lives in one repo or has no formal
 spec; the orchestrator is the right home when the work genuinely spans repos and

{specfuse_loop-0.3.10 → specfuse_loop-0.3.12}/specfuse/loop/data/templates/WU.template.md

@@ -38,7 +38,7 @@ AUTHOR-SET FIELDS — fill or override these at draft/arm time:
 - `produces` — OPTIONAL. File path(s) this WU must produce; machine-enforced by the driver's
   presence gate (FEAT-2026-0022). Lint WARN when absent on `implementation` WUs.
 
-DRIVER-OWNED FIELDS — the driver writes these at outcome time; authors leave them absent:
+DRIVER-OWNED FIELDS - the driver writes these at outcome time; authors leave them absent:
 <!-- 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 -->

{specfuse_loop-0.3.10 → specfuse_loop-0.3.12}/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.10"
+DRIVER_VERSION = "0.3.12"
 # 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
@@ -766,6 +766,84 @@ def _current_branch() -> str:
     return git("branch", "--show-current")
 
 
+def _default_branch() -> "str | None":
+    """The repo's default branch, or None if undeterminable.
+
+    Prefers origin's HEAD symref (`origin/main` -> `main`); falls back to a
+    local `main`/`master` when there is no remote. None when neither resolves —
+    callers then treat the current branch as non-default (auto_sync commits its
+    scaffold sync rather than leaving it dangling).
+    """
+    ref = subprocess.run(
+        ["git", "symbolic-ref", "--short", "refs/remotes/origin/HEAD"],
+        capture_output=True, text=True,
+    )
+    if ref.returncode == 0 and ref.stdout.strip():
+        name = ref.stdout.strip()
+        return name[len("origin/"):] if name.startswith("origin/") else name
+    for cand in ("main", "master"):
+        if subprocess.run(
+            ["git", "rev-parse", "--verify", "--quiet", cand],
+            capture_output=True, text=True,
+        ).returncode == 0:
+            return cand
+    return None
+
+
+# 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
+# overlay set (templates/, rules/, docs/, schemas/) plus the meta files.
+_SCAFFOLD_MANAGED_PREFIXES: tuple[str, ...] = (
+    ".specfuse/templates/", ".specfuse/rules/",
+    ".specfuse/docs/", ".specfuse/schemas/",
+)
+_SCAFFOLD_MANAGED_EXACT: frozenset[str] = frozenset({
+    ".specfuse/VERSION", ".specfuse/.scaffold-manifest",
+    ".specfuse/verification.yml.example",
+})
+
+
+def _is_scaffold_managed(path: str) -> bool:
+    return (path in _SCAFFOLD_MANAGED_EXACT
+            or any(path.startswith(p) for p in _SCAFFOLD_MANAGED_PREFIXES))
+
+
+def _scaffold_managed_dirty() -> set[str]:
+    """Tracked-dirty paths the scaffold overlay owns (subset of the dirty set)."""
+    return {p for p in _tracked_dirty_paths() if _is_scaffold_managed(p)}
+
+
+def _persist_scaffold_sync(installed: str) -> None:
+    """After auto_sync overlays a newer scaffold, keep the tree clean for the
+    rest of the run. On a non-default branch, commit the scaffold-managed
+    changes (`chore(loop): sync scaffold to X.Y.Z`). On the DEFAULT branch, leave
+    them and print guidance — committing scaffold churn onto the default branch
+    is undesirable; --prepare (or the next ensure_feature_branch) carries them
+    onto the feature branch and folds them into its scaffold commit instead.
+    """
+    dirty = _scaffold_managed_dirty()
+    if not dirty:
+        return
+    branch = _current_branch()
+    on_default = (not branch) or branch == _default_branch()
+    if on_default:
+        print(
+            f"auto_sync: scaffold upgraded to {installed}; leaving "
+            f"{len(dirty)} scaffold file(s) uncommitted on default branch "
+            f"'{branch or '(detached)'}'. --prepare will carry them onto the "
+            f"feature branch, or commit them yourself.",
+            file=sys.stderr,
+        )
+        return
+    commit_bookkeeping(sorted(dirty), f"chore(loop): sync scaffold to {installed}")
+    print(
+        f"auto_sync: scaffold upgraded to {installed}; committed "
+        f"{len(dirty)} scaffold file(s) on '{branch}'.",
+        file=sys.stderr,
+    )
+
+
 def _branch_prep_hint(feature_dir: "Path", feat_fm: dict, feature_id: str) -> str:
     """Actionable next-step block for the two pre-flight guards.
 
@@ -920,6 +998,11 @@ def prepare_feature(feat_fm: dict, feature_dir: "Path", feature_id: str) -> None
     for rel in (".specfuse/roadmap.md", ".specfuse/roadmap-archive.md"):
         if (repo_root / rel).exists():
             add_paths.append(str(repo_root / rel))
+    # Fold auto_sync's scaffold overlay into this commit too. On the default
+    # branch auto_sync leaves those uncommitted (see _persist_scaffold_sync);
+    # committing them here lands the upgrade on the feature branch, clean.
+    for rel in sorted(_scaffold_managed_dirty()):
+        add_paths.append(str(repo_root / rel))
     git("add", "--", *add_paths)
     staged = git("status", "--porcelain", "--", *add_paths)
     if staged:
@@ -1006,7 +1089,11 @@ def ensure_feature_branch(feat_fm: dict, feature_dir: "Path | None" = None) -> N
         # Create-from-HEAD carries the working tree onto the new branch. Only
         # the expected /pick-feature flips may ride along; anything else stops.
         dirty = _tracked_dirty_paths()
-        unexpected = dirty - _expected_flip_paths(feature_dir)
+        # Scaffold-overlay files (auto_sync's own upgrade writes) ride along too:
+        # they are driver-owned, and prepare_feature folds them into the scaffold
+        # commit. Only genuinely-unrelated edits remain "unexpected" (#prepare).
+        allowed = _expected_flip_paths(feature_dir) | _scaffold_managed_dirty()
+        unexpected = dirty - allowed
         if unexpected:
             raise FeatureBranchError(
                 "working tree has uncommitted changes to unexpected paths: "
@@ -3112,7 +3199,14 @@ def run(
         # 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)
+            # Genuinely-unrelated dirty paths (not the /pick-feature flips, not
+            # auto_sync's scaffold overlay) still stop --prepare — but with a
+            # clean, actionable message and a non-zero exit, not a traceback.
+            try:
+                prepare_feature(feat_fm, feature_dir, feature_id)
+            except FeatureBranchError as exc:
+                print(f"--prepare cannot proceed:\n{exc}", file=sys.stderr)
+                return 1
         if prepare_only:
             print("Prepared: feature is on its branch and committed. "
                   "Re-run `specfuse-loop` to start the gate.")
@@ -3998,6 +4092,7 @@ def auto_sync(
                 f"WARNING: auto_sync: plugin config drift corrected: {', '.join(changes)}",
                 file=sys.stderr,
             )
+        _persist_scaffold_sync(installed)
         return
 
     # Older with modified files.
@@ -4056,6 +4151,7 @@ def auto_sync(
                 f"WARNING: auto_sync: plugin config drift corrected: {', '.join(changes)}",
                 file=sys.stderr,
             )
+        _persist_scaffold_sync(installed)
     else:
         # Non-interactive (CI / claude -p): skip modified files + warn; never block.
         print(
@@ -4092,6 +4188,7 @@ def auto_sync(
                 f"WARNING: auto_sync: plugin config drift corrected: {', '.join(changes)}",
                 file=sys.stderr,
             )
+        _persist_scaffold_sync(installed)
 
 
 def main() -> int:

{specfuse_loop-0.3.10 → specfuse_loop-0.3.12/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.3.10 → specfuse_loop-0.3.12}/specfuse_loop.egg-info/SOURCES.txt

@@ -112,12 +112,14 @@ tests/test_miniyaml_equivalence.py
 tests/test_miniyaml_negative.py
 tests/test_planned_cost_lint.py
 tests/test_prepare_feature.py
+tests/test_prepare_scaffold_sync.py
 tests/test_produces_field.py
 tests/test_result_block.py
 tests/test_roadmap_add_skill.py
 tests/test_roadmap_archive_skill.py
 tests/test_roadmap_row_parser.py
 tests/test_scaffold_data_in_sync.py
+tests/test_scaffold_doc_hygiene.py
 tests/test_scaffold_docs.py
 tests/test_scaffold_init.py
 tests/test_scaffold_manifest.py

specfuse_loop-0.3.12/tests/test_prepare_scaffold_sync.py

@@ -0,0 +1,172 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""auto_sync's scaffold upgrade must not poison the same run's --prepare.
+
+Before this fix, `specfuse-loop --prepare` crashed with a traceback: auto_sync
+overlays the new scaffold (dirtying .specfuse/VERSION, .scaffold-manifest,
+docs/, templates/) and leaves it uncommitted, then ensure_feature_branch
+refuses to carry those "unexpected" paths onto the new feature branch.
+
+The graceful behavior pinned here:
+
+  1. auto_sync COMMITS its own scaffold overlay on a non-default branch
+     (`chore(loop): sync scaffold to X.Y.Z`) so the tree is clean; on the
+     DEFAULT branch it leaves them + prints guidance (--prepare carries them).
+  2. ensure_feature_branch CARRIES scaffold-managed dirty paths onto a new
+     branch instead of refusing — but still blocks genuinely-unrelated edits.
+  3. prepare_feature FOLDS the scaffold-managed paths into its scaffold commit
+     (so the default-branch case lands them committed on the feature branch).
+"""
+
+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():
+    """Temp git repo on `main`, one commit, a tracked scaffold template."""
+    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")
+        tmpl = root / ".specfuse/templates/WU.template.md"
+        tmpl.parent.mkdir(parents=True)
+        tmpl.write_text("old template\n")
+        (root / ".specfuse/VERSION").write_text("0.3.0\n")
+        (root / "README.md").write_text("# fixture\n")
+        _git(root, "add", ".")
+        _git(root, "commit", "-q", "-m", "init")
+        yield root
+
+
+def _dirty_scaffold(root: Path) -> None:
+    """Simulate auto_sync's overlay: modify tracked scaffold files."""
+    (root / ".specfuse/templates/WU.template.md").write_text("new template\n")
+    (root / ".specfuse/VERSION").write_text("0.3.11\n")
+
+
+class TestDefaultBranch(unittest.TestCase):
+    def test_local_main_detected(self):
+        with _repo() as root, _chdir(root):
+            self.assertEqual(loop._default_branch(), "main")
+
+
+class TestScaffoldManagedDirty(unittest.TestCase):
+    def test_classifies_scaffold_vs_user_paths(self):
+        with _repo() as root:
+            _dirty_scaffold(root)
+            (root / "README.md").write_text("# edited\n")  # user edit
+            with _chdir(root):
+                managed = loop._scaffold_managed_dirty()
+        self.assertIn(".specfuse/templates/WU.template.md", managed)
+        self.assertIn(".specfuse/VERSION", managed)
+        self.assertNotIn("README.md", managed)
+
+
+class TestPersistScaffoldSync(unittest.TestCase):
+    def test_commits_on_feature_branch(self):
+        with _repo() as root:
+            _git(root, "checkout", "-q", "-b", "feat/x")
+            _dirty_scaffold(root)
+            with _chdir(root):
+                loop._persist_scaffold_sync("0.3.11")
+                dirty = loop._tracked_dirty_paths()
+            self.assertEqual(dirty, set(), "scaffold sync must be committed")
+            self.assertIn("sync scaffold to 0.3.11",
+                          _git(root, "log", "-1", "--pretty=%s"))
+
+    def test_guides_and_leaves_on_default_branch(self):
+        with _repo() as root:  # on main == default
+            _dirty_scaffold(root)
+            with _chdir(root):
+                loop._persist_scaffold_sync("0.3.11")
+                dirty = loop._tracked_dirty_paths()
+            # left uncommitted (no surprise commit on the default branch)
+            self.assertIn(".specfuse/VERSION", dirty)
+            self.assertEqual("init", _git(root, "log", "-1", "--pretty=%s"))
+
+
+class TestEnsureFeatureBranchCarriesScaffold(unittest.TestCase):
+    def test_scaffold_paths_carry_onto_new_branch(self):
+        with _repo() as root:
+            _dirty_scaffold(root)
+            with _chdir(root):
+                loop.ensure_feature_branch({"branch": "feat/y"})
+                current = _git(root, "branch", "--show-current")
+            self.assertEqual(current, "feat/y")
+            self.assertEqual(
+                (root / ".specfuse/templates/WU.template.md").read_text(),
+                "new template\n",
+            )
+
+    def test_unexpected_edit_still_blocks_even_with_scaffold_dirty(self):
+        with _repo() as root:
+            _commit = root / "src/app.py"
+            _commit.parent.mkdir()
+            _commit.write_text("x = 1\n")
+            _git(root, "add", ".")
+            _git(root, "commit", "-q", "-m", "app")
+            _dirty_scaffold(root)
+            (root / "src/app.py").write_text("x = 2\n")  # unrelated edit
+            with _chdir(root):
+                with self.assertRaises(loop.FeatureBranchError) as ctx:
+                    loop.ensure_feature_branch({"branch": "feat/z"})
+            self.assertIn("src/app.py", str(ctx.exception))
+
+
+class TestPrepareFoldsScaffold(unittest.TestCase):
+    def test_default_branch_scaffold_folds_into_prepare_commit(self):
+        with _repo() as root:  # on main == default
+            feat_dir = root / ".specfuse/features/FEAT-2026-0099-x"
+            feat_dir.mkdir(parents=True)
+            (feat_dir / "PLAN.md").write_text("branch: feat/FEAT-2026-0099-x\n")
+            _dirty_scaffold(root)  # auto_sync left these on default branch
+            with _chdir(root):
+                loop.prepare_feature(
+                    {"branch": "feat/FEAT-2026-0099-x"}, feat_dir,
+                    "FEAT-2026-0099",
+                )
+                dirty = loop._tracked_dirty_paths()
+                current = _git(root, "branch", "--show-current")
+            self.assertEqual(current, "feat/FEAT-2026-0099-x")
+            self.assertEqual(dirty, set(), "scaffold + folder must be committed")
+            # scaffold file is committed on the feature branch
+            self.assertEqual(
+                _git(root, "show", "HEAD:.specfuse/templates/WU.template.md"),
+                "new template",
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

specfuse_loop-0.3.12/tests/test_scaffold_doc_hygiene.py

@@ -0,0 +1,79 @@
+#
+# Copyright 2026 Specfuse Contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""Issue #140 — vendored scaffold docs/templates must not carry defects that
+trip Markdown inspections downstream.
+
+Two genuine defects were observed in a freshly-initialized project:
+
+1. Broken relative links to `methodology.md` from `docs/concepts/*.md`: the
+   link uses a same-directory path but `methodology.md` lives one level up in
+   `docs/`. Correct target is `../methodology.md`.
+2. A "Bad character" parse error on the em-dash (U+2014) leading the inline
+   text of the `DRIVER-OWNED FIELDS` paragraph in `WU.template.md`.
+
+These guards run against the CANONICAL sources (`docs/`, `.specfuse/`); the
+byte-match drift guard in test_scaffold_data_in_sync.py keeps the vendored
+`specfuse/loop/data/` copies in lockstep, so fixing the canonicals + re-vendoring
+propagates the fix everywhere.
+"""
+
+from __future__ import annotations
+
+import pathlib
+import re
+import unittest
+
+REPO_ROOT = pathlib.Path(__file__).parent.parent
+DOCS = REPO_ROOT / "docs"
+WU_TEMPLATE = REPO_ROOT / ".specfuse" / "templates" / "WU.template.md"
+
+# Markdown inline link with a relative path target (skips absolute URLs and
+# pure-anchor links). Captures the path portion, dropping any `#anchor`.
+_LINK_RE = re.compile(r"\]\((?!https?://)([^)#][^)]*?)(?:#[^)]*)?\)")
+EM_DASH = "—"
+
+
+class TestScaffoldDocHygiene(unittest.TestCase):
+
+    def test_docs_relative_md_links_resolve(self):
+        """Every relative .md link in docs/ must resolve to an existing file
+        from the linking file's own directory (issue #140 defect 1)."""
+        broken: list[str] = []
+        for md in sorted(DOCS.rglob("*.md")):
+            for lineno, line in enumerate(
+                md.read_text(encoding="utf-8").splitlines(), start=1
+            ):
+                for target in _LINK_RE.findall(line):
+                    if not target.endswith(".md"):
+                        continue
+                    resolved = (md.parent / target).resolve()
+                    if not resolved.is_file():
+                        rel = md.relative_to(REPO_ROOT)
+                        broken.append(f"{rel}:{lineno} -> {target}")
+        self.assertEqual(
+            [], broken,
+            "broken relative .md links in docs/ (fix the path):\n"
+            + "\n".join(broken),
+        )
+
+    def test_wu_template_driver_owned_line_has_no_em_dash(self):
+        """The DRIVER-OWNED FIELDS paragraph must not carry the U+2014 em-dash
+        that IntelliJ flags as a Bad character (issue #140 defect 2)."""
+        matches = [
+            line
+            for line in WU_TEMPLATE.read_text(encoding="utf-8").splitlines()
+            if line.startswith("DRIVER-OWNED FIELDS")
+        ]
+        self.assertTrue(matches, "DRIVER-OWNED FIELDS line not found in template")
+        for line in matches:
+            self.assertNotIn(
+                EM_DASH, line,
+                "DRIVER-OWNED FIELDS line still contains the U+2014 em-dash "
+                "that trips the Markdown parser — use ' - ' instead",
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

specfuse_loop-0.3.10/specfuse/loop/data/VERSION

@@ -1 +0,0 @@
-0.3.10