specfuse-loop 0.3.16__tar.gz → 0.3.18__tar.gz

{specfuse_loop-0.3.16/specfuse_loop.egg-info → specfuse_loop-0.3.18}/PKG-INFO

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

{specfuse_loop-0.3.16 → specfuse_loop-0.3.18}/pyproject.toml

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

{specfuse_loop-0.3.16 → specfuse_loop-0.3.18}/specfuse/loop/_miniyaml.py

@@ -53,7 +53,9 @@ on a missing gate set — silent misparses are worse than crashes.
         fields that the driver writes to WU frontmatter.
       - **booleans** — exact lowercase `true` / `false` only. `True`, `yes`,
         `on`, etc. are errors.
-      - **empty value** — a key followed by `:` with nothing after is `None`.
+      - **empty value / explicit null** — a key followed by `:` with nothing
+        after is `None`; so are the explicit YAML null spellings `null`,
+        `Null`, `NULL`, and `~` (matching yaml.safe_load).
   * **Inline (flow) lists** — `[]`, `[a]`, `[a, b]`. Items are scalars only;
     nested brackets are an error. Real usage is correlation-ID lists.
   * **Comments** — `#` starting a line (after optional whitespace), or
@@ -73,8 +75,9 @@ on a missing gate set — silent misparses are worse than crashes.
   * Mixed / inconsistent indentation.
   * Nested brackets inside a flow list.
   * Escape sequences other than `\\` and `\"` in double-quoted strings.
-  * Boolean spellings other than exact lowercase `true` / `false`.
-  * Explicit null markers (`null`, `Null`, `NULL`, `~`).
+  * Boolean spellings other than exact lowercase `true` / `false` (the YAML
+    1.1 "Norway problem" — `yes`/`no`/`on`/`off`/`True` — stays rejected on
+    purpose; only `null` is accepted as a non-lowercase-keyword idiom).
   * Integers with sign, leading zeros, floats, hex, or underscores.
 
 A file using any of those raises `MiniYAMLError` with a line number and a
@@ -108,7 +111,7 @@ _FORBIDDEN_BOOLS = {
     "yes", "Yes", "YES", "no", "No", "NO",
     "on", "On", "ON", "off", "Off", "OFF",
 }
-_FORBIDDEN_NULLS = {"null", "Null", "NULL", "~"}
+_NULL_SCALARS = {"null", "Null", "NULL", "~"}
 
 
 # --------------------------------------------------------------------------- #
@@ -363,9 +366,13 @@ def _parse_scalar(text: str, lineno: int) -> Any:
         # forgiving result-block parse path on real agent output.
         raise MiniYAMLError(
             f"line {lineno}: flow mappings unsupported — use a block mapping")
-    if text in _FORBIDDEN_NULLS:
-        raise MiniYAMLError(
-            f"line {lineno}: explicit null marker unsupported — leave value empty")
+    if text in _NULL_SCALARS:
+        # Explicit YAML null spellings map to None, same as an empty value.
+        # Accepting them (rather than failing loud) removes a foot-gun for
+        # hand-authored frontmatter and for anything generated by a real YAML
+        # library, which emits `null` for None — and matches yaml.safe_load,
+        # tightening the equivalence guarantee (#177).
+        return None
     if text in _FORBIDDEN_BOOLS:
         raise MiniYAMLError(
             f"line {lineno}: only lowercase `true`/`false` accepted as "

specfuse_loop-0.3.18/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.18

{specfuse_loop-0.3.16 → specfuse_loop-0.3.18}/specfuse/loop/data/verification.yml.example

@@ -28,6 +28,15 @@
 #
 # cost_tracking: true
 
+# PER-GATE `wu_must_reference: true` (optional, default false). Flag a gate
+# whose fix is MECHANICAL over a work unit's own output — a formatter, an
+# auto-fixable linter (`spotless:check`, `black --check`, `gofmt -l`,
+# `prettier --check`). The plan linter (specfuse-lint) then WARNs when an
+# implementation WU's Verification section names none of that gate's command —
+# catching, at authoring time and zero model cost, the case where a WU forgets
+# a mechanical gate and the driver spins retries on the identical failure until
+# the attempt budget is exhausted. Leave it off for project-global gates
+# (leak-scan, hygiene checks) that an individual WU has no reason to name.
 code:
   - name: tests
     command: "pytest -q"
@@ -37,6 +46,9 @@ code:
     command: "python3 -W error -c 'pass'"    # replace with your build's -Werror equivalent
   - name: lint
     command: "ruff check ."
+  - name: format
+    command: "black --check ."               # deterministic formatter: fix with `black .`
+    wu_must_reference: true                   # WUs must name it (see note above)
   - name: security
     command: "bandit -r src -ll"             # or your OWASP-aligned scanner
 

{specfuse_loop-0.3.16 → specfuse_loop-0.3.18}/specfuse/loop/lint_plan.py

@@ -138,6 +138,69 @@ def _slice_section(body: str, section_name: str) -> str:
     return after[:em.start()] if em else after
 
 
+# Interpreters / super-generic words that don't distinguish one gate command
+# from another — excluded from a command's signature tokens (#176).
+_GATE_TOKEN_STOP = {
+    "python", "python3", "bash", "sh", "run", "exec", "discover",
+    "report", "source", "true", "false",
+}
+_GATE_TOKEN_RE = re.compile(r"[A-Za-z][A-Za-z0-9_.:+-]{2,}")
+# Verification prose that delegates to the whole gate set — treat as
+# referencing every gate so a legitimate "all gates pass" phrasing is not
+# flagged.
+_UMBRELLA_GATES_RE = re.compile(r"(?i)\b(all|every|entire|full|the)\b[^.\n]{0,24}\bgate")
+
+
+def _must_reference_gate_signatures(feature_dir: Path) -> list[tuple[str, set[str]]]:
+    """Return [(gate_name, signature_tokens)] for OPT-IN must-reference gates (#176).
+
+    Reads ``<project>/.specfuse/verification.yml`` (``feature_dir`` is
+    ``.../.specfuse/features/<name>``) and includes only `code` gates that set
+    ``wu_must_reference: true``. This is deliberately opt-in: warning on every
+    declared gate is noise on real multi-gate projects (leak-scan, hygiene
+    bats, etc. that an individual WU has no business naming). A project flags
+    the gates whose fix is mechanical over a WU's own output — formatters,
+    auto-fixable linters — the class #175 shows can burn the whole attempt
+    budget when a WU forgets them. Empty list (the check no-ops) when the file
+    is absent, unparseable, or no gate opts in. Each gate's token set is the
+    distinctive words of its command plus the gate name, lowercased.
+    """
+    vpath = feature_dir.parent.parent / "verification.yml"
+    if not vpath.is_file():
+        return []
+    try:
+        cfg = _miniyaml.parse(vpath.read_text()) or {}
+    except _miniyaml.MiniYAMLError:
+        return []
+    out: list[tuple[str, set[str]]] = []
+    for gate in cfg.get("code") or []:
+        if not isinstance(gate, dict) or gate.get("wu_must_reference") is not True:
+            continue
+        name = str(gate.get("name") or "").strip()
+        command = str(gate.get("command") or "")
+        tokens = {t.lower() for t in _GATE_TOKEN_RE.findall(command)
+                  if t.lower() not in _GATE_TOKEN_STOP}
+        if name:
+            tokens.add(name.lower())
+        if tokens:
+            out.append((name or command[:40], tokens))
+    return out
+
+
+def _unreferenced_code_gates(
+    verification_text: str, signatures: list[tuple[str, set[str]]],
+) -> list[str]:
+    """Names of code gates whose tokens *verification_text* references none of.
+
+    An umbrella "all gates" phrasing short-circuits to [] (author delegated).
+    """
+    if _UMBRELLA_GATES_RE.search(verification_text):
+        return []
+    low = verification_text.lower()
+    return [name for name, tokens in signatures
+            if not any(tok in low for tok in tokens)]
+
+
 def detect_oracle_verbs(ac_section_text: str) -> list[str]:
     """Return matched oracle-verb strings found in the AC section text."""
     found = []
@@ -249,6 +312,11 @@ def lint(feature_dir: Path) -> list[str]:
     if missing:
         errs.append(f"PLAN.md frontmatter missing keys: {sorted(missing)}")
 
+    # Opt-in must-reference gate signatures, loaded once for the
+    # Verification-reference WARN below (#176). Empty unless the project flags
+    # gates with `wu_must_reference: true`.
+    must_ref_gate_sigs = _must_reference_gate_signatures(feature_dir)
+
     if "base" in fm:
         base_val = fm["base"]
         feature_id_val = fm.get("feature_id", feature_dir.name)
@@ -400,6 +468,25 @@ def lint(feature_dir: Path) -> list[str]:
                         f"driver. See authoring-work-units §9 + FEAT-2026-0017."
                     )
 
+            # Verification ↔ must-reference gate WARN (#176). For gates a
+            # project has flagged `wu_must_reference: true` — those whose fix is
+            # mechanical over a WU's own output (formatters, auto-fixable
+            # linters) — the driver enforces them regardless of what a WU's
+            # Verification names. A session not told to run one writes code that
+            # fails it and, per #175, can burn the whole attempt budget on the
+            # mechanical failure. Flag at lint time, at zero model cost. Opt-in,
+            # so no noise on projects that don't flag any gate.
+            if wu_type_val == "implementation" and must_ref_gate_sigs:
+                verif_text = _slice_section(wbody, "Verification")
+                unref = _unreferenced_code_gates(verif_text, must_ref_gate_sigs)
+                if unref:
+                    print(
+                        f"WARN: {wfile}: Verification references none of the "
+                        f"must-reference gate(s): {', '.join(unref)}. The driver "
+                        f"runs them regardless; name each so the session knows to "
+                        f"satisfy it before finishing (#176)."
+                    )
+
             # Deliverable-presence declaration WARN (FEAT-2026-0022/T01).
             # Advisory: an implementation WU should declare the file path(s) it
             # is contracted to yield via `produces:`, which T02's presence gate

{specfuse_loop-0.3.16 → specfuse_loop-0.3.18}/specfuse/loop/loop.py

@@ -63,7 +63,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.16"
+DRIVER_VERSION = "0.3.18"
 # 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
@@ -190,14 +190,27 @@ FM = re.compile(r"^---\s*$")
 
 
 def read_frontmatter(path: Path) -> tuple[dict, str]:
-    """Return (frontmatter_dict, body_text)."""
+    """Return (frontmatter_dict, body_text).
+
+    A parse failure is re-raised with the file path attached and the line
+    clarified as frontmatter-relative (add 1 for the file line, since the
+    opening `---` is line 1). Without this a `_miniyaml.MiniYAMLError` carries
+    only a block-relative line number, so locating the offending file across
+    many feature folders meant grepping by hand (#177).
+    """
     lines = path.read_text().splitlines()
     if not lines or not FM.match(lines[0]):
         return {}, path.read_text()
     j = 1
     while j < len(lines) and not FM.match(lines[j]):
         j += 1
-    fm = _miniyaml.parse("\n".join(lines[1:j])) or {}
+    try:
+        fm = _miniyaml.parse("\n".join(lines[1:j])) or {}
+    except _miniyaml.MiniYAMLError as exc:
+        raise _miniyaml.MiniYAMLError(
+            f"{path}: {exc} (line is relative to the frontmatter block; "
+            f"add 1 for the file line)"
+        ) from exc
     body = "\n".join(lines[j + 1 :])
     return fm, body
 
@@ -261,7 +274,16 @@ def find_feature(arg: str | None) -> Path:
     for d in sorted(FEATURES_DIR.glob("*/")):
         plan = d / "PLAN.md"
         if plan.exists():
-            fm, _ = read_frontmatter(plan)
+            try:
+                fm, _ = read_frontmatter(plan)
+            except _miniyaml.MiniYAMLError as exc:
+                # One feature's malformed frontmatter must not block dispatch of
+                # every OTHER feature. Feature lookup is the earliest and least
+                # relevant failure point; skip the bad candidate with a warning
+                # rather than aborting the whole scan (#177).
+                print(f"warning: skipping {d.name} — unparseable PLAN.md "
+                      f"frontmatter: {exc}", file=sys.stderr)
+                continue
             if fm.get("status") == "active":
                 actives.append(d)
             elif fm.get("status") == "done":
@@ -542,6 +564,36 @@ def detect_degraded_oracle(stdout: str) -> str | None:
     return None
 
 
+# A failure signature carries no distinguishing content when it is a bare
+# code/markdown fence, whitespace-only, or pure ANSI. Non-Python gate output
+# (e.g. a TypeScript `tests` gate) matches none of the Python-specific
+# _SIG_PATTERNS below and used to fall through to the first line after the
+# marker — often a ``` fence — collapsing genuinely different failures to one
+# value and false-firing spinning_signature_repeat (#167).
+_FENCE_RE = re.compile(r"^[`~]{3,}[\w.+-]*$")
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+# Sentinel returned when every line after the FAIL marker is non-informative.
+# Distinct from `no_gate_marker` (a marker WAS found) and treated as
+# non-informative by `_is_noninformative_signature`.
+NO_SIGNATURE = "no_signature"
+
+
+def _is_noninformative_signature(sig: "str | None") -> bool:
+    """True when *sig* cannot distinguish one failure from another.
+
+    Covers None, whitespace-only, bare fences (``` / ~~~, optionally with a
+    language tag), pure-ANSI strings, and the NO_SIGNATURE sentinel. The spin
+    detector and the extraction fallback both consult this so a content-free
+    signature neither becomes a WU's identity nor trips escalation (#167).
+    """
+    if sig is None or sig == NO_SIGNATURE:
+        return True
+    stripped = _ANSI_RE.sub("", sig).strip()
+    if not stripped:
+        return True
+    return bool(_FENCE_RE.match(stripped))
+
+
 def parse_gate_failure_signature(stdout: str) -> tuple[str, str]:
     """Extract (failure_class, failure_signature) from gate runner stdout.
 
@@ -577,9 +629,12 @@ def parse_gate_failure_signature(stdout: str) -> tuple[str, str]:
             return failure_class, sig if sig else "unknown"
     for line in after_lines:
         stripped = line.strip()
-        if stripped:
-            return failure_class, stripped[:100]
-    return failure_class, "unknown"
+        # Skip non-informative lines (bare fences, whitespace, pure ANSI):
+        # keying the signature off one would collapse distinct failures (#167).
+        if _is_noninformative_signature(stripped):
+            continue
+        return failure_class, stripped[:100]
+    return failure_class, NO_SIGNATURE
 
 
 def detect_spinning_signature_repeat(
@@ -592,6 +647,9 @@ def detect_spinning_signature_repeat(
     Returns False when either element of current is None.
     Returns False when current or prior is the no_gate_marker sentinel to
     avoid false-positive halts on parser-opaque failures (AC4).
+    Returns False when either signature is non-informative — a bare fence,
+    whitespace, pure ANSI, or the NO_SIGNATURE sentinel — since such values
+    collapse distinct failures and would false-fire the spin halt (#167).
     """
     _SENTINEL = ("other", "no_gate_marker")
     if prior is None:
@@ -600,6 +658,9 @@ def detect_spinning_signature_repeat(
         return False
     if current == _SENTINEL or prior == _SENTINEL:
         return False
+    if (_is_noninformative_signature(current[1])
+            or _is_noninformative_signature(prior[1])):
+        return False
     return current == prior
 
 
@@ -616,7 +677,56 @@ def extract_failure_excerpt(stdout: str, max_chars: int = 500) -> str:
     encoded = text.encode("utf-8")
     if len(encoded) <= max_chars:
         return text
-    return encoded[-max_chars:].decode("utf-8", errors="ignore")
+    # Head+tail, not tail-only (#175): build-tool output puts the actionable
+    # part (the list of offending files) up top and boilerplate (help URLs,
+    # stack-trace hints) at the bottom. A tail-only slice reliably keeps the
+    # noise; splitting the budget preserves both ends.
+    marker = "\n...\n"
+    budget = max_chars - len(marker.encode("utf-8"))
+    if budget <= 0:
+        return encoded[-max_chars:].decode("utf-8", errors="ignore")
+    head_bytes = budget // 2
+    tail_bytes = budget - head_bytes
+    head = encoded[:head_bytes].decode("utf-8", errors="ignore")
+    tail = encoded[-tail_bytes:].decode("utf-8", errors="ignore")
+    return head + marker + tail
+
+
+# Forward-looking retry directives keyed by failure_class (#175 fix 1). The
+# gate output replayed into a retry describes files the per-attempt reset
+# already discarded, and reads as stale advice about a prior attempt. These
+# reframe it as a standing requirement for the fresh attempt and name the
+# mechanical remedy per class — no per-tool knowledge.
+_RETRY_CLASS_HINT: dict[str, str] = {
+    "lint": "This was a lint/format gate — its fix is mechanical: run the "
+            "formatter / linter's fix command over your changes and re-run the "
+            "gate before declaring done, rather than only rewriting the code.",
+    "tests": "Run the failing tests and make them pass before declaring done.",
+    "coverage": "Add tests covering the new or changed code to clear the "
+                "coverage gate before declaring done.",
+    "security": "Resolve the flagged security findings (or add a narrowly "
+                "scoped, justified suppression) before declaring done.",
+}
+
+
+def synthesize_retry_directive(failure_class: "str | None") -> str:
+    """Return a forward-looking retry instruction for *failure_class* (#175).
+
+    Prepended to the failure note fed into the next attempt. The note itself
+    is raw gate output about files the reset discarded; without this lead a
+    fresh session reads it as stale advice and reproduces the same omission
+    (e.g. never running the formatter), failing identically until attempts
+    exhaust. The lead reframes the output as a standing requirement and the
+    per-class hint names the remedy generically.
+    """
+    lead = ("The previous attempt's work was DISCARDED before this retry, so "
+            "the gate output below refers to files that no longer exist. Do "
+            "not read it as stale advice about a past attempt — treat it as a "
+            "standing requirement for THIS fresh attempt. ")
+    hint = _RETRY_CLASS_HINT.get(
+        failure_class or "",
+        "Satisfy every declared gate before declaring done.")
+    return lead + hint
 
 
 def emit_attempt_outcome(
@@ -1498,6 +1608,51 @@ def reset_preserving_events(
         _clean_attempt_untracked(untracked_before, events_path)
 
 
+def capture_working_tree_diff(head_before: str, max_chars: int = 20000) -> str:
+    """Return `git diff <head_before>` (working tree vs pre-attempt base), capped.
+
+    Folded into a failing attempt's evidence note BEFORE the per-attempt
+    `git reset --hard` discards the rejected work, so a blocked WU stays
+    diagnosable — a human (or /gate-status) can see the diff that was rolled
+    back, not just a truncated failure excerpt (#168).
+
+    Best-effort: returns "" on any git error or a clean tree. Truncated to
+    max_chars so a large refactor's diff cannot bloat the committed note.
+    """
+    try:
+        out = subprocess.run(
+            ["git", "diff", head_before],
+            capture_output=True, text=True, check=True,
+        ).stdout
+    except (subprocess.CalledProcessError, OSError):
+        return ""
+    if len(out) > max_chars:
+        out = out[:max_chars] + "\n… (diff truncated)\n"
+    return out
+
+
+def persist_attempt_notes(
+    work_dir: Path, wu_id: str, attempt_notes: "list[tuple[int, str]]",
+) -> "list[Path]":
+    """Write buffered per-attempt evidence to work/<wu>/attempt-N.md.
+
+    Extracted so both escalation paths persist evidence the same way: the
+    exhausted-attempts `for-else` and the early `spinning_signature_repeat`
+    halt. Previously only the former wrote notes, so a signature-repeat block
+    left nothing on disk to diagnose (#168). Returns the written paths for
+    inclusion in the escalation commit. `work/` is gitignored, so the explicit
+    `git add` in commit_bookkeeping is what tracks these.
+    """
+    wu_key = wu_id.replace("/", "_")
+    paths: list[Path] = []
+    for atmpt, evidence in attempt_notes:
+        p = work_dir / wu_key / f"attempt-{atmpt}.md"
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(evidence)
+        paths.append(p)
+    return paths
+
+
 class SquashCommitError(RuntimeError):
     """Raised when squash_commit's `git commit` is rejected (non-zero exit).
 
@@ -4144,10 +4299,29 @@ def run(
                     # Per-attempt notes are buffered (not written to disk) so they
                     # ride with the spinning-escalation commit if we exhaust
                     # attempts; on eventual PASS they're discarded as scratch.
-                    attempt_notes.append((attempt, payload))
-                    failure_note = payload
+                    # Fold the rejected working-tree diff into the buffered
+                    # evidence NOW, before the reset below discards it (#168).
+                    # Signature/excerpt parsing stays on the raw payload.
+                    _diff = capture_working_tree_diff(head_before)
+                    _evidence = payload
+                    if _diff:
+                        _evidence = (
+                            payload
+                            + "\n\n## Rejected working-tree diff "
+                              "(discarded by git reset on block)\n\n"
+                            + "```diff\n" + _diff + "\n```\n"
+                        )
+                    attempt_notes.append((attempt, _evidence))
                     _fc, _fs = parse_gate_failure_signature(payload)
                     _ex = extract_failure_excerpt(payload)
+                    # Prepend a forward-looking directive so the retry reads the
+                    # gate output as a standing requirement, not stale advice
+                    # about the discarded attempt (#175 fix 1).
+                    failure_note = (
+                        synthesize_retry_directive(_fc)
+                        + "\n\n## Gate output from the discarded attempt\n\n"
+                        + payload
+                    )
                     wu_events.append(emit_attempt_outcome(
                         wu, attempt, "failed",
                         attempts_usage[-1],
@@ -4169,11 +4343,18 @@ def run(
                         }))
                         reset_preserving_events(head_before, events_path,
                                                 untracked_before=untracked_before)
+                        # Persist buffered evidence (verify output + rejected
+                        # diff) AFTER the reset — work/ is gitignored so the
+                        # reset leaves it untouched, and this makes a
+                        # signature-repeat block diagnosable like the
+                        # exhausted-attempts path (#168).
+                        note_paths = persist_attempt_notes(
+                            work_dir, wu.wu_id, attempt_notes)
                         backend.set_wu(wu, "status", "blocked_human")
                         write_cost_to_wu(backend, wu, cum_usage)
                         flush_events(events_path, wu_events)
                         commit_bookkeeping(
-                            [wu.file, events_path],
+                            [wu.file, events_path, *note_paths],
                             f"chore(loop): {wu.wu_id} blocked_human "
                             f"(spinning_signature_repeat, attempt {attempt})"
                             f"\n\nFeature: {wu.wu_id}",
@@ -4206,13 +4387,8 @@ def run(
                         o == "zero_token" for o in attempt_outcomes)
                     reason = ("all_attempts_zero_token" if all_zero
                               else "spinning_detected")
-                    wu_key = wu.wu_id.replace("/", "_")
-                    note_paths = []
-                    for atmpt, evidence in attempt_notes:
-                        p = work_dir / wu_key / f"attempt-{atmpt}.md"
-                        p.parent.mkdir(parents=True, exist_ok=True)
-                        p.write_text(evidence)
-                        note_paths.append(p)
+                    note_paths = persist_attempt_notes(
+                        work_dir, wu.wu_id, attempt_notes)
                     backend.set_wu(wu, "status", "blocked_human")
                     write_cost_to_wu(backend, wu, cum_usage)
                     wu_events.append(build_event("human_escalation", wu.wu_id, {

{specfuse_loop-0.3.16 → specfuse_loop-0.3.18}/specfuse/loop/scaffold.py

@@ -8,6 +8,7 @@ import importlib.resources
 import json
 import os
 import re
+import sys
 from pathlib import Path
 
 from . import _miniyaml
@@ -389,9 +390,45 @@ def upgrade_specfuse(
     wire_claude(target_path)
     _write_manifest(specfuse_dir, manifest_entries)
 
+    _warn_unmanaged_legacy_dirs(specfuse_dir)
+
     return sorted(written)
 
 
+def _warn_unmanaged_legacy_dirs(specfuse_dir: Path) -> None:
+    """Warn (stderr) when legacy scripts/ or skills/ copies exist post-upgrade.
+
+    Current scaffold data ships neither directory: scripts come from the
+    specfuse-loop package, skills from the specfuse@specfuse plugin. Only
+    pre-PyPI (init.sh-era) repos carry full copies, and `upgrade` overlays
+    none of them while still advancing VERSION — so a VERSION that outpaces
+    the vendored scripts/skills is silent drift (#165). New projects have
+    neither dir, so this is a no-op for them.
+
+    A warning, not a prune: reconciling those copies (see `migrate_legacy`)
+    is destructive and left to an explicit operator step.
+    """
+    drift: list[str] = []
+    for name in ("scripts", "skills"):
+        d = specfuse_dir / name
+        if d.is_dir():
+            n = sum(1 for p in d.rglob("*") if p.is_file())
+            if n:
+                drift.append(f"  .specfuse/{name}/ ({n} file(s))")
+    if not drift:
+        return
+    print(
+        f"specfuse upgrade: WARNING — VERSION advanced to {scaffold_version()}, "
+        "but these directories are NOT managed by upgrade and may be stale:\n"
+        + "\n".join(drift)
+        + "\n  Scripts are provided by the specfuse-loop package and skills by "
+        "the specfuse@specfuse plugin; these are leftover full copies from an "
+        "older (pre-package) install. Remove them once nothing local depends "
+        "on them.",
+        file=sys.stderr,
+    )
+
+
 def init(target: str | Path, *, ci_check: str | None = None) -> list[str]:
     """Bootstrap a Specfuse-enabled repo: write .specfuse/ then wire .claude/.
 

{specfuse_loop-0.3.16 → specfuse_loop-0.3.18/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.3.16 → specfuse_loop-0.3.18}/specfuse_loop.egg-info/SOURCES.txt

@@ -102,6 +102,8 @@ tests/test_lint_plan_relative_import.py
 tests/test_lint_produces_driver_helper.py
 tests/test_lint_sections.py
 tests/test_lint_task_graph_yaml_selection.py
+tests/test_lint_verification_reference.py
+tests/test_loop_attempt_evidence.py
 tests/test_loop_auto_archive.py
 tests/test_loop_caveman_preamble.py
 tests/test_loop_close_intermediate.py