@gobing-ai/spur 0.3.91 → 0.3.92

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.91",
+    "version": "0.3.92",
     "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/environment-lens.md

@@ -24,7 +24,7 @@ field named by each column — never as a history-anatomy `category` (that vocab
 | automated checks | `reliability` | `automated-checks` | `environment`; action is a gate, not prose |
 | coding standards | `workflow` | `coding-standards` | `environment`; owner surface is review, never implementer |
 | AGENTS.md placement | `workflow` | `agents-md-placement` | `environment`; action = move to skill/reference/check |
-| tool economy | `performance` | `tool-economy` | existing cache-health P3; `environment` when the tool itself is the waste |
+| tool economy | `performance` | `tool-economy` | existing evidence-based reuse-observation P3 (task 0913); `environment` when the tool itself is the waste |
 | no-ops | `workflow` | `no-ops` | `environment`; `file:line` of the dead instruction |
 | information access | `telemetry` | `information-access` | existing chained-step `~unknown` P3; `environment` when access is missing |
 

package/plugins/sp/scripts/dogfood-testing/validate-report.mjs

@@ -25,6 +25,135 @@ function declaredExecutedSteps(markdown) {
   const match = markdown.match(/\*\*Steps:\*\*\s*\d+\s+derived,\s*(\d+)\s+executed/);
   return match ? Number.parseInt(match[1], 10) : null;
 }
+var UNKNOWN_CELLS = new Set(["~unknown", "unknown", "—", "-", "?", "n/a", "~n/a"]);
+var CACHE_SHARE_TOLERANCE = 1;
+function sectionBody(markdown, headingRe) {
+  const heading = markdown.match(headingRe);
+  if (!heading || heading.index === undefined)
+    return null;
+  const after = markdown.slice(heading.index + heading[0].length);
+  const nextHeading = after.search(/^###? /m);
+  return nextHeading === -1 ? after : after.slice(0, nextHeading);
+}
+function parseTokensLine(line) {
+  const match = line.match(/~(?<total>n\/a|\d+)\s+total\s*\|\s*~(?<cached>n\/a|\d+)\s+cached(?:\s*\(\s*~?(?<pct>n\/a|\d+(?:\.\d+)?)%\s*hit rate\))?/i);
+  if (!match)
+    return null;
+  const num = (v) => v === undefined ? null : v === "n/a" ? "n/a" : Number.parseInt(v, 10);
+  return { total: num(match.groups?.total), cached: num(match.groups?.cached), pct: num(match.groups?.pct) };
+}
+function parseTokenCell(cell) {
+  const t = cell.trim();
+  if (UNKNOWN_CELLS.has(t))
+    return null;
+  const m = t.match(/~?(\d+)/);
+  return m ? Number.parseInt(m[1], 10) : null;
+}
+function parsePctCell(cell) {
+  const t = cell.trim();
+  if (UNKNOWN_CELLS.has(t))
+    return null;
+  const m = t.match(/(\d+(?:\.\d+)?)\s*%/);
+  return m ? Number.parseFloat(m[1]) : null;
+}
+function ledgerCostRows(markdown) {
+  const body = sectionBody(markdown, /^### 3\. Monitor Ledger\s*$/m);
+  if (body === null)
+    return [];
+  return body.split(`
+`).filter((line) => line.trim().startsWith("|")).filter((line) => !/^\|[\s:|-]+\|?\s*$/.test(line.trim())).filter((line) => !/^\|\s*`?drift:/.test(line.trim())).slice(1).map((line) => {
+    const cells = line.split("|").map((c) => c.trim()).filter((c, i, a) => !(i === 0 && c === "") && !(i === a.length - 1 && c === ""));
+    const freshCell = cells[5] ?? "";
+    const cachedCell = cells[6] ?? "";
+    return {
+      step: cells[0] ?? "",
+      fresh: parseTokenCell(freshCell),
+      cached: parseTokenCell(cachedCell),
+      cachePct: parsePctCell(cells[7] ?? ""),
+      unknownCell: UNKNOWN_CELLS.has(freshCell) || UNKNOWN_CELLS.has(cachedCell)
+    };
+  });
+}
+function validateCostEvidence(markdown, errors) {
+  const costBlock = sectionBody(markdown, /^#### Cost\s*$/m);
+  if (costBlock === null) {
+    errors.push("missing_cost_block");
+    return;
+  }
+  for (const field of ["Ledger estimate", "Method", "Meter"]) {
+    if (!costBlock.includes(`**${field}:**`))
+      errors.push(`missing_cost_field:${field}`);
+  }
+  const ledgerLine = costBlock.split(`
+`).find((l) => l.includes("**Ledger estimate:**")) ?? "";
+  const costTotals = parseTokensLine(ledgerLine);
+  if (ledgerLine !== "" && costTotals === null)
+    errors.push("malformed_cost_line");
+  const footerLine = markdown.split(`
+`).find((l) => l.trim().startsWith("Tokens:"));
+  const footerTotals = footerLine ? parseTokensLine(footerLine) : null;
+  if (footerLine !== undefined && footerTotals === null)
+    errors.push("malformed_footer");
+  if (footerLine === undefined && markdown.includes("── Dogfood Summary ──")) {
+    errors.push("missing_footer_tokens");
+  }
+  const pctScopes = [costBlock, footerLine ?? ""];
+  for (const row of ledgerCostRows(markdown)) {
+    if (row.cachePct !== null)
+      pctScopes.push(`${row.cachePct}%`);
+  }
+  for (const scope of pctScopes) {
+    for (const m of scope.matchAll(/(\d+(?:\.\d+)?)\s*%/g)) {
+      const pct = Number.parseFloat(m[1]);
+      if (pct < 0 || pct > 100)
+        errors.push(`impossible_percentage:${m[0].trim()}`);
+    }
+  }
+  const rows = ledgerCostRows(markdown);
+  for (const row of rows) {
+    if (row.unknownCell && row.cachePct !== null)
+      errors.push("unknown_row_with_numeric_cache");
+  }
+  for (const row of rows) {
+    if (row.fresh === null || row.cached === null || row.cachePct === null)
+      continue;
+    const basis = row.fresh + row.cached;
+    if (basis === 0)
+      continue;
+    const expected = Math.round(row.cached / basis * 100);
+    if (Math.abs(row.cachePct - expected) > CACHE_SHARE_TOLERANCE) {
+      errors.push(`cache_pct_mismatch:${row.step}_expected_${expected}`);
+    }
+  }
+  const observable = rows.filter((r) => r.fresh !== null && r.cached !== null);
+  const sumFresh = observable.reduce((acc, r) => acc + (r.fresh ?? 0), 0);
+  const sumCached = observable.reduce((acc, r) => acc + (r.cached ?? 0), 0);
+  const checkTotals = (label, totals) => {
+    if (totals === null)
+      return;
+    if (observable.length > 0) {
+      const expectedTotal = sumFresh + sumCached;
+      if (typeof totals.total === "number" && totals.total !== expectedTotal) {
+        errors.push(`cost_total_mismatch:${label}_expected_${expectedTotal}`);
+      }
+      if (typeof totals.cached === "number" && totals.cached !== sumCached) {
+        errors.push(`cost_total_mismatch:${label}_cached_expected_${sumCached}`);
+      }
+      const expectedPct = expectedTotal > 0 ? Math.round(sumCached / expectedTotal * 100) : null;
+      if (expectedPct !== null) {
+        if (totals.pct === "n/a" || totals.pct === null) {
+          errors.push(`missing_cache_share:${label}`);
+        } else if (typeof totals.pct === "number" && Math.abs(totals.pct - expectedPct) > CACHE_SHARE_TOLERANCE) {
+          errors.push(`cache_share_mismatch:${label}_expected_${expectedPct}`);
+        }
+      }
+    } else if (typeof totals.total === "number" || typeof totals.cached === "number" || typeof totals.pct === "number") {
+      errors.push(`fabricated_cache_share:${label}`);
+    }
+  };
+  checkTotals("cost", costTotals);
+  checkTotals("footer", footerTotals);
+}
 function validateReport(markdown) {
   const errors = [];
   if (!markdown.includes("── Dogfood Summary ──"))
@@ -56,6 +185,7 @@ function validateReport(markdown) {
       errors.push("ledger_cardinality");
     }
   }
+  validateCostEvidence(markdown, errors);
   return { ok: errors.length === 0, errors };
 }
 function parseValidateCliArgs(argv) {
@@ -83,6 +213,12 @@ Exit codes:
   2  validation failed (errors on stdout / --json)
   1  usage error
 
+Cost evidence (task 0913): a complete report must carry the Cost block
+(Ledger estimate / Method / Meter), percentages within 0..100, totals equal to
+the ledger sums of observable rows (fresh + cached), and 'n/a' (never a
+fabricated number) when no observable rows exist. Display-rounding tolerance
+for the cache share is ±1 percentage point.
+
 Phase 4 finalize MUST run this before status: complete (task 0278 R6).
 On exit 2: set status: aborted and list error codes under #### Unresolved.`;
 function runValidateCli(argv, readFile) {

package/plugins/sp/scripts/dogfood-testing/validate-report.ts

@@ -5,8 +5,13 @@
  * codes, callable from tests and by agents finalizing a run. It validates the
  * *complete-report* shape: the six unique section headings, Issues subheads, the
  * mandatory summary footer with both delivery paths, frontmatter protocol string,
- * and ledger↔declared-steps cardinality. Aborted/partial reports are out of scope —
- * they legitimately lack the footer and Steps line.
+ * ledger↔declared-steps cardinality, and the Cost evidence contract (task 0913):
+ * a complete report must carry a Cost block (Ledger estimate / Method / Meter),
+ * percentages within 0..100, observable token totals consistent with the ledger
+ * row sums (fresh + cached), and no fabricated share when no observable rows
+ * exist. Unknown cells are never folded into zero; all-unknown evidence must
+ * render `n/a`. Aborted/partial reports remain out of scope — they legitimately
+ * lack the footer and Steps line.
  *
  * CLI (task 0278 R6): `bun …/validate-report.ts --file <report.md> [--json]`
  */
@@ -49,6 +54,185 @@ function declaredExecutedSteps(markdown: string): number | null {
     return match ? Number.parseInt(match[1], 10) : null;
 }
 
+// ── Cost evidence contract (task 0913, R2) ──────────────────────────────────
+
+const UNKNOWN_CELLS = new Set(['~unknown', 'unknown', '—', '-', '?', 'n/a', '~n/a']);
+
+/** Display-rounding tolerance: a whole-percent share may differ from the exact
+ * value by at most 1 point (e.g. 700/2100 = 33.3% may display as 33%). */
+const CACHE_SHARE_TOLERANCE = 1;
+
+function sectionBody(markdown: string, headingRe: RegExp): string | null {
+    const heading = markdown.match(headingRe);
+    if (!heading || heading.index === undefined) return null;
+    const after = markdown.slice(heading.index + heading[0].length);
+    const nextHeading = after.search(/^###? /m);
+    return nextHeading === -1 ? after : after.slice(0, nextHeading);
+}
+
+interface CostTotals {
+    total: number | 'n/a' | null;
+    cached: number | 'n/a' | null;
+    pct: number | 'n/a' | null;
+}
+
+function parseTokensLine(line: string): CostTotals | null {
+    const match = line.match(
+        /~(?<total>n\/a|\d+)\s+total\s*\|\s*~(?<cached>n\/a|\d+)\s+cached(?:\s*\(\s*~?(?<pct>n\/a|\d+(?:\.\d+)?)%\s*hit rate\))?/i,
+    );
+    if (!match) return null;
+    const num = (v: string | undefined): number | 'n/a' | null =>
+        v === undefined ? null : v === 'n/a' ? 'n/a' : Number.parseInt(v, 10);
+    return { total: num(match.groups?.total), cached: num(match.groups?.cached), pct: num(match.groups?.pct) };
+}
+
+interface LedgerCostRow {
+    step: string;
+    fresh: number | null;
+    cached: number | null;
+    cachePct: number | null;
+    unknownCell: boolean;
+}
+
+function parseTokenCell(cell: string): number | null {
+    const t = cell.trim();
+    if (UNKNOWN_CELLS.has(t)) return null;
+    const m = t.match(/~?(\d+)/);
+    return m ? Number.parseInt(m[1], 10) : null;
+}
+
+function parsePctCell(cell: string): number | null {
+    const t = cell.trim();
+    if (UNKNOWN_CELLS.has(t)) return null;
+    const m = t.match(/(\d+(?:\.\d+)?)\s*%/);
+    return m ? Number.parseFloat(m[1]) : null;
+}
+
+function ledgerCostRows(markdown: string): LedgerCostRow[] {
+    const body = sectionBody(markdown, /^### 3\. Monitor Ledger\s*$/m);
+    if (body === null) return [];
+    return body
+        .split('\n')
+        .filter((line) => line.trim().startsWith('|'))
+        .filter((line) => !/^\|[\s:|-]+\|?\s*$/.test(line.trim()))
+        .filter((line) => !/^\|\s*`?drift:/.test(line.trim()))
+        .slice(1) // drop header row
+        .map((line) => {
+            const cells = line
+                .split('|')
+                .map((c) => c.trim())
+                .filter((c, i, a) => !(i === 0 && c === '') && !(i === a.length - 1 && c === ''));
+            // Columns: 0 Step … 5 Fresh, 6 Cached, 7 Cache %
+            const freshCell = cells[5] ?? '';
+            const cachedCell = cells[6] ?? '';
+            return {
+                step: cells[0] ?? '',
+                fresh: parseTokenCell(freshCell),
+                cached: parseTokenCell(cachedCell),
+                cachePct: parsePctCell(cells[7] ?? ''),
+                unknownCell: UNKNOWN_CELLS.has(freshCell) || UNKNOWN_CELLS.has(cachedCell),
+            };
+        });
+}
+
+function validateCostEvidence(markdown: string, errors: string[]): void {
+    const costBlock = sectionBody(markdown, /^#### Cost\s*$/m);
+    if (costBlock === null) {
+        errors.push('missing_cost_block');
+        return;
+    }
+    for (const field of ['Ledger estimate', 'Method', 'Meter']) {
+        if (!costBlock.includes(`**${field}:**`)) errors.push(`missing_cost_field:${field}`);
+    }
+
+    const ledgerLine = costBlock.split('\n').find((l) => l.includes('**Ledger estimate:**')) ?? '';
+    const costTotals = parseTokensLine(ledgerLine);
+    // A label present but unparseable is its own defect (task 0913 review P3-1): report it and
+    // keep validating — an early return here disabled every downstream cost check, including
+    // the per-row impossible-percentage scan. An absent label is already reported above as
+    // missing_cost_field; with no line to parse there is nothing further to check for it.
+    if (ledgerLine !== '' && costTotals === null) errors.push('malformed_cost_line');
+    const footerLine = markdown.split('\n').find((l) => l.trim().startsWith('Tokens:'));
+    const footerTotals = footerLine ? parseTokensLine(footerLine) : null;
+    // Same contract for the footer: a present-but-unparseable Tokens: line must not
+    // silently skip the footer totals comparison. An absent Tokens: line with the
+    // summary block present is its own defect (task 0913 verify advisory).
+    if (footerLine !== undefined && footerTotals === null) errors.push('malformed_footer');
+    if (footerLine === undefined && markdown.includes('── Dogfood Summary ──')) {
+        errors.push('missing_footer_tokens');
+    }
+
+    // Percentages must be within 0..100 wherever cost evidence renders one.
+    const pctScopes = [costBlock, footerLine ?? ''];
+    for (const row of ledgerCostRows(markdown)) {
+        if (row.cachePct !== null) pctScopes.push(`${row.cachePct}%`);
+    }
+    for (const scope of pctScopes) {
+        for (const m of scope.matchAll(/(\d+(?:\.\d+)?)\s*%/g)) {
+            const pct = Number.parseFloat(m[1]);
+            if (pct < 0 || pct > 100) errors.push(`impossible_percentage:${m[0].trim()}`);
+        }
+    }
+
+    const rows = ledgerCostRows(markdown);
+
+    // Unknown cells are never folded into a numeric share: a row whose basis is
+    // unknown must carry `—`, never a computed percent.
+    for (const row of rows) {
+        if (row.unknownCell && row.cachePct !== null) errors.push('unknown_row_with_numeric_cache');
+    }
+
+    // Per-row arithmetic: a numeric Cache % must match the row's own fresh/cached cells
+    // (±1pt display rounding), not merely the aggregate share (task 0913 verify advisory).
+    for (const row of rows) {
+        if (row.fresh === null || row.cached === null || row.cachePct === null) continue;
+        const basis = row.fresh + row.cached;
+        if (basis === 0) continue;
+        const expected = Math.round((row.cached / basis) * 100);
+        if (Math.abs(row.cachePct - expected) > CACHE_SHARE_TOLERANCE) {
+            errors.push(`cache_pct_mismatch:${row.step}_expected_${expected}`);
+        }
+    }
+
+    const observable = rows.filter((r) => r.fresh !== null && r.cached !== null);
+    const sumFresh = observable.reduce((acc, r) => acc + (r.fresh ?? 0), 0);
+    const sumCached = observable.reduce((acc, r) => acc + (r.cached ?? 0), 0);
+
+    const checkTotals = (label: string, totals: CostTotals | null): void => {
+        if (totals === null) return;
+        if (observable.length > 0) {
+            const expectedTotal = sumFresh + sumCached;
+            if (typeof totals.total === 'number' && totals.total !== expectedTotal) {
+                errors.push(`cost_total_mismatch:${label}_expected_${expectedTotal}`);
+            }
+            if (typeof totals.cached === 'number' && totals.cached !== sumCached) {
+                errors.push(`cost_total_mismatch:${label}_cached_expected_${sumCached}`);
+            }
+            const expectedPct = expectedTotal > 0 ? Math.round((sumCached / expectedTotal) * 100) : null;
+            if (expectedPct !== null) {
+                if (totals.pct === 'n/a' || totals.pct === null) {
+                    errors.push(`missing_cache_share:${label}`);
+                } else if (
+                    typeof totals.pct === 'number' &&
+                    Math.abs(totals.pct - expectedPct) > CACHE_SHARE_TOLERANCE
+                ) {
+                    errors.push(`cache_share_mismatch:${label}_expected_${expectedPct}`);
+                }
+            }
+        } else if (
+            typeof totals.total === 'number' ||
+            typeof totals.cached === 'number' ||
+            typeof totals.pct === 'number'
+        ) {
+            // No observable denominator: numeric totals/shares fabricate evidence
+            // from unknown rows (unknown folded into zero). `n/a` is the honest form.
+            errors.push(`fabricated_cache_share:${label}`);
+        }
+    };
+    checkTotals('cost', costTotals);
+    checkTotals('footer', footerTotals);
+}
+
 export function validateReport(markdown: string): ReportValidation {
     const errors: string[] = [];
 
@@ -86,6 +270,10 @@ export function validateReport(markdown: string): ReportValidation {
         }
     }
 
+    // Cost evidence (task 0913, R2) — required block, arithmetic consistency,
+    // honest unknowns.
+    validateCostEvidence(markdown, errors);
+
     return { ok: errors.length === 0, errors };
 }
 
@@ -119,6 +307,12 @@ Exit codes:
   2  validation failed (errors on stdout / --json)
   1  usage error
 
+Cost evidence (task 0913): a complete report must carry the Cost block
+(Ledger estimate / Method / Meter), percentages within 0..100, totals equal to
+the ledger sums of observable rows (fresh + cached), and 'n/a' (never a
+fabricated number) when no observable rows exist. Display-rounding tolerance
+for the cache share is ±1 percentage point.
+
 Phase 4 finalize MUST run this before status: complete (task 0278 R6).
 On exit 2: set status: aborted and list error codes under #### Unresolved.`;
 

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

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// @bun
+
+// plugins/sp/scripts/feature-verification-steps.ts
+import { spawnSync } from "child_process";
+import {
+  closeSync,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync
+} from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+
+// plugins/sp/lib/env.ts
+function getEnvVar(name, fallback) {
+  const raw = process.env[name];
+  return raw === undefined ? fallback : raw;
+}
+
+// plugins/sp/scripts/feature-verification-steps.ts
+var SAFE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function bundleEntry() {
+  return fileURLToPath(new URL("../lib/inline-run.generated.mjs", import.meta.url));
+}
+function sourceModeError(spurBin) {
+  return new Error(`source mode: refusing to load packages/app/src/index.ts (spurBin=${JSON.stringify(spurBin)}). ` + "That entry is not the feature-verification contract surface \u2014 it does not export " + "splitLaunchCommand / ArtifactDao. Fix: run in bundle mode so " + "plugins/sp/lib/inline-run.generated.mjs is loaded (omit --module-mode, or pass --module-mode bundle) " + "and regenerate that bundle if it is missing. Reinstalling the sp plugin does not add these seams to the app source entry.");
+}
+function resolveModuleMode(raw) {
+  if (raw === "" || raw === "bundle")
+    return "bundle";
+  if (raw === "source")
+    return "source";
+  throw new Error(`unknown --module-mode ${JSON.stringify(raw)}; expected "source" or "bundle"`);
+}
+async function loadModule(spurBin, mode) {
+  if (mode === "source")
+    throw sourceModeError(spurBin);
+  const bundle = bundleEntry();
+  if (!existsSync(bundle)) {
+    throw new Error(`feature-verification-steps: mode=bundle \u2014 the generated inline bundle is missing at ${bundle}` + `${spurBin === "" ? "" : ` (spurBin=${spurBin})`}. ` + "Fix: in a source checkout run `bun run build:bundle`; for an installed plugin reinstall it.");
+  }
+  return requireModule(bundle, mode);
+}
+async function requireModule(entry, mode) {
+  const mod = await import(entry);
+  const missing = [
+    "startFeatureVerificationReceipt",
+    "completeFeatureVerificationReceipt",
+    "captureFeatureReceiptDigest",
+    "resolveWorkflowDefinition",
+    "splitLaunchCommand",
+    "openInlineRunProjectDb",
+    "ArtifactDao"
+  ].filter((k) => typeof mod[k] !== "function");
+  if (missing.length > 0) {
+    throw new Error(`feature-verification-steps: mode=${mode} \u2014 application entry ${entry} is missing feature-verification seams (${missing.join(", ")}). ` + "Fix: the generated inline bundle is stale or incomplete \u2014 run `bun run build:bundle` in a source checkout, or reinstall the sp plugin.");
+  }
+  return mod;
+}
+function assertSafeId(kind, id) {
+  if (!SAFE_ID_RE.test(id) || id.includes("..")) {
+    throw new Error(`refusing unsafe ${kind}: ${id}`);
+  }
+}
+function findFeatureFile(featureDir, featureId) {
+  if (!existsSync(featureDir))
+    return;
+  const name = readdirSync(featureDir).find((n) => n.startsWith(`${featureId}_`) && n.endsWith(".md"));
+  return name === undefined ? undefined : join(featureDir, name);
+}
+var nodeFsShim = {
+  ensureDir: (dir) => {
+    mkdirSync(dir, { recursive: true });
+  },
+  writeFile: (path, body) => {
+    writeFileSync(path, body);
+  },
+  rename: (src, dest) => {
+    renameSync(src, dest);
+  },
+  readFile: (path) => {
+    return readFileSync(path, "utf8");
+  }
+};
+async function verify(featureId, runId, cmdOverride, spurBin, mode) {
+  assertSafeId("feature id", featureId);
+  assertSafeId("run id", runId);
+  const cwd = process.cwd();
+  const mod = await loadModule(spurBin, mode);
+  const runDir = join(cwd, ".spur", "run");
+  mkdirSync(runDir, { recursive: true });
+  const selected = await mod.resolveWorkflowDefinition(cwd, "feature-verification");
+  const vars = selected.workflow.vars;
+  const configuredCmd = typeof vars?.verificationCmd === "string" && vars.verificationCmd.length > 0 ? vars.verificationCmd : "bun run spur-check-feature";
+  const effectiveCmd = cmdOverride !== "" ? cmdOverride : configuredCmd;
+  const featureFile = findFeatureFile(join(cwd, "docs", "features"), featureId);
+  if (featureFile === undefined) {
+    throw new Error(`feature ${featureId} not found under ${join(cwd, "docs", "features")}`);
+  }
+  const featureContent = readFileSync(featureFile, "utf8");
+  const learningsPath = join(cwd, ".spur", "context", "learnings.md");
+  const learningsContent = existsSync(learningsPath) ? readFileSync(learningsPath, "utf8") : undefined;
+  const beforeDigest = await mod.captureFeatureReceiptDigest(cwd, featureContent, learningsContent);
+  const receipt = await mod.startFeatureVerificationReceipt(nodeFsShim, runDir, {
+    featureId,
+    runId,
+    workdir: cwd,
+    verifier: {
+      name: "feature-verification",
+      sourcePath: selected.path,
+      layer: selected.layer,
+      definitionDigest: selected.digest
+    },
+    verificationCmd: effectiveCmd,
+    inputDigest: beforeDigest
+  });
+  const db = await mod.openInlineRunProjectDb(cwd);
+  try {
+    await new mod.ArtifactDao(db.adapter).record({
+      runId,
+      path: join(runDir, `${runId}-feature-verification.json`),
+      kind: "feature-verification"
+    });
+  } finally {
+    db.close();
+  }
+  const logPath = join(runDir, `${runId}-feature-verification.log`);
+  const launch = mod.splitLaunchCommand(effectiveCmd, "feature-verification verificationCmd");
+  if ("error" in launch) {
+    await mod.completeFeatureVerificationReceipt(nodeFsShim, runDir, receipt, {
+      status: "FAIL",
+      inputDigest: beforeDigest
+    });
+    console.log(`feature-verification-steps: ${featureId} verification FAIL (${launch.error})`);
+    return;
+  }
+  const logFd = openSync(logPath, "a");
+  try {
+    const result = spawnSync(launch.command, launch.leadingArgs, {
+      cwd,
+      stdio: ["ignore", logFd, logFd],
+      timeout: 14400000
+    });
+    const exit = result.status ?? 1;
+    const afterDigest = await mod.captureFeatureReceiptDigest(cwd, featureContent, learningsContent);
+    const status = exit === 0 && afterDigest === beforeDigest ? "PASS" : "FAIL";
+    await mod.completeFeatureVerificationReceipt(nodeFsShim, runDir, receipt, { status, inputDigest: afterDigest });
+    console.log(`feature-verification-steps: ${featureId} verification ${status} (run ${runId}, log ${logPath})`);
+  } finally {
+    closeSync(logFd);
+  }
+}
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const flag = (name) => {
+    const i = args.indexOf(name);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] ?? "" : "";
+  };
+  if (command !== "verify") {
+    console.error("Usage: feature-verification-steps.ts verify --feature-id <id> --run-id <id> [--cmd <command>]");
+    process.exit(2);
+  }
+  verify(flag("--feature-id") || getEnvVar("featureId") || "", flag("--run-id") || getEnvVar("__runId") || "", flag("--cmd") || getEnvVar("verificationCmd") || "", flag("--spur-bin") || getEnvVar("spurBin") || "", resolveModuleMode(flag("--module-mode"))).then(() => process.exit(0)).catch((err) => {
+    console.error(`feature-verification-steps: ${String(err)}`);
+    process.exit(1);
+  });
+}
+main();