@gobing-ai/spur 0.3.55 → 0.3.58

package/plugins/sp/commands/dev-idea.md

@@ -2,12 +2,13 @@
 description: Turn a vague idea into a feature with AC and a decomposed task batch — discovery, idea-eval, feature-create, AC, feature-check, system-design, decompose, batch-create (Design by default), handoff
 role: planner
 argument-hint: "\"<idea>\" [--auto] [--skip-design] [--approve-taste] [--agent <inline|auto|name>]"
-allowed-tools: ["Bash", "Read", "AskUserQuestion"]
+allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
 
 # Dev Idea
 
-Wraps the **idea-pipeline.yaml** workflow.
+Wraps the **sp:spur-dev** skill; the machine is **idea-pipeline.yaml** — the stage
+contract below maps to that workflow's transitions.
 
 ## Argument Flags
 
@@ -40,20 +41,7 @@ vars as subsets of `--approve-taste` (`idea_approved` / `design_approved`). Pref
 
 ## Implementation
 
-Map flags → workflow vars, then:
-
-```bash
-spur workflow run .spur/workflows/idea-pipeline.yaml --vars '{
-  "idea":"<text>",
-  "profile":"interactive|auto",
-  "design":"auto|skip",
-  "design_approved":"false|true",
-  "idea_approved":"false|true",
-  "agent":"<executor-or-role>"
-}'
-```
-
-Omit `agent` from `--vars` unless the operator passed `--agent`: an absent var lets `agent.default`
-(a Layer-1 role, resolved to its tier's cheapest usable executor) govern, which is the intended
-routing. Passing `--agent <name>` pins that executor for every `agent.run` stage — the escape hatch
-when the resolved executor is unusable (quota exhaustion, auth failure).
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- `Skill(skill="sp:spur-dev", args="idea $ARGUMENTS")`
+- Stage contract (discovery → idea-eval → feature-create → AC → feature-check → system-design →
+  decompose → batch-create → handoff): `plugins/sp/skills/spur-dev/references/dev-operations.md` § idea.

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.55",
+    "version": "0.3.58",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/scripts/task-size-precheck.ts

@@ -141,13 +141,18 @@ function runSpur(spurBin: string, args: string[]): string {
  * tier all read as `standard` — conservative: a false block is one flag away,
  * a false pass costs a 30-minute timed-out implement.
  */
-function resolveCapabilityTier(spurBin: string, executor: string): string {
+function resolveCapabilityTier(spurBin: string, executor: string): { tier: string; resolvedName: string } {
     try {
         const out = runSpur(spurBin, ['agent', 'doctor', executor, '--json']);
-        const tier = JSON.parse(out)?.agents?.[0]?.capabilityTier;
-        return typeof tier === 'string' && tier ? tier : 'standard';
+        const row = JSON.parse(out)?.agents?.[0];
+        const tier = row?.capabilityTier;
+        // R1 (0622 F2/F4 residue): `doctor <role>` resolves the role to its cheapest
+        // eligible executor (`coder` → `omp`); surface the resolved executor name in
+        // the block message, not the role the caller passed in.
+        const resolvedName = typeof row?.agent === 'string' && row.agent.length > 0 ? row.agent : executor;
+        return { tier: typeof tier === 'string' && tier ? tier : 'standard', resolvedName };
     } catch {
-        return 'standard';
+        return { tier: 'standard', resolvedName: executor };
     }
 }
 
@@ -185,11 +190,11 @@ function main(): void {
     // R3 (0487): a large task on a sub-capable executor blocks even when the caller
     // raised the caps — the caps are an acceptance of size, not a capability grant.
     if (executor && (reqCount > LARGE_TASK_REQS || planItemCount > LARGE_TASK_PLAN_ITEMS)) {
-        const tier = resolveCapabilityTier(spurBin, executor);
+        const { tier, resolvedName } = resolveCapabilityTier(spurBin, executor);
         if (!CAPABLE_TIERS.has(tier)) {
             reasons.push(
                 `Task size (${reqCount} R-items / ${planItemCount} Plan items) requires a capable executor, ` +
-                    `but ${executor} is tier ${tier}. ` +
+                    `but ${resolvedName} is tier ${tier}. ` +
                     `Pass \`--agent <capable>\` or \`--vars '{"implementAgent":"<capable>"}'\`, or split the task.`,
             );
         }

package/plugins/sp/skills/dogfood-testing/references/monitor-ledger.md

@@ -19,7 +19,7 @@ lives in the dual artifacts (see [report-template.md](report-template.md) → Al
 artifacts):
 
 | File | Path |
-|------|------|
+| ------ | ------ |
 | Live | `.spur/run/dogfood/<run_id>.md` |
 | Report | `docs/dogfood/YYYY-MM-DD-<testee-slug>-dogfood.md` |
 
@@ -73,7 +73,7 @@ in the report's §6 Findings (no exemption applies).
 ```
 
 | Column | Meaning |
-|--------|---------|
+| -------- | --------- |
 | `Step` | The derived step label (Phase 1) or `N` for a single-step testee. |
 | `Attempts` | How many times the step was run (1 = first-try; >1 = retried under the fix budget). |
 | `Outcome` | `PASS` / `FIXED` / `UNRESOLVED` / `N/A`. (`FIXED` = failed then passed within budget.) |
@@ -114,7 +114,7 @@ Ledger estimates alone are **confidence: LOW**. When assembling the report Cost
 ([report-template.md](report-template.md) §2):
 
 | Source | When to use | Confidence | Scope label |
-|--------|-------------|------------|-------------|
+| -------- | ------------- | ------------ | ------------- |
 | Ledger `chars/4` heuristic | Always | LOW | per-step trend |
 | `ccusage` daily/session | If CLI available and returns data | MEDIUM | day or session — **not** per-step |
 | Agent usage fields in tool results | If present (never invent) | MEDIUM | as reported by the tool |
@@ -168,7 +168,7 @@ the driver re-fetching data it already holds. Apply these while monitoring each
 When aggregate cache% risks falling under 50%, apply this checklist **before** re-reading:
 
 | # | Action | Why |
-|---|--------|-----|
+| --- | -------- | ----- |
 | 1 | Reuse the Step-1 `spur task show --json` capture for the rest of the run | Avoids re-tokenizing the full task body |
 | 2 | Do not re-Read SKILL.md / report-template after Phase 1 loaded them | Skill body is large; keep one copy in context |
 | 3 | Prefer `--json` CLI over re-parsing freeform prose | Smaller, stable payloads |

package/plugins/sp/skills/dogfood-testing/references/report-template.md

@@ -25,7 +25,7 @@ colon form — the dash form `sp-dogfood-testing@…` is rejected in new runs.
 Every dogfood run **always** writes **two** files — with or without `--save`:
 
 | Artifact | Path | Role |
-|----------|------|------|
+| ---------- | ------ | ------ |
 | **Live** | `.spur/run/dogfood/<run_id>.md` | Mid-run SSOT; opened in Phase 1; ledger rows appended on every step resolve |
 | **Report** | `docs/dogfood/YYYY-MM-DD-<testee-slug>-dogfood.md` | Operator artifact; same content promoted on open + every step + finalize |
 
@@ -59,7 +59,7 @@ workspace_fingerprint:    ← optional — recorded in Phase 1 for fix-mode and
 ### Status model (partial-OK)
 
 | `status` | When |
-|----------|------|
+| ---------- | ------ |
 | `running` | Phase 1 opened; steps still in progress |
 | `aborted` | Finalize-or-abort after mid-run stop / incomplete narrative |
 | `complete` | Phase 4 finished a normal end-of-run report |
@@ -238,6 +238,7 @@ downstream task creation does not inherit an unactionable acceptance criterion:
 The tag is a prompt to whoever turns findings into tasks: `[stale]` → drop, `[unverifiable]` →
 reframe or defer, `[feasible]` → proceed. A finding without a tag is treated as `[feasible]`.
 Severity scale:
+
 - **P1** — blocks correct use or causes drift/wrong output; fix before shipping the testee.
 - **P2** — real friction or a latent correctness gap; fix soon. **Includes mandatory workspace-drift
   finding:** when a drift row (`drift:external`) is present in the ledger, a P2 finding naming the
@@ -310,6 +311,7 @@ Findings (P1+P2):
 ```
 
 Rules:
+
 - **Result** and **Tokens** lines are mandatory; always tag token numbers `[~estimate]`.
 - List Fixed / Unresolved / Findings; print `(none)` when empty — never omit a sub-list.
 - With `--full`, Findings include P3+P4.

package/plugins/sp/skills/issue-finding/SKILL.md

@@ -139,14 +139,23 @@ sessions (typed ETL via `spur history` — or raw JSONL under the three fallback
 **Primary path (typed sources):** `spur history report --mode forensics` (task 0555).
 
 ```bash
-# 0568 R4: SPUR_BIN env > local CLI > PATH — stale PATH spur fails history import.
-SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
-
-$SPUR_BIN history import --source <source> --json   # checkpoint resume
-$SPUR_BIN history analyze --json                    # writes versioned artifact (0554)
-$SPUR_BIN history report --mode forensics           # pure renderer; latest artifact pointer
+# 0568 R4 / 0504 R4: SPUR_BIN env > local CLI. NEVER a bare PATH `spur` for history validation —
+# a stale global binary silently runs old code. If SPUR_BIN is unset and apps/cli/src/index.ts
+# is absent, FAIL LOUDLY instead of falling back to PATH.
+SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo '')}"
+[ -n "$SPUR_BIN" ] || { echo 'REFUSING: no source-local spur and SPUR_BIN unset (0504 R4)'; exit 1; }
+
+$SPUR_BIN history import --source <source> --json   # checkpoint resume; record provenance header
+$SPUR_BIN history analyze --sessions <ids> --source <src> --json   # narrow the artifact (T2: full run → 2.7 MB trap)
+$SPUR_BIN history report --mode forensics           # pure renderer; reads the LATEST artifact — verify it is the one you just wrote
 ```
 
+**Artifact-size discipline:** `history analyze` without narrowing writes an artifact covering every
+session in the DB — multi-MB blobs that drown the context. Narrow with `--sessions` / `--source` to
+the corpus this investigation actually needs. `history report` renders whatever artifact the latest
+pointer references; if you ran analyze for another purpose in between, re-run analyze (narrowed)
+before reporting.
+
 The forensics renderer emits **8 CLI-derivable sections**: Session Data Summary, Tool Breakdown,
 Token Profile (tokens + cache-hit ratio — never prices), Time Decomposition, Per-Phase, Per-Tool
 Execution Time, Bottleneck Ranking, and the Raw Data appendix. The CLI does not write the
@@ -271,7 +280,9 @@ EOF
 spur task update <wbs> --section Background --from-file /tmp/issue-bg.md --json
 ```
 
-**Required sections for a meta issue-finding task:**
+**Recommended sections for a meta issue-finding task** (live matrix `.spur/tasks/section-matrix.yaml`
+meta variant — `Root Cause` is allowed at every status; `Notes` and `References` are **not** defined
+sections and must not be authored):
 
 | Section             | Content                                                                                              |
 | ------------------- | ---------------------------------------------------------------------------------------------------- |
@@ -281,17 +292,18 @@ spur task update <wbs> --section Background --from-file /tmp/issue-bg.md --json
 | Q&A                 | 4–6 Q&A pairs: rationale, approach, hook vs guidance, savings, decomposition                         |
 | Design              | Per-fix evidence (counts, timestamps), fix content, target location                                  |
 | Plan                | Ordered checkboxes referencing requirements                                                          |
-| Notes               | Root-cause analyses (RC1–RC*n*) with forensic evidence (meta template: **not** a Root Cause section) |
-| References          | Session JSONL paths, source/agent, guard `file:line`, pipeline YAML, commits                         |
+| Root Cause          | RC1–RC*n* analyses with forensic evidence — allowed at every status for meta tasks                   |
+
 
 **Section format rules** (from task 0379):
 
 1. **Solution `file:line` citations**: repo-relative `file:line` (e.g. `apps/web/src/components/SupervisorTab.tsx:17-20`), never bare `:line` or bare filename without path.
 2. **Review P1–P4 table**: if a Review section exists, include a table with a cell matching
    `/^\s*P[1-4]\s*$/` and a non-placeholder content cell.
-3. **Meta template**: no `Root Cause` section — put analyses in `Notes`.
+3. **Meta template**: `Root Cause` is allowed at every status for meta tasks (live matrix) —
+   put RC analyses there, never in `Notes` or `References` (undefined sections).
 4. **Canonical sections only**: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`,
-   `Design`, `Plan`, `Solution`, `Root Cause`, `Testing`, `Review`, `References`, `History`, `Notes`.
+   `Design`, `Plan`, `Solution`, `Root Cause`, `Testing`, `Review`, `History`.
 5. **Section body**: body-only for `--section` (no duplicate heading).
 6. **Batch writes**: write all section temps → apply all `spur task update --section` calls →
    **one** `spur task check`. Never write-check-rewrite-check per section.

package/plugins/sp/skills/spur-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spur-cli
-description: "The CLI facade for the `spur` command surface - one reference per noun (task/feature/rule/workflow/agent/message/team/init/status/serve): verbs, flags, `--json` shapes, exit codes, the CLI-gated write contract. NOT for driving the lifecycle (that is the spine, sp:spur-dev). Triggers: \"spur task\", \"spur feature\", \"spur rule\", \"spur workflow\", \"spur agent\", \"spur message\", \"spur team\", \"spur status\", \"spur init\", \"spur serve\", \"create a task\", \"task check\", \"batch-create\", or looking up any spur CLI verb or convention."
+description: "The CLI facade for the `spur` command surface - one reference per noun (task/feature/rule/workflow/builder/agent/message/team/self): verbs, flags, `--json` shapes, exit codes, the CLI-gated write contract. NOT for driving the lifecycle (that is the spine, sp:spur-dev). Triggers: \"spur task\", \"spur feature\", \"spur rule\", \"spur workflow\", \"spur agent\", \"spur message\", \"spur team\", \"spur self\", \"spur self init\", \"spur self status\", \"create a task\", \"task check\", \"batch-create\", or looking up any spur CLI verb or convention."
 license: Apache-2.0
 metadata:
   author: spur
@@ -14,12 +14,11 @@ metadata:
     - feature
     - rule
     - workflow
+    - builder
     - agent
     - message
     - team
-    - status
-    - init
-    - serve
+    - self
   openclaw:
     emoji: "🧰"
 ---
@@ -27,7 +26,7 @@ metadata:
 # spur-cli — the CLI facade for the Spur command surface
 
 `spur-cli` is the single reference for operating the **`spur` command-line surface**. Each `spur`
-noun (`task`, `feature`, `rule`, `workflow`, `agent`, `message`, `team`, `init`, `status`, `serve`) has one reference file that documents *what each verb
+noun (`task`, `feature`, `rule`, `workflow`, `builder`, `agent`, `message`, `team`, `self`) has one reference file that documents *what each verb
 is, how to use it well, its flags, `--json` shapes, and exit codes*. This skill is a **facade /
 dispatch reference** — it tells you which verb does what and routes you to the noun's detail. It is
 **not** an orchestrator and contains **no competency logic**: the skill knows *how to invoke*; the
@@ -38,17 +37,17 @@ CLI knows *what is valid*; the **spine** (`sp:spur-dev`) knows *how to drive the
 Pick the noun, read its reference. Each Tier A and Tier B reference owns that noun's full verb catalog and conventions.
 
 | Tier | Noun | Operate | Reference |
-|------|------|---------|-----------|
+| ------ | ------ | --------- | ----------- |
 | **Tier A** | **task** | Task corpus: create (variants), `deps` mutation, canonical `sections` (`init`/`add`/`list`), status lifecycle, `record`/`verdict` artifacts, `run-link`, `check --json` matrix | [references/tasks.md](references/tasks.md) |
 | **Tier A** | **feature** | Feature tree: author with hierarchical IDs (DD-14), acceptance criteria (Gherkin), status lifecycle, move subtrees, `check --json` | [references/features.md](references/features.md) |
 | **Tier A** | **rule** | Constraint quality gate: run presets, author rules, fine-tune, validate rule files/presets, extend engine | [references/rules.md](references/rules.md) |
 | **Tier A** | **workflow** | Dual-mode workflow runtime: author state-machine / transition-flow workflows, validate, run, read traces | [references/workflows.md](references/workflows.md) |
+| **Tier A** | **builder** | Release plumbing: bump a package (or the `workspace:`-pinned set) with `bump-ver`, delete release tags with `drop-tags`, commit + tag + optional push | [references/builder.md](references/builder.md) |
 | **Tier B** | **agent** | Coding-agent execution surface: run prompts via detected/named agents, manage team agent specs, persistent self-draining loop, readiness check | [references/agent.md](references/agent.md) |
 | **Tier B** | **message** | Durable inter-agent messaging: send, inbox, reply, watch | [references/message.md](references/message.md) |
 | **Tier B** | **team** | Team coordination and supervision: assign, status, up/down rosters, start/stop supervised processes | [references/team.md](references/team.md) |
-| **Tier B** | **init** / **status** | Project scaffolding (`init`) + status overview; post-scaffold init validation probes & layout classification | [references/init.md](references/init.md) |
-| **Tier B** | **serve** | Local web server fallback: Task Kanban + team supervisor API | [references/serve.md](references/serve.md) |
-| **Tier C** | **history** / **migrate** / **projects** / **help** | Excluded while immature (see exclusion reasons below). Read `spur <noun> --help` as last resort | Last-resort `--help` |
+| **Tier B** | **self** | Self-management verbs: scaffold (`init`), schema migrations (`migrate`), local web server (`serve`), status overview (`status`); `self init` runs post-scaffold validation probes & layout classification | [references/self.md](references/self.md) |
+| **Tier C** | **history** / **projects** / **help** | Excluded while immature (see exclusion reasons below). Read `spur <noun> --help` as last resort | Last-resort `--help` |
 
 **Execute-First Contract:** Load `sp:spur-cli` references first to execute Tier A and Tier B commands directly without calling `spur --help`. Use `spur <noun> --help` only as a last resort for Tier C nouns, version skew, unlisted long-tail flags, or parity assertion failures.
 
@@ -57,9 +56,8 @@ Pick the noun, read its reference. Each Tier A and Tier B reference owns that no
 These nouns are intentionally undocumented - each has a concrete immaturity reason, not an oversight:
 
 | Noun | Reason |
-|------|--------|
+| ------ | -------- |
 | `history` | `report` verb is a TODO stub (`spur history report` prints a marker); surface is still converging. |
-| `migrate` | Zero verbs - bare `spur migrate --json` runs schema migrations. No verb catalog to document. |
 | `projects` | Multi-project management surface (`add`/`remove`/`list`/`start`/`stop`); still evolving and not yet stable enough for a reference. |
 | `help` | Auto-generated by Commander.js; not a real noun. |
 
@@ -105,6 +103,17 @@ the whole point of this facade is that the CLI surface has a single, scalable ho
   semantics — including task and feature status-transition verbs — while multi-step lifecycle
   orchestration belongs to `sp:spur-dev`.
 
+## Shared option registry (0618)
+
+Options shared by two or more command modules are declared once in
+`apps/cli/src/commands/shared-options.ts` and spread at every call site
+(`.option(...SHARED_OPTIONS.<key>)` — parser/default/collector args append after the spread). One
+registry entry per **(flag, description) pair**: semantic homonyms (`--json`,
+`--cwd`) keep separate keys with their distinct texts. When editing a command module, never
+re-declare a shared flag inline — `apps/cli/tests/shared-option-parity.test.ts` fails on any literal
+declaration of a flag string in `SHARED_OPTION_FLAGS`. Add a new shared option by adding the entry
+and spreading it; full contract in `docs/04_DESIGN.md` §1.0.1.
+
 ## See also
 
 - **[references/agent.md](references/agent.md)** - coding-agent execution surface (`run`, `loop`,
@@ -114,10 +123,9 @@ the whole point of this facade is that the CLI surface has a single, scalable ho
   `inbox`, `reply`, `watch`).
 - **[references/team.md](references/team.md)** - team coordination and supervision (`assign`,
   `status`, `up`/`down`, `start`/`stop`).
-- **[references/serve.md](references/serve.md)** - local web server fallback (Task Kanban + team
-  supervisor API).
-- **[references/init.md](references/init.md)** - `spur init` / `spur status` CLI verbs and
-  post-scaffold init validation (Phase 1.5/1.6 probes).
+- **[references/self.md](references/self.md)** - `spur self init|migrate|serve|status` CLI verbs
+  (the four legacy top-level nouns remain hidden aliases). `self init` runs post-scaffold init
+  validation (Phase 1.5/1.6 probes).
 - **`sp:spur-dev`** - the spine that dispatches these verbs into the planning +
   execution lifecycle. Use it to *drive* work; use this facade to *look up or operate a verb*.
 - **`plugins/sp/references/roles.md`** — the Layer-1 role→tier table (`scribe` / `coder` /

package/plugins/sp/skills/spur-cli/references/agent.md

@@ -215,3 +215,8 @@ spur agent delete worker-1 --force
   supervision.
 - **`spur message` (see [message.md](message.md))** - the inbox `--drain` reads from.
 - **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.
+
+> **Shared option declarations (0618):** options shared across command modules resolve from
+> `apps/cli/src/commands/shared-options.ts` (`SHARED_OPTIONS`). Never re-declare a shared flag
+> inline in a command module — see SKILL.md "Shared option registry" and
+> `docs/04_DESIGN.md` §1.0.1.

package/plugins/sp/skills/spur-cli/references/builder.md

@@ -0,0 +1,49 @@
+---
+name: spur-cli-builder
+description: "spur-cli noun reference: operate `spur builder` as the release plumbing surface - bump a workspace package (or the `workspace:`-pinned release set) with `bump-ver`, delete release tags with `drop-tags`, with commit + annotated tag + optional push. Promoted from spur-dev (task 0617, ADR-051); frozen at exactly these two verbs."
+see_also:
+  - spur-cli
+---
+
+# spur builder - release plumbing
+
+`spur builder` is the CLI for **version bumps and release tags**. It wraps the internal
+`spur-dev release` flow behind a public two-verb surface, promoted verbatim from
+`scripts/commands/release.ts` (now a thin forwarder to the same implementation). Package ids are
+the unscoped short names (`@gobing-ai/spur` → `spur`); the released set and the aggregate tag are
+discovered from the repo's own workspace manifests, so the same code serves any git+semver
+monorepo.
+
+This noun is **frozen at exactly two verbs** by operator consent (`docs/design/harness-surface-governance.md`
+§3) — do not invent additional `builder` subcommands.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `bump-ver [package-id] <version>` | Bump one package (manifest + in-source `binaryVersion` + consumer `workspace:` pins), commit, tag, optionally push | `--all` `--push` `--json` |
+| `drop-tags [package-id] <version>` | Delete a package's release tag (local only by default) | `--all` `--remote` `--json` |
+
+A bare `bump-ver <version>` (single positional that parses as semver) or explicit `--all` bumps
+every package pinned via `workspace:` by another workspace package, then adds per-package trace
+tags plus the aggregate `@<scope>/<root>-v<version>` publish tag. `drop-tags --all` mirrors that
+for deletion.
+
+**Exit codes:** `0` success, `1` error (invalid semver, unknown package id, dirty tree, detached
+HEAD, or an existing local/origin tag). **Errors abort before any write** — a re-run after fixing
+the cause is safe.
+
+## `bump-ver` - bump and tag a release
+
+```bash
+spur builder bump-ver spur 0.1.4            # one package: manifest, pins, commit, tag @gobing-ai/spur-v0.1.4
+spur builder bump-ver --all 0.1.4           # every workspace:-pinned package + aggregate tag
+spur builder bump-ver --all 0.1.4 --push    # also push branch + tags to origin
+```
+
+## `drop-tags` - delete release tags
+
+```bash
+spur builder drop-tags spur 0.1.4           # delete the local tag @gobing-ai/spur-v0.1.4
+spur builder drop-tags --all 0.1.4 --remote # delete per-package + aggregate tags, locally and on origin
+```

package/plugins/sp/skills/spur-cli/references/features/hierarchy-mece.md

@@ -158,7 +158,7 @@ work under H.
 - [ ] Sibling set stays MECE at that parent.
 - [ ] Name is capability/outcome, not a package path.
 - [ ] Will attach tasks with `--feature <new-id>` (or parent if intentionally epic-only).
-- [ ] After create: `spur feature refresh` if INDEX must update; `spur feature check <id>`.
+- [ ] After create: `spur feature refresh --feature <new-id>` if INDEX must update; `spur feature check <new-id>`.
 
 ## Checklist: before restructure / `/sp:dev-feature-change`
 
@@ -166,7 +166,7 @@ work under H.
 - [ ] False merges rejected (name overlap ≠ one Goal).
 - [ ] Apply via CLI (`spur feature move`, `spur task update --feature`), not raw ID edits.
 - [ ] Dry-run reviewed; doc rewrites limited to agreed surface (e.g. root `docs/*.md`).
-- [ ] `spur feature refresh` + `spur feature check` after apply.
+- [ ] `spur feature refresh --all` + `spur feature check --json` after apply.
 
 ---
 

package/plugins/sp/skills/spur-cli/references/features/roadmap-priority.md

@@ -78,7 +78,7 @@ For roadmap adjustment work:
 3. Present the proposed moves/status/priority changes before mutating if the blast radius spans
    multiple features.
 4. Apply each accepted deterministic change through `spur feature update` or `spur feature move`.
-5. Run `spur feature refresh` and `spur feature check --json`.
+5. Run `spur feature refresh --all` and `spur feature check --json`.
 
 Do not add `/sp:prd-adjust` for this. The current CLI already has the deterministic primitives; the
 PM value is the ranking and tradeoff judgment.

package/plugins/sp/skills/spur-cli/references/features/verbs.md

@@ -116,7 +116,7 @@ spur feature update  <id> [status] [--field <k> --value <v>] [--section <n> --fr
 spur feature advance <id> [--to <status>] [--folder] [--json]
 spur feature list    [--status <s>] [--priority <p>] [--folder] [--json]
 spur feature move    <id> [--parent <id>] [--dry-run] [--folder] [--json]
-spur feature refresh [--feature <id>] [--folder] [--json]
+spur feature refresh [--feature <id> | --all] [--folder] [--json]
 spur feature sync    [id] | --all [--dry-run] [--force] [--folder] [--json]
 spur feature check   [id] [--strict] [--folder] [--json]
 ```

package/plugins/sp/skills/spur-cli/references/features.md

@@ -27,8 +27,8 @@ what* or *how to write a scenario*, this skill.
 | `advance <id>` | Walk forward along the legal lifecycle path to a target status | `--to <status>` (default `done`) `--folder` `--json` |
 | `list` | List features, filtered | `--status <s>` `--priority <p>` `--folder` `--json` |
 | `move <id>` | Re-parent a subtree (cascade-rename of descendants) | `--parent <id>` `--dry-run` `--folder` `--json` |
-| `refresh` | Rebuild INDEX + each feature `## Tasks` table from task edges (**docs only**; no status change) | `--feature <id>` `--folder` `--json` |
-| `check [id]` | Validate one feature / the tree; the 4-layer gate | `--strict` `--folder` `--json` |
+| `refresh` | Rebuild INDEX + each feature `## Tasks` table from task edges (**docs only**; no status change) | `--feature <id>` `--all` `--folder` `--json` |
+| `check [id]` | Validate one feature / the tree; the 4-layer gate; `--fix` repairs structural findings in place | `--strict` `--fix` `--folder` `--json` |
 | `sync [id]` | Align feature **lifecycle status** with linked task states (real transitions + guards) | `--all` `--dry-run` `--force` `--folder` `--json` |
 
 **`refresh` vs `sync` (do not conflate):**
@@ -157,6 +157,9 @@ the AC coverage map. Habits that keep it green:
   the files (files win). This is **not** `sync` — it does not change feature status.
 - **Scope `refresh` to one feature** with `--feature <id>` when only one feature's task links changed
   (INDEX.md is still regenerated for the whole tree): `spur feature refresh --feature H2`.
+- **The broad sweep is explicit** (task 0625 R5a): bare `spur feature refresh` refuses to sweep; pass
+  `--all` to rewrite every feature's `## Tasks` region. A bare sweep silently touched unrelated
+  features during the A3 run.
 
 ## Roadmap and priority habits
 
@@ -192,7 +195,7 @@ reopens. It computes a proposal (`from → to` with a `reason`) and, unless `--d
 via real lifecycle transitions (dogfood / one-active-goal / L4 gates may deny a hop).
 
 **Not for roster tables.** A stale `## Tasks` line (e.g. task still listed `todo` after it is `done`)
-is fixed with `spur feature refresh`, not `sync`. Use `sync --dry-run` first when you only want to
+is fixed with `spur feature refresh --feature <id>` (or explicit `--all`), not `sync`. Use `sync --dry-run` first when you only want to
 see the proposed status hop.
 
 ```bash
@@ -235,3 +238,8 @@ spur feature sync H2 --folder docs/custom-tasks --json   # non-default tasks fol
   *drive* planning; use this skill to *look up a verb* or *author AC*.
 - **`spur task` (see [tasks.md](tasks.md))** — the companion for `spur task` (WBS lifecycle, section editing, the
   readiness matrix).
+
+> **Shared option declarations (0618):** options shared across command modules resolve from
+> `apps/cli/src/commands/shared-options.ts` (`SHARED_OPTIONS`). Never re-declare a shared flag
+> inline in a command module — see SKILL.md "Shared option registry" and
+> `docs/04_DESIGN.md` §1.0.1.

package/plugins/sp/skills/spur-cli/references/message.md

@@ -107,3 +107,8 @@ lines.
 - **`spur agent` (see [agent.md](agent.md))** - `run --drain` and `loop` consume the inbox.
 - **`spur team` (see [team.md](team.md))** - team lifecycle that assigns agents to tasks.
 - **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.
+
+> **Shared option declarations (0618):** options shared across command modules resolve from
+> `apps/cli/src/commands/shared-options.ts` (`SHARED_OPTIONS`). Never re-declare a shared flag
+> inline in a command module — see SKILL.md "Shared option registry" and
+> `docs/04_DESIGN.md` §1.0.1.

package/plugins/sp/skills/spur-cli/references/rules.md

@@ -207,3 +207,8 @@ directly on the command line.
 
 **Template type**: technique
 **Purpose**: Operate `spur rule` across its full lifecycle as the deterministic constraint gate in LLM code delivery
+
+> **Shared option declarations (0618):** options shared across command modules resolve from
+> `apps/cli/src/commands/shared-options.ts` (`SHARED_OPTIONS`). Never re-declare a shared flag
+> inline in a command module — see SKILL.md "Shared option registry" and
+> `docs/04_DESIGN.md` §1.0.1.

package/plugins/sp/skills/spur-cli/references/self.md

@@ -0,0 +1,101 @@
+---
+name: spur-cli-self
+description: "spur-cli noun reference for `spur self`: self-management verbs — scaffold (`init`), schema migrations (`migrate`), local web server (`serve`), and status overview (`status`). Each verb mounts the same command builder as its legacy top-level noun, which remains a hidden alias over the identical command."
+see_also:
+  - spur-cli
+---
+
+# spur self - self-management verbs
+
+`spur self` hosts the four self-management verbs. Each verb is the canonical path for a command
+that also remains registered as a legacy top-level **hidden alias** (`spur init`, `spur migrate`,
+`spur serve`, `spur status`) so existing scripts, workflow YAML, and habits keep working unchanged.
+Both paths share the same command builder: identical flags, output, and exit codes. The legacy
+top-level forms are omitted from `spur --help`, leaving `self` as the visible surface.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `init` | Scaffold a new Spur project in the current directory | `--name <name>` `--force` `--minimal` `--json` |
+| `migrate` | Apply CLI-owned schema migrations | `--json` |
+| `serve` | Start the Spur web server (local fallback) | `--port <n>` `--host <addr>` `--no-open` `--cwd <path>` `--json` |
+| `status [path]` | Show project and git status for a Spur project | `--json` |
+
+**Deep detail lives in the verb-owner references** — **[init.md](init.md)** owns the `init` and
+`status` verbs (scaffold semantics + the Phase 1.5 / 1.6 post-scaffold validation probes),
+**[serve.md](serve.md)** owns the `serve` verb (server flags and dry-probe semantics). `migrate`
+has no reference of its own and is documented inline below.
+
+## `self init` - scaffold a Spur project
+
+```bash
+spur self init                        # interactive: prompt for project name
+spur self init --name my-project      # non-interactive
+spur self init --name my-project --force  # overwrite existing .spur/ files
+spur self init --minimal              # skip optional scaffolding (rules, workflows)
+spur self init --json                 # machine-readable
+```
+
+Materializes the `.spur/` directory tree with config, docs, rules, and workflow templates. Flags:
+`--name <name>` (default: current directory name), `--force` (recreate existing files), `--minimal`
+(skip optional scaffolding), `--json` (machine-readable output). Post-scaffold validation probes
+(Phase 1.5 / 1.6) run immediately after this verb completes — see **[init.md](init.md)** for the
+probe protocol and rule-glob adaptation procedure.
+
+## `self migrate` - apply CLI-owned schema migrations
+
+```bash
+spur self migrate                     # apply pending migrations
+spur self migrate --json              # machine-readable { ok, applied }
+```
+
+Temporary helper: applies CLI-owned schema migrations and reports `{ ok, applied }`. Only flag is
+`--json`.
+
+## `self serve` - start the local web server
+
+```bash
+spur self serve                       # default: localhost:3000, opens browser
+spur self serve --port 8080 --host 0.0.0.0
+spur self serve --no-open             # skip browser
+spur self serve --json                # dry probe: print { port, url, pid, running } and exit
+```
+
+Starts the Hono/Cloudflare-Worker server that serves the web Task Kanban and exposes the team
+supervisor API (`/api/team/*`). It is the local fallback when no remote server is configured.
+Flags: `--port <n>`, `--host <addr>`, `--no-open`, `--cwd <path>`, `--json` (a dry probe — reports
+the resolved port/url without starting the server). Full flag semantics: **[serve.md](serve.md)**.
+
+## `self status [path]` - project and git status
+
+```bash
+spur self status                      # current directory
+spur self status /path/to/project     # specific project
+spur self status --json               # machine-readable
+```
+
+Reports the project's Spur configuration state (init status, feature/task counts, rule preset
+health) and git working-tree status. Optional `[path]` argument targets a different project
+directory. Only flag is `--json`.
+
+## What this skill is NOT
+
+- **Not the team supervisor.** `self serve` hosts the supervisor API; `spur team start` / `stop` /
+  `status` are the verbs that drive it. See **[team.md](team.md)**.
+- **Not a production server.** This is the local fallback. Production deployment uses the Cloudflare
+  Worker build (`apps/server/`), not `self serve`.
+
+## See also
+
+- **[init.md](init.md)** - `init` / `status` verbs: scaffold semantics and the Phase 1.5 / 1.6
+  post-scaffold validation probes.
+- **[serve.md](serve.md)** - `serve` verb: server flags and the `--json` dry-probe contract.
+- **`spur team` (see [team.md](team.md))** - `start`/`stop`/`status` require `self serve` for the
+  supervisor API.
+- **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.
+
+> **Shared option declarations (0618):** options shared across command modules resolve from
+> `apps/cli/src/commands/shared-options.ts` (`SHARED_OPTIONS`). Never re-declare a shared flag
+> inline in a command module — see SKILL.md "Shared option registry" and
+> `docs/04_DESIGN.md` §1.0.1.

package/plugins/sp/skills/spur-cli/references/tasks.md

@@ -51,7 +51,7 @@ re-reading or re-tokenizing the task.
 | `batch-create` | Create many tasks from a validated JSON array | `--file <path>` `--folder` `--json` |
 | `record <wbs>` | Write `Testing` from a verify verdict (deterministic); bare-`## Review` fallback only; optional Solution + transition | `--verdict-file <path>` `--solution-from-diff` `--transition <status>` `--folder` `--json` |
 | `verdict <wbs>` | Derive PASS/PARTIAL/FAIL/UNKNOWN from verify answer text → verdict JSON; see [answer-file shape](tasks/verbs.md#answer-file-shape-what---from-answer-parses) | `--from-answer <path>` `--folder` `--json` |
-| `check [wbs]` | Four-layer validation; the readiness matrix | `--strict` `--as <status>` `--strict-core` `--folder` `--json` |
+| `check [wbs]` | Four-layer validation; the readiness matrix; `--fix` repairs structural findings in place | `--strict` `--as <status>` `--strict-core` `--fix` `--folder` `--json` |
 | `resolve <file-path>` | Map a file path to its owning task WBS | `--strict` `--folder` `--json` |
 | `path <wbs>` | Map a WBS to its absolute task file path (inverse of `resolve`) | `--folder` `--json` |
 | `run-link <wbs>` | Record pipeline run provenance link for task | `--source <src>` `--run-id <id>` `--json` |
@@ -310,3 +310,8 @@ spur task path 0040 --json
   execution loop. Use it to *drive* work; use this skill to *look up a verb*.
 - **`spur feature` (see [features.md](features.md))** — the companion for `spur feature` (hierarchical IDs, AC conventions,
   traceability).
+
+> **Shared option declarations (0618):** options shared across command modules resolve from
+> `apps/cli/src/commands/shared-options.ts` (`SHARED_OPTIONS`). Never re-declare a shared flag
+> inline in a command module — see SKILL.md "Shared option registry" and
+> `docs/04_DESIGN.md` §1.0.1.

package/plugins/sp/skills/spur-cli/references/team.md

@@ -138,3 +138,8 @@ process spawning. The started process runs `spur agent loop --agent <id>` under
 - **`spur message` (see [message.md](message.md))** - the durable inbox team members drain.
 - **`spur serve` (see [serve.md](serve.md))** - the local server `start`/`stop`/`status` require.
 - **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.
+
+> **Shared option declarations (0618):** options shared across command modules resolve from
+> `apps/cli/src/commands/shared-options.ts` (`SHARED_OPTIONS`). Never re-declare a shared flag
+> inline in a command module — see SKILL.md "Shared option registry" and
+> `docs/04_DESIGN.md` §1.0.1.