specfuse-loop 0.4.0__tar.gz → 0.6.0__tar.gz

{specfuse_loop-0.4.0/specfuse_loop.egg-info → specfuse_loop-0.6.0}/PKG-INFO

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

{specfuse_loop-0.4.0 → specfuse_loop-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.4.0"
+version = "0.6.0"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -63,6 +63,8 @@ select = ["E4", "E7", "E9", "F", "PLW1510", "B", "BLE001", "S110", "TRY004"]
 [project.scripts]
 specfuse-loop = "specfuse.loop.loop:main"
 specfuse-lint = "specfuse.loop.lint_plan:main"
+specfuse-monitor-lint = "specfuse.loop.lint_monitoring:main"
+specfuse-stats = "specfuse.loop.events_stats:main"
 
 [tool.setuptools.packages.find]
 # Ship ONLY the specfuse namespace package. Without this scope, setuptools'

specfuse_loop-0.6.0/specfuse/loop/_wu_sections.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""
+Dependency-free slicers for work-unit body sections.
+
+Shared by `loop.py` and `lint_plan.py`, which cannot import each other
+(`lint_plan.py` imports `VERDICT_VALUES` from `loop.py`, so the reverse
+import would be a cycle). This module imports nothing from either.
+"""
+
+from __future__ import annotations
+
+import re
+
+_AC_START_RE = re.compile(
+    r"(?mi)^\*\*Acceptance criteria[^\n*]*\*\*\.?|^#{1,6}\s+Acceptance criteria"
+)
+_AC_END_RE = re.compile(r"(?m)^(?:\*\*|#{1,6}\s)")
+
+
+def slice_acceptance_criteria(body: str) -> str:
+    """Return the text of the Acceptance criteria section only (bold-preamble or ATX)."""
+    m = _AC_START_RE.search(body)
+    if not m:
+        return ""
+    nl = body.find("\n", m.end())
+    after = body[nl + 1:] if nl != -1 else ""
+    em = _AC_END_RE.search(after)
+    return after[:em.start()] if em else after
+
+
+def slice_wu_section(body: str, section_name: str) -> str:
+    """Return content between a named section heading and the next heading."""
+    start_re = re.compile(rf"(?mi)^(?:#+\s*|\**){re.escape(section_name)}")
+    m = start_re.search(body)
+    if not m:
+        return ""
+    nl = body.find("\n", m.end())
+    after = body[nl + 1:] if nl != -1 else ""
+    em = _AC_END_RE.search(after)
+    return after[:em.start()] if em else after

specfuse_loop-0.6.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.6.0

{specfuse_loop-0.4.0 → specfuse_loop-0.6.0}/specfuse/loop/data/docs/methodology.md

@@ -159,6 +159,39 @@ re-run condition that would upgrade the verdict to `met`. Without the record,
 close-time obligations (fresh oracle re-runs, consumer-visible-change
 enumeration).
 
+**Exiting a hedged verdict** (FEAT-2026-0070) — a hedge left the feature with no
+supported path to `done`, because `fire_terminal_flips` runs at close-WU-*outcome*
+time and the driver never re-dispatches a `done` close WU. Two surfaces now close
+that gap, and **neither writes terminal state itself** — both route through the
+one owner:
+
+- `specfuse-loop --recheck-verdict <FEATURE_ID>` re-reads the terminal close WU's
+  verdict from disk and fires the flips if it now permits them, without
+  re-dispatching the WU. Use it when follow-ups were genuinely discharged and the
+  verdict was honestly upgraded to `met`. It is a no-op (exit `0`, printing why)
+  when the feature is already `done` or the verdict is still hedged.
+- `/accept-hedged-close` is the operator path for a hedge that is the ceiling **by
+  construction** — the criterion's oracle lives outside the repo and no amount of
+  gate work will close it. It surfaces the §2 follow-up record, requires a one-line
+  reason and explicit acknowledgment of the standing follow-ups, writes an
+  acceptance record, and then invokes `--recheck-verdict`. It carries the
+  follow-ups forward; it does not discharge them.
+
+**The row flips from any non-`done` status** (FEAT-2026-0070) — the terminal
+roadmap-row flip previously fired only on `active → done`, so an `autonomy: auto`
+feature that self-dispatched from a `planned` row stayed `planned` through a
+correct close and escalated `roadmap_row_not_done`. Any non-`done` row now flips.
+
+**Terminal state has exactly one writer.** `fire_terminal_flips` in
+`specfuse/loop/loop.py` owns the gate → `passed`, roadmap row → `done`, PLAN.md →
+`done`, and auto-archive transitions. Every close path — dispatched, auto-closed,
+and out-of-band re-check — calls that one function; no skill and no agent writes
+those surfaces. Issue #49 exists because two paths once diverged, and
+`[FEAT-2026-0023/G1-CLOSE]` is the rule that came out of it: do **not** add a "flip
+PLAN.md to done" acceptance criterion to a close WU, and do not let a skill
+hand-edit a terminal surface — if a new path needs the flip, give the driver an
+entry point and call it.
+
 **Predicate-version transparency** — every `auto_close_decision` event in
 `events.jsonl` carries a `predicate_version` field (e.g., `predicate_version:
 v1`). Future revisions to the predicate constants increment this version, so
@@ -176,16 +209,50 @@ the field-by-field schema see
 § "Event payload shape — `attempt_outcome` v1". The full payload is
 not restated here (one fact, one home).
 
-`outcome` taxonomy is **locked at v1**: `passed | failed | blocked |
-zero_token | files_changed_mismatch | post_pass_invariant_failed |
-closing_deliverable_missing | smoke_import_failed`. Extending the
-taxonomy requires a deliberate versioning decision.
+`outcome` taxonomy, as `loop.py` actually emits it — eleven values,
+bound to the emitter by `tests/test_attempt_outcome_contract.py`:
+
+| outcome | meaning |
+|---|---|
+| `passed` | verify + all driver-side guards clean |
+| `failed` | a verification gate failed |
+| `blocked` | the agent reported `status: blocked` |
+| `zero_token_skip` | the session produced no tokens; nothing ran |
+| `files_changed_mismatch` | RESULT declared paths that show no diff |
+| `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 |
+| `squash_commit_failed` | `git commit` for the squash was rejected |
+| `smoke_import_failed` | a declared smoke-import line failed post-squash |
+
+Extending it is a breaking change for every consumer below and requires a
+deliberate versioning decision — **and an update here in the same commit.**
+Five of the values above shipped without that step, and the drift was
+found only when someone mined the corpus (#270).
 
 `failure_class` taxonomy is **locked at v1**: `tests | lint |
 security | coverage | symbol_existence | bandit | other | null`.
 `failure_class: other` is the explicit catch-all for paths not yet
 classified; `null` means the outcome was `passed` (no failure).
 
+**Where the diagnostic lives depends on the outcome.** This is the part that
+misleads readers of the "standardized set" above: `failure_class` /
+`failure_excerpt` are not populated on every non-`passed` outcome, and a
+consumer that queries only those concludes the record is empty when it is not.
+
+| outcome | carries its reason in |
+|---|---|
+| `failed`, `files_changed_mismatch`, `produces_not_in_diff` | `failure_class` + `failure_signature` + `failure_excerpt` |
+| `blocked` | **`agent_blocked_reason`** (plus a sibling `human_escalation` event) |
+| `closing_deliverable_missing`, `no_deliverable_files`, `deliverable_missing`, `squash_commit_failed` | **`summary`** |
+| `files_changed_mismatch` (pre-0.3.23) | **`unchanged_paths`** only — `failure_*` was added by #182 |
+| `zero_token_skip` | nothing, correctly — no attempt ran |
+
+**Read every field in that table before concluding a record is undiagnosable.**
+A cross-repo audit reported three separate "missing diagnostic" findings that
+were all query errors against this contract, none of which existed (#270).
+
 Consumers that read `attempt_outcome` events (the auto-close
 predicate, `/gate-status`, the spinning-detector hook, close-ceremony
 cost analysis) treat the `outcome` and `failure_class` values as an

{specfuse_loop-0.4.0 → specfuse_loop-0.6.0}/specfuse/loop/data/docs/skills.md

@@ -66,6 +66,11 @@ roadmap ──/pick-feature──▶ active ──/draft-feature──▶ gate 1
 - **`/derive-verification`** — draft a `.specfuse/verification.yml` for a project
   by inspecting its CI, tooling manifests, and code. Run this once when
   bootstrapping the loop in a repo that already has CI worth deriving gates from.
+- **`/derive-monitoring`** — draft a `.specfuse/monitoring.yml` (plus a local
+  overrides file and a filled secrets checklist) for a project by discovering
+  deployed components from repo evidence and auditing them against the
+  design-for-diagnosis rule. Run this once a project has real components to
+  monitor.
 
 ### 3. Run — the driver (not a skill)
 
@@ -73,6 +78,13 @@ roadmap ──/pick-feature──▶ active ──/draft-feature──▶ gate 1
 WU as a fresh session, verifies, and commits. It is a command, not a skill. It
 either auto-closes a clean gate or halts at the gate boundary for review.
 
+It also owns every terminal flip (gate → `passed`, roadmap row → `done`, PLAN.md →
+`done`, auto-archive) — no skill writes those surfaces. When a verdict is upgraded
+*after* its close WU is already `done`, re-fire them with
+`specfuse-loop --recheck-verdict <FEATURE_ID>`: it re-reads the terminal close WU's
+verdict from disk and flips only if it now permits, printing why when it does not.
+Safe to run on an already-`done` or still-hedged feature — it writes nothing.
+
 ### 4. Arm — the human checkpoint at each gate
 
 - **`/arm-gate`** — at a gate boundary (driver halted with `awaiting_review`, next
@@ -96,9 +108,21 @@ either auto-closes a clean gate or halts at the gate boundary for review.
 
 ### 6. Wrap — finish a done feature
 
+- **`/accept-hedged-close`** — the path out of `/wrap-feature`'s refusal. A close
+  that legitimately ends `verdict: met_locally` (or `partially_met`) leaves every
+  terminal surface un-flipped by design, and for some features that hedge is the
+  ceiling *by construction* — the criterion's oracle lives outside the repo. This
+  skill quotes the standing follow-up record, requires a one-line reason and
+  explicit acknowledgment of every open item, writes an acceptance record into
+  `RETROSPECTIVE.md`, and then fires the flips through the driver's
+  `--recheck-verdict` primitive. It carries the follow-ups forward — accepting a
+  hedge is shipping with known-open items, not closing them. Refuses on `met`
+  (nothing to accept), on `not_met`, and on a close WU that isn't `done`. It never
+  writes PLAN.md's status, a gate's status, or the roadmap row.
 - **`/wrap-feature`** — after the terminal gate is `done`, push the feature
   branch, open a PR, optionally watch CI, and point at the next pick. Refuses if
-  PLAN.md isn't `done` yet.
+  PLAN.md isn't `done` yet — run `/accept-hedged-close` first if the block is a
+  standing hedged verdict.
 - **`/roadmap-archive`** — move a done or abandoned feature's detail section from
   `roadmap.md` to `roadmap-archive.md`, leaving a back-link.
 

{specfuse_loop-0.4.0 → specfuse_loop-0.6.0}/specfuse/loop/data/gitignore.snippet

@@ -9,3 +9,4 @@
 .specfuse/.loop.lock
 .specfuse/.scratch-*
 .specfuse/scripts/__pycache__/
+.specfuse/monitoring.overrides.yml

specfuse_loop-0.6.0/specfuse/loop/data/monitoring-secrets-checklist.md

@@ -0,0 +1,32 @@
+# Monitoring secrets checklist
+
+Merge and execution semantics land in FEAT-2026-0040 (`specfuse-monitor run`).
+This file is a shape declaration only: the list of environment-variable
+**names** an operator must export before running monitoring checks locally.
+It names variables, never values — it is safe to commit and safe to read.
+
+Pair this checklist with `.specfuse/monitoring.overrides.yml` (copied from
+`monitoring.overrides.yml.example`): every `credentials.*` value in that file
+is one of the names below.
+
+## Required environment variables
+
+- `ACME_TELEMETRY_STAGING_API_KEY` — Acme Telemetry console, staging
+  workspace, API keys page.
+- `ACME_BROKER_STAGING_CONNECTION_STRING` — Acme Broker console, staging
+  namespace, connection strings page (read-only credential).
+- `ACME_TELEMETRY_PROD_API_KEY` — Acme Telemetry console, production
+  workspace, API keys page.
+- `ACME_BROKER_PROD_CONNECTION_STRING` — Acme Broker console, production
+  namespace, connection strings page (read-only credential).
+
+## How to use this checklist
+
+1. Export each name above on the machine that will run
+   `specfuse-monitor run --dry-run` (FEAT-2026-0040), using whatever secret
+   store your shell profile or process manager already uses.
+2. Never write a value for any of these names into a tracked file, a commit
+   message, or this checklist itself — only the name belongs here.
+3. If a name above is missing on your machine, obtain the value from the
+   console page listed next to it; do not invent or reuse a value from
+   another environment.

specfuse_loop-0.6.0/specfuse/loop/data/monitoring.overrides.yml.example

@@ -0,0 +1,70 @@
+# .specfuse/monitoring.overrides.yml.example
+#
+# Machine-local override slice for monitoring.yml — which environment a local
+# run targets, the credential ENV-VAR NAMES available on this machine, and
+# `runner: local` forced on every component. Copy to
+# `.specfuse/monitoring.overrides.yml` (gitignored — see
+# .specfuse/gitignore.snippet) and edit for your own machine.
+#
+# MERGE AND EXECUTION SEMANTICS LAND IN FEAT-2026-0040. This file, like
+# monitoring.yml.example, is a shape declaration only: valid, inspectable, and
+# machine-checkable standing alone. It does not itself merge into
+# monitoring.yml or invoke anything — that is `specfuse-monitor run`'s job,
+# a CLI FEAT-2026-0040 ships.
+#
+# SAME SCHEMA AS monitoring.yml.example, unchanged — validated by
+# `specfuse/loop/lint_monitoring.py` (`validate_monitoring`). One monitoring
+# schema, not two. See docs/concepts/monitoring-schema.md.
+#
+# SECURITY POSTURE: identical to monitoring.yml.example. Every credential
+# value below is an ENVIRONMENT-VARIABLE NAME (UPPER_SNAKE_CASE), never a
+# literal secret — see .specfuse/monitoring-secrets-checklist.md for where to
+# obtain each value. Every organization name, host, workspace ID, and queue
+# name here is an obvious placeholder.
+
+# --------------------------------------------------------------------------
+# environments
+#
+# The machine-local slice usually names only the one environment this
+# machine runs checks against locally (here: staging).
+# --------------------------------------------------------------------------
+environments:
+  staging:
+    telemetry:
+      provider: acme-telemetry
+      credentials:
+        api_key: ACME_TELEMETRY_STAGING_API_KEY
+    broker:
+      provider: acme-broker
+      credentials:
+        connection_string: ACME_BROKER_STAGING_CONNECTION_STRING
+
+# --------------------------------------------------------------------------
+# components
+#
+# Every component's `runner` is forced to `local` in this override slice —
+# that is the property that makes it a *local-runner* bootstrap artifact.
+# `diagnose`/`autofix` stay at the same conservative defaults as
+# monitoring.yml.example.
+# --------------------------------------------------------------------------
+components:
+  - name: web-api
+    type: http-service
+    runner: local
+    diagnose: manual
+    autofix: "off"
+    checks:
+      - type: heartbeat
+      - type: error-logs
+
+  - name: order-worker
+    type: queue-consumer
+    runner: local
+    diagnose: manual
+    autofix: "off"
+    checks:
+      - type: dlq
+        harvest_mode: peek
+        targets:
+          - subscription: acme-orders-dlq-sub
+            function: ProcessOrder

specfuse_loop-0.6.0/specfuse/loop/data/monitoring.yml.example

@@ -0,0 +1,170 @@
+# .specfuse/monitoring.yml.example
+#
+# Declares how THIS project notices that a deployed component is misbehaving,
+# the way verification.yml declares how a change is proven correct before it
+# merges. Copy this file to `.specfuse/monitoring.yml` and edit it for your
+# real environments and components to opt in.
+#
+# MONITORING IS OPT-IN. An absent `.specfuse/monitoring.yml` is a correct,
+# valid final state — it is not an error, and the shipped gate does not fail
+# on a missing file. Only add this file once you have real components to
+# watch.
+#
+# This file is validated structurally by `specfuse/loop/lint_monitoring.py`
+# (`validate_monitoring`). Schema reference: docs/concepts/monitoring-schema.md
+#
+# SECURITY POSTURE: every credential-bearing value below is an
+# ENVIRONMENT-VARIABLE NAME (UPPER_SNAKE_CASE or the Section__Key form used by
+# .NET, Spring, and other hierarchical-config stacks), never a literal secret. The
+# validator rejects inline literals. Every organization name, host, workspace
+# ID, and queue name here is an obvious placeholder — replace them with your
+# own before use, but never with a literal credential value.
+
+# --------------------------------------------------------------------------
+# environments
+#
+# One entry per deploy target (staging, production, ...). Each environment
+# names its telemetry and broker provider bindings. `provider` is an OPAQUE
+# STRING this layer does not interpret — FEAT-2026-0040's harvester CLI reads
+# it and dispatches to a provider-specific adapter. Adding a new provider
+# never requires a change here or in the validator.
+# --------------------------------------------------------------------------
+environments:
+  staging:
+    telemetry:
+      provider: acme-telemetry
+      credentials:
+        api_key: ACME_TELEMETRY_STAGING_API_KEY
+    broker:
+      provider: acme-broker
+      credentials:
+        connection_string: ACME_BROKER_STAGING_CONNECTION_STRING
+
+  production:
+    telemetry:
+      provider: acme-telemetry
+      credentials:
+        api_key: ACME_TELEMETRY_PROD_API_KEY
+    broker:
+      provider: acme-broker
+      credentials:
+        connection_string: ACME_BROKER_PROD_CONNECTION_STRING
+
+# --------------------------------------------------------------------------
+# components
+#
+# One entry per deployable unit. Two are shown here so the per-component
+# dial model is visible rather than implied: `web-api` is HTTP-serving,
+# `order-worker` is message-consuming. Each component carries the same five
+# required fields and the same three dials, regardless of its shape.
+#
+# Dials, all per component:
+#   runner    — where diagnosis/autofix executes for this component.
+#               one of: local | gh-actions | in-cluster
+#   diagnose  — whether a harvested finding is investigated automatically.
+#               one of: manual | auto
+#   autofix   — whether a diagnosed finding may trigger an automated fix.
+#               one of: "off" | "on"  (quoted: bare `off` is not valid YAML
+#               here — see _miniyaml's rejection of the "off"/"on" spellings)
+#
+# Start every component at runner: local, diagnose: manual, autofix: "off".
+# Loosen one dial at a time as you build confidence in the checks below.
+# --------------------------------------------------------------------------
+components:
+  - name: web-api
+    type: http-service
+    runner: local
+    diagnose: manual
+    autofix: "off"
+    checks:
+      # http-5xx: alerts when the rolling 5xx rate crosses a threshold.
+      # Use for any component that serves HTTP traffic directly.
+      - type: http-5xx
+
+      # heartbeat: alerts when the component stops reporting in at all —
+      # the check that catches "it didn't error, it just went silent."
+      - type: heartbeat
+
+      # error-logs: scans structured application logs for error-level
+      # entries. Cheapest check to add; pairs with the design-for-diagnosis
+      # rule's structured-logging requirement.
+      - type: error-logs
+
+  - name: order-worker
+    type: queue-consumer
+    runner: local
+    diagnose: manual
+    autofix: "off"
+    checks:
+      # dlq: alerts when messages land in this component's dead-letter
+      # queue. harvest_mode controls whether the harvester CLI (0040) only
+      # reads DLQ entries (peek) or removes them from the queue after
+      # reading (quarantine) — start with peek until you trust the pipeline.
+      - type: dlq
+        harvest_mode: peek
+        targets:
+          - subscription: acme-orders-dlq-sub
+            function: ProcessOrder
+
+      # invariant: runs an operator-supplied query against this component's
+      # data and alerts when it returns unexpected rows. `query` is opaque
+      # to this schema (it is not parsed or executed here); `fingerprint_by`
+      # names the column used to dedupe repeat findings into one issue.
+      - type: invariant
+        query: "select count(*) from orders where fulfilled_at is null and created_at < now() - interval '1 day'"
+        fingerprint_by: order_id
+
+      - type: heartbeat
+
+  # acme-functions-host: the motivating shape this feature exists for. One
+  # deployable, many triggers — 3 queue subscriptions and 2 timer schedules,
+  # all running inside one process. `cloud_RoleName` is per-process, so this
+  # is ONE component (one role name, one set of dials), not five. Each
+  # trigger gets its own `targets[]` entry instead of its own component: a
+  # `dlq` check enumerates per subscription, a `heartbeat` check enumerates
+  # per schedule, and both stay attributable without duplicating the
+  # component (and its role-name-keyed error-logs/heartbeat query) once per
+  # trigger. See docs/concepts/monitoring-schema.md#check-targets.
+  - name: acme-functions-host
+    type: multi-trigger-host
+    runner: local
+    diagnose: manual
+    autofix: "off"
+    checks:
+      # One dlq check, many targets — not one dlq check per subscription.
+      # `subscription` is what the harvester queries; `function` is what a
+      # human diagnoses by, since a subscription name alone rarely tells an
+      # on-call engineer which handler failed.
+      - type: dlq
+        harvest_mode: peek
+        targets:
+          - subscription: acme-orders-created-sub
+            function: ProcessOrderCreated
+          - subscription: acme-orders-cancelled-sub
+            function: ProcessOrderCancelled
+          - subscription: acme-inventory-sync-sub
+            function: SyncInventoryLevels
+
+      # One heartbeat check, many targets — one per schedule, so a single
+      # silent timer among several is still individually visible instead of
+      # being averaged away by a single host-wide heartbeat.
+      - type: heartbeat
+        targets:
+          - name: nightly-reconciliation
+            cron: "0 2 * * *"
+            timezone: Etc/UTC
+          - name: hourly-cache-warm
+            cron: "0 * * * *"
+            timezone: Etc/UTC
+
+      # queue-stalled: catches a consumer that has stopped consuming — no
+      # message failed (so `dlq` sees nothing), the host is still alive (so
+      # `heartbeat` sees nothing), and queue depth is a broker coordinate, not
+      # a telemetry query (so `invariant` can't see it either). Same
+      # subscription/function coordinates as `dlq`; the stall-threshold value
+      # is opaque here, exactly like `invariant.query`.
+      - type: queue-stalled
+        targets:
+          - subscription: acme-orders-created-sub
+            function: ProcessOrderCreated
+            stall_after: 15m

specfuse_loop-0.6.0/specfuse/loop/data/rules/close-discipline.md

@@ -0,0 +1,115 @@
+<!--
+Copyright 2026 Specfuse Contributors
+Licensed under the Apache License, Version 2.0. See LICENSE.
+-->
+
+# Rule: close discipline
+
+Three obligations for `close` and `close-intermediate` WUs, binding at close
+time. Sibling of [`planning-discipline.md`](planning-discipline.md) (plan/arm
+time) and of the per-WU closing obligations in
+[`result-contract.md`](result-contract.md). Provenance: FEAT-2026-0049
+(the specfuse-generator dogfood), where three gates auto-closed at
+`attempts: 0` and the one close forced to run caught two false-`done` WUs and
+an unsatisfiable predicate — 48% of the feature's spend landed after the
+terminal gate had already "auto-closed". A close that only writes prose
+verifies nothing.
+
+A close whose acceptance criteria include ANY obligation below is
+**load-bearing**: the plan author sets `auto_close_disabled: true` in that
+WU's frontmatter so the auto-close predicate cannot optimize it away (#189).
+
+## 1. Oracles re-run fresh
+
+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
+feature's criteria assert on generated artifacts, regenerate into a clean
+output directory before asserting — stale output satisfies any assertion.
+
+> **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
+> catches the composite: all WUs individually green while the feature-level
+> oracle fails.
+
+## 2. Hedged-verdict follow-up record
+
+On `met_locally`, the close must produce a named record — in the gate review
+or `RETROSPECTIVE.md` — with one entry per unmet criterion:
+
+- the criterion, verbatim;
+- why it is unverifiable in this environment;
+- the exact re-run condition that would upgrade the verdict to `met`.
+
+The driver (>= 0.3.21) already guarantees the surfaces stay un-flipped on a
+hedged verdict (gate `awaiting_review`, roadmap `active`, PLAN `active`);
+this record is the other half: without it, `met_locally` is a dead end —
+no artifact says what would make it `met`, and the honest hedged verdict
+degrades into a polite synonym for "unknown".
+
+## 3. Consumer-visible contract changes enumerated, human-acknowledged
+
+The close enumerates every consumer-visible addition, removal, or rename the
+feature makes across ALL its producing WUs — API surface, generated models,
+published schemas, CLI flags, whatever contract consumers depend on — and
+blocks on explicit human acknowledgment of the list. A feature with no such
+changes writes exactly: `n/a — no consumer-visible contract change` (do not
+fabricate an empty enumeration; the n/a line is the reviewed claim).
+
+A close carrying this obligation is always load-bearing
+(`auto_close_disabled: true`).
+
+> **Provenance.** A breaking removal from a generated model survived four
+> gates unreviewed because no close surface owned the breaking-change list.
+> A silent breaking change is the most expensive false-done, and it is not
+> language-specific — any generated or published contract has this surface.
+
+## 4. What the driver checks — the exact strings
+
+Sections 1–3 are obligations you reason about. **This section is a format
+contract you must match literally.** The driver refuses a closing WU that
+produces correct content in the wrong shape, and it refuses it *after* the WU
+has run — so a mismatch costs a full re-dispatch, not a re-arm.
+
+That is not hypothetical. Across 158 closing WUs in 9 repositories, **28% of all
+closing-WU spend was burned on attempts the driver refused**, and three guards
+whose requirements appeared in no authoring surface accounted for **45% of that
+waste**. This table exists so that number goes down.
+
+| Guard | Applies to | What it requires, exactly |
+|---|---|---|
+| `assert_retrospective_exists` | `close`, `close-intermediate` | `RETROSPECTIVE.md` exists in the feature dir and is non-empty |
+| `assert_retrospective_gate_section` | `close-intermediate` | A heading matching `^#{1,3} Gate <N>` — i.e. `## Gate 1`, for the gate being closed. Not "Gate one", not a bare bold line |
+| `assert_cost_analysis_section_when_met` | `close` with `verdict: met` | A heading matching `^##+ Cost analysis` (case-insensitive) — `## Cost analysis` is the conventional spelling |
+| `assert_failure_class_breakdown_when_failures_present` | `close`, `close-intermediate`, when the gate had ≥1 failed attempt | A literal `### Failure-class breakdown` heading — three hashes, not two |
+| `assert_learnings_appended_or_noop` | `close`, `close-intermediate` | Either ≥1 added line to `.specfuse/LEARNINGS.md` in this WU's squash, **or** the exact phrase `nothing generalizes` (case-insensitive) somewhere in `RETROSPECTIVE.md` |
+| `assert_doc_or_roadmap_diff` | `close`, `close-intermediate` | The squash touches at least one of: `docs/*`, `.specfuse/roadmap.md`, `.specfuse/LEARNINGS.md`, or any `RETROSPECTIVE.md` |
+| `assert_verdict_well_formed` | `close` | A `verdict:` **frontmatter** field on the WU file, one of `met`, `met_locally`, `partially_met`, `not_met`. Not in the body |
+| `assert_gate_review_exists` | `plan-next` | **`GATE-{N+1}-REVIEW.md`** — named for the gate being *drafted*, not the gate being closed. A gate-1 `plan-next` writes `GATE-02-REVIEW.md` |
+| `assert_next_gate_drafted_or_terminal` | `plan-next` | The next gate has ≥1 WU at `status: draft` in `PLAN.md`, or the feature is terminal |
+| `assert_declared_deliverables` | any WU with `produces:` | Every path listed in `produces:` appears in the squash diff |
+| `assert_autoclose_debt_reconciled` | `close` | On a `close` WU, if `RETROSPECTIVE.md` carries T06's `<!-- specfuse:autoclose-debt gate=N ... -->` marker for a gate earlier than the terminal gate, the terminal close's `## What the loop did NOT verify` section must name that gate literally as `gate N`. Marker-gated (fires on none of this repo's pre-FEAT-2026-0070 closes); short-circuits `(True, "")` when the terminal close WU is itself `auto_close: true` |
+
+**The `GATE-{N+1}` row is the single most expensive guard in the system**
+($53.11 of measured waste across 15 refusals) and the one most likely to
+surprise: the review artifact is named for the gate it *arms*, because that is
+the gate a human reads it to review. See issue #261.
+
+**If a closing WU retries, read this table before assuming the work was hard.**
+By measured cost, format mismatches are the more likely explanation.
+
+> **Provenance (issue #265).** Guard requirements are enforced in
+> `specfuse/loop/loop.py`'s `assert_*` functions and were, until this section
+> existed, discoverable only by reading them or by paying for a refusal.
+> `tests/test_closing_guard_contracts.py` binds this table to those functions'
+> own source, so a guard that changes its literal fails a test rather than
+> silently invalidating this documentation.
+
+## Split with project-local rules
+
+These are the generic obligations. The concrete grounding — which command is
+the oracle, which surface is "the API", project-specific regeneration
+hazards — is per-project and belongs in that project's
+`.specfuse/rules-local/` (never touched by upgrade), referencing this rule.