@gobing-ai/spur 0.3.95 → 0.3.96

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

@@ -0,0 +1,210 @@
+// packages/app/src/services/residual-scan.ts
+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(`
+`)}
+`;
+}
+export {
+  scanResiduals,
+  renderReport,
+  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.96",
     "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

@@ -54,7 +54,7 @@ roles:
     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

package/plugins/sp/scripts/history-anatomy-cache.mjs

@@ -1,15 +1,16 @@
 #!/usr/bin/env node
-import { createRequire } from "node:module";
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
+// @bun
 
 // plugins/sp/scripts/history-anatomy-cache.ts
-import { spawnSync } from "node:child_process";
+import { spawnSync } from "child_process";
+import { mkdirSync, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+
+// plugins/sp/lib/history-anatomy.generated.mjs
 import { createHash as createHash2 } from "node:crypto";
 import {
   closeSync,
   existsSync,
   fsyncSync,
-  mkdirSync,
   openSync,
   readdirSync,
   readFileSync,
@@ -19,8 +20,6 @@ import {
   writeFileSync
 } from "node:fs";
 import { join } from "node:path";
-
-// plugins/sp/lib/artifact-digest.generated.mjs
 import { createHash } from "node:crypto";
 var ARTIFACT_ARRAY_CLASSIFICATION = {
   byTool: "ranked",
@@ -63,8 +62,6 @@ function semanticArtifactDigest(artifactJson) {
   const material = JSON.stringify(canonicalize(artifactJson, "root"));
   return createHash("sha256").update(material).digest("hex");
 }
-
-// plugins/sp/scripts/history-anatomy-cache.ts
 var REPORT_SECTIONS = [
   "Scope and provenance",
   "Executive summary",
@@ -669,6 +666,8 @@ function diffPorcelain(before, now, expects) {
   const beforePaths = porcelainPaths(before);
   return [...porcelainPaths(now)].filter((p) => !beforePaths.has(p) && !expects.has(p)).sort();
 }
+
+// plugins/sp/scripts/history-anatomy-cache.ts
 var VALID_COMMANDS = "digest, check, paths, assert-clean, probe, stamp, refresh, publish";
 var PROBE_USAGE = "<script> probe --artifact <a.json> --target <report.md> [--baseline <b.json>] [--mode daily|ad-hoc] " + "[--date <YYYY-MM-DD>] [--recompute true] [--out <prov.json>] [--skill-dir <d>] [--contract <f>] [--workflow <f>] [--helper <f>]";
 function parseFlags(args) {
@@ -698,7 +697,7 @@ function runCacheCli(argv) {
       }
       let artifact;
       try {
-        artifact = JSON.parse(readFileSync(a, "utf8"));
+        artifact = JSON.parse(readFileSync2(a, "utf8"));
       } catch {
         return { exitCode: 1, stdout: "", stderr: `could not parse artifact at ${a}
 ` };
@@ -712,7 +711,7 @@ function runCacheCli(argv) {
         return { exitCode: 1, stdout: "", stderr: `usage: <script> check <report.md>
 ` };
       }
-      const result = checkReportStructure(readFileSync(a, "utf8"));
+      const result = checkReportStructure(readFileSync2(a, "utf8"));
       const stdout = `${result.ok ? "PASS" : "FAIL"}
 ${result.problems.map((p) => `- ${p}
 `).join("")}`;
@@ -751,7 +750,7 @@ ${result.problems.map((p) => `- ${p}
         return { exitCode: 0, stdout: "", stderr: `assert-clean: git unavailable; skipped
 ` };
       }
-      const undeclared = diffPorcelain(readFileSync(f.baseline, "utf8"), now, expects);
+      const undeclared = diffPorcelain(readFileSync2(f.baseline, "utf8"), now, expects);
       if (undeclared.length > 0) {
         return {
           exitCode: 1,
@@ -795,13 +794,13 @@ ${result.problems.map((p) => `- ${p}
         since: f.since,
         until: f.until
       });
-      writeFileSync(f.out, env);
+      writeFileSync2(f.out, env);
       if (f["run-id"] !== undefined && f["run-id"] !== "") {
         mkdirSync(".spur/run", { recursive: true });
         const envVars = Object.fromEntries(env.trim().split(`
 `).map((l) => [l.slice(0, l.indexOf("=")), l.slice(l.indexOf("=") + 1)]));
         const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
-        writeFileSync(`.spur/run/${f["run-id"]}-selector.json`, `${JSON.stringify({
+        writeFileSync2(`.spur/run/${f["run-id"]}-selector.json`, `${JSON.stringify({
           mode: v.mode,
           date: envVars.HA_DATE ?? null,
           focus: v.focus,
@@ -843,7 +842,7 @@ ${result.problems.map((p) => `- ${p}
 ` };
       }
       if (f.out !== undefined)
-        writeFileSync(f.out, `${JSON.stringify(result.current, null, 2)}
+        writeFileSync2(f.out, `${JSON.stringify(result.current, null, 2)}
 `);
       const reasons = result.decision.reasons.map((r) => `- ${r}
 `).join("");
@@ -861,8 +860,8 @@ ${reasons}`, stderr: "" };
         };
       }
       try {
-        const p = JSON.parse(readFileSync(f.provenance, "utf8"));
-        writeFileSync(f.out, `${stampReport(readFileSync(f.candidate, "utf8"), p)}
+        const p = JSON.parse(readFileSync2(f.provenance, "utf8"));
+        writeFileSync2(f.out, `${stampReport(readFileSync2(f.candidate, "utf8"), p)}
 `);
       } catch {
         return { exitCode: 1, stdout: "", stderr: `stamp: could not read candidate or provenance
@@ -882,8 +881,8 @@ ${reasons}`, stderr: "" };
       }
       try {
         const disposition = f.disposition ?? "hit";
-        const refreshed = refreshReport(readFileSync(f.report, "utf8"), f["validated-at"] ?? new Date().toISOString(), disposition);
-        writeFileSync(f.out, refreshed.endsWith(`
+        const refreshed = refreshReport(readFileSync2(f.report, "utf8"), f["validated-at"] ?? new Date().toISOString(), disposition);
+        writeFileSync2(f.out, refreshed.endsWith(`
 `) ? refreshed : `${refreshed}
 `);
       } catch {
@@ -921,5 +920,7 @@ export {
   decideCache,
   checkReportStructure,
   buildProvenance,
-  bannerLine
+  bannerLine,
+  REPORT_SECTIONS,
+  FINDING_FIELDS
 };