specfuse-loop 0.3.0__tar.gz → 0.3.1__tar.gz

{specfuse_loop-0.3.0/specfuse_loop.egg-info → specfuse_loop-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.3.0
+Version: 0.3.1
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0
@@ -77,8 +77,8 @@ the planning rigor Ralph's bare task list lacks.
   `.specfuse/scripts/adopt_feature.py <repo> <issue-number>` (or the
   interactive `/adopt-feature` skill) to scaffold a dispatchable feature
   folder from a picked issue.
-- The **driver** (`.specfuse/scripts/loop.py`) walks the current gate's ready
-  work units, dispatches each as a fresh `claude -p` session, runs the unit's
+- The **driver** (`specfuse-loop`, from the pip package) walks the current gate's
+  ready work units, dispatches each as a fresh `claude -p` session, runs the unit's
   verification itself as the exit oracle, and commits one squashed,
   trailer-carrying commit per unit. A failed gate is retried with a fresh
   session carrying the failure evidence, up to three attempts, then escalated.
@@ -101,29 +101,34 @@ In a target single-repo project:
 cloning to enable the pre-push hook (runs `scripts/smoke-test.sh` — same
 checks CI runs — before each `git push`). Bypass with `git push --no-verify`.
 
-The driver installs from PyPI and the skills from the Claude Code marketplace:
+The driver installs from PyPI and the skills ship as a Claude Code plugin:
 
 ```bash
-pip install specfuse-loop                       # the driver: `specfuse-loop` on PATH
-# in Claude Code: skills under the /specfuse: namespace
+pipx install specfuse                           # umbrella CLI; pulls specfuse-loop>=0.3.0
+#   gives you: specfuse, specfuse-loop, specfuse-lint  (or: python3 -m pip install specfuse, in a venv)
+
+# in Claude Code, enable the skills plugin (one-time):
 #   /plugin marketplace add specfuse/specfuse
 #   /plugin install specfuse@specfuse
 
-# scaffold a target repo's .specfuse/ state (templates, rules, verification.yml)
-./init.sh /path/to/your-project                 # legacy installer (v1.0; removed in v1.1)
+specfuse init /path/to/your-project             # scaffold .specfuse/ + wire .claude/ (--dry-run previews)
 
 cd /path/to/your-project
 $EDITOR .specfuse/verification.yml              # match the `code` gates to your stack
-# author your first feature folder under .specfuse/features/ from .specfuse/templates/
-specfuse-loop --dry-run                          # or: python .specfuse/scripts/loop.py --dry-run
-specfuse-loop
+# author your first feature (in Claude Code: /draft-feature)
+specfuse-loop --dry-run                          # show the gate walk, no dispatch
+specfuse-loop                                    # the real run
 ```
 
-> **Distribution (FEAT-2026-0019).** Code ships via pip (`specfuse-loop`), the
-> `specfuse` umbrella CLI bridges pip ↔ plugin (`specfuse upgrade`), and Claude
-> assets ship via the [`specfuse/specfuse`](https://github.com/specfuse/specfuse)
-> marketplace. `init.sh` remains the scaffold bootstrap (laying down `.specfuse/`
-> state) until pip-native scaffolding lands; it prints a deprecation banner.
+> **Distribution.** Code ships via pip — `specfuse` (umbrella CLI: `init` /
+> `upgrade`) pulls `specfuse-loop` (the driver); Claude assets ship via the
+> [`specfuse/specfuse`](https://github.com/specfuse/specfuse) plugin marketplace.
+> `specfuse init` lays down `.specfuse/` and wires `.claude/`; `specfuse upgrade`
+> overlays a newer scaffold and pip-upgrades both packages. Every `specfuse-loop`
+> run self-provisions (version-syncs `.specfuse/` from the installed package), so
+> an upgrade reaches existing projects on their next run. (`./init.sh` is a
+> deprecated v1.0 shim that delegates to `specfuse init`/`upgrade`; slated for
+> removal.)
 
 > **One driver per working tree.** The driver holds an exclusive advisory lock on
 > `.specfuse/.loop.lock` for the duration of a run; a second driver targeting the
@@ -145,7 +150,7 @@ python .specfuse/scripts/loop.py --dry-run
 ```
 specfuse-loop/
 ├── LICENSE  NOTICE  CONTRIBUTING.md  README.md  .gitignore
-├── init.sh                      scaffold .specfuse/ into a target repo
+├── init.sh                      deprecated v1.0 shim → delegates to `specfuse init`/`upgrade`
 ├── docs/
 │   ├── getting-started.md       narrated first-feature + operator walkthrough
 │   ├── methodology.md           the gate-cycle contract (shared with the orchestrator)
@@ -164,7 +169,7 @@ specfuse-loop/
     └── features/FEAT-2026-0001-health-endpoint/   (the worked example)
 ```
 
-`init.sh` also ships the durable docs — `methodology.md`, `skills.md`, and
+`specfuse init` also ships the durable docs — `methodology.md`, `skills.md`, and
 `concepts/` — into a target's `.specfuse/docs/`, so an initialized repo is
 self-documenting without this checkout.
 

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1}/README.md

@@ -48,8 +48,8 @@ the planning rigor Ralph's bare task list lacks.
   `.specfuse/scripts/adopt_feature.py <repo> <issue-number>` (or the
   interactive `/adopt-feature` skill) to scaffold a dispatchable feature
   folder from a picked issue.
-- The **driver** (`.specfuse/scripts/loop.py`) walks the current gate's ready
-  work units, dispatches each as a fresh `claude -p` session, runs the unit's
+- The **driver** (`specfuse-loop`, from the pip package) walks the current gate's
+  ready work units, dispatches each as a fresh `claude -p` session, runs the unit's
   verification itself as the exit oracle, and commits one squashed,
   trailer-carrying commit per unit. A failed gate is retried with a fresh
   session carrying the failure evidence, up to three attempts, then escalated.
@@ -72,29 +72,34 @@ In a target single-repo project:
 cloning to enable the pre-push hook (runs `scripts/smoke-test.sh` — same
 checks CI runs — before each `git push`). Bypass with `git push --no-verify`.
 
-The driver installs from PyPI and the skills from the Claude Code marketplace:
+The driver installs from PyPI and the skills ship as a Claude Code plugin:
 
 ```bash
-pip install specfuse-loop                       # the driver: `specfuse-loop` on PATH
-# in Claude Code: skills under the /specfuse: namespace
+pipx install specfuse                           # umbrella CLI; pulls specfuse-loop>=0.3.0
+#   gives you: specfuse, specfuse-loop, specfuse-lint  (or: python3 -m pip install specfuse, in a venv)
+
+# in Claude Code, enable the skills plugin (one-time):
 #   /plugin marketplace add specfuse/specfuse
 #   /plugin install specfuse@specfuse
 
-# scaffold a target repo's .specfuse/ state (templates, rules, verification.yml)
-./init.sh /path/to/your-project                 # legacy installer (v1.0; removed in v1.1)
+specfuse init /path/to/your-project             # scaffold .specfuse/ + wire .claude/ (--dry-run previews)
 
 cd /path/to/your-project
 $EDITOR .specfuse/verification.yml              # match the `code` gates to your stack
-# author your first feature folder under .specfuse/features/ from .specfuse/templates/
-specfuse-loop --dry-run                          # or: python .specfuse/scripts/loop.py --dry-run
-specfuse-loop
+# author your first feature (in Claude Code: /draft-feature)
+specfuse-loop --dry-run                          # show the gate walk, no dispatch
+specfuse-loop                                    # the real run
 ```
 
-> **Distribution (FEAT-2026-0019).** Code ships via pip (`specfuse-loop`), the
-> `specfuse` umbrella CLI bridges pip ↔ plugin (`specfuse upgrade`), and Claude
-> assets ship via the [`specfuse/specfuse`](https://github.com/specfuse/specfuse)
-> marketplace. `init.sh` remains the scaffold bootstrap (laying down `.specfuse/`
-> state) until pip-native scaffolding lands; it prints a deprecation banner.
+> **Distribution.** Code ships via pip — `specfuse` (umbrella CLI: `init` /
+> `upgrade`) pulls `specfuse-loop` (the driver); Claude assets ship via the
+> [`specfuse/specfuse`](https://github.com/specfuse/specfuse) plugin marketplace.
+> `specfuse init` lays down `.specfuse/` and wires `.claude/`; `specfuse upgrade`
+> overlays a newer scaffold and pip-upgrades both packages. Every `specfuse-loop`
+> run self-provisions (version-syncs `.specfuse/` from the installed package), so
+> an upgrade reaches existing projects on their next run. (`./init.sh` is a
+> deprecated v1.0 shim that delegates to `specfuse init`/`upgrade`; slated for
+> removal.)
 
 > **One driver per working tree.** The driver holds an exclusive advisory lock on
 > `.specfuse/.loop.lock` for the duration of a run; a second driver targeting the
@@ -116,7 +121,7 @@ python .specfuse/scripts/loop.py --dry-run
 ```
 specfuse-loop/
 ├── LICENSE  NOTICE  CONTRIBUTING.md  README.md  .gitignore
-├── init.sh                      scaffold .specfuse/ into a target repo
+├── init.sh                      deprecated v1.0 shim → delegates to `specfuse init`/`upgrade`
 ├── docs/
 │   ├── getting-started.md       narrated first-feature + operator walkthrough
 │   ├── methodology.md           the gate-cycle contract (shared with the orchestrator)
@@ -135,7 +140,7 @@ specfuse-loop/
     └── features/FEAT-2026-0001-health-endpoint/   (the worked example)
 ```
 
-`init.sh` also ships the durable docs — `methodology.md`, `skills.md`, and
+`specfuse init` also ships the durable docs — `methodology.md`, `skills.md`, and
 `concepts/` — into a target's `.specfuse/docs/`, so an initialized repo is
 self-documenting without this checkout.
 

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1}/pyproject.toml

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

specfuse_loop-0.3.1/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.1

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1}/specfuse/loop/data/docs/getting-started.md

@@ -6,33 +6,65 @@ the [README](../README.md); for the full contracts see
 [`methodology.md`](methodology.md) and for the interactive operations see
 [`skills.md`](skills.md).
 
-The loop is stdlib-only Python plus Claude Code. There is no install step in your
-target repo — `init.sh` copies a self-contained scaffold in.
+The driver is pure-stdlib Python; it installs from PyPI, and the interactive
+skills ship as a Claude Code plugin. You install the tooling once, then scaffold
+each project you want to drive with one command.
 
 ---
 
-## 1. Install the scaffold
+## 1. Install the tooling and scaffold your project
 
-From your checkout of `specfuse/loop`, point `init.sh` at the repo you want to
-drive:
+Install the umbrella package — it pulls the driver (`specfuse-loop>=0.3.0`) as a
+dependency and puts the `specfuse`, `specfuse-loop`, and `specfuse-lint` commands
+on your PATH. It's a command-line app, so **pipx** is the recommended installer
+(isolated environment, no `--break-system-packages` on PEP 668 / externally-
+managed Pythons):
 
 ```bash
-./init.sh /path/to/your-project
+pipx install specfuse           # recommended
+# or, inside a virtualenv you control:
+python3 -m pip install specfuse
 ```
 
-This writes `.specfuse/` (templates, rules, skills, the driver, and the durable
-docs) into your project and wires `.claude/` so Claude Code discovers the skills.
-It refuses if `.specfuse/` already exists — use `./init.sh --upgrade` to update an
-existing install in place without touching your authored files.
+> On Debian/Ubuntu/macOS-Homebrew Pythons a bare `pip install` into the system
+> interpreter is blocked (`externally-managed-environment`). Use `pipx` (or a
+> venv) — that's what puts `specfuse-loop` / `specfuse-lint` on PATH for the gate
+> commands to find.
+
+Enable the skills plugin in Claude Code (one-time):
+
+```
+/plugin marketplace add specfuse/specfuse
+/plugin install specfuse@specfuse
+```
+
+Then scaffold the repo you want to drive:
+
+```bash
+specfuse init /path/to/your-project        # add --dry-run to preview, writes nothing
+```
+
+This writes `.specfuse/` (templates, rules, the durable docs, `verification.yml`,
+and an empty `features/`) into your project and merge-safely wires `.claude/`
+(`CLAUDE.md`, `settings.json` enabling the `specfuse@specfuse` plugin) plus a
+`.gitignore` snippet. It refuses if `.specfuse/` already exists — use
+`specfuse upgrade /path/to/your-project` to overlay a newer scaffold in place
+without touching your authored files. (The skills come from the plugin, not from
+files copied into your repo.)
 
 > **Don't gitignore `.specfuse/`.** The loop's durable state lives there and must
-> be committed for the loop to work. `init.sh` warns if it detects the directory
-> is ignored.
+> be committed for the loop to work.
+
+> **Self-provisioning.** Every `specfuse-loop` run first version-syncs `.specfuse/`
+> from the installed package (missing → scaffold, older → overlay, equal → no-op,
+> never downgrades). So `pip install -U specfuse` followed by a run keeps the
+> scaffold current — `specfuse upgrade` is the explicit equivalent. Disable with
+> `--no-autosync` or `autosync: false` in `.specfuse/config`.
 
 ## 2. Match verification to your stack
 
-`init.sh` seeds `.specfuse/verification.yml`. Open it and make the `code` gate set
-run *your* project's checks:
+`specfuse init` seeds `.specfuse/verification.yml`. Open it and make the `code`
+gate set run *your* project's checks:
 
 ```yaml
 code:
@@ -63,10 +95,11 @@ Two ways to create a feature folder under `.specfuse/features/`:
 - **Interactively (recommended):** run **`/pick-feature`** to choose from your
   roadmap, then **`/draft-feature`**. Draft-feature asks framing questions, then
   proposes a gate skeleton and gate 1's work units, writing only on your accept.
-- **By hand:** copy the worked example,
-  `.specfuse/features/FEAT-2026-0001-health-endpoint/`, and adapt it. It's a
-  deliberately small two-unit feature that exercises the whole loop. Or start from
-  the bare templates in `.specfuse/templates/`.
+- **By hand:** start from the bare templates in `.specfuse/templates/`
+  (`PLAN`, `GATE`, `WU`) and fill in a small first feature. (The
+  `specfuse/loop` source repo also carries a worked example,
+  `FEAT-2026-0001-health-endpoint`, if you want a complete reference to copy
+  from.)
 
 A feature folder holds:
 
@@ -81,7 +114,7 @@ Then create the branch named in `PLAN.md`'s frontmatter (`branch:`).
 ## 4. Validate before running
 
 ```bash
-python .specfuse/scripts/lint_plan.py .specfuse/features/FEAT-2026-0001-health-endpoint
+specfuse-lint .specfuse/features/FEAT-YYYY-NNNN-your-feature
 ```
 
 The linter checks structure: every WU has the five mandatory sections, the closing
@@ -92,8 +125,8 @@ dispatch.
 ## 5. Dry-run, then run
 
 ```bash
-python .specfuse/scripts/loop.py --dry-run     # show the gate walked, in dep order, no dispatch
-python .specfuse/scripts/loop.py               # the real thing
+specfuse-loop --dry-run     # show the gate walked, in dep order, no dispatch
+specfuse-loop               # the real thing
 ```
 
 With no `--feature` flag the driver picks the single `active` feature. For each
@@ -136,7 +169,7 @@ the ones you accept to `pending`, marks the finished gate `passed`, and prints t
 resume command. Read the `GATE-NN-REVIEW.md` the planner wrote first: it's
 weighted toward where the planner was *least* certain.
 
-Then re-run `loop.py`. Repeat until the terminal gate is `done`.
+Then re-run `specfuse-loop`. Repeat until the terminal gate is `done`.
 
 ## 7. Wrap up
 

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1}/specfuse/loop/data/docs/skills.md

@@ -10,9 +10,11 @@ to do, and writes only on your explicit go-ahead. None of them dispatch agent
 sessions or run the loop — they manipulate the durable files (`roadmap.md`,
 `PLAN.md`, `GATE-NN.md`, `WU-*.md`, `LEARNINGS.md`) that the driver then acts on.
 
-All skills below ship to a target repo via `init.sh` and appear under
-`.specfuse/skills/` (symlinked into `.claude/skills/` so Claude Code discovers
-them).
+All skills below ship as the `specfuse@specfuse` Claude Code plugin (enable once
+with `/plugin marketplace add specfuse/specfuse` then `/plugin install
+specfuse@specfuse`; `specfuse init` wires the plugin into the repo's
+`.claude/settings.json`). They appear under the `/specfuse:` namespace — no files
+are copied into your repo.
 
 ## The lifecycle, in order
 
@@ -21,7 +23,7 @@ A feature moves through these phases. The skill for each phase is named.
 ```
 roadmap ──/pick-feature──▶ active ──/draft-feature──▶ gate 1 detailed
                                                             │
-                                                   python loop.py
+                                                   specfuse-loop
                                                             │
                                    ┌────────────────────────┴───────────────┐
                                    ▼                                         ▼
@@ -62,9 +64,9 @@ roadmap ──/pick-feature──▶ active ──/draft-feature──▶ gate 1
 
 ### 3. Run — the driver (not a skill)
 
-`python .specfuse/scripts/loop.py` walks the active gate, dispatches each WU as a
-fresh session, verifies, and commits. It is a script, not a skill. It either
-auto-closes a clean gate or halts at the gate boundary for review.
+`specfuse-loop` (the pip-installed driver) walks the active gate, dispatches each
+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.
 
 ### 4. Arm — the human checkpoint at each gate
 
@@ -106,7 +108,7 @@ auto-closes a clean gate or halts at the gate boundary for review.
   methodology: 1 bug = 1 branch = 1 PR, test-first. Refuses and proposes
   promoting to a feature if the work is large or risky.
 - **`/feature-conversion`** — bring an existing feature folder into conformance
-  with the current scaffold's structural contract. Runs after `init.sh --upgrade`
+  with the current scaffold's structural contract. Runs after `specfuse upgrade`
   flags a feature as `FAIL`. Interactive, lint-driven.
 - **`/learnings-suggest`** — scan `attempt_outcome` events across features,
   cluster non-passing attempts, and surface recurring patterns as candidate

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1}/specfuse/loop/data/roadmap.template.md

@@ -15,11 +15,12 @@ Detail a feature's first-gate work units when you are ready to start it; the gat
 after that is drafted for you by the prior gate's plan-next. Until you start a
 feature, a one-line entry here is enough.
 
-| Feature ID     | Title                | Status   | Folder |
-|----------------|----------------------|----------|--------|
-| FEAT-2026-0001 | Health-check endpoint| active   | `features/FEAT-2026-0001-health-endpoint/` |
-| FEAT-2026-0002 | <title>              | planned  | — |
-| FEAT-2026-0003 | <title>              | planned  | — |
+Add your first feature with **`/roadmap-add`** (it auto-picks the next
+`FEAT-YYYY-NNNN` ID and writes the row + detail section), or add a row by hand in
+the canonical column order below.
+
+| Feature ID     | Title | Status | Folder | Detail |
+|----------------|-------|--------|--------|--------|
 
 Status: `planned` → `active` → `done` (or `abandoned`).
 

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1}/specfuse/loop/data/verification.yml.example

@@ -34,7 +34,7 @@ code:
   - name: coverage
     command: "coverage report --fail-under=90"
   - name: warnings
-    command: "python -W error -c 'pass'"     # replace with your build's -Werror equivalent
+    command: "python3 -W error -c 'pass'"    # replace with your build's -Werror equivalent
   - name: lint
     command: "ruff check ."
   - name: security
@@ -50,4 +50,4 @@ doc:
 # a malformed next-gate draft fails here, where you are already reviewing.
 plannext:
   - name: plan-lint
-    command: "python .specfuse/scripts/lint_plan.py {feature_dir}"
+    command: "specfuse-lint {feature_dir}"

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1}/specfuse/loop/lint_plan.py

@@ -23,7 +23,7 @@ Two jobs:
 
 Exit 0 = clean, 1 = problems (printed).
 
-Usage:  python .specfuse/scripts/lint_plan.py .specfuse/features/FEAT-XXXX-slug
+Usage:  specfuse-lint .specfuse/features/FEAT-XXXX-slug
 """
 
 from __future__ import annotations

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1}/specfuse/loop/loop.py

@@ -62,7 +62,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.0"
+DRIVER_VERSION = "0.3.1"
 # 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
@@ -3666,7 +3666,7 @@ def run(
                 f"flip accepted WUs to `pending`,\n"
                 f"                          mark this gate `passed`. "
                 f"Reads {review.name} for planner findings.\n"
-                f"  - Resume               python3 .specfuse/scripts/loop.py"
+                f"  - Resume               specfuse-loop"
             )
         return 0
     except BookkeepingCommitError as exc:

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1/specfuse_loop.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.3.0
+Version: 0.3.1
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0
@@ -77,8 +77,8 @@ the planning rigor Ralph's bare task list lacks.
   `.specfuse/scripts/adopt_feature.py <repo> <issue-number>` (or the
   interactive `/adopt-feature` skill) to scaffold a dispatchable feature
   folder from a picked issue.
-- The **driver** (`.specfuse/scripts/loop.py`) walks the current gate's ready
-  work units, dispatches each as a fresh `claude -p` session, runs the unit's
+- The **driver** (`specfuse-loop`, from the pip package) walks the current gate's
+  ready work units, dispatches each as a fresh `claude -p` session, runs the unit's
   verification itself as the exit oracle, and commits one squashed,
   trailer-carrying commit per unit. A failed gate is retried with a fresh
   session carrying the failure evidence, up to three attempts, then escalated.
@@ -101,29 +101,34 @@ In a target single-repo project:
 cloning to enable the pre-push hook (runs `scripts/smoke-test.sh` — same
 checks CI runs — before each `git push`). Bypass with `git push --no-verify`.
 
-The driver installs from PyPI and the skills from the Claude Code marketplace:
+The driver installs from PyPI and the skills ship as a Claude Code plugin:
 
 ```bash
-pip install specfuse-loop                       # the driver: `specfuse-loop` on PATH
-# in Claude Code: skills under the /specfuse: namespace
+pipx install specfuse                           # umbrella CLI; pulls specfuse-loop>=0.3.0
+#   gives you: specfuse, specfuse-loop, specfuse-lint  (or: python3 -m pip install specfuse, in a venv)
+
+# in Claude Code, enable the skills plugin (one-time):
 #   /plugin marketplace add specfuse/specfuse
 #   /plugin install specfuse@specfuse
 
-# scaffold a target repo's .specfuse/ state (templates, rules, verification.yml)
-./init.sh /path/to/your-project                 # legacy installer (v1.0; removed in v1.1)
+specfuse init /path/to/your-project             # scaffold .specfuse/ + wire .claude/ (--dry-run previews)
 
 cd /path/to/your-project
 $EDITOR .specfuse/verification.yml              # match the `code` gates to your stack
-# author your first feature folder under .specfuse/features/ from .specfuse/templates/
-specfuse-loop --dry-run                          # or: python .specfuse/scripts/loop.py --dry-run
-specfuse-loop
+# author your first feature (in Claude Code: /draft-feature)
+specfuse-loop --dry-run                          # show the gate walk, no dispatch
+specfuse-loop                                    # the real run
 ```
 
-> **Distribution (FEAT-2026-0019).** Code ships via pip (`specfuse-loop`), the
-> `specfuse` umbrella CLI bridges pip ↔ plugin (`specfuse upgrade`), and Claude
-> assets ship via the [`specfuse/specfuse`](https://github.com/specfuse/specfuse)
-> marketplace. `init.sh` remains the scaffold bootstrap (laying down `.specfuse/`
-> state) until pip-native scaffolding lands; it prints a deprecation banner.
+> **Distribution.** Code ships via pip — `specfuse` (umbrella CLI: `init` /
+> `upgrade`) pulls `specfuse-loop` (the driver); Claude assets ship via the
+> [`specfuse/specfuse`](https://github.com/specfuse/specfuse) plugin marketplace.
+> `specfuse init` lays down `.specfuse/` and wires `.claude/`; `specfuse upgrade`
+> overlays a newer scaffold and pip-upgrades both packages. Every `specfuse-loop`
+> run self-provisions (version-syncs `.specfuse/` from the installed package), so
+> an upgrade reaches existing projects on their next run. (`./init.sh` is a
+> deprecated v1.0 shim that delegates to `specfuse init`/`upgrade`; slated for
+> removal.)
 
 > **One driver per working tree.** The driver holds an exclusive advisory lock on
 > `.specfuse/.loop.lock` for the duration of a run; a second driver targeting the
@@ -145,7 +150,7 @@ python .specfuse/scripts/loop.py --dry-run
 ```
 specfuse-loop/
 ├── LICENSE  NOTICE  CONTRIBUTING.md  README.md  .gitignore
-├── init.sh                      scaffold .specfuse/ into a target repo
+├── init.sh                      deprecated v1.0 shim → delegates to `specfuse init`/`upgrade`
 ├── docs/
 │   ├── getting-started.md       narrated first-feature + operator walkthrough
 │   ├── methodology.md           the gate-cycle contract (shared with the orchestrator)
@@ -164,7 +169,7 @@ specfuse-loop/
     └── features/FEAT-2026-0001-health-endpoint/   (the worked example)
 ```
 
-`init.sh` also ships the durable docs — `methodology.md`, `skills.md`, and
+`specfuse init` also ships the durable docs — `methodology.md`, `skills.md`, and
 `concepts/` — into a target's `.specfuse/docs/`, so an initialized repo is
 self-documenting without this checkout.
 

{specfuse_loop-0.3.0 → specfuse_loop-0.3.1}/specfuse_loop.egg-info/SOURCES.txt

@@ -111,6 +111,7 @@ tests/test_scaffold_docs.py
 tests/test_scaffold_init.py
 tests/test_scaffold_manifest.py
 tests/test_scaffold_resources.py
+tests/test_scaffold_seed_sanity.py
 tests/test_scaffold_upgrade.py
 tests/test_scaffold_wiring.py
 tests/test_squash_commit_hook_crash.py
@@ -122,4 +123,5 @@ tests/test_upgrade_integration.py
 tests/test_validate_event.py
 tests/test_verdict_coupling.py
 tests/test_verify_empty_gate_set.py
+tests/test_version_consistency.py
 tests/test_version_skew.py

specfuse_loop-0.3.1/tests/test_scaffold_seed_sanity.py

@@ -0,0 +1,80 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""Sanity guards on the scaffold seed a fresh `specfuse init` writes.
+
+These lock the fixes for the brand-new-project install bugs:
+  - the shipped verification.yml gate commands must be runnable on a
+    pip-installed project (console scripts, not `python .specfuse/scripts/...`
+    which does not exist there);
+  - the roadmap template must carry the 5-column header `roadmap-add` requires
+    (Detail column), and must NOT pre-populate demo features.
+"""
+
+from __future__ import annotations
+
+import re
+import unittest
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+DATA = REPO_ROOT / "specfuse" / "loop" / "data"
+
+
+class TestVerificationSeed(unittest.TestCase):
+
+    def test_gate_commands_reference_no_missing_scripts(self):
+        """No shipped gate command may invoke `.specfuse/scripts/...` — that path
+        is absent in a pip-installed project; use the console scripts."""
+        text = (DATA / "verification.yml.example").read_text(encoding="utf-8")
+        offenders = [
+            ln.strip() for ln in text.splitlines()
+            if "command:" in ln and ".specfuse/scripts/" in ln
+        ]
+        self.assertEqual(
+            offenders, [],
+            f"gate commands must not call .specfuse/scripts/* (absent under pip); "
+            f"use specfuse-lint / specfuse-loop. Offenders: {offenders}",
+        )
+
+    def test_plan_lint_uses_console_script(self):
+        text = (DATA / "verification.yml.example").read_text(encoding="utf-8")
+        self.assertIn("specfuse-lint", text,
+                      "the plan-next lint gate should call `specfuse-lint`")
+
+
+class TestRoadmapSeed(unittest.TestCase):
+
+    def _table_header(self) -> str:
+        text = (DATA / "roadmap.template.md").read_text(encoding="utf-8")
+        for ln in text.splitlines():
+            if ln.startswith("| Feature ID"):
+                return ln
+        self.fail("roadmap.template.md has no `| Feature ID` table header")
+
+    def test_header_has_detail_column(self):
+        """roadmap-add requires the 5-column order incl. Detail."""
+        cols = [c.strip() for c in self._table_header().strip("|").split("|")]
+        self.assertEqual(
+            cols, ["Feature ID", "Title", "Status", "Folder", "Detail"],
+            f"roadmap template header must match roadmap-add's expected columns; "
+            f"got {cols}",
+        )
+
+    def test_no_demo_feature_rows(self):
+        """A fresh project's roadmap must not ship example features."""
+        text = (DATA / "roadmap.template.md").read_text(encoding="utf-8")
+        feat_rows = [
+            ln for ln in text.splitlines()
+            if re.match(r"\|\s*FEAT-\d{4}-\d{4}", ln)
+        ]
+        self.assertEqual(
+            feat_rows, [],
+            f"roadmap template must start with an empty table; demo rows found: "
+            f"{feat_rows}",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

specfuse_loop-0.3.1/tests/test_version_consistency.py

@@ -0,0 +1,120 @@
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""The four package-version sources must agree — enforced every CI run.
+
+specfuse-loop's version lives in four places (pyproject, DRIVER_VERSION, the
+canonical .specfuse/VERSION, and the synced specfuse/loop/data/VERSION seed).
+The release.yml tag/version-agreement check covers pyproject + DRIVER_VERSION
+but (a) omits the two scaffold VERSION files and (b) only runs at TAG time. A
+half-bump then sits undetected until release. This test closes both gaps: it
+runs on every PR and asserts all four are equal, plus MIN_SCAFFOLD_VERSION is
+not ahead of the driver. It also exercises scripts/bump_version.py, the helper
+that sets all four in lockstep.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import re
+import tempfile
+import unittest
+from pathlib import Path
+
+from tests._loop_loader import load_loop
+
+loop = load_loop()
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def _pyproject_version(root: Path) -> str:
+    text = (root / "pyproject.toml").read_text(encoding="utf-8")
+    m = re.search(r'(?m)^version\s*=\s*"([^"]+)"', text)
+    assert m, "no version line in pyproject.toml"
+    return m.group(1)
+
+
+def _load_bump():
+    path = REPO_ROOT / "scripts" / "bump_version.py"
+    spec = importlib.util.spec_from_file_location("bump_version", path)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+bump_version = _load_bump()
+
+
+class TestVersionConsistency(unittest.TestCase):
+
+    def test_all_four_sources_agree(self):
+        pkg = _pyproject_version(REPO_ROOT)
+        driver = loop.DRIVER_VERSION
+        specfuse_ver = (REPO_ROOT / ".specfuse" / "VERSION").read_text().strip()
+        data_ver = (REPO_ROOT / "specfuse" / "loop" / "data" / "VERSION").read_text().strip()
+        self.assertEqual(
+            {pkg, driver, specfuse_ver, data_ver}, {pkg},
+            f"version sources disagree: pyproject={pkg} DRIVER_VERSION={driver} "
+            f".specfuse/VERSION={specfuse_ver} data/VERSION={data_ver}. "
+            f"Run `python3 scripts/bump_version.py {pkg}` to re-sync.",
+        )
+
+    def test_min_scaffold_not_ahead_of_driver(self):
+        self.assertLessEqual(
+            loop._parse_version(loop.MIN_SCAFFOLD_VERSION),
+            loop._parse_version(loop.DRIVER_VERSION),
+            "MIN_SCAFFOLD_VERSION must not exceed DRIVER_VERSION",
+        )
+
+
+class TestBumpVersionHelper(unittest.TestCase):
+
+    def _make_tree(self, root: Path, version: str) -> None:
+        (root / "pyproject.toml").write_text(
+            f'[project]\nname = "specfuse-loop"\nversion = "{version}"\n',
+            encoding="utf-8",
+        )
+        loop_dir = root / "specfuse" / "loop"
+        (loop_dir / "data").mkdir(parents=True)
+        (loop_dir / "loop.py").write_text(
+            f'DRIVER_VERSION = "{version}"\nMIN_SCAFFOLD_VERSION = "0.2.0"\n',
+            encoding="utf-8",
+        )
+        (root / ".specfuse").mkdir()
+        (root / ".specfuse" / "VERSION").write_text(version + "\n", encoding="utf-8")
+        (loop_dir / "data" / "VERSION").write_text(version + "\n", encoding="utf-8")
+
+    def test_set_version_updates_all_four(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._make_tree(root, "0.2.0")
+            changed = bump_version.set_version(root, "0.9.0")
+            self.assertEqual(
+                set(changed),
+                {"pyproject.toml", "specfuse/loop/loop.py",
+                 ".specfuse/VERSION", "specfuse/loop/data/VERSION"},
+            )
+            self.assertIn('version = "0.9.0"', (root / "pyproject.toml").read_text())
+            self.assertIn('DRIVER_VERSION = "0.9.0"',
+                          (root / "specfuse/loop/loop.py").read_text())
+            self.assertEqual((root / ".specfuse/VERSION").read_text().strip(), "0.9.0")
+            self.assertEqual(
+                (root / "specfuse/loop/data/VERSION").read_text().strip(), "0.9.0")
+            # MIN_SCAFFOLD_VERSION must be left untouched.
+            self.assertIn('MIN_SCAFFOLD_VERSION = "0.2.0"',
+                          (root / "specfuse/loop/loop.py").read_text())
+
+    def test_set_version_idempotent(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            self._make_tree(root, "0.5.0")
+            self.assertEqual(bump_version.set_version(root, "0.5.0"), [])
+
+    def test_main_rejects_bad_version(self):
+        self.assertEqual(bump_version.main(["not-a-version"]), 2)
+        self.assertEqual(bump_version.main([]), 2)
+
+
+if __name__ == "__main__":
+    unittest.main()

specfuse_loop-0.3.0/specfuse/loop/data/VERSION

@@ -1 +0,0 @@
-0.3.0