@gobing-ai/spur 0.3.77 → 0.3.80

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.77",
+    "version": "0.3.80",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -53,14 +53,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.4.57",
-        "@gobing-ai/ts-ai-runner": "^0.4.57",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.57",
-        "@gobing-ai/ts-infra": "^0.4.57",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.57",
-        "@gobing-ai/ts-rule-engine": "^0.4.57",
-        "@gobing-ai/ts-runtime": "^0.4.57",
-        "@gobing-ai/ts-utils": "^0.4.57",
+        "@gobing-ai/ts-db": "^0.4.62",
+        "@gobing-ai/ts-ai-runner": "^0.4.62",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.62",
+        "@gobing-ai/ts-infra": "^0.4.62",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.62",
+        "@gobing-ai/ts-rule-engine": "^0.4.62",
+        "@gobing-ai/ts-runtime": "^0.4.62",
+        "@gobing-ai/ts-utils": "^0.4.62",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/README.md

@@ -171,10 +171,12 @@ Commands above are thin wrappers; the actual logic lives in `skills/`. The spine
 dispatches five competency skills by function — design (`sp:sys-architecture`), decomposition
 (`sp:spec-decomposition`), implementation (`sp:code-implementation`), testing (`sp:code-testing`),
 and verification (`sp:code-verification`) — plus a CLI facade (`sp:spur-cli`, one reference per
-`spur` noun) and standalone technique skills (`sp:next-router`, `sp:test-driven-development`, `sp:brainstorm`,
-`sp:wayfinder`, `sp:sys-debugging`, `sp:code-review`, `sp:code-simplification`, `sp:code-improvement`,
-`sp:parallel-execution`, `sp:branch-workflow`, `sp:doc-evolve`, `sp:dogfood-testing`,
-`sp:daily-summary`, `sp:reverse-engineering`, `sp:issue-finding`, `sp:conflict-finding`,
+`spur` noun) and standalone technique skills (`sp:next-router`, `sp:next-feature`,
+`sp:test-driven-development`, `sp:source-driven-development`, `sp:doubt-driven-development`,
+`sp:brainstorm`, `sp:wayfinder`, `sp:sys-debugging`, `sp:code-review`, `sp:pr-reviewing`,
+`sp:functional-review`, `sp:code-simplification`, `sp:code-improvement`, `sp:parallel-execution`,
+`sp:branch-workflow`, `sp:doc-evolve`, `sp:dogfood-testing`, `sp:daily-summary`,
+`sp:reverse-engineering`, `sp:history-anatomy`, `sp:issue-finding`, `sp:conflict-finding`,
 `sp:indexed-context`, `sp:session-review`, `sp:redesign-web-ui`). See
 [skills/spur-dev/SKILL.md](skills/spur-dev/SKILL.md)'s Step routing table for which skill owns which
 pipeline step.
@@ -215,6 +217,7 @@ plugins/sp/
 │   │   └── references/routing-table.md
 │   ├── parallel-execution/          # Fan-out decision framework + patterns
 │   │   └── references/{fan-out-patterns, result-synthesis}.md
+│   ├── pr-reviewing/                # GitHub PR review loop backing /sp:dev-pr-review
 │   ├── source-driven-development/   # Source-first API/contract verification (SKILL.md only)
 │   ├── spec-decomposition/          # Feature/spec → task-batch competency
 │   │   └── references/decomposition.md
@@ -255,6 +258,8 @@ plugins/sp/
 ├── agents/                          # 4 specialist subagents (expert-spur, super-coder, super-planner, super-reviewer)
 ├── hooks/                           # hooks.json + task-write-guard.{ts,test.ts} + context-{session-start,post-tool,session-stop}.ts
 │                                    # + careful-guard.{ts,test.ts} + context-hooks.test.ts + token-estimate.test.ts
+│                                    # + shared policy modules: agent-hint.ts, destructive-policy.{ts,test.ts}, task-file-policy.{ts,test.ts}
+│                                    # + pi/guard-extension.{ts,test.ts} (plugin.json `extensions.pi` entry point)
 ├── scripts/                         # Executable helpers, split from prompts (ADR-031) — validate-commands.ts (thin-wrapper validator), batch-preflight.ts + scripts/<skill>/
 │                                    # (daily-summary: {daily-summary, logger}.ts; dogfood-testing: {detect-pipeline-driving, validate-report}.ts)
 ├── tests/                           # Plugin tests — command-contract.test.ts + skill-structure.test.ts + batch-preflight.test.ts + per-skill suites
@@ -318,13 +323,13 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `daily-summary`             | 1.0.0 | Daily summary report generator — orchestrates ccusage CLI + git history into structured markdown summaries                                                                                                                                 |
 | `doc-evolve`                | 1.0   | Key-document evolution per `docs/99_PROJECT_CONSTITUTION.md` — drift audits, same-commit sync checks, frontmatter-contract verification, machine-appended lessons                                                                          |
 | `reverse-engineering`       | 1.1   | Codebase analysis / HLD generation / audit — depth-driven reverse engineering with orthogonal mode, focus, and format controls; backs `/sp:dev-reverse`                                                                                    |
-| `issue-finding`             | 1.1   | Session-log forensics — multi-source discovery, bottleneck ranking, optional topic focus, CLI-gated fix task generation; **legacy path** — superseded by `history-anatomy` for indexed reporting; backs no current command; directly invocable as sp:issue-finding |
+| `issue-finding`             | 2.0   | Session-log forensics — multi-source discovery, bottleneck ranking, optional topic focus, CLI-gated fix task generation; **legacy path** — superseded by `history-anatomy` for indexed reporting; backs no current command; directly invocable as sp:issue-finding |
 | `conflict-finding`          | 1.0   | Authority-aware semantic audit — four-pillar (source/task/feature/authority) conflict discovery, claim-specific authority resolution, reproducible evidence, confirmed owner-routed remediation; backs `/sp:dev-find-conflict`             |
 | `next-feature`              | 1.0   | Prompt-first feature frontier prioritizer — sync-first precondition, B3 actionability gate (cited, never restated), tiered rubric over measured signals, D1–D4 defect proposals conforming to the restructure map schema; backs `/sp:dev-find-next` |
 | `pr-reviewing`              | 1.0   | GitHub Codex PR review — PR prepare/reuse, `@codex review` request with per-HEAD dedupe, bounded polling, findings normalization, validated fix + re-review; spine SSOT `pr-review.yaml` + `scripts/pr-reviewing.ts`; backs `/sp:dev-pr-review`     |
 | `indexed-context`           | 1.0   | Cross-agent project context — anatomy/learnings/pitfalls/buglog/memory in `.spur/context/`; hook-tracked token-ledger; graceful degradation on agents without hooks                                                                        |
 | `history-anatomy`           | 1.0   | Diagnostic interpretation owner over already-imported history — daily/ad-hoc mode contract, closed finding taxonomy, twelve-section report contract, `enrich`/`validate` rubrics; no workflow launch, no JSONL fallback, no corpus mutation                                                                   |
-| `session-review`            | 1.0   | Inline review of the active coding-agent session — compact outcomes, evidence-backed resolved/open issue classification, proposal-only improvements, and next actions; no workflow, import, delegation, or mutation                                                                                           |
+| `session-review`            | 1.1   | Inline review of the active coding-agent session — compact outcomes, evidence-backed resolved/open issue classification, proposal-only improvements, and next actions; no workflow, import, delegation, or mutation                                                                                           |
 | `redesign-web-ui`           | 1.0   | Existing-UI visual upgrade — audit generic AI fingerprints, apply in-stack polish against `DESIGN.md` / live tokens, verify behavior and viewports; does not migrate frameworks                                                                                                                            |
 
 #### Bounded coexistence and retirement gate — `sp:issue-finding` (HA-S1 0661)
@@ -418,7 +423,7 @@ the pipeline's Phase 7 review step.
 | ---------------- | ------------ | ----------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------- |
 | `expert-spur`    | expert       | `sp:spur-cli`                                                           | green   | "create tasks", "feature lifecycle", "add a rule", "author a workflow"          |
 | `super-coder`    | builder      | `sp:sys-architecture` + `sp:code-implementation` + `sp:code-testing` + `sp:sys-debugging` | blue    | "implement this", "write the code", "fix this bug", "design the architecture"   |
-| `super-planner`  | orchestrator | `sp:spur-dev` + `sp:dogfood-testing`                                    | green   | "run this task end to end", "run all tasks", "run the batch", "runall"          |
+| `super-planner`  | orchestrator | `sp:spur-dev` + `sp:parallel-execution` + `sp:dogfood-testing` + `sp:next-router` | green   | "run this task end to end", "run all tasks", "run the batch", "runall"          |
 | `super-reviewer` | reviewer     | `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` | crimson | "review this", "check the code", "SECUA review", "run task 0042 through review" |
 
 Each agent has:

package/plugins/sp/agents/super-reviewer.md

@@ -97,7 +97,8 @@ HITL gate unless `--auto` was passed.
 - [ ] Establish scope first: WBS mode (task diff) or path mode (source glob). Derive the diff
       scope the same way `sp:code-verification` Step 3 does.
 - [ ] Dispatch each requested dimension to its owning skill — do not inline the review logic.
-- [ ] Merge findings into a single ranked report (severity: blocker > major > minor > advisory).
+- [ ] Merge findings into a single ranked report, emitting native priority cells
+      (`P1 (blocker)` > `P2 (major)` > `P3 (minor)` > `P4 (advisory)` — see Output Format).
 - [ ] In pipeline mode, write the merged report to the task's `## Review` section via
       `spur task update <wbs> --section Review --from-file`; in standalone mode, emit as output.
 - [ ] Cite `file:line` evidence for every finding — no vague "implemented correctly."
@@ -109,6 +110,8 @@ HITL gate unless `--auto` was passed.
 - [ ] Never edit `task-pipeline.yaml` or reach into a pipeline step.
 - [ ] Never auto-approve a HITL gate unless `--auto` was passed.
 - [ ] Never soften a FAIL to PARTIAL, or PARTIAL to PASS, to avoid surfacing.
+- [ ] Never emit a word-only Severity cell, an empty priority scaffold, or a `##`/`###` heading
+      inside a `### Review` body — all three fail the existing checkers.
 - [ ] Never skip a dimension the operator requested with `--focus`.
 
 ## Definition of Done Housekeeping
@@ -120,22 +123,44 @@ enforcement checklist. Reference:
 
 ## Output Format
 
+### Priority vocabulary (task 0818 R3)
+
+Emit priorities **natively** — the consumer (`hasPopulatedPriorityTable`,
+`packages/app/src/services/task-check.ts`) requires a `P1`–`P4` cell, and a word-only severity cell
+fails it. One explicit mapping, no transcription step anywhere downstream:
+
+| Priority cell | Severity | Meaning |
+| --- | --- | --- |
+| `P1 (blocker)` | blocker | Ships broken or unsafe; blocks the verdict |
+| `P2 (major)` | major | Real defect or structural problem; must be dispositioned |
+| `P3 (minor)` | minor | Localized issue; fix or accept explicitly |
+| `P4 (advisory)` | advisory | Observation, non-blocking |
+
+Severity words stay visible in the same cell — the mapping adds the machine-readable label, it does
+not replace the semantics.
+
+**Section-relative headings.** In pipeline mode the report body is written *into* the task's
+`### Review` section, so every heading inside it MUST be `####` or deeper. A `##`/`###` heading in
+the body becomes a new top-level task section and corrupts the document. In standalone mode
+(emitted as output, not written to a task) the same body may be rendered one level shallower.
+
 ```markdown
-## Review Report — <wbs|path>
+#### Review Report — <wbs|path>
 
 **Scope:** <wbs diff | path glob>
 **Dimensions:** functional, security, efficiency, correctness, usability, architecture
 **Verdict:** PASS | PARTIAL | FAIL
 
-### Findings (ranked)
+##### Findings (ranked)
 
-| # | Severity | Dimension | Finding | Location |
+| # | Priority | Dimension | Finding | Location |
 |---|----------|-----------|---------|----------|
-| 1 | blocker | security | SQL injection in query builder | `src/api/users.ts:42` |
-| 2 | major | architecture | Shallow pass-through UserService | `src/services/users.ts:15` |
-| 3 | minor | correctness | Missing error branch in createUser | `src/api/users.ts:48` |
+| 1 | P1 (blocker) | security | SQL injection in query builder | `src/api/users.ts:42` |
+| 2 | P2 (major) | architecture | Shallow pass-through UserService | `src/services/users.ts:15` |
+| 3 | P3 (minor) | correctness | Missing error branch in createUser | `src/api/users.ts:48` |
+| 4 | P4 (advisory) | usability | `createUser` error text omits the field name | `src/api/users.ts:51` |
 
-### Functional Traceability
+##### Functional Traceability
 
 | Req | Status | Evidence |
 |-----|--------|----------|
@@ -145,6 +170,16 @@ enforcement checklist. Reference:
 **Next:** <one-line action>
 ```
 
+**No findings.** Never invent a defect to populate the table. Emit one substantive `P4 (advisory)`
+row that states what was reviewed and what was found — placeholder cells (empty, `—`, `n/a`) are
+rejected by the checker, and so they should be:
+
+```markdown
+| # | Priority | Dimension | Finding | Location |
+|---|----------|-----------|---------|----------|
+| 1 | P4 (advisory) | — | No P1–P3 findings: 6 changed files reviewed across all six dimensions; R1–R3 traceable to tests | `packages/app/src/workflow/proof-input-fingerprint.ts:102-160` |
+```
+
 With `--json`, emit the same shape as a JSON object for machine consumption.
 
 ## Out of scope

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

@@ -62,5 +62,6 @@ thread `--depth` into each per-task refine.
 ## Implementation
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — bootstrap checklist, quick readiness before isolation, workflow inventory before YAML, comprehensive checks at owning boundaries (task 0814 R1/R3/R4/R7/R8).
 - Batch orchestration: `Skill(skill="sp:spur-dev", args="refineall $ARGUMENTS")`
 - Per-task refine (inner): `Skill(skill="sp:spur-dev", args="refine <wbs> $SHARED_FLAGS")`

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

@@ -31,6 +31,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 ## Implementation
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — bootstrap checklist, quick readiness before isolation, workflow inventory before YAML, comprehensive checks at their owning boundaries (task 0814 R1/R3/R4/R7/R8).
 - Full pipeline (default `--mode full`): interactive omit/`--agent inline` uses the
   [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md) via
   `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")`; `--agent auto` or a named executor

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

@@ -82,5 +82,6 @@ full distinction.
 ## Implementation
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface). Interactive sequential omit/`inline` keeps the orchestrator in the host session through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md); the resolved selector applies uniformly — eligible `agent.run` stages dispatch once to a native subagent with host fallback (0508). `--agent auto`, a name, or parallel mode retains the isolated per-task workflow boundary.
+- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — bootstrap checklist, quick readiness before isolation, workflow inventory before YAML, comprehensive checks at owning boundaries (task 0814 R1/R3/R4/R7/R8).
 - Interactive sequential omit/inline: `Skill(skill="sp:spur-dev", args="runall-inline $ARGUMENTS")`.
 - Explicit executor or parallel mode: `Skill(skill="sp:spur-dev", args="runall $ARGUMENTS")` → `sp:super-planner` agent.

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

@@ -68,6 +68,7 @@ Without `--fix all`, shippable is not evaluated (optional note: use `--fix all`
 ## Implementation
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — bootstrap checklist, quick readiness before isolation, workflow inventory before YAML, comprehensive checks at owning boundaries (task 0814 R1/R3/R4/R7/R8).
 - Batch orchestration: `Skill(skill="sp:spur-dev", args="verifyall $ARGUMENTS")`
 - Per-task verification (inner): `Skill(skill="sp:code-verification", args="verify <wbs> $SHARED_FLAGS")`
 - Shippable gate: once after the batch (same skill § Shippable readiness gate)

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.77",
+    "version": "0.3.80",
     "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/batch-preflight.mjs

@@ -3,6 +3,119 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // plugins/sp/scripts/batch-preflight.ts
+function quickReadiness(input) {
+  const status = (input.status ?? "").toLowerCase();
+  const operation = input.operation;
+  if (operation !== "run" && operation !== "refine" && operation !== "verify") {
+    return {
+      action: "invalid",
+      code: "IV",
+      reason: `quick-readiness: unknown operation '${operation}' (${input.wbs})`
+    };
+  }
+  if (input.filteredCount !== undefined) {
+    if (input.filteredCount < 0) {
+      return {
+        action: "invalid",
+        code: "IV",
+        reason: `quick-readiness: invalid negative filtered count '${input.filteredCount}' (${input.wbs})`
+      };
+    }
+    if (input.filteredCount === 0) {
+      return {
+        action: "skipped",
+        code: "EMPTY",
+        reason: `quick-readiness: empty status-filtered set — nothing to ${operation} (${input.wbs})`
+      };
+    }
+  }
+  if (status === "cancelled" || status === "done") {
+    if (operation === "verify" && input.force === true) {
+      return {
+        action: "runnable",
+        code: "FORCE",
+        reason: `quick-readiness: verify --force re-verification of ${status} task ${input.wbs}`
+      };
+    }
+    return {
+      action: "skipped",
+      code: status === "done" ? "DONE" : "CANCELLED",
+      reason: `quick-readiness: already ${status} — no ${operation} hop (${input.wbs})`
+    };
+  }
+  if (status === "blocked") {
+    return {
+      action: "blocked",
+      code: "BLK",
+      reason: `quick-readiness: blocked — human/handover first (${input.wbs})`
+    };
+  }
+  if (operation === "run" && input.dependencies && input.dependencies.length > 0) {
+    const unmet = input.dependencies.filter((d) => (input.depStatuses?.[d] ?? "missing").toLowerCase() !== "done");
+    if (unmet.length > 0) {
+      return {
+        action: "blocked",
+        code: "DEP",
+        reason: `quick-readiness: unmet deps — ${unmet.join(", ")} (${input.wbs})`,
+        unmetDeps: unmet
+      };
+    }
+  }
+  const required = input.requiredSections ?? [];
+  const present = input.presentSections ?? [];
+  const gaps = required.filter((s) => {
+    const finding = input.sectionFindings?.[s];
+    return !present.includes(s) || finding !== undefined && finding !== "";
+  });
+  if (operation === "refine") {
+    if (status !== "backlog" && status !== "todo") {
+      return {
+        action: "skipped",
+        code: "NONPLAN",
+        reason: `quick-readiness: refine targets backlog/todo only, not '${status}' (${input.wbs})`
+      };
+    }
+    return {
+      action: "runnable",
+      code: "OK",
+      reason: `quick-readiness: refine ready for ${input.wbs} (${gaps.length} planning gap(s) to fill)`
+    };
+  }
+  if (operation === "verify") {
+    if (status !== "testing" && status !== "wip") {
+      return {
+        action: "invalid",
+        code: "NOVERIFY",
+        reason: `quick-readiness: verify needs testing/wip, not '${status}' (${input.wbs})`
+      };
+    }
+    return {
+      action: "runnable",
+      code: "OK",
+      reason: `quick-readiness: verify ready for ${input.wbs}`
+    };
+  }
+  if (status !== "todo" && status !== "wip" && status !== "testing") {
+    return {
+      action: "invalid",
+      code: "NORUN",
+      reason: `quick-readiness: run needs todo/wip/testing, not '${status}' (${input.wbs})`
+    };
+  }
+  if (gaps.length > 0) {
+    return {
+      action: "needs-refinement",
+      code: "REFINE",
+      reason: `quick-readiness: implementation sections incomplete (${input.wbs})`,
+      gaps
+    };
+  }
+  return {
+    action: "runnable",
+    code: "OK",
+    reason: `quick-readiness: run ready for ${input.wbs}`
+  };
+}
 function preflightTask(input) {
   const status = (input.status ?? "").toLowerCase();
   const deps = input.dependencies ?? [];
@@ -72,6 +185,11 @@ function parsePreflightCliArgs(argv) {
   let recovery = false;
   let help = false;
   let json = false;
+  let operation = null;
+  let force = false;
+  let filteredCount = null;
+  let requiredSections = [];
+  let presentSections = [];
   for (let i = 0;i < argv.length; i++) {
     const a = argv[i];
     if (a === "--help" || a === "-h")
@@ -80,7 +198,21 @@ function parsePreflightCliArgs(argv) {
       json = true;
     else if (a === "--recovery")
       recovery = true;
-    else if (a === "--wbs")
+    else if (a === "--force")
+      force = true;
+    else if (a === "--operation") {
+      const v = argv[++i] ?? "";
+      operation = v === "run" || v === "refine" || v === "verify" ? v : null;
+    } else if (a === "--filtered-count") {
+      const v = Number(argv[++i]);
+      filteredCount = Number.isFinite(v) ? v : null;
+    } else if (a === "--required-sections") {
+      const raw = argv[++i] ?? "";
+      requiredSections = raw.length === 0 ? [] : raw.split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (a === "--present-sections") {
+      const raw = argv[++i] ?? "";
+      presentSections = raw.length === 0 ? [] : raw.split(",").map((s) => s.trim()).filter(Boolean);
+    } else if (a === "--wbs")
       wbs = argv[++i] ?? wbs;
     else if (a === "--status")
       status = argv[++i] ?? null;
@@ -96,11 +228,25 @@ function parsePreflightCliArgs(argv) {
       }
     }
   }
-  return { status, deps, depStatuses, wbs, recovery, help, json };
+  return {
+    status,
+    deps,
+    depStatuses,
+    wbs,
+    recovery,
+    help,
+    json,
+    operation,
+    force,
+    filteredCount,
+    requiredSections,
+    presentSections
+  };
 }
 var PREFLIGHT_CLI_USAGE = `Usage:
   bun plugins/sp/scripts/batch-preflight.ts --wbs <wbs> --status <status> \\
     [--deps 0275,0276] [--dep-status 0275:done,0276:todo] [--recovery] [--json]
+  bun plugins/sp/scripts/batch-preflight.ts --operation <run|refine|verify> --wbs <wbs> --status <status>     [--filtered-count <n>] [--required-sections A,B] [--present-sections A,B] [--force] [--json]
 
 Exit: 0 = run (or recovery hint printed); 2 = skip; 1 = usage.`;
 function runPreflightCli(argv) {
@@ -117,6 +263,30 @@ function runPreflightCli(argv) {
 `;
     return { exitCode: 0, stdout: body, stderr: "" };
   }
+  if (args.operation !== null) {
+    const result2 = quickReadiness({
+      wbs: args.wbs,
+      status: args.status,
+      operation: args.operation,
+      dependencies: args.deps,
+      depStatuses: args.depStatuses,
+      ...args.filteredCount !== null ? { filteredCount: args.filteredCount } : {},
+      ...args.requiredSections.length > 0 ? { requiredSections: args.requiredSections } : {},
+      ...args.presentSections.length > 0 ? { presentSections: args.presentSections } : {},
+      ...args.force ? { force: true } : {}
+    });
+    const runnable = result2.action === "runnable" || result2.action === "needs-refinement";
+    if (args.json) {
+      return { exitCode: runnable ? 0 : 2, stdout: `${JSON.stringify(result2, null, 2)}
+`, stderr: "" };
+    }
+    return {
+      exitCode: runnable ? 0 : 2,
+      stdout: `${result2.action}${result2.code ? ` ${result2.code}` : ""}: ${result2.reason}
+`,
+      stderr: ""
+    };
+  }
   const result = preflightTask({
     wbs: args.wbs,
     status: args.status,
@@ -154,6 +324,7 @@ function runPreflightCli(argv) {
 export {
   runPreflightCli,
   recoveryHint,
+  quickReadiness,
   preflightTask,
   parsePreflightCliArgs,
   PREFLIGHT_CLI_USAGE