@gobing-ai/spur 0.3.65 → 0.3.67

package/config/workflows/history-anatomy.yaml

@@ -44,7 +44,6 @@
 #   spurBin   — PATH-independent spur invocation (overridden by CLI at run start)
 #   __runId   — run-scoped id for explicit artifact paths (allocated in start)
 #   stepTimeoutMs — agent.run budget for enrich/validate
-#   correctionCount — bounded correction loop counter file path bits (name resolved in correct)
 
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
@@ -73,7 +72,6 @@ vars:
   spurBin: "spur"
   __runId: ""
   stepTimeoutMs: "1800000"
-  correctionCount: "0"
   workflowFile: "config/workflows/history-anatomy.yaml"
   contractVersion: "1"
   reportDir: "docs/report"
@@ -231,8 +229,11 @@ states:
   - id: correct
     description: >
       A two-pass correction budget (0690). onEnter increments the counter; retry edges guard on
-      the run-scoped correction-count file < 2 (`vars.correctionCount` is the declared home; the
-      file is the live bound), and a failure after the second repair takes the -> failed edge. The
+      the run-scoped correction-count file
+      `.spur/run/$__runId-correction-count` < 2 (the live bound — the
+      former `vars.correctionCount` declared-but-unread var was removed,
+      0702 R3), and a failure after the second repair takes the -> failed
+      edge. The
       counter is shared by the structure-gate and validate FAIL edges, so a structure repair can
       still be followed by one validation-driven repair. The
       model half re-authors the candidate in place from the gate findings and validation notes —

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.65",
+    "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/commands/dev-review-session.md

@@ -1,22 +1,25 @@
 ---
-description: "Review the active coding-agent session immediately: summarize outcomes, distinguish resolved and open issues with evidence, and propose bounded improvements. Triggers: review this session, session wrap-up, immediate retrospective, what happened, what was resolved"
+description: "Review the active coding-agent session immediately: summarize outcomes, distinguish resolved and open issues with evidence, and propose bounded improvements. With --triage: apply pure-doc / one-to-two-line fixes inline, then file remaining findings as one new task. Triggers: review this session, session wrap-up, immediate retrospective, what happened, what was resolved, triage findings"
 role: reviewer
-argument-hint: "[<focus>]"
+argument-hint: "[<focus>] [--triage]"
 allowed-tools: ["Bash", "Read", "Grep", "Glob", "Skill"]
 ---
 
 # Dev Review Session
 
-Wraps the **sp:session-review** skill for a lightweight, report-only review of the active host
-session. It uses the current conversation plus read-only repository evidence, runs inline so the
-session context is preserved, and never launches a workflow, imports history, creates a task, or
-applies a remediation.
+Wraps the **sp:session-review** skill for a lightweight review of the active host session. By
+default it is report-only: current conversation plus read-only repository evidence, run inline so
+the session context is preserved — no workflow launch, history import, task creation, or
+remediation. With `--triage`, it first triages the findings, then applies direct fixes (pure
+documentation work and one-to-two-line fixes) inline and files everything remaining as exactly one
+new task for further fixing.
 
 ## Argument Flags
 
 | Flag | Description | Default |
 | --- | --- | --- |
 | `[<focus>]` | Optional question or operation to emphasize without excluding material session outcomes. | full active session |
+| `--triage` | After the report: bucket findings → apply pure-doc / 1–2-line fixes inline → create one task for the remainder. | off (report-only) |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
@@ -25,6 +28,8 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 ```
 /sp:dev-review-session
 /sp:dev-review-session "why the verification loop repeated"
+/sp:dev-review-session --triage
+/sp:dev-review-session "F95 findings" --triage
 ```
 
 ## Implementation

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.65",
+    "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/scripts/dogfood-testing/detect-pipeline-driving.mjs

@@ -7,9 +7,13 @@ var PIPELINE_TOKENS = [
   "--next",
   "dev-runall",
   "dev-wrapall",
+  "dev-refineall",
+  "dev-verifyall",
   "dev-run",
   "dev-wrap",
   "dev-idea",
+  "refineall",
+  "verifyall",
   "runall",
   "wrapall",
   "run",

package/plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts

@@ -51,9 +51,13 @@ const PIPELINE_TOKENS = [
     '--next',
     'dev-runall',
     'dev-wrapall',
+    'dev-refineall',
+    'dev-verifyall',
     'dev-run',
     'dev-wrap',
     'dev-idea',
+    'refineall',
+    'verifyall',
     'runall',
     'wrapall',
     'run',

package/plugins/sp/scripts/dogfood-testing/validate-report.mjs

@@ -18,7 +18,7 @@ function countLedgerDataRows(markdown) {
   const nextHeading = after.search(/^### /m);
   const body = nextHeading === -1 ? after : after.slice(0, nextHeading);
   const rows = body.split(`
-`).filter((line) => line.trim().startsWith("|")).filter((line) => !/^\|[\s:|-]+\|?\s*$/.test(line.trim())).filter((line) => !/^\|\s*drift:/.test(line.trim()));
+`).filter((line) => line.trim().startsWith("|")).filter((line) => !/^\|[\s:|-]+\|?\s*$/.test(line.trim())).filter((line) => !/^\|\s*`?drift:/.test(line.trim()));
   return Math.max(rows.length - 1, 0);
 }
 function declaredExecutedSteps(markdown) {

package/plugins/sp/scripts/dogfood-testing/validate-report.ts

@@ -37,8 +37,9 @@ function countLedgerDataRows(markdown: string): number | null {
         .filter((line) => line.trim().startsWith('|'))
         .filter((line) => !/^\|[\s:|-]+\|?\s*$/.test(line.trim()))
         // drift:external rows are documentary (task 0296) — included in the table but
-        // subtracted from the executed-step count, per the @1.2 cardinality contract.
-        .filter((line) => !/^\|\s*drift:/.test(line.trim()));
+        // subtracted from the executed-step count, per the @1.2 cardinality contract;
+        // the prescribed code-span form (`drift:external`) matches too (task 0701 R5b).
+        .filter((line) => !/^\|\s*`?drift:/.test(line.trim()));
     // Minus the header row; what remains are data rows.
     return Math.max(rows.length - 1, 0);
 }

package/plugins/sp/skills/dogfood-testing/SKILL.md

@@ -408,22 +408,22 @@ no fix applications and a clean tree at finalize needs no drift row.
 
 ### What drift is — and is not
 
-**Drift** = a tracked file changes that neither the driver nor the testee ledger row names.
-**Explained** set = files named in ledger `Fix Applied` cells (driver fixes) plus files the testee
-wrote that the driver recorded in the ledger (testee-attributed writes). Anything else in
-`git status --porcelain` that is new or modified since baseline is drift.
+**Drift** = a tracked file changes that neither the driver nor a testee ledger row names.
+**Explained** set = files named in ledger `Fix Applied` cells (driver fixes) plus testee writes the
+driver recorded in the ledger. Anything else new or modified in `git status --porcelain` since
+baseline is drift.
 
 ### On detecting drift
 
 - Append a **warning ledger row** tagged `drift:external` in the Step column: paths in `Fix Applied`,
-  `Outcome: drift`, `Basis: <fingerprint diff>`. Do NOT mark the step PASSED/FIXED on account of
-  drift; the row records the drift, it does not change a step's outcome.
+  `Outcome: drift`, `Basis: <fingerprint diff>`. Do NOT mark the step PASSED/FIXED because of
+  drift; the row records the drift, it does not change a step's outcome. Write the Step cell as
+  the code span `` `drift:external` `` — the validator drops it from the data-row count (0701 R5b).
 - Emit a **mandatory report finding** under §6 Findings — `P2 — workspace drift detected during
-  run; attribution to external writer` — naming the drifted paths and the snapshot delta. The report
-  explicitly states the run's evidence is degraded, not voided.
-- The driver **never** claims drifted files as its own or the testee's work. A fix ledger row's
-  `Fix Applied` cites only the file:line the driver changed; drift rows cite the drifted paths
-  separately.
+  run; attribution to external writer` — naming the drifted paths and the snapshot delta. The
+  report states the run's evidence is degraded, not voided.
+- The driver **never** claims drifted files as its own or the testee's work: a fix row's
+  `Fix Applied` cites only what the driver changed; drift rows cite drifted paths separately.
 
 ### Worktree advisory (mutating dogfoods)
 

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

@@ -1,8 +1,8 @@
 ---
 name: session-review
-description: "Review the active coding-agent session, distinguish resolved and open issues with evidence, and propose bounded improvements. Triggers: review this session, session wrap-up, immediate retrospective, what happened, what was resolved."
+description: "Review the active coding-agent session: separate resolved from open issues with evidence, propose bounded improvements. With --triage, apply pure-doc / 1–2-line fixes inline and file the rest as one task. Triggers: review this session, wrap-up, triage findings."
 license: Apache-2.0
-version: 1.0.0
+version: 1.1.0
 metadata:
   author: spur
   platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
@@ -31,6 +31,7 @@ cross-agent windows, recurrence, trends, or quantitative performance forensics.
 | Argument | Description | Default |
 | --- | --- | --- |
 | `[focus]` | Question or operation to emphasize. It changes ordering, not evidence collection. | full active session |
+| `--triage` | Opt into bounded remediation after the report: apply direct fixes (pure docs / one-to-two-line fixes) inline, then file all remaining actionable findings as exactly one new task via the CLI-gated corpus surface. | off (report-only) |
 
 ## Evidence boundary
 
@@ -46,6 +47,28 @@ cross-agent windows, recurrence, trends, or quantitative performance forensics.
 - State `not available` when compaction or missing output removed evidence. Never reconstruct it from
   memory or claim a verification that did not run.
 
+## Triage mode (`--triage`)
+
+Report-only stays the default. With `--triage`, run the same evidence pass, then remediate in
+three buckets — never skip triage and start fixing from the raw findings list.
+
+1. **Triage every finding into exactly one bucket:**
+   - **Direct fix** — pure documentation work, or a one-to-two-line fix with obvious, local,
+     low-risk scope. Read the root cause first; a "one-liner" that needs design or touches a
+     shared write path is not direct.
+   - **Task** — real, actionable, and not already owned by an existing task. Deferred
+     requirements recorded inside their own task files are pointers, not duplicates.
+   - **Note** — pre-existing, environmental, or ownerless observations; report only.
+2. **Apply direct fixes inline** — smallest surgical diff, project style, and re-verify each
+   with the targeted check (lint / test / the exact command that exhibited the issue).
+3. **Create exactly one task** for the Task bucket through the CLI-gated corpus surface
+   (`spur task create`, then `spur task update <wbs> --section <s> --from-file` per section).
+   One task, not one per finding: each finding keeps its evidence, a suggested fix direction,
+   and an AC where verifiable. Exclude what direct fixes already resolved — say so in the task
+   Background instead.
+4. **Report** — add a Triage section: applied fixes (path + one-line what + verification) and
+   the created task WBS. The Resolved/Open tables keep their evidence rules unchanged.
+
 ## Protocol
 
 1. **Resolve scope.** Review the active session from the operator's initiating request through the
@@ -86,6 +109,14 @@ session. Do not list ordinary implementation steps as issues.
 For each supported proposal, name its owner surface, expected impact, verification method, and
 reversibility. Proposals remain report-only: apply no change and create no task.
 
+### Triage (only when `--triage` was passed)
+
+| Applied fix / created task | Bucket | What + verification |
+| --- | --- | --- |
+
+One row per applied fix and one per created task (with its WBS). Omit the section entirely when
+`--triage` was not passed.
+
 ### Next actions
 
 List only actions needed to finish partial scope, confirm a hypothesis, or preserve a demonstrated
@@ -94,10 +125,12 @@ improvement. Use `None` when the session is complete and no follow-up is justifi
 ## Boundaries
 
 - Stay in the active host session. Do not delegate; a fresh context loses the evidence being reviewed.
-- Do not launch a workflow, import history, create or update corpus items, or edit files.
-- Do not append indexed-context memory.
-- Do not perform baseline comparison, recurrence classification, cache publication, or a twelve-section
-  forensic report; those belong to imported-history analysis.
+- Do not launch a workflow, import history, append indexed-context memory, perform baseline
+  comparison or recurrence classification, or emit a twelve-section forensic report; those belong
+  to imported-history analysis.
+- Report-only by default: do not create or update corpus items or edit files. The single exception
+  is `--triage` mode, which permits exactly two mutation classes — direct fixes from the triage
+  bucket, and the one triage task. Anything beyond that stays a proposal.
 - Do not turn a single low-impact observation into a new policy. Report it as a candidate until it
   recurs or demonstrates a high-impact contract violation.
 

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