specfuse-loop 0.3.20__tar.gz → 0.3.22__tar.gz

{specfuse_loop-0.3.20/specfuse_loop.egg-info → specfuse_loop-0.3.22}/PKG-INFO

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

{specfuse_loop-0.3.20 → specfuse_loop-0.3.22}/pyproject.toml

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

specfuse_loop-0.3.22/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.22

specfuse_loop-0.3.22/specfuse/loop/data/rules/planning-discipline.md

@@ -0,0 +1,119 @@
+<!--
+Copyright 2026 Specfuse Contributors
+Licensed under the Apache License, Version 2.0. See LICENSE.
+-->
+
+# Rule: planning discipline
+
+Encodes hard-won discipline from feature retrospectives — the checks that, applied
+at design and arming time, would have prevented the most expensive re-plans. Each
+check below is cheap (a grep, a sentence, a table, one local run) and guards a
+failure mode that cost multiple gates when skipped. Provenance is named per check so
+the reasoning survives the rule (the FEAT-2026-0049 / F1–F4 references resolve in the
+retrospective of the specfuse-generator dogfood feature that motivated these checks).
+
+These are **binding at draft, plan-next, and arm time**. A gate armed in violation
+of any check is not ready, regardless of what a WU's frontmatter says.
+
+## 1. Existing-mechanism search — before designing any enforcement or measurement
+
+Before an ADR designs a validation rule, a severity level, an enforcement gate, or a
+measurement, it must first establish that the mechanism does not already exist. The
+ADR is **incomplete** without this section.
+
+- **Grep the inventory.** Search the directory that holds the mechanism's
+  siblings — for a validation rule, the project's rules directory (e.g.
+  `grep -rl <concept> <path/to/validation/rules/>`); for an artifact, the
+  tool's own inventory command (e.g. `<tool> templates`); for any other
+  check, the directory that holds its siblings.
+- **Record the grep command and its verdict** in the ADR — the exact command, and
+  either "no existing mechanism, building new" or "found `<X>`, reusing / extending
+  it". A verdict of "reusing" that then builds new anyway must say why.
+- **Read the javadoc/description of anything the grep surfaces.** A rule that already
+  covers the property may say so in its own words.
+
+> **Provenance (FEAT-2026-0049 / F3).** The feature spent three gates building a
+> `WARNING→ERROR` ladder on a new rule while the enforcement it needed already existed
+> in `RelationshipSymmetryValidationRule` — whose javadoc (F-029, 2026-05-29) literally
+> said the debt "surfaces as a Saturday-night surprise when the inference rule changes."
+> A one-line grep of the rules directory at ADR time would have found it. Cost: two
+> gates and a full pivot.
+
+## 2. Escalation-predicate satisfiability — for any severity flip
+
+Any plan that raises a check to `ERROR`, flips a `WARNING` to blocking, or asserts a
+"zero issues" close predicate must answer, in writing, one question:
+
+> **What does this rule report on a spec/input already in its intended final state?**
+
+If the answer is anything other than **zero**, the predicate is **unsatisfiable** —
+the rule fires on correct inputs, so "zero issues" can never be reached and the
+severity flip forces wrong changes. **Stop and redesign** before arming: fix the rule
+so a correct input reports zero, or route enforcement to a different mechanism (see §1).
+
+> **Provenance (FEAT-2026-0049 / F3).** ADR D3 ("omission = intent — a non-owning
+> reference is declared by omission") and D6 ("`ERROR` when the rule reports zero
+> issues") contradicted each other inside the same document: post-flip, every correct
+> omission still tripped the rule, so "zero" was unreachable. The contradiction was
+> answerable by reading the ADR against itself. Separately, the *shipped* rule
+> false-positived ~35 of 49 on real specs (#821) — a severity flip forcing wrong
+> changes, exactly what this check prevents.
+
+## 3. Flag-scope table — for any WU introducing or flipping a behavior flag
+
+A WU that introduces, gates on, or flips a behavior flag must contain a **flag-scope
+table**: every code path the flag is claimed to affect, marked *gated* / *not gated*,
+with a one-line *why* per row. The arming review checks the feature's headline claim
+("the flip retires inference", "the flag makes X strict") against the table — a claim
+the table does not support is a scope mismatch, and scope mismatches surface gates
+later as defects, not at arming.
+
+| Code path | Gated by flag? | Why |
+|---|---|---|
+| `<path/method>` | yes / no | <one line> |
+
+> **Provenance (FEAT-2026-0049 / F1).** The plan enumerated both inference paths
+> (bare-FK and `$ref`) on day one, but no document ever crossed "which paths does the
+> `explicitRelationshipsOnly` flag gate" against "the flip retires inference." The flag
+> was built FK-path-only, deliberately and correctly — but the mismatch with the
+> headline claim surfaced two gates later (F1), and again as a runtime defect (F4).
+
+## 4. Runtime probe before arming a default/severity flip
+
+A gate whose WUs flip a **default value** or a **severity** may **not** be armed on
+"mechanical, nothing design-open." Before arming, apply the change locally and run the
+**exact command the WU's tests gate will run** (the full oracle, not a subset), and
+paste the resulting failure list into the gate review. The probe is the arming
+evidence; "nothing design-open" without it is a claim, not a fact.
+
+- Run the *full* oracle. A subset hides failures in the paths the change touches that
+  the subset does not exercise.
+- The probe's failure list becomes the WU's enumerated test surface — the WU no longer
+  discovers its own breakage attempt by attempt.
+
+> **Provenance (FEAT-2026-0049 / F4).** Gate 4 was armed on "nothing is design-open"
+> without ever applying the default flip and running the full suite once. The WU then
+> spun three times (~$14) on a real defect that one local run exposed in seconds — and
+> the first two diagnoses were made against a *subset*, missing failures the full suite
+> showed. Contrast: an earlier gate's "measure before drafting" probe (a `WARNING` run
+> over the real specs) worked and correctly shrank the next WU's scope.
+
+## 5. Planning-WU cost floor
+
+`plan-next` and `close` / `close-intermediate` WUs are systematically under-estimated.
+When drafting their `planned_cost_usd`, use a **floor of $5.00** — never the $2–3 that
+"it's just bookkeeping" suggests. A gate `cost_budget_usd` set to the sum of $2–3
+planning estimates is a brake that fires by construction on the first real close.
+
+> **Provenance (FEAT-2026-0049 + LEARNINGS [FEAT-2026-0044]).** Planning/close WUs ran
+> 2.8–5.2× their $2–3 estimates: `plan-next` at $5.90 and $15.65, `close-intermediate`
+> at $5.67, against $2–3 drafts. LEARNINGS `[FEAT-2026-0044]` had already predicted this
+> systematic under-estimation; the floor makes the prediction binding.
+
+## Why these live together
+
+Each is a one-time check that trades a minute at design/arm time against a gate (or
+three) of rework. They share a root: **automation and authors both trust a claim
+without the cheap check that would test it** — a grep not run (§1), a contradiction not
+read (§2), a scope not tabled (§3), a suite not run (§4), an estimate not calibrated
+(§5). State the check, run it, record the verdict. Every plan, every arm.

{specfuse_loop-0.3.20 → specfuse_loop-0.3.22}/specfuse/loop/data/rules/result-contract.md

@@ -107,6 +107,33 @@ blocked_reason: <present only when status is blocked>
 5. **No secret-looking values in evidence.** The RESULT block is read by the driver
    and may be archived. See [`security-boundaries.md`](security-boundaries.md).
 
+## Closing obligations for implementation WUs (FEAT-2026-0049)
+
+Four binding obligations before `status: complete`. Each guards a way a prior WU
+closed on nothing:
+
+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
+   explicitly: "no change needed because X; here is the evidence the deliverable
+   already holds: `<command + output>`." Silence on an unchanged deliverable is not
+   a valid close. (The driver enforces this mechanically since specfuse-loop 0.3.21
+   — #198, outcome `produces_not_in_diff`; the obligation binds regardless of
+   driver version.)
+2. **A plan-level contradiction is `blocked`, not `complete`.** If mid-WU you find
+   the plan cannot be delivered as written (a decision contradicts another, a
+   deliverable cannot exist), emit `status: blocked` with the finding in
+   `blocked_reason`. Never write the finding into a gate document and close
+   `complete`. `complete` means the deliverables exist; `blocked` means they cannot
+   or should not.
+3. **Every `evidence:` cites an executed command** — its observed exit code/output.
+   Reading source, grepping for a string, or citing another WU's RESULT is not
+   verification. For a validation-rule or severity claim the evidence must include a
+   negative observation (the rule seen rejecting a purpose-built bad input); see
+   [`verification-discipline.md`](verification-discipline.md) §3.
+4. **Analysis without edits is not a silent attempt.** If an attempt produces
+   analysis but no file edits, say so explicitly and end `blocked` (or with a
+   concrete next-edit plan). Do not exhaust the attempt on prose.
+
 ## Why this matters
 
 The driver's trust model is that the RESULT block is an honest claim about what

{specfuse_loop-0.3.20 → specfuse_loop-0.3.22}/specfuse/loop/data/rules/verification-discipline.md

@@ -39,6 +39,12 @@ Two generic meanings, both apply unless the unit narrows the scope:
   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.
+- **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
+  run proves it. For any rule or severity claim, include a **negative observation**:
+  the rule seen rejecting a purpose-built bad input. A rule that fires on nothing
+  passes every test.
 
 **Verification is the exit oracle.** The agent's own report is advisory; done is
 decided by the checks passing, not by the agent's belief. If a check fails you are

specfuse_loop-0.3.22/specfuse/loop/data/rules-local/README.md

@@ -0,0 +1,43 @@
+<!--
+Copyright 2026 Specfuse Contributors
+Licensed under the Apache License, Version 2.0. See LICENSE.
+-->
+
+# Project-authored rules (`rules-local/`)
+
+This directory belongs to **your project**, not to Specfuse. Put binding rules
+here that are specific to this repository — its tools, its paths, its failure
+modes — and that should survive every scaffold upgrade.
+
+**The contract:** `specfuse upgrade` never writes, overwrites, or prunes
+anything in `rules-local/`. That is the opposite of the sibling
+`.specfuse/rules/` directory, which is versioned: upgrades overwrite its files
+with the shipped versions and delete files the shipped scaffold no longer
+carries. A project rule placed in `rules/` will be lost on upgrade; the same
+rule placed here is permanent.
+
+## When to write a rule here vs. upstream
+
+- **Here:** the rule names your project's directories, commands, tools, or
+  conventions ("grep `src/main/java/.../validation/rules/` before designing a
+  rule", "the generator jar's `templates` command lists artifacts"). Upstream
+  would have to genericize away exactly the specifics that make it useful to
+  you.
+- **Upstream (a PR to the scaffold's `rules/`):** the failure mode is
+  project-agnostic and other Specfuse projects would hit it too. Keep the
+  provenance; genericize the examples.
+
+## Wiring a rule into the loop
+
+Rules load via the `@`-references in your `.claude/CLAUDE.md` Specfuse rules
+block. Add one line per rule you author:
+
+```markdown
+@.specfuse/rules-local/<your-rule>.md
+```
+
+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).
+
+This README is seeded once and never overwritten — edit it freely.

{specfuse_loop-0.3.20 → specfuse_loop-0.3.22}/specfuse/loop/data/templates/GATE.template.md

@@ -30,6 +30,23 @@ here for human review-and-arm: read the review artifact, accept or edit the draf
 next-gate work units, flip the accepted ones to `pending`, set this gate's status to
 `passed`, and re-run.
 
+## Arming discipline (see `.specfuse/rules/planning-discipline.md`)
+
+Before flipping this gate's next-gate WUs to `pending`:
+
+- **Runtime probe for a default/severity flip (§4).** If any WU in the gate being armed
+  flips a **default value** or a **severity**, it may **not** be armed on "mechanical,
+  nothing design-open." Apply the change locally, run the **exact command the WU's tests
+  gate will run** (the full oracle, not a subset), and paste the failure list into
+  `GATE-NN-REVIEW.md`. That list becomes the WU's enumerated test surface. Arming such a
+  gate without a probe is what makes an implementation WU spin on a defect one local run
+  would have shown.
+- **Flag-scope table (§3).** If a WU introduces or flips a behavior flag, confirm it
+  carries a flag-scope table and that the feature's headline claim matches it.
+- **Escalation-predicate satisfiability (§2).** If a WU raises a check to `ERROR` or
+  asserts a "zero issues" predicate, confirm PLAN.md answered "what does the rule report
+  on a correct input" and that the answer is zero.
+
 ## Reflection notes
 
 <Written by the human at review time. What surprised you, what you changed in the

{specfuse_loop-0.3.20 → specfuse_loop-0.3.22}/specfuse/loop/data/templates/PLAN.template.md

@@ -23,6 +23,32 @@ each WU file owns its own status, and each GATE file owns its gate's status. Det
 only as far as the next gate; plan-next drafts the gate after that from the
 retrospective and lessons.
 
+## Existing-mechanism search (mandatory — see `.specfuse/rules/planning-discipline.md` §1)
+
+Before any ADR or gate designs a validation rule, a severity level, an enforcement
+gate, or a measurement, establish that it does not already exist. **An ADR without
+this section is incomplete.** If this feature designs no such mechanism, write
+exactly `n/a — no enforcement or measurement designed` and stop — do not fabricate
+a grep to fill the section.
+
+- **Grep command run:** `<the exact command — e.g. grep -rl <concept>
+  src/main/java/.../validation/rules/>`
+- **Verdict:** `<"no existing mechanism, building new" | "found <X>, reusing/extending">`
+- **If reusing:** name `<X>` and quote the line of its javadoc/description that
+  confirms it covers the property. If building new despite a hit, say why the hit does
+  not suffice.
+
+## Escalation-predicate satisfiability (mandatory for any severity flip — §2)
+
+If this feature raises a check to `ERROR`, flips a `WARNING` to blocking, or asserts a
+"zero issues" close predicate, answer here:
+
+- **What does the rule report on an input already in its intended final state?**
+  `<answer>`
+- If that answer is **not zero**, the predicate is unsatisfiable — the rule fires on
+  correct inputs. **Redesign before drafting gates:** fix the rule so a correct input
+  reports zero, or route enforcement to the mechanism found in the search above.
+
 ## Task graph
 
 ```yaml

{specfuse_loop-0.3.20 → specfuse_loop-0.3.22}/specfuse/loop/data/templates/WU.template.md

@@ -28,6 +28,10 @@ AUTHOR-SET FIELDS — fill or override these at draft/arm time:
   `xhigh` | `max`. Absent → type-keyed default. `low`/`medium` add a terseness directive.
 - `planned_cost_usd` — OPTIONAL. Estimated USD at draft time. Compared against actual in close
   WU's cost analysis. Lint WARN when absent on active/draft WUs (non-blocking).
+  **Planning-WU cost floor (`.specfuse/rules/planning-discipline.md` §5):** for `plan-next`,
+  `close`, and `close-intermediate` WUs, draft `planned_cost_usd` at a **floor of $5.00** — these
+  run 2.8–5.2× the $2–3 that "it's just bookkeeping" suggests. A gate `cost_budget_usd` set to
+  the sum of $2–3 planning estimates is a brake that fires by construction on the first real close.
 - `generated_surfaces` — OPTIONAL. Paths to generated files this unit's acceptance depends on.
 - `oracle_env` — OPTIONAL. Environment the verifying oracle runs in: `macos_local`,
   `linux_docker`, `github_actions_ci`, or an operator-named string. Lint WARN when AC mentions
@@ -77,6 +81,17 @@ cheapest hollow-pass guard; see `/authoring-work-units` §12 for the contract an
 the carve-outs (refactor, migration, pure-data → explicit `Red-test exempt:
 <reason>` line in the WU body).
 
+**Flag-scope table** (REQUIRED only when this WU introduces, gates on, or flips a
+behavior flag; omit otherwise — see `.specfuse/rules/planning-discipline.md` §3). Every
+code path the flag is claimed to affect, marked gated / not gated, with a one-line why.
+The arming review checks the feature's headline claim ("the flip retires X") against
+this table; a claim the table does not support is a scope mismatch that surfaces as a
+defect gates later.
+
+| Code path | Gated by flag? | Why |
+|---|---|---|
+| `<path/method>` | yes / no | <one line> |
+
 **Do not touch.** Generated directories (`_generated/`, `gen-src/`, or the repo's
 declared equivalent), files owned by other work units in this gate, secrets,
 `.git/`. The driver owns all git operations — you edit files only. See

{specfuse_loop-0.3.20 → specfuse_loop-0.3.22}/specfuse/loop/lint_plan.py

@@ -248,12 +248,23 @@ def _find_task_graph_block(body: str) -> dict | None:
     return None
 
 
+# Ceremony WU types systematically under-estimated in the field: close and
+# plan-next WUs ran 2.8-5.2x over on $2-3 estimates across FEAT-2026-0049
+# (clabonte/generator), poisoning every calibration built on the plans (#201).
+# The floor is a WARN threshold, not a cap — estimates below it are almost
+# certainly wishful, not cheap.
+CEREMONY_COST_FLOOR_USD = 5.0
+_CEREMONY_TYPES = frozenset({"close", "close-intermediate", "plan-next"})
+
+
 def check_planned_cost(feature_dir: Path, plan_fm: dict, gates: list) -> None:
     """Emit WARN for missing planned_cost_usd on WUs and PLAN.md.
 
     Sealed WUs (wu status=done AND plan status=done) are skipped silently —
     backfilling cost estimates on history is pointless.  Active or draft WUs
-    get the WARN.  PLAN.md is compared against the sum of WU planned costs;
+    get the WARN.  Ceremony-type WUs (close/close-intermediate/plan-next)
+    with a planned cost below CEREMONY_COST_FLOOR_USD get a floor WARN
+    (#201).  PLAN.md is compared against the sum of WU planned costs;
     delta > 10% emits a separate WARN naming the delta.  Never raises or
     appends to an errors list — all findings are WARN-only (exit code 0).
     """
@@ -283,6 +294,21 @@ def check_planned_cost(feature_dir: Path, plan_fm: dict, gates: list) -> None:
                 )
             if planned is not None:
                 wu_sum += float(planned)
+                # Floor applies to POSITIVE estimates only: the observed
+                # failure is a real-but-wishful $2-3 estimate anchoring
+                # calibration, not an explicit 0.00 (the scaffold's
+                # "unestimated" placeholder, already visible as such).
+                if (not is_sealed
+                        and wfm.get("type") in _CEREMONY_TYPES
+                        and 0 < float(planned) < CEREMONY_COST_FLOOR_USD):
+                    print(
+                        f"WARN: {wfile}: planned_cost_usd "
+                        f"${float(planned):.2f} is below the "
+                        f"${CEREMONY_COST_FLOOR_USD:.2f} floor for "
+                        f"'{wfm.get('type')}' WUs. Ceremony WUs ran 2.8-5.2x "
+                        f"over on $2-3 estimates (FEAT-2026-0049); raise the "
+                        f"estimate rather than anchoring calibration on it."
+                    )
 
     wu_sum = round(wu_sum, 2)