@gobing-ai/spur 0.3.67 → 0.3.68

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

@@ -16,7 +16,7 @@ Wraps the **sp:spur-dev** skill.
 | `"<description>"` | Feature description to plan. | required |
 | `--feature` `<id>` | Attach to an existing feature. | omitted |
 | `--parent` `<feature-id>` | Create under a parent feature. | omitted |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing planning. The planning pipeline's `agent.run` stages are headless — they always dispatch a subprocess. `inline` — also what omission resolves to since task 0687 — substitutes tier resolution there with one warning naming the resolved executor; `auto` (tier-resolves an executor); a name (pins that executor). | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing planning. Omission and `inline` drive `idea-pipeline.yaml` in this session with zero external agent/workflow processes; `auto` tier-resolves an executor and a name pins one, both through the async workflow worker. | inline |
 | `--skip-design` | Omit the system-design hop. | off |
 | `--auto` | Skip objective HITL gates. | off |
 | `--approve-taste` | With --auto: skip design-approval pause. | off |
@@ -43,5 +43,7 @@ for taste gates). Alias: `--design-approved` (prefer `--approve-taste`).
 ## Implementation
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Omitted/`inline`: drive `idea-pipeline.yaml` through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md). Do not launch `spur workflow run`, `spur agent run`, or a native subagent unless the operator explicitly requests delegation.
+- `auto`/name: launch `spur workflow run idea-pipeline.yaml --async`, observe with one `workflow trace --follow`, and only report cancellation as stopped when `workflow cancel --json` returns `killed: true`.
 - `Skill(skill="sp:spur-dev", args="plan $ARGUMENTS")`
 - Full Design package + batch `design` field contract: `plugins/sp/skills/spur-dev/references/dev-operations.md` § plan and `planning-workflow.md` Step 5.5.

package/plugins/sp/commands/dev-review-session.md

@@ -12,7 +12,8 @@ default it is report-only: current conversation plus read-only repository eviden
 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.
+new task for further fixing. The result includes a non-overlapping time breakdown with durations in
+`M:SS` or `H:MM:SS` form and `n/a` for unavailable measurements.
 
 ## Argument Flags
 

package/plugins/sp/hooks/context-post-tool.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+
 /**
  * context-post-tool — PostToolUse hook for indexed-context
  * (matcher: Bash|Grep|Glob|Read|Write|Edit — task 0248).
@@ -19,8 +20,9 @@
  * `superskill hook run sp context-post-tool`.
  */
 
-import { appendFileSync, existsSync, readFileSync, statSync } from 'node:fs';
-import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
 
 /** Tools recorded by this hook (must match hooks.json PostToolUse matcher). */
 export const ALLOWED_TOOLS = new Set(['Bash', 'Grep', 'Glob', 'Read', 'Write', 'Edit']);
@@ -282,6 +284,15 @@ export function recordToolUseEvent(
     const session = sessionMeta.session ?? '';
     if (!session) return null;
 
+    // Freshness stamp (task 0711 R4): the indexed-context producer is the agent
+    // following the skill's update guidance; the observable producer moment in
+    // code is a Write/Edit landing on a `.spur/context/*.md` file. Each such
+    // write refreshes `.freshness.json` so staleness checks can compare the
+    // sidecar's source commit against HEAD until the next regeneration.
+    if ((toolName === 'Write' || toolName === 'Edit') && isContextIndexFile(contextDir, filePath)) {
+        stampContextFreshness(contextDir, currentHeadCommit(), now());
+    }
+
     const tokens = resolveTokenEstimate(toolName, payload.tool_input, payload.tool_response);
     const ts = now().toISOString();
     const type = mapToolType(toolName);
@@ -309,6 +320,94 @@ export function recordToolUseEvent(
     return event;
 }
 
+// ─── Context freshness sidecar (task 0711 R4) ───────────────────────────
+
+export interface ContextFreshness {
+    schema_version: number;
+    source_commit: string;
+    generated_at: string;
+}
+
+export const CONTEXT_FRESHNESS_SCHEMA_VERSION = 1;
+
+/** True when `filePath` is a regenerated context index inside `contextDir` (not the sidecars). */
+export function isContextIndexFile(contextDir: string, filePath: string): boolean {
+    const resolvedDir = resolve(contextDir);
+    const resolvedFile = resolve(filePath);
+    if (!resolvedFile.startsWith(resolvedDir + sep)) return false;
+    const name = resolvedFile.slice(resolvedDir.length + 1);
+    return name.endsWith('.md');
+}
+
+/** Current HEAD, best-effort — null when git is unavailable or the dir is not a work tree. */
+export function currentHeadCommit(): string | null {
+    try {
+        const out = execSync('git rev-parse HEAD', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const commit = out.trim();
+        return commit.length > 0 ? commit : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Write/refresh `.spur/context/.freshness.json`. Best-effort: any I/O failure
+ * leaves the previous sidecar (or none) in place — the hook contract is
+ * fail-open, never blocking.
+ */
+export function stampContextFreshness(contextDir: string, sourceCommit: string | null, at: Date): void {
+    if (!sourceCommit) return;
+    const body: ContextFreshness = {
+        schema_version: CONTEXT_FRESHNESS_SCHEMA_VERSION,
+        source_commit: sourceCommit,
+        generated_at: at.toISOString(),
+    };
+    try {
+        writeFileSync(join(contextDir, '.freshness.json'), JSON.stringify(body));
+    } catch {
+        /* fail-open */
+    }
+}
+
+export interface ContextFreshnessCheck {
+    stale: boolean;
+    reason?: string;
+}
+
+/**
+ * Compare a freshness sidecar against the current HEAD (task 0711 R4). A
+ * missing/unparsable sidecar is stale (`never stamped`); a commit mismatch is
+ * stale until the producer regenerates the index.
+ */
+export function checkContextFreshness(raw: string | null, headCommit: string | null): ContextFreshnessCheck {
+    if (raw === null) return { stale: true, reason: 'never stamped' };
+    let body: ContextFreshness;
+    try {
+        body = JSON.parse(raw) as ContextFreshness;
+    } catch {
+        return { stale: true, reason: 'malformed sidecar' };
+    }
+    if (body.schema_version !== CONTEXT_FRESHNESS_SCHEMA_VERSION) {
+        return { stale: true, reason: `schema_version ${String(body.schema_version)}` };
+    }
+    if (typeof body.source_commit !== 'string' || body.source_commit === '') {
+        return { stale: true, reason: 'missing source_commit' };
+    }
+    if (headCommit !== null && body.source_commit !== headCommit) {
+        return { stale: true, reason: 'source commit changed since generation' };
+    }
+    return { stale: false };
+}
+
+/** Read the freshness sidecar, or null when absent/unreadable. */
+export function readContextFreshness(contextDir: string): string | null {
+    try {
+        return readFileSync(join(contextDir, '.freshness.json'), 'utf-8');
+    } catch {
+        return null;
+    }
+}
+
 // Entrypoint — thin wrapper; logic lives in {@link recordToolUseEvent} for unit coverage.
 if (import.meta.main) {
     void (async () => {

package/plugins/sp/hooks/context-session-start.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+
 /**
  * context-session-start — SessionStart hook for indexed-context.
  *
@@ -11,10 +12,11 @@
  * Self-contained by design (task 0232/0246).
  */
 
+import { execSync } from 'node:child_process';
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-
 import { resolveAgentHint, resolveModelHint } from './agent-hint';
+import { checkContextFreshness } from './context-post-tool';
 
 export { resolveAgentHint, resolveModelHint } from './agent-hint';
 
@@ -161,6 +163,25 @@ export function recordSessionStart(
     if (agent) startEvent.agent = agent;
     if (model) startEvent.model = model;
 
+    // Freshness check (task 0711 R4): report whether the context indexes were
+    // regenerated at the current HEAD. Best-effort, fail-open — git failures
+    // yield head=null, which marks stale only via the sidecar's own defects.
+    let headCommit: string | null = null;
+    try {
+        const out = execSync('git rev-parse HEAD', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const trimmed = out.trim();
+        headCommit = trimmed.length > 0 ? trimmed : null;
+    } catch {
+        headCommit = null;
+    }
+    let freshnessRaw: string | null = null;
+    try {
+        freshnessRaw = readFileSync(join(dir, '.freshness.json'), 'utf-8');
+    } catch {
+        freshnessRaw = null;
+    }
+    startEvent.contextFreshness = checkContextFreshness(freshnessRaw, headCommit);
+
     const ledgerPath = join(dir, 'token-ledger.jsonl');
     try {
         appendFileSync(ledgerPath, `${JSON.stringify(startEvent)}\n`);

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.67",
+    "version": "0.3.68",
     "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/stage-registry-adapter.ts

@@ -24,7 +24,8 @@
  *   bun plugins/sp/scripts/stage-registry-adapter.ts --help
  */
 
-import { readFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 // ─── Inline type definitions (mirrors packages/domain/src/stage-registry/) ─
@@ -203,6 +204,107 @@ export interface TaskSignal {
     feature_id?: string | null;
     hasCheckpoint?: boolean;
 }
+
+/**
+ * Result of routing-checkpoint inspection (task 0711 R3).
+ *
+ * `usable` feeds `TaskSignal.hasCheckpoint`: only a checkpoint that parses as
+ * the canonical frontmatter contract, matches the task (owner identity), is
+ * non-terminal, and is not commit-drifted may route A4 (wip + checkpoint →
+ * continue). Anything else is reported with its reason and IGNORED — routing
+ * falls through to the non-checkpoint row (A5); it is never silently trusted.
+ *
+ * Lean inline mirror of `packages/app/src/workflow/checkpoint-contract.ts`
+ * (the plugin installs into foreign repos and cannot import workspace
+ * packages — same discipline as the domain-type mirrors above); the parity
+ * test pins the two together.
+ */
+export interface RoutingCheckpointInspection {
+    usable: boolean;
+    reason?: string;
+}
+
+export interface RoutingCheckpointOptions {
+    /** Current repository HEAD; when provided, a mismatched/absent `source_commit` is drift. */
+    headCommit?: string;
+    /** Existence probe for referenced artifacts; default `existsSync`. */
+    artifactExists?: (path: string) => boolean;
+}
+
+/**
+ * Inspect `.spur/memory/sessions/<wbs>-checkpoint.md` for resume routing
+ * (task 0711 R3). A missing file yields `{ usable: false, reason: 'absent' }`
+ * — the normal case, indistinguishable for routing from a rejected one.
+ */
+export function inspectRoutingCheckpoint(
+    sessionsDir: string,
+    wbs: string,
+    opts: RoutingCheckpointOptions = {},
+): RoutingCheckpointInspection {
+    let raw: string;
+    try {
+        raw = readFileSync(join(sessionsDir, `${wbs}-checkpoint.md`), 'utf-8');
+    } catch {
+        return { usable: false, reason: 'absent' };
+    }
+    if (!raw.startsWith('---')) return { usable: false, reason: 'malformed: missing frontmatter' };
+    const end = raw.indexOf('\n---', 3);
+    if (end < 0) return { usable: false, reason: 'malformed: unterminated frontmatter' };
+
+    const scalars = new Map<string, string>();
+    const artifacts: string[] = [];
+    let inArtifacts = false;
+    for (const rawLine of raw.slice(4, end).split('\n')) {
+        const line = rawLine.trim();
+        if (line.startsWith('- ')) {
+            if (inArtifacts) artifacts.push(line.slice(2).trim().replace(/^"|"$/g, ''));
+            continue;
+        }
+        inArtifacts = false;
+        const sep = line.indexOf(':');
+        if (sep <= 0) continue;
+        const key = line.slice(0, sep).trim();
+        const value = line
+            .slice(sep + 1)
+            .trim()
+            .replace(/^"|"$/g, '');
+        if (key === 'artifacts') {
+            inArtifacts = true;
+            if (value !== '') {
+                artifacts.push(
+                    ...value
+                        .split(',')
+                        .map((p) => p.trim().replace(/^"|"$/g, ''))
+                        .filter((p) => p !== ''),
+                );
+            }
+            continue;
+        }
+        scalars.set(key, value);
+    }
+
+    if (scalars.get('schema_version') !== '1') return { usable: false, reason: 'malformed: schema_version' };
+    if (scalars.get('task_wbs') !== wbs) {
+        return { usable: false, reason: `owner-mismatch: task_wbs=${scalars.get('task_wbs')} != ${wbs}` };
+    }
+    const status = scalars.get('status') ?? '';
+    if (['done', 'failed', 'cancelled', 'skipped'].includes(status)) {
+        return { usable: false, reason: `terminal: status=${status}` };
+    }
+    const head = opts.headCommit;
+    if (head !== undefined) {
+        const commit = scalars.get('source_commit') ?? '';
+        if (commit === '' || commit !== head) {
+            return { usable: false, reason: `commit-drift: checkpoint@${commit.slice(0, 12) || 'none'} != HEAD` };
+        }
+    }
+    const probe = opts.artifactExists ?? existsSync;
+    for (const artifact of artifacts) {
+        const p = artifact.trim().replace(/^"|"$/g, '');
+        if (p !== '' && !probe(p)) return { usable: false, reason: `missing-artifact: ${p}` };
+    }
+    return { usable: true };
+}
 export interface FeatureSignal {
     id: string;
     status: FeatureStatus;
@@ -894,6 +996,8 @@ const TABLE_C: TableCRow[] = [
     },
     {
         // C4 — rule findings: requires spur rule run
+        // SAFETY: sentinel, not a string — this row never dispatches; null is the
+        // intentional HITL-stop placeholder that formatStageResult renders as no-command.
         redirectDispatch: null as unknown as string, // HITL stop
         rowId: 'C4',
         probeRows: ['A3', 'A5', 'A6'],
@@ -1315,6 +1419,17 @@ export function formatStageResult(result: StageResolution): string[] {
     return lines;
 }
 
+/** Current repository HEAD, best-effort — null outside a work tree or without git. */
+function currentHeadCommit(): string | null {
+    try {
+        const out = execSync('git rev-parse HEAD', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+        const commit = out.trim();
+        return commit.length > 0 ? commit : null;
+    } catch {
+        return null;
+    }
+}
+
 export function runCli(argv: string[], opts?: { resolve?: (input: ResolutionInput) => StageResolution }): CliResult {
     const parsed = parseCliArgs(argv);
     const resolve = opts?.resolve ?? resolveStage;
@@ -1337,6 +1452,30 @@ export function runCli(argv: string[], opts?: { resolve?: (input: ResolutionInpu
         };
     }
 
+    // Routing checkpoint (0711 R3): a canonical checkpoint at
+    // .spur/memory/sessions/<wbs>-checkpoint.md that survives inspection (owner,
+    // non-terminal, at HEAD, artifacts present) enables the A4 resume row for wip
+    // tasks; anything else is REPORTED and ignored — routing falls through to the
+    // non-checkpoint row. Best-effort and fail-open: git/fs failures leave the
+    // checkpoint unconsidered.
+    let checkpointNote: string | undefined;
+    let hasCheckpoint: boolean | undefined;
+    if (parsed.wbs) {
+        try {
+            const inspection = inspectRoutingCheckpoint(
+                join(process.cwd(), '.spur', 'memory', 'sessions'),
+                parsed.wbs,
+                { headCommit: currentHeadCommit() ?? undefined },
+            );
+            hasCheckpoint = inspection.usable;
+            if (!inspection.usable && inspection.reason !== 'absent') {
+                checkpointNote = `note: routing checkpoint ignored — ${inspection.reason}`;
+            }
+        } catch {
+            hasCheckpoint = undefined;
+        }
+    }
+
     // Build resolution input from CLI args (note: no live corpus access in CLI mode)
     const input: ResolutionInput = {
         target: parsed.wbs ?? parsed.feature ?? '',
@@ -1345,13 +1484,16 @@ export function runCli(argv: string[], opts?: { resolve?: (input: ResolutionInpu
         once: parsed.once,
         auto: parsed.auto,
         fullMode: parsed.full,
-        task: parsed.wbs ? { wbs: parsed.wbs, status: parsed.taskStatus ?? 'unknown', dependencies: [] } : undefined,
+        task: parsed.wbs
+            ? { wbs: parsed.wbs, status: parsed.taskStatus ?? 'unknown', dependencies: [], hasCheckpoint }
+            : undefined,
         feature: parsed.feature ? { id: parsed.feature, status: 'active', tasks: [] } : undefined,
     };
 
     try {
         const result = resolve(input);
         const lines = formatStageResult(result);
+        if (checkpointNote) lines.push(checkpointNote);
         return { exitCode: result.reasonKind === 'dispatch' ? 0 : 2, stdout: `${lines.join('\n')}\n`, stderr: '' };
     } catch (e) {
         return { exitCode: 1, stdout: '', stderr: `error: ${(e as Error).message}` };

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-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):**