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

{specfuse_loop-0.3.21/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.21
+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.21 → specfuse_loop-0.3.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.3.21"
+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.21 → 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.21 → 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.21 → 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.21 → 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.21 → 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.21 → specfuse_loop-0.3.22}/specfuse/loop/loop.py

@@ -64,7 +64,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.3.21"
+DRIVER_VERSION = "0.3.22"
 # Oldest scaffold layout this driver can drive. init.sh stamps the scaffold's own
 # version into `.specfuse/VERSION`; check_scaffold_version() fails loud at startup if
 # the consumer's scaffold is older than this, pointing at `specfuse upgrade`. Bump

{specfuse_loop-0.3.21 → specfuse_loop-0.3.22}/specfuse/loop/scaffold.py

@@ -166,6 +166,9 @@ _RULES_BLOCK = (
     "@.specfuse/rules/never-touch.md\n"
     "@.specfuse/rules/security-boundaries.md\n"
     "@.specfuse/rules/verification-discipline.md\n"
+    "<!-- Project-authored rules live in .specfuse/rules-local/ (never touched\n"
+    "     by `specfuse upgrade`). Add one @.specfuse/rules-local/<rule>.md line\n"
+    "     per rule below. See .specfuse/rules-local/README.md. -->\n"
 )
 
 _RULES_SENTINEL = "@.specfuse/rules/result-contract.md"
@@ -321,6 +324,8 @@ def upgrade_specfuse(
     Overwrites versioned files (templates/, rules/, verification.yml.example, VERSION),
     prunes versioned files the seed no longer ships (scoped to templates/ and rules/),
     seeds missing user-authored files from templates, and refreshes .claude wiring.
+    rules-local/ is project-owned: never overlaid, never pruned; only its README
+    is seeded when absent.
 
     Returns the sorted list of .specfuse/ relpaths written.
     Raises ScaffoldDowngradeError if the target VERSION is newer than the installed seed.
@@ -372,6 +377,12 @@ def upgrade_specfuse(
         ("LEARNINGS.md", "LEARNINGS.template.md"),
         ("roadmap.md", "roadmap.template.md"),
         ("verification.yml", "verification.yml.example"),
+        # rules-local/ is the project-authored rules directory: outside every
+        # versioned overlay prefix and prune dir BY CONSTRUCTION, so upgrade
+        # never overwrites or deletes its contents. The README is seeded once
+        # (create-if-absent, like the other user seeds) and then owned by the
+        # project.
+        ("rules-local/README.md", "rules-local/README.md"),
     ]
     for target_rel, seed_rel in user_seeds:
         dest = specfuse_dir / target_rel

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.3.21
+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.21 → specfuse_loop-0.3.22}/specfuse_loop.egg-info/SOURCES.txt

@@ -25,9 +25,11 @@ specfuse/loop/data/docs/concepts/architecture-addendum-gates-and-iterative-plann
 specfuse/loop/data/docs/concepts/ralph-lineage.md
 specfuse/loop/data/rules/correlation-ids.md
 specfuse/loop/data/rules/never-touch.md
+specfuse/loop/data/rules/planning-discipline.md
 specfuse/loop/data/rules/result-contract.md
 specfuse/loop/data/rules/security-boundaries.md
 specfuse/loop/data/rules/verification-discipline.md
+specfuse/loop/data/rules-local/README.md
 specfuse/loop/data/schemas/event.schema.json
 specfuse/loop/data/schemas/events/initiative_created.schema.json
 specfuse/loop/data/schemas/events/spec_issue_resolved.schema.json

{specfuse_loop-0.3.21 → specfuse_loop-0.3.22}/tests/test_init_integration.py

@@ -36,6 +36,8 @@ _EXPECTED_SPECFUSE_TREE = {
     "templates/WU.template.md",
     "rules/correlation-ids.md",
     "rules/never-touch.md",
+    "rules/planning-discipline.md",
+    "rules-local/README.md",
     "rules/result-contract.md",
     "rules/security-boundaries.md",
     "rules/verification-discipline.md",
@@ -117,6 +119,7 @@ class TestInitFullLayout(unittest.TestCase):
         for rel in (
             "rules/correlation-ids.md",
             "rules/never-touch.md",
+            "rules/planning-discipline.md",
             "rules/result-contract.md",
             "rules/security-boundaries.md",
             "rules/verification-discipline.md",

{specfuse_loop-0.3.21 → specfuse_loop-0.3.22}/tests/test_scaffold_data_in_sync.py

@@ -25,6 +25,8 @@ TRACKED = {
     "templates/WU.template.md",
     "rules/correlation-ids.md",
     "rules/never-touch.md",
+    "rules/planning-discipline.md",
+    "rules-local/README.md",
     "rules/result-contract.md",
     "rules/security-boundaries.md",
     "rules/verification-discipline.md",

{specfuse_loop-0.3.21 → specfuse_loop-0.3.22}/tests/test_scaffold_init.py

@@ -18,6 +18,8 @@ _EXPECTED_TREE = {
     "templates/WU.template.md",
     "rules/correlation-ids.md",
     "rules/never-touch.md",
+    "rules/planning-discipline.md",
+    "rules-local/README.md",
     "rules/result-contract.md",
     "rules/security-boundaries.md",
     "rules/verification-discipline.md",
@@ -45,6 +47,7 @@ _VERSIONED_SEED_TO_TARGET = {
     "templates/WU.template.md": "templates/WU.template.md",
     "rules/correlation-ids.md": "rules/correlation-ids.md",
     "rules/never-touch.md": "rules/never-touch.md",
+    "rules/planning-discipline.md": "rules/planning-discipline.md",
     "rules/result-contract.md": "rules/result-contract.md",
     "rules/security-boundaries.md": "rules/security-boundaries.md",
     "rules/verification-discipline.md": "rules/verification-discipline.md",

{specfuse_loop-0.3.21 → specfuse_loop-0.3.22}/tests/test_scaffold_resources.py

@@ -20,6 +20,8 @@ _EXPECTED_RELPATHS = {
     "templates/WU.template.md",
     "rules/correlation-ids.md",
     "rules/never-touch.md",
+    "rules/planning-discipline.md",
+    "rules-local/README.md",
     "rules/result-contract.md",
     "rules/security-boundaries.md",
     "rules/verification-discipline.md",

{specfuse_loop-0.3.21 → specfuse_loop-0.3.22}/tests/test_scaffold_upgrade.py

@@ -212,6 +212,40 @@ class TestUpgradeOverlayAndPreserve(unittest.TestCase):
         upgrade_specfuse(self.target)
         self.assertTrue(user_file.exists())
 
+    def test_upgrade_preserves_rules_local_files(self):
+        """The rules-local/ contract: project-authored rules survive upgrade
+        byte-identical — never overlaid, never pruned."""
+        sentinel = b"# Project rule\n\nGrep our own rules dir before designing.\n"
+        rule = self.specfuse / "rules-local" / "our-project-rule.md"
+        rule.parent.mkdir(exist_ok=True)
+        rule.write_bytes(sentinel)
+
+        upgrade_specfuse(self.target)
+
+        self.assertTrue(rule.exists(),
+                        "project-authored rules-local file must survive upgrade")
+        self.assertEqual(rule.read_bytes(), sentinel,
+                         "project-authored rules-local file must be untouched")
+
+    def test_upgrade_seeds_rules_local_readme_when_absent(self):
+        readme = self.specfuse / "rules-local" / "README.md"
+        if readme.exists():
+            readme.unlink()
+            readme.parent.rmdir()
+        written = upgrade_specfuse(self.target)
+        self.assertTrue(readme.exists())
+        self.assertIn("rules-local/README.md", written)
+
+    def test_upgrade_never_overwrites_edited_rules_local_readme(self):
+        sentinel = b"project-edited readme"
+        readme = self.specfuse / "rules-local" / "README.md"
+        readme.parent.mkdir(exist_ok=True)
+        readme.write_bytes(sentinel)
+        upgrade_specfuse(self.target)
+        self.assertEqual(readme.read_bytes(), sentinel,
+                         "seeded README is project-owned after init — "
+                         "upgrade must not overwrite it")
+
     def test_upgrade_prune_does_not_touch_scripts_dir(self):
         # init.sh-legacy scripts/ dir must be left alone (migration prune out of scope)
         scripts = self.specfuse / "scripts"

specfuse_loop-0.3.21/specfuse/loop/data/VERSION

@@ -1 +0,0 @@
-0.3.21