specfuse-loop 0.9.2__tar.gz → 0.10.0__tar.gz

{specfuse_loop-0.9.2/specfuse_loop.egg-info → specfuse_loop-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.9.2
+Version: 0.10.0
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0
@@ -81,7 +81,7 @@ 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-loop`, from the pip package) walks the current gate's
+- The **driver** (`specfuse run`, from the `specfuse-loop` 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
@@ -108,8 +108,9 @@ checks CI runs — before each `git push`). Bypass with `git push --no-verify`.
 The driver installs from PyPI and the skills ship as a Claude Code plugin:
 
 ```bash
-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)
+pipx install specfuse                           # or: uv tool install specfuse
+#   one command for the whole suite: specfuse run / lint / monitor / stats / …
+#   (or: python3 -m pip install specfuse, in a venv)
 
 # in Claude Code, enable the skills plugin (one-time):
 #   /plugin marketplace add specfuse/specfuse
@@ -120,19 +121,28 @@ specfuse init /path/to/your-project             # scaffold .specfuse/ + wire .cl
 cd /path/to/your-project
 $EDITOR .specfuse/verification.yml              # match the `code` gates to your stack
 # author your first feature (in Claude Code: /draft-feature)
-specfuse-loop --dry-run                          # show the gate walk, no dispatch
-specfuse-loop                                    # the real run
+specfuse run --dry-run                           # show the gate walk, no dispatch
+specfuse run                                     # the real run
 ```
 
-> **Distribution.** Code ships via pip — `specfuse` (umbrella CLI: `init` /
-> `upgrade`) pulls `specfuse-loop` (the driver); Claude assets ship via the
+> **Distribution.** Code ships via pip — the `specfuse` umbrella hard-depends on
+> `specfuse-loop` (the driver) and every other component, so `pipx upgrade
+> specfuse` / `uv tool upgrade specfuse` re-resolves the whole suite. 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
+> is the same idempotent operation over an existing scaffold. Every `specfuse
+> 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.)
+>
+> **Flat commands are deprecated.** `specfuse-loop`, `specfuse-lint`,
+> `specfuse-monitor`, `specfuse-monitor-lint` and `specfuse-stats` still work as
+> aliases until 1.0.0, with identical arguments and behaviour. Use the
+> subcommands. `specfuse doctor` reports which flat names are still on your PATH;
+> `SPECFUSE_NO_DEPRECATION_WARNING=1` silences the notice in noisy hooks or CI.
+> `pip install specfuse-loop` on its own remains supported for library use.
 
 > **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

{specfuse_loop-0.9.2 → specfuse_loop-0.10.0}/README.md

@@ -48,7 +48,7 @@ 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-loop`, from the pip package) walks the current gate's
+- The **driver** (`specfuse run`, from the `specfuse-loop` 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
@@ -75,8 +75,9 @@ checks CI runs — before each `git push`). Bypass with `git push --no-verify`.
 The driver installs from PyPI and the skills ship as a Claude Code plugin:
 
 ```bash
-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)
+pipx install specfuse                           # or: uv tool install specfuse
+#   one command for the whole suite: specfuse run / lint / monitor / stats / …
+#   (or: python3 -m pip install specfuse, in a venv)
 
 # in Claude Code, enable the skills plugin (one-time):
 #   /plugin marketplace add specfuse/specfuse
@@ -87,19 +88,28 @@ specfuse init /path/to/your-project             # scaffold .specfuse/ + wire .cl
 cd /path/to/your-project
 $EDITOR .specfuse/verification.yml              # match the `code` gates to your stack
 # author your first feature (in Claude Code: /draft-feature)
-specfuse-loop --dry-run                          # show the gate walk, no dispatch
-specfuse-loop                                    # the real run
+specfuse run --dry-run                           # show the gate walk, no dispatch
+specfuse run                                     # the real run
 ```
 
-> **Distribution.** Code ships via pip — `specfuse` (umbrella CLI: `init` /
-> `upgrade`) pulls `specfuse-loop` (the driver); Claude assets ship via the
+> **Distribution.** Code ships via pip — the `specfuse` umbrella hard-depends on
+> `specfuse-loop` (the driver) and every other component, so `pipx upgrade
+> specfuse` / `uv tool upgrade specfuse` re-resolves the whole suite. 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
+> is the same idempotent operation over an existing scaffold. Every `specfuse
+> 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.)
+>
+> **Flat commands are deprecated.** `specfuse-loop`, `specfuse-lint`,
+> `specfuse-monitor`, `specfuse-monitor-lint` and `specfuse-stats` still work as
+> aliases until 1.0.0, with identical arguments and behaviour. Use the
+> subcommands. `specfuse doctor` reports which flat names are still on your PATH;
+> `SPECFUSE_NO_DEPRECATION_WARNING=1` silences the notice in noisy hooks or CI.
+> `pip install specfuse-loop` on its own remains supported for library use.
 
 > **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

{specfuse_loop-0.9.2 → specfuse_loop-0.10.0}/pyproject.toml

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

{specfuse_loop-0.9.2 → specfuse_loop-0.10.0}/specfuse/loop/closing_requirements.py

@@ -179,8 +179,9 @@ class Requirement:
     """One closing-artifact requirement, as data.
 
     ``applies_when`` names the condition under which the requirement fires:
-    ``always``, ``verdict_met``, ``verdict_hedged``, ``failures_present``, or
-    ``autoclose_debt_marker``. ``phase`` is ``pre-squash`` (checked by
+    ``always``, ``verdict_met``, ``verdict_hedged``, ``failures_present``,
+    ``autoclose_debt_marker``, or ``criteria_artifact_present`` (the gate's
+    ``GATE-NN-CRITERIA.md`` exists). ``phase`` is ``pre-squash`` (checked by
     ``assert_closing_deliverables`` right after the WU's own squash) or
     ``post-pass`` (checked by ``verify_post_pass_invariants`` after the
     gate-boundary state flips run).
@@ -299,6 +300,18 @@ CLOSING_REQUIREMENTS: dict[str, list[Requirement]] = {
             file=RETROSPECTIVE_FILENAME,
             enforced_by="assert_changelog_entry_for_contract_changes",
         ),
+        Requirement(
+            id="close-l", wu_type="close", phase="pre-squash",
+            description=(
+                "Every entry in GATE-NN-CRITERIA.md carries a kind: in "
+                "criteria_state.ORACLE_KINDS and a state: in "
+                "criteria_state.CRITERION_STATES, and every entry whose kind "
+                "has no knowable scope and whose state reads pass carries an "
+                "attempt: equal to the current attempt"
+            ),
+            applies_when="criteria_artifact_present",
+            enforced_by="check_criteria_state_well_formed",
+        ),
     ],
     "close-intermediate": [
         Requirement(
@@ -343,6 +356,18 @@ CLOSING_REQUIREMENTS: dict[str, list[Requirement]] = {
             file=LEARNINGS_PATH,
             enforced_by="assert_learnings_staged_under_auto",
         ),
+        Requirement(
+            id="close-intermediate-f", wu_type="close-intermediate", phase="pre-squash",
+            description=(
+                "Every entry in GATE-NN-CRITERIA.md carries a kind: in "
+                "criteria_state.ORACLE_KINDS and a state: in "
+                "criteria_state.CRITERION_STATES, and every entry whose kind "
+                "has no knowable scope and whose state reads pass carries an "
+                "attempt: equal to the current attempt"
+            ),
+            applies_when="criteria_artifact_present",
+            enforced_by="check_criteria_state_well_formed",
+        ),
     ],
     "plan-next": [
         Requirement(

{specfuse_loop-0.9.2 → specfuse_loop-0.10.0}/specfuse/loop/cost.py

@@ -5,22 +5,27 @@
 """One lifetime-cost reader shared by both cost-gated consumers.
 
 `wu_lifetime_cost_usd` answers "what has this work unit cost over its whole
-life," correctly on both re-arm shapes recorded in FEAT-2026-0062/PLAN.md:
-
-  * fold-ran   — a re-arm folded the prior cycle's spend into
-                 `cumulative_cost_usd`, and `re_arm_history[].prior_cost_usd`
-                 names the same money.
-  * fold-never-ran — the prior cycle's spend survives only in
-                 `re_arm_history[].prior_cost_usd`; `cumulative_cost_usd` is
-                 absent.
-
-Summing frontmatter fields cannot distinguish these shapes without replaying
-fold history, and naive summation double-counts the fold-ran shape. Instead
-this module sums `payload.cost_usd` across every `attempt_outcome` event for
-the work unit in `events.jsonl` — a source that already carries every
-dispatch cycle's cost exactly once, independent of fold shape. Frontmatter is
-used only as a fallback for the units this repo's corpus shows have no usable
-event history (see FEAT-2026-0062 criterion 9's measurement).
+life." FEAT-2026-0067 converged the fold onto one path: every re-arm now
+unconditionally folds the prior cycle's spend into `cumulative_cost_usd`
+(driven by an explicit `folded_through_re_arm` marker, not by inferring state
+from a value), so `cumulative_cost_usd` is the lifetime accumulator and
+`re_arm_history[].prior_cost_usd` is a pure audit record of what each cycle
+cost — not a second place the fold might or might not have run.
+
+Before that migration, some already-re-armed WUs had a prior cycle's spend
+survive only in `re_arm_history[].prior_cost_usd` with `cumulative_cost_usd`
+absent — a pre-migration legacy shape that this module's frontmatter fallback
+still tolerates for projects that have not run the FEAT-2026-0067 migration,
+not an ongoing design a reader needs to branch on.
+
+Summing frontmatter fields cannot distinguish "already folded" from "never
+folded" without replaying fold history, and naive summation double-counts a
+folded record. Instead this module sums `payload.cost_usd` across every
+`attempt_outcome` event for the work unit in `events.jsonl` — a source that
+already carries every dispatch cycle's cost exactly once, independent of fold
+shape. Frontmatter is used only as a fallback for the units this repo's
+corpus shows have no usable event history (see FEAT-2026-0062 criterion 9's
+measurement).
 
 Deliberately dependency-light: this module must not import `loop.py` or
 `arm_eval.py` (see `arm_eval.py`'s module docstring on the `loop -> arm_eval`

specfuse_loop-0.10.0/specfuse/loop/criteria_state.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+#
+# Copyright 2026 Specfuse contributors
+# Licensed under the Apache License, Version 2.0. See LICENSE.
+#
+"""Per-criterion close state — schema, parser, renderer (FEAT-2026-0056/T01).
+
+Defines the entry shape for `GATE-NN-CRITERIA.md`, the per-gate artifact that
+lets a close remember, per acceptance criterion, which oracle proved it, that
+oracle's exit code, and the tree state it ran against. Follows the shape of
+`closing_requirements.py`'s hedged-verdict follow-up record: a per-entry
+classified record living inside a markdown artifact, regex-parsed, with the
+classification written by the close that ran the oracle and never inferred by
+a reader.
+
+Data and parsing only — no file I/O, no driver wiring, no skip policy. See
+FEAT-2026-0056/PLAN.md and GATE-01.md for the design this module encodes.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+#: An oracle's scope classification. `narrow` oracles (a scoped test nodeid,
+#: a symbol-existence import, a structural assert, a countable grep) survive
+#: a re-close; `broad` oracles (the full suite, a full regen, a scenario
+#: matrix) re-run unconditionally on every close attempt.
+ORACLE_KINDS: frozenset = frozenset({"narrow", "broad"})
+
+#: A criterion's recorded verification outcome for a given close attempt.
+CRITERION_STATES: frozenset = frozenset({"pass", "fail", "unverified"})
+
+_ENTRY_HEADING_RE = re.compile(r"^### (\S+)\s*$", re.MULTILINE)
+
+_FIELD_PATTERNS = {
+    "criterion": re.compile(r"^- \*\*criterion:\*\*\s*(.+)$", re.MULTILINE),
+    "oracle": re.compile(r"^- \*\*oracle:\*\*\s*(.+)$", re.MULTILINE),
+    "kind": re.compile(r"^- \*\*kind:\*\*\s*`([^`]+)`", re.MULTILINE),
+    "state": re.compile(r"^- \*\*state:\*\*\s*`([^`]+)`", re.MULTILINE),
+    "proved_at_sha": re.compile(r"^- \*\*proved_at_sha:\*\*\s*`([^`]+)`", re.MULTILINE),
+    "attempt": re.compile(r"^- \*\*attempt:\*\*\s*`?([^`\n]+)`?", re.MULTILINE),
+}
+
+
+@dataclass(frozen=True)
+class CriterionStateEntry:
+    """One `### <criterion_id>` block in a `GATE-NN-CRITERIA.md` artifact."""
+
+    criterion_id: str
+    criterion: Optional[str]
+    oracle: Optional[str]
+    kind: Optional[str]
+    state: Optional[str]
+    proved_at_sha: Optional[str]
+    attempt: Optional[str]
+
+
+#: Matches `GATE-NN-CRITERIA.md` basenames (any `NN`), and nothing else —
+#: not `GATE-NN.md`, not `GATE-NN-REVIEW.md`, not `RETROSPECTIVE.md`.
+CRITERIA_FILENAME_RE = re.compile(r"^GATE-\d+-CRITERIA\.md$")
+
+
+def criteria_filename(gate_n: int) -> str:
+    """The single source of truth for a gate's criteria-artifact basename."""
+    return f"GATE-{gate_n:02d}-CRITERIA.md"
+
+
+def criterion_id_for(wu_sub_id: str, ordinal: int) -> str:
+    """Stable criterion identity: producing WU's sub-ID + 1-based ordinal.
+
+    Ordinal, not a hash of the criterion text — a criterion whose wording is
+    edited between attempts is still the same criterion, and a hash would
+    silently orphan its recorded state.
+    """
+    return f"{wu_sub_id}#{ordinal}"
+
+
+def _extract_field(block: str, name: str) -> Optional[str]:
+    m = _FIELD_PATTERNS[name].search(block)
+    if not m:
+        return None
+    return m.group(1).strip()
+
+
+def parse_criteria_state(text: str) -> list[CriterionStateEntry]:
+    """Parse a `GATE-NN-CRITERIA.md` artifact into entries, in document order.
+
+    A block missing a field yields that field as `None` rather than raising —
+    the artifact is written incrementally across attempts, so a partially
+    populated block is a normal, not exceptional, state.
+    """
+    headings = list(_ENTRY_HEADING_RE.finditer(text))
+    entries: list[CriterionStateEntry] = []
+    for i, m in enumerate(headings):
+        criterion_id = m.group(1)
+        start = m.end()
+        end = headings[i + 1].start() if i + 1 < len(headings) else len(text)
+        block = text[start:end]
+        entries.append(
+            CriterionStateEntry(
+                criterion_id=criterion_id,
+                criterion=_extract_field(block, "criterion"),
+                oracle=_extract_field(block, "oracle"),
+                kind=_extract_field(block, "kind"),
+                state=_extract_field(block, "state"),
+                proved_at_sha=_extract_field(block, "proved_at_sha"),
+                attempt=_extract_field(block, "attempt"),
+            )
+        )
+    return entries
+
+
+@dataclass(frozen=True)
+class ReverificationWorklist:
+    """Partition of a gate's recorded entries for a re-dispatched close attempt.
+
+    `carry_forward` entries are provably safe to skip re-verifying this
+    attempt; `reverify` entries must re-run their oracle. `oracle_groups`
+    collapses byte-identical oracle commands among `reverify` entries so each
+    runs once per attempt rather than once per criterion.
+    """
+
+    carry_forward: list[CriterionStateEntry]
+    reverify: list[CriterionStateEntry]
+    oracle_groups: list[tuple[str, list[str]]]
+
+
+def build_reverification_worklist(
+    entries: list[CriterionStateEntry], current_attempt: str
+) -> ReverificationWorklist:
+    """Partition recorded entries into what a re-close may carry vs. re-verify.
+
+    An entry carries forward only when it is provably safe: `kind ==
+    "narrow"`, `state == "pass"`, a non-empty `oracle`, and a non-empty
+    `attempt`. Everything else — a missing or unrecognized `kind`, `state:
+    fail` or `state: unverified`, and every `broad` entry regardless of
+    state — goes to `reverify`. Fail-safe default: unclassifiable entries
+    land in `reverify`, never in `carry_forward`.
+    """
+    carry_forward: list[CriterionStateEntry] = []
+    reverify: list[CriterionStateEntry] = []
+    for entry in entries:
+        if (
+            entry.kind == "narrow"
+            and entry.state == "pass"
+            and entry.oracle
+            and entry.attempt
+        ):
+            carry_forward.append(entry)
+        else:
+            reverify.append(entry)
+
+    groups: dict[str, list[str]] = {}
+    order: list[str] = []
+    for entry in reverify:
+        if not entry.oracle:
+            continue
+        if entry.oracle not in groups:
+            groups[entry.oracle] = []
+            order.append(entry.oracle)
+        groups[entry.oracle].append(entry.criterion_id)
+    oracle_groups = [(oracle, groups[oracle]) for oracle in order]
+
+    return ReverificationWorklist(
+        carry_forward=carry_forward,
+        reverify=reverify,
+        oracle_groups=oracle_groups,
+    )
+
+
+def render_criteria_state(entries: list[CriterionStateEntry]) -> str:
+    """Render entries back into `GATE-NN-CRITERIA.md` markdown.
+
+    Round-trips through `parse_criteria_state` — a missing field is simply
+    omitted from its block rather than rendered as a literal `None`.
+    """
+    blocks = []
+    for entry in entries:
+        lines = [f"### {entry.criterion_id}", ""]
+        if entry.criterion is not None:
+            lines.append(f"- **criterion:** {entry.criterion}")
+        if entry.oracle is not None:
+            lines.append(f"- **oracle:** {entry.oracle}")
+        if entry.kind is not None:
+            lines.append(f"- **kind:** `{entry.kind}`")
+        if entry.state is not None:
+            lines.append(f"- **state:** `{entry.state}`")
+        if entry.proved_at_sha is not None:
+            lines.append(f"- **proved_at_sha:** `{entry.proved_at_sha}`")
+        if entry.attempt is not None:
+            lines.append(f"- **attempt:** `{entry.attempt}`")
+        blocks.append("\n".join(lines) + "\n")
+    return "\n".join(blocks)

specfuse_loop-0.10.0/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.10.0

{specfuse_loop-0.9.2 → specfuse_loop-0.10.0}/specfuse/loop/data/docs/concepts/adopting-auto-mode.md

@@ -44,7 +44,7 @@ Additive, present whether or not any feature in the project uses `auto`:
   (`close-e` / `close-intermediate-e`, `closing_requirements.py`), fired when
   a closing WU under `autonomy_default: auto` touches `.specfuse/LEARNINGS.md`
   directly instead of staging to `LEARNINGS-pending.md`. Changes
-  `specfuse-lint --closing` output accordingly. Inert outside `auto`, but the
+  `specfuse lint --closing` output accordingly. Inert outside `auto`, but the
   requirement registry is a published surface every project's lint now
   carries.
 

{specfuse_loop-0.9.2 → specfuse_loop-0.10.0}/specfuse/loop/data/docs/getting-started.md

@@ -14,22 +14,26 @@ 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):
+Install the umbrella package — it hard-depends on every component, so one
+install puts the whole suite behind a single `specfuse` command. It's a
+command-line app, so **pipx** (or **uv**) is the recommended installer (isolated
+environment, no `--break-system-packages` on PEP 668 / externally-managed
+Pythons):
 
 ```bash
 pipx install specfuse           # recommended
+uv tool install specfuse        # equivalent
 # or, inside a virtualenv you control:
 python3 -m pip install specfuse
 ```
 
+Upgrade the whole suite the same way — `pipx upgrade specfuse` /
+`uv tool upgrade specfuse` re-resolves every component. No extras, no flags, no
+bracket quoting.
+
 > 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.
+> venv) — that's what puts `specfuse` on PATH for the gate commands to find.
 
 > **Windows: Git-Bash is required.** The driver runs natively on Windows (no WSL),
 > but it routes gate commands through **Git-Bash** so a target repo's
@@ -65,7 +69,7 @@ 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/`
+> **Self-provisioning.** Every `specfuse 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
@@ -124,7 +128,7 @@ the loop will refuse to start until the folder is on its branch and committed.
 Let the driver do both for you:
 
 ```bash
-specfuse-loop --prepare      # create the PLAN.md `branch:`, commit the folder, then run
+specfuse run --prepare      # create the PLAN.md `branch:`, commit the folder, then run
 ```
 
 (Or by hand: `git checkout -b <branch>` from `PLAN.md`'s frontmatter, then
@@ -133,7 +137,7 @@ specfuse-loop --prepare      # create the PLAN.md `branch:`, commit the folder,
 ## 4. Validate before running
 
 ```bash
-specfuse-lint .specfuse/features/FEAT-YYYY-NNNN-your-feature
+specfuse lint .specfuse/features/FEAT-YYYY-NNNN-your-feature
 ```
 
 The linter checks structure: every WU has the five mandatory sections, the closing
@@ -144,8 +148,8 @@ 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
+specfuse run --dry-run     # show the gate walked, in dep order, no dispatch
+specfuse run               # the real thing
 ```
 
 With no `--feature` flag the driver picks the single `active` feature. For each
@@ -188,7 +192,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 `specfuse-loop`. Repeat until the terminal gate is `done`.
+Then re-run `specfuse run`. Repeat until the terminal gate is `done`.
 
 ## 7. Wrap up
 

specfuse_loop-0.10.0/specfuse/loop/data/docs/glossary.md

@@ -0,0 +1,108 @@
+# Glossary
+
+The words Specfuse uses, in the order you meet them. Each entry says what the
+thing *is* and, where one exists, the command or skill that acts on it.
+
+For the full contract behind any of these, see
+[`methodology.md`](methodology.md); this page is the first read, not the
+reference.
+
+## The shape of the work
+
+**Roadmap** — `.specfuse/roadmap.md`, the ordered list of features a project
+intends to build, one row each. Add to it with `/roadmap-add`; pick what to
+build next with `/pick-feature`.
+
+**Feature** — one substantial piece of work, `FEAT-YYYY-NNNN`, with a folder
+under `.specfuse/features/`. Its `PLAN.md` holds the goal, the gates, and the
+budget. Roughly: a thing you would describe in a sentence to someone who does
+not work on the project.
+
+**Gate** — a stage of a feature, numbered from 1. A gate holds a set of work
+units, a budget, and acceptance criteria. **The gate is where the loop stops
+and you decide** — everything inside one runs unattended; the boundary between
+two is yours.
+
+**Work unit (WU)** — the smallest dispatchable piece: one file, one job, one
+fresh session. `FEAT-YYYY-NNNN/T01`. Everything the session needs is in that
+file, because it starts with no memory of anything before it.
+
+**Verification** — the commands in `.specfuse/verification.yml` that decide
+whether a work unit actually passed. The loop runs them itself and does not
+take the session's word for it.
+
+**LEARNINGS** — `.specfuse/LEARNINGS.md`, what earlier work taught, carried
+into later planning so the same mistake is not made twice.
+
+## What happens to it
+
+**Draft** — write a feature and its first gate's work units, usually with
+`/draft-feature`. Drafted units are proposals; nothing runs yet.
+
+**Arm** — review the drafted units and accept, revise, or reject each, then
+release the gate to run. This is the human checkpoint. `/arm-gate`.
+
+**Dispatch** — hand one work unit to a fresh session and let it work.
+`specfuse run` walks the current gate and dispatches whatever is ready.
+
+**Attempt** — one dispatch of one work unit. A unit gets three before the loop
+gives up and asks you.
+
+**Close** — the ceremony that ends a gate: what was learned, what it cost,
+whether the goal was met, and drafting the next gate. The loop runs it as a
+work unit like any other.
+
+**Wrap** — finish the feature: push the branch, open the pull request.
+`/wrap-feature`.
+
+**Self-provisioning** — every `specfuse run` first checks whether
+`.specfuse/` matches the installed version and updates it if not, so an upgrade
+reaches a project on its next run.
+
+## States you will see
+
+**A feature** is `planned`, `active`, `blocked`, `done`, or `abandoned`.
+`blocked` means a named dependency is unmet — clear it with `/block-feature
+--unblock`.
+
+**A gate** is `open` (running), `awaiting_review` (finished, waiting for you to
+arm the next one), or `passed`.
+
+**A work unit** is `draft`, `pending` (armed, waiting its turn), `in_progress`,
+`done`, `abandoned`, or `blocked_human`.
+
+**`blocked_human`** — a unit tried, failed three times, and stopped. Nothing is
+broken and nothing is lost; it needs a decision. `/gate-status` explains what
+happened, `/unblock-wu` re-arms it once you have fixed the cause.
+
+**A close verdict** is `met` (the goal was achieved and shown), `met_locally`
+(achieved here, but not proven beyond this repository), `partially_met`, or
+`not_met`. The middle two are **hedged**: the feature is held short of finished
+on purpose until you accept the gap, with `/accept-hedged-close`.
+
+## Terms that look like jargon because they are
+
+**Oracle** — the check that decides pass or fail. A *narrow* oracle tests one
+specific thing, so a pass can be trusted later; a *broad* one (a whole test
+suite) covers too much for its green to be carried forward.
+
+**`produces:`** — the files a work unit promises to deliver. The loop compares
+them against what actually changed, so a unit cannot report success having
+written nothing.
+
+**Hollow pass** — a work unit reporting success without changing anything. The
+`produces:` check exists to catch it.
+
+**Spinning** — repeated attempts making no progress. The loop detects it and
+stops rather than spending the remaining budget.
+
+**Re-arm** — putting a stopped work unit back in the queue after fixing the
+cause. Requires a one-line reason from you, which is the record of why it was
+worth retrying.
+
+**Escalation** — the loop stopping to ask you something, with what it tried,
+why it stopped, the options, and a recommendation.
+
+**Auto mode** — letting safe gates arm themselves. The dangerous boundaries
+still stop for you. See
+[`concepts/adopting-auto-mode.md`](concepts/adopting-auto-mode.md).