@gobing-ai/spur 0.3.55 → 0.3.57

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.md

@@ -28,7 +28,7 @@ what* or *how to write a scenario*, this skill.
 | `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` |
+| `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):**
@@ -235,3 +235,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.

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

@@ -199,10 +199,45 @@ spur workflow run ./workflows/approval.yaml --steer                # interactive
 - **`--steer`** is synchronous and in-process: it cannot combine with `--json` or `--async` (exit `2`).
   It accepts steering commands on stdin at declared action boundaries for interactive control.
 
+## Composition measures and the advisory (0615)
+
+`workflow validate` (valid path only) also reports a **warn-only composition advisory** covering the
+two detectable measures from ADR-069. It answers "does this workflow lean on ad-hoc shell or raw
+agent prompts where a first-class surface would own it better?" — nothing more.
+
+**The two triggers:**
+
+- **Shell measure** — a `shell` action (state hooks `onEnter`/`onExit`; guards are exempt) flags when
+  its `command` has **≥6** non-comment units (split on newline and `;`, blank/`#` units skipped).
+- **agent.run measure** — an `agent.run` action flags when its `input` is a **non-slash** prompt;
+  raw prompt length only sets the reported severity (<200 low / ≤1000 medium / >1000 high).
+
+**How to run it:** it is not a separate command — `spur workflow validate <file> --json` returns
+`composition: {findings[], suppressed}` on the valid path; human mode prints the advisory to stderr
+with exit 0. Actions with a recorded disposition in
+`config/workflow-composition-baseline.json` (resolved by walking up from the workflow file) are
+counted in `suppressed`, not `findings`.
+
+**How to read it, and the fix path per defect class:**
+
+- **Shell finding** → pick one of the five recorded owner options from
+  `docs/design/workflow-shell-ownership.md`: (a) public `spur` verb (consent-gated),
+  (b) application service, (c) least-privilege built-in action kind, (d) workflow-relative external
+  extension, (e) deliberately-stays-shell exception (record the reason in the baseline).
+- **agent.run finding** → move the operation behind a centralized agent skill or slash command and
+  make the action's `input` reference it (ADR-043 preference).
+
+**Advisory-only posture (binding):** findings never justify blocking a run, failing a gate, or
+editing a pipeline that is currently executing. The advisory never changes `validate`'s exit status,
+never blocks `workflow run`, and is not part of `spur-check` / `spur-check-new`. Treat a finding as
+a to-be-enhanced note for the workflow's owner — surface it in your report, apply the fix only when
+the operator accepts it, and never hot-edit a running workflow's shell in place.
+
 ## Command surface
 
 ```
 spur workflow validate <file> [--no-schema] [--json]
+spur workflow show      <file>
 spur workflow run      <file> [--run-id <id>] [--vars <json>] [--dry-run] [--async] [--no-plan] [--quiet/--silent/--verbose] [--detail <level>] [--trace-file] [--no-log] [--steer] [--json]
 spur workflow continue [run-id] [--yes] [--answer <yes|no|cancel>] [--json]
 spur workflow cancel   <run-id> [--json]
@@ -359,3 +394,8 @@ directly on the command line.
 
 **Template type**: technique
 **Purpose**: Operate `spur workflow` across its full lifecycle — choose the execution mode, author, validate, run, and refine dual-mode workflows
+
+> **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-dev/references/dev-operations.md

@@ -412,14 +412,15 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
 - **Behavior:** 0. **Start at the anchors, never at a discovery run.** If `--findings <anchors>` is given, that space-separated `file:line` list IS the failing set — open those locations first, in order, and fix them; do not run the gate to find out what broke. If only `--gate-log <path>` is given, read that log first and identify the failing findings (lint/test errors with their `file:line` anchors) before running the loop — the captured log is the authoritative source. Either way the first action of this hop is a read, not a gate run (R3, task 0482).
   1. Run `bun run format` (add `-- <path>` if `--scope` is given) to settle formatter-only diffs first — `bun run lint` asserts `--error-on-warnings` + typecheck but does **not** rewrite formatting, so a formatter-only change (e.g. a multi-line import reflow) can pass `lint` locally yet still be unformatted. Formatting before linting removes that class of false-green.
   2. Run `bun run lint` (add `-- <path>` if `--scope` is given). Collect all errors.
-  3. If lint is clean, skip to step 5.
-  4. **Lint fix loop:** for each error, diagnose the root cause and apply the smallest fix. **Use targeted probes to verify each fix** (`bunx tsc --noEmit` on the affected package, `bun run lint -- <file>`) — do NOT re-run the full gate after every batch. Loop until lint is green.
-  5. Run `bun run test`. Collect all failures.
-  6. If tests are green, done.
-  7. **Test fix loop:** for each failure, diagnose (test bug vs implementation bug), apply the fix, re-run the **failing test only** (`bun test <file> --test-name-pattern "<test>"`). Do NOT re-run the full suite per fix — it is the dominant loop cost (task 0436 R2).
-  8. **Confirming run (at most once).** After all fixes, run `bun run format && bun run lint && bun run test` **at most once** to confirm. If it passes, the hop is done.
-  9. **Pipeline-awareness (R4, task 0483).** When `/sp:dev-fixall` is invoked from the pipeline's `test-fix` hop, `test-recheck` runs the full `${vars.qualityGateCmd}` gate immediately after this hop returns — that is the **deciding** run that writes PASS to `.spur/run/<wbs>-test-gate.status`. Do NOT re-run the full gate beyond the single confirming run in step 8; the deciding run belongs to `test-recheck`. If your confirming run already passed, return immediately — a second or third gate run inside this hop is pure redundancy (0482 ran the gate 3× plus a standalone `bun run test`; all four were followed by `test-recheck` running it a 5th time). If your confirming run failed and you fixed more, re-run the full gate once more within `--max-retry` budget, then return — let `test-recheck` judge.
-  10. Report: list what was fixed (file + one-line summary per fix). If any error could not be resolved, report it explicitly — do not suppress.
+  3. **Surface-change sweep (before any fix).** If the failing set is a **surface/parity** change — CLI noun/verb/flag surface, reference-file structure, or a renamed/moved symbol — do one upfront `rg` sweep across ALL test dirs + docs for stale references to the changed symbols (e.g. `rg -l "<old-noun>|<old-file>.md|Tier C" apps/*/tests plugins/sp/tests plugins/sp/skills docs`), and fix every pinned test/docs file in that sweep. A surface change is pinned in **multiple independent test files** (each with its own hardcoded noun→reference map); discovering them one-by-one via full-suite probes is the dominant waste — each wave costs a suite run and a fresh edit loop (task 0436 R2 lesson). One sweep produces the complete edit set upfront.
+  4. If lint is clean, skip to step 6.
+  5. **Lint fix loop:** for each error, diagnose the root cause and apply the smallest fix. **Use targeted probes to verify each fix** (`bunx tsc --noEmit` on the affected package, `bun run lint -- <file>`) — do NOT re-run the full gate after every batch. Loop until lint is green.
+  6. Run `bun run test`. Collect all failures.
+  7. If tests are green, done.
+  8. **Test fix loop:** for each failure, diagnose (test bug vs implementation bug), apply the fix, re-run the **failing test only** (`bun test <file> --test-name-pattern "<test>"`). Do NOT re-run the full suite per fix — it is the dominant loop cost (task 0436 R2).
+  9. **Confirming run (at most once).** After all fixes, run `bun run format && bun run lint && bun run test` **at most once** to confirm. If it passes, the hop is done.
+  10. **Pipeline-awareness (R4, task 0483).** When `/sp:dev-fixall` is invoked from the pipeline's `test-fix` hop, `test-recheck` runs the full `${vars.qualityGateCmd}` gate immediately after this hop returns — that is the **deciding** run that writes PASS to `.spur/run/<wbs>-test-gate.status`. Do NOT re-run the full gate beyond the single confirming run in step 9; the deciding run belongs to `test-recheck`. If your confirming run already passed, return immediately — a second or third gate run inside this hop is pure redundancy (0482 ran the gate 3× plus a standalone `bun run test`; all four were followed by `test-recheck` running it a 5th time). If your confirming run failed and you fixed more, re-run the full gate once more within `--max-retry` budget, then return — let `test-recheck` judge.
+  11. Report: list what was fixed (file + one-line summary per fix). If any error could not be resolved, report it explicitly — do not suppress.
 - **Invariants:** Never bypass with `--no-verify`, `--force`, or new `biome-ignore`/`eslint-disable` suppressions. Never skip or `.skip` a test to make the suite green. Fix the root cause, not the symptom. Never claim green on `bun run lint` alone — a formatter-only diff passes `lint` but fails the formatter; run `bun run format` (or assert it produces no diff) before declaring the gate clean. **Never re-run the full gate more than once per confirming pass** (R4) — use targeted probes during the fix loops and let the pipeline's `test-recheck` state be the deciding run.
 - **MANDATORY Exit Condition.** The ONLY way to complete successfully:
   1. Run validation command: `eval "$VALIDATION_CMD"`

package/plugins/sp/skills/spur-dev/references/execution-batch.md

@@ -734,6 +734,25 @@ command doc so it does not read as a bug.
   `sp:super-planner` surfaces blockers/HITL only at the **batch boundary** (between task runs), not
   from inside a pipeline step.
 
+## Gate preflight (dogfood 2026-08-21, feature A3)
+
+The A3 batch burned multiple full `spur-check-new` runs (~2 min each) that failed only at the tail
+gates. The cheap rule gates fail fast when run first — the full-gate run is dominated by the ~65 s
+test suite, so a gate run that dies at `test-post-check` or `corpus-check` wasted most of its wall
+time. Before launching a full `spur-check-new`:
+
+1. **Run the two rule gates first** — `bun run test-pre-check` (43 rules: `no-console-output`,
+   `no-direct-process-spawn`, `cli-*`, `require-corresponding-test`) and `bun run test-post-check`
+   (`every-export-has-tsdoc`, `coverage-gate`). They catch boundary/TSDoc violations in seconds.
+2. **Promoted code must satisfy the boundary rules `scripts/` never enforced.** A command module
+   moving from `scripts/` into `apps/cli/src` must route output through the `CommandOutput` seam (no
+   `console.*`), spawn processes via `NodeProcessExecutor` (no `Bun.spawnSync`), get a
+   `runtime-boundaries` fs-io exemption for sync reads (mirrors `task.ts`), and a non-command helper
+   must not live in `apps/cli/src/commands/` (the noun scan treats every file there as a noun).
+3. **Doc/TSDoc edits shift `file:line` anchors** cited by other tasks — `corpus-check` surfaces them
+   as `L4.anchor-subject-mismatch`. Repoint the shifted citations (via `spur task update --section`)
+   in the same commit, and reconcile new/stale baseline entries before the gate run.
+
 ## AC traceability
 
 | AC | Where satisfied |

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -124,12 +124,34 @@ Transition guards are not advisory. Execute the declared guard exactly, in order
 resolved variables and artifacts. `--no-lifecycle` remains bookkeeping only; the YAML's task checks,
 verdict gate, record step, and done guard all remain authoritative.
 
-## Batch use
+## Record & done sequencing (dogfood 2026-08-21, feature A3)
 
-Sequential `/sp:dev-runall` with omit/`inline` runs this driver once per ready WBS, with a fresh run
-id and the same frozen/topologically ordered batch plan. Batch inspection, halt/keep-going policy,
-and reporting remain in `execution-batch.md`. Parallel mode cannot share one host session safely and
-therefore keeps the existing isolated subprocess/worktree path (trigger 4).
+Order matters for the `testing → done` hop. The A3 batch hit the same clobbering spiral on two
+tasks (0617, 0619) because the sections were hand-written **before** the verdict artifact existed:
+
+1. **Write the verdict artifact first.** `spur task record --solution-from-diff --transition testing`
+   reads `.spur/run/<wbs>-verdict.json` (default). With no artifact it emits a **UNKNOWN** verdict and
+   **overwrites** a hand-authored `## Testing` with an auto-generated "No requirements recorded" table,
+   plus replaces `## Solution` with a bare auto change-map. Creating the artifact first (PASS, with
+   requirement rows keyed by scenario title) makes `task record` the compliant path.
+   ```bash
+   # verdict artifact first (shape: {wbs, verdict, requirements:[{id,status,evidence}], checks:[], source})
+   # then the record hop; then re-write Testing/Solution if record's backfill is thinner than intended.
+   spur task update <wbs> wip --no-lifecycle
+   spur task record <wbs> --solution-from-diff --transition testing
+   ```
+   The engine now preserves an already-authored Testing when the verdict is UNKNOWN (task-service
+   `record` fallback-only, mirroring the Review 0593 precedent) — but the order above is still the
+   contract for the standard pipeline.
+2. **Done-probe before done.** Run the check projected to `done` (`spur task check <wbs> --as done`
+   via the `TaskCheckService` probe pattern) — it surfaces `L3.unchecked-checklist` (flip `- [ ]` → `- [x]`)
+   and `L3.required-section-placeholder` before the transition, not after.
+3. **Solution change-map anchor rule (L4.anchor-subject-mismatch).** A Solution change-map table must
+   list **one `file:line` per row**. A ·-joined paragraph makes every anchor's "subject" the other
+   anchors and trips the L4 subject check. Paths containing `_` (e.g. `docs/help/cmd_*.md`,
+   `spur-cli-matrix.md`) can **never** match their cited line — the snake_case filename token is
+   extracted as the subject and cannot appear in the line content — so drop those rows from the table
+   (prose still covers them).
 
 ## Failure contract