@gobing-ai/spur 0.3.66 → 0.3.68

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

@@ -1,7 +1,7 @@
 ---
 description: Turn a vague idea into a feature with AC and a decomposed task batch — discovery, idea-eval, feature-create, AC, feature-check, system-design, decompose, batch-create (Design by default), handoff
 role: planner
-argument-hint: "\"<idea>\" [--auto] [--skip-design] [--approve-taste] [--agent <auto|name>]"
+argument-hint: "\"<idea>\" [--auto] [--skip-design] [--approve-taste] [--agent <inline|auto|name>]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
 
@@ -20,7 +20,7 @@ contract below maps to that workflow's transitions.
 | `--approve-taste` | With `--auto`: set idea_approved + design_approved so idea-eval / design-approval do not pause. | off |
 | `--idea-approved` | Compatibility alias for idea_approved=true (subset of --approve-taste). | off |
 | `--design-approved` | Compatibility alias for design_approved=true (subset of --approve-taste). | off |
-| `--agent` `<auto\|name>` | Who runs the model-bearing ideation. The pipeline's `agent.run` stages are headless — they always dispatch a subprocess. Omission and explicit `--agent inline` resolve identically per task 0687: tier substitution plus one warning naming the substituted executor; `auto` (tier-resolves an executor); a name (pins that executor). | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing ideation. 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 |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
@@ -31,7 +31,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
   [--auto]              # skip objective HITL only (feature-check, batch-create)
   [--skip-design]       # design package off (system-design + task Design)
   [--approve-taste]     # with --auto: skip idea-eval + design-approval pauses
-  [--agent <auto|name>]          # who runs the model-bearing ideation (default: agent.default)
+  [--agent <inline|auto|name>]   # inline is the current session; auto/name are async workers
 ```
 
 There is **no** `--design` force flag. Design is default-on; only `--skip-design` opts out.
@@ -42,6 +42,8 @@ vars as subsets of `--approve-taste` (`idea_approved` / `design_approved`). Pref
 ## 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="idea $ARGUMENTS")`
 - Stage contract (discovery → idea-eval → feature-create → AC → feature-check → system-design →
   decompose → batch-create → handoff): `plugins/sp/skills/spur-dev/references/dev-operations.md` § idea.

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.66",
+    "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}` };