@gobing-ai/spur 0.3.62 → 0.3.64

package/plugins/sp/references/environment-lens.md

@@ -0,0 +1,66 @@
+# Environment-improvement lens
+
+One mapping turns retrospective "environment" observations into concrete surface improvements
+across the two live report owners: `sp:dogfood-testing` report §6 and `sp:history-anatomy`
+sections 4/9. (The inspiration is an out-of-tree retrospective practice; it is deliberately not
+shipped or invoked by anything in this plugin.)
+
+**This file is the single source of truth for the seven categories and the placement rule.**
+Neither report projection restates the table below; each links here as its category table
+(task 0686 / feature I9; accepted design `docs/design/environment-improvement-lens.md`,
+ADR-084/085). There is deliberately no `/sp:dev-retro` command, no CLI change, and no protocol
+bump behind this mapping.
+
+## Canonical categories and projections
+
+Exactly one file (this one) enumerates these seven names. Encode them **only** in the projected
+field named by each column — never as a history-anatomy `category` (that vocabulary is frozen at
+`reliability | repetition | workflow | performance | coverage | telemetry | positive`).
+
+| Retro category | History-anatomy `category` (closed) | History-anatomy `<signal>` | Dogfood class |
+| --- | --- | --- | --- |
+| navigation | `workflow` | `navigation` | `environment` (P3–P2) |
+| 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 |
+| 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 |
+
+Dogfood class tags are optional and closed: `environment` | `testee` | `waste`. Grammar,
+classification table, and fix-mode boundaries live in the owning projection:
+[`report-template.md` §6](../skills/dogfood-testing/references/report-template.md).
+History-anatomy key grammar and the structure gate live in
+[`report-contract.md`](../skills/history-anatomy/references/report-contract.md).
+
+## Placement rule
+
+When an observation lands, choose a home in this order — never a new sentence in an
+always-loaded steering file when a lower step fits:
+
+1. **Automatable → propose a check.** Anything a linter, typechecker, test, script-contract
+   check, or filesystem linter could catch becomes a new-or-tighter automated gate
+   (`spur-check`, biome rules, bun tests), not a reminder sentence.
+2. **Coding standard → the review path.** The owner surface is `sp:code-verification`,
+   `sp:code-review`, or pipeline review — never the implementer skill.
+3. **Always-loaded steering (`AGENTS.md` / `CLAUDE.md`) → navigation pointer only.** Detail
+   moves to a skill, reference, or check; the steering file keeps at most a pointer.
+
+## Present-don't-apply
+
+Findings projected through this lens are **proposals**, in either owner's report. No projection
+applies a change, produces a diff, or claims to have executed anything. Dogfood bounded fix-mode
+may repair a failed `testee`-class step, but never mutates a finding tagged `environment`;
+class — not the cited file path — decides whether bounded fix may mutate. History-anatomy stays
+report-only. Accepted proposals reach the tree through operator-approved surfaces (`spur task
+create` handoff, manual edit), which remain explicit human gates.
+
+## Keep / drop boundary
+
+Kept here because both live reports consume it: the seven names above, their projections, and
+this placement rule. Dropped (each needs its own operator decision): installing or invoking the
+out-of-tree retro practice, a standalone retro command, `CODING_STANDARDS.md` as a file, runtime
+parsing of this markdown by validators, automatic remediation of environment findings, and
+folding the lens into wrap-up learnings or `.spur/context/` memory.
+`plugins/sp/skills/issue-finding/` remains the legacy coexistence non-target — it gains nothing
+from this mapping.

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,69 @@ 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 m = opts.helper.match(/\/scripts\/(?:([^/]+)\/)?[^/]+$/);
+  const pluginRoot = m ? opts.helper.slice(0, m.index) : opts.helper;
+  const skill = `${pluginRoot}/skills/${m?.[1] ? `${m[1]}-history-anatomy` : "history-anatomy"}`;
+  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 +586,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 +651,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 +702,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 +807,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,36 @@ 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';
+    // Layouts: monorepo `<root>/scripts/<file>` → skill `<root>/skills/history-anatomy`;
+    // superskill-installed `<root>/scripts/<plugin>/<file>` → skill `<root>/skills/<plugin>-history-anatomy`.
+    // (0660 dogfood 2026-08-26: the single-segment strip left HA_SKILL bogus on installed layouts,
+    // silently degrading probe contract/skill digests to "not available".)
+    const m = opts.helper.match(/\/scripts\/(?:([^/]+)\/)?[^/]+$/);
+    const pluginRoot = m ? opts.helper.slice(0, m.index) : opts.helper;
+    const skill = `${pluginRoot}/skills/${m?.[1] ? `${m[1]}-history-anatomy` : 'history-anatomy'}`;
+    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 +804,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 +878,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 +930,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: '' };