@gobing-ai/spur 0.3.84 → 0.3.86

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.84",
+    "version": "0.3.86",
     "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/daily-summary/daily-summary.mjs

@@ -8,6 +8,15 @@ import { spawn, spawnSync } from "child_process";
 import { existsSync, mkdirSync, readlinkSync, writeFileSync } from "fs";
 import { dirname, isAbsolute, join, resolve } from "path";
 
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVar(name, fallback) {
+  const raw = process.env[name];
+  return raw === undefined ? fallback : raw;
+}
+function getEnvVars() {
+  return process.env;
+}
+
 // plugins/sp/scripts/daily-summary/logger.ts
 var state = { console: true, file: false };
 function emit(stream, message) {
@@ -103,7 +112,7 @@ var defaultProcessSpawner = (cmd, args, env) => {
     try {
       const proc = spawn(cmd, args, {
         stdio: ["ignore", "pipe", "pipe"],
-        env: env ?? process.env
+        env: env ?? getEnvVars()
       });
       const stdoutChunks = [];
       const stderrChunks = [];
@@ -130,7 +139,7 @@ function setProcessSpawner(next) {
 }
 async function getCcusageData(date) {
   try {
-    const env = { ...process.env };
+    const env = { ...getEnvVars() };
     const ccusageCheck = await processSpawner("ccusage", ["--version"], env);
     if (ccusageCheck.exitCode !== 0) {
       return null;
@@ -279,10 +288,10 @@ async function getGitCommits(date) {
   }
 }
 async function promptUser() {
-  if (process.env.SP_DAILY_SUMMARY_NO_PROMPT === "1") {
+  if (getEnvVar("SP_DAILY_SUMMARY_NO_PROMPT") === "1") {
     return { learnings: "", issuesFixed: "", pending: "" };
   }
-  if (process.env.RD3_DAILY_SUMMARY_NO_PROMPT === "1") {
+  if (getEnvVar("RD3_DAILY_SUMMARY_NO_PROMPT") === "1") {
     logger.warn("[deprecate] RD3_DAILY_SUMMARY_NO_PROMPT is deprecated; use SP_DAILY_SUMMARY_NO_PROMPT");
     return { learnings: "", issuesFixed: "", pending: "" };
   }

package/plugins/sp/scripts/daily-summary/daily-summary.ts

@@ -11,6 +11,8 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { getEnvVar, getEnvVars } from '@gobing-ai/ts-utils';
+
 import { logger } from './logger';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -225,7 +227,7 @@ export const defaultProcessSpawner: ProcessSpawner = (cmd, args, env) => {
         try {
             const proc = spawn(cmd, args, {
                 stdio: ['ignore', 'pipe', 'pipe'],
-                env: env ?? process.env,
+                env: env ?? getEnvVars(),
             });
             const stdoutChunks: Buffer[] = [];
             const stderrChunks: Buffer[] = [];
@@ -258,7 +260,7 @@ export function setProcessSpawner(next?: ProcessSpawner): void {
 export async function getCcusageData(date: string): Promise<CcusageData | null> {
     try {
         // Check if ccusage is available
-        const env = { ...process.env };
+        const env = { ...getEnvVars() };
         const ccusageCheck = await processSpawner('ccusage', ['--version'], env);
         if (ccusageCheck.exitCode !== 0) {
             return null;
@@ -473,10 +475,10 @@ export async function getGitCommits(date: string): Promise<GitCommit[]> {
 // ─── User Input ─────────────────────────────────────────────────────────────
 
 export async function promptUser(): Promise<UserAnnotations> {
-    if (process.env.SP_DAILY_SUMMARY_NO_PROMPT === '1') {
+    if (getEnvVar('SP_DAILY_SUMMARY_NO_PROMPT') === '1') {
         return { learnings: '', issuesFixed: '', pending: '' };
     }
-    if (process.env.RD3_DAILY_SUMMARY_NO_PROMPT === '1') {
+    if (getEnvVar('RD3_DAILY_SUMMARY_NO_PROMPT') === '1') {
         logger.warn('[deprecate] RD3_DAILY_SUMMARY_NO_PROMPT is deprecated; use SP_DAILY_SUMMARY_NO_PROMPT');
         return { learnings: '', issuesFixed: '', pending: '' };
     }

package/plugins/sp/scripts/feature-sync-bounded.mjs

@@ -8,6 +8,14 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVar(name, fallback) {
+  const raw = process.env[name];
+  return raw === undefined ? fallback : raw;
+}
+
+// plugins/sp/scripts/feature-sync-bounded.ts
 function classifySyncResult(result) {
   if (result.proposal.gateBlocked === true)
     return "blocked";
@@ -95,8 +103,8 @@ through unchanged.
 
 Exit: 0 = sync handled (applied / no-op / suppressed-blocked / live-blocked).`;
 function defaultSpurBin() {
-  if (process.env.SPUR_BIN)
-    return process.env.SPUR_BIN;
+  if (getEnvVar("SPUR_BIN"))
+    return getEnvVar("SPUR_BIN");
   const local = fileURLToPath(new URL("../../../apps/cli/src/index.ts", import.meta.url));
   if (existsSync(local))
     return `bun ${local}`;

package/plugins/sp/scripts/feature-sync-bounded.ts

@@ -24,6 +24,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 // ── Local types (match packages/app FeatureService shapes; no package import) ───────────
 
@@ -250,7 +251,7 @@ Exit: 0 = sync handled (applied / no-op / suppressed-blocked / live-blocked).`;
  * keeps ad-hoc invocations from silently hitting a stale PATH install.
  */
 export function defaultSpurBin(): string {
-    if (process.env.SPUR_BIN) return process.env.SPUR_BIN;
+    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
     // scripts/ -> plugins/sp/ -> <repo>/apps/cli/src/index.ts (fileURLToPath — raw pathname breaks
     // on %-encoded paths, e.g. spaces in the checkout directory)
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));

package/plugins/sp/scripts/idea-handoff.mjs

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 // @bun
 
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVars() {
+  return process.env;
+}
+
 // plugins/sp/scripts/idea-handoff.ts
 var libUrl = new URL("../lib/idea-handoff.generated.mjs", import.meta.url).href;
 async function loadHandoffLib() {
   return await import(libUrl);
 }
 var IDEA_HANDOFF_USAGE = "usage: idea-handoff.ts  (env: __runId, featureId, optional spurBin) \u2014 no subcommands";
-async function main(argv, env = process.env) {
+async function main(argv, env = getEnvVars()) {
   if (argv.length > 0) {
     process.stderr.write(`${IDEA_HANDOFF_USAGE}
 `);

package/plugins/sp/scripts/idea-handoff.ts

@@ -1,4 +1,7 @@
 #!/usr/bin/env bun
+
+import { getEnvVars } from '@gobing-ai/ts-utils';
+
 /**
  * idea-handoff — portable entrypoint for the idea-pipeline finalization (task 0824, feature I21).
  *
@@ -29,7 +32,7 @@ export async function loadHandoffLib(): Promise<typeof import('../lib/idea-hando
 export const IDEA_HANDOFF_USAGE =
     'usage: idea-handoff.ts  (env: __runId, featureId, optional spurBin) — no subcommands';
 
-export async function main(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
+export async function main(argv: string[], env: NodeJS.ProcessEnv = getEnvVars()): Promise<number> {
     if (argv.length > 0) {
         process.stderr.write(`${IDEA_HANDOFF_USAGE}\n`);
         return 2;

package/plugins/sp/scripts/inline-pipeline-parity-check.ts

@@ -43,7 +43,7 @@ const DOCUMENTED = {
         'run.artifact',
         'command.gate',
     ]),
-    guards: new Set(['always', 'shell']),
+    guards: new Set(['always', 'shell', 'action-ok', 'contract-violation']),
 } as const;
 
 /** Directory of workflow definitions the driver is responsible for. */

package/plugins/sp/scripts/inline-run-setup.ts

@@ -30,16 +30,29 @@
  * Usage:
  *   bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]
  *   bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]
+ *   bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> \
+ *       --status <done|failed|running|paused> --ok <true|false> --duration-ms <n> [--spur-bin <path>]
+ *   bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--spur-bin <path>]
  *
  * The `--fingerprint` mode prints the engine's proof-input digest for the given spec files and
  * creates nothing (task 0862 R5).
  *
+ * The `--action` / `--close` modes are the inline driver's ADR-117 emission boundary (task
+ * 0868): `--action` records one completed action boundary as an `action_runs` row through the
+ * shared `WorkflowActionTraceWriter`, `--close` marks the run row terminal through the same
+ * writer. `--action` is best-effort: a persistence failure is appended to
+ * `.spur/run/<run-id>.log` and the script still exits 0 with `{"ok":false}` on stdout, so
+ * observation never wedges the run. `--close` is NOT best-effort: the run-row closure is
+ * bookkeeping, so a missing run row or a persistence failure exits 1 with a named error.
+ * Exit 2 is reserved for usage errors.
+ *
  * Env: SPUR_BIN
  */
 
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 /** Outcome document written to `.spur/run/<run-id>-inline-setup.json`. */
 interface SetupOutcome {
@@ -63,6 +76,13 @@ function usage(): never {
     console.error(
         '       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]',
     );
+    console.error(
+        '       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> ' +
+            '--status <done|failed|running|paused> --ok <true|false> --duration-ms <n> [--spur-bin <path>]',
+    );
+    console.error(
+        '       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--spur-bin <path>]',
+    );
     process.exit(2);
 }
 
@@ -177,13 +197,133 @@ async function printFingerprint(taskFile: string, featureFile: string, spurBin:
     return 0;
 }
 
+/** Terminal statuses the inline driver may declare when closing its run row. */
+const CLOSE_STATUSES = new Set(['done', 'failed', 'paused']);
+
+/** Action-row statuses the engine's `action_runs.status` column accepts. */
+const ACTION_STATUSES = new Set(['running', 'done', 'failed', 'paused']);
+
+/** Input for the ADR-117 emission modes (`--action` / `--close`). */
+interface TraceModeInput {
+    readonly runId: string;
+    readonly close: boolean;
+    readonly node: string;
+    readonly kind: string;
+    readonly status: string;
+    readonly ok: boolean;
+    readonly durationMs: number;
+    readonly spurBin: string;
+}
+
+/**
+ * Append one emission-failure line to `.spur/run/<run-id>.log` — the run log the inline
+ * driver already owns. Best-effort and synchronous (the process may exit immediately
+ * after), and never throws: an unwritable log must not wedge the run (ADR-117 R3).
+ */
+function appendTraceFailureLine(runId: string, detail: string): void {
+    try {
+        const runDir = join(process.cwd(), '.spur', 'run');
+        if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
+        const safeRunId = runId.replace(/[^A-Za-z0-9._-]/g, '_');
+        const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+        appendFileSync(join(runDir, `${safeRunId}.log`), `[${stamp}] ${detail}\n`);
+    } catch {
+        // Best-effort (R3): the run continues even when the failure cannot be recorded.
+    }
+}
+
+/**
+ * Emit one trace write through the SHARED `WorkflowActionTraceWriter` (task 0868 R5/R7).
+ * `--action` is best-effort: an emission failure is recorded to the run log and reported
+ * on stdout as `{"ok":false}`, and the script exits 0 so the run still reaches its declared
+ * terminal state (R3/R12). `--close` is bookkeeping, so a missing run row or a persistence
+ * failure fails loudly with exit 1 (review findings #1/#4).
+ */
+async function runTraceMode(input: TraceModeInput): Promise<number> {
+    const operation = input.close ? 'run.close' : 'action.finish';
+    const fail = (error: string): number => {
+        appendTraceFailureLine(
+            input.runId,
+            `trace-emission-failed operation=${operation} run=${input.runId}` +
+                `${input.node === '' ? '' : ` node=${input.node}`}${input.kind === '' ? '' : ` kind=${input.kind}`}: ${error}`,
+        );
+        process.stdout.write(`${JSON.stringify({ ok: false, runId: input.runId, error })}\n`);
+        // The action boundary is best-effort (exit 0); the run-row closure fails loudly (exit 1).
+        return input.close ? 1 : 0;
+    };
+
+    const { entry, repoRoot, chain } = resolveAppEntry(input.spurBin);
+    if (entry === null || repoRoot === null) {
+        return fail(
+            `no monorepo checkout of spur is reachable via ${chain} — the shared trace writer ` +
+                'lives in packages/app (point SPUR_BIN at a repo checkout)',
+        );
+    }
+
+    const app = (await import(entry)) as {
+        openInlineRunProjectDb: (workdir: string) => Promise<{ adapter: unknown; close: () => void }>;
+        createWorkflowActionTraceWriter: (
+            db: unknown,
+            recordFailure?: (failure: unknown) => void,
+        ) => {
+            recordAction: (boundary: Record<string, unknown>) => Promise<{ ok: boolean; actionId?: string }>;
+            closeRun: (runId: string, status: string) => Promise<{ ok: boolean }>;
+        };
+    };
+
+    let projectDb: { adapter: unknown; close: () => void } | undefined;
+    try {
+        projectDb = await app.openInlineRunProjectDb(process.cwd());
+        const writer = app.createWorkflowActionTraceWriter(projectDb.adapter, (failure: unknown) => {
+            const detail = failure as { operation?: string; error?: string };
+            appendTraceFailureLine(
+                input.runId,
+                `trace-emission-failed operation=${detail.operation ?? operation} run=${input.runId}: ${detail.error ?? 'unknown error'}`,
+            );
+        });
+        const result = input.close
+            ? await writer.closeRun(input.runId, input.status)
+            : await writer.recordAction({
+                  runId: input.runId,
+                  node: input.node,
+                  kind: input.kind,
+                  status: input.status,
+                  ok: input.ok,
+                  durationMs: input.durationMs,
+              });
+        process.stdout.write(`${JSON.stringify({ ...result, runId: input.runId })}\n`);
+        return 0;
+    } catch (error) {
+        if (input.close && (error as { name?: string }).name === 'RunRowNotFoundError') {
+            // The run row must exist before --close can mark it terminal (R6); a missing row
+            // is a loud correctness failure, not a best-effort emission failure (finding #4).
+            const message = error instanceof Error ? error.message : String(error);
+            appendTraceFailureLine(input.runId, `trace-close-failed run=${input.runId}: ${message}`);
+            process.stdout.write(
+                `${JSON.stringify({ ok: false, runId: input.runId, error: message, code: 'RUN_NOT_FOUND' })}\n`,
+            );
+            return 1;
+        }
+        return fail(error instanceof Error ? error.message : String(error));
+    } finally {
+        projectDb?.close();
+    }
+}
+
 async function main(): Promise<void> {
     let runId = '';
     let file = '';
     let fingerprint = false;
     let taskFile = '';
     let featureFile = '';
-    let spurBin = process.env.SPUR_BIN ?? '';
+    let action = false;
+    let close = false;
+    let node = '';
+    let kind = '';
+    let status = '';
+    let okRaw = '';
+    let durationRaw = '';
+    let spurBin = getEnvVar('SPUR_BIN') ?? '';
     const argv = process.argv.slice(2);
     for (let i = 0; i < argv.length; i++) {
         if (argv[i] === '--run-id') runId = argv[++i] ?? '';
@@ -191,6 +331,13 @@ async function main(): Promise<void> {
         else if (argv[i] === '--fingerprint') fingerprint = true;
         else if (argv[i] === '--task-file') taskFile = argv[++i] ?? '';
         else if (argv[i] === '--feature-file') featureFile = argv[++i] ?? '';
+        else if (argv[i] === '--action') action = true;
+        else if (argv[i] === '--close') close = true;
+        else if (argv[i] === '--node') node = argv[++i] ?? '';
+        else if (argv[i] === '--kind') kind = argv[++i] ?? '';
+        else if (argv[i] === '--status') status = argv[++i] ?? '';
+        else if (argv[i] === '--ok') okRaw = argv[++i] ?? '';
+        else if (argv[i] === '--duration-ms') durationRaw = argv[++i] ?? '';
         else if (argv[i] === '--spur-bin') spurBin = argv[++i] ?? spurBin;
     }
 
@@ -200,6 +347,42 @@ async function main(): Promise<void> {
         if (runId !== '' || file !== '' || taskFile.trim() === '') usage();
         process.exit(await printFingerprint(taskFile, featureFile, spurBin));
     }
+
+    // ADR-117 emission modes (task 0868): the inline driver reports one completed action
+    // boundary, or closes its run row at the declared terminal state. Both share the run-id
+    // filename guard, the app-entry resolution chain and the best-effort failure contract.
+    if (action || close) {
+        if (action && close) usage();
+        if (runId.trim() === '' || status.trim() === '') usage();
+        if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
+        if (close) {
+            if (!CLOSE_STATUSES.has(status)) usage();
+            process.exit(
+                await runTraceMode({
+                    runId,
+                    close: true,
+                    node: '',
+                    kind: '',
+                    status,
+                    ok: true,
+                    durationMs: 0,
+                    spurBin,
+                }),
+            );
+        }
+        if (node.trim() === '' || kind.trim() === '') usage();
+        if (!ACTION_STATUSES.has(status)) usage();
+        // `--ok` and `--duration-ms` are required and exact for the action mode
+        // (review finding #2): a miscased `--ok True` or an omitted `--duration-ms`
+        // must be a loud usage error, never a silently-defaulted `ok=0` /
+        // `duration_ms=0` row.
+        if (okRaw !== 'true' && okRaw !== 'false') usage();
+        const ok = okRaw === 'true';
+        const durationMs = Number(durationRaw);
+        if (durationRaw.trim() === '' || !Number.isFinite(durationMs) || durationMs < 0) usage();
+        process.exit(await runTraceMode({ runId, close: false, node, kind, status, ok, durationMs, spurBin }));
+    }
+
     if (runId.trim() === '' || file.trim() === '') usage();
     if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
 

package/plugins/sp/scripts/pr-reviewing.mjs

@@ -5,8 +5,15 @@
 import { spawnSync } from "child_process";
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVars() {
+  return process.env;
+}
+
+// plugins/sp/scripts/pr-reviewing.ts
 var spawnRunner = (cmd) => {
-  const proc = spawnSync(cmd[0] ?? "", [...cmd.slice(1)], { encoding: "utf8", env: process.env });
+  const proc = spawnSync(cmd[0] ?? "", [...cmd.slice(1)], { encoding: "utf8", env: getEnvVars() });
   return {
     code: proc.status ?? 1,
     stdout: proc.stdout ?? "",

package/plugins/sp/scripts/pr-reviewing.ts

@@ -22,6 +22,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEnvVars } from '@gobing-ai/ts-utils';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -118,7 +119,7 @@ export type CommandRunner = (cmd: readonly string[]) => CmdResult;
 /** Real execution: resolve the binary from PATH and capture its output. The default runner. */
 export const spawnRunner: CommandRunner = (cmd) => {
     // Pass env explicitly so both Node and Bun resolve git/gh against the caller's PATH.
-    const proc = spawnSync(cmd[0] ?? '', [...cmd.slice(1)], { encoding: 'utf8', env: process.env });
+    const proc = spawnSync(cmd[0] ?? '', [...cmd.slice(1)], { encoding: 'utf8', env: getEnvVars() });
     return {
         code: proc.status ?? 1,
         stdout: proc.stdout ?? '',

package/plugins/sp/scripts/quality-gate.mjs

@@ -17,6 +17,13 @@ import {
 } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
+
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVars() {
+  return process.env;
+}
+
+// plugins/sp/scripts/quality-gate.ts
 var MAX_GATE_ATTEMPTS = 5;
 var MAX_FINDINGS = 20;
 var RETRY_DELAY_MS_DEFAULT = 1e4;
@@ -178,7 +185,7 @@ function runQualityGate(mode, env, options = {}) {
   return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile };
 }
 var QUALITY_GATE_USAGE = "usage: quality-gate.ts <run|recheck>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest)";
-function main(argv, env = process.env) {
+function main(argv, env = getEnvVars()) {
   const mode = argv[0];
   if (mode !== "run" && mode !== "recheck") {
     process.stderr.write(`${QUALITY_GATE_USAGE}

package/plugins/sp/scripts/quality-gate.ts

@@ -41,6 +41,7 @@ import {
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { getEnvVars } from '@gobing-ai/ts-utils';
 
 export const MAX_GATE_ATTEMPTS = 5;
 export const MAX_FINDINGS = 20;
@@ -268,7 +269,7 @@ export function runQualityGate(
 export const QUALITY_GATE_USAGE =
     'usage: quality-gate.ts <run|recheck>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest)';
 
-export function main(argv: string[], env: QualityGateEnv = process.env): number {
+export function main(argv: string[], env: QualityGateEnv = getEnvVars()): number {
     const mode = argv[0];
     if (mode !== 'run' && mode !== 'recheck') {
         process.stderr.write(`${QUALITY_GATE_USAGE}\n`);

package/plugins/sp/scripts/surface-drift-inventory.ts

@@ -179,9 +179,6 @@ export function parseInvocation(spanRaw: string): Parsed | null {
         }
     }
     if (nouns.length === 0 && verbs.length === 0 && flags.length === 0) return null;
-    if (process.env.DEBUG_SPANS === '1') {
-        process.stderr.write(`SPAN ${JSON.stringify({ spanRaw, nouns, verbs, flags })}\n`);
-    }
     return { nouns, verbs, flags };
 }
 
@@ -636,9 +633,9 @@ const JSON_PROBES: string[][] = [
     ['feature', 'show', 'I3', '--json'],
     ['rule', 'list', '--json'],
     ['agent', 'list', '--json'],
-    ['agent', 'doctor', 'omp', '--json'],
+    ['agent', 'doctor', 'pi', '--json'],
     ['workflow', 'list', '--json'],
-    ['workflow', 'validate', 'basic.yaml', '--json'],
+    ['workflow', 'validate', 'task-pipeline.yaml', '--json'],
     ['status', '--json'],
     ['projects', 'list', '--json'],
 ];

package/plugins/sp/scripts/task-evidence-precheck.ts

@@ -37,6 +37,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 /** Exact task-content declaration that activates the live-evidence gate (0726 R2). */
 const DECLARATION_PREFIX = 'evidence-channel:';
@@ -58,7 +59,7 @@ function usage(): never {
 }
 
 function defaultSpurBin(): string {
-    if (process.env.SPUR_BIN) return process.env.SPUR_BIN;
+    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
     if (existsSync(local)) return `bun ${local}`;
     return 'spur';

package/plugins/sp/scripts/task-size-precheck.ts

@@ -19,13 +19,14 @@
  *   bun plugins/sp/scripts/task-size-precheck.ts <wbs> [--spur-bin <path>]
  *     [--max-reqs <n>] [--max-plan-items <n>]
  *
- * Env: SPUR_BIN, MAX_IMPLEMENT_REQS, MAX_IMPLEMENT_PLAN_ITEMS
+ * Env: SPUR_BIN (flags own the size ceilings — env overrides removed, task 0902)
  */
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 // ─── Counting (sync with packages/app/src/services/task-size-precheck.ts) ────
 
@@ -88,7 +89,7 @@ function usage(): never {
  * keeps ad-hoc invocations from silently hitting a stale PATH install.
  */
 function defaultSpurBin(): string {
-    if (process.env.SPUR_BIN) return process.env.SPUR_BIN;
+    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
     // scripts/ -> plugins/sp/ -> <repo>/apps/cli/src/index.ts (fileURLToPath — raw pathname breaks
     // on %-encoded paths, e.g. spaces in the checkout directory)
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
@@ -107,8 +108,9 @@ function parseArgs(argv: string[]): {
     // Doubled deterministic ceiling (0723 operator decision): 10 R-items / 16
     // Plan items — keep in sync with DEFAULT_TASK_SIZE_LIMITS in
     // packages/app/src/services/task-size-precheck.ts (asserted by test).
-    let maxReqs = Number(process.env.MAX_IMPLEMENT_REQS) || 10;
-    let maxPlanItems = Number(process.env.MAX_IMPLEMENT_PLAN_ITEMS) || 16;
+    // Overridable per invocation via --max-reqs / --max-plan-items (no env fallback).
+    let maxReqs = 10;
+    let maxPlanItems = 16;
 
     let i = 0;
     while (i < argv.length) {

package/plugins/sp/scripts/verify-answer-lint.ts

@@ -32,6 +32,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 // ─── CLI (same spur-bin chain as task-evidence-precheck.ts) ─────────────────
 
@@ -41,7 +42,7 @@ function usage(): never {
 }
 
 function defaultSpurBin(): string {
-    if (process.env.SPUR_BIN) return process.env.SPUR_BIN;
+    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
     if (existsSync(local)) return `bun ${local}`;
     return 'spur';

package/plugins/sp/scripts/workflow-step-profile.mjs

@@ -5,6 +5,14 @@
 import { spawnSync } from "child_process";
 import { existsSync } from "fs";
 import { fileURLToPath } from "url";
+
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVar(name, fallback) {
+  const raw = process.env[name];
+  return raw === undefined ? fallback : raw;
+}
+
+// plugins/sp/scripts/workflow-step-profile.ts
 var DEFAULT_LAST = 20;
 var DEFAULT_WINDOW_SEC = 300;
 function nearestRankP50(values) {
@@ -168,8 +176,8 @@ function formatStepProfileHuman(profile) {
 `;
 }
 function defaultSpurBin() {
-  if (process.env.SPUR_BIN)
-    return process.env.SPUR_BIN;
+  if (getEnvVar("SPUR_BIN"))
+    return getEnvVar("SPUR_BIN");
   const local = fileURLToPath(new URL("../../../apps/cli/src/index.ts", import.meta.url));
   if (existsSync(local))
     return `bun ${local}`;

package/plugins/sp/scripts/workflow-step-profile.ts

@@ -25,6 +25,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 // ── Input shapes (a subset of the live `spur workflow trace --json` payload) ─────────────
 
@@ -321,7 +322,7 @@ export interface StepProfileCliArgs {
  * --spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`.
  */
 export function defaultSpurBin(): string {
-    if (process.env.SPUR_BIN) return process.env.SPUR_BIN;
+    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
     if (existsSync(local)) return `bun ${local}`;
     return 'spur';