@gobing-ai/spur 0.3.91 → 0.3.93

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

@@ -13,14 +13,36 @@
  *
  * Modes:
  *   run     reset the attempt counter, truncate the log, execute the gate loop
- *   recheck truncate the log, execute the probe first (probe failure is the gate
- *           failure, the gate loop is skipped), then execute the gate loop
+ *   recheck truncate the log; a full-tier FAIL receipt at the current digest is a
+ *           no-progress skip straight to the FAIL write (0940 R2), otherwise the probe
+ *           runs first (probe failure is the gate failure, the gate loop is skipped),
+ *           then the gate loop
+ *   light   changed-scope tier (task 0939, ADR-124): biome on the changed files,
+ *           per-workspace typecheck, and filename-mapped related tests run inside
+ *           their workspace; merges rows under `tier: light`, soft-fails
+ *   status  print `{reuse, reason}` for the task's receipt and exit 0
  *
  * Retry contract: a failed attempt is retried (up to 5 total attempts) only when its
  * output matches a SQLite busy/locked error; the delay defaults to 10 seconds and is
  * overridable via `SPUR_QUALITY_GATE_RETRY_DELAY_MS` (tests).
  *
- * Environment: `wbs` (required), `qualityGateCmd`, `gateProbeCmd` (recheck), `proofDigest`.
+ * Check receipts (task 0939, ADR-124): `run` writes `.spur/run/<wbs>-check-receipt.json`
+ * (`check-receipt/v1`) when `proofDigest` is set; without a digest no receipt is written and the
+ * log says why. The gate executes `qualityGateCmd` as one unit, so the full-tier receipt carries
+ * a single `test` row for the whole `bun run spur-check` chain (lint | typecheck | test-pre-check
+ * | test | test-post-check). `light` accumulates: a sub-check already PASS in a light receipt at
+ * the same `{id, inputDigest}` is skipped, and light rows never make a receipt reusable for
+ * review — `status` reuses only `PASS` + `tier: full` + matching digest. Reuse observability
+ * (0940 R3): `status` reuse and light accumulation emit `check.reused`, and the no-progress
+ * recheck emits `check.skipped-no-progress`, in the gate log and on stdout (the action result
+ * `data`); both surfaces run this same script, so there is no surface branch.
+ *
+ * Standalone contract: the digest is consumed, never computed — the pipeline captures it with
+ * `proof.fingerprint` into `env.proofDigest`; standalone callers use
+ * `inline-run-setup.ts --fingerprint`. No `@gobing-ai/*` value imports.
+ *
+ * Environment: `wbs` (required), `qualityGateCmd`, `gateProbeCmd` (recheck), `proofDigest`,
+ * `runId` (receipt identity; falls back to `pipeline-<wbs>`).
  * Soft-fail contract: the process always exits 0; the verdict lives in the status file.
  *
  * Node-builtin imports only; pure helpers are exported for unit testing (ADR-065).
@@ -65,6 +87,8 @@ export interface QualityGateEnv {
     qualityGateCmd?: string;
     gateProbeCmd?: string;
     proofDigest?: string;
+    /** Receipt run identity; `pipeline-<wbs>` when absent (task-pipeline convention). */
+    runId?: string;
     [key: string]: string | undefined;
 }
 
@@ -80,6 +104,8 @@ export interface QualityGateResult {
     findingsFile: string;
     statusFile: string;
     attemptFile: string;
+    /** Written only by `run` with `proofDigest` set (0939 R2). */
+    receiptFile?: string;
 }
 
 export function isTransientLock(attemptOutput: string): boolean {
@@ -156,6 +182,323 @@ export function scanCoverageShortfalls(logText: string, threshold: CoverageThres
     return [...shortfalls.values()];
 }
 
+// ─── Check receipts + light tier (task 0939, ADR-124) ───
+
+export const RECEIPT_SCHEMA_VERSION = 'check-receipt/v1';
+
+export type ReceiptTier = 'full' | 'light';
+export type CheckStatus = 'PASS' | 'FAIL';
+/** Frozen non-reuse reasons of `status` mode (0939 R3). */
+export type ReceiptReuseReason = 'missing' | 'failed' | 'stale' | 'light-only';
+
+export interface CheckReceiptRow {
+    id: string;
+    cmd: string;
+    status: CheckStatus;
+    durationMs: number;
+    logPath: string;
+}
+
+export interface CheckReceipt {
+    schemaVersion: 'check-receipt/v1';
+    wbs: string;
+    runId: string;
+    tier: ReceiptTier;
+    inputDigest: string;
+    checks: CheckReceiptRow[];
+    status: CheckStatus;
+    completedAt: string;
+}
+
+export interface ReceiptReadStatus {
+    reuse: boolean;
+    /** `'ok'` only when reuse holds; otherwise one of the frozen reasons. */
+    reason: ReceiptReuseReason | 'ok';
+}
+
+export interface BuildReceiptInput {
+    wbs: string;
+    runId: string;
+    tier: ReceiptTier;
+    inputDigest: string;
+    checks: CheckReceiptRow[];
+    /** ISO-8601 completion timestamp; injected so receipts stay reproducible in tests. */
+    completedAt: string;
+}
+
+/** Stamp `check-receipt/v1`; the overall status derives from the rows (no rows → PASS). */
+export function buildReceipt(input: BuildReceiptInput): CheckReceipt {
+    return {
+        schemaVersion: RECEIPT_SCHEMA_VERSION,
+        wbs: input.wbs,
+        runId: input.runId,
+        tier: input.tier,
+        inputDigest: input.inputDigest,
+        checks: input.checks,
+        status: input.checks.every((row) => row.status === 'PASS') ? 'PASS' : 'FAIL',
+        completedAt: input.completedAt,
+    };
+}
+
+/** Parse a check receipt; `null` when absent, unreadable, or corrupt. */
+function readReceipt(receiptPath: string): CheckReceipt | null {
+    try {
+        return JSON.parse(readFileSync(receiptPath, 'utf8')) as CheckReceipt;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * 0940 R2 — no-progress recheck shape: a full-tier FAIL receipt bound to the current proof-input
+ * digest, i.e. the fix pass changed nothing tracked and the full chain can only reproduce the
+ * failure. `readReceiptStatus` cannot express this decision (a FAIL receipt is `reason: 'failed'`
+ * at every digest), so the two fields are compared directly. Light-tier receipts and any digest
+ * mismatch never skip — the probe and full gate run unchanged (anti-pattern: reusing a light
+ * receipt, or comparing against a digest captured before `test-fix`).
+ */
+export function receiptFailsAtDigest(receipt: CheckReceipt | null, currentDigest: string): boolean {
+    return (
+        receipt !== null &&
+        receipt.schemaVersion === RECEIPT_SCHEMA_VERSION &&
+        receipt.tier === 'full' &&
+        receipt.status === 'FAIL' &&
+        currentDigest.length > 0 &&
+        receipt.inputDigest === currentDigest
+    );
+}
+
+/**
+ * Reuse verdict for `.spur/run/<wbs>-check-receipt.json` against the current proof-input digest.
+ * Evaluated missing → failed → stale → light-only; reuse requires `PASS` + `tier: full` + digest
+ * match, so light rows can never flip a receipt reusable (0939 invariant).
+ */
+export function readReceiptStatus(receiptPath: string, currentDigest: string): ReceiptReadStatus {
+    const receipt = readReceipt(receiptPath);
+    if (receipt === null || receipt.schemaVersion !== RECEIPT_SCHEMA_VERSION) {
+        return { reuse: false, reason: 'missing' };
+    }
+    if (receipt.status !== 'PASS') return { reuse: false, reason: 'failed' };
+    if (currentDigest.length === 0 || receipt.inputDigest !== currentDigest) {
+        return { reuse: false, reason: 'stale' };
+    }
+    if (receipt.tier !== 'full') return { reuse: false, reason: 'light-only' };
+    return { reuse: true, reason: 'ok' };
+}
+
+const TEST_FILE_PATTERN = /\.test\.tsx?$/;
+
+export interface LightScope {
+    files: string[];
+    workspaces: string[];
+    tests: string[];
+}
+
+/**
+ * The bun workspace a changed file belongs to: the shortest directory prefix below the repo root
+ * that holds a package.json (`apps/*`, `packages/*`). Null for root-level files, which no
+ * workspace owns. Pure via the injected `exists` predicate.
+ */
+function workspaceOf(file: string, exists: (p: string) => boolean): string | null {
+    const segments = file.split('/');
+    for (let depth = 1; depth < segments.length; depth++) {
+        const prefix = segments.slice(0, depth).join('/');
+        if (exists(`${prefix}/package.json`)) return prefix;
+    }
+    return null;
+}
+
+/**
+ * Light-tier scope from changed repo-relative paths: every touched workspace plus the related
+ * tests. `<ws>/src/**x.ts` maps to `<ws>/tests/**x.test.ts` by filename (refine decision —
+ * deterministic and cheap; the import graph is not consulted), and a changed `*.test.ts` under a
+ * workspace includes itself. The full tier stays the safety net for everything the mapping
+ * misses. Unmapped-but-existing candidates are dropped by the `exists` check.
+ */
+export function lightScope(changedFiles: string[], exists: (p: string) => boolean = existsSync): LightScope {
+    const files: string[] = [];
+    const workspaces = new Set<string>();
+    const tests = new Set<string>();
+    for (const file of changedFiles) {
+        files.push(file);
+        const workspace = workspaceOf(file, exists);
+        if (workspace === null) continue;
+        workspaces.add(workspace);
+        const rest = file.slice(workspace.length + 1);
+        if (rest.startsWith('src/')) {
+            const candidate = `${workspace}/tests/${rest.slice('src/'.length).replace(/\.tsx?$/, (ext) => `.test${ext}`)}`;
+            if (exists(candidate)) tests.add(candidate);
+        } else if (rest.startsWith('tests/') && TEST_FILE_PATTERN.test(rest)) {
+            tests.add(file);
+        }
+    }
+    return { files, workspaces: [...workspaces].sort(), tests: [...tests].sort() };
+}
+
+export interface LightCheckPlan {
+    id: string;
+    cmd: string;
+}
+
+/** Does the workspace package.json declare a `typecheck` script? (fs default; tests inject.) */
+export function workspaceHasTypecheck(workspace: string): boolean {
+    try {
+        const pkg = JSON.parse(readFileSync(join(workspace, 'package.json'), 'utf8')) as {
+            scripts?: { typecheck?: string };
+        };
+        return typeof pkg.scripts?.typecheck === 'string';
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * The light sub-checks for a scope, in run order: `format-lint:changed` (biome, repo root),
+ * `typecheck:<ws>` per workspace declaring the script, `test:<ws>` per workspace with related
+ * tests. Tests always run through `cd <ws> &&` — never from the repo root, whose bunfig preload
+ * does not apply inside the workspace.
+ */
+export function planLightChecks(
+    scope: LightScope,
+    hasTypecheck: (workspace: string) => boolean = workspaceHasTypecheck,
+): LightCheckPlan[] {
+    const plans: LightCheckPlan[] = [];
+    if (scope.files.length > 0) {
+        plans.push({ id: 'format-lint:changed', cmd: `bunx biome check ${scope.files.join(' ')}` });
+    }
+    for (const workspace of scope.workspaces) {
+        if (hasTypecheck(workspace)) {
+            plans.push({ id: `typecheck:${workspace}`, cmd: `cd ${workspace} && bun run typecheck` });
+        }
+    }
+    const testsByWorkspace = new Map<string, string[]>();
+    for (const test of scope.tests) {
+        const workspace = test.slice(0, test.indexOf('/tests/'));
+        const paths = testsByWorkspace.get(workspace) ?? [];
+        paths.push(test.slice(workspace.length + 1));
+        testsByWorkspace.set(workspace, paths);
+    }
+    for (const [workspace, paths] of testsByWorkspace) {
+        plans.push({ id: `test:${workspace}`, cmd: `cd ${workspace} && bun test ${paths.join(' ')}` });
+    }
+    return plans;
+}
+
+/** Changed paths for the light tier: `git diff --name-only HEAD` plus untracked; existing only. */
+function gitChangedFiles(cwd: string | undefined): string[] {
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+    const changed = new Set<string>();
+    for (const cmd of ['git diff --name-only HEAD', 'git ls-files --others --exclude-standard']) {
+        const result = runShellCommand(cmd, cwd);
+        for (const line of result.output.split('\n')) {
+            const file = line.trim();
+            if (file.length > 0 && existsSync(abs(file))) changed.add(file);
+        }
+    }
+    return [...changed].sort();
+}
+
+function receiptRunId(env: QualityGateEnv): string {
+    return (env.runId ?? '').length > 0 ? (env.runId as string) : `pipeline-${env.wbs}`;
+}
+
+export interface LightGateResult {
+    status: CheckStatus;
+    scope: LightScope;
+    checks: CheckReceiptRow[];
+    logFile: string;
+    receiptFile: string;
+}
+
+/**
+ * Light tier (0939 R1): run the planned sub-checks, merge their rows into the receipt under
+ * `tier: light`, exit soft. A sub-check already PASS in a light receipt at the same
+ * `{id, inputDigest}` is skipped (accumulation, AC1); prior rows whose id left the plan are
+ * dropped with the rest of the old receipt.
+ */
+export function runLightGate(env: QualityGateEnv, options: QualityGateOptions = {}): LightGateResult {
+    const cwd = options.cwd;
+    const abs = (p: string): string => (cwd ? join(cwd, p) : p);
+    const runDir = join('.spur', 'run');
+    mkdirSync(abs(runDir), { recursive: true });
+    const logFile = join(runDir, `${env.wbs}-light-gate.log`);
+    const receiptFile = join(runDir, `${env.wbs}-check-receipt.json`);
+    writeFileSync(abs(logFile), '');
+
+    const digest = env.proofDigest ?? '';
+    const scope = lightScope(gitChangedFiles(cwd), (p) => existsSync(abs(p)));
+    // Bind the fs predicates to the gate cwd, not the process cwd (tests run gates in fixtures).
+    const plans = planLightChecks(scope, (workspace) => workspaceHasTypecheck(abs(workspace)));
+
+    const reusable = new Map<string, CheckReceiptRow>();
+    let preserveFullReceipt = false;
+    if (digest.length > 0) {
+        try {
+            const prior = JSON.parse(readFileSync(abs(receiptFile), 'utf8')) as CheckReceipt;
+            if (prior?.schemaVersion === RECEIPT_SCHEMA_VERSION && prior.inputDigest === digest) {
+                if (prior.tier === 'full') {
+                    // A full-tier receipt at the same digest is boundary evidence read by status
+                    // mode (0940/0943); light must never demote it to a tier-light receipt.
+                    preserveFullReceipt = true;
+                } else {
+                    for (const row of prior.checks ?? []) if (row.status === 'PASS') reusable.set(row.id, row);
+                }
+            }
+        } catch {
+            // No prior receipt (or unreadable) — every planned sub-check runs.
+        }
+    }
+
+    const checks: CheckReceiptRow[] = [];
+    let skipped = 0;
+    for (const plan of plans) {
+        const priorRow = reusable.get(plan.id);
+        if (priorRow !== undefined) {
+            checks.push(priorRow);
+            skipped++;
+            // 0940 R3: accumulation reuse is observable in the gate log and on stdout (the
+            // action result `data`); both surfaces run this same script.
+            const line = `--- light ${plan.id}: check.reused — skipped (PASS at the same input digest)\n`;
+            process.stdout.write(line); // tee: stdout and the log
+            appendFileSync(abs(logFile), line);
+            continue;
+        }
+        const startedAtMs = Date.now();
+        const result = runShellCommand(plan.cmd, cwd);
+        const durationMs = Date.now() - startedAtMs;
+        const status: CheckStatus = result.code === 0 ? 'PASS' : 'FAIL';
+        appendFileSync(abs(logFile), `--- light ${plan.id}: ${status} (${durationMs}ms)\n${result.output}`);
+        checks.push({ id: plan.id, cmd: plan.cmd, status, durationMs, logPath: logFile });
+    }
+
+    const receipt = buildReceipt({
+        wbs: env.wbs,
+        runId: receiptRunId(env),
+        tier: 'light',
+        inputDigest: digest,
+        checks,
+        completedAt: new Date().toISOString(),
+    });
+    if (preserveFullReceipt) {
+        // Light ran for its log; the file keeps the full-tier receipt untouched.
+        appendFileSync(
+            abs(logFile),
+            '--- light receipt: not written — the full-tier receipt at the same input digest is preserved\n',
+        );
+        process.stdout.write(
+            `light gate ${receipt.status} (${scope.files.length} changed files; checks: ${checks.length},` +
+                ` skipped: ${skipped}; receipt: ${receiptFile} preserved (full tier); log: ${logFile})\n`,
+        );
+    } else {
+        writeFileSync(abs(receiptFile), `${JSON.stringify(receipt, null, 2)}\n`);
+        process.stdout.write(
+            `light gate ${receipt.status} (${scope.files.length} changed files; checks: ${checks.length},` +
+                ` skipped: ${skipped}; receipt: ${receiptFile}; log: ${logFile})\n`,
+        );
+    }
+    return { status: receipt.status, scope, checks, logFile, receiptFile };
+}
+
 function retryDelayMs(env: QualityGateEnv): number {
     const raw = Number.parseInt(env[RETRY_DELAY_MS_ENV] ?? '', 10);
     return Number.isFinite(raw) && raw >= 0 ? raw : RETRY_DELAY_MS_DEFAULT;
@@ -201,12 +544,28 @@ export function runQualityGate(
     // run: `echo 0 > "$ATTEMPT_FILE" && : > "$LOG_FILE"`; recheck: truncate only.
     writeFileSync(abs(logFile), '');
     if (mode === 'run') writeFileSync(abs(attemptFile), '0\n');
+    const gateStartedAtMs = Date.now();
 
     let gateRc = 0;
     let gateAttempt = 0;
 
+    // 0940 R2 — no-progress skip, before the probe: a full-tier FAIL receipt at the current
+    // proof-input digest means the fix pass changed nothing tracked, so the full chain can only
+    // reproduce the failure. The marker tees to stdout (the action result `data`) and the log,
+    // then the shared FAIL path below writes findings/status/verdict exactly as a red gate does.
+    // The attempt counter is pipeline-owned (only the test-fix hop increments it; `recheck` never
+    // touches it), so the existing cap still bounds the loop.
+    const noProgressSkip =
+        mode === 'recheck' && receiptFailsAtDigest(readReceipt(abs(rel('-check-receipt.json'))), env.proofDigest ?? '');
+    if (noProgressSkip) {
+        const line = `check.skipped-no-progress — full-tier FAIL receipt at input digest ${env.proofDigest ?? ''}; recheck skipped\n`;
+        process.stdout.write(line); // tee: stdout and the log
+        appendFileSync(abs(logFile), line);
+        gateRc = 1;
+    }
+
     // recheck probe: a probe failure is the gate failure; the gate loop is skipped.
-    if (mode === 'recheck' && (env.gateProbeCmd ?? '').length > 0) {
+    if (mode === 'recheck' && !noProgressSkip && (env.gateProbeCmd ?? '').length > 0) {
         const probe = runShellCommand(env.gateProbeCmd ?? '', cwd);
         writeFileSync(abs(`${logFile}.probe`), probe.output);
         gateRc = probe.code;
@@ -263,15 +622,42 @@ export function runQualityGate(
     writeFileSync(abs(statusFile), `${status}\n`);
     appendFileSync(abs(logFile), `proof-digest: ${env.proofDigest ?? ''}\n`);
 
-    return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile };
+    // 0939 R2: only `run` writes the full-tier receipt, and only with a digest to bind it to.
+    let receiptFile: string | undefined;
+    if (mode === 'run') {
+        if ((env.proofDigest ?? '').length > 0) {
+            receiptFile = join(runDir, `${env.wbs}-check-receipt.json`);
+            const receipt = buildReceipt({
+                wbs: env.wbs,
+                runId: receiptRunId(env),
+                tier: 'full',
+                inputDigest: env.proofDigest ?? '',
+                checks: [
+                    {
+                        id: 'test',
+                        cmd: env.qualityGateCmd ?? '',
+                        status,
+                        durationMs: Date.now() - gateStartedAtMs,
+                        logPath: logFile,
+                    },
+                ],
+                completedAt: new Date().toISOString(),
+            });
+            writeFileSync(abs(receiptFile), `${JSON.stringify(receipt, null, 2)}\n`);
+        } else {
+            appendFileSync(abs(logFile), 'check-receipt: not written — env `proofDigest` is not set\n');
+        }
+    }
+
+    return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile, receiptFile };
 }
 
 export const QUALITY_GATE_USAGE =
-    'usage: quality-gate.ts <run|recheck>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest)';
+    'usage: quality-gate.ts <run|recheck|light|status>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest, runId)';
 
-export function main(argv: string[], env: QualityGateEnv = getEnvVars()): number {
+export function main(argv: string[], env: QualityGateEnv = getEnvVars(), options: QualityGateOptions = {}): number {
     const mode = argv[0];
-    if (mode !== 'run' && mode !== 'recheck') {
+    if (mode !== 'run' && mode !== 'recheck' && mode !== 'light' && mode !== 'status') {
         process.stderr.write(`${QUALITY_GATE_USAGE}\n`);
         return 2;
     }
@@ -279,7 +665,22 @@ export function main(argv: string[], env: QualityGateEnv = getEnvVars()): number
         process.stderr.write('quality-gate: env `wbs` is required\n');
         return 2;
     }
-    runQualityGate(mode, env);
+    if (mode === 'light') {
+        runLightGate(env);
+    } else if (mode === 'status') {
+        const runDir = join(options.cwd ?? '.', '.spur', 'run');
+        const verdict = readReceiptStatus(join(runDir, `${env.wbs}-check-receipt.json`), env.proofDigest ?? '');
+        if (verdict.reuse) {
+            // 0940 R3: reuse is observable in the gate log and on stdout (the action result
+            // `data`); the `{reuse, reason}` JSON stays the last stdout line for machine readers.
+            const line = `check.reused — full-tier receipt reused for input digest ${env.proofDigest ?? ''}\n`;
+            process.stdout.write(line); // tee: stdout and the log
+            appendFileSync(join(runDir, `${env.wbs}-test-gate.log`), line);
+        }
+        process.stdout.write(`${JSON.stringify(verdict)}\n`);
+    } else {
+        runQualityGate(mode, env);
+    }
     return 0;
 }
 

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

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+// plugins/sp/scripts/record-feature-sync.ts
+import { spawnSync } from "node:child_process";
+import { appendFileSync, existsSync } from "node:fs";
+
+// plugins/sp/lib/env.ts
+function getEnvVar(name, fallback) {
+  const raw = process.env[name];
+  return raw === undefined ? fallback : raw;
+}
+
+// plugins/sp/scripts/record-feature-sync.ts
+function resolveSpurBin(argv) {
+  const flag = argv.indexOf("--spur-bin");
+  const value = flag !== -1 ? argv[flag + 1] : undefined;
+  return value ?? getEnvVar("spurBin") ?? "spur";
+}
+function main() {
+  const argv = process.argv.slice(2);
+  const spurBin = resolveSpurBin(argv);
+  const wbs = getEnvVar("wbs") ?? "";
+  if (wbs.length === 0) {
+    console.error("record-feature-sync: env `wbs` is required");
+    process.exit(0);
+  }
+  const reportPath = `.spur/run/${wbs}-report.txt`;
+  const report = (line) => {
+    appendFileSync(reportPath, `${line}
+`);
+  };
+  const show = spawnSync(spurBin, ["task", "show", wbs, "--json"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  let featureId = "";
+  try {
+    const parsed = JSON.parse(show.stdout ?? "");
+    featureId = String(parsed.feature_id ?? parsed.frontmatter?.feature_id ?? "");
+  } catch {
+    featureId = "";
+  }
+  if (featureId.length === 0) {
+    report(`Orphan task ${wbs} — no feature_id linked — proposal: consider linking to a parent feature.`);
+    return;
+  }
+  if (existsSync("plugins/sp/scripts/feature-sync-bounded.ts")) {
+    spawnSync("bun", ["plugins/sp/scripts/feature-sync-bounded.ts", featureId, "--spur-bin", spurBin, "--json"], {
+      stdio: "inherit"
+    });
+    return;
+  }
+  const staged = spawnSync("superskill", ["script", "path", "sp", "feature-sync-bounded.mjs"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  const stagedPath = (staged.stdout ?? "").trim();
+  if (staged.status === 0 && stagedPath.length > 0 && existsSync(stagedPath)) {
+    spawnSync("node", [stagedPath, featureId, "--spur-bin", spurBin, "--json"], { stdio: "inherit" });
+    return;
+  }
+  spawnSync(spurBin, ["feature", "sync", featureId, "--json"], { stdio: "inherit" });
+}
+main();

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

@@ -0,0 +1,84 @@
+/**
+ * record-feature-sync — record-step post-record feature sync owner (tasks 0328 / 0411 / 0931).
+ *
+ * Extracted from the record onEnter shell (0931 R5): ADR-115 caps one workflow shell at 10
+ * logical commands and 800 chars, and the deferFeatureSync guard plus the sync chain can no
+ * longer share it. The pipeline shell resolves this script (in-repo first, superskill-staged
+ * .mjs fallback), notes a deferral, and delegates the rest here:
+ *
+ * - A task with no feature_id gets the orphan proposal note (0328).
+ * - The sync routes through feature-sync-bounded.ts (0411 retry suppression), then the
+ *   superskill-staged module, then bare `spur feature sync` (0328).
+ * - Best-effort by contract: a sync failure never fails the record step.
+ *
+ * Node-builtin imports only (ADR-065): this file is transpiled to a node-runnable .mjs twin
+ * by `superskill script convert`. Env: wbs (required), spurBin (default "spur"); the
+ * `--spur-bin <bin>` argument wins over the env var.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { appendFileSync, existsSync } from 'node:fs';
+import { getEnvVar } from '../lib/env';
+
+function resolveSpurBin(argv: string[]): string {
+    const flag = argv.indexOf('--spur-bin');
+    const value = flag !== -1 ? argv[flag + 1] : undefined;
+    return value ?? getEnvVar('spurBin') ?? 'spur';
+}
+
+function main(): void {
+    const argv = process.argv.slice(2);
+    const spurBin = resolveSpurBin(argv);
+    const wbs = getEnvVar('wbs') ?? '';
+    if (wbs.length === 0) {
+        console.error('record-feature-sync: env `wbs` is required');
+        process.exit(0); // best-effort contract — never fail the record step
+    }
+
+    const reportPath = `.spur/run/${wbs}-report.txt`;
+    const report = (line: string): void => {
+        appendFileSync(reportPath, `${line}\n`);
+    };
+
+    const show = spawnSync(spurBin, ['task', 'show', wbs, '--json'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    let featureId = '';
+    try {
+        const parsed = JSON.parse(show.stdout ?? '') as {
+            feature_id?: string;
+            frontmatter?: { feature_id?: string };
+        };
+        featureId = String(parsed.feature_id ?? parsed.frontmatter?.feature_id ?? '');
+    } catch {
+        featureId = '';
+    }
+
+    if (featureId.length === 0) {
+        report(`Orphan task ${wbs} — no feature_id linked — proposal: consider linking to a parent feature.`);
+        return;
+    }
+
+    if (existsSync('plugins/sp/scripts/feature-sync-bounded.ts')) {
+        spawnSync('bun', ['plugins/sp/scripts/feature-sync-bounded.ts', featureId, '--spur-bin', spurBin, '--json'], {
+            stdio: 'inherit',
+        });
+        return;
+    }
+
+    const staged = spawnSync('superskill', ['script', 'path', 'sp', 'feature-sync-bounded.mjs'], {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const stagedPath = (staged.stdout ?? '').trim();
+    if (staged.status === 0 && stagedPath.length > 0 && existsSync(stagedPath)) {
+        spawnSync('node', [stagedPath, featureId, '--spur-bin', spurBin, '--json'], { stdio: 'inherit' });
+        return;
+    }
+
+    spawnSync(spurBin, ['feature', 'sync', featureId, '--json'], { stdio: 'inherit' });
+    // Falls through with exit 0: a sync failure never fails the record step (0411).
+}
+
+main();