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

{specfuse_loop-0.2.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.2.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.2.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.2.0 → specfuse_loop-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.2.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"
@@ -56,8 +56,12 @@ specfuse-lint = "specfuse.loop.lint_plan:main"
 
 [tool.setuptools.packages.find]
 # Ship ONLY the specfuse namespace package. Without this scope, setuptools'
-# auto-discovery sweeps tests/, docs/, and scripts/ into the wheel. The driver's
-# data (templates, rules, features) lives in the consumer's `.specfuse/`, not in
-# the wheel, so the package is pure code.
+# auto-discovery sweeps tests/, docs/, and scripts/ into the wheel.
 include = ["specfuse*"]
 namespaces = true
+
+[tool.setuptools.package-data]
+# Include the scaffold seed so `specfuse init` / `specfuse upgrade` can copy
+# templates, rules, and other seed files out of the wheel without needing the
+# loop source repo on disk.
+"specfuse.loop" = ["data/**/*", "data/*"]

specfuse_loop-0.3.1/specfuse/loop/data/LEARNINGS.template.md

@@ -0,0 +1,69 @@
+# LEARNINGS
+
+Durable, reusable rules distilled from every gate's retrospective. The `lessons` work
+unit appends here; planning reads here before detailing any new feature. This is the
+feedback loop that makes each plan better than the last.
+
+Append only. Phrase each entry as a rule that would change how a FUTURE work unit is
+written or executed, not a one-off observation. De-duplicate against what is here.
+Feature-specific observations stay in that feature's `RETROSPECTIVE.md` and are not
+promoted here.
+
+## Format
+
+```
+- [FEAT-YYYY-NNNN/G1] Implementation WUs must name the module a new route/handler
+  lives in; "add it to the router" cost a blocked attempt when no router existed yet.
+```
+
+## Entries
+
+<!-- lessons work units append below this line -->
+<!--
+The entries below are GENERIC methodology lessons that ship with the scaffold —
+they are about how to write and run work units, not about any one project. Your
+project's own `lessons` work units append project-specific rules beneath them.
+-->
+
+- [meta/first-live-use] Scope a feature's acceptance criteria to the feature's
+  own footprint — its slug, the paths it creates or edits, the symbols it
+  introduces. Acceptance criteria that grep or scan the WHOLE repo will trip
+  on pre-existing, unrelated state and (correctly) cause the agent to emit
+  `status: blocked` even when the WU's own work is fine. Example failure mode:
+  a "no TODO comments anywhere in the tree" check that fires on legacy code
+  the WU never touches. Rule: bound checks to the feature's path prefixes
+  (e.g. `src/<slug>/**`) or to files the WU declares in `generated_surfaces` /
+  `files_changed`; repo-wide invariants belong in a separate hygiene WU or in
+  the repo's `code` gate set, not in a per-feature acceptance criterion.
+
+- [meta/first-live-use] Name what the WU is expected to PRODUCE, not only what
+  it must NOT touch. The "Do not touch" section bounds the WU on one side;
+  without an equally-explicit "produces" list, an agent can helpfully write
+  files that should belong to a later WU (e.g. docs that were T92's job
+  showing up in T01's commit) without the verification gates objecting. Rule:
+  in addition to the "Do not touch" list, the WU's Acceptance criteria should
+  name the specific files/sections the WU is expected to author. A reviewer
+  reading the diff should be able to point at every changed file and find it
+  in either the WU's produces-list or the gate's verification output.
+
+- [meta/first-live-use] The "hygiene WU" pattern — when a substantive WU
+  discovers a pre-existing bug in a path its "Do not touch" rule forbids
+  (typical case: shared module, infrastructure config, dependency version),
+  the right move is to insert a narrow hygiene WU EARLIER in the gate (or as
+  a precursor gate) that fixes only that issue. Not: loosen the blocked WU's
+  scope to permit the cross-cutting fix (muddies its boundary). Not: fix it
+  manually out-of-loop and pretend the gate ran clean (silent drift between
+  the methodology's history and git's). The hygiene WU should have a single,
+  obvious acceptance criterion and pass on its own verification; the original
+  blocked WU then runs after, unmodified.
+
+- [meta/loop-driver-bugs] Driver bookkeeping (frontmatter status flips,
+  events.jsonl appends, per-attempt notes) must be committed if it should
+  survive across WUs — uncommitted writes are wiped by the inter-attempt
+  `git reset --hard`. Agent-work commits (per-WU squash) are separate from
+  bookkeeping commits (`chore(loop): ...`). When authoring WUs whose
+  verification commands themselves write to disk, remember the agent's
+  working tree is reset between failed attempts — scratch files written
+  during a failed attempt won't persist into the next attempt's prompt unless
+  the agent explicitly buffers them in the prompt-facing failure note the
+  driver hands to the next attempt.

specfuse_loop-0.3.1/specfuse/loop/data/VERSION

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

specfuse_loop-0.3.1/specfuse/loop/data/docs/concepts/architecture-addendum-gates-and-iterative-planning.md

@@ -0,0 +1,97 @@
+# Architecture Addendum — Gates and the iterative planning cycle (Model B)
+
+> **Status: adopted (2026-06).** Gate placement is resolved as **Model B — gates live in the
+> loop, per component, NOT in the orchestrator PM.** The gate cycle was proven on a real
+> multi-gate feature (loop `FEAT-2026-0003`: plan-next drafted real, armable next gates across
+> three cycles). This addendum records that decision and what it means for the orchestrator.
+>
+> **This supersedes the earlier Model-A proposal** (an earlier revision of this file that
+> proposed folding gate identification / `plan-next` / per-gate `plan_review` into the PM agent as
+> a `v1.7.0` behavioral change). That fold-in was **not adopted**; the PM does not gain gate
+> machinery. See the orchestrator repo's `docs/gate-placement-proposal.md` (Model A vs B, decision
+> criteria) and `docs/naming-convention.md` for the canonical contracts.
+
+---
+
+## 1. The decision
+
+The orchestrator coordinates one level above a single-repo goal. An **initiative**
+(`INIT-YYYY-NNNN`) is decomposed by the PM into a **`feature_graph`** of **features**
+(`INIT-YYYY-NNNN/FNN`), each a single-repo goal dispatched to one component. **Each dispatched
+implementation feature == a loop feature**: the receiving component's loop decomposes it into
+**gates** and **work units** and grinds it through its gate cycle.
+
+So gates are **internal to the loop**, not orchestrator state. The orchestrator owns
+`initiative → feature` decomposition, cross-repo dependency ordering, and the spec/generated
+interface contracts between features; it does **not** identify gates, run `plan-next`, or hold a
+per-gate `plan_review`. The loop owns all of that, per [`methodology.md`](methodology.md).
+
+**Why Model B (summary).** The loop is single-repo + edit-and-commit; codegen freezes the
+cross-repo interface (generated `emit-*`/`on-*` contracts are immutable `_generated/`), so
+component-loops grind hand-code against frozen boundaries and cannot break each other. This
+dissolves the hardest part of Model A (predicting cross-repo gate boundaries inside the PM) and
+keeps the gate cycle built once, in the loop. Full rationale + the rejected Model A:
+`gate-placement-proposal.md`.
+
+## 2. What changed in the orchestrator (minimal — no PM gate machinery)
+
+The orchestrator change is the **initiative/feature reframe**, already folded into
+`orchestrator-architecture.md` §1A and `naming-convention.md`:
+
+- **Vocabulary / IDs:** initiative → feature → gate → work unit; `INIT-YYYY-NNNN/FNN/TNN`
+  (legacy/component-local `FEAT-…/TNN`). Root token = origin.
+- **State machines (unchanged in shape):** the "feature state machine" is the **initiative**
+  lifecycle; the "task state machine" is the **feature** lifecycle. Gates/WUs do **not** appear in
+  the orchestrator's state machines — they are loop-internal.
+- **PM agent (reframed, not gate-extended):** `feature-decomposition` (was task-decomposition)
+  produces a `feature_graph`; `issue-drafting` files feature issues labelled by type;
+  `plan-review` reviews the `feature_graph`; `dependency-recomputation` (runtime `scripts/poller.py`)
+  flips features `pending → ready`. **No** gate identification, `plan-next`, or per-gate
+  `plan_review` in the PM — those were the Model-A additions and are dropped.
+- **Dispatch by feature type:** `implementation` → the component-loop (loop GitHub feature-pick on
+  `specfuse:feature`); `qa_*` → the QA agent (`specfuse:qa-feature`), a distinct cross-repo role,
+  **not** a loop. QA is the exception to uniform-loop dispatch.
+- **Per-gate autonomy / arming** lives in the loop (not the PM): autonomy flows orchestrator →
+  loop (`review`/`supervised` stop at each gate for a human arm; `auto` self-arms safe gates under
+  the methodology §9 conjunction). The merge gate stays human until the QA loop is trusted.
+
+The orchestrator's earlier "no gates" behavior is therefore not changed by *adding* gates to it —
+gates were placed in the loop instead.
+
+## 3. What the loop owns (the gate layer)
+
+Per [`methodology.md`](methodology.md): the gate cycle (plan → execute → close → review&arm), the
+four-type closing sequence (`retrospective → lessons → docs → plan-next`), `plan-next` drafting
+the next gate (never arming it), `LEARNINGS.md`, and per-gate autonomy. These are **loop-internal**
+to each dispatched feature; the orchestrator sees only the feature's overall state (via issue
+labels) and its completion (PR merge → merge-watcher → `state:done`).
+
+## 4. Reconciliation with the orchestrator (the surface-specific seams)
+
+Per the collaboration charter §2 / methodology §10, only these differ between surfaces:
+
+| Concern        | Loop (single-repo)                       | Orchestrator (multi-repo)                         |
+|----------------|------------------------------------------|---------------------------------------------------|
+| State backend  | WU/GATE/PLAN frontmatter, git-tracked    | GitHub issue labels + the initiative registry     |
+| Dispatch       | driver shells out (`claude -p`)          | poller routes by type → loop / QA agent           |
+| Branch / merge | one branch, squash per WU                | branch + PR per **feature**, merge watcher        |
+| Report-back    | RESULT block                             | `task_completed` event (+ `state:*` labels) via the loop's `GitHubBackend` |
+
+The loop's `loop.py` is the reference for the orchestrator's poller (its dispatch/verify/retry/
+gate-stop semantics decompose across the poller, PM dependency-recomputation, and the merge
+watcher); the orchestrator does not import `loop.py`.
+
+## 5. Status of the old Model-A sections
+
+The prior revision's §A.2–§A.11 (feature-state `in_progress → plan_review` oscillation, gate
+skeleton in the PM, `plan-next` as a PM skill, per-gate `plan_review`, the auto-arm conjunction in
+the PM, PM `v1.7.0`, the `gates`/`task.gate` frontmatter fields) described **Model A and are not
+implemented.** The `feature-frontmatter.schema.json` `gates` array is not used by the orchestrator
+(gates are loop-internal). If a future need arises to surface gate state at the orchestrator level,
+re-open this addendum deliberately.
+
+## 6. Remaining (gated)
+
+- `specfuse/methodology` extraction — once the gate-cycle contracts stop changing run-to-run
+  (charter §4; two contract fixes landed during the FEAT-2026-0003 dogfood — let them soak).
+- Loop kit → `stable` in the orchestrator distribution manifest (same soak gate).

specfuse_loop-0.3.1/specfuse/loop/data/docs/concepts/ralph-lineage.md

@@ -0,0 +1,66 @@
+# Why the loop exists — lineage and positioning
+
+## The Ralph lineage
+
+The loop descends from the "Ralph" technique: in its purest form, a bash loop
+that feeds a prompt to a coding agent repeatedly until the work is done, with a
+fresh context each iteration and durable state kept in files (git history, a
+progress file, a task list) rather than in the context window. Its insight is
+that for large work, *stubbornness plus fresh context* beats a single clever
+pass — the loop is the hero, not the model.
+
+Ralph's known weakness is the thinness of its task list: a bare list of TODOs
+gives an agent nothing to enforce patterns against, so it drifts. The ecosystem's
+answer to "that's too coarse for serious work" has been to make the units of work
+granular and self-contained enough that ephemeral workers can pick them up,
+execute, and hand off — orchestration of many such workers ("Gas Town"-style).
+
+The Specfuse Loop is that idea with the planning rigor added back in. It keeps
+Ralph's fresh-context-per-iteration property but moves it to **work-unit
+granularity**, and it replaces the thin task list with the **Plan + Work Unit**
+pattern: crisp work units with hard "do not touch" boundaries, explicit
+acceptance criteria, and machine-checkable verification gates. The up-front
+planning investment is precisely what earns the right to let execution run
+unattended — the richer the unit, the longer the loop can safely run before a
+human checkpoint.
+
+Two things distinguish it from vanilla Ralph:
+
+- **Verification is the exit oracle, not the agent's say-so.** The driver re-runs
+  the unit's gates and they decide done — eliminating Ralph's classic
+  premature-"done" failure.
+- **Gates are human checkpoints by design.** The loop runs unattended *within* a
+  gate and stops *at* it. Reflection, a cross-feature learnings rollup, and
+  drafting the next batch happen systematically as the gate's closing sequence,
+  not when someone remembers to ask.
+
+## Where it sits in Specfuse
+
+Specfuse is a methodology and an organization, not a single tool. Three
+independently-adoptable projects live under it:
+
+- **`specfuse/codegen`** turns OpenAPI / AsyncAPI / Arazzo specifications into
+  deterministic source code — the boilerplate no one should hand-write and no
+  agent should hallucinate.
+- **`specfuse/loop`** (this project) executes the Plan + Work Unit pattern in a
+  single repository, with no specification required and no agent-coordination
+  overhead. The lightweight surface.
+- **`specfuse/orchestrator`** coordinates specialized agents across many
+  component repositories from validated specifications — the heavyweight surface
+  for multi-repo, spec-first feature delivery.
+
+The loop and the orchestrator are two execution surfaces of **one** methodology
+(see [`methodology.md`](methodology.md)); they share the gate cycle, the
+work-unit contract, the correlation-ID scheme, and the verification discipline.
+The loop is the right home for work that lives in one repo or has no formal
+spec; the orchestrator is the right home when the work genuinely spans repos and
+is driven by specifications that `codegen` can turn into a stable foundation.
+
+## What it is not
+
+- Not a general-purpose AI coding platform. It does one shape of work:
+  plan-driven, gated, fresh-context execution in a single repo.
+- Not a replacement for human judgment. Every gate is a human checkpoint; the
+  loop keeps agents *inside* a loop, it does not remove the loop.
+- Not a hosted service. It runs on your machine, against your repo, under your
+  accounts.

specfuse_loop-0.3.1/specfuse/loop/data/docs/getting-started.md

@@ -0,0 +1,221 @@
+# Getting started
+
+This walks you from an empty project to a feature delivered by the loop, then
+shows what to do when a run halts. It assumes you've read the one-minute pitch in
+the [README](../README.md); for the full contracts see
+[`methodology.md`](methodology.md) and for the interactive operations see
+[`skills.md`](skills.md).
+
+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 tooling and scaffold your project
+
+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
+pipx install specfuse           # recommended
+# or, inside a virtualenv you control:
+python3 -m pip install specfuse
+```
+
+> 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.
+
+> **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
+
+`specfuse init` seeds `.specfuse/verification.yml`. Open it and make the `code`
+gate set run *your* project's checks:
+
+```yaml
+code:
+  - name: tests
+    command: "pytest -q"
+  - name: coverage
+    command: "coverage report --fail-under=90"
+  - name: lint
+    command: "ruff check ."
+  - name: security
+    command: "bandit -r src -ll"
+```
+
+These commands are the **exit oracle**: the driver re-runs them itself after every
+work unit and *they* decide whether the unit is done — the agent's own self-report
+is advisory only ([methodology §5](methodology.md)). Keep this set in lock-step
+with your GitHub branch protection, or an agent can pass locally and still be
+unmergeable.
+
+If your repo already has CI worth deriving from, run **`/derive-verification`** in
+Claude Code instead of editing by hand — it inspects your CI and tooling and
+drafts the file for you.
+
+## 3. Author your first feature
+
+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:** 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:
+
+| File | Owns | Who writes it |
+|------|------|---------------|
+| `PLAN.md` | the *shape*: gate order, WU membership, dependency edges, feature status | you / `draft-feature` (gate 1); `plan-next` (later gates) |
+| `GATE-NN.md` | one gate's status and definition of done | you / the planner |
+| `WU-*.md` | a single work unit: frontmatter + the prompt a fresh session receives | you / `draft-feature` / `plan-next` |
+
+Then create the branch named in `PLAN.md`'s frontmatter (`branch:`).
+
+## 4. Validate before running
+
+```bash
+specfuse-lint .specfuse/features/FEAT-YYYY-NNNN-your-feature
+```
+
+The linter checks structure: every WU has the five mandatory sections, the closing
+sequence is present and well-formed, dependencies resolve, IDs are well-formed.
+Fix anything it flags before dispatching — it's far cheaper than a failed
+dispatch.
+
+## 5. Dry-run, then run
+
+```bash
+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
+ready work unit it:
+
+1. marks the WU `in_progress`,
+2. dispatches a **fresh** `claude -p` session with that unit's model and prompt,
+3. runs the unit's verification **itself** as the exit oracle,
+4. on pass, makes **one squashed commit** carrying the `Feature: FEAT-.../TNN`
+   trailer.
+
+A failed gate is discarded and re-dispatched to a fresh session carrying the
+failure evidence, up to three attempts, then the unit is escalated to
+`blocked_human` and the gate halts.
+
+> **One driver per working tree.** The driver holds an exclusive lock on
+> `.specfuse/.loop.lock`. A second driver on the same checkout exits immediately.
+> To run two features at once, use separate `git worktree` checkouts. `--dry-run`
+> is exempt.
+
+## 6. The gate boundary — where you come back in
+
+A gate ends with a **closing sequence** that runs automatically: it writes a
+retrospective, promotes durable lessons to `LEARNINGS.md`, reconciles docs, and —
+crucially — **drafts the next gate's work units** (as `draft`) so the next gate is
+waiting for you to review.
+
+Two things can happen at the boundary:
+
+- **The gate auto-closes.** On a clean, on-plan gate the deterministic predicate
+  (`gate_eval.py`) closes it without a reflective session — but `plan-next` still
+  drafts the next gate, so the human review step still fires
+  ([methodology §3](methodology.md)).
+- **The driver halts with `awaiting_review`.** The next gate's WUs are in `draft`
+  and the driver will refuse to execute them until you arm them. **Arming is the
+  human checkpoint and is deliberately not automated.**
+
+Run **`/arm-gate`**. It walks each drafted WU — accept / revise / reject — flips
+the ones you accept to `pending`, marks the finished gate `passed`, and prints the
+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 `specfuse-loop`. Repeat until the terminal gate is `done`.
+
+## 7. Wrap up
+
+When the terminal gate is `done`, run **`/wrap-feature`**: it pushes the feature
+branch, opens a PR, optionally watches CI, and points at the next pick. Then
+**`/roadmap-archive`** moves the finished feature's detail out of the active
+roadmap.
+
+---
+
+## Operating a running loop
+
+The driver runs unattended within a gate, but real runs hit snags. The map:
+
+| Symptom | What it means | Do this |
+|---------|---------------|---------|
+| Driver halts, a WU is `blocked_human` | A unit failed three attempts or hit an escalation trigger | Run **`/gate-status`** for a diagnosis (root cause, options, recommended action) |
+| You fixed the blocker (creds, dep, spec) | The WU is still `blocked_human` | Run **`/unblock-wu`** to re-arm it (`blocked_human → pending`, attempts reset), then re-run |
+| Driver exits "could not acquire lock" | Another driver owns this checkout | Find/stop the other driver, or use a separate `git worktree` |
+| A gate is `awaiting_review` | Normal gate boundary | Run **`/arm-gate`** (§6) |
+| The feature isn't worth finishing | — | Run **`/abandon-feature`** — flips every WU/gate/PLAN/roadmap surface cleanly |
+| A WU "passed" but wrote no code | Hollow pass | Tighten the WU's acceptance criteria and verification; see [`authoring-work-units`](skills.md) |
+
+**Where the durable state lives** (nothing important is in a context window):
+
+- `PLAN.md` / `GATE-NN.md` / `WU-*.md` frontmatter — current status of everything.
+- `events.jsonl` (per feature) — the event log; every dispatch emits an
+  `attempt_outcome`.
+- `RETROSPECTIVE.md` — feature-local raw observations from each close.
+- `LEARNINGS.md` (repo root of `.specfuse/`) — cross-feature durable lessons, read
+  at planning time so each plan is better than the last. Run
+  **`/learnings-suggest`** periodically to mine recurring failures into new
+  entries.
+
+When in doubt after a halt, start with **`/gate-status`** — it reads all of the
+above and tells you where you stand.
+
+## Fixing a bug (not a feature)
+
+Bugs don't go through the feature methodology. Run **`/fix-bug`** with the issue
+number or report: it's 1 bug = 1 branch = 1 PR, test-first. It refuses and
+proposes promoting to a feature if the work turns out large or risky.
+
+## Next
+
+- [`methodology.md`](methodology.md) — the full gate-cycle contract.
+- [`skills.md`](skills.md) — every skill, by lifecycle phase.
+- [`concepts/ralph-lineage.md`](concepts/ralph-lineage.md) — why the loop is
+  shaped the way it is.