specfuse-loop 0.9.0__tar.gz → 0.9.2__tar.gz

{specfuse_loop-0.9.0/specfuse_loop.egg-info → specfuse_loop-0.9.2}/PKG-INFO

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

{specfuse_loop-0.9.0 → specfuse_loop-0.9.2}/pyproject.toml

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

specfuse_loop-0.9.2/specfuse/loop/data/CHANGELOG.seed.md

@@ -0,0 +1,27 @@
+# Changelog
+
+Consumer-visible changes to this project, newest first.
+
+<!--
+How entries get here. Two collection points, because bugs have no close
+ceremony:
+
+  - a feature's close appends its "Consumer-visible contract changes"
+    enumeration (close-discipline.md §3) to Unreleased, one entry per change;
+  - `fix-bug` appends one line carrying the issue number before opening its PR.
+
+Every entry carries a `FEAT-YYYY-NNNN` or `#<issue>` trace in trailing
+parentheses, and sits under one of four class headings: Breaking, Added,
+Changed, Fixed. An entry without a trace is a lint finding — a changelog line
+nobody can trace back to the work that produced it is a line nobody can act on.
+
+No backfill. This file starts empty on purpose. Reconstructing history from
+commit subjects produces entries that read plausibly and describe the wrong
+thing; the enumeration a close already wrote is the source, and work that
+predates this file has none to lift.
+
+Cutting a release stamps Unreleased with the version and freezes it. Appends
+only ever go to Unreleased.
+-->
+
+## [Unreleased]

specfuse_loop-0.9.2/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.9.2

{specfuse_loop-0.9.0 → specfuse_loop-0.9.2}/specfuse/loop/data/rules/correlation-ids.md

@@ -145,17 +145,6 @@ The session running `plan-next` mints the next gate's substantive IDs as drafts;
 the human arms them. When adding a new closing WU type to `lint_plan.py`, also
 add its `<NAME>` segment to `CORRELATION_ID_RE` so the new IDs pass validation.
 
-**Two enforcement surfaces, one contract.** `lint_plan.py`'s `CORRELATION_ID_RE`
-enforces this format on `PLAN.md` graphs and WU frontmatter. The event envelope
-(`specfuse/loop/data/schemas/event.schema.json`) enforces a narrower vendored
-`correlation_id` pattern that does not yet know the closing-sequence or hygiene
-shapes; the loop widens it without editing the vendored file, via a driver-local
-registry (`specfuse/loop/data/schemas/driver-event.schema.json`'s `correlation_id`
-key, read by `validate_event.py`'s `load_validator`) — the same deep-copy
-fall-through FEAT-2026-0060 established for `event_type` (FEAT-2026-0073). When
-adding a new `<NAME>` segment, update `CORRELATION_ID_RE` **and** that registry's
-`closing_names` so both surfaces admit the new shape together.
-
 Do not reuse an ordinal even after a unit is abandoned. Once an ID has appeared in
 the event log, it is spent. Reusing it would make history ambiguous.
 

specfuse_loop-0.9.2/specfuse/loop/gate_commands.py

@@ -0,0 +1,94 @@
+#
+# Copyright 2026 Specfuse Contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""Read the gate sets out of `.specfuse/verification.yml` (#592).
+
+`verification.yml` is the source of truth for what gets verified. Anything
+that runs gates should derive its list from here rather than keeping a copy.
+
+`scripts/smoke-test.sh` used to carry a hand-maintained mirror under the
+comment "Keep in sync". It drifted by six gates, and two of them
+(`roadmap-link-gate`, `arm-sweep-gate`) shipped with features that week and
+were never once executed by CI. A declared-but-unrun gate is worse than an
+absent one, because the declaration reads as coverage.
+
+Deliberately not a YAML dependency: `_miniyaml` already parses this project's
+files, and adding a third-party parser to a path CI depends on would trade one
+drift risk for an install risk.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_SET_RE = re.compile(r"^([a-z_][a-z0-9_]*):\s*$", re.M)
+_NAME_RE = re.compile(r"^  - name:\s*(\S+)\s*$", re.M)
+_COMMAND_RE = re.compile(r'^\s+command:\s*"(.*?)"\s*$', re.M | re.S)
+
+
+def _set_block(text: str, set_name: str) -> str:
+    """Return the raw text of one top-level gate set, without its siblings."""
+    starts = [(m.group(1), m.start()) for m in _SET_RE.finditer(text)]
+    for i, (name, pos) in enumerate(starts):
+        if name != set_name:
+            continue
+        end = starts[i + 1][1] if i + 1 < len(starts) else len(text)
+        return text[pos:end]
+    return ""
+
+
+def iter_code_gates(
+    verification_yml: "Path | str", set_name: str = "code"
+) -> list[tuple[str, str]]:
+    """Yield `(name, command)` for every gate in *set_name*, in declared order.
+
+    Order is preserved because gate order is a real signal: the cheap,
+    fast-failing gates are declared first so a broken build reports in seconds
+    rather than after the full suite.
+    """
+    text = Path(verification_yml).read_text(encoding="utf-8")
+    block = _set_block(text, set_name)
+    if not block:
+        return []
+
+    gates: list[tuple[str, str]] = []
+    entries = re.split(r"^  - name:\s*", block, flags=re.M)[1:]
+    for entry in entries:
+        name = entry.split("\n", 1)[0].strip()
+        m = _COMMAND_RE.search(entry)
+        command = m.group(1).strip() if m else ""
+        gates.append((name, command))
+    return gates
+
+
+def code_gate_names(
+    verification_yml: "Path | str", set_name: str = "code"
+) -> list[str]:
+    """Names only, for parity checks."""
+    text = Path(verification_yml).read_text(encoding="utf-8")
+    return _NAME_RE.findall(_set_block(text, set_name))
+
+
+def main() -> int:
+    """Print `name<TAB>command` per gate, for shell consumption.
+
+    Used by `scripts/smoke-test.sh`, which substitutes its own interpreter for
+    a leading `python3`: the declared commands name `python3` because that is
+    what a target project's driver invokes, while the smoke test must use the
+    virtualenv interpreter that actually has the dependencies installed.
+    """
+    import argparse
+
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("verification_yml")
+    ap.add_argument("--set", default="code", dest="set_name")
+    args = ap.parse_args()
+    for name, command in iter_code_gates(args.verification_yml, args.set_name):
+        print(f"{name}\t{command}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{specfuse_loop-0.9.0 → specfuse_loop-0.9.2}/specfuse/loop/lint_plan.py

@@ -84,6 +84,20 @@ MODEL_ALIASES = frozenset({"sonnet", "opus", "haiku"})
 VALID_EFFORT = frozenset({"low", "medium", "high", "xhigh", "max"})
 FULL_MODEL_ID_RE = re.compile(r"^claude-\w[\w.-]*$")
 
+# Two enforcement surfaces, one contract. This pattern governs PLAN.md graphs
+# and WU frontmatter. The event envelope enforces its own, narrower
+# `correlation_id` pattern (`data/schemas/event.schema.json`, vendored from the
+# methodology core and never edited here); the driver widens it via the
+# driver-local registry `data/schemas/driver-event.schema.json`, read by
+# `validate_event.load_validator` on a deep copy — the fall-through
+# FEAT-2026-0060 established for `event_type` and FEAT-2026-0073 extended to
+# correlation IDs.
+#
+# ADDING A NEW `<NAME>` SEGMENT: update this pattern AND that registry's
+# `closing_names`, or IDs the linter accepts will be rejected by envelope
+# validation. This note lives here, at the change site, rather than in
+# `rules/correlation-ids.md` — that file is vendored from core, so a loop-local
+# addition to it is reverted by the next `sync-scaffold.sh` run (#581).
 CORRELATION_ID_RE = re.compile(
     r"^(FEAT-\d{4}-\d{4}(/(T\d{2}(H\d*)?|G\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE)))?|"
     r"INIT-\d{4}-\d{4}/F\d{2}(/(T\d{2}(H\d*)?|G\d+-(RETRO|LESSONS|DOCS|PLAN|CLOSE-INTERMEDIATE|CLOSE)))?)$"
@@ -226,6 +240,15 @@ def read_frontmatter(path: Path) -> tuple[dict, str]:
     j = 1
     while j < len(lines) and not FM.match(lines[j]):
         j += 1
+    if j >= len(lines):
+        # See loop.read_frontmatter: an opening `---` with no closing one made
+        # the scan run off the end and parse the document as frontmatter,
+        # reporting the failure against an arbitrary body line (#306).
+        raise _miniyaml.MiniYAMLError(
+            f"{path}: frontmatter block opened with `---` on line 1 but is "
+            f"never closed — add a `---` line to end it. Every line after it "
+            f"was read as frontmatter, so no check could evaluate this file."
+        )
     return _miniyaml.parse("\n".join(lines[1:j])) or {}, "\n".join(lines[j + 1:])
 
 
@@ -645,6 +668,60 @@ def _match_dnt_boundary(
     return None
 
 
+def check_produces_shape(feature_dir: Path, gates: list) -> list[str]:
+    """ERROR when a WU's `produces:` entry is a directory rather than a file
+    or glob.
+
+    Same family as `check_produces_boundary` below, and the same argument: the
+    driver refuses this outright, but only after a full `claude -p` session.
+    Since the agent cannot edit its own frontmatter, every retry is
+    byte-identical -- a real feature paid $6.42 and 20.6 minutes across three
+    of them before `spinning_detected` fired, while `specfuse-lint` reported
+    `OK - structurally valid` throughout (#593).
+
+    Every input is static, so this belongs in the pre-dispatch checklist. The
+    message is rendered by `loop.produces_shape_error`, the same function the
+    driver's guards call, so all three surfaces read identically rather than
+    drifting into three descriptions of one rule.
+
+    Applies to every WU with a `produces:` entry regardless of status: a `done`
+    WU with a directory entry is a folder authored against the pre-0.9.0
+    contract, and reporting it is how a migrating project finds them all at
+    once instead of one dispatch at a time.
+    """
+    from .loop import produces_shape_error
+
+    found: list[str] = []
+    for gate in gates:
+        for entry in gate.get("work_units") or []:
+            wid, wfile = entry.get("id"), entry.get("file")
+            if not wid or not wfile:
+                continue
+            wpath = feature_dir / wfile
+            if not wpath.exists():
+                continue
+            wfm, _ = read_frontmatter(wpath)
+            produces_raw = wfm.get("produces")
+            if not produces_raw:
+                continue
+            raw_entries = (
+                produces_raw if isinstance(produces_raw, list) else [produces_raw]
+            )
+            for p in raw_entries:
+                p_s = str(p).strip()
+                if not p_s:
+                    continue
+                err = produces_shape_error(p_s)
+                if err:
+                    found.append(
+                        f"ERROR: {wfile}: {wid} {err}. assert_declared_"
+                        f"deliverables refuses this after a full dispatch "
+                        f"attempt, and a retry cannot help — the agent cannot "
+                        f"edit its own frontmatter. See #593."
+                    )
+    return found
+
+
 def check_produces_boundary(feature_dir: Path, gates: list) -> list[str]:
     """ERROR when a WU's own `produces:` path (or `produces_driver_helper`
     surface) falls inside its own Do-not-touch section's paths.
@@ -879,6 +956,21 @@ def check_planning_sections(
 
 
 def lint(feature_dir: Path) -> list[str]:
+    """Lint a feature folder, converting an unparseable file into a finding.
+
+    A malformed WU used to abort the whole run with a traceback, which made
+    the folder unevaluable by *every* check rather than one (#306). The lint's
+    job is to report what is wrong with a folder; a file it cannot parse is
+    the most basic thing that can be wrong with one, so it is a finding like
+    any other. Callers still get a non-empty error list and a non-zero exit.
+    """
+    try:
+        return _lint_impl(feature_dir)
+    except _miniyaml.MiniYAMLError as exc:
+        return [f"ERROR: unparseable frontmatter — {exc}"]
+
+
+def _lint_impl(feature_dir: Path) -> list[str]:
     errs: list[str] = []
     plan = feature_dir / "PLAN.md"
     if not plan.exists():
@@ -1198,6 +1290,7 @@ def lint(feature_dir: Path) -> list[str]:
     check_closing_guard_literals(feature_dir, gates)
     check_autoclose_debt_prediction(feature_dir, gates)
     check_produces_satisfiability(feature_dir, gates)
+    errs.extend(check_produces_shape(feature_dir, gates))
     errs.extend(check_produces_boundary(feature_dir, gates))
     errs.extend(check_done_feature_gates(feature_dir, fm))
 

{specfuse_loop-0.9.0 → specfuse_loop-0.9.2}/specfuse/loop/loop.py

@@ -60,7 +60,7 @@ from . import _filelock
 from . import _miniyaml
 from . import _wu_sections
 from . import scaffold as _scaffold
-from .changelog import parse_changelog
+from .changelog import ENTRY_CLASSES, parse_changelog
 from .closing_requirements import (
     AUTOCLOSE_DEBT_MARKER_RE,
     CHANGELOG_PATH,
@@ -105,7 +105,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.9.0"
+DRIVER_VERSION = "0.9.2"
 # 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
@@ -245,6 +245,17 @@ def read_frontmatter(path: Path) -> tuple[dict, str]:
     j = 1
     while j < len(lines) and not FM.match(lines[j]):
         j += 1
+    if j >= len(lines):
+        # Unterminated block: an opening `---` with no closing one. Without
+        # this check the scan runs off the end, the whole document is parsed
+        # as frontmatter, and the failure is reported against whatever body
+        # line happens to be first — which sent #306 chasing an HTML comment
+        # that was never the problem. Name the actual defect instead.
+        raise _miniyaml.MiniYAMLError(
+            f"{path}: frontmatter block opened with `---` on line 1 but is "
+            f"never closed — add a `---` line to end it. Every line after it "
+            f"was read as frontmatter, so no check could evaluate this file."
+        )
     try:
         fm = _miniyaml.parse("\n".join(lines[1:j])) or {}
     except _miniyaml.MiniYAMLError as exc:
@@ -4674,7 +4685,12 @@ def assert_changelog_entry_for_contract_changes(
         return (
             False,
             f"assert_changelog_entry_for_contract_changes: '{CONSUMER_VISIBLE_HEADING}' "
-            f"names a real change but {CHANGELOG_PATH} does not exist",
+            f"names a real change but {CHANGELOG_PATH} does not exist. Create it at "
+            f"the repo root with a '## [Unreleased]' heading, then append this "
+            f"feature's enumeration under one of: "
+            f"{', '.join(sorted(ENTRY_CLASSES))}. Projects scaffolded before "
+            f"{CHANGELOG_PATH} was seeded will not have one; `specfuse upgrade` "
+            f"creates it without touching an existing file (#575)",
         )
     result = parse_changelog(changelog.read_text())
     unreleased = result.unreleased()
@@ -4795,6 +4811,52 @@ def assert_implementation_touched_files(
     )
 
 
+def produces_shape_error(path: str) -> "str | None":
+    """Return why *path* is an invalid ``produces:`` entry, or None if it is fine.
+
+    Shape only -- never presence. A path that does not exist yet is perfectly
+    valid at draft time; whether it was actually produced is the dispatch
+    gate's question, asked after the session.
+
+    Split out of ``assert_declared_deliverables`` so the one fact that needs no
+    session output can be checked by every surface that has the frontmatter:
+    ``lint_plan`` at draft/arm/conformance time, and the driver before it
+    spends a token (#593). A real feature paid $6.42 across three byte-identical
+    refusals for a ``Path.is_dir()`` call, with ``specfuse-lint`` reporting
+    ``OK - structurally valid`` the whole time.
+
+    The three surfaces must read identically, so all render this one string.
+    """
+    if path.endswith("/") or Path(path).is_dir():
+        return (
+            f"declared deliverable is a directory: {path} — directories "
+            "are not valid produces: entries under the unified "
+            "literal/glob contract (a directory always passed presence "
+            "while failing assert_produces_in_diff's diff match); declare "
+            "the specific file(s) or a glob instead"
+        )
+    return None
+
+
+def assert_produces_shape(wu: WorkUnit) -> tuple[bool, str]:
+    """Pre-dispatch half of ``assert_declared_deliverables`` (#593).
+
+    Every input is static: the WU's own frontmatter and the filesystem. None
+    of it depends on what a session did, so refusing here converts a $2.46
+    attempt into a $0.00 refusal -- the lever ``planning-discipline.md`` §5
+    already names, where ``assert_verdict_well_formed`` fired 10 times for
+    nothing because it is checked before the agent spends anything.
+
+    The agent cannot edit its own frontmatter, so a WU that fails this cannot
+    be fixed by retrying it; escalating immediately is the only honest move.
+    """
+    for raw in wu.produces or []:
+        err = produces_shape_error(str(raw))
+        if err:
+            return False, err
+    return True, ""
+
+
 def assert_declared_deliverables(wu: WorkUnit) -> tuple[bool, str]:
     """Deliverable-presence gate (FEAT-2026-0022/T02), unified with
     ``assert_produces_in_diff``'s literal/glob contract (FEAT-2026-0055/T03).
@@ -4826,14 +4888,11 @@ def assert_declared_deliverables(wu: WorkUnit) -> tuple[bool, str]:
     for raw in wu.produces:
         path = str(raw)
         p = Path(path)
-        if path.endswith("/") or p.is_dir():
-            return False, (
-                f"declared deliverable is a directory: {path} — directories "
-                "are not valid produces: entries under the unified "
-                "literal/glob contract (a directory always passed presence "
-                "while failing assert_produces_in_diff's diff match); declare "
-                "the specific file(s) or a glob instead"
-            )
+        # Shape refusal is shared with the pre-dispatch guard and lint_plan so
+        # all three surfaces render one message (#593).
+        shape_err = produces_shape_error(path)
+        if shape_err:
+            return False, shape_err
         if any(ch in path for ch in "*?["):
             matches = [
                 m for m in glob.glob(path)
@@ -5511,6 +5570,34 @@ def run(
                     blocked = True
                     continue
 
+                # produces: shape gate (#593). Same posture as the re-arm gate
+                # above: fires BEFORE any dispatch state change, so a WU the
+                # driver is guaranteed to refuse costs $0.00 instead of a full
+                # session. Every input is static frontmatter plus the
+                # filesystem, and the agent cannot edit its own frontmatter --
+                # so retrying is provably useless. A real feature paid $6.42
+                # across three byte-identical refusals before spinning fired.
+                shape_ok, shape_reason = assert_produces_shape(wu)
+                if not shape_ok:
+                    backend.set_wu(wu, "status", "blocked_human")
+                    flush_events(events_path, [build_event(
+                        "human_escalation", wu.wu_id, {
+                            "reason": "produces_shape_invalid",
+                            "blocked_reason": shape_reason,
+                            "attempts": 0,
+                            "failure_class": "guard_refusal",
+                            "failure_signature": "assert_produces_shape",
+                        })])
+                    commit_bookkeeping(
+                        [wu.file, events_path],
+                        f"chore(loop): {wu.wu_id} blocked "
+                        f"(produces: shape invalid)"
+                        f"\n\nFeature: {wu.wu_id}",
+                    )
+                    print(f"   BLOCKED before dispatch (no cost) — {shape_reason}")
+                    blocked = True
+                    continue
+
                 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

{specfuse_loop-0.9.0 → specfuse_loop-0.9.2}/specfuse/loop/scaffold.py

@@ -13,6 +13,9 @@ from pathlib import Path
 
 from . import _miniyaml
 from . import labels as _labels
+# The one name for the file close-k reads; scaffold seeds what that guard
+# requires, so both must agree on the path (#575).
+from .closing_requirements import CHANGELOG_PATH
 
 try:
     from importlib.resources.abc import Traversable  # Python 3.11+
@@ -163,8 +166,11 @@ _SEED_RENAME: dict[str, str] = {
 
 # Seed files handled by other work units; skip during init.
 # - gitignore.snippet: handled by T05 (wire_claude)
+# - CHANGELOG.seed.md: a repo-root file, not a .specfuse/ one; wire_claude
+#   writes it to the project root (#575)
 _SKIP_SEEDS: frozenset[str] = frozenset({
     "gitignore.snippet",
+    "CHANGELOG.seed.md",
 })
 
 
@@ -260,6 +266,26 @@ def _write_gitignore(target_path: Path) -> None:
     gitignore.write_text(existing + snippet, encoding="utf-8")
 
 
+def _write_changelog(target_path: Path) -> None:
+    """Seed a root CHANGELOG.md when the project has none (#575).
+
+    `close-k` fails a close whose §3 enumeration names a real consumer-visible
+    change unless `CHANGELOG.md`'s Unreleased gained a matching entry. Before
+    this, `specfuse init` never created the file, so a fresh project's first
+    such feature failed at its terminal close — the most expensive point in a
+    feature to be blocked — on a file the scaffold owed it.
+
+    Create-only. An existing CHANGELOG.md is a project's own document and is
+    never read, merged, or overwritten: `upgrade` routes through `wire_claude`
+    too, and silently rewriting a consumer-facing file on upgrade is worse than
+    the gap this closes.
+    """
+    changelog = target_path / CHANGELOG_PATH
+    if changelog.exists():
+        return
+    changelog.write_bytes(read_scaffold("CHANGELOG.seed.md"))
+
+
 def _write_claude_md(target_path: Path) -> None:
     claude_dir = target_path / ".claude"
     claude_dir.mkdir(parents=True, exist_ok=True)
@@ -355,6 +381,7 @@ def wire_claude(target: str | Path) -> None:
     """
     target_path = Path(target)
     _write_gitignore(target_path)
+    _write_changelog(target_path)
     _write_claude_md(target_path)
     _write_settings_json(target_path)
     refresh_claude_plugin_config(target_path)

{specfuse_loop-0.9.0 → specfuse_loop-0.9.2}/specfuse/loop/validate_event.py

@@ -146,6 +146,11 @@ def load_driver_correlation_patterns() -> dict | None:
     A missing, unreadable, or structurally incomplete registry file degrades
     to None (no widening — vendored-only validation) rather than raising,
     matching ``load_driver_event_types``'s existing contract.
+
+    ADDING A NEW ``<NAME>`` SEGMENT: update ``closing_names`` here AND
+    ``lint_plan.CORRELATION_ID_RE``, or the linter will accept IDs that
+    envelope validation rejects. The two surfaces enforce one contract and
+    must move together (#581).
     """
     global _DRIVER_CORRELATION_PATTERNS_CACHE
     if _DRIVER_CORRELATION_PATTERNS_CACHE is not _UNSET:

{specfuse_loop-0.9.0 → specfuse_loop-0.9.2/specfuse_loop.egg-info}/PKG-INFO

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

{specfuse_loop-0.9.0 → specfuse_loop-0.9.2}/specfuse_loop.egg-info/SOURCES.txt

@@ -15,6 +15,7 @@ specfuse/loop/closing_requirements.py
 specfuse/loop/cost.py
 specfuse/loop/escalation.py
 specfuse/loop/events_stats.py
+specfuse/loop/gate_commands.py
 specfuse/loop/gate_eval.py
 specfuse/loop/gh_backend.py
 specfuse/loop/gh_features.py
@@ -27,6 +28,7 @@ specfuse/loop/loop.py
 specfuse/loop/plan_baseline.py
 specfuse/loop/scaffold.py
 specfuse/loop/validate_event.py
+specfuse/loop/data/CHANGELOG.seed.md
 specfuse/loop/data/LEARNINGS.template.md
 specfuse/loop/data/VERSION
 specfuse/loop/data/gitignore.snippet
@@ -128,6 +130,7 @@ tests/test_bookkeeping_no_verify.py
 tests/test_changelog_collection.py
 tests/test_changelog_release_wiring.py
 tests/test_changelog_schema.py
+tests/test_ci_runs_every_gate.py
 tests/test_claude_resolution.py
 tests/test_close_wu_self_reference.py
 tests/test_closing_deliverable_guard.py
@@ -136,6 +139,7 @@ tests/test_closing_guard_prediction.py
 tests/test_closing_requirements.py
 tests/test_console_encoding.py
 tests/test_correlation_id_override.py
+tests/test_correlation_id_two_surfaces.py
 tests/test_cost_lifetime.py
 tests/test_cost_tracking.py
 tests/test_degraded_oracle.py
@@ -256,6 +260,7 @@ tests/test_prepare_scaffold_sync.py
 tests/test_produces_field.py
 tests/test_produces_in_diff.py
 tests/test_produces_semantics_unified.py
+tests/test_produces_shape.py
 tests/test_provision_labels.py
 tests/test_queue_stalled_adapter.py
 tests/test_redaction_windows_home.py
@@ -286,6 +291,7 @@ tests/test_template_closing_shapes.py
 tests/test_terminal_flip_ownership.py
 tests/test_terminal_flips.py
 tests/test_timeout_kill_portable.py
+tests/test_unterminated_frontmatter.py
 tests/test_untracked_feature_folder.py
 tests/test_untracked_file_absorption.py
 tests/test_upgrade_integration.py

{specfuse_loop-0.9.0 → specfuse_loop-0.9.2}/tests/test_changelog_collection.py

@@ -216,3 +216,43 @@ class TestChangelogCollection(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class TestMissingChangelogMessage(unittest.TestCase):
+    """#575 — the absent-file halt must name the fix, not just the absence.
+
+    The bare message reported that CHANGELOG.md does not exist without saying
+    the operator should create one or that the scaffold now seeds it, so a
+    first-time user read a terminal-close halt as a broken install.
+    """
+
+    def _reason_for_missing_changelog(self, root: Path) -> str:
+        fdir = root / "feature"
+        fdir.mkdir()
+        (fdir / "RETROSPECTIVE.md").write_text(
+            "# Retrospective\n\n"
+            "## Consumer-visible contract changes\n\n"
+            "1. **New CLI flag `--foo`.** Additive, no removal.\n\n"
+            "## Cost analysis\n\nAll cheap.\n"
+        )
+        wu = _make_wu(file=fdir / "WU-close.md", wu_id="FEAT-2026-9999/G1-CLOSE")
+        ok, reason = loop.assert_changelog_entry_for_contract_changes(
+            wu, fdir, root, DUMMY_HEAD,
+        )
+        self.assertFalse(ok, "a missing CHANGELOG.md must still fail close-k")
+        return reason
+
+    def test_message_names_the_remedy_and_the_legal_classes(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            reason = self._reason_for_missing_changelog(Path(tmp))
+        self.assertIn("[Unreleased]", reason)
+        self.assertIn("specfuse upgrade", reason)
+        self.assertIn("#575", reason)
+        for cls in ("added", "changed", "fixed", "breaking"):
+            self.assertIn(cls, reason, f"message omits legal class {cls!r}")
+
+    def test_message_says_upgrade_preserves_an_existing_file(self):
+        """Telling an operator to run `upgrade` is only safe if it cannot clobber."""
+        with tempfile.TemporaryDirectory() as tmp:
+            reason = self._reason_for_missing_changelog(Path(tmp))
+        self.assertIn("without touching an existing file", reason)