@gobing-ai/spur 0.3.95 → 0.3.97

package/plugins/sp/lib/residual-scan.generated.mjs

@@ -0,0 +1,226 @@
+// packages/app/src/services/residual-scan.ts
+import { join } from "node:path";
+import { createHash } from "node:crypto";
+var MARKER_PATTERN = /TODO|FIXME|XXX|HACK/;
+var PRIORITY_PATTERN = /^P[1-4]/;
+var NONE_FINDING = /^(none( found)?|no (findings?|issues?)( found)?|—)\s*(\(.*\))?\.?$/i;
+var DISPOSITION_HEADER = /^(Disposition|Action|Status|Resolution|Fixed)$/i;
+var RESOLVED_DISPOSITION = /^(FIXED|RESOLVED|DONE)\b/i;
+var DEFERRED_DISPOSITION = /^DEFER(RED)?\b/i;
+var ANCHOR_PATTERN = /[A-Za-z0-9_./-]+\.[A-Za-z]+:[0-9]+/g;
+var RANGE_ANCHOR = /([A-Za-z0-9_./-]+\.[A-Za-z]+):([0-9]+)-[0-9]+/g;
+var EXCLUDED_PATHS = ["docs/tasks", "docs/features/", ".spur/"];
+var ALLOW_PRAGMA = "residual-scan:allow";
+function makeItemId(category, location, text) {
+  const normalized = text.trim().replace(/\s+/g, " ");
+  const hex = createHash("sha256").update(`${location}${normalized}`).digest("hex");
+  return `${category}:${hex.slice(0, 8)}`;
+}
+function normalizeAnchor(location) {
+  return location.replace(RANGE_ANCHOR, "$1:$2");
+}
+function locationOf(locationCell, finding) {
+  const cell = locationCell.trim().replace(/`/g, "");
+  if (cell.length > 0 && cell !== "—")
+    return normalizeAnchor(cell);
+  const backtick = finding.match(/`([^`]+)`/)?.[1];
+  return backtick === undefined ? "" : normalizeAnchor(backtick);
+}
+function parseReviewFindings(taskContent) {
+  const section = taskContent.split(/^### Review\b/m)[1];
+  if (section === undefined)
+    return [];
+  const body = section.split(/^### /m)[0] ?? "";
+  const out = [];
+  const lines = body.split(`
+`);
+  for (let i = 0;i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined || !line.trimStart().startsWith("|"))
+      continue;
+    const header = splitRow(line);
+    const priorityCol = header.findIndex((h) => h.trim() === "Priority");
+    if (priorityCol === -1) {
+      while (i + 1 < lines.length && lines[i + 1]?.trimStart().startsWith("|"))
+        i++;
+      continue;
+    }
+    const findingCol = header.findIndex((h) => h.trim() === "Finding");
+    const locationCol = header.findIndex((h) => h.trim() === "Location");
+    const dispositionCol = header.findIndex((h) => DISPOSITION_HEADER.test(h.trim()));
+    i++;
+    const sep = lines[i];
+    if (sep !== undefined && /^\s*\|[\s:|-]+\|\s*$/.test(sep))
+      i++;
+    while (i < lines.length) {
+      const row = lines[i];
+      if (row === undefined || !row.trimStart().startsWith("|"))
+        break;
+      const cells = splitRow(row);
+      const priority = (cells[priorityCol] ?? "").trim();
+      const finding = (cells[findingCol] ?? "").trim();
+      const disposition = dispositionCol === -1 ? "" : (cells[dispositionCol] ?? "").trim();
+      if (PRIORITY_PATTERN.test(priority) && !NONE_FINDING.test(finding) && finding.length > 0 && !RESOLVED_DISPOSITION.test(disposition)) {
+        const location = locationOf(cells[locationCol] ?? "", finding);
+        out.push(DEFERRED_DISPOSITION.test(disposition) ? { priority, location, text: finding, deferral: disposition } : { priority, location, text: finding });
+      }
+      i++;
+    }
+  }
+  return out;
+}
+function splitRow(line) {
+  return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
+}
+function parseDiffMarkers(addedLines) {
+  return addedLines.filter((l) => !EXCLUDED_PATHS.some((p) => l.file.startsWith(p))).filter((l) => !l.text.includes(ALLOW_PRAGMA)).filter((l) => MARKER_PATTERN.test(l.text)).map((l) => ({ location: `${l.file}:${l.line}`, text: l.text.trim() }));
+}
+function findUncheckedBoxes(taskContent) {
+  const path = "task-file";
+  return taskContent.split(`
+`).map((text, idx) => ({ text: text.trim(), line: idx + 1 })).filter((l) => l.text.startsWith("- [ ]")).map((l) => ({ location: `${path}:${l.line}`, text: l.text }));
+}
+function classify(items, deferrals) {
+  const deferred = new Map(deferrals.map((d) => [d.id, d.reason]));
+  return items.map((item) => {
+    const id = makeItemId(item.category, item.location, item.text);
+    let klass;
+    if (item.category === "review-finding")
+      klass = item.priority?.startsWith("P4") ? "advisory" : "blocking";
+    else if (item.category === "staging-residue")
+      klass = "housekeeping";
+    else
+      klass = "blocking";
+    if (klass === "blocking" && item.category !== "unchecked-box") {
+      const p3Like = item.category === "diff-marker" || item.category === "review-finding" && (item.priority ?? "").startsWith("P3");
+      const reason = deferred.get(id);
+      if (p3Like && reason !== undefined && reason.trim().length > 0)
+        klass = "deferrable";
+    }
+    return {
+      id,
+      category: item.category,
+      class: klass,
+      priority: item.priority,
+      location: item.location,
+      text: item.text
+    };
+  });
+}
+function scanResiduals(inputs) {
+  const { wbs, base, taskContent, addedLines, stagingResidue, deferrals } = inputs;
+  const reviewRows = parseReviewFindings(taskContent);
+  const tableDeferrals = reviewRows.flatMap((r) => r.deferral === undefined ? [] : [{ id: makeItemId("review-finding", r.location, r.text), reason: r.deferral }]);
+  const review = reviewRows.map((r) => ({
+    category: "review-finding",
+    priority: r.priority,
+    location: r.location,
+    text: r.text
+  }));
+  const markers = base === null ? [] : parseDiffMarkers(addedLines).map((m) => ({
+    category: "diff-marker",
+    location: m.location,
+    text: m.text
+  }));
+  const boxes = findUncheckedBoxes(taskContent).map((b) => ({
+    category: "unchecked-box",
+    location: b.location,
+    text: b.text
+  }));
+  const residue = stagingResidue.map((p) => ({
+    category: "staging-residue",
+    location: p,
+    text: p
+  }));
+  const items = classify([...review, ...markers, ...boxes, ...residue], [...tableDeferrals, ...deferrals]);
+  const counts = { blocking: 0, deferrable: 0, advisory: 0, housekeeping: 0 };
+  for (const item of items)
+    counts[item.class]++;
+  return {
+    wbs,
+    base,
+    scanned: {
+      "review-finding": true,
+      "diff-marker": base !== null,
+      "unchecked-box": true,
+      "staging-residue": true
+    },
+    items,
+    counts
+  };
+}
+function blockingAnchors(items) {
+  const anchors = new Set;
+  for (const item of items) {
+    if (item.class !== "blocking")
+      continue;
+    for (const m of normalizeAnchor(item.location).matchAll(ANCHOR_PATTERN))
+      anchors.add(m[0]);
+  }
+  return [...anchors];
+}
+function foldVerdict(verdict, scan, existingFindings, maxFindings = 20) {
+  const blocking = scan.items.filter((i) => i.class === "blocking");
+  const deferrable = scan.items.filter((i) => i.class === "deferrable");
+  const evidence = `blocking=${blocking.length} deferrable=${deferrable.length} advisory=${scan.counts.advisory} housekeeping=${scan.counts.housekeeping}` + (blocking.length > 0 ? `; blocking ids: ${blocking.map((i) => i.id).join(", ")}` : "") + (deferrable.length > 0 ? `; deferrable ids: ${deferrable.map((i) => i.id).join(", ")}` : "");
+  const checks = verdict.checks.filter((c) => c.name !== "residual-sweep");
+  checks.push({ name: "residual-sweep", status: blocking.length > 0 ? "fail" : "pass", evidence });
+  const merged = new Set([
+    ...existingFindings.split(/\s+/).filter((a) => a.length > 0),
+    ...blockingAnchors(scan.items)
+  ]);
+  const findings = [...merged].sort().slice(0, maxFindings).map((a) => `${a} `).join("");
+  let verdictStatus = verdict.verdict === "PASS" ? "PASS" : "FAIL";
+  if (verdict.verdict === "PARTIAL")
+    verdictStatus = "PARTIAL";
+  else if (verdict.verdict === "FAIL")
+    verdictStatus = "FAIL";
+  else if (blocking.length > 0)
+    verdictStatus = "PARTIAL";
+  return { verdict: verdictStatus, checks, findings };
+}
+function renderReport(wbs, items, attemptCount) {
+  const lines = [
+    `# Residual report — ${wbs}`,
+    "",
+    `Attempt: ${attemptCount}`,
+    "",
+    "| Category | Class | Location | Text |",
+    "| --- | --- | --- | --- |"
+  ];
+  for (const item of items) {
+    lines.push(`| ${item.category} | ${item.class} | ${item.location} | ${item.text.replace(/\|/g, "\\|")} |`);
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+function recordedVerdictPath(runDir, wbs, fs) {
+  const evidence = join(runDir, "..", "memory", "evidence");
+  const durable = join(evidence, `${wbs}-verdict.json`);
+  for (const path of [join(runDir, ".."), join(evidence, ".."), evidence, durable]) {
+    try {
+      if (fs.lstatSync(path).isSymbolicLink())
+        throw new Error(`residual-scan: symlink evidence path: ${path}`);
+    } catch (error) {
+      if (error.code !== "ENOENT")
+        throw error;
+    }
+  }
+  return fs.existsSync(durable) ? durable : join(runDir, `${wbs}-verdict.json`);
+}
+export {
+  scanResiduals,
+  renderReport,
+  recordedVerdictPath,
+  parseReviewFindings,
+  parseDiffMarkers,
+  normalizeAnchor,
+  makeItemId,
+  locationOf,
+  foldVerdict,
+  findUncheckedBoxes,
+  classify,
+  blockingAnchors,
+  ALLOW_PRAGMA
+};

package/plugins/sp/lib/spur-bin.ts

@@ -0,0 +1,36 @@
+/**
+ * Shared spur-invocation helper for the sp plugin scripts (task 1007 R9, RF-architect-001).
+ *
+ * `spurCommand` and `defaultSpurBin` moved verbatim from `wrapup-steps.ts` and
+ * `workflow-step-profile.ts` so every surviving plugin script imports one copy (imported by
+ * relative path like `lib/env.ts`, so the standalone contract holds; not an app bundle
+ * because it carries no Spur-domain logic). Node/bun builtins and the vendored `./env`
+ * gateway only — bundled standalone by `superskill install`, so no `@gobing-ai/*` value
+ * imports (task 0669).
+ */
+
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { getEnvVar } from './env';
+
+/** `spurBin` splits on whitespace into a command plus prefix args (so `bun x.ts` works). */
+export function spurCommand(spurBin: string | undefined): { cmd: string; prefix: string[] } {
+    const parts = (spurBin ?? 'spur')
+        .trim()
+        .split(/\s+/)
+        .filter((p) => p.length > 0);
+    return { cmd: parts[0] ?? 'spur', prefix: parts.slice(1) };
+}
+
+/**
+ * Resolve the spur CLI monorepo-safely (twin-safe resolution:
+ * self-contained and no plugin script imports another):
+ * --spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`.
+ */
+export function defaultSpurBin(): string {
+    const fromEnv = getEnvVar('SPUR_BIN');
+    if (fromEnv) return fromEnv;
+    const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));
+    if (existsSync(local)) return `bun ${local}`;
+    return 'spur';
+}

package/plugins/sp/lib/step-profile.generated.d.mts

@@ -0,0 +1,71 @@
+/**
+ * GENERATED by scripts/commands/bundle-plugin-lib.ts — do not edit.
+ * Source of truth: packages/app/src/workflow/step-profile.ts (task 1005 R1).
+ */
+export declare interface ActionCostLike {
+    cacheHit: number | null;
+}
+export declare interface ActionCostAttributionLike {
+    exact: ActionCostLike | null;
+    estimated: ActionCostLike | null;
+}
+export declare interface TraceActionEvent {
+    kind: string;
+    node?: string;
+    actionKind?: string;
+    durationMs?: number | null;
+    startedAt?: string | null;
+    completedAt?: string | null;
+    invocation?: Record<string, string | number | boolean> | null;
+    cost?: ActionCostAttributionLike | null;
+}
+export declare interface StepProfileRun {
+    runId: string;
+    events: readonly TraceActionEvent[];
+}
+export declare interface TraceRunEntry {
+    runId: string;
+    isDryRun?: boolean;
+    status?: string;
+    workflowName?: string;
+}
+export declare type SessionMode = 'fresh' | 'resumed' | 'mixed';
+export declare interface StepProfileExecution {
+    runId: string;
+    node: string;
+    actionKind: string;
+    durationMs: number | null;
+    idleGapMs: number | null;
+    session: 'fresh' | 'resumed' | null;
+    cacheHit: number | null;
+}
+export declare interface StepProfileRow {
+    node: string;
+    actionKind: string;
+    runs: number;
+    executions: number;
+    durationMs: { p50: number | null; max: number | null };
+    idleGapMs: { p50: number | null };
+    session: SessionMode | null;
+    cacheHit: { p50: number | null; known: number; of: number };
+    flags: string[];
+}
+export declare interface StepProfile {
+    workflow: string;
+    windowSec: number;
+    sampledRuns: number;
+    rows: StepProfileRow[];
+}
+export declare const DEFAULT_LAST: number;
+export declare const DEFAULT_WINDOW_SEC: number;
+export declare function nearestRankP50(values: readonly number[]): number | null;
+export declare function extractExecutions(runId: string, events: readonly TraceActionEvent[]): StepProfileExecution[];
+export declare function rowFlags(row: StepProfileRow, windowSec: number): string[];
+export declare function buildRows(executions: readonly StepProfileExecution[], windowSec: number): StepProfileRow[];
+export declare function buildStepProfile(input: {
+    workflow: string;
+    windowSec: number;
+    runs: readonly StepProfileRun[];
+}): StepProfile;
+export declare function nonDryRuns(entries: readonly TraceRunEntry[]): TraceRunEntry[];
+export declare function formatStepProfileHuman(profile: StepProfile): string;

package/plugins/sp/lib/step-profile.generated.mjs

@@ -0,0 +1,174 @@
+// packages/app/src/workflow/step-profile.ts
+var DEFAULT_LAST = 20;
+var DEFAULT_WINDOW_SEC = 300;
+function nearestRankP50(values) {
+  if (values.length === 0)
+    return null;
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.ceil(sorted.length / 2) - 1] ?? null;
+}
+function numeric(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function msBetween(from, to) {
+  if (typeof from !== "string" || typeof to !== "string")
+    return null;
+  const start = Date.parse(from);
+  const end = Date.parse(to);
+  if (!Number.isFinite(start) || !Number.isFinite(end))
+    return null;
+  return end - start;
+}
+function sessionOf(event) {
+  const value = event.invocation?.continue;
+  if (value === true)
+    return "resumed";
+  if (value === false)
+    return "fresh";
+  return null;
+}
+function cacheHitOf(event) {
+  return numeric(event.cost?.exact?.cacheHit);
+}
+function startKey(event) {
+  const parsed = typeof event.startedAt === "string" ? Date.parse(event.startedAt) : Number.NaN;
+  return Number.isFinite(parsed) ? parsed : Number.POSITIVE_INFINITY;
+}
+function extractExecutions(runId, events) {
+  const actions = events.filter((e) => e.kind === "action").sort((a, b) => {
+    const left = startKey(a);
+    const right = startKey(b);
+    return left === right ? 0 : left - right;
+  });
+  const executions = [];
+  for (const [index, event] of actions.entries()) {
+    const previous = index === 0 ? undefined : actions[index - 1];
+    executions.push({
+      runId,
+      node: event.node ?? "",
+      actionKind: event.actionKind ?? "",
+      durationMs: numeric(event.durationMs),
+      idleGapMs: msBetween(previous?.completedAt, event.startedAt),
+      session: sessionOf(event),
+      cacheHit: cacheHitOf(event)
+    });
+  }
+  return executions;
+}
+function foldSession(executions) {
+  const known = new Set(executions.map((e) => e.session).filter((s) => s !== null));
+  if (known.size === 0)
+    return null;
+  if (known.size === 1)
+    return [...known][0] ?? null;
+  return "mixed";
+}
+function rowFlags(row, windowSec) {
+  const wMs = windowSec * 1000;
+  const flags = [];
+  const agentRun = row.actionKind === "agent.run";
+  const resumed = row.session === "resumed" || row.session === "mixed";
+  const p50 = row.durationMs.p50;
+  if (!agentRun && p50 !== null && p50 > wMs)
+    flags.push("step-over-window");
+  const idle = row.idleGapMs.p50;
+  if (agentRun && resumed && idle !== null && idle > wMs)
+    flags.push("resume-after-idle");
+  const hit = row.cacheHit.p50;
+  if (agentRun && resumed && row.cacheHit.known > 0 && hit !== null && hit < 0.5)
+    flags.push("resume-cold-cache");
+  if (agentRun && p50 !== null && p50 > 2 * wMs)
+    flags.push("agent-run-over-2w");
+  return flags;
+}
+function buildRows(executions, windowSec) {
+  const grouped = new Map;
+  for (const execution of executions) {
+    const key = `${execution.node}\x00${execution.actionKind}`;
+    const bucket = grouped.get(key);
+    if (bucket === undefined)
+      grouped.set(key, [execution]);
+    else
+      bucket.push(execution);
+  }
+  const rows = [];
+  for (const bucket of grouped.values()) {
+    const first = bucket[0];
+    if (first === undefined)
+      continue;
+    const durations = bucket.map((e) => e.durationMs).filter((d) => d !== null);
+    const gaps = bucket.map((e) => e.idleGapMs).filter((g) => g !== null);
+    const hits = bucket.map((e) => e.cacheHit).filter((h) => h !== null);
+    const row = {
+      node: first.node,
+      actionKind: first.actionKind,
+      runs: new Set(bucket.map((e) => e.runId)).size,
+      executions: bucket.length,
+      durationMs: {
+        p50: nearestRankP50(durations),
+        max: durations.length === 0 ? null : Math.max(...durations)
+      },
+      idleGapMs: { p50: nearestRankP50(gaps) },
+      session: first.actionKind === "agent.run" ? foldSession(bucket) : null,
+      cacheHit: {
+        p50: nearestRankP50(hits),
+        known: hits.length,
+        of: bucket.length
+      },
+      flags: []
+    };
+    row.flags = rowFlags(row, windowSec);
+    rows.push(row);
+  }
+  return rows.sort((a, b) => a.node === b.node ? a.actionKind.localeCompare(b.actionKind) : a.node.localeCompare(b.node));
+}
+function buildStepProfile(input) {
+  const executions = input.runs.flatMap((run) => extractExecutions(run.runId, run.events));
+  return {
+    workflow: input.workflow,
+    windowSec: input.windowSec,
+    sampledRuns: input.runs.length,
+    rows: buildRows(executions, input.windowSec)
+  };
+}
+function nonDryRuns(entries) {
+  return entries.filter((e) => e.isDryRun !== true && typeof e.runId === "string" && e.runId.length > 0);
+}
+function seconds(value) {
+  return value === null ? "?" : `${(value / 1000).toFixed(1)}s`;
+}
+function ratio(value) {
+  return value === null ? "?" : value.toFixed(2);
+}
+function formatStepProfileHuman(profile) {
+  const lines = [
+    `step profile — ${profile.workflow} (window ${profile.windowSec}s, ${profile.sampledRuns} sampled runs)`
+  ];
+  for (const row of profile.rows) {
+    lines.push([
+      row.node.padEnd(20),
+      row.actionKind.padEnd(14),
+      `${row.runs}/${row.executions}`.padEnd(8),
+      `p50=${seconds(row.durationMs.p50)}`.padEnd(12),
+      `max=${seconds(row.durationMs.max)}`.padEnd(12),
+      `idle=${seconds(row.idleGapMs.p50)}`.padEnd(12),
+      `session=${row.session ?? "?"}`.padEnd(15),
+      `cacheHit=${ratio(row.cacheHit.p50)} (${row.cacheHit.known}/${row.cacheHit.of})`.padEnd(20),
+      `flags=${row.flags.length === 0 ? "-" : row.flags.join(",")}`
+    ].join(" "));
+  }
+  return `${lines.join(`
+`)}
+`;
+}
+export {
+  rowFlags,
+  nonDryRuns,
+  nearestRankP50,
+  formatStepProfileHuman,
+  extractExecutions,
+  buildStepProfile,
+  buildRows,
+  DEFAULT_WINDOW_SEC,
+  DEFAULT_LAST
+};

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.95",
+    "version": "0.3.97",
     "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

@@ -50,11 +50,11 @@ 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-job-dump, dev-daily, dev-changelog, dev-refresh, rule-add, rule-refine, workflow-add, workflow-refine, spur-init]
     stages: [changelog]
   - id: coder
     tier: standard
-    commands: [dev-run, dev-unit, dev-debug, dev-simplify, dev-fixall, dev-reverse, dev-wrap, dev-wrapall, dev-gtd]
+    commands: [dev-run, dev-unit, dev-debug, dev-simplify, dev-fixall, dev-fixgha, dev-reverse, dev-wrap, dev-wrapall, dev-gtd]
     stages: [implement, test, wrap]
   - id: reviewer
     tier: capable-1
@@ -62,7 +62,7 @@ roles:
     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-feature-change]
+    commands: [dev-plan, dev-refine, dev-brainstorm, dev-idea, dev-runall, dev-parallel, dev-next, dev-job-resume, dev-arch, dev-refineall, dev-find-next, dev-feature-change]
     stages: [plan, refine, brainstorm]
 ```
 

package/plugins/sp/scripts/feature-verification-steps.mjs

@@ -10,7 +10,9 @@ import {
   openSync,
   readdirSync,
   readFileSync,
+  realpathSync,
   renameSync,
+  statSync,
   writeFileSync
 } from "fs";
 import { join } from "path";
@@ -74,6 +76,17 @@ function findFeatureFile(featureDir, featureId) {
   return name === undefined ? undefined : join(featureDir, name);
 }
 var nodeFsShim = {
+  realPath: realpathSync,
+  readDir: readdirSync,
+  stat: (path) => {
+    try {
+      return statSync(path);
+    } catch (error) {
+      if (error.code === "ENOENT")
+        return null;
+      throw error;
+    }
+  },
   ensureDir: (dir) => {
     mkdirSync(dir, { recursive: true });
   },
@@ -123,7 +136,7 @@ async function verify(featureId, runId, cmdOverride, spurBin, mode) {
   try {
     await new mod.ArtifactDao(db.adapter).record({
       runId,
-      path: join(runDir, `${runId}-feature-verification.json`),
+      path: mod.featureReceiptPaths(runDir, featureId, runId).runScoped,
       kind: "feature-verification"
     });
   } finally {

package/plugins/sp/scripts/feature-verification-steps.ts

@@ -33,7 +33,9 @@ import {
     openSync,
     readdirSync,
     readFileSync,
+    realpathSync,
     renameSync,
+    statSync,
     writeFileSync,
 } from 'node:fs';
 import { join } from 'node:path';
@@ -45,6 +47,7 @@ const SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 
 /** Shape of the generated inline bundle / repo app source this script consumes. */
 interface VerificationModule {
+    featureReceiptPaths: typeof import('../../../packages/app/src/workflow/feature-verification-receipt')['featureReceiptPaths'];
     startFeatureVerificationReceipt: typeof import('../../../packages/app/src/workflow/feature-verification-receipt')['startFeatureVerificationReceipt'];
     completeFeatureVerificationReceipt: typeof import('../../../packages/app/src/workflow/feature-verification-receipt')['completeFeatureVerificationReceipt'];
     captureFeatureReceiptDigest: typeof import('../../../packages/app/src/workflow/feature-verification-receipt')['captureFeatureReceiptDigest'];
@@ -143,6 +146,16 @@ function findFeatureFile(featureDir: string, featureId: string): string | undefi
 // FileSystem port; only ensureDir/writeFile/rename are exercised on the
 // start/complete paths. Swap to createNodeFileSystem if more surface is needed.
 const nodeFsShim = {
+    realPath: realpathSync,
+    readDir: readdirSync,
+    stat: (path: string) => {
+        try {
+            return statSync(path);
+        } catch (error) {
+            if ((error as { code?: string }).code === 'ENOENT') return null;
+            throw error;
+        }
+    },
     ensureDir: (dir: string) => {
         mkdirSync(dir, { recursive: true });
     },
@@ -209,7 +222,7 @@ async function verify(
     try {
         await new mod.ArtifactDao(db.adapter as never).record({
             runId,
-            path: join(runDir, `${runId}-feature-verification.json`),
+            path: mod.featureReceiptPaths(runDir, featureId, runId).runScoped,
             kind: 'feature-verification',
         });
     } finally {