@gobing-ai/spur 0.3.66 → 0.3.67

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.66",
+    "version": "0.3.67",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",

package/plugins/sp/agents/expert-spur.md

@@ -1,13 +1,13 @@
 ---
 name: expert-spur
 description: |
-  Use PROACTIVELY for "create tasks for this feature", "update all task statuses", "audit task traceability", "create a feature with acceptance criteria", "harden the rule catalog", "author a batch of workflows", or "expert-spur". Multi-step Spur CLI corpus work across any `spur` noun — task, feature, rule, workflow: batch creation, status sweeps, section-editing campaigns, traceability audits, rule catalog hardening, workflow authoring/refactoring. Use when corpus work spans many files or nouns and warrants its own context; for a single operation, run the `spur` CLI directly.
+  Use PROACTIVELY for "create tasks for this feature", "update all task statuses", "audit task traceability", "create a feature with acceptance criteria", "harden the rule catalog", "author a batch of workflows", or "expert-spur". Multi-step corpus work across `spur task`, `feature`, `rule`, and `workflow`: batch creation, status sweeps, section campaigns, traceability audits, rule hardening, and workflow authoring/refactoring. For one deterministic operation, run the CLI directly.
 
   <example>
-  Context: Batch task status update across a feature's tasks.
+  Context: Batch task status update across a feature.
   user: "Move all A1 tasks from backlog to wip."
-  assistant: "Delegating to sp:expert-spur — reads the spur-cli task reference, then runs spur task update for each."
-  <commentary>Multi-task batch work warrants context isolation.</commentary>
+  assistant: "Delegating to sp:expert-spur — loads the task reference, resolves the set, then applies and checks each transition."
+  <commentary>A multi-task sweep needs isolated sequencing and between-operation judgment.</commentary>
   </example>
 tools: [Read, Grep, Glob, Bash, Skill]
 model: inherit
@@ -17,113 +17,86 @@ skills: [sp:spur-cli]
 
 # Expert Spur
 
-A specialist wrapper that delegates ALL multi-step `spur` CLI corpus work — across **every noun**
-(task, feature, rule, workflow) — to the **sp:spur-cli** facade skill, in its own context window.
-Use it for heavy, multi-operation corpus work (batch updates, status sweeps, traceability audits,
-rule-catalog hardening, workflow refactors) that benefits from isolation; for a single operation,
-use the `spur` CLI directly or invoke `sp:spur-dev`.
+Thin specialist for multi-step Spur **corpus** work. The backend skill `sp:spur-cli` owns noun,
+verb, flag, output, and exit semantics; this agent selects its task/feature/rule/workflow reference,
+sequences operations, and evaluates each result before continuing.
 
 ## Role
 
-You are the **Spur corpus steward**. You operate the `spur` command surface across all four nouns —
-`spur task`, `spur feature`, `spur rule`, `spur workflow` — using their verbs end to end. The
-`sp:spur-cli` facade owns verb usage, per-noun conventions, and the check-before-write discipline;
-your job is to route to the right noun reference, sequence operations, and apply judgment between
-them.
-
-**Core principle:** Delegate to the `sp:spur-cli` facade for verb guidance and per-noun conventions.
-For the planning/execution lifecycle (intake → feature → decomposition → pipeline run), delegate to
-`sp:spur-dev` (the spine). Do NOT reimplement CLI logic or validation — the CLI owns it.
-
-Read `plugins/sp/skills/spur-cli/SKILL.md` (and the relevant `references/<noun>.md`) for the verb
-guide and conventions before acting.
-
-## When to use
-
-- **Batch operations** — create, update, or check many tasks/features in one sweep.
-- **Status sweeps** — move tasks/features between statuses across a feature, phase, or tree.
-- **Traceability audits** — verify every task links to a feature, every scenario maps to a task.
-- **Section-editing campaigns** — update the same section across multiple tasks.
-- **Rule-catalog work** — author, fine-tune, validate, or harden constraint rules across the catalog.
-- **Workflow work** — decide fit, author, validate, dry-run, tune, or refactor one or more workflows.
-  Read `sp:spur-cli` `references/workflows/workflow-fit-and-tuning.md` before authoring or
-  refactoring, and apply it in this order:
-  - **Fit first.** A process earns a `spur workflow` only when it replays, branches on a
-    machine-checkable predicate, **and** needs a durable per-run record. Fewer than three → recommend
-    a descriptive procedure or checklist and stop. Author the mode gate only after fit clears.
-  - **Simplicity is the budget, and it is measured.** `shell` commands at or under 5 non-comment
-    units, `agent.run` inputs referencing a slash command rather than carrying a raw prompt, guards
-    a single predicate. Over budget → pick a recorded owner from
-    `docs/design/workflow-shell-ownership.md`; never reformat to dodge the measure.
-  - **Latency and observability are authoring decisions.** Minimize `agent.run` node count first;
-    soft status-file probe over repeated probing; guards ordered cheapest-discriminating-first;
-    `iterationBound` from a latency budget; states named for outcomes; `failureStates` declared.
-  - **Refactor in a named direction** — promote (prose → workflow), demote (workflow → prose),
-    or optimize in place. Back an optimization with a before/after `spur workflow trace` pair,
-    never with a feel.
-  - Composition-advisory findings (`workflow validate --json` → `composition`) are advisory only;
-    never block a run or edit an executing pipeline over them.
-- **Corpus health checks** — run `check`/`validate` across a batch and report findings.
-
-For a single operation, use the `spur` CLI directly. For the planning/execution lifecycle, use
-`sp:spur-dev`.
-
-## Skill invocation
-
-Invoke `sp:spur-cli` for verb guidance and per-noun conventions:
-
-| Platform | Invocation |
-| ---------- | ----------- |
-| Claude Code | `Skill(skill="sp:spur-cli", args="<noun> <query>")` |
-| Other platforms | Invoke `sp:spur-cli` directly as a skill |
+You are the Spur corpus steward: a specialist sequencer over `skill: sp:spur-cli`, not a second
+implementation of the CLI or lifecycle spine.
+
+## Scope
+
+Use for:
+
+- Batch task or feature creation, mutation, status, section, refresh, and check campaigns.
+- Cross-corpus traceability or structural audits.
+- Rule catalog authoring, validation, execution, and hardening.
+- Workflow fit decisions, authoring/refactoring, validation, dry-runs, and trace comparison.
+
+Do not use for one CLI invocation. Do not use for planning→implementation→verification lifecycle
+or batch task execution; `sp:spur-dev` owns that orchestration. The backend skill covers the other
+CLI nouns for direct use, but they are not this corpus specialist's scope.
+
+## Process
+
+1. Load `plugins/sp/skills/spur-cli/SKILL.md` and the exact noun reference before invoking a verb.
+2. Resolve and freeze the target set. Report ambiguity instead of guessing identifiers or flags.
+3. Run the noun's read/check/validate path before mutation where available.
+4. Mutate only through `spur`; parse `--json` output when the verb advertises it.
+5. Inspect each result before the next dependent operation; stop on structural or validation failure.
+6. Run the scoped check/validate/refresh path after mutation. After task/feature batch writes, run
+   `spur task check --corpus --json` once.
+
+Workflow fit, mode selection, simplicity budgets, authoring, and tuning live in the workflow
+references under `plugins/sp/skills/spur-cli/references/workflows/`; load them rather than copying
+their runbook here.
 
 ## Rules
 
 ### Always
 
-- [ ] Delegate verb guidance to `sp:spur-cli`; use the `spur` CLI for all mutations.
-- [ ] Run the noun's `check`/`validate` verb before and after editing (e.g. `spur task check <wbs> --json`).
-- [ ] Run the corpus-wide sweep after batch edits: `spur task check --corpus --json` (fails on structural errors outside `config/corpus-baseline.json`).
-- [ ] Use `spur task update --section --from-file` for all task section edits.
-- [ ] Run the noun's scoped `refresh` after batch operations where one exists (`spur task refresh`, `spur feature refresh --feature <id>` or `--all`).
-- [ ] Run the workflow fit gate before authoring any new workflow, and recommend a descriptive procedure when it does not clear all three parts.
+- Use the source-local CLI when working in the Spur repository.
+- Use `spur task update --section --from-file` for task section writes.
+- Keep check-before/write/check-after evidence and the final scoped refresh result.
+- Preserve declaration order and currently executing runs when changing workflows.
 
 ### Never
 
-- [ ] Never edit corpus files directly — always through CLI verbs.
-- [ ] Never reimplement verb logic or validation — the CLI owns it.
-- [ ] Never drive the planning/execution lifecycle through this agent — use `sp:spur-dev`.
-- [ ] Never author a workflow whose every node is a raw-prompt `agent.run` — that is a descriptive procedure paying a process spawn per step.
+- Edit task or feature corpus files directly.
+- Invent a noun, verb, flag, JSON field, or exit code.
+- Reimplement CLI validation in prose or shell.
+- Never drive the planning/execution lifecycle; do not run application implementation or task
+  pipelines through this agent.
 
 ## Output Format
 
-Report using this template:
-
 ```markdown
 ## Spur Corpus Operations Report
 
-**Noun(s)**: [task | feature | rule | workflow]
-**Operation**: [create | update | audit | sweep | author] — [scope]
-**Confidence**: HIGH / MEDIUM / LOW
+**Noun(s):** task | feature | rule | workflow
+**Scope:** <resolved ids/files>
+**Confidence:** HIGH | MEDIUM | LOW
 
 ### Changes
-| ID/WBS | Action | Status |
-|--------|--------|--------|
-| 0042 | update wip | ✓ |
-
-### Gate Results
-- check/validate: [pass/fail per item]
-- refresh: [done]
-
-### Next Steps
-1. [Actionable step]
+| Target | Operation | Result |
+| --- | --- | --- |
+| 0042 | update wip | pass |
+
+### Gates
+- pre-check: <result>
+- post-check/validate: <result>
+- refresh/corpus sweep: <result or n/a>
 ```
 
 ## Platform Notes
 
-- **Claude Code:** native — `Bash` runs the `spur` CLI; `Skill()` invokes `sp:spur-cli`.
-- **Other platforms:** agents are optional wrappers. Invoke `sp:spur-cli` directly.
+- Claude Code: use `Skill(skill="sp:spur-cli", args="<noun> <query>")`, then Bash for `spur`.
+- Other platforms: invoke `sp:spur-cli` directly; the agent wrapper is optional.
 
 ## Dispatch surface
 
-When you dispatch corpus work to another agent, choose the execution surface per [dispatch-surface.md](../skills/parallel-execution/references/dispatch-surface.md) - native subagent by default, `spur agent run` only on a named trigger (state which one).
+If corpus work must be dispatched again, follow
+[dispatch-surface.md](../skills/parallel-execution/references/dispatch-surface.md): native subagent
+by default, `spur agent run` only on a named trigger.

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.66",
+    "version": "0.3.67",
     "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/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/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."
+description: "Reference and operate the complete `spur` CLI surface: task, feature, rule, workflow, builder, agent, message, team, self, history, and projects. Use for verb or flag lookup, machine-readable output and exit contracts, or CLI-gated corpus writes. Triggers: \"spur task\", \"spur history\", \"spur projects\", \"create a task\", \"task check\", and any Spur CLI convention. Not for planning or execution lifecycle orchestration (`sp:spur-dev`)."
 license: Apache-2.0
 metadata:
   author: spur
@@ -19,15 +19,17 @@ metadata:
     - message
     - team
     - self
+    - history
+    - projects
   openclaw:
     emoji: "🧰"
 ---
 
 # 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`, `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 /
+`spur-cli` is the single reference for operating the **`spur` command-line surface**. Each visible
+noun has one reference file that documents *what each verb is, how to use it well, its flags,
+machine-readable output, and material exit semantics*. 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
 CLI knows *what is valid*; the **spine** (`sp:spur-dev`) knows *how to drive the lifecycle*.
@@ -47,18 +49,20 @@ Pick the noun, read its reference. Each Tier A and Tier B reference owns that no
 | **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** | **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` |
+| **Tier B** | **history** | Import agent histories, aggregate forensic artifacts, render reports, and run the checkpoint-resumed daily pipeline | [references/history.md](references/history.md) |
+| **Tier B** | **projects** | Manage the local multi-project registry and start/stop project servers | [references/projects.md](references/projects.md) |
+| **Tier C** | **help** | Commander-generated help command; not a Spur noun | Generated `--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.
+**Execute-First Contract:** Load the noun reference first and execute Tier A or Tier B commands
+without calling `spur --help`. Use the source-local `spur <noun> [verb] --help` only for version
+skew, unlisted long-tail flags, or a parity assertion failure.
 
 ### Tier C exclusion reasons
 
-These nouns are intentionally undocumented - each has a concrete immaturity reason, not an oversight:
+The only exclusion is generated by Commander and is not a product noun:
 
 | Noun | Reason |
 | ------ | -------- |
-| `history` | `report` verb is a TODO stub (`spur history report` prints a marker); surface is still converging. |
-| `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. |
 
 Each noun's per-topic detail lives one level deeper under `references/<noun>/` (e.g.
@@ -74,6 +78,8 @@ Use this skill to:
   or run a workflow, from the command line.
 - **Author within a noun** — write a rule, author a workflow, write acceptance criteria — following
   the noun reference's conventions.
+- **Operate local analytics and project management** — import/analyze/report history or manage the
+  multi-project registry through their references.
 
 Do **not** use this skill for:
 
@@ -89,6 +95,22 @@ file** (`references/<noun>.md`), plus an optional `references/<noun>/` subdir fo
 detail, plus one row in the Noun-routing table above. Do not create a separate `spur-<noun>` skill —
 the whole point of this facade is that the CLI surface has a single, scalable home.
 
+## Source and machine-output contract
+
+The implementation authority is `apps/cli/src/index.ts` plus the noun registration module under
+`apps/cli/src/commands/`; application-service output types remain authoritative for payload fields.
+When a reference and the source-local CLI disagree, stop, cite the source symbol, and repair the
+reference in the same change. The live parity gate is
+`plugins/sp/tests/cli-surface-parity.test.ts`.
+
+Do not assume every verb supports JSON. When `<noun> <verb> --help` advertises `--json`, parse
+stdout as one JSON document (or one document per row for documented streams). When it also
+advertises `--json-envelope`, raw JSON remains the default; the opt-in shape is
+`{ ok: true, data }` / `{ ok: false, error }`, with paginated list metadata where applicable.
+`SPUR_JSON_ENVELOPE=1` enables the same seam unless an explicit flag overrides it. The guarded
+inventory and deliberate raw exceptions live in `docs/04_DESIGN.md` §4.1 and
+`apps/cli/tests/json-envelope-inventory.test.ts`; do not duplicate that inventory here.
+
 ## What this skill is NOT
 
 - **Not the spine.** Driving a task through `task-pipeline.yaml`, HITL surfacing, decomposition, and
@@ -126,20 +148,23 @@ and spreading it; full contract in `docs/04_DESIGN.md` §1.0.1.
 - **[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).
+- **[references/history.md](references/history.md)** - history import, forensic artifact analysis,
+  pure report rendering, and the daily pipeline.
+- **[references/projects.md](references/projects.md)** - local multi-project registry and server
+  lifecycle.
 - **`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` /
   `reviewer` / `planner`, one per tier). The facade's nouns/verbs serve those roles; the table is
   the role vocabulary, the operator config maps tiers to executors.
-- **`sp:expert-spur`** — the subagent that loads this facade for multi-step, multi-noun corpus work
-  in its own context window.
 
 ## Platform Notes
 
 ### Claude Code
 
-`spur` CLI via the Bash tool; every verb supports `--json` for machine consumption. Invoke this skill
-directly via `Skill(skill="sp:spur-cli", args="<noun> <verb> …")` to look up or operate a verb.
+Run the `spur` CLI via the Bash tool. Use `--json` only where the selected verb advertises it. Invoke
+this skill directly via `Skill(skill="sp:spur-cli", args="<noun> <verb> …")` to look up or operate
+a verb.
 
 ### Codex / OpenClaw / OpenCode / Antigravity
 

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

@@ -1,6 +1,6 @@
 ---
 name: spur-cli-agent
-description: "spur-cli noun reference: operate `spur agent` as the coding-agent execution surface - run prompts via detected or named agents, manage team agent specs, run the persistent self-draining loop, and check agent readiness. The concrete levers (--model, --agent) behind the dispatch-surface escalation rule."
+description: "spur-cli noun reference: operate `spur agent` as the coding-agent execution surface - run prompts, wait on pinned occupants, manage team agent specs, run the persistent self-draining loop, and check readiness."
 see_also:
   - spur-cli
 ---
@@ -9,7 +9,7 @@ see_also:
 
 `spur agent` is the CLI for **running and inspecting coding agents**. It wraps the agents the
 operator already has installed (Claude Code, Codex, omp, OpenCode, Antigravity, etc.) behind a
-uniform `run` / `loop` / `spec` surface, so the rest of the harness can dispatch work without
+uniform run, wait, loop, and spec-management surface, so the rest of the harness can dispatch work without
 hard-coding a specific agent.
 
 This is a **companion reference**, not an orchestrator. It documents *what each verb is and how to
@@ -30,8 +30,9 @@ that before using `run` for fan-out dispatch.
 | `edit <id>` | Open an agent spec in `$EDITOR`, or print its path | - |
 | `delete <id>` | Remove an agent spec | `--force` |
 
-All verbs accept `--json` for machine consumption. **Exit codes:** `0` success, `1` error, `2`
-invalid usage.
+`list`, `doctor`, `run`, `wait`, and `create` accept `--json` plus `--json-envelope`. `loop`, `edit`,
+and `delete` are human/process-control surfaces. **Exit codes:** `0` success, `1` failure, and `2`
+invalid usage; `run` can also propagate the invoked agent's non-zero result.
 
 ## `run` - execute a prompt via a coding agent
 
@@ -56,6 +57,7 @@ through a coding agent as an external process, producing a persisted run record
 | `--spec <id>` | Team agent spec id (occupant addressing, 0542 R1). Pairs with `--drain`; with `--spec` alone the run is addressed to the occupant without touching the inbox. A legacy `--agent <spec-id>` still works during the transition with a one-time warning (shim `agent-flag-spec-id`). |
 | `--drain` | Prepend pending inbox messages addressed to `--spec <id>` before the prompt. |
 | `--json` | Output machine-readable JSON where supported. |
+| `--json-envelope` | Wrap JSON using the facade's standard output contract. |
 
 `--json` adds a `resolved` block (`{ role?, tier?, executor?, agent, source }`) reporting the
 resolution decision — the role, its tier, and the executor that won for role routing; the pin for
@@ -125,6 +127,7 @@ exits 2 naming the accepted vocabulary. Resolution collapses onto the same ident
 
 | Flag | Purpose |
 | ------ | --------- |
+| `--role <name>` | Resolve a Layer-1 role or executor name to exactly one materialized instance; mutually exclusive with `[specId]`. |
 | `--run <runId>` | Pin a specific run id (default: the spec's latest run). |
 | `--until <state>` | Lifecycle state to wait for (repeatable OR): `idle` \| `working` \| `invoke-exit` \| `blocked`. Default `idle`. |
 | `--timeout <ms>` | Caller deadline. Undefined = no deadline (stall budget still applies). |

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

@@ -0,0 +1,69 @@
+---
+name: spur-cli-history
+description: "spur-cli noun reference: operate `spur history` to import coding-agent transcripts, aggregate versioned forensic artifacts, render an artifact without database access, or run the checkpoint-resumed daily pipeline."
+see_also:
+  - spur-cli
+---
+
+# spur history - local forensic analytics
+
+`spur history` is the local history data plane: import transcripts into SQLite, aggregate a
+versioned artifact, render that artifact, or run the daily composition. Command registration and
+CLI guards live in `apps/cli/src/commands/history.ts` (`registerHistoryCommand`); payload contracts
+live in `packages/app/src/services/history-service.ts` (`FanOutResult`, `DailyResult`,
+`HistoryService`, `runHistoryReport`) and `packages/domain/src/analytics/artifact.ts`
+(`HistoryArtifact`).
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `import` | Import one source or fan out across all supported sources | `--source <source>` `--file <path>` `--root <path>` `--mode <mode>` `--dry-run` `--source-timeout <ms>` `--json` |
+| `analyze` | Aggregate imported rows and write a versioned forensic artifact | `--since <iso>` `--until <iso>` `--source <source>` `--session <id>` `--run <runId>` `--task <wbs>` `--top <n>` `--out <path>` `--json` |
+| `report [path]` | Purely render an existing artifact; default to `latest.json` | `--mode <name>` `--task <wbs>` `--top <n>` `--json` |
+| `daily` | Run import-all → analyze → artifact → 90-day report pruning once | `--since <iso>` `--until <iso>` `--root <path>` `--source-timeout <ms>` `--mode <name>` `--json` |
+
+Every JSON-capable verb also advertises `--json-envelope`; use the facade's machine-output contract.
+
+## `import` - isolated fan-out
+
+```bash
+bun run apps/cli/src/index.ts history import --source all --dry-run --json
+bun run apps/cli/src/index.ts history import --source codex --mode incremental --json
+bun run apps/cli/src/index.ts history import --source codex --file session.jsonl --mode force-file --json
+```
+
+- `--source all` and a single source use the same per-source fan-out path. A failed/timed-out source
+  does not abort its siblings.
+- Modes are `incremental`, `full`, and `force-file`. `--file` with the default `all` source is a
+  usage error. `--file --mode full` requires `--dry-run`; use `force-file` for a real single-file
+  write.
+- JSON contains `entries`, `warnings`, `exitCode`, and CLI/importer `provenance`. For real-data
+  validation, invoke the source-local CLI and record that provenance; never trust a bare global
+  `spur` that may be stale.
+- Exit `0` when every source is clean/empty, `2` for a mixed failure or any degraded source, and `1`
+  when all sources fail. CLI usage guards also exit `1` on this noun.
+
+## `analyze` - artifact writer
+
+`analyze` performs SQL aggregation over imported history and writes a stable, versioned
+`HistoryArtifact`. Selectors combine with AND. `--top` bounds leaderboards, not totals. `--out`
+overrides the dated report path; otherwise the service writes under `.spur/reports/history/` and
+updates `latest.json`. Human mode renders a summary; `--json` emits the artifact.
+
+## `report` - pure artifact renderer
+
+`report` never opens the database. It reads an explicit artifact or the `latest.json` pointer,
+validates the schema version, optionally narrows the loaded artifact with `--task` / `--top`, and
+renders `default` or `forensics` mode. Unknown modes, invalid `--top`, missing/mismatched task
+dimensions, missing artifacts, and schema mismatches exit `1` instead of silently widening output.
+
+## `daily` - run-once composition
+
+`daily` runs incremental import-all, analyze, artifact write, and report-directory pruning in one
+process. `--since` / `--until` scope analysis only, not import. Checkpoints make a missed run resume
+without double-counting. The result carries `{ fanOut, artifact, pruned, coverage, reportPath? }`;
+its exit code is the fan-out exit code. `--mode` adds a rendered sidecar after analysis.
+
+For the full artifact and data-plane contracts, use `docs/04_DESIGN.md` history sections and
+`docs/design/history-data-processing.md`; do not infer fields from rendered prose.

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

@@ -24,8 +24,8 @@ use it well*.
 | `reply <msg-id> <body>` | Thread a reply to a message | `--json` |
 | `watch` | Follow an agent inbox - surface new messages as they arrive | `--agent <id>` `--interval <ms>` `--json` |
 
-All verbs accept `--json` for machine consumption. **Exit codes:** `0` success, `1` error, `2`
-invalid usage.
+All verbs accept `--json` and `--json-envelope`. `watch` applies the envelope per emitted row.
+**Exit codes:** `0` success, `1` error, `2` invalid usage.
 
 ## `send` - enqueue a message
 

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

@@ -0,0 +1,59 @@
+---
+name: spur-cli-projects
+description: "spur-cli noun reference: operate `spur projects` to register local project roots, inspect live status, start detached project servers, and stop or remove registry entries."
+see_also:
+  - spur-cli
+---
+
+# spur projects - local multi-project registry
+
+`spur projects` manages the machine-local registry resolved by
+`packages/config/src/projects.ts` (`getProjectsFilePath`) and implemented by
+`packages/app/src/services/project-registry.ts` (`ProjectRegistry`). Server startup is owned by
+`packages/app/src/services/project-start.ts` (`startRegisteredProject`); CLI registration and JSON
+shapes live in `apps/cli/src/commands/projects.ts`.
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `add <path>` | Upsert an existing path in the registry | `--name <name>` `--json` |
+| `remove <target>` | Remove an entry by display name or path | `--json` |
+| `list` | List entries with live running status | `--json` |
+| `start <target>` | Start or reuse a detached project server | `--port <n>` `--json` |
+| `stop <target>` | Best-effort stop the listener and clear its recorded port | `--json` |
+
+Every verb also advertises `--json-envelope`; use the facade's machine-output contract. Success is
+exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
+
+## Registry behavior
+
+- The default file is `~/.config/spur/projects.json`; `SPUR_PROJECTS_FILE` overrides it. Entries are
+  `{ name, path, port }`, where `port: 0` means stopped.
+- Paths are normalized (including `~`) and existing paths resolve to real paths. Name lookup is
+  case-insensitive. Registry mutations use an advisory lock.
+- `add` requires an existing path, resolves a relative path from the current working directory, and
+  defaults the display name to its basename. It upserts; it does not start a server. The current
+  source does not enforce a `.spur/` marker or directory type.
+- `list` probes recorded ports and heals stale entries to `port: 0` before reporting `running`.
+
+## Server lifecycle
+
+```bash
+spur projects start my-project --json
+spur projects start /path/to/unregistered/project --port 3333 --json
+spur projects stop my-project --json
+```
+
+`start` resolves by name or path. An existing unregistered path is auto-registered. A live recorded
+port is returned idempotently; otherwise the service allocates a port (3000–3999 unless explicitly
+set), spawns `spur serve --host 127.0.0.1 --no-open` detached in the project root, waits for the port,
+then persists it.
+
+`stop` finds processes bound to the recorded port, sends `SIGTERM` best-effort while excluding the
+CLI and its parent, and clears the registry port. It is not a persistent supervisor contract.
+`remove` only removes the registry entry; stop a running project first when process cleanup matters.
+
+Raw JSON success payloads are verb-specific (`project`, `projects`, `removed`, `stopped`, or start
+status fields). Under `--json-envelope` they move beneath `data`; failures normalize beneath
+`error`. Read `apps/cli/src/commands/projects.ts` for exact fields.

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

@@ -223,6 +223,18 @@ the active tasks folder (or `--folder`).
 | `--folder <path>` | Custom tasks folder. |
 | `--json` | Machine-readable report envelope. |
 
+## `migrate-anchors`
+
+Qualify ambiguous in-repo evidence anchors to repo-relative paths across the task corpus. Run
+`--dry-run` first: unambiguous matches are reported in `qualified`, multiple matches in `ambiguous`
+without rewriting, and schema-incompatible files in `skipped`. The write path uses the planning
+service rather than raw file edits.
+
+```bash
+spur task migrate-anchors --dry-run --json
+spur task migrate-anchors --json
+```
+
 ## `resolve <file-path>`
 
 Map a file path to its **owning task** — returns the WBS + task file. Strategies, in order: direct
@@ -329,6 +341,19 @@ A free-form prose answer (no tables, or tables missing the required headers) yie
 the artifact source and directs the operator to `/sp:dev-verify <wbs>`. Re-run verify with the
 table format above.
 
+## `verifyall-aggregate`
+
+Read a JSON array of `{wbs,outcome[,reason]}` rows from `--from-file` (default
+`.spur/run/verifyall-batch-input.json`) and derive one deterministic batch verdict. Valid outcomes
+are `PASS`, `PARTIAL`, `FAIL`, `NOT-STARTED`, and `UNKNOWN`; `NOT-STARTED` rows are reported but
+excluded from rollup. Exit `1` when the aggregate verdict is `FAIL` or the input is invalid.
+
+## `scaffold-tests <wbs>`
+
+Generate BDD stubs from the task's Acceptance Criteria. `--file <path>` overrides the target test
+file; `--folder <path>` overrides task lookup. JSON reports the target plus created, skipped,
+drifted, and warning results.
+
 ## `refresh-roster <wbs>`
 
 Regenerate a parent task's sub-task roster block in `## Plan` — the marker-delimited table that the
@@ -367,12 +392,15 @@ spur task sections <wbs> <init|add|list> [name] [--folder] [--json]
 spur task list     [--status <s>] [--phase <p>] [--parent <wbs>] [--feature <id>] [--folder] [--json]
 spur task refresh  [--folder] [--json]
 spur task migrate  [--dry-run] [--folder] [--json]
+spur task migrate-anchors [--dry-run] [--json]
 spur task refresh-roster <wbs> [--folder] [--json]
 spur task batch-create --file <path> [--folder] [--json]
 spur task record   <wbs> [--verdict-file <p>] [--solution-from-diff] [--transition <s>] [--folder] [--json]
 spur task verdict  <wbs> [--from-answer <p>] [--folder] [--json]
+spur task verifyall-aggregate [--from-file <path>] [--json]
 spur task check    [wbs] [--strict] [--as <status>] [--strict-core] [--folder] [--json]
 spur task resolve  <file-path> [--strict] [--folder] [--json]
 spur task path     <wbs> [--folder] [--json]
 spur task run-link <wbs> [--source <src>] [--run-id <id>] [--json]
+spur task scaffold-tests <wbs> [--file <path>] [--folder] [--json]
 ```

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

@@ -26,7 +26,7 @@ use it well*.
 | `start <agent-id>` | Start a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
 | `stop <agent-id>` | Stop a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
 
-All verbs accept `--json` for machine consumption. `--server <url>` (default:
+All verbs except the text-only `assign` accept `--json` and `--json-envelope`. `--server <url>` (default:
 `http://localhost:3000/api`) targets the supervisor API started by `spur serve`. **Exit codes:** `0`
 success, `1` error, `2` invalid usage.
 

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

@@ -264,6 +264,12 @@ spur workflow list     [--json]
 spur workflow trace    [run-id] [--workflow <name>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output] [--json]
 ```
 
+### `show` - project a definition
+
+`spur workflow show <file>` renders the declared graph as Mermaid. `--format todo` instead emits a
+declared-step checklist; `--json` serializes the selected projection. This verb intentionally does
+not advertise `--json-envelope` because its JSON projection is a kept-raw document surface.
+
 | Flag (on `run`) | Effect |
 | --------------- | ------ |
 | `--vars <json>` | Per-run variable overrides (JSON object). Merged over the workflow's `vars`. Values must be strings. User vars win over injected defaults (`spurBin`). |