@gobing-ai/spur 0.3.48 → 0.3.50

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

@@ -1,15 +1,15 @@
 ---
-description: Get things done — quality gate → fix → act CI simulation → commit → push → gh verify in one flow
+description: Get things done — quality gate → fix → commit → push → gh verify in one flow (optional act CI simulation via --act)
 role: coder
-argument-hint: "[<quality-gate-command>] [--dry-run] [--skip-act] [--no-push] [--no-verify] [--scope <path>] [--max-retry <n>]"
+argument-hint: "[<quality-gate-command>] [--dry-run] [--act] [--no-push] [--no-verify] [--scope <path>] [--max-retry <n>]"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Grep", "Glob"]
 ---
 
 # Dev GTD
 
 Self-contained end-to-end delivery command: local quality gate (auto-fix via `/sp:dev-fixall`),
-local CI/CD simulation via `act`, conventional commit message generation, commit, push, and
-GitHub push-success verification via `gh`. Designed to stand alone (no backing skill); once mature
+optional local CI/CD simulation via `act` (`--act` only), conventional commit message generation,
+commit, push, and GitHub push-success verification via `gh`. Designed to stand alone (no backing skill); once mature
 it supersedes `/sp:dev-gitmsg` and is absorbed into the shared command structure.
 
 ## Argument Flags
@@ -18,7 +18,7 @@ it supersedes `/sp:dev-gitmsg` and is absorbed into the shared command structure
 | --- | --- | --- |
 | `<quality-gate-command>` | Local quality gate to run first; on failure, invoke `/sp:dev-fixall "<cmd>"` to fix all issues automatically. | `bun run check` |
 | `--dry-run` | Generate the git message and plan only — no commit, push, or gh verify. | off |
-| `--skip-act` | Skip the local `act` CI/CD simulation step. | off |
+| `--act` | Run local `act` CI/CD simulation before commit (heavy: launches Docker). Default off — stage 6 `gh` verify covers real CI post-push. Reach for it on workflow edits, dependency bumps, infra changes. Independent of `--dry-run`: `--dry-run --act` still runs the simulation. | off |
 | `--no-push` | Commit but do not git push or gh-verify. | off |
 | `--no-verify` | Push but skip the `gh` push-success verification. | off |
 | `--scope <path>` | Scope the commit-message diff analysis to a path. | all staged changes |
@@ -28,7 +28,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ## Usage
 
-/sp:dev-gtd [<quality-gate-command>] [--dry-run] [--skip-act] [--no-push] [--no-verify] [--scope <path>] [--max-retry <n>]
+/sp:dev-gtd [<quality-gate-command>] [--dry-run] [--act] [--no-push] [--no-verify] [--scope <path>] [--max-retry <n>]
 
 ## Implementation
 
@@ -41,8 +41,9 @@ default `bun run check`. Run it. If it exits non-zero, invoke `/sp:dev-fixall "<
 re-run the gate. Loop until the gate is clean or `--max-retry` is exhausted. Report what was fixed
 per file.
 
-**2 — Local CI/CD simulation via `act`.** Confirm Docker is running (`docker info`). On macOS the
-repo uses OrbStack — if the default context is not ready, use
+**2 — Local CI/CD simulation via `act` (opt-in).** Skip this stage entirely unless `--act` is
+given. When `--act` is given: confirm Docker is running (`docker info`). On macOS the repo uses
+OrbStack — if the default context is not ready, use
 `DOCKER_HOST=unix://$HOME/.orbstack/run/docker.sock`. Run
 `act -W .github/workflows/ci.yml -j verify` (or the repo's `bun run verify-gha-ci`); prefer
 `--container-architecture` matching your host when the runner pulls a foreign platform. If a step
@@ -57,10 +58,8 @@ If the build failure includes `TS2307: Cannot find module` on a workspace packag
 resolve Bun workspace packages because Bun does not create `node_modules/@scope/` symlinks.
 The real GitHub CI runner passes. **Do not** modify the build infrastructure to work around this
 `act`-specific issue. Instead, emit a clear message:
-`⚠ act CI simulation failed on workspace resolution — this is a container-environment artifact. Re-run with --skip-act to skip this step.`
-Then stop the run (this stage failed). The operator can use `--skip-act` to proceed.
-
-Skip this stage entirely when `--skip-act` is given.
+`⚠ act CI simulation failed on workspace resolution — this is a container-environment artifact. Re-run without --act to skip this step (it is opt-in).`
+Then stop the run (this stage failed). The operator can proceed by re-running without `--act`.
 
 **3 — Generate a conventional commit message.** Follow the gitmsg procedure (the same one
 `/sp:dev-gitmsg` runs). Run `git diff --cached --stat` (add `-- <path>` when `--scope` is given) for

package/plugins/sp/commands/dev-history-load.md

@@ -0,0 +1,63 @@
+---
+description: "On-demand cumulative history load + narrowed analyze: run spur history import (checkpoint-resume, additive) then spur history analyze, optionally narrowed to a session/task/window, with optional forensics render. Triggers: load history, import agent conversations, analyze my history, history for this conversation"
+role: scribe
+argument-hint: "[--source <name>] [--session <id>] [--task <wbs>] [--since <iso>] [--until <iso>] [--report] [--dry-run] [--json]"
+allowed-tools: ["Bash", "Read"]
+---
+
+# Dev History Load
+
+Runs the on-demand history load+analyze sequence: `spur history import` (all sources, checkpoint
+resume — additive and self-healing) then `spur history analyze`, with narrowing flags routed to the
+verb that accepts them. Wraps the shipped CLI sequence in one discoverable surface; owns no import
+logic, no state, and no cadence.
+
+## Argument Flags
+
+| Flag                 | Description                                                    | Default  |
+| -------------------- | -------------------------------------------------------------- | -------- |
+| `--source` `<name>`  | Agent source to import and analyze (both verbs).               | all      |
+| `--session` `<id>`   | Narrow the analyze to a single session id.                     | omitted  |
+| `--task` `<wbs>`     | Narrow the analyze to a single task WBS.                       | omitted  |
+| `--since` `<iso>`    | Inclusive lower bound on the analyze window.                   | omitted  |
+| `--until` `<iso>`    | Inclusive upper bound on the analyze window.                   | omitted  |
+| `--report`           | Render `spur history report --mode forensics` after analyze.   | off      |
+| `--dry-run`          | Preview the sequence; import scans without persisting.         | off      |
+| `--json`             | Emit one JSON result object; no banner text interleaved.       | off      |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+```
+/sp:dev-history-load
+/sp:dev-history-load --source omp --session <session-id>
+/sp:dev-history-load --task <wbs> --since 2026-08-01 --until 2026-08-15
+/sp:dev-history-load --report
+/sp:dev-history-load --dry-run
+/sp:dev-history-load --json
+```
+
+**Cumulative by checkpoint, not by this command.** Re-running imports only newly appended
+conversation data — the shipped import checkpoint resume (task 0470 R6) makes repeat runs additive
+and never double-counts. This command never prunes reports and never re-implements the daily
+pipeline; for the periodic cadence (import-all → analyze → artifact → 90-day prune, self-healing),
+run `spur history daily` instead.
+
+**Degraded sources proceed with a warning; fully-failed imports abort (0569).** `spur history
+import` distinguishes fatal from degraded fan-outs by exit code: **exit 1** (every source
+failed) aborts the sequence before analyze and propagates the exit code; **exit 2** (mixed —
+at least one source imported, some skipped malformed rows) proceeds to analyze with a loud
+per-source warning: stderr names each degraded source with its parse/validation error counts
+(human mode), and the `--json` payload carries a `warnings` array with the source, counts, and
+the import step's warning detail. A steady-state degraded source therefore no longer blocks a
+bare run; to scope around one deliberately, use `--source <name>` per source.
+
+## Implementation
+
+Run the load-then-analyze sequence per `plugins/sp/scripts/history-load.ts` — import first, analyze
+only after import exits 0, narrowing forwarded to `analyze` only:
+
+```
+bun plugins/sp/scripts/history-load.ts $ARGUMENTS
+```

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

@@ -0,0 +1,39 @@
+---
+description: "Review GitHub PRs with Codex; collect and fix findings."
+role: reviewer
+argument-hint: "[full|submit|collect|fix|rerun|status|rules] [--base <branch>] [--no-wait] [--agent <inline|auto|name>] [<focus>]"
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Dev PR Review
+
+Wraps the **sp:pr-reviewing** skill. The review itself runs on the GitHub PR through Codex
+(`@codex review`) — never through a local Codex review mechanism; the invoking agent orchestrates
+and (in `fix` mode) implements.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `<mode>` | `full\|submit\|collect\|fix\|rerun\|status\|rules` — full: request (deduped) + wait + report; submit: request and stop at pending; collect: report the latest review; fix: validate findings, fix legitimate ones, re-review; rerun: force a fresh review of the pushed HEAD; status: read-only composite; rules: author the repo's `AGENTS.md` `## Code Review Rules`. | full |
+| `--base` `<branch>` | Base branch when a new PR must be created. | existing PR base, else repo default |
+| `--no-wait` | Return pending right after the review request instead of polling. | off |
+| `--agent` `<inline\|auto\|name>` | Who performs model-bearing triage/fix. Omit uses the current agent, `inline` forbids dispatch, `auto` resolves the declared role, and a name pins that executor. This does not change the deterministic workflow/direct route. | omit |
+| `<focus>` | Remaining free text — extra review focus appended to the Codex request (e.g. `security boundaries and transaction idempotency`). | none |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+/sp:dev-pr-review [full|submit|collect|fix|rerun|status|rules] [--base <branch>] [--no-wait] [--agent <inline|auto|name>] [review focus]
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Delegate everything: `Skill(skill="sp:pr-reviewing", args="$ARGUMENTS")`. The skill owns mode
+  routing, finding triage, fix, and rules authoring; `.spur/workflows/pr-review.yaml` is the SSOT
+  for the review spine's state order and guards; the staged `pr-reviewing.ts` is the
+  deterministic git/gh core every spine step shells out to.
+- The external review goes through the GitHub PR and an `@codex review` comment only — never local
+  Codex review commands. Never force-push, rewrite history, merge the PR, or discard unrelated
+  changes; outside `fix` mode, ask before creating any commit.

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.48",
+    "version": "0.3.50",
     "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/references/roles.md

@@ -9,10 +9,12 @@ see_also:
 
 # Roles — the Layer-1 role-to-tier table
 
-The executor-selection contract is two layers. **Layer 1 (this file)** maps *role → tier* and is
-owned by plugin `sp`; **Layer 2** maps *tier → executor* and is owned by the operator in
-`.spur/config.yaml`. This file never names an executor, a model, or a vendor — it declares only
-what tier a role's work needs, and the operator's config decides which executor serves that tier.
+The executor-selection contract is two layers. **Layer 1 (this file)** projects *role → tier*;
+its SSOT is `DEFAULT_AGENT_ROLES` in `packages/config/src/index.ts` (task 0572 / ADR-061) — this
+file is the agent/human-facing view plus the plugin-owned command→role mapping. **Layer 2** maps
+*tier → executor* and is owned by the operator in `.spur/config.yaml`. This file never names an
+executor, a model, or a vendor — it declares only what tier a role's work needs, and the
+operator's config decides which executor serves that tier.
 
 The vocabulary is four roles, one per tier:
 
@@ -36,12 +38,17 @@ collapse, named as people so they stay addressable in `--agent`.
 
 ## The table
 
+<!-- PROJECTION (task 0572 / ADR-061): the tier/stages half of the block below is a generated view
+     of DEFAULT_AGENT_ROLES in packages/config/src/index.ts — edit that constant, not this file.
+     plugins/sp/tests/roles.test.ts (R9) fails the suite on any drift between the two. The
+     `commands:` half is plugin data (command frontmatter is its SSOT). -->
+
 ```yaml
 version: 1
 roles:
   - id: scribe
     tier: cheap
-    commands: [dev-gitmsg, dev-handover, dev-daily, dev-changelog, dev-refresh, rule-add, rule-refine, workflow-add, workflow-refine, spur-init]
+    commands: [dev-gitmsg, dev-handover, dev-daily, dev-history-load, dev-changelog, dev-refresh, rule-add, rule-refine, workflow-add, workflow-refine, spur-init]
     stages: [changelog]
   - id: coder
     tier: standard
@@ -49,11 +56,11 @@ roles:
     stages: [implement, test, wrap]
   - id: reviewer
     tier: capable-1
-    commands: [dev-verify, dev-verifyall, dev-review, dev-dogfood, rule-scan, dev-find-conflict, dev-find-issue]
+    commands: [dev-verify, dev-verifyall, dev-review, dev-pr-review, dev-dogfood, rule-scan, dev-find-conflict, dev-find-issue]
     stages: [verify, review, dogfood]
   - id: planner
     tier: capable-2
-    commands: [dev-plan, dev-refine, dev-brainstorm, dev-idea, dev-runall, dev-parallel, dev-next, dev-arch, dev-refineall, dev-find-next, dev-featurechange]
+    commands: [dev-plan, dev-refine, dev-brainstorm, dev-idea, dev-runall, dev-parallel, dev-next, dev-arch, dev-refineall, dev-find-next, dev-feature-change]
     stages: [plan, refine, brainstorm]
 ```
 
@@ -81,13 +88,19 @@ must not sit below the highest `min_tier` among its folded stages.
   `refine`, `brainstorm`.
 
 **Placement notes (directory closure, task 0535).** The decided four-row table listed 31 commands;
-the live `plugins/sp/commands/` directory has 37. The six additional commands were placed by the
+the live `plugins/sp/commands/` directory has 39. The six additional commands were placed by the
 same stage logic: `dev-refineall` folds `refine` → planner; `dev-find-next` is planning-side
-frontier work → planner; `dev-featurechange` is planning-half corpus surgery on the feature tree →
+frontier work → planner; `dev-feature-change` is planning-half corpus surgery on the feature tree →
 planner; `dev-gtd` is the execution/delivery flow → coder; `dev-find-conflict` and `dev-find-issue`
-are audits/analysis → reviewer (same reasoning as `rule-scan`).
+are audits/analysis → reviewer (same reasoning as `rule-scan`). Later additions: `dev-history-load`
+is mechanical load+analyze orchestration → scribe; `dev-pr-review` is review orchestration —
+driving the external PR review and triaging its findings folds the `review` stage → reviewer.
 
 **Consistency is a test, not a convention.** `plugins/sp/tests/roles.test.ts` parses this YAML and
 asserts the tier-distinctness, command closure, stage-floor, and boundary invariants against the
-real command directory, the real stage registry, and the real operator config. When the table and
-the registry disagree, fix the table or the registry — never the test.
+real command directory, the real stage registry, and the real operator config — plus parity with
+`DEFAULT_AGENT_ROLES` (R9, 0572): the table above must equal the code SSOT byte-for-byte on
+id/tier/stages. When the table and the registry disagree, fix the table or the registry — never the
+test. When the table and `DEFAULT_AGENT_ROLES` disagree, fix the constant (or regenerate this view).
+A project may re-tier/re-stage a role at config time via `agent.roles` (closed vocabulary) — that
+override never flows back into this file.

package/plugins/sp/scripts/history-load.ts

@@ -0,0 +1,400 @@
+#!/usr/bin/env bun
+/**
+ * dev-history-load — on-demand cumulative history import + narrowed analyze (task 0567).
+ *
+ * Deterministic CLI sequence backing `/sp:dev-history-load`. Runs `spur history import`
+ * first, then `spur history analyze` only after import exits 0 or 2 (exit 2 is a
+ * mixed/degraded fan-out: proceed with a loud per-source warning — 0569). Narrowing flags
+ * (`--session`, `--task`, `--since`, `--until`) are forwarded to `analyze` only — `import`
+ * rejects them. `--source` reaches both. Owns no import logic, no state, and no cadence:
+ * cumulative behavior comes from the shipped checkpoint resume, and the periodic pipeline
+ * stays on `spur history daily`.
+ *
+ * Frozen flag set (dev-history-load.md argument-hint): `--source <name>`, `--session <id>`,
+ * `--task <wbs>`, `--since <iso>`, `--until <iso>`, `--report`, `--dry-run`, `--json`.
+ * Unknown flags are a hard error (exit 2) — never silently forwarded.
+ *
+ * Every `spur history` step uses `--json`; human output is derived from parsed JSON, never
+ * from child-process prose.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// ─── Frozen flag surface ────────────────────────────────────────────────────
+
+/** Flags that consume the next argv token as their value. */
+const VALUE_FLAGS: Record<string, true> = {
+    '--source': true,
+    '--session': true,
+    '--task': true,
+    '--since': true,
+    '--until': true,
+};
+/** Flags that are boolean switches. */
+const BOOL_FLAGS: Record<string, true> = {
+    '--report': true,
+    '--dry-run': true,
+    '--json': true,
+};
+const ALL_FLAGS: Record<string, true> = { ...VALUE_FLAGS, ...BOOL_FLAGS };
+
+interface ParsedArgs {
+    source?: string;
+    session?: string;
+    task?: string;
+    since?: string;
+    until?: string;
+    report: boolean;
+    dryRun: boolean;
+    json: boolean;
+}
+
+interface ProcResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+}
+
+// ─── Arg parsing ─────────────────────────────────────────────────────────────
+
+function usage(): never {
+    console.error(
+        'Usage: history-load.ts [--source <name>] [--session <id>] [--task <wbs>] ' +
+            '[--since <iso>] [--until <iso>] [--report] [--dry-run] [--json]',
+    );
+    process.exit(2);
+}
+
+/** Flag literal → ParsedArgs field. `--dry-run` is the one flag whose field name differs. */
+const FLAG_KEY: Record<string, keyof ParsedArgs> = {
+    '--source': 'source',
+    '--session': 'session',
+    '--task': 'task',
+    '--since': 'since',
+    '--until': 'until',
+    '--report': 'report',
+    '--dry-run': 'dryRun',
+    '--json': 'json',
+};
+
+/** Parse argv against the frozen flag set; unknown flags exit 2. */
+function parseArgs(argv: string[]): ParsedArgs {
+    const out: ParsedArgs = { report: false, dryRun: false, json: false };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (!arg.startsWith('--') || ALL_FLAGS[arg] !== true) usage();
+        if (BOOL_FLAGS[arg] === true) {
+            out[FLAG_KEY[arg]] = true;
+            continue;
+        }
+        const value = argv[++i];
+        if (value === undefined || value.startsWith('--')) usage();
+        out[FLAG_KEY[arg]] = value;
+    }
+    return out;
+}
+
+// ─── spur resolution + invocation ────────────────────────────────────────────
+
+/**
+ * Resolve the spur CLI monorepo-safely: SPUR_BIN env > monorepo-local CLI entry > PATH.
+ * Mirrors task-size-precheck.ts defaultSpurBin so ad-hoc and test invocations resolve the
+ * same way (never a silently stale PATH install).
+ */
+function defaultSpurBin(): string {
+    if (process.env.SPUR_BIN) return process.env.SPUR_BIN;
+    const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
+    if (existsSync(local)) return `bun ${local}`;
+    return 'spur';
+}
+
+/** Run spur with a possibly multi-token bin (`<runtime> <mainModule>`), splitting like runSpur. */
+function runSpur(spurBin: string, args: string[]): ProcResult {
+    const [file = 'spur', ...lead] = spurBin.split(/\s+/).filter(Boolean);
+    const result = spawnSync(file, [...lead, ...args], { encoding: 'utf-8' });
+    return {
+        status: result.status ?? 1,
+        stdout: result.stdout ?? '',
+        stderr: result.stderr ?? '',
+    };
+}
+
+// ─── Artifact path resolution ────────────────────────────────────────────────
+
+/**
+ * Resolve the analyze artifact path from the `latest.json` pointer the analyze step
+ * maintains (task 0464 R2 symlink under `.spur/reports/history/`). Returns null when the
+ * pointer is absent or dangling.
+ */
+function latestArtifactPath(cwd: string): string | null {
+    const pointer = join(cwd, '.spur', 'reports', 'history', 'latest.json');
+    if (!existsSync(pointer)) return null;
+    try {
+        return realpathSync(pointer);
+    } catch {
+        return null;
+    }
+}
+
+// ─── Result shaping ──────────────────────────────────────────────────────────
+
+interface ImportJson {
+    entries?: Array<{
+        source: string;
+        status: string;
+        messages?: number;
+        parseErrors?: number;
+        validationErrors?: number;
+    }>;
+    exitCode?: number;
+    warnings?: Array<{ code: string; source: string; detail?: string }>;
+    provenance?: unknown;
+}
+
+/** Parse `spur history import --json` output; returns null when unparseable. */
+function parseImportJson(stdout: string): ImportJson | null {
+    try {
+        const parsed = JSON.parse(stdout) as ImportJson;
+        return parsed && Array.isArray(parsed.entries) ? parsed : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Build the analyze argv with narrowing routed to analyze only. */
+function buildAnalyzeArgs(args: ParsedArgs): string[] {
+    const out = ['history', 'analyze', '--json'];
+    if (args.source) out.push('--source', args.source);
+    if (args.session) out.push('--session', args.session);
+    if (args.task) out.push('--task', args.task);
+    if (args.since) out.push('--since', args.since);
+    if (args.until) out.push('--until', args.until);
+    return out;
+}
+
+/** Emit a single JSON object on stdout; used for every `--json` exit path. */
+function emitJson(obj: unknown): void {
+    process.stdout.write(`${JSON.stringify(obj)}\n`);
+}
+
+/** Per-source degradation summary carried into output payloads (task 0569). */
+interface DegradedWarning {
+    source: string;
+    status: string;
+    parseErrors: number;
+    validationErrors: number;
+    detail: string;
+}
+
+/**
+ * Build per-source degradation warnings from a fan-out import JSON: one entry per
+ * degraded/failed source with its parse/validation error counts and the import step's
+ * warning detail (0569 R1). Empty on a clean fan-out.
+ */
+function buildDegradedWarnings(imp: ImportJson | null): DegradedWarning[] {
+    const detailFor = (source: string): string =>
+        imp?.warnings?.find((w) => w.source === source)?.detail ?? 'no warning detail reported by import';
+    return (imp?.entries ?? [])
+        .filter((e) => e.status === 'degraded' || e.status === 'failed')
+        .map((e) => ({
+            source: e.source,
+            status: e.status,
+            parseErrors: typeof e.parseErrors === 'number' ? e.parseErrors : 0,
+            validationErrors: typeof e.validationErrors === 'number' ? e.validationErrors : 0,
+            detail: detailFor(e.source),
+        }));
+}
+
+/** Attach the degradation warnings to a payload only when the fan-out was degraded (0569 R1). */
+function withWarnings(payload: Record<string, unknown>, degraded: DegradedWarning[]): Record<string, unknown> {
+    return degraded.length > 0 ? { ...payload, warnings: degraded } : payload;
+}
+
+// ─── Main sequence ───────────────────────────────────────────────────────────
+
+function main(): void {
+    const args = parseArgs(process.argv.slice(2));
+    const spurBin = defaultSpurBin();
+    const cwd = process.cwd();
+
+    // 1. Import argv — narrowing flags NEVER reach import (it rejects them).
+    const importArgs = ['history', 'import', '--json'];
+    if (args.source) importArgs.push('--source', args.source);
+    if (args.dryRun) importArgs.push('--dry-run');
+
+    const importResult = runSpur(spurBin, importArgs);
+    const imp = parseImportJson(importResult.stdout);
+
+    // 2. Fatal import failures (R9, 0569): any non-zero exit EXCEPT the mixed/degraded
+    //    code 2 aborts — surface the failing source + error, skip analyze, propagate the
+    //    import step's exit code.
+    if (importResult.status !== 0 && importResult.status !== 2) {
+        const failed = (imp?.entries ?? [])
+            .filter((e) => e.status !== 'ok' && e.status !== 'empty')
+            .map((e) => e.source);
+        const warning = imp?.warnings?.find((w) => w.code === 'source-failed' || w.code === 'source-degraded');
+        const detail = warning?.detail || importResult.stderr.trim() || 'import exited non-zero';
+        const message = failed.length > 0 ? `import failed for source(s): ${failed.join(', ')} — ${detail}` : detail;
+        if (args.json) {
+            emitJson({
+                import: imp ?? { entries: [], exitCode: importResult.status },
+                artifact: null,
+                reported: false,
+                status: 'error',
+                message,
+            });
+        } else {
+            console.error(message);
+        }
+        process.exit(importResult.status);
+    }
+
+    // 2b. Degraded fan-out tolerance (0569 R1): exit 2 (mixed — at least one source
+    //     imported, some skipped rows) proceeds to analyze with a loud per-source warning.
+    const degraded = importResult.status === 2 ? buildDegradedWarnings(imp) : [];
+    if (degraded.length > 0 && !args.json) {
+        console.error('WARNING: import fan-out degraded — proceeding with the healthy sources:');
+        for (const w of degraded) {
+            console.error(
+                `  ${w.source}: status=${w.status} parseErrors=${w.parseErrors} ` +
+                    `validationErrors=${w.validationErrors} — ${w.detail}`,
+            );
+        }
+    }
+
+    // 3. Dry-run short-circuit (R4): report what would have run, write nothing.
+    if (args.dryRun) {
+        const analyzeArgs = buildAnalyzeArgs(args);
+        const sequence = [`spur history import --json${args.source ? ` --source ${args.source}` : ''} --dry-run`];
+        sequence.push(`spur ${analyzeArgs.join(' ')}`);
+        if (args.report) sequence.push('spur history report --mode forensics <artifact-path>');
+        if (args.json) {
+            emitJson(
+                withWarnings(
+                    {
+                        import: imp ?? { entries: [], exitCode: importResult.status },
+                        artifact: null,
+                        reported: false,
+                        status: 'dry-run',
+                        wouldRun: sequence,
+                    },
+                    degraded,
+                ),
+            );
+        } else {
+            console.log('[dry-run] would run:');
+            for (const line of sequence) console.log(`  ${line}`);
+        }
+        process.exit(0);
+    }
+
+    // 4. Analyze — only after import exited 0. Narrowing flags forwarded here only.
+    const analyzeResult = runSpur(spurBin, buildAnalyzeArgs(args));
+    if (analyzeResult.status !== 0) {
+        const message = analyzeResult.stderr.trim() || `history analyze exited non-zero (${analyzeResult.status})`;
+        if (args.json) {
+            emitJson({
+                import: imp ?? { entries: [], exitCode: 0 },
+                artifact: null,
+                reported: false,
+                status: 'error',
+                message,
+            });
+        } else {
+            console.error(message);
+        }
+        process.exit(analyzeResult.status);
+    }
+
+    let artifact: { totals?: { messages?: number } } | null = null;
+    try {
+        artifact = JSON.parse(analyzeResult.stdout) as { totals?: { messages?: number } };
+    } catch {
+        // fall through — artifact resolution below will surface the missing pointer
+    }
+    const artifactPath = latestArtifactPath(cwd);
+
+    // 5. Empty-window guard (R10): zero matched messages is NOT a successful analysis.
+    const messages = artifact?.totals?.messages;
+    if (typeof messages === 'number' && messages === 0) {
+        const message = 'history analyze: window matched zero messages — nothing to report';
+        if (args.json) {
+            emitJson({
+                import: imp ?? { entries: [], exitCode: 0 },
+                artifact: artifactPath,
+                reported: false,
+                status: 'empty-window',
+                message,
+            });
+        } else {
+            console.error(message);
+        }
+        process.exit(1);
+    }
+
+    if (artifactPath === null) {
+        const message =
+            'history analyze completed but no artifact pointer (.spur/reports/history/latest.json) was found';
+        if (args.json) {
+            emitJson({
+                import: imp ?? { entries: [], exitCode: 0 },
+                artifact: null,
+                reported: false,
+                status: 'error',
+                message,
+            });
+        } else {
+            console.error(message);
+        }
+        process.exit(1);
+    }
+
+    // 6. Optional forensics render (R5) against the artifact just written.
+    let reported = false;
+    let reportText = '';
+    if (args.report) {
+        const reportResult = runSpur(spurBin, ['history', 'report', '--mode', 'forensics', artifactPath]);
+        reported = reportResult.status === 0;
+        reportText = reportResult.stdout;
+        if (reportResult.status !== 0) {
+            const message = reportResult.stderr.trim() || `history report exited non-zero (${reportResult.status})`;
+            if (args.json) {
+                emitJson({
+                    import: imp ?? { entries: [], exitCode: 0 },
+                    artifact: artifactPath,
+                    reported: false,
+                    status: 'error',
+                    message,
+                });
+            } else {
+                console.error(message);
+            }
+            process.exit(reportResult.status);
+        }
+    }
+
+    // 7. Output: one JSON object (no interleaved banner) or a short human summary.
+    const count = (imp?.entries ?? []).reduce((sum, e) => sum + (typeof e.messages === 'number' ? e.messages : 0), 0);
+    if (args.json) {
+        const payload = withWarnings(
+            {
+                import: imp ?? { entries: [], exitCode: 0 },
+                artifact: artifactPath,
+                reported,
+                status: 'ok',
+            },
+            degraded,
+        );
+        if (args.report) payload.report = reportText;
+        emitJson(payload);
+    } else {
+        console.log(`history import: ${count} records`);
+        console.log(`artifact: ${artifactPath}`);
+        if (args.report) process.stdout.write(reportText);
+    }
+}
+
+main();