specfuse-loop 0.19.0__tar.gz → 0.20.0__tar.gz

{specfuse_loop-0.19.0/specfuse_loop.egg-info → specfuse_loop-0.20.0}/PKG-INFO

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

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/pyproject.toml

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

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/closing_requirements.py

@@ -281,14 +281,25 @@ CLOSING_REQUIREMENTS: dict[str, list[Requirement]] = {
         ),
         Requirement(
             id="close-e", wu_type="close", phase="pre-squash",
-            description=f"RETROSPECTIVE.md has a '{COST_ANALYSIS_HEADING}' heading",
+            description=(
+                f"RETROSPECTIVE.md has a '{COST_ANALYSIS_HEADING}' heading "
+                "when verdict==met AND gate_eval.reflection_required says "
+                "the gate went off-plan (FEAT-2026-0106/T03) — an on-plan "
+                "close skips this reflective section"
+            ),
             file=RETROSPECTIVE_FILENAME, heading=COST_ANALYSIS_HEADING,
             applies_when="verdict_met",
             enforced_by="assert_cost_analysis_section_when_met",
         ),
         Requirement(
             id="close-f", wu_type="close", phase="pre-squash",
-            description=f"RETROSPECTIVE.md has a '{FAILURE_CLASS_HEADING}' heading",
+            description=(
+                f"RETROSPECTIVE.md has a '{FAILURE_CLASS_HEADING}' heading "
+                "when non-passing attempts are present AND "
+                "gate_eval.reflection_required says the gate went off-plan "
+                "(FEAT-2026-0106/T03) — an on-plan close skips this "
+                "reflective section"
+            ),
             file=RETROSPECTIVE_FILENAME, heading=FAILURE_CLASS_HEADING,
             heading_level=FAILURE_CLASS_HEADING_LEVEL,
             applies_when="failures_present",
@@ -397,7 +408,13 @@ CLOSING_REQUIREMENTS: dict[str, list[Requirement]] = {
         ),
         Requirement(
             id="close-intermediate-d", wu_type="close-intermediate", phase="pre-squash",
-            description=f"RETROSPECTIVE.md has a '{FAILURE_CLASS_HEADING}' heading",
+            description=(
+                f"RETROSPECTIVE.md has a '{FAILURE_CLASS_HEADING}' heading "
+                "when non-passing attempts are present AND "
+                "gate_eval.reflection_required says the gate went off-plan "
+                "(FEAT-2026-0106/T03) — an on-plan close skips this "
+                "reflective section"
+            ),
             file=RETROSPECTIVE_FILENAME, heading=FAILURE_CLASS_HEADING,
             heading_level=FAILURE_CLASS_HEADING_LEVEL,
             applies_when="failures_present",

specfuse_loop-0.20.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.20.0

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/data/docs/methodology.md

@@ -185,6 +185,16 @@ For the full design rationale see `PLAN.md` for FEAT-2026-0018.
    FEAT-2026-0016, if present, is also inspected — any prior `blocked_human`
    cycle disables auto.
 2. **No replan** — no `replan` event in `events.jsonl` for this gate's WUs.
+   A replan fires when a unit's next attempt would be its last permitted one
+   (the ceiling `resolve_max_attempts` resolves for that unit, not a bare
+   count of two) — the driver runs a fresh re-plan session instead of
+   retrying the same failing body verbatim. Units with `iterate_on_failure:
+   true` are exempt: they fail on purpose against a convergent validator, and
+   a replan there would misread deliberate iteration as spinning. Seeing this
+   check disable auto-close means a unit was mis-sized at authoring time (see
+   `/authoring-work-units` §6), not that anything is broken. A unit that
+   still spins out after this automatic re-plan escalates to a human — see
+   the escalation brief below for what that escalation tells the operator.
 3. **Per-WU cost ≤ 1.5× planned** — every substantive WU's `cost_usd` ≤
    `planned_cost_usd × 1.5`. If `planned_cost_usd` absent: skip this check for
    that WU (graceful degrade — emits a warning reason in the decision but doesn't
@@ -202,6 +212,28 @@ For the full design rationale see `PLAN.md` for FEAT-2026-0018.
    failed (already governed by check 1 if blocked), but the FINAL outcome on
    each WU must be clean.
 
+**The escalation brief (FEAT-2026-0104)** — **every** `blocked_human`
+escalation of a work unit, not only the spin-out that follows the automatic
+re-plan above, halts with a six-part operator brief
+(`.specfuse/rules/operator-escalation.md`'s six parts, in order), printed to
+the console and recorded verbatim in the `human_escalation` event's `message`
+field in `events.jsonl`. Gate-level halts — a gate budget exceeded, a
+pre-existing gate failure, a failing broad run — are excluded: those are keyed
+on the feature rather than on one unit, and there is no single unit to brief
+about. The escalation `reason` decides
+whether the brief's first option is re-planning the remaining gate:
+`spinning_detected`, `spinning_signature_repeat`, `convergence_plateau`, and
+`replan_unchanged_body` carry it, because for those a wider re-scope is the
+remedy; `all_attempts_zero_token`, `deterministic_refusal_repeat`,
+`produces_shape_invalid`, `spinning_reproduction_missing`, `prep_halted`, and
+`agent_reported_blocked` do not, because re-planning would fix nothing about
+that reason's actual cause (`REPLAN_OPTION_SCOPE` in `loop.py` is the single
+table both the brief and its tests consult). When it applies, the option is a
+recommendation, not an action the driver performs: the brief names
+`/unblock-wu` for the operator to run, re-arming the unit(s) so the driver's
+own automatic re-plan trigger (check 2 above) becomes reachable again for
+each — it resets `attempts`, it does not itself rewrite a body.
+
 **Auto-close terminal** — when the predicate fires on a terminal gate, the driver
 writes a stub `RETROSPECTIVE.md`, marks the close WU `status: done` with
 `auto_close: true` frontmatter, and fires `fire_terminal_flips` directly. The
@@ -563,6 +595,18 @@ reflective session. Ceremony proportionality trades reflection only on
 features that stay small **and** on-plan. The `gate_eval.py` predicate is
 the safety net; this rule does not replace it.
 
+**Reflective prose is conditional too (FEAT-2026-0106).** The roadmap once
+asked for a retrospective "only on `not_met` or on request" — superseded,
+for an ordering reason: the close writes `RETROSPECTIVE.md` before the judge
+produces a verdict, so there is nothing to condition on at write time. The
+close instead keys its reflective sections (`## Cost analysis`,
+`### Failure-class breakdown`) on the same off-plan signal named above
+(blocked WU, replan event, cost overrun) rather than on the verdict. Every
+other closing obligation — measurements above all, since the judge's evidence
+bundle depends on them regardless of how the gate went — stays unconditional;
+see [`close-discipline.md`](../.specfuse/rules/close-discipline.md) §1a for
+which is which.
+
 The canonical threshold is **8** (stated here, in `docs/methodology.md`;
 referenced, not re-defined, in `.specfuse/skills/draft-feature/SKILL.md`).
 
@@ -610,6 +654,31 @@ feature's `RETROSPECTIVE.md`; only rules that would change how a *future* WU is
 written or executed graduate to `LEARNINGS.md`. This is the human-scale analogue
 of the Ralph loop feeding errors back into the prompt.
 
+### The binding-block word budget (FEAT-2026-0111)
+
+The `.claude/CLAUDE.md` "Specfuse binding rules" block — every `@`-referenced
+file a dispatched work-unit session is held to — is capped at 2,500 words
+(`BINDING_BLOCK_WORD_CAP` in `specfuse/loop/loop.py`), enforced by
+`check_binding_block_budget`. Every rule added to that block, including a
+project-authored entry under `.specfuse/rules-local/`, is counted against this
+one shared cap; a project adding a local rule spends the same allowance the
+loop's own rules already draw from.
+
+`.specfuse/rules-local/learnings-distilled.md` — the LEARNINGS-derived
+distillate wired into the block — carries its own 500-word sub-budget
+(`LEARNINGS_DISTILLED_WORD_CAP`) inside the 2,500-word total. `score_learnings_entries`
+ranks candidate entries and a human accept step (`apply_distilled_decisions`)
+cuts the accepted set to that 500-word sub-budget, not to an entry count.
+
+The ranking's `reach` field — the count of other feature files that cite an
+entry — is **a tiebreaker with an age bias, not a ranking signal**: it counts
+citations in planning documents, and planning agents cite what they have
+already read in `LEARNINGS.md`, so visibility inflates its own count, and it
+favors older entries that have had more features' worth of planning sessions
+in which to be cited. Neither `reach` nor `cost_usd` measures whether a rule
+actually improves a session's work — that is a judgment the accept step still
+has to make by reading the entry, not a property either weight computes.
+
 ## 9. Autonomy
 
 Three levels — `auto`, `review`, `supervised` — set once as a feature default

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/data/rules/close-discipline.md

@@ -76,6 +76,20 @@ conclude it — the reason the judge is a fresh session in the first place. A
 close body names what to measure and what evidence counts, never what value to
 write. Naming the verdict in the body is a drafting defect, not a shortcut.
 
+## 1a. Which obligations are conditional (FEAT-2026-0106)
+
+Not every obligation above binds on every close. The reflective sections —
+`## Cost analysis` and `### Failure-class breakdown` — are conditional on
+`gate_eval`'s off-plan signal (a blocked WU, a `replan` event, a cost
+overrun): an on-plan close skips them. Measurements are not conditional on
+anything, for the reason stated in §1 — the judge's evidence bundle slices
+`## Measurements` out of `RETROSPECTIVE.md` regardless of how the gate went,
+so a close that skipped writing them would starve the judge of the evidence
+it needs to reach a verdict at all. `docs/methodology.md` §6 "Ceremony
+proportionality" states the same off-plan signal at the gate-dispatch level
+(whether a close runs at all); this section is the narrower case of a close
+that does run still skipping prose the gate didn't earn.
+
 ## 2. The verdict is binary; unfinished work is tracked, not hedged
 
 The verdict a close records is `met` or `not_met` — there is no partial

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/data/rules/never-touch.md

@@ -7,50 +7,47 @@ Licensed under the Apache License, Version 2.0. See LICENSE.
 
 Three categories of path are off-limits to every work-unit session, regardless of
 unit type. If a unit's acceptance criteria or verification commands appear to
-require modifying something in this list, that is an escalation condition, not a
+require modifying something in this list, that is an escalation condition, not
 license to proceed — signal blocked per
 [`verification-discipline.md`](verification-discipline.md), naming the
-boundary. (How "blocked" is signalled is surface-specific — a `status: blocked`
+boundary. (How "blocked" is signalled is surface-specific: a `status: blocked`
 RESULT on the loop, a `blocked_*` transition on the orchestrator.)
 
 ## 1. Generated code directories
 
-Any path under a generated directory — `_generated/`, `gen-src/`, or whatever the
-repo declares as its generated tree — is off-limits. Generators own those files
-end-to-end; an edit there is silently overwritten on the next regeneration and
-leaves no trace of why.
+Any path under a generated directory — `_generated/`, `gen-src/`, or whatever
+the repo declares as its generated tree — is off-limits. Generators own those
+files end-to-end; an edit there is silently overwritten on regeneration,
+leaving no trace of why.
 
-- The canonical names are `_generated/` and `gen-src/`, but the repo's own
-  declaration (in its README, a `specfuse.yaml`, or equivalent config) is
-  authoritative. If your repo's generated directory uses a different name, treat
-  that name with identical prohibition.
-- The rule applies to every file under the directory, recursively. Creating a new
-  file inside a generated directory is still a write to that directory.
-- The rule applies regardless of whether the file currently exists.
+- Canonical names are `_generated/` and `gen-src/`, but the repo's own
+  declaration (README, `specfuse.yaml`, equivalent config) is authoritative;
+  a differently-named generated directory gets identical treatment.
+- Applies to every file under the directory recursively, including a new file
+  created there, and regardless of whether the file currently exists.
 
-When a generated file is wrong, the response is to change the spec or the generator
-that produced it, not the file itself. If that is outside this unit's boundary,
-signal blocked with the spec/generator change named.
+When a generated file is wrong, change the spec or generator that produced
+it, not the file itself. If that is outside this unit's boundary, signal
+blocked with the spec/generator change named.
 
 ## 2. Secrets and credentials
 
 Secrets include, at minimum: API tokens, deploy keys, SSH private keys, OAuth
-client secrets, webhook signing secrets, database passwords, `.env` files, cloud
-credentials (AWS, GCP, Azure), and any file conventionally holding a credential
+client secrets, webhook signing secrets, database passwords, `.env` files,
+cloud credentials (AWS, GCP, Azure), and any file conventionally holding one
 (`*.pem`, `*.key`, `id_rsa*`, `credentials.json`, `.npmrc` tokens, `gh auth`
 tokens).
 
 You must not:
 
-- Read the contents of a secrets file. If a unit requires one, see
+- Read a secrets file's contents. If a unit requires one, see
   [`security-boundaries.md`](security-boundaries.md) for the escalation path.
-- Write any value that looks like a credential into the RESULT block, the event
-  log, a commit, or any artifact you produce — whether the value came from a real
-  secret or was invented.
-- Echo the contents of environment variables that hold secrets. Reference them by
-  name (`$GITHUB_TOKEN`) over reading their values.
-- Commit secret files to the repo under any circumstance, including as examples
-  or fixtures.
+- Write anything credential-looking into the RESULT block, event log, a
+  commit, or any produced artifact — whether real or invented.
+- Echo secret-holding environment variables. Reference by name
+  (`$GITHUB_TOKEN`) over reading their values.
+- Commit secret files under any circumstance, including as examples or
+  fixtures.
 
 ## 3. `.git/` internals
 

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/data/rules/result-contract.md

@@ -13,15 +13,15 @@ driver re-runs verification itself, and that is what decides done.
 ## Who reads it — emit it only when something does
 
 This block is a **machine interface**, not a report. Emit it when a program is
-on the other end: a work-unit session the driver dispatched (always), or a skill
-invoked **non-interactively** from a calling program that parses the outcome
-(`fix-bug` under `autofix_invoke` is the live example).
+on the other end: a work-unit session the driver dispatched (always), or a
+skill invoked **non-interactively** from a calling program that parses the
+outcome (`fix-bug` under `autofix_invoke` is the live example).
 
-Do **not** emit it on an interactive run. A human who typed `/pick-feature` has
-no parser; the block lands as a slab to scroll past, which is the verbosity
-[`human-output.md`](human-output.md) exists to prevent — report to them per that
-rule instead. When in doubt, look at who invoked you: a slash command typed by a
-person is interactive; a `claude -p` dispatch is not.
+Do **not** emit it on an interactive run — a human who typed `/pick-feature`
+has no parser, and the block lands as a slab to scroll past, the verbosity
+[`human-output.md`](human-output.md) exists to prevent. Report to them per
+that rule instead. When in doubt: a slash command typed by a person is
+interactive; a `claude -p` dispatch is not.
 
 ## The cycle: state intent, act, verify, report
 
@@ -33,25 +33,25 @@ cycle; this file is normative on how the loop surface reports step 4.
    the unit is not what you thought it was.
 2. **Act.** Stay inside that scope. "While I was here I also fixed X" is drift;
    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. 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.
+3. **Verify.** Re-read what you produced — Write/Edit reports the action taken,
+   not the property you wanted — and run the work unit's own 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
+   verification. A behavioural claim needs a run, not a source reading; 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 **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
-boundary).
+A failing check leaves you in one of three situations: correctable locally
+(fix the cause, re-run the **whole narrow tier** from the top), spinning
+(three fresh attempts is the driver's budget — emit `status: blocked` with
+evidence rather than guessing), or fundamentally blocked (spec ambiguity,
+generated code that must change, a missing dependency — emit `status: blocked`
+naming the boundary).
 
 ## Format
 
@@ -59,6 +59,7 @@ boundary).
 ```result
 status: complete | blocked        # complete = "I believe acceptance criteria are met"
 summary: <one sentence on what changed>
+forward_note: <optional — one sentence on what the NEXT unit should know>
 files_changed:
   - path/to/file
 acceptance_criteria:
@@ -72,6 +73,13 @@ produces_unchanged:               # optional — closing obligation 1 below
 ```
 ````
 
+`summary` is backward-looking by this contract's own definition — one sentence
+on what changed. `forward_note` is the other half: what surprised you, or what
+the next unit should know, that `summary` does not capture. It is optional and
+never required by any guard. Omit it and nothing changes: the driver's
+`PROGRESS.md` entry is exactly what it would have written without this field
+(FEAT-2026-0106/T02).
+
 ## Rules
 
 1. **No git.** You edit files only. The driver stages, squashes, and commits one
@@ -94,29 +102,29 @@ produces_unchanged:               # optional — closing obligation 1 below
 7. **A "pre-existing" failure claim cites the commit it was measured on.**
    Calling a failure pre-existing is a claim about a *different* commit —
    typically the merge-base — and nothing observed on your own branch
-   establishes it. Name the command and the commit, give the numbers from both
-   sides, and emit `status: blocked` rather than asserting a baseline you could
-   not measure: a mass of errors sharing one signature (network refused,
-   unresolvable build dependencies) is a report about where the suite ran, not
-   about the repository (#2075).
+   establishes it. Name the command and commit, give the numbers from both
+   sides, and emit `status: blocked` rather than asserting an unmeasured
+   baseline: a mass of errors sharing one signature (network refused,
+   unresolvable build dependencies) reports where the suite ran, not the
+   repository (#2075).
 
 ## Closing obligations for implementation WUs (FEAT-2026-0049)
 
 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 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`.
+   path under `produces_unchanged:` — 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`.** Put the
+   finding in `blocked_reason`; never write it into a gate document and close
+   `complete`.
 3. **Every `evidence:` cites an executed command** and its observed exit
-   code/output. Reading source, grepping for a string, or citing another WU's
+   code/output. Reading source, grepping a string, or citing another WU's
    RESULT is not verification.
-4. **Analysis without edits is not a silent attempt.** Say so explicitly and end
+4. **Analysis without edits is not a silent attempt.** Say so and end
    `blocked` rather than spending the attempt on prose.
 
 The driver's whole cycle — re-verify, commit, advance the dependency frontier,

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/data/rules/security-boundaries.md

@@ -12,10 +12,8 @@ lists the specific path categories that are off-limits.
 
 ## Secrets
 
-Secrets include API tokens, deploy keys, SSH private keys, OAuth client secrets,
-webhook signing secrets, database passwords, `.env` files, cloud credentials, and
-anything conventionally treated as a credential (see the enumeration in
-[`never-touch.md`](never-touch.md) §2). The posture is strict:
+The full enumeration lives in [`never-touch.md`](never-touch.md) §2. The
+posture here is strict:
 
 - **Never read.** Do not open a secrets file to inspect its contents, not even
   "just to see the format." If a unit's verification needs one, stop and
@@ -41,29 +39,27 @@ Treat suspected-secret values with the same care as confirmed-secret values. A
 ## When a work unit appears to require privileged access
 
 A unit whose acceptance criteria or verification commands appear to require
-reading a secret, editing generated code directly, or any other privileged action
-is almost always a unit-definition problem, not a license to break the rule.
-
-1. **Stop.** Do not attempt the privileged action. Do not attempt to work around
-   the requirement (for example, by running a command that reads the secret
-   implicitly).
-2. **Re-read the unit.** Verify you have understood the step correctly. Often the
-   unit describes how the *human* will verify, with the session doing an
-   upstream-only step.
-3. **If the requirement is genuine, signal blocked.** Name the privilege
-   required (e.g., "verification command requires reading `config/db-prod.env`")
-   as the blocked reason. Work halts and the human decides whether to adjust the
-   unit, run the step out-of-band, or provide a scoped credential. (The signal is
-   surface-specific — a `status: blocked` RESULT on the loop, a `blocked_*`
-   transition on the orchestrator.)
-4. **Do not report the unit complete.** A verification that could not be run is
-   not a verification; a unit whose verification cannot be run is not done (see
-   [`verification-discipline.md`](verification-discipline.md)).
-
-The common mistake here is to "helpfully" substitute a weaker check for a
-privileged one — "I couldn't run the secret-requiring command, so I inspected the
-diff visually and it looks right." That is a verification-bypass, not a
-verification, and it produces a RESULT block the driver cannot trust.
+reading a secret, editing generated code directly, or any other privileged
+action is almost always a unit-definition problem, not license to break the
+rule.
+
+1. **Stop.** Do not attempt the privileged action, or work around it (e.g. a
+   command that reads the secret implicitly).
+2. **Re-read the unit.** Often it describes how the *human* verifies, with the
+   session doing an upstream-only step.
+3. **If genuine, signal blocked.** Name the privilege required (e.g.
+   "verification command requires reading `config/db-prod.env`") as the
+   blocked reason; the human decides whether to adjust the unit, run the step
+   out-of-band, or provide a scoped credential. (Surface-specific — a
+   `status: blocked` RESULT on the loop, a `blocked_*` transition on the
+   orchestrator.)
+4. **Do not report complete.** A verification that could not be run is not a
+   verification (see [`verification-discipline.md`](verification-discipline.md)).
+
+The common mistake is substituting a weaker check for a privileged one — "I
+couldn't run the secret-requiring command, so I inspected the diff visually."
+That is a verification-bypass, and it produces a RESULT block the driver
+cannot trust.
 
 ## Authenticated tooling
 

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/data/rules-local/README.md

@@ -40,4 +40,24 @@ Follow the shipped rules' format: one failure mode per rule, the check stated
 imperatively, provenance recorded so the reasoning survives the rule (see
 `.specfuse/rules/planning-discipline.md` for the model).
 
+## The shared word budget
+
+The `.claude/CLAUDE.md` binding rules block a work-unit session is dispatched
+against is capped at 2,500 words total, and every rule you add here counts
+against that one shared budget alongside the loop's own rules — this is not a
+free directory. `.specfuse/rules-local/learnings-distilled.md`, the
+LEARNINGS-derived distillate, carries its own 500-word sub-budget inside that
+total; its content is decided by a human accept step
+(`apply_distilled_decisions` in `specfuse/loop/loop.py`) that cuts a ranked
+proposal to the sub-budget, not to an entry count. Before adding an entry to
+that distillate or to a rule here, check whether a guard or lint already
+enforces it — if so, it does not belong in the block: the block is for what a
+session must be *told*, not for what tooling already *checks*.
+
+The ranking's `reach` field (count of other feature files citing an entry) is
+a tiebreaker with an age bias, not a ranking: it inflates on its own
+visibility and favors older entries. Neither `reach` nor the entry's recorded
+cost measures whether the rule actually improves a session's work — that
+judgment call is still the accept step's, made by reading the entry.
+
 This README is seeded once and never overwritten — edit it freely.

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/data/schemas/driver-event.schema.json

@@ -3,7 +3,7 @@
   "$id": "https://specfuse.dev/loop/schemas/driver-event.schema.json",
   "title": "Driver-local envelope registry",
   "description": "Additive to the vendored orchestrator envelope (event.schema.json): shapes the loop driver emits with no orchestrator-side counterpart. validate_event.py resolves each shape against the vendored envelope first; only when absent there does it fall through to this registry. `event_types` (FEAT-2026-0060) widens the event_type enum; task_started, task_completed, and human_escalation are already sanctioned in the vendored enum and must not be duplicated here. `correlation_id` (FEAT-2026-0073) widens the correlation_id pattern to admit the closing-sequence and hygiene shapes `.specfuse/rules/correlation-ids.md` documents; `closing_names` and `hygiene_suffix_pattern` here must state the same set of shapes as that rules file's combined pattern (and as specfuse/loop/lint_plan.py's CORRELATION_ID_RE, which independently enforces the same contract on PLAN.md graphs).",
-  "$comment": "FEAT-2026-0060/T01: event_types derived from the union of every build_event(...) call site in specfuse/loop/loop.py and a corpus sweep of every .specfuse/features/*/events.jsonl, subtracting the vendored envelope enum. attempt_outcome and gate_reached were already-known precedent (loop.py's build_arm_predicate_event docstring); auto_close_decision, arm_predicate_evaluated, re_arm_dispatched, plan_next_draft_lint, and unsandboxed_dispatch are additional driver-local mechanics the orchestrator has no concept of. gate_auto_armed (loop.py build_event call under gate_events.append) and re_arm_rejected (loop.py build_event call under the spinning_reproduction_missing re-arm check) are emitted by real code paths that have never fired in a recorded run, so a corpus-only sweep cannot see them; they are included because call-site derivation does. FEAT-2026-0073/T01: correlation_id added — closing_names and hygiene_suffix_pattern mirror correlation-ids.md's documented shapes and lint_plan.py's CORRELATION_ID_RE verbatim, so the envelope, the rules file, and the PLAN-graph linter state one contract. FEAT-2026-0075/T03: driver_staleness_detected added — emitted at gate completion when a work unit's squash diff touched the driver's own importable surface, naming the editing unit, the driver paths it touched, and the IDs of units this process dispatched afterward (which ran the pre-edit module). FEAT-2026-0100/T02: judged added — emitted once per terminal close after the closing-deliverable guards, carrying the close's own verdict, the judge session's verdict (null when the judge was disabled, timed out, or returned nothing parseable, with the reason beside it), and whether the judge lowered it. FEAT-2026-0109/T01: baseline_attribution added — emitted when the retroactive per-attempt-failure baseline probe (attribute_failure_to_baseline) runs fresh, carrying the gate, the failing-gate set, and the unit whose failed attempt triggered the probe. FEAT-2026-0109/T06: broad_run_result added — emitted whenever the once-per-gate broad verification pass (gate_broad_run_check) actually runs (never on a tree-unchanged dedup skip), carrying the gate, the tree it was measured on, and its pass/fail outcome; a failing broad run additionally raises the existing human_escalation event type with reason: broad_run_gate_failure, which needs no schema addition since human_escalation is already sanctioned in the vendored envelope enum. FEAT-2026-0109/T08: driver_build_pinned added — emitted once per process, before any work unit is dispatched, when this process is itself a materialized pin (`_reexec_pinned`); carries the pin's tree hash and its path so an operator or test can read what build actually ran without inferring it from `ps` output. `driver_staleness_detected` needed no addition here: this unit reuses it with `halted: false` for the pinned, non-halting case (the registry constrains the type list, not the payload), adding `pinned_tree` / `next_pin_tree` fields alongside the existing `halted: true` shape.",
+  "$comment": "FEAT-2026-0060/T01: event_types derived from the union of every build_event(...) call site in specfuse/loop/loop.py and a corpus sweep of every .specfuse/features/*/events.jsonl, subtracting the vendored envelope enum. attempt_outcome and gate_reached were already-known precedent (loop.py's build_arm_predicate_event docstring); auto_close_decision, arm_predicate_evaluated, re_arm_dispatched, plan_next_draft_lint, and unsandboxed_dispatch are additional driver-local mechanics the orchestrator has no concept of. gate_auto_armed (loop.py build_event call under gate_events.append) and re_arm_rejected (loop.py build_event call under the spinning_reproduction_missing re-arm check) are emitted by real code paths that have never fired in a recorded run, so a corpus-only sweep cannot see them; they are included because call-site derivation does. FEAT-2026-0073/T01: correlation_id added — closing_names and hygiene_suffix_pattern mirror correlation-ids.md's documented shapes and lint_plan.py's CORRELATION_ID_RE verbatim, so the envelope, the rules file, and the PLAN-graph linter state one contract. FEAT-2026-0075/T03: driver_staleness_detected added — emitted at gate completion when a work unit's squash diff touched the driver's own importable surface, naming the editing unit, the driver paths it touched, and the IDs of units this process dispatched afterward (which ran the pre-edit module). FEAT-2026-0100/T02: judged added — emitted once per terminal close after the closing-deliverable guards, carrying the close's own verdict, the judge session's verdict (null when the judge was disabled, timed out, or returned nothing parseable, with the reason beside it), and whether the judge lowered it. FEAT-2026-0109/T01: baseline_attribution added — emitted when the retroactive per-attempt-failure baseline probe (attribute_failure_to_baseline) runs fresh, carrying the gate, the failing-gate set, and the unit whose failed attempt triggered the probe. FEAT-2026-0109/T06: broad_run_result added — emitted whenever the once-per-gate broad verification pass (gate_broad_run_check) actually runs (never on a tree-unchanged dedup skip), carrying the gate, the tree it was measured on, and its pass/fail outcome; a failing broad run additionally raises the existing human_escalation event type with reason: broad_run_gate_failure, which needs no schema addition since human_escalation is already sanctioned in the vendored envelope enum. FEAT-2026-0109/T08: driver_build_pinned added — emitted once per process, before any work unit is dispatched, when this process is itself a materialized pin (`_reexec_pinned`); carries the pin's tree hash and its path so an operator or test can read what build actually ran without inferring it from `ps` output. `driver_staleness_detected` needed no addition here: this unit reuses it with `halted: false` for the pinned, non-halting case (the registry constrains the type list, not the payload), adding `pinned_tree` / `next_pin_tree` fields alongside the existing `halted: true` shape. FEAT-2026-0104/T04: replan added — emitted once a re-plan turn (T03's run_replan_turn) rewrites a unit's body ahead of its last permitted attempt, so gate_eval.py's evaluate_auto_close (check 2, already reading this event_type since FEAT-2026-0018/T02) can disable auto-close for a gate that needed one.",
   "event_types": [
     "attempt_outcome",
     "gate_reached",
@@ -19,7 +19,8 @@
     "judged",
     "baseline_attribution",
     "broad_run_result",
-    "driver_build_pinned"
+    "driver_build_pinned",
+    "replan"
   ],
   "correlation_id": {
     "closing_names": [

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/data/verification.yml.example

@@ -121,6 +121,12 @@
 # defaults:
 #   max_attempts: 3
 #   retain_on_guard_refusal: true
+#
+# The re-plan-after-two-failures behaviour (FEAT-2026-0104) reads this same
+# `max_attempts` resolution and adds no config key of its own — a unit's
+# next-to-last attempt re-plans instead of retrying verbatim, governed
+# entirely by the ceiling above (or a WU's own `max_attempts`) plus that WU's
+# `iterate_on_failure` flag.
 
 code:
   - name: tests

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/gate_eval.py

@@ -302,6 +302,34 @@ def evaluate_auto_close(feature_dir: Path, gate_id: int) -> AutoCloseDecision:
             predicate_version=PREDICATE_VERSION,
         )
 
+    return _evaluate_predicate_core(feature_dir, gate_id, plan, feature_id)
+
+
+def evaluate_off_plan_signal(feature_dir: Path, gate_id: int) -> AutoCloseDecision:
+    """Same predicate as `evaluate_auto_close`, but never short-circuited by
+    `auto_close_disabled` (FEAT-2026-0106/T03).
+
+    `auto_close_disabled` is an operator's administrative choice to always
+    dispatch a close for ceremony/oracle re-run reasons
+    (`close-discipline.md` — a "load-bearing" close always sets it) and says
+    nothing about whether the gate itself deviated from plan. A caller asking
+    "did this gate go off plan" — as opposed to "is this gate eligible to
+    auto-close" — needs the real blocked/replan/cost-overrun evidence even
+    when that flag is set, so this skips straight to `_evaluate_predicate_core`.
+    """
+    plan = _read_plan_metrics(feature_dir)
+    fm = plan["frontmatter"]
+    feature_id = fm.get("feature_id", feature_dir.name)
+    return _evaluate_predicate_core(feature_dir, gate_id, plan, feature_id)
+
+
+def _evaluate_predicate_core(
+    feature_dir: Path, gate_id: int, plan: dict, feature_id: str,
+) -> AutoCloseDecision:
+    """The v1 predicate itself, shared by `evaluate_auto_close` and
+    `evaluate_off_plan_signal` — everything after the `auto_close_disabled`
+    short-circuit those two apply differently.
+    """
     # Locate target gate in task graph
     gates = plan["gates"]
     target_gate = next((g for g in gates if g.get("gate") == gate_id), None)

{specfuse_loop-0.19.0 → specfuse_loop-0.20.0}/specfuse/loop/judge.py

@@ -167,6 +167,25 @@ def strip_forbidden_sections(text: str) -> str:
     return result
 
 
+# The driver, not the close, owns terminal-flip state: `fire_terminal_flips`
+# writes PLAN.md's status, the roadmap row and the gate's own status AFTER a
+# judge returns, and only when the verdict is `met`. So at judge time all three
+# necessarily read un-flipped, on every close of every feature.
+# `GATE.template.md` nevertheless copies a criterion about them into every
+# gate's definition of done, and a judge that reads it literally lowers the
+# verdict -- which guarantees the state stays as found, so a re-close runs a
+# fresh judge against identical evidence and reaches the identical verdict.
+# FEAT-2026-0104 deadlocked there for one close (#3307). Strip the criterion
+# here; `render_judge_prompt` says why, because stripping alone only stops the
+# reminder -- the judge can still go and read the roadmap itself.
+_DRIVER_OWNED_STATUS_CRITERION = re.compile(
+    r"^[ \t]*[-*][ \t]+Documentation and roadmap status[^\n]*\n?", re.M)
+
+
+def _strip_driver_owned_status_criterion(text: str) -> str:
+    return _DRIVER_OWNED_STATUS_CRITERION.sub("", text or "")
+
+
 def _clean_evidence(text: str) -> str:
     return truncate_evidence(strip_forbidden_sections(text or ""))
 
@@ -224,7 +243,8 @@ def build_judge_bundle(
 
     return JudgeBundle(
         gate_number=gate_number,
-        definition_of_done=_clean_evidence(definition_of_done),
+        definition_of_done=_clean_evidence(
+            _strip_driver_owned_status_criterion(definition_of_done)),
         criteria=criteria,
         diff_text=_clean_evidence(diff_text),
         measurements=_clean_evidence(measurements_text),
@@ -272,6 +292,12 @@ did not do this work and have no stake in the answer.
    one. The measurements it recorded are already below.
 5. Change nothing. You run no git command, edit no file, and fix nothing you
    find. You report.
+6. `PLAN.md`'s status, the roadmap row, and this gate's own status are not
+   evidence and are not yours to grade. The driver writes all three after you
+   return, and only if you answer `met` — so while you are looking at them they
+   necessarily read un-flipped, on every close of every feature. Reading one of
+   them as a failure is a verdict that manufactures its own evidence: it keeps
+   them un-flipped, and the next judge sees exactly what you saw.
 
 ## Definition of done (gate {bundle.gate_number})