@gobing-ai/spur 0.3.66 → 0.3.68

package/plugins/sp/skills/session-review/SKILL.md

@@ -46,6 +46,9 @@ cross-agent windows, recurrence, trends, or quantitative performance forensics.
   name the confirmation needed.
 - State `not available` when compaction or missing output removed evidence. Never reconstruct it from
   memory or claim a verification that did not run.
+- Derive timing only from timestamps and tool-call records visible in the active session. Use
+  non-overlapping stages whose durations sum to elapsed time; render unavailable duration or call
+  counts as `n/a` instead of estimating them.
 
 ## Triage mode (`--triage`)
 
@@ -91,6 +94,19 @@ three buckets — never skip triage and start fixing from the raw findings list.
 
 State the overall result in one to three sentences, including partial or blocked scope.
 
+### Time breakdown
+
+Summarize elapsed time and, when supported by evidence, productive work, avoidable setup/recovery,
+and operator wait time. Then render non-overlapping stages:
+
+| Stage | Time | Tool calls | Assessment |
+| --- | ---: | ---: | --- |
+
+Format durations as `M:SS` below one hour and `H:MM:SS` at one hour or above (`1:44`, not `1m44s`;
+`0:33`, not `33s`). Include a `Total` row when elapsed time is available. Keep operator approval
+waits separate from execution bottlenecks. Use `n/a` for any value not supported by the active
+session evidence.
+
 ### Resolved issues
 
 | Issue | Root cause | Resolution | Evidence |

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`). |

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -96,9 +96,9 @@ surface is already resolved and name the trigger / `operator override`. A comman
 inside that subprocess boundary runs its backing skill in that process; it must not spawn another
 `spur agent run` for the same trigger. This prevents recursive dispatch.
 
-**Pipeline wrappers (`dev-run`, `dev-runall`)** — the orchestrator is a loop; its *stages* do the
+**Pipeline wrappers (`dev-run`, `dev-runall`, `dev-idea`, `dev-plan`)** — the orchestrator is a loop; its *stages* do the
 model-bearing work. Interactive omit/`inline` therefore uses the
-[inline pipeline driver](inline-pipeline-driver.md): it reads `task-pipeline.yaml`, executes each
+[inline pipeline driver](inline-pipeline-driver.md): it reads the selected pipeline YAML, executes each
 `agent.run` input through the backing skill in the host session, and preserves every shell action
 and guard. `auto` or a named executor is merged into per-task `vars.agent` and
 `vars.implementAgent`, and the workflow's `agent.run` steps run under that subprocess executor (see
@@ -122,9 +122,11 @@ leg for eligible stages. Operator
 confirmation actions, `pause: true`, and approve/taste/ask decisions stay host-owned. Each inline
 model stage appends `stage <id> executed inline in session <session-id>` to its run log; a
 subagent-dispatched stage appends `stage <id> executed via subagent <agent-id> (host session
-<session-id>)` instead. `dev-plan` remains a workflow subprocess, as do `dev-run`/`dev-runall` with
-`--agent auto` or a name, parallel batches, and every headless `spur workflow run` / `spur agent
-run`. `dev-run --mode implement` continues to run its single competency in-session under omitted
+<session-id>)` instead. `dev-idea` and `dev-plan` also drive `idea-pipeline.yaml` in the host session,
+with no native subagent unless the operator explicitly requests delegation. `--agent auto` or a
+name, parallel batches, and every headless `spur workflow run` / `spur agent run` use subprocesses;
+dev-command workflow subprocesses launch `--async` so cancellation owns a process group and only
+`killed: true` means a live run stopped. `dev-run --mode implement` continues to run its single competency in-session under omitted
 `--agent` or explicit `--agent inline` (identical values, 0687 R1).
 
 ### Executor precedence chain (R7)
@@ -143,7 +145,7 @@ resolved in this order; first match wins:
 `--agent auto` tier-resolves an executor (stage `model_policy` → `agent.default` → tier priority)
 **before** merging, so it enters the chain at step 1 already resolved to a concrete name.
 On a headless workflow surface, explicit `--agent inline` substitutes tier resolution with a warning
-(0687 R3) instead of rejecting — it resolves exactly like an omitted flag. Interactive task wrappers
+(0687 R3) instead of rejecting — it resolves exactly like an omitted flag. Interactive pipeline wrappers
 consume both inline resolutions identically (0508 eligibility as generalized by 0687 R2) before this
 chain and use the host driver. Omitting the flag on a headless surface forwards nothing, so the
 spawned step resolves to `agent.default` (step 2) or the YAML literal (step 3).
@@ -193,18 +195,17 @@ explicit process boundary and retain their existing resolution, output, timeout,
 contracts. The interactive task wrapper does not change the YAML or engine; it reads the YAML as
 SSOT and interprets the actions in-session before any workflow subprocess exists. It records inline
 provenance without fabricating an `AgentRunTracedResult`.
-`spur agent run` itself resolves omitted `--agent` to `agent.default`, rejects explicit `--agent
-inline` with the stable special error (a headless surface cannot host a session), and `--agent
-auto` tier-resolves — the unified `--agent` selector on the dev command surface does not change the
-CLI's resolution.
+`spur agent run` resolves omitted or explicit `inline` through tier substitution on its headless
+surface and emits one warning naming the concrete executor; `auto` tier-resolves without the inline
+warning. Interactive dev wrappers consume inline before this boundary, so they never spawn it.
 
 ### Inline trade-off
 
 Inline avoids process startup and preserves the host session's context and tools. Relative to
 subprocess dispatch it provides **no isolated workspace**, **no per-stage subprocess action
 record**, **no independent timeout or abort boundary**, and **no tier-selected executor**: the
-executor is the current coding agent. Interactive task pipelines retain a run log, run-link, and
-session provenance through the inline driver. If process isolation or an independently killable
+executor is the current coding agent. Interactive pipelines retain a run log and session provenance
+through the inline driver; task pipelines additionally record a task run-link. If process isolation or an independently killable
 stage is required, select the subprocess path (`--agent auto` or `--agent <name>`).
 
 ## Every write is CLI-gated
@@ -611,22 +612,30 @@ CLI-gated corpus artifact. The `wrapup-pipeline.yaml` `learning-capture` step wr
 ## Session Checkpoint Convention
 
 Long-running pipelines write resumable checkpoints to `.spur/memory/sessions/` so an interrupted
-run can be resumed. The convention is documented here; the actual checkpoint write/read actions
-in pipeline YAMLs are added in Phase 4 (task 0171).
+run can be resumed. The canonical frontmatter schema below is parsed by
+`packages/app/src/workflow/checkpoint-contract.ts` (task 0711): a checkpoint that does not match
+it is ignored by routing/cleanup (safe fallthrough) and never reclaimed.
 
-**Format:** Markdown file with YAML frontmatter:
+**Format:** Markdown file with YAML frontmatter (canonical field set, task 0711):
 
 ```yaml
 ---
+schema_version: 1
 session_id: "2026-07-01-0167"
 workflow: "task-pipeline"
 run_id: "wf_..."
 task_wbs: "0167"
 feature_id: "I"
 phase: "verify"
+status: "running"
 last_gate: "review-approved"
-timestamp: "2026-07-01T18:30:00Z"
+source_commit: "<full 40-hex HEAD at write time>"
+digest: "sha256:..."
+generated_at: "2026-07-01T18:30:00Z"
+updated_at: "2026-07-01T18:30:00Z"
 next_action: "run verification"
+artifacts:
+  - .spur/run/0167-verdict.json
 ---
 
 ## Session Notes
@@ -634,6 +643,17 @@ next_action: "run verification"
 <free-form markdown: what was done, what's pending, any blockers>
 ```
 
+Field semantics (enforced by `parseCheckpointMetadata` / `checkpointStaleness`):
+
+- `schema_version` must be `1`; any other value → ignored.
+- `status` is one of `running|pending|approved|done|failed|cancelled|skipped`. A terminal status
+  (`done|failed|cancelled|skipped`) marks the checkpoint terminal — never resumed, only cleaned
+  up once retention expires.
+- `source_commit` pins repository HEAD at write time; drift staleness is reported, not hidden.
+- `artifacts` lists referenced run files; a missing artifact makes the checkpoint stale.
+- Writers: write after every HITL gate decision, phase transition, and terminal state; overwrite
+  the same file on resume (`session_id` = `<date>-<wbs-or-feature>`).
+
 **Write checkpoints after:**
 
 - Every HITL gate decision (approved/rejected/deferred).
@@ -652,6 +672,10 @@ next_action: "run verification"
 - **Not CLI-gated.** Checkpoint files are written directly by the pipeline's checkpoint action
   (a `shell` step that writes to `.spur/memory/sessions/<session-id>.md`). They do not go through
   `spur task update`.
+- **Canonical schema.** The frontmatter above is the contract (task 0711 R1). Non-canonical or
+  malformed checkpoints are ignored by the router and kept (never silently deleted) by cleanup.
+- **Retention.** Terminal checkpoints older than `workflowLogRetentionDays` with no active run are
+  reclaimed by `spur workflow clean` (task 0711 R5–R8); non-terminal checkpoints are always kept.
 - **Not a validated corpus.** Checkpoints are working memory. They are overwritten when a session
   resumes and re-checkpoints. They are NOT authoritative task state — the task file is.
 - **One file per session.** The `session_id` is `<date>-<wbs-or-feature>`. A resumed session

package/plugins/sp/skills/spur-dev/references/dev-operations.md

@@ -74,7 +74,7 @@ each would be scope creep for one-liner procedures.
 | 4   | run        | `dev-run`           | `Skill()`         | `sp:spur-dev` (`run` / `implement`)                                                | `<wbs> [--mode <full\|implement>] [--agent <inline\|auto\|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]]`                                                                                              |
 | 5   | refine     | `dev-refine`        | `Skill()`         | `sp:spur-dev` (`refine`)                                                           | `<wbs> [--focus <mode>] [--description <text>] [--depth <standard\|ready>] [--agent <inline\|auto\|name>] [--auto] [--next]`                                                                           |
 | 5a  | refineall  | `dev-refineall`     | `Skill()`         | `sp:spur-dev` (`refineall`)                                                        | `--feature <id> \| --tasks <selector> [--focus <mode>] [--description <text>] [--depth <standard\|ready>] [--agent <inline\|auto\|name>] [--auto] [--keep-going] [--status <s>] [--json] [--worktree [<name>]]` |
-| 6   | plan       | `dev-plan`          | `Skill()`         | `sp:spur-dev` (`plan`)                                                             | `"<description>" [--feature <id>] [--parent <feature-id>] [--agent <inline\|auto\|name>] [--skip-design] [--auto] [--approve-taste]`                                                                   |
+| 6   | plan       | `dev-plan`          | `Skill()`         | inline driver (`idea-pipeline`) or async workflow                                  | `"<description>" [--feature <id>] [--parent <feature-id>] [--agent <inline\|auto\|name>] [--skip-design] [--auto] [--approve-taste]`                                                                   |
 | 7   | docs       | _(no thin wrapper)_ | `Skill()`         | `sp:doc-evolve`                                                                    | `"<change description>"`                                                                                                                                                                               |
 | 8   | changelog  | `dev-changelog`     | `inline`          | git log + conventional-commit grouping                                             | `[--since <ref>] [--until <ref>] [--version <ver>]`                                                                                                                                                    |
 | 9   | gitmsg     | `dev-gitmsg`        | `inline`          | bounded diff capture → concern grouping → conventional commit                      | `[--commit] [--squash] [--all] [--scope <path>]`                                                                                                                            |
@@ -85,7 +85,7 @@ each would be scope creep for one-liner procedures.
 | 13a | parallel   | `dev-parallel`      | `Skill()`         | `sp:parallel-execution`                                                            | `--tasks <selector> [--feature <id>] [--mode <fan-out\|review-panel\|investigation>] [--agent <inline\|auto\|name>] [--json]`                                                                          |
 | 14  | wrap       | `dev-wrap`          | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `<wbs> [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                                                                 |
 | 15  | wrapall    | `dev-wrapall`       | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `[--since <iso>] [--feature <id>] [--status <s>] [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                        |
-| 16  | idea       | `dev-idea`          | `Skill()`         | `spur workflow run` (idea-pipeline)                                                | `"<idea>" [--auto] [--skip-design] [--approve-taste] [--agent <inline\|auto\|name>]`                                                                                                                                                  |
+| 16  | idea       | `dev-idea`          | `Skill()`         | inline driver (`idea-pipeline`) or async workflow                                  | `"<idea>" [--auto] [--skip-design] [--approve-taste] [--agent <inline\|auto\|name>]`                                                                                                                                                  |
 
 ## Skill-backed operations
 
@@ -255,7 +255,7 @@ must not be changed without updating the backing skill.
 ### 6. plan
 
 - **Purpose:** Plan a feature from a description — intake → feature create → AC generation → feature check gate → decomposition → batch-create (with **Design by default**).
-- **Inputs:** `"<description>"` (required). `--feature <id>` links to an existing feature. `--parent <feature-id>` nests under a parent. The planning pipeline's `agent.run` stages always dispatch a subprocess; `--agent <inline|auto|name>` selector accepted — `inline` substitutes tier resolution with a warning on this headless surface (task 0687) (see [SSOT](cross-cutting.md#inline-default-execution-surface)). **Design package flags (unified with `/sp:dev-idea`):**
+- **Inputs:** `"<description>"` (required). `--feature <id>` links to an existing feature. `--parent <feature-id>` nests under a parent. Omitted/`inline` drives `idea-pipeline.yaml` in the host session; `auto` or a name launches the async workflow worker. **Design package flags (unified with `/sp:dev-idea`):**
   - **Default:** author task `design` on every batch item + feature satellite when the seam heuristic fires (**ties lean design**). There is **no** `--design` force flag.
   - `--skip-design` — skip feature satellite **and** omit task `design` fields (scaffold only; refine fills later). Sole design opt-out.
   - `--approve-taste` — with `--auto`, pre-clear design-approval taste pause when that gate is used (`design_approved=true`). Alias: `--design-approved`.
@@ -340,9 +340,9 @@ must not be changed without updating the backing skill.
   - `--skip-design` — design package off (system-design + task Design).
   - `--approve-taste` — with `--auto`, skip **all** remaining taste pauses this run (idea-eval + design-approval). Sets `idea_approved=true` and `design_approved=true`.
     Aliases (prefer `--approve-taste`): `--idea-approved` → `idea_approved`; `--design-approved` → `design_approved`. There is **no** `--design` force flag.
-- **Backing:** `spur workflow run idea-pipeline.yaml` — direct workflow invocation.
-- **Behavior:** Builds vars from the table above and invokes the idea pipeline. Flow: discovery → **idea-eval** (taste; reject → cancelled) → feature-create → ac-generate → feature-check → system-design (conditional) → design-approval (taste) → decompose → batch-create → handoff. STOPS at handoff — no task execution, no pipeline nesting.
-- **Delegation:** Direct `spur workflow run idea-pipeline.yaml` (command maps flags → vars, then `Bash`).
+- **Backing:** `idea-pipeline.yaml` through the inline driver for omitted/`inline`, or `spur workflow run idea-pipeline.yaml --async` for `auto`/name.
+- **Behavior:** Builds vars from the table above and drives the idea pipeline. Flow: discovery → **idea-eval** (taste; reject → cancelled) → feature-create → ac-generate → feature-check → system-design (conditional) → design-approval (taste) → decompose → batch-create → handoff. STOPS at handoff — no task execution, no pipeline nesting. Headless runs use one `trace --follow`; cancellation is reported stopped only when `workflow cancel --json` returns `killed: true`.
+- **Delegation:** Host-session inline driver by default; explicit executor selection uses the async workflow worker.
 - **Idea-evaluation gate:** After discovery, operator reviews `.spur/run/idea-eval-report.md` ([idea-evaluation.md](idea-evaluation.md)). Approve continues; reject/cancel → no feature. Under `--auto`, still pauses unless taste pre-cleared (`--approve-taste` / alias). Enhanced idea is a sidecar — `vars.idea` is not overwritten.
 - **Design package (`--skip-design` only):**