@gobing-ai/spur 0.3.62 → 0.3.63

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

@@ -3,6 +3,7 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // plugins/sp/scripts/history-anatomy-cache.ts
+import { spawnSync } from "node:child_process";
 import { createHash as createHash2 } from "node:crypto";
 import {
   closeSync,
@@ -63,7 +64,7 @@ function semanticArtifactDigest(artifactJson) {
 }
 
 // plugins/sp/scripts/history-anatomy-cache.ts
-var ELEVEN_SECTIONS = [
+var REPORT_SECTIONS = [
   "Scope and provenance",
   "Executive summary",
   "Baseline comparison",
@@ -73,6 +74,7 @@ var ELEVEN_SECTIONS = [
   "Remediation options",
   "Performance analysis",
   "Workflow and process improvements",
+  "Report-only advisories",
   "Positive patterns",
   "Evidence ledger"
 ];
@@ -85,7 +87,10 @@ var FINDING_FIELDS = [
   "inference",
   "confidence",
   "contradictions",
-  "evidenceAnchor"
+  "evidenceAnchor",
+  "severity",
+  "reproCommand",
+  "ownerSurface"
 ];
 function parseScalar(raw) {
   const t = raw.trim();
@@ -249,12 +254,21 @@ function decideCache(cached, current, opts) {
 function escapeRe(s) {
   return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+var FINDING_CATEGORIES = [
+  "reliability",
+  "repetition",
+  "workflow",
+  "performance",
+  "coverage",
+  "telemetry",
+  "positive"
+];
 function checkReportStructure(reportMarkdown) {
   const problems = [];
   if (/TODO|PLACEHOLDER|FIXME|^\|\s*\|/im.test(reportMarkdown))
     problems.push("placeholder-or-todo-present");
   let lastIdx = -1;
-  for (const section of ELEVEN_SECTIONS) {
+  for (const section of REPORT_SECTIONS) {
     const re = new RegExp(`^#{2,3}\\s+${escapeRe(section)}\\s*$`, "m");
     const m = reportMarkdown.match(re);
     if (m === null || (m.index ?? -1) <= lastIdx) {
@@ -263,11 +277,45 @@ function checkReportStructure(reportMarkdown) {
       lastIdx = m.index;
     }
   }
-  const findingRows = reportMarkdown.match(/^\|\s*(reliability|repetition|workflow|performance|coverage|telemetry|positive):[^|]+/gm);
-  for (const row of findingRows ?? []) {
-    for (const field of FINDING_FIELDS) {
-      if (!row.toLowerCase().includes(field))
-        problems.push(`finding-missing-field:${field}`);
+  const findingsIdx = reportMarkdown.search(/^##\s+Findings\s*$/im);
+  if (findingsIdx !== -1) {
+    const tail = reportMarkdown.slice(findingsIdx);
+    const nextSection = tail.slice(1).search(/^##\s+/im);
+    const findingsBody = nextSection === -1 ? tail : tail.slice(0, nextSection + 1);
+    const catAlt = FINDING_CATEGORIES.join("|");
+    const knownRows = findingsBody.match(new RegExp(`^\\|\\s*(?:${catAlt}):[^|]+`, "gm")) ?? [];
+    const invalidRows = findingsBody.match(/^\|\s*([^|:\s][^|:]*):[^|]+/gm) ?? [];
+    for (const row of [...new Set([...knownRows, ...invalidRows])]) {
+      const segMatch = row.match(/^\|\s*([^:|]+):/);
+      if (segMatch && !FINDING_CATEGORIES.includes(segMatch[1].trim())) {
+        problems.push(`finding-invalid-key-category:${segMatch[1].trim()}`);
+      }
+      const rowLower = row.toLowerCase();
+      for (const field of FINDING_FIELDS) {
+        if (!rowLower.includes(field.toLowerCase()))
+          problems.push(`finding-missing-field:${field}`);
+      }
+    }
+    const blocks = findingsBody.split(/^###\s+/m).slice(1);
+    for (const block of blocks) {
+      if (!block.includes("`key`") && !/\|\s*key\s*:/.test(block))
+        continue;
+      for (const field of FINDING_FIELDS) {
+        if (!block.includes(field))
+          problems.push(`finding-missing-field:${field}`);
+      }
+      if (!/(^|[\s`])P[123]([\s`.]|$)/.test(block) && !block.includes("symbolic-severity")) {
+        problems.push("finding-invalid-severity");
+      }
+      const catValue = block.match(/`category`\s*[:=]\s*`?([^`\n]+?)`?\s*(?:\n|$)/)?.[1];
+      if (catValue && !FINDING_CATEGORIES.includes(catValue.trim())) {
+        problems.push(`finding-invalid-category:${catValue.trim()}`);
+      }
+      const keyValue = block.match(/`key`\s*[:=]\s*`?([^`\n]+?)`?\s*(?:\n|$)/)?.[1] ?? "";
+      const firstSegment = keyValue.split(":")[0]?.trim() ?? "";
+      if (keyValue !== "" && !FINDING_CATEGORIES.includes(firstSegment)) {
+        problems.push(`finding-invalid-key-category:${firstSegment}`);
+      }
     }
   }
   const ledgerIdx = reportMarkdown.search(/^#{2,3}\s+Evidence\s+ledger/im);
@@ -319,17 +367,68 @@ function localDay(tz, at = new Date) {
     return at.toISOString().slice(0, 10);
   }
 }
+function tzOffsetMs(tz, at) {
+  const parts = Object.fromEntries(new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    hour12: false,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit"
+  }).formatToParts(at).filter((p) => p.type !== "literal").map((p) => [p.type, p.value]));
+  const asUtc = Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), parts.hour === "24" ? 0 : Number(parts.hour), Number(parts.minute), Number(parts.second));
+  const atSec = Math.floor(at.getTime() / 1000) * 1000;
+  return asUtc - atSec;
+}
+function zonedDayStart(tz, ymd) {
+  const [y, m, d] = ymd.split("-").map(Number);
+  const utcMidnight = Date.UTC(y ?? 1970, (m ?? 1) - 1, d ?? 1);
+  const guess = new Date(utcMidnight - tzOffsetMs(tz, new Date(utcMidnight)));
+  return new Date(utcMidnight - tzOffsetMs(tz, guess));
+}
+function formatZonedIso(tz, at) {
+  const off = tzOffsetMs(tz, at);
+  const abs = Math.abs(off);
+  const pad = (n) => String(n).padStart(2, "0");
+  const offStr = `${off < 0 ? "-" : "+"}${pad(Math.floor(abs / 3600000))}:${pad(Math.floor(abs % 3600000 / 60000))}`;
+  return `${new Date(at.getTime() + off).toISOString().slice(0, 23)}${offStr}`;
+}
+function dayBounds(tz, ymd) {
+  const start = zonedDayStart(tz, ymd);
+  const nextYmd = localDay(tz, new Date(start.getTime() + 30 * 3600000));
+  return {
+    since: formatZonedIso(tz, start),
+    until: formatZonedIso(tz, new Date(zonedDayStart(tz, nextYmd).getTime() - 1))
+  };
+}
 function resolvePaths(opts) {
   const pluginRoot = opts.helper.replace(/\/scripts\/[^/]+$/, "");
   const skill = `${pluginRoot}/skills/history-anatomy`;
-  const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
+  const tz = opts.tz ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
   const date = opts.date !== undefined && opts.date !== "" ? opts.date : localDay(tz, opts.now ?? new Date);
   const target = opts.output !== undefined && opts.output !== "" ? opts.output : `${opts.reportDir}/${date}-history-anatomy.md`;
-  return `HA_HELPER=${opts.helper}
+  const adHoc = opts.mode === "ad-hoc" && !!opts.since && !!opts.until;
+  let env = `HA_HELPER=${opts.helper}
 HA_SKILL=${skill}
 HA_TARGET=${target}
 HA_DATE=${date}
 `;
+  if (adHoc) {
+    return `${env}HA_SINCE=${opts.since}
+HA_UNTIL=${opts.until}
+`;
+  }
+  const current = dayBounds(tz, date);
+  const baseline = dayBounds(tz, localDay(tz, new Date(zonedDayStart(tz, date).getTime() - 12 * 3600000)));
+  env += `HA_SINCE=${current.since}
+HA_UNTIL=${current.until}
+`;
+  env += `HA_BASELINE_SINCE=${baseline.since}
+HA_BASELINE_UNTIL=${baseline.until}
+`;
+  return env;
 }
 function buildProvenance(opts) {
   let raw;
@@ -486,7 +585,15 @@ function publishAtomically(candidatePath, targetPath) {
     throw err;
   }
 }
-var VALID_COMMANDS = "digest, check, paths, probe, stamp, refresh, publish";
+function porcelainPaths(text) {
+  return new Set(text.split(`
+`).map((line) => line.replace(/^\S+\s+/, "").trim()).filter((line) => line.length > 0));
+}
+function diffPorcelain(before, now, expects) {
+  const beforePaths = porcelainPaths(before);
+  return [...porcelainPaths(now)].filter((p) => !beforePaths.has(p) && !expects.has(p)).sort();
+}
+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>]";
 function parseFlags(args) {
   const out = {};
@@ -543,13 +650,50 @@ ${result.problems.map((p) => `- ${p}
       publishAtomically(a, b);
       return { exitCode: 0, stdout: "", stderr: "" };
     }
+    case "assert-clean": {
+      const f = parseFlags(argv.slice(1));
+      if (f.baseline === undefined) {
+        return {
+          exitCode: 1,
+          stdout: "",
+          stderr: `usage: <script> assert-clean --baseline <porcelain.txt> [--expect <path>]...
+`
+        };
+      }
+      const expects = new Set;
+      for (const arg of argv.slice(1)) {
+        if (arg.startsWith("--expect="))
+          expects.add(arg.slice("--expect=".length));
+      }
+      let now;
+      try {
+        now = spawnSync("git", ["status", "--porcelain"], {
+          encoding: "utf8",
+          ...f.cwd !== undefined ? { cwd: f.cwd } : {}
+        }).stdout ?? "";
+      } catch {
+        return { exitCode: 0, stdout: "", stderr: `assert-clean: git unavailable; skipped
+` };
+      }
+      const undeclared = diffPorcelain(readFileSync(f.baseline, "utf8"), now, expects);
+      if (undeclared.length > 0) {
+        return {
+          exitCode: 1,
+          stdout: "",
+          stderr: undeclared.map((p) => `undeclared write: ${p}
+`).join("")
+        };
+      }
+      return { exitCode: 0, stdout: `clean
+`, stderr: "" };
+    }
     case "paths": {
       const f = parseFlags(argv.slice(1));
       if (f.helper === undefined || f.out === undefined) {
         return {
           exitCode: 1,
           stdout: "",
-          stderr: `usage: <script> paths --helper <p> --out <env> [--report-dir <d>] [--date <d>] [--output <p>]
+          stderr: `usage: <script> paths --helper <p> --out <env> [--report-dir <d>] [--date <d>] [--output <p>] [--mode <m>] [--since <s>] [--until <u>]
 `
         };
       }
@@ -557,7 +701,10 @@ ${result.problems.map((p) => `- ${p}
         helper: f.helper,
         reportDir: f["report-dir"] ?? "docs/report",
         date: f.date,
-        output: f.output
+        output: f.output,
+        mode: f.mode,
+        since: f.since,
+        until: f.until
       }));
       return { exitCode: 0, stdout: "", stderr: "" };
     }
@@ -659,9 +806,11 @@ export {
   refreshReport,
   publishAtomically,
   probe,
+  porcelainPaths,
   parseProvenance,
   logicDigest,
   importedSnapshotAsOf,
+  diffPorcelain,
   decideCache,
   checkReportStructure,
   buildProvenance,

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

@@ -27,6 +27,7 @@
  * `packages/` imports and no `Bun.*` globals, so the committed `.mjs` twin runs under bare `node`.
  */
 
+import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import {
     closeSync,
@@ -89,7 +90,7 @@ export interface CacheDecision {
 
 // Frozen vocabulary from 0658's references/report-contract.md, kept local (not imported from
 // `packages/`, not re-read from the skill) so this deterministic script is self-contained.
-const ELEVEN_SECTIONS = [
+const REPORT_SECTIONS = [
     'Scope and provenance',
     'Executive summary',
     'Baseline comparison',
@@ -99,6 +100,9 @@ const ELEVEN_SECTIONS = [
     'Remediation options',
     'Performance analysis',
     'Workflow and process improvements',
+    // 0680 R5: standing report-only advisory slot (repeated tool-and-argument
+    // signatures propose no automatic interruption).
+    'Report-only advisories',
     'Positive patterns',
     'Evidence ledger',
 ];
@@ -113,6 +117,10 @@ const FINDING_FIELDS = [
     'confidence',
     'contradictions',
     'evidenceAnchor',
+    // 0680 R1-R3: triage fields — the gate fails a finding missing any of them.
+    'severity',
+    'reproCommand',
+    'ownerSurface',
 ];
 
 // ── 1. Semantic artifact digest ────────────────────────────────────────────────────────────
@@ -311,8 +319,19 @@ function escapeRe(s: string): string {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 
+/** Closed finding categories (0686/I9). Kept next to FINDING_FIELDS — the gate parses them. */
+const FINDING_CATEGORIES = [
+    'reliability',
+    'repetition',
+    'workflow',
+    'performance',
+    'coverage',
+    'telemetry',
+    'positive',
+] as const;
+
 /**
- * Check a candidate report against the frozen report contract — the eleven sections in order,
+ * Check a candidate report against the frozen report contract — the twelve sections in order,
  * the nine per-finding fields, no placeholders/TODOs/empty bodies, and evidence-ledger anchors.
  */
 export function checkReportStructure(reportMarkdown: string): { ok: boolean; problems: string[] } {
@@ -321,7 +340,7 @@ export function checkReportStructure(reportMarkdown: string): { ok: boolean; pro
     if (/TODO|PLACEHOLDER|FIXME|^\|\s*\|/im.test(reportMarkdown)) problems.push('placeholder-or-todo-present');
 
     let lastIdx = -1;
-    for (const section of ELEVEN_SECTIONS) {
+    for (const section of REPORT_SECTIONS) {
         const re = new RegExp(`^#{2,3}\\s+${escapeRe(section)}\\s*$`, 'm');
         const m = reportMarkdown.match(re);
         if (m === null || (m.index ?? -1) <= lastIdx) {
@@ -331,12 +350,57 @@ export function checkReportStructure(reportMarkdown: string): { ok: boolean; pro
         }
     }
 
-    const findingRows = reportMarkdown.match(
-        /^\|\s*(reliability|repetition|workflow|performance|coverage|telemetry|positive):[^|]+/gm,
-    );
-    for (const row of findingRows ?? []) {
-        for (const field of FINDING_FIELDS) {
-            if (!row.toLowerCase().includes(field)) problems.push(`finding-missing-field:${field}`);
+    // 0680 R1-R3: findings are authored as bullet blocks under `## Findings` (one `### <title>`
+    // block per finding, key-value bullets). Scan each block that carries a stable key and fail
+    // it missing any triage field — including the three new ones. Without this scan a bullet
+    // finding never matches the legacy pipe-row regex and the triage gate was vacuous.
+    // 0686/I9: category parsing is scoped to that same body — an explicit category outside the
+    // closed vocabulary (FINDING_CATEGORIES) or a stable key whose first segment does so fails
+    // rather than passing vacuously.
+    const findingsIdx = reportMarkdown.search(/^##\s+Findings\s*$/im);
+    if (findingsIdx !== -1) {
+        const tail = reportMarkdown.slice(findingsIdx);
+        const nextSection = tail.slice(1).search(/^##\s+/im);
+        const findingsBody = nextSection === -1 ? tail : tail.slice(0, nextSection + 1);
+
+        const catAlt = FINDING_CATEGORIES.join('|');
+        const knownRows = findingsBody.match(new RegExp(`^\\|\\s*(?:${catAlt}):[^|]+`, 'gm')) ?? [];
+        const invalidRows = findingsBody.match(/^\|\s*([^|:\s][^|:]*):[^|]+/gm) ?? [];
+        for (const row of [...new Set([...knownRows, ...invalidRows])]) {
+            // 0686/I9: a pipe row outside the closed first-segment set fails by name instead of
+            // being skipped silently by the legacy regex.
+            const segMatch = row.match(/^\|\s*([^:|]+):/);
+            if (segMatch && !(FINDING_CATEGORIES as readonly string[]).includes(segMatch[1].trim())) {
+                problems.push(`finding-invalid-key-category:${segMatch[1].trim()}`);
+            }
+            // Case-insensitive on BOTH sides — camelCase triage fields otherwise never match a
+            // lowercased row.
+            const rowLower = row.toLowerCase();
+            for (const field of FINDING_FIELDS) {
+                if (!rowLower.includes(field.toLowerCase())) problems.push(`finding-missing-field:${field}`);
+            }
+        }
+
+        const blocks = findingsBody.split(/^###\s+/m).slice(1);
+        for (const block of blocks) {
+            if (!block.includes('`key`') && !/\|\s*key\s*:/.test(block)) continue;
+            for (const field of FINDING_FIELDS) {
+                if (!block.includes(field)) problems.push(`finding-missing-field:${field}`);
+            }
+            // Severity vocabulary is closed (0680 R1): P1/P2/P3 only (symbolic placeholders allowed).
+            if (!/(^|[\s`])P[123]([\s`.]|$)/.test(block) && !block.includes('symbolic-severity')) {
+                problems.push('finding-invalid-severity');
+            }
+            // 0686/I9 closed-category enforcement on bullet findings.
+            const catValue = block.match(/`category`\s*[:=]\s*`?([^`\n]+?)`?\s*(?:\n|$)/)?.[1];
+            if (catValue && !(FINDING_CATEGORIES as readonly string[]).includes(catValue.trim())) {
+                problems.push(`finding-invalid-category:${catValue.trim()}`);
+            }
+            const keyValue = block.match(/`key`\s*[:=]\s*`?([^`\n]+?)`?\s*(?:\n|$)/)?.[1] ?? '';
+            const firstSegment = keyValue.split(':')[0]?.trim() ?? '';
+            if (keyValue !== '' && !(FINDING_CATEGORIES as readonly string[]).includes(firstSegment)) {
+                problems.push(`finding-invalid-key-category:${firstSegment}`);
+            }
         }
     }
 
@@ -422,6 +486,66 @@ function localDay(tz: string, at: Date = new Date()): string {
     }
 }
 
+/** Wall-clock offset of `tz` at instant `at`, ms east of UTC (0674 R2). */
+function tzOffsetMs(tz: string, at: Date): number {
+    const parts = Object.fromEntries(
+        new Intl.DateTimeFormat('en-US', {
+            timeZone: tz,
+            hour12: false,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        })
+            .formatToParts(at)
+            .filter((p) => p.type !== 'literal')
+            .map((p) => [p.type, p.value]),
+    );
+    const asUtc = Date.UTC(
+        Number(parts.year),
+        Number(parts.month) - 1,
+        Number(parts.day),
+        parts.hour === '24' ? 0 : Number(parts.hour),
+        Number(parts.minute),
+        Number(parts.second),
+    );
+    // Millisecond-truncate the comparison instant — Intl parts carry second precision, and an
+    // untruncated .999 epoch would leak into the offset (0674).
+    const atSec = Math.floor(at.getTime() / 1000) * 1000;
+    return asUtc - atSec;
+}
+
+/** First instant of local calendar day `ymd` (two-pass so the offset guess survives DST edges). */
+function zonedDayStart(tz: string, ymd: string): Date {
+    const [y, m, d] = ymd.split('-').map(Number);
+    const utcMidnight = Date.UTC(y ?? 1970, (m ?? 1) - 1, d ?? 1);
+    const guess = new Date(utcMidnight - tzOffsetMs(tz, new Date(utcMidnight)));
+    return new Date(utcMidnight - tzOffsetMs(tz, guess));
+}
+
+/** Instant rendered in `tz` wall clock with explicit offset: YYYY-MM-DDTHH:mm:ss.sss±HH:MM. */
+function formatZonedIso(tz: string, at: Date): string {
+    const off = tzOffsetMs(tz, at);
+    const abs = Math.abs(off);
+    const pad = (n: number): string => String(n).padStart(2, '0');
+    const offStr = `${off < 0 ? '-' : '+'}${pad(Math.floor(abs / 3_600_000))}:${pad(Math.floor((abs % 3_600_000) / 60_000))}`;
+    // Shifting by the offset then formatting as UTC yields the zone's own wall clock.
+    return `${new Date(at.getTime() + off).toISOString().slice(0, 23)}${offStr}`;
+}
+
+/** Inclusive bounds of one local calendar day; a DST day is 23/24/25h and both ends carry the real offset. */
+function dayBounds(tz: string, ymd: string): { since: string; until: string } {
+    const start = zonedDayStart(tz, ymd);
+    // start + 30h always lands inside the NEXT calendar day regardless of 23/24/25h lengths.
+    const nextYmd = localDay(tz, new Date(start.getTime() + 30 * 3_600_000));
+    return {
+        since: formatZonedIso(tz, start),
+        until: formatZonedIso(tz, new Date(zonedDayStart(tz, nextYmd).getTime() - 1)),
+    };
+}
+
 /**
  * Resolve the run's fixed paths once (0660 R4/R15): the skill directory beside the helper, the
  * effective local date, and the publication target. Emitted as an env file so every downstream
@@ -433,14 +557,31 @@ export function resolvePaths(opts: {
     date?: string;
     output?: string;
     now?: Date;
+    /** IANA zone override (test hook); defaults to the process zone. */
+    tz?: string;
+    mode?: string;
+    since?: string;
+    until?: string;
 }): string {
     const pluginRoot = opts.helper.replace(/\/scripts\/[^/]+$/, '');
     const skill = `${pluginRoot}/skills/history-anatomy`;
-    const tz = Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
+    const tz = opts.tz ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
     const date = opts.date !== undefined && opts.date !== '' ? opts.date : localDay(tz, opts.now ?? new Date());
     const target =
         opts.output !== undefined && opts.output !== '' ? opts.output : `${opts.reportDir}/${date}-history-anatomy.md`;
-    return `HA_HELPER=${opts.helper}\nHA_SKILL=${skill}\nHA_TARGET=${target}\nHA_DATE=${date}\n`;
+    // 0674 R1/R2: daily bounds are derived here — date arithmetic in a named zone is exactly
+    // the "exceeds the shell composition threshold" case (ADR-069 R1), and DST makes a local
+    // day 23/24/25h. Ad-hoc (0674 R3): operator bounds pass through untouched, no baseline pair.
+    const adHoc = opts.mode === 'ad-hoc' && !!opts.since && !!opts.until;
+    let env = `HA_HELPER=${opts.helper}\nHA_SKILL=${skill}\nHA_TARGET=${target}\nHA_DATE=${date}\n`;
+    if (adHoc) {
+        return `${env}HA_SINCE=${opts.since}\nHA_UNTIL=${opts.until}\n`;
+    }
+    const current = dayBounds(tz, date);
+    const baseline = dayBounds(tz, localDay(tz, new Date(zonedDayStart(tz, date).getTime() - 12 * 3_600_000)));
+    env += `HA_SINCE=${current.since}\nHA_UNTIL=${current.until}\n`;
+    env += `HA_BASELINE_SINCE=${baseline.since}\nHA_BASELINE_UNTIL=${baseline.until}\n`;
+    return env;
 }
 
 export interface ProbeOptions {
@@ -658,7 +799,23 @@ export interface CacheCliResult {
     stderr: string;
 }
 
-const VALID_COMMANDS = 'digest, check, paths, probe, stamp, refresh, publish';
+/** Parse a `git status --porcelain` text into its path set. */
+export function porcelainPaths(text: string): Set<string> {
+    return new Set(
+        text
+            .split('\n')
+            .map((line) => line.replace(/^\S+\s+/, '').trim())
+            .filter((line) => line.length > 0),
+    );
+}
+
+/** Paths present now but absent from the baseline and not declared outputs (0676 R3). */
+export function diffPorcelain(before: string, now: string, expects: Set<string>): string[] {
+    const beforePaths = porcelainPaths(before);
+    return [...porcelainPaths(now)].filter((p) => !beforePaths.has(p) && !expects.has(p)).sort();
+}
+
+const VALID_COMMANDS = 'digest, check, paths, assert-clean, probe, stamp, refresh, publish';
 const 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>]';
@@ -716,13 +873,49 @@ export function runCacheCli(argv: string[]): CacheCliResult {
             publishAtomically(a, b);
             return { exitCode: 0, stdout: '', stderr: '' };
         }
+        case 'assert-clean': {
+            // 0676 R3: fingerprint diff around a model stage. `--baseline` holds the
+            // pre-stage `git status --porcelain`; every path present now but absent there
+            // must be one of the stage's declared outputs, else exit 1 naming each.
+            const f = parseFlags(argv.slice(1));
+            if (f.baseline === undefined) {
+                return {
+                    exitCode: 1,
+                    stdout: '',
+                    stderr: 'usage: <script> assert-clean --baseline <porcelain.txt> [--expect <path>]...\n',
+                };
+            }
+            const expects = new Set<string>();
+            for (const arg of argv.slice(1)) {
+                if (arg.startsWith('--expect=')) expects.add(arg.slice('--expect='.length));
+            }
+            let now: string;
+            try {
+                now =
+                    spawnSync('git', ['status', '--porcelain'], {
+                        encoding: 'utf8',
+                        ...(f.cwd !== undefined ? { cwd: f.cwd } : {}),
+                    }).stdout ?? '';
+            } catch {
+                return { exitCode: 0, stdout: '', stderr: 'assert-clean: git unavailable; skipped\n' };
+            }
+            const undeclared = diffPorcelain(readFileSync(f.baseline, 'utf8'), now, expects);
+            if (undeclared.length > 0) {
+                return {
+                    exitCode: 1,
+                    stdout: '',
+                    stderr: undeclared.map((p) => `undeclared write: ${p}\n`).join(''),
+                };
+            }
+            return { exitCode: 0, stdout: 'clean\n', stderr: '' };
+        }
         case 'paths': {
             const f = parseFlags(argv.slice(1));
             if (f.helper === undefined || f.out === undefined) {
                 return {
                     exitCode: 1,
                     stdout: '',
-                    stderr: 'usage: <script> paths --helper <p> --out <env> [--report-dir <d>] [--date <d>] [--output <p>]\n',
+                    stderr: 'usage: <script> paths --helper <p> --out <env> [--report-dir <d>] [--date <d>] [--output <p>] [--mode <m>] [--since <s>] [--until <u>]\n',
                 };
             }
             writeFileSync(
@@ -732,6 +925,9 @@ export function runCacheCli(argv: string[]): CacheCliResult {
                     reportDir: f['report-dir'] ?? 'docs/report',
                     date: f.date,
                     output: f.output,
+                    mode: f.mode,
+                    since: f.since,
+                    until: f.until,
                 }),
             );
             return { exitCode: 0, stdout: '', stderr: '' };

package/plugins/sp/skills/dogfood-testing/references/report-template.md

@@ -237,6 +237,36 @@ downstream task creation does not inherit an unactionable acceptance criterion:
 
 The tag is a prompt to whoever turns findings into tasks: `[stale]` → drop, `[unverifiable]` →
 reframe or defer, `[feasible]` → proceed. A finding without a tag is treated as `[feasible]`.
+
+**Optional class tag (environment lens, task 0686).** A finding line may carry one closed class
+tag — `environment` | `testee` | `waste` — positioned immediately after the em dash and distinct
+from the trailing feasibility tag:
+
+```
+- **P2** — [environment] <what's wrong>. → **Action:** <concrete change>.  (`file:line`, ~effort)  `[feasible]`
+```
+
+Omitting the class preserves the current line shape; untagged findings remain valid and the
+protocol stays `sp:dogfood-testing@1.2` (the validator gains no required field; the cache-health
+P3 above needs no class).
+
+- `testee` — a defect in the testee's contract (the protocol the run grades). Bounded fix-mode
+  may repair it, unchanged.
+- `environment` — a steering/placement/check-shaped observation projected from the
+  [environment-improvement lens](../../../references/environment-lens.md), which owns the
+  category table and the placement rule. **Proposal-only:** even under `--max-retry N`, bounded
+  retries never `Edit` or `Write` `AGENTS.md`, `CLAUDE.md`, skills, rules, numbered docs, or
+  plugin references for an environment-tagged finding — it stays a recommended action here.
+- `waste` — a token/tool-waste diagnostic with no missing environment affordance behind it.
+
+Class, not the cited file path, decides whether bounded fix may mutate. A session mistake a
+linter, typechecker, test, or filesystem gate could have caught is `environment`, and its
+recommended action proposes a new-or-tighter automated check — never another sentence in an
+always-loaded steering file. Missed coding standards are `environment` owned by a review path
+(`sp:code-verification`, `sp:code-review`, or pipeline review) — never the implementer skill;
+navigation friction and dead always-loaded instructions are likewise `environment`, not
+`testee`.
+
 Severity scale:
 
 - **P1** — blocks correct use or causes drift/wrong output; fix before shipping the testee.

package/plugins/sp/skills/history-anatomy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: history-anatomy
-description: "Independent owner of diagnostic interpretation over already-imported history — the daily/ad-hoc mode contract, a closed finding taxonomy, the eleven-section report contract, and the enrich/validate rubrics. Triggers: history-anatomy, run the daily report, ad-hoc diagnosis, find issues over history."
+description: "Independent owner of diagnostic interpretation over already-imported history — the daily/ad-hoc mode contract, a closed finding taxonomy, the twelve-section report contract, and the enrich/validate rubrics. Triggers: history-anatomy, run the daily report, ad-hoc diagnosis, find issues over history."
 license: Apache-2.0
 version: 1.0.0
 metadata:
@@ -37,7 +37,7 @@ fresh skill cannot be added to the BASELINE exemption map).
 **Choose the mode first.** The single entry is `--mode daily|ad-hoc` (default `daily`):
 `references/modes.md`.
 
-**Then hold the report to the contract.** Every report must contain the eleven sections and every
+**Then hold the report to the contract.** Every report must contain the twelve sections and every
 finding the full field set, with evidence rules and an explicit comparability verdict:
 `references/report-contract.md`.
 
@@ -63,5 +63,5 @@ finding the full field set, with evidence rules and an explicit comparability ve
 | Reference | Owns |
 | --- | --- |
 | [`references/modes.md`](references/modes.md) | The daily/ad-hoc mode matrix, bounds normalization, the DST-aware calendar-day rule, and the fail-loud message shape. |
-| [`references/report-contract.md`](references/report-contract.md) | The eleven sections (in order), the per-finding field set, the closed category vocabulary, the stable-key grammar, the evidence rules, comparison semantics, recurrence classes, and the positive-pattern / remediation standards. |
+| [`references/report-contract.md`](references/report-contract.md) | The twelve sections (in order), the per-finding field set, the closed category vocabulary, the stable-key grammar, the evidence rules, comparison semantics, recurrence classes, and the positive-pattern / remediation standards. |
 | [`references/operations.md`](references/operations.md) | The `enrich` and `validate` operation rubrics; neither launches a workflow. |