specfuse-loop 0.16.0__tar.gz → 0.18.0__tar.gz

{specfuse_loop-0.16.0/specfuse_loop.egg-info → specfuse_loop-0.18.0}/PKG-INFO

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

{specfuse_loop-0.16.0 → specfuse_loop-0.18.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.16.0"
+version = "0.18.0"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -88,3 +88,16 @@ namespaces = true
 # templates, rules, and other seed files out of the wheel without needing the
 # loop source repo on disk.
 "specfuse.loop" = ["data/**/*", "data/*"]
+
+# FEAT-2026-0109/T05: per-test dynamic contexts turn the `tests` gate's
+# existing `coverage run --source=specfuse` (`.specfuse/verification.yml`)
+# into a measured file/line -> test map for free — see
+# `GATE-02-REVIEW.md` § "Tests touching changed files" for why this beat an
+# import-graph or path-convention rule. Lives here rather than a new
+# `.coveragerc` because none exists today and the `tests` gate already
+# passes `--source` on the command line; adding a second config surface
+# would split coverage configuration in two. Read by `build_changed_file_test_map`
+# (`specfuse/loop/loop.py`) via the `coverage` package's own config loading —
+# no code here parses this section directly.
+[tool.coverage.run]
+dynamic_context = "test_function"

specfuse_loop-0.18.0/specfuse/loop/build_provenance.py

@@ -0,0 +1,332 @@
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+"""Which build am I actually running? (#1040)
+
+An installed console script (`specfuse-loop`, `specfuse-lint`, …) resolves
+`specfuse.loop` from `site-packages`. In a checkout of the driver's own source
+whose tree has moved ahead of the installed wheel, that means the command runs
+**a different program than the session believes it is running** -- and reports
+confidently.
+
+The failure mode is the worst kind: it does not error, it returns a plausible
+number. Three observed occurrences, two at real cost:
+
+* A gate-1 arming probe swept `specfuse-lint --closing` to confirm a new
+  requirement added no findings. It resolved to the installed 0.7.1 wheel,
+  which contained neither the new rules nor the module implementing them --
+  "the sweep would have reported identically had T03 shipped nothing."
+* A terminal close produced **14 spurious red results** before the run was
+  repeated from the repo root.
+
+Every affected surface had been patched by convention -- work-unit bodies
+saying "use the `.specfuse/scripts/` shim, not the installed console script"
+-- which is exactly the shape `a-rule-a-human-must-execute-is-not-a-control`
+says does not hold: a rule a session must remember, a silent wrong answer when
+it forgets, and no signal telling the two apart.
+
+This module is that signal. It warns; it does not refuse. #1040 lists refusal
+as a stronger option and recommends warning first, on the grounds that the
+warning's own evidence is what tells you whether refusal is needed.
+
+**Silent for downstream projects by construction.** The check fires only when
+the directory being operated on contains a `specfuse/loop/` source tree of its
+own -- i.e. a checkout of the driver. A project that installed Specfuse has no
+such path, so the console script is the correct thing to run there and this
+module never says anything.
+
+**A third state (FEAT-2026-0109/T08).** An out-of-tree build used to be
+uniformly "confidently wrong" -- an arbitrary installed wheel, indistinguishable
+from a driver that forgot to rebuild. It no longer is: `main()` now
+materializes its own pin of `specfuse/` outside the working tree, keyed on
+`HEAD^{tree}`, and re-enters execution from it (`loop.py`'s `_reexec_pinned`).
+That pin's provenance is recorded (`_PIN_MARKER_NAME`), so `out_of_tree_warning`
+can tell the two apart: a *recorded* pin reports both tree hashes and says
+which one it executed; an *unidentified* out-of-tree build keeps the alarming
+text verbatim, because it is still exactly as dangerous as the wheel that
+motivated this module.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Optional
+
+#: The shim that always resolves to the working tree, named in the warning as
+#: the concrete fix. `.specfuse/scripts/` is vendored per project.
+_SHIM_HINT = "python3 -m specfuse.loop.loop   (or .specfuse/scripts/<script>.py)"
+
+#: Relative path identifying a driver source checkout.
+_SOURCE_MARKER = Path("specfuse") / "loop" / "loop.py"
+
+
+def running_package_dir() -> Path:
+    """The `specfuse/loop/` directory this process actually imported.
+
+    Derived from this module's own location rather than by importing
+    `loop.py`: the check runs at CLI startup, and importing the driver to ask
+    where the driver is would be both slow and circular.
+    """
+    return Path(__file__).resolve().parent
+
+
+def source_tree_package_dir(start: Optional[Path] = None) -> Optional[Path]:
+    """The `specfuse/loop/` of the source checkout *start* sits in, if any.
+
+    Walks upward from *start* (default: the current directory) looking for a
+    `specfuse/loop/loop.py`. Returns `None` when there is none -- the normal
+    case for a project that installed Specfuse, and the reason this check is
+    silent there.
+    """
+    current = (start if start is not None else Path.cwd()).resolve()
+    for candidate in (current, *current.parents):
+        if (candidate / _SOURCE_MARKER).is_file():
+            return (candidate / "specfuse" / "loop").resolve()
+    return None
+
+
+#: Repo root, relative to which the pin cache lives -- overridable so tests
+#: (and an operator with no writable platform cache) can redirect it without
+#: env-var-shaped magic sprinkled through the pinning logic itself.
+_PIN_CACHE_ENV_VAR = "SPECFUSE_PIN_CACHE_DIR"
+
+#: Marker file written into a materialized pin, naming the tree hash it was
+#: built from. Its presence (and matching content) is what lets
+#: `out_of_tree_warning` tell a recorded pin apart from an arbitrary
+#: out-of-tree build -- anything under the pin cache root WITHOUT this marker
+#: (or whose content disagrees with its own directory name) is treated as
+#: unidentified, never trusted silently.
+_PIN_MARKER_NAME = ".specfuse-pin-tree"
+
+#: Manifest of every file `materialize_pin` copied into a pin, written
+#: alongside the marker. The marker alone only proves a directory CLAIMS to be
+#: the pin for a tree hash; an age-based tmp reaper (or anything else) can
+#: delete files from under it without touching the marker, and a copy missing
+#: files must never be reported as the running build (FEAT-2026-0109/T09,
+#: FOLLOW-UPS.md "A materialized pin can lose its files ..."). Reuse checks
+#: every path this manifest lists before trusting an existing pin.
+_PIN_MANIFEST_NAME = ".specfuse-pin-manifest"
+
+#: The launcher `main()` re-execs through once a pin is materialized. Its own
+#: directory becomes `sys.path[0]` for a script invocation (probed fact #2 in
+#: FEAT-2026-0109/T08's work-unit body), so it lives beside the pinned
+#: `specfuse/` copy rather than importing it via `-m` or `-c`, both of which
+#: the probe showed the working tree's copy shadows.
+PIN_LAUNCHER_NAME = "_run_pinned.py"
+
+_PIN_LAUNCHER_SOURCE = '''\
+"""Generated by specfuse.loop.build_provenance.materialize_pin — do not edit.
+
+Re-enters `specfuse.loop.loop:main` from this pin. This file's own directory
+is `sys.path[0]` for a script invocation, ahead of the cwd, so the `specfuse`
+package importable next to it resolves before the working tree's copy does.
+"""
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from specfuse.loop.loop import main  # noqa: E402
+
+if __name__ == "__main__":
+    sys.exit(main())
+'''
+
+
+def repo_root_for(start: Optional[Path] = None) -> Optional[Path]:
+    """The repo root of the source checkout *start* sits in, if any."""
+    tree = source_tree_package_dir(start)
+    return None if tree is None else tree.parent.parent
+
+
+def head_tree_hash(repo_root: Path) -> Optional[str]:
+    """`git rev-parse HEAD^{tree}` for *repo_root*, or None if unavailable.
+
+    None (rather than raising) covers every reason a tree hash might not be
+    resolvable -- no git binary, not a git repo, no commits yet -- and each
+    one means the same thing to a caller: pinning cannot proceed, run
+    unpinned. `never-touch.md`'s "stop at a boundary" posture, not a bug to
+    chase down.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(repo_root), "rev-parse", "HEAD^{tree}"],
+            capture_output=True, text=True, check=True,
+        )
+    except (subprocess.CalledProcessError, OSError):
+        return None
+    tree_hash = result.stdout.strip()
+    return tree_hash or None
+
+
+def pin_cache_root() -> Path:
+    """Where materialized pins live -- always outside any working tree.
+
+    A platform cache directory keyed by tree hash, per the work unit's
+    flag-scope table: putting it inside the tree it names would make its own
+    key (`HEAD^{tree}`) move every time the pin is written. `$TMPDIR` (or its
+    override) rather than a dotfile under the repo for the same reason.
+    """
+    override = os.environ.get(_PIN_CACHE_ENV_VAR)
+    if override:
+        return Path(override)
+    return Path(tempfile.gettempdir()) / "specfuse-pins"
+
+
+def pin_dir_for(tree_hash: str) -> Path:
+    return pin_cache_root() / tree_hash
+
+
+def _pin_manifest_lines(pin_specfuse_dir: Path) -> list:
+    """Relative paths of every file under *pin_specfuse_dir*, sorted."""
+    return sorted(
+        str(p.relative_to(pin_specfuse_dir))
+        for p in pin_specfuse_dir.rglob("*") if p.is_file()
+    )
+
+
+def _pin_is_complete(pin_dir: Path, tree_hash: str) -> bool:
+    """Whether *pin_dir* is a matching, fully-present pin for *tree_hash*.
+
+    Checks the marker's content (as before) AND that every file the manifest
+    recorded at materialize time is still present -- a manifest recorded once
+    and never re-derived from the possibly-reaped directory, so a pin missing
+    files fails this check instead of being reported as complete because most
+    of it happens to still be there.
+    """
+    marker = pin_dir / _PIN_MARKER_NAME
+    if not (marker.is_file()
+            and marker.read_text(encoding="utf-8").strip() == tree_hash):
+        return False
+    manifest = pin_dir / _PIN_MANIFEST_NAME
+    if not manifest.is_file():
+        return False
+    try:
+        expected = [line for line in
+                    manifest.read_text(encoding="utf-8").splitlines() if line]
+    except OSError:
+        return False
+    specfuse_dir = pin_dir / "specfuse"
+    return bool(expected) and all(
+        (specfuse_dir / rel).is_file() for rel in expected)
+
+
+def materialize_pin(repo_root: Path, tree_hash: str) -> Path:
+    """Copy *repo_root*'s `specfuse/` package to a pin keyed on *tree_hash*.
+
+    Idempotent: a pin already materialized for this tree hash -- marker
+    matches AND every manifested file is still present, `_pin_is_complete`
+    -- is reused as-is, so a second process pinning the same commit does not
+    re-copy. A pin that is missing files (an age-based tmp reaper, or
+    anything else, deleting from under an intact marker) fails that check
+    and is rebuilt from scratch here rather than reused half-complete
+    (FEAT-2026-0109/T09). Builds into a sibling temp directory first and
+    installs it with a single `os.replace` so a reader never observes a
+    half-copied pin.
+    """
+    pin_dir = pin_dir_for(tree_hash)
+    if _pin_is_complete(pin_dir, tree_hash):
+        return pin_dir
+
+    cache_root = pin_cache_root()
+    cache_root.mkdir(parents=True, exist_ok=True)
+    staging = Path(tempfile.mkdtemp(prefix=f".{tree_hash}-", dir=str(cache_root)))
+    try:
+        shutil.copytree(
+            repo_root / "specfuse", staging / "specfuse",
+            ignore=shutil.ignore_patterns("__pycache__", "*.pyc"),
+        )
+        (staging / PIN_LAUNCHER_NAME).write_text(_PIN_LAUNCHER_SOURCE, encoding="utf-8")
+        (staging / _PIN_MARKER_NAME).write_text(tree_hash, encoding="utf-8")
+        manifest = _pin_manifest_lines(staging / "specfuse")
+        (staging / _PIN_MANIFEST_NAME).write_text(
+            "\n".join(manifest) + ("\n" if manifest else ""), encoding="utf-8")
+        if pin_dir.exists():
+            if _pin_is_complete(pin_dir, tree_hash):
+                # Another process won the race and finished first; its copy
+                # is equally valid (same tree hash, fully present), so keep
+                # it and discard ours.
+                shutil.rmtree(staging, ignore_errors=True)
+            else:
+                # Stale marker, or a prior pin that lost files -- replace it.
+                shutil.rmtree(pin_dir, ignore_errors=True)
+                os.replace(staging, pin_dir)
+        else:
+            os.replace(staging, pin_dir)
+    finally:
+        if staging.exists():
+            shutil.rmtree(staging, ignore_errors=True)
+    return pin_dir
+
+
+def pinned_build_info(running: Path) -> "Optional[tuple[str, Path]]":
+    """If *running* is a recorded pin, return `(tree_hash, pin_root)`; else None.
+
+    Trusts only a marker directly under a pin whose directory name equals the
+    marker's own content -- an out-of-tree build that merely happens to sit
+    under the cache root without a matching marker is still unidentified, not
+    a free pass.
+    """
+    pin_root = running.parent.parent  # running == pin_root/specfuse/loop
+    marker = pin_root / _PIN_MARKER_NAME
+    if not marker.is_file():
+        return None
+    try:
+        recorded = marker.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    if not recorded or pin_root.name != recorded:
+        return None
+    return recorded, pin_root
+
+
+def out_of_tree_warning(start: Optional[Path] = None) -> Optional[str]:
+    """Return the warning text, or `None` when there is nothing to warn about.
+
+    Separated from the printing so the message can be asserted on directly.
+
+    Three states (FEAT-2026-0109/T08): in-tree (`None`), a **recorded pin**
+    (reports both tree hashes, no alarming language -- this driver
+    materialized it, from a named commit, this run), and an **unidentified**
+    out-of-tree build (the original, unchanged "confidently wrong" text --
+    still exactly as dangerous as the stale wheel that motivated this module).
+    """
+    tree = source_tree_package_dir(start)
+    if tree is None:
+        return None
+    running = running_package_dir()
+    if running == tree:
+        return None
+    pin_info = pinned_build_info(running)
+    if pin_info is not None:
+        pinned_hash, pin_root = pin_info
+        working_root = tree.parent.parent
+        working_hash = head_tree_hash(working_root)
+        return (
+            f"running a recorded pin of specfuse from {pin_root} "
+            f"(tree {pinned_hash}); the working tree at {working_root} is "
+            f"now at tree {working_hash or 'unknown'}."
+        )
+    return (
+        f"warning: running specfuse from {running}, but the working tree at "
+        f"{tree.parent.parent} carries its own source.\n"
+        f"         This command is measuring the INSTALLED build, not your "
+        f"checkout — results can be confidently wrong rather than failing.\n"
+        f"         Run instead: {_SHIM_HINT}"
+    )
+
+
+def warn_if_out_of_tree(start: Optional[Path] = None, stream=None) -> Optional[str]:
+    """Print the warning to stderr when one applies; return what was printed.
+
+    stderr, not stdout: several of these commands have parseable stdout that a
+    caller consumes, and a diagnostic must not land in it.
+    """
+    message = out_of_tree_warning(start)
+    if message is not None:
+        print(message, file=stream if stream is not None else sys.stderr)
+    return message

{specfuse_loop-0.16.0 → specfuse_loop-0.18.0}/specfuse/loop/closing_requirements.py

@@ -53,6 +53,7 @@ RETROSPECTIVE_FILENAME = "RETROSPECTIVE.md"
 #: creates the artifact and the requirement that a `not_met` close carry it.
 FOLLOW_UPS_FILENAME = "FOLLOW-UPS.md"
 FOLLOW_UP_ENTRY_RE = re.compile(r"^### ", re.MULTILINE)
+FOLLOW_UP_ENTRY_END_RE = re.compile(r"^#{1,3}\s", re.MULTILINE)
 
 #: `## Post-merge checklist` — the optional PLAN.md section a `met` close
 #: files as one `specfuse:post-merge` issue (FEAT-2026-0085/T03).
@@ -74,8 +75,12 @@ def parse_followup_entries(text: str) -> list[str]:
     """
     matches = list(FOLLOW_UP_ENTRY_RE.finditer(text))
     entries = []
-    for i, m in enumerate(matches):
-        end = matches[i + 1].start() if i + 1 < len(matches) else len(text)
+    for m in matches:
+        # An entry ends at the next heading of any level up to `###`, not
+        # only the next `### `: a closing `## Discharged` section used to be
+        # filed as the tail of the last entry's issue body (#1729).
+        nxt = FOLLOW_UP_ENTRY_END_RE.search(text, m.end())
+        end = nxt.start() if nxt else len(text)
         entries.append(text[m.start():end].strip("\n") + "\n")
     return entries
 
@@ -140,6 +145,16 @@ def gate_section_heading_re(gate_n: int) -> re.Pattern:
     )
 
 
+#: The feature-oracle verdict line a close's `## Measurements` section must
+#: carry when the gate declares `feature_oracle` (FEAT-2026-0101/T02). The
+#: gate's `feature_oracle` *is* the feature-level re-run
+#: `close-discipline.md` §1 requires — see
+#: [FEAT-2026-0057/G1-CLOSE/feature-oracle-is-a-different-question].
+FEATURE_ORACLE_KEY = "feature_oracle"
+FEATURE_ORACLE_VERDICT_RE = re.compile(
+    rf"^###\s+{re.escape(FEATURE_ORACLE_KEY)}:\s*(PASS|FAIL)\s*$", re.MULTILINE,
+)
+
 GATE_REVIEW_FILENAME_TEMPLATE = "GATE-{next_gate:02d}-REVIEW.md"
 
 
@@ -339,6 +354,19 @@ CLOSING_REQUIREMENTS: dict[str, list[Requirement]] = {
             applies_when="criteria_artifact_present",
             enforced_by="check_criteria_state_well_formed",
         ),
+        Requirement(
+            id="close-n", wu_type="close", phase="pre-squash",
+            description=(
+                f"When the gate's GATE-NN.md declares {FEATURE_ORACLE_KEY}, "
+                "RETROSPECTIVE.md's Measurements section records a "
+                "PASS/FAIL verdict line naming it — the gate's "
+                f"{FEATURE_ORACLE_KEY} is the feature-level re-run "
+                "close-discipline.md §1 requires "
+                "[FEAT-2026-0057/G1-CLOSE/feature-oracle-is-a-different-question]"
+            ),
+            file=RETROSPECTIVE_FILENAME,
+            enforced_by="check_feature_oracle_verdict_recorded",
+        ),
     ],
     "close-intermediate": [
         Requirement(

specfuse_loop-0.18.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.18.0

{specfuse_loop-0.16.0 → specfuse_loop-0.18.0}/specfuse/loop/data/docs/methodology.md

@@ -86,6 +86,16 @@ it mostly does not need. Author-set unless marked driver-owned.
 - `generated_surfaces` — OPTIONAL. Generated files this unit's acceptance depends on.
 - `oracle_env` — OPTIONAL. Where the verifying oracle runs: `macos_local`,
   `linux_docker`, `github_actions_ci`, or an operator-named string.
+- `feature_oracle` — GATE-level, not WU-level: lives in `GATE-NN.md`
+  frontmatter, one per gate. The executable proof of that gate's definition of
+  done, exercising the user-visible outcome end to end. Required to start
+  **red** and go **green** at the gate's walking skeleton (its first
+  implementation unit, permitted to stub anything off the thinnest end-to-end
+  path — `.specfuse/skills/authoring-work-units/SKILL.md` §14). The driver
+  runs it as part of every unit's verification in that gate and again at the
+  close, which records the verdict. `GATE.template.md` carries the key;
+  `/draft-feature` refuses to draft a gate without one
+  (`.specfuse/rules/close-discipline.md` §5, FEAT-2026-0101).
 - `produces` — OPTIONAL. Path(s) or glob(s) this unit must yield; the driver's
   presence gate refuses `complete` when one is missing or empty.
 - `produces_driver_helper` — OPTIONAL. Symbol(s) this unit adds to the driver.
@@ -295,11 +305,16 @@ line.
 
 **Unfinished work becomes tracked issues, not prose.** After a `not_met`
 close's squash, `file_followup_issues` files one GitHub issue per
-`FOLLOW-UPS.md` entry under `specfuse:follow-up`, carrying the entry body
-verbatim and idempotent per entry; on a `met` close it files the optional
-`## Post-merge checklist` section as one `specfuse:post-merge` issue. `gh`
-absent or failing leaves `FOLLOW-UPS.md` itself as the record — the driver
-never deletes or rewrites it — and emits one `followups_recorded` event naming
+`FOLLOW-UPS.md` entry under `specfuse:follow-up`, titled from the entry's
+heading text (`[FEAT-2026-0155 follow-up] <heading>`), carrying the entry body
+verbatim behind a `<!-- specfuse:followup id=… -->` marker, and writing
+`**Tracked as #N.**` back under the heading so the entry is filed once across
+every later attempt — an entry that already carries that line, by the driver's
+hand or a person's, is skipped; on a `met` close it files the optional
+`## Post-merge checklist` section as one `specfuse:post-merge` issue and writes
+the same line under that heading in `PLAN.md`. `gh` absent or failing leaves
+`FOLLOW-UPS.md` itself as the record — the driver never deletes or rewrites an
+entry, it only adds the tracked line — and emits one `followups_recorded` event naming
 the `filed` and `unfiled` counts.
 
 **Re-firing the flips out of band** (FEAT-2026-0070) — `fire_terminal_flips`
@@ -359,7 +374,7 @@ bound to the emitter by `tests/test_attempt_outcome_contract.py`:
 | `closing_deliverable_missing` | a closing-WU guard refused (see `close-discipline.md` §4) |
 | `deliverable_missing` | a declared `produces:` path is absent |
 | `no_deliverable_files` | the squash names only the WU file / events |
-| `produces_not_in_diff` | `produces:` path exists but is not in the squash |
+| `produces_not_in_diff` | `produces:` path exists but is not in the squash, and the RESULT's `produces_unchanged:` did not justify it |
 | `squash_commit_failed` | `git commit` for the squash was rejected |
 | `smoke_import_failed` | a declared smoke-import line failed post-squash |
 | `learnings_not_staged` | a closing WU under `autonomy_default: auto` touched `.specfuse/LEARNINGS.md` directly instead of staging to `LEARNINGS-pending.md` (FEAT-2026-0053/T09) |
@@ -555,6 +570,15 @@ a roadmap-anchor check (with a loud flag if the goal itself seems to be drifting
 and open questions — each mapped to the draft WU it affects. The summary is
 advisory and owns no state.
 
+**The oracle-progression obligation.** `plan-next` also drafts the next gate's
+`feature_oracle`, and its review summary must state how the drafted oracle
+advances the prior gate's oracle — in prose, as a judgment call, not as a
+lint rule. Nothing can decide mechanically whether one shell command is a
+"stronger" proof than another, so this is the one place an
+unenforceable-but-important question belongs: the summary is already weighted
+toward doubt and already carries the roadmap-anchor check above it
+(FEAT-2026-0101).
+
 ## 8. LEARNINGS — the cross-feature feedback loop
 
 `LEARNINGS.md` is an append-only, cross-feature log of durable, reusable rules

{specfuse_loop-0.16.0 → specfuse_loop-0.18.0}/specfuse/loop/data/rules/close-discipline.md

@@ -24,10 +24,32 @@ WU's frontmatter so the auto-close predicate cannot optimize it away (#189).
 The close re-runs every oracle the feature's acceptance criteria name — the
 full test command(s), plus any compile/execution gates — fresh, in this
 session, exit codes read directly. Never inherit a producing WU's
-self-report: `done` is a claim, the re-run is the verification. When the
+self-report: `done` is a claim, the re-run is the verification. What may be
+inherited is narrower and stated in §5: on a **re-close** of the same gate, a
+`narrow` criterion's green recorded in `GATE-NN-CRITERIA.md` by an earlier
+close attempt is carried forward; every `broad` oracle and the gate's
+`feature_oracle` re-run on every attempt. "Fresh" binds the first close of a
+gate in full, and the broad half of every close after it — never a producing
+unit's own report. When the
 feature's criteria assert on generated artifacts, regenerate into a clean
 output directory before asserting — stale output satisfies any assertion.
 
+**The gate's `feature_oracle` is the feature-level re-run, not one more unit
+oracle.** Re-running every producing unit's own oracle is a different, weaker
+question: `[FEAT-2026-0057/G1-CLOSE/feature-oracle-is-a-different-question]`
+records a close where fifteen unit oracles re-ran green and none could
+observe the defect, because none asserted on the path the feature was meant
+to change. A gate's `GATE-NN.md` may declare one `feature_oracle` — the
+composite question the units were each too small to ask. When it does, the
+close re-runs it fresh, same as any other oracle above, and records its
+verdict as a `### feature_oracle: PASS` or `### feature_oracle: FAIL` line in
+`## Measurements`. `specfuse lint --closing` fails a close that omits this
+line when the gate declares an oracle (`close-n`,
+`check_feature_oracle_verdict_recorded` in `closing_requirements.py` /
+`lint_closing.py`); a gate that declares no `feature_oracle` imposes no such
+requirement here — see this rule's "What the driver checks" section and T03
+for whether an absent declaration is itself a finding.
+
 > **Provenance.** A WU reported `done` while its source was untouched and its
 > oracle never ran; the driver-side produces-vs-diff guard now refuses that
 > pass (specfuse-loop >= 0.3.21), but only the close's own fresh re-run

{specfuse_loop-0.16.0 → specfuse_loop-0.18.0}/specfuse/loop/data/rules/operator-escalation.md

@@ -6,7 +6,7 @@ Licensed under the Apache License, Version 2.0. See LICENSE.
 # Rule: operator escalation framing
 
 Binding whenever work **stops and needs a human decision** — a `blocked` work
-unit, a gate at `awaiting_review`, a hedged verdict, a scope question, a refusal,
+unit, a gate at `awaiting_review`, a `not_met` verdict, a scope question, a refusal,
 or any skill that asks before writing.
 
 The audience is someone **deciding**, not someone executing. They may not have
@@ -60,7 +60,7 @@ so in that line rather than dropping it silently.
 ## The feature briefing — required when the halt is at feature scope
 
 The six parts frame a **decision**. When the halt is at feature or gate scope —
-a hedged terminal verdict, a feature that stopped partway and needs a human —
+a `not_met` terminal verdict, a feature that stopped partway and needs a human —
 the decision is not the whole question. The operator also needs to know whether
 the work *achieved what it was funded to achieve*, and that is a separate
 question from whether the tasks passed.
@@ -124,11 +124,11 @@ success is the failure this section prevents.
 
 - **Options without a recommendation.** Surfacing choices and stopping pushes the
   analysis back onto the person who asked. Always make the call; they can override.
-- **A refusal reported as a malfunction.** A withheld terminal flip on a hedged
+- **A refusal reported as a malfunction.** A withheld terminal flip on a `not_met`
   verdict is the contract working. Reporting it in the same tone as a crash makes
   a correct system look broken and invites someone to "fix" the safety catch.
 - **Writing the human's own justification for them.** Where a field records *why a
-  human accepted something* — `/accept-hedged-close`'s reason line, `/unblock-wu`'s
+  human decided something* — a `type: human` unit's `evidence:` line, `/unblock-wu`'s
   rationale, a contract-change acknowledgment — that text must come from the human.
   An agent that drafts it has removed the signature it was collecting. Ask; do not
   supply.

{specfuse_loop-0.16.0 → specfuse_loop-0.18.0}/specfuse/loop/data/rules/result-contract.md

@@ -35,14 +35,19 @@ cycle; this file is normative on how the loop surface reports step 4.
    the work unit's **Do not touch** section is binding.
 3. **Verify.** Re-read what you produced — the Write/Edit tool reports the
    action it took, not the property you wanted — and run the work unit's own
-   verification commands, in declared order, with full output. "I assume the
+   verification commands, in declared order, with full output. On the loop
+   that set is the **per-attempt (narrow) tier**: the unit type's gates minus
+   any declaring `tier: broad`, with `tests` through its `narrow_command` over
+   the unit's `produces:` test modules. The full suite, coverage and every
+   `tier: broad` gate are the driver's, once per gate — running them in-session
+   buys nothing the driver does not re-run. "I assume the
    tests still pass" is not a verification. A behavioural claim needs a run, not
    a reading of the source; a rule-or-severity claim needs a **negative
    observation**, the rule seen rejecting a purpose-built bad input.
 4. **Report.** Report only what verification confirmed.
 
 A failing check leaves you in one of three situations: correctable locally (fix
-the cause, re-run the **full** gate set from the top), spinning (three fresh
+the cause, re-run the **whole narrow tier** from the top), spinning (three fresh
 attempts is the driver's budget — emit `status: blocked` with the evidence
 rather than guessing), or fundamentally blocked (a spec ambiguity, generated
 code that must change, a missing dependency — emit `status: blocked` naming the
@@ -61,6 +66,9 @@ acceptance_criteria:
     met: true | false
     evidence: <how you know — a test name, a behavior, a line reference>
 blocked_reason: <present only when status is blocked>
+produces_unchanged:               # optional — closing obligation 1 below
+  - path: <a produces: entry, verbatim>
+    justification: <the command you ran and its output showing the deliverable already holds>
 ```
 ````
 
@@ -96,9 +104,12 @@ blocked_reason: <present only when status is blocked>
 
 1. **Diff against `produces:` first.** Every path in the WU's `produces:` list
    must show a working-tree change, or the RESULT must justify each unchanged
-   path with the command and output showing the deliverable already holds.
-   Silence on an unchanged deliverable is not a valid close (#198, outcome
-   `produces_not_in_diff`).
+   path under `produces_unchanged:` — the entry spelled as `produces:` spells
+   it, plus the command and output showing the deliverable already holds. The
+   driver reads that list: a justified entry passes and is recorded on the
+   attempt as `produces_justified`; an unjustified one, or a blank
+   justification, is refused (#198, #3268, outcome `produces_not_in_diff`).
+   Silence on an unchanged deliverable is not a valid close.
 2. **A plan-level contradiction is `blocked`, not `complete`.** If the plan
    cannot be delivered as written, put the finding in `blocked_reason`; never
    write it into a gate document and close `complete`.

{specfuse_loop-0.16.0 → specfuse_loop-0.18.0}/specfuse/loop/data/rules/verification-discipline.md

@@ -38,7 +38,10 @@ Two generic meanings, both apply unless the unit narrows the scope:
 - **Run the declared verification commands.** The unit names the checks that
   decide done. Run them yourself first, in declared order, with full output.
   Generic verifications — "I assume the tests still pass" — are not verifications.
-  The commands are the verification.
+  The commands are the verification. Where a surface tiers its checks — the
+  loop's per-attempt narrow tier against the driver's once-per-gate broad run —
+  the declared set is the tier the surface assigns to the session; running the
+  broader tier in-session proves nothing the surface does not re-run itself.
 - **Observe behavior, not source.** A claim that code does X is verified by making
   X happen and reading the output — never by reading the source that looks like it
   does X. A rule read as `ERROR` in source may be gated off and never fire; only a
@@ -50,8 +53,8 @@ Two generic meanings, both apply unless the unit narrows the scope:
 decided by the checks passing, not by the agent's belief. If a check fails you are
 in one of three situations:
 
-1. **Correctable locally.** Fix the cause, re-run the **full** check set from the
-   top, then continue. A re-run that fixes the original failure but introduces a
+1. **Correctable locally.** Fix the cause, re-run the **whole declared** check set
+   from the top, then continue. A re-run that fixes the original failure but introduces a
    new one is still a failed cycle.
 2. **Spinning threshold reached** (typically three fresh attempts on one unit).
    Signal blocked with precise evidence rather than spending the cycle guessing.