start-vibing 4.3.0 → 4.3.2

package/template/.claude/skills/super-design/scripts/extract-tokens.mjs

@@ -1,10 +1,18 @@
 #!/usr/bin/env node
+// Extract + canonicalize + hash design tokens from Tailwind configs, CSS custom
+// properties, and DTCG / Tokens Studio JSON (artifact §9.1 lines 707-709, §9.2
+// lines 720-761). Output is deterministic regardless of insertion order
+// (artifact §9.2 line 722: "canonical = JSON.stringify(theme,
+// Object.keys(theme).sort())").
 import fs from "node:fs";
 import path from "node:path";
+import { createHash } from "node:crypto";
 import { pathToFileURL } from "node:url";
 
 const out = {};
+const sources = [];
 const tailwindConfigs = ["tailwind.config.ts", "tailwind.config.js", "tailwind.config.mjs", "tailwind.config.cjs"];
+let tailwindFound = false;
 for (const candidate of tailwindConfigs) {
   if (fs.existsSync(candidate)) {
     try {
@@ -12,10 +20,14 @@ for (const candidate of tailwindConfigs) {
       const cfg = (await import(pathToFileURL(path.resolve(candidate)).href)).default;
       const resolved = resolveConfig(cfg);
       flatten(resolved.theme, "tw", out);
+      tailwindFound = true;
     } catch (e) { out[`_error_${candidate}`] = String(e.message || e); }
     break;
   }
 }
+if (tailwindFound) sources.push("tailwind");
+
+let cssFound = false;
 try {
   const postcss = (await import("postcss")).default;
   const cssCandidates = ["styles/globals.css","src/styles/globals.css","app/globals.css","styles/theme.css","src/app/globals.css"];
@@ -23,19 +35,168 @@ try {
     if (!fs.existsSync(css)) continue;
     const source = fs.readFileSync(css, "utf8");
     const root = postcss.parse(source);
-    root.walkAtRules("theme", at => { at.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); }); });
-    root.walkRules(":root", rule => { rule.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); }); });
+    root.walkAtRules("theme", at => { at.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); cssFound = true; }); });
+    root.walkRules(":root", rule => { rule.walkDecls(/^--/, d => { out[`css:${d.prop}`] = d.value.trim(); cssFound = true; }); });
   }
 } catch (e) { out._postcss_error = String(e.message || e); }
+if (cssFound) sources.push("css-vars");
+
+// DTCG + Tokens Studio support (artifact §9.1 line 707-709, §9.2 line 747).
+const dtcgFiles = discoverDtcgFiles(".");
+let dtcgFound = false;
+for (const file of dtcgFiles) {
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    const parsed = JSON.parse(raw);
+    // Tokens Studio $metadata/$themes are not token trees — skip.
+    if (path.basename(file) === "$metadata.json" || path.basename(file) === "$themes.json") continue;
+    const resolved = resolveDtcgAliases(parsed, file);
+    const relFile = path.relative(".", file).replaceAll("\\", "/");
+    flattenDtcg(resolved, `dtcg:${relFile}`, out);
+    dtcgFound = true;
+  } catch (e) {
+    out[`_dtcg_error_${file}`] = String(e.message || e);
+  }
+}
+if (dtcgFound) sources.push("dtcg");
+
+// Deterministic canonical form: keys sorted top-to-bottom.
+const sorted = Object.keys(out).sort().reduce((acc, k) => { acc[k] = out[k]; return acc; }, {});
+const canonical = JSON.stringify(sorted);
+const tokens_hash = "sha256:" + createHash("sha256").update(canonical).digest("hex");
 
-console.log(JSON.stringify(out, null, 2));
+console.log(JSON.stringify({ tokens: sorted, tokens_hash, sources: sources.sort() }, null, 2));
 
 function flatten(obj, prefix, acc) {
   if (obj == null) return;
   if (typeof obj !== "object") { acc[prefix] = String(obj); return; }
-  for (const [k, v] of Object.entries(obj)) {
+  // Sort keys so hash is stable across JS engines / config formatters.
+  // Artifact §9.2 line 722 calls this out explicitly.
+  for (const k of Object.keys(obj).sort()) {
+    const v = obj[k];
     const key = `${prefix}.${k}`;
     if (v && typeof v === "object" && !Array.isArray(v)) flatten(v, key, acc);
     else acc[key] = Array.isArray(v) ? v.join(",") : String(v);
   }
 }
+
+// Walk cwd, returning **/*.tokens.json (excluding build/vendor dirs) plus the
+// two conventional Tokens Studio single-file exports.
+function discoverDtcgFiles(rootDir) {
+  const skipDirs = new Set(["node_modules", "dist", ".next", "build", ".git", "coverage", ".turbo", ".cache"]);
+  const found = [];
+  const walk = (dir) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (skipDirs.has(entry.name) || entry.name.startsWith(".")) {
+          // Allow explicit `.tokens` dir used by some Tokens Studio setups.
+          if (entry.name !== ".tokens") continue;
+        }
+        walk(path.join(dir, entry.name));
+      } else if (entry.isFile()) {
+        const full = path.join(dir, entry.name);
+        if (entry.name.endsWith(".tokens.json")) found.push(full);
+        else if (entry.name === "tokens.json" && (dir === rootDir || path.basename(dir) === ".tokens")) found.push(full);
+      }
+    }
+  };
+  walk(rootDir);
+  return found.sort();
+}
+
+// Resolve DTCG aliases transitively. Supports both `{color.brand.primary}` and
+// Tokens Studio legacy `$color.brand.primary`. Cycle detection throws loudly.
+function resolveDtcgAliases(tree, filename) {
+  const resolving = new Set();
+  const lookup = (pathStr) => {
+    const segs = pathStr.split(".");
+    let node = tree;
+    for (const s of segs) {
+      if (node == null || typeof node !== "object") return undefined;
+      node = node[s];
+    }
+    return node;
+  };
+  const resolveValue = (value, trail) => {
+    if (typeof value !== "string") return value;
+    const braceMatch = value.match(/^\{([^}]+)\}$/);
+    const dollarMatch = value.match(/^\$([A-Za-z_][A-Za-z0-9_.-]*)$/);
+    const aliasPath = braceMatch ? braceMatch[1] : dollarMatch ? dollarMatch[1] : null;
+    if (!aliasPath) return value;
+    if (trail.has(aliasPath)) {
+      throw new Error(`DTCG alias cycle in ${filename}: ${[...trail, aliasPath].join(" -> ")}`);
+    }
+    const target = lookup(aliasPath);
+    if (target == null) return value; // dangling alias: pass through raw
+    const next = typeof target === "object" && target !== null && "$value" in target ? target.$value : target;
+    return resolveValue(next, new Set([...trail, aliasPath]));
+  };
+  const walk = (node) => {
+    if (node == null || typeof node !== "object") return node;
+    if (Array.isArray(node)) return node.map(walk);
+    if ("$value" in node) {
+      const copy = { ...node };
+      try {
+        copy.$value = resolveValue(copy.$value, new Set());
+      } catch (err) {
+        // Cycles must fail loudly per requirements.
+        throw err;
+      }
+      copy.$value = applyTokensStudioTransforms(copy.$value, node.$extensions, filename);
+      return copy;
+    }
+    const result = {};
+    for (const k of Object.keys(node)) result[k] = walk(node[k]);
+    return result;
+  };
+  return walk(tree);
+}
+
+// Apply Tokens Studio `modify` transforms (lighten/darken/alpha). Anything
+// unparseable emits a warning to stderr and passes through the raw $value.
+function applyTokensStudioTransforms(value, extensions, filename) {
+  const modify = extensions?.["studio.tokens"]?.modify;
+  if (!modify || typeof value !== "string") return value;
+  const { type, amount, space } = modify;
+  const num = Number(amount);
+  try {
+    if (type === "alpha" && /^#([0-9a-f]{6})$/i.test(value) && Number.isFinite(num)) {
+      const a = Math.round(Math.max(0, Math.min(1, num)) * 255).toString(16).padStart(2, "0");
+      return value + a;
+    }
+    if ((type === "lighten" || type === "darken") && /^#([0-9a-f]{6})$/i.test(value) && Number.isFinite(num)) {
+      const hex = value.slice(1);
+      const rgb = [0, 2, 4].map(i => parseInt(hex.slice(i, i + 2), 16));
+      const factor = type === "lighten" ? num : -num;
+      const adjusted = rgb.map(c => Math.max(0, Math.min(255, Math.round(c + (factor * 255)))));
+      return "#" + adjusted.map(c => c.toString(16).padStart(2, "0")).join("");
+    }
+    process.stderr.write(`[extract-tokens] warn: unsupported Tokens Studio modify(${type}, space=${space}) in ${filename}; passing through raw value\n`);
+    return value;
+  } catch {
+    process.stderr.write(`[extract-tokens] warn: failed to apply Tokens Studio modify(${type}) in ${filename}; passing through raw value\n`);
+    return value;
+  }
+}
+
+// Flatten a resolved DTCG tree into `prefix.path = stringified $value` leaves.
+function flattenDtcg(node, prefix, acc) {
+  if (node == null) return;
+  if (typeof node !== "object" || Array.isArray(node)) {
+    acc[prefix] = Array.isArray(node) ? node.join(",") : String(node);
+    return;
+  }
+  if ("$value" in node) {
+    const v = node.$value;
+    const t = node.$type;
+    const key = t ? `${prefix}[${t}]` : prefix;
+    acc[key] = typeof v === "object" ? JSON.stringify(v, Object.keys(v).sort()) : String(v);
+    return;
+  }
+  for (const k of Object.keys(node).sort()) {
+    if (k.startsWith("$")) continue; // $description / $extensions / $metadata
+    flattenDtcg(node[k], `${prefix}.${k}`, acc);
+  }
+}

package/template/.claude/skills/super-design/scripts/hash-pages.sh

@@ -1,42 +1,228 @@
 #!/usr/bin/env bash
 # Usage: hash-pages.sh <urls_file>
+#
+# Captures three viewports per URL (mobile_375, tablet_768, desktop_1280),
+# computes sha256 (exact) + phash (perceptual) for each, and emits a single
+# JSON file with one record per URL (artifact §3.4, §10 line 492, §16 lines
+# 1367-1384).
+#
+# Env vars:
+#   OUT_DIR          — where to write hashes.json and the per-viewport PNGs
+#                      (default: docs/super-design/.cache/hashes).
+#   MASK_SELECTORS   — comma-separated CSS selectors masked on every
+#                      screenshot via Playwright's `mask:` option with
+#                      maskColor "#000". Artifact §3.4 defaults are always
+#                      merged in; user-supplied selectors are additive.
+#   MASK_COLOR       — overrides the mask fill color (default #000).
+#   HASH_URL_TIMEOUT — per-URL navigation timeout ms (default 30000).
+#
+# Output shape (artifact §10 line 492):
+#   {
+#     "url": "...",
+#     "html_hash":          "sha256:...",
+#     "dom_structure_hash": "sha256:...",
+#     "screenshot_hash":    "sha256:...",   (desktop, back-compat)
+#     "viewport_hashes": {
+#       "mobile_375":  { "sha256": "...", "phash": "..." },
+#       "tablet_768":  { "sha256": "...", "phash": "..." },
+#       "desktop_1280":{ "sha256": "...", "phash": "..." }
+#     }
+#   }
+#
+# Perceptual hash (phash):
+#   We prefer `sharp` if installed (true DCT/aHash on a 32x32 greyscale
+#   downsample). If sharp is unavailable we fall back to a deterministic
+#   PNG-structural fingerprint — 64 bits derived from 8 evenly-sliced
+#   sha256 windows over the PNG buffer. This is NOT a true perceptual
+#   hash; it survives identical re-renders but is sensitive to any pixel
+#   change. Compare with Hamming distance only when sharp was used (the
+#   emitted record includes an "engine" field so consumers can pick the
+#   right distance metric).
 set -euo pipefail
+
 URLS="${1:?usage: hash-pages.sh <urls_file>}"
 OUT_DIR="${OUT_DIR:-docs/super-design/.cache/hashes}"
+MASK_SELECTORS="${MASK_SELECTORS:-}"
+MASK_COLOR="${MASK_COLOR:-#000}"
+HASH_URL_TIMEOUT="${HASH_URL_TIMEOUT:-30000}"
 mkdir -p "$OUT_DIR"
 
-URLS="$URLS" OUT_DIR="$OUT_DIR" node --experimental-vm-modules <<'JS'
+URLS="$URLS" OUT_DIR="$OUT_DIR" \
+MASK_SELECTORS="$MASK_SELECTORS" MASK_COLOR="$MASK_COLOR" \
+HASH_URL_TIMEOUT="$HASH_URL_TIMEOUT" node --experimental-vm-modules <<'JS'
 import { chromium } from "playwright";
 import { createHash } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 
 const urlsFile = process.env.URLS;
 const outDir = process.env.OUT_DIR;
-const urls = readFileSync(urlsFile, "utf8").split("\n").map(s => s.trim()).filter(Boolean);
+const maskColor = process.env.MASK_COLOR || "#000";
+const navTimeout = Number(process.env.HASH_URL_TIMEOUT || 30000);
+
+// Artifact §3.4 defaults — always masked.
+const DEFAULT_MASKS = [
+  "[data-timestamp]",
+  ".relative-time",
+  "[data-react-hydration]",
+  "video",
+  "canvas",
+];
+const userMasks = (process.env.MASK_SELECTORS || "")
+  .split(",").map(s => s.trim()).filter(Boolean);
+const maskSelectors = [...new Set([...DEFAULT_MASKS, ...userMasks])];
+
+// Volatile attributes stripped from the DOM structure hash (artifact §3.4
+// — added data-react-hydration to match the mask defaults).
+const VOLATILE_ATTRS = new Set([
+  "nonce",
+  "data-timestamp",
+  "data-reactid",
+  "data-next-hydrate",
+  "data-react-hydration",
+]);
+
+const urls = readFileSync(urlsFile, "utf8")
+  .split("\n").map(s => s.trim()).filter(Boolean);
+
+const VIEWPORTS = [
+  { label: "mobile_375",  width: 375,  height: 667  },
+  { label: "tablet_768",  width: 768,  height: 1024 },
+  { label: "desktop_1280", width: 1280, height: 800  },
+];
+
+const sha = (s) => createHash("sha256").update(s).digest("hex");
+
+// Optional sharp — gives us a real perceptual hash. Falls back to a
+// PNG-structural fingerprint (documented in the header) when absent.
+let sharp = null;
+let phashEngine = "fallback-png-fingerprint";
+try {
+  sharp = (await import("sharp")).default;
+  phashEngine = "sharp-ahash-8x8";
+} catch { /* no sharp installed; use fallback */ }
+
+async function aHash(buf) {
+  if (!sharp) return fallbackFingerprint(buf);
+  // Average-hash: downscale to 8x8 greyscale, threshold at mean.
+  const raw = await sharp(buf)
+    .greyscale()
+    .resize(8, 8, { fit: "fill", kernel: "cubic" })
+    .raw()
+    .toBuffer();
+  let sum = 0;
+  for (let i = 0; i < raw.length; i++) sum += raw[i];
+  const mean = sum / raw.length;
+  let bits = 0n;
+  for (let i = 0; i < 64; i++) {
+    bits = (bits << 1n) | (raw[i] >= mean ? 1n : 0n);
+  }
+  return bits.toString(16).padStart(16, "0");
+}
+
+function fallbackFingerprint(buf) {
+  // Zero-dep deterministic fingerprint: slice PNG into 8 windows, take the
+  // first byte of each window's sha256, concat to 16 hex chars. Order of
+  // magnitude cheaper than a real pHash and only collision-safe for
+  // identical-buffer comparisons, but it gives us a stable 64-bit slot in
+  // viewport_hashes so downstream tooling can still key on it.
+  if (buf.length === 0) return "0".repeat(16);
+  const windows = 8;
+  const step = Math.max(1, Math.floor(buf.length / windows));
+  let out = "";
+  for (let i = 0; i < windows; i++) {
+    const start = i * step;
+    const end = i === windows - 1 ? buf.length : start + step;
+    const slice = buf.subarray(start, end);
+    const h = createHash("sha256").update(slice).digest();
+    out += h.subarray(0, 1).toString("hex");
+  }
+  return out;
+}
+
 const browser = await chromium.launch();
-const ctx = await browser.newContext({
-  viewport: { width: 1280, height: 800 }, reducedMotion: "reduce", deviceScaleFactor: 1,
-});
-const page = await ctx.newPage();
-const sha = s => createHash("sha256").update(s).digest("hex");
 const results = [];
 for (const url of urls) {
+  const entry = { url, viewport_hashes: {} };
   try {
-    await page.goto(url, { waitUntil: "networkidle", timeout: 30000 });
-    const html = (await page.content()).replace(/\s+/g, " ").trim();
-    const dom = await page.evaluate(() => {
-      const V = new Set(["nonce","data-timestamp","data-reactid","data-next-hydrate"]);
-      const walk = n => n.nodeType !== 1 ? "" :
-        `<${n.tagName.toLowerCase()}[${[...n.attributes].filter(a=>!V.has(a.name))
-          .map(a=>`${a.name}=${a.value}`).sort().join(",")}]${[...n.childNodes].map(walk).join("")}>`;
-      return walk(document.documentElement);
-    });
-    const buf = await page.screenshot({ fullPage: true, animations: "disabled", caret: "hide" });
-    results.push({ url, html_hash: "sha256:" + sha(html),
-      dom_structure_hash: "sha256:" + sha(dom), screenshot_hash: "sha256:" + sha(buf) });
-  } catch (e) { results.push({ url, error: String(e.message || e) }); }
+    // Shared context: cache html/dom work on first (desktop) viewport.
+    let capturedHtml = null;
+    let capturedDom = null;
+
+    for (const vp of VIEWPORTS) {
+      const ctx = await browser.newContext({
+        viewport: { width: vp.width, height: vp.height },
+        reducedMotion: "reduce",
+        deviceScaleFactor: 1,
+      });
+      const page = await ctx.newPage();
+      await page.goto(url, { waitUntil: "networkidle", timeout: navTimeout });
+
+      if (capturedHtml === null) {
+        capturedHtml = (await page.content()).replace(/\s+/g, " ").trim();
+        capturedDom = await page.evaluate((volatileList) => {
+          const V = new Set(volatileList);
+          const walk = (n) => n.nodeType !== 1 ? "" :
+            `<${n.tagName.toLowerCase()}[${[...n.attributes]
+              .filter(a => !V.has(a.name))
+              .map(a => `${a.name}=${a.value}`)
+              .sort().join(",")}]${[...n.childNodes].map(walk).join("")}>`;
+          return walk(document.documentElement);
+        }, [...VOLATILE_ATTRS]);
+      }
+
+      // Build mask locator list (skip selectors that error — they're OK
+      // if nothing matches; only invalid syntax throws).
+      const masks = [];
+      for (const sel of maskSelectors) {
+        try { masks.push(page.locator(sel)); } catch { /* bad selector */ }
+      }
+
+      const buf = await page.screenshot({
+        fullPage: true,
+        animations: "disabled",
+        caret: "hide",
+        mask: masks,
+        maskColor,
+      });
+
+      // Persist PNG for visual-regression.sh to consume.
+      const pngDir = join(outDir, "screenshots", encodeURIComponent(url));
+      mkdirSync(pngDir, { recursive: true });
+      const pngPath = join(pngDir, `${vp.label}.png`);
+      writeFileSync(pngPath, buf);
+
+      const ph = await aHash(buf);
+      entry.viewport_hashes[vp.label] = {
+        sha256: "sha256:" + sha(buf),
+        phash: `${phashEngine === "sharp-ahash-8x8" ? "phash" : "fpr"}:${ph}`,
+        png_path: pngPath,
+      };
+
+      if (vp.label === "desktop_1280") {
+        entry.screenshot_hash = entry.viewport_hashes[vp.label].sha256;
+      }
+
+      await ctx.close();
+    }
+
+    entry.html_hash = "sha256:" + sha(capturedHtml);
+    entry.dom_structure_hash = "sha256:" + sha(capturedDom);
+    entry.mask_selectors = maskSelectors;
+    entry.phash_engine = phashEngine;
+  } catch (e) {
+    entry.error = String(e.message || e);
+  }
+  results.push(entry);
 }
-writeFileSync(outDir + "/hashes.json", JSON.stringify(results, null, 2));
+
+writeFileSync(join(outDir, "hashes.json"), JSON.stringify(results, null, 2));
 await browser.close();
-console.log(JSON.stringify({ count: results.length, path: outDir + "/hashes.json" }));
+console.log(JSON.stringify({
+  count: results.length,
+  path: join(outDir, "hashes.json"),
+  phash_engine: phashEngine,
+  viewports: VIEWPORTS.map(v => v.label),
+  mask_selectors: maskSelectors,
+}));
 JS

package/template/.claude/skills/super-design/scripts/setup-git-notes.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# Usage: setup-git-notes.sh
+#
+# One-shot setup so `git notes --ref=super-design` round-trips across
+# clones. Without the remote refspec, git fetch ignores notes by default
+# (artifact §7 line 570-573).
+set -euo pipefail
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+  echo '{"error":"not-a-git-repo"}' >&2; exit 3
+fi
+
+# Idempotent: only add if absent.
+if git config --get-all remote.origin.fetch 2>/dev/null |
+   grep -q 'refs/notes/super-design'; then
+  echo '{"status":"already-configured"}'
+else
+  git config --add remote.origin.fetch \
+    '+refs/notes/super-design:refs/notes/super-design'
+  echo '{"status":"added","ref":"refs/notes/super-design"}'
+fi

package/template/.claude/skills/super-design/scripts/validate-state.sh

@@ -1,15 +1,78 @@
 #!/usr/bin/env bash
+# Usage: validate-state.sh [<app_path_or_state_path>]
+#
+# Validates the super-design audit state file. On schema/parse errors,
+# moves the broken file aside (artifact §3 "Graceful corruption handling"
+# line 74) and emits a JSON verdict. Also enforces schema_version major
+# compatibility (artifact §12 line 934).
+#
+# Monorepo support (artifact §11 line 902): the positional arg is the
+# app root (e.g. `apps/web`); state is looked up at
+# `<app_path>/docs/super-design/.audit-state.json`. For single-app
+# repos pass "." or omit (default behavior preserved). Back-compat: if
+# the arg ends in `.audit-state.json` it is used verbatim.
+#
+# Validation strategy:
+#   1. If `ajv` is on PATH, validate against audit-state.schema.json
+#      (draft-07 canonical schema, task #18).
+#   2. Otherwise fall back to the inline jq shape check that existed
+#      pre-schema. Same corrupt-rename behavior in both paths.
 set -euo pipefail
-STATE="${1:-docs/super-design/.audit-state.json}"
-if [[ ! -f "$STATE" ]]; then echo '{"status":"missing"}'; exit 2; fi
-jq -e '
-  (.schema_version | type == "string") and
-  (.last_audit_at  | fromdateiso8601 | . > 0) and
-  (.git_sha_at_audit | test("^[0-9a-f]{7,64}$")) and
-  (.skill_version  | type == "string") and
-  (.tools | type == "object")
-' "$STATE" >/dev/null 2>&1 || { echo '{"status":"corrupt"}'; exit 2; }
+ARG="${1:-.}"
+case "$ARG" in
+  *.audit-state.json) STATE="$ARG" ;;
+  .|"")              STATE="docs/super-design/.audit-state.json" ;;
+  *)                 STATE="${ARG%/}/docs/super-design/.audit-state.json" ;;
+esac
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+SCHEMA="$SKILL_DIR/audit-state.schema.json"
+
+# Current schema major is either read from a sibling .schema-version file
+# (so the number can be bumped without editing shell) or falls back to 1.
+SCHEMA_VERSION_FILE="$SKILL_DIR/.schema-version"
+if [ -f "$SCHEMA_VERSION_FILE" ]; then
+  CURRENT_SCHEMA_MAJOR="$(cut -d. -f1 <"$SCHEMA_VERSION_FILE" | tr -d '[:space:]')"
+else
+  CURRENT_SCHEMA_MAJOR=1
+fi
+
+if [ ! -f "$STATE" ]; then echo '{"status":"missing"}'; exit 2; fi
+
+# Parse + shape check. On failure, rename so the user can inspect and we
+# fall through to first-audit (SKILL.md Step 1 treats "corrupt" that way).
+schema_ok=1
+if command -v ajv >/dev/null 2>&1 && [ -f "$SCHEMA" ]; then
+  if ! ajv validate -s "$SCHEMA" -d "$STATE" --errors=text >/dev/null 2>&1; then
+    schema_ok=0
+  fi
+else
+  # Fallback: inline jq shape check (pre-schema behavior).
+  if ! jq -e '
+    (.schema_version | type == "string") and
+    (.last_audit_at  | fromdateiso8601 | . > 0) and
+    (.git_sha_at_audit | test("^[0-9a-f]{7,64}$")) and
+    (.skill_version  | type == "string") and
+    (.tools | type == "object")
+  ' "$STATE" >/dev/null 2>&1; then
+    schema_ok=0
+  fi
+fi
+
+if [ "$schema_ok" -eq 0 ]; then
+  mv "$STATE" "$STATE.corrupt-$(date +%s)" 2>/dev/null || true
+  echo '{"status":"corrupt"}'; exit 2
+fi
+
+# schema_version major-bump check — if state was written by a newer OR
+# incompatible-older skill, force a full re-audit rather than silently
+# trusting the shape.
+STATE_MAJOR="$(jq -r '.schema_version' "$STATE" | cut -d. -f1)"
+if [ -z "$STATE_MAJOR" ] || [ "$STATE_MAJOR" != "$CURRENT_SCHEMA_MAJOR" ]; then
+  echo "{\"status\":\"schema-incompatible\",\"action\":\"force-full\",\"state_major\":\"${STATE_MAJOR:-unknown}\",\"current_major\":\"${CURRENT_SCHEMA_MAJOR}\"}"
+  exit 1
+fi
+
 AGE_DAYS=$(( ( $(date -u +%s) - $(jq -r '.last_audit_at | fromdateiso8601' "$STATE") ) / 86400 ))
-if (( AGE_DAYS > 180 )); then echo "{\"status\":\"stale-force-full\",\"age_days\":$AGE_DAYS}"; exit 1
-elif (( AGE_DAYS > 90 )); then echo "{\"status\":\"stale-refresh-research\",\"age_days\":$AGE_DAYS}"; exit 1
+if [ "$AGE_DAYS" -gt 180 ]; then echo "{\"status\":\"stale-force-full\",\"age_days\":$AGE_DAYS}"; exit 1
+elif [ "$AGE_DAYS" -gt 90 ]; then echo "{\"status\":\"stale-refresh-research\",\"age_days\":$AGE_DAYS}"; exit 1
 else echo "{\"status\":\"fresh\",\"age_days\":$AGE_DAYS}"; exit 0; fi

package/template/.claude/skills/super-design/scripts/verify-audit.sh

@@ -1,19 +1,72 @@
 #!/usr/bin/env bash
+# Usage: verify-audit.sh [--strict] <session_dir>
+#
+# Verifies the artifacts produced by an sd-audit session:
+#   1. .audit-state.json exists and passes validate-state.sh
+#      (so the schema task #18 schema is actually enforced end-to-end).
+#   2. findings.json exists and parses as a JSON array.
+#   3. Every finding has a SHOT (screenshot_path) + SNAP (snapshot_path)
+#      that resolves to a non-empty file on disk.
+#   4. Every finding's snapshot_quote appears verbatim in its snapshot.
+#
+# Exit codes:
+#   0  OK (no errors, no warnings — or warnings present without --strict)
+#   1  non-fatal warning in --strict mode, or verification failure
+#   2  missing prerequisites (session dir / findings.json)
 set -euo pipefail
-SESSION_DIR="${1:?usage: verify-audit.sh <session_dir>}"
+
+STRICT=0
+if [ "${1:-}" = "--strict" ]; then STRICT=1; shift; fi
+
+SESSION_DIR="${1:?usage: verify-audit.sh [--strict] <session_dir>}"
 FINDINGS="$SESSION_DIR/findings.json"
-if [[ ! -f "$FINDINGS" ]]; then echo "FATAL: no findings.json at $FINDINGS" >&2; exit 2; fi
+SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+VALIDATE="$SKILL_DIR/scripts/validate-state.sh"
+STATE="${AUDIT_STATE:-docs/super-design/.audit-state.json}"
+
+WARNINGS=0
+warn() { echo "WARN: $*" >&2; WARNINGS=$((WARNINGS + 1)); }
 
-jq -r '.[] | [.id, .screenshot_path, .snapshot_path] | @tsv' "$FINDINGS" | while IFS=$'\t' read -r id shot snap; do
-  if [[ ! -s "$shot" ]]; then echo "FAIL $id: missing/empty screenshot $shot" >&2; exit 1; fi
-  if [[ ! -s "$snap" ]]; then echo "FAIL $id: missing/empty snapshot $snap" >&2; exit 1; fi
+# 1. State file schema check — non-fatal (state may live outside session
+#    dir, or may legitimately be absent on first run). In --strict mode
+#    any anomaly counts as a warning.
+if [ ! -f "$STATE" ]; then
+  warn "no audit state at $STATE (first audit? expected on CI)"
+else
+  if ! bash "$VALIDATE" "$STATE" >/dev/null 2>&1; then
+    warn "validate-state.sh rejected $STATE (schema drift or stale)"
+  fi
+fi
+
+# 2. findings.json must exist and parse.
+if [ ! -f "$FINDINGS" ]; then
+  echo "FATAL: no findings.json at $FINDINGS" >&2; exit 2
+fi
+if ! jq -e 'type == "array"' "$FINDINGS" >/dev/null 2>&1; then
+  echo "FATAL: $FINDINGS is not a JSON array" >&2; exit 1
+fi
+
+# 3. Every referenced screenshot/snapshot resolves to a non-empty file.
+jq -r '.[] | [.id, .screenshot_path, .snapshot_path] | @tsv' "$FINDINGS" | \
+while IFS=$'\t' read -r id shot snap; do
+  if [ ! -s "$shot" ]; then echo "FAIL $id: missing/empty screenshot $shot" >&2; exit 1; fi
+  if [ ! -s "$snap" ]; then echo "FAIL $id: missing/empty snapshot $snap" >&2; exit 1; fi
 done
 
+# 4. snapshot_quote must appear verbatim in the snapshot.
 jq -c '.[]' "$FINDINGS" | while read -r f; do
   id=$(echo "$f" | jq -r .id)
-  q=$(echo "$f" | jq -r .snapshot_quote)
-  s=$(echo "$f" | jq -r .snapshot_path)
-  if ! grep -qF "$q" "$s"; then echo "FAIL $id: quote not found verbatim in $s" >&2; exit 1; fi
+  q=$(echo "$f"  | jq -r .snapshot_quote)
+  s=$(echo "$f"  | jq -r .snapshot_path)
+  if ! grep -qF "$q" "$s"; then
+    echo "FAIL $id: quote not found verbatim in $s" >&2; exit 1
+  fi
 done
 
-echo "OK: $(jq 'length' "$FINDINGS") findings verified"
+COUNT=$(jq 'length' "$FINDINGS")
+if [ "$STRICT" -eq 1 ] && [ "$WARNINGS" -gt 0 ]; then
+  echo "STRICT: $COUNT findings verified, $WARNINGS warning(s)" >&2
+  exit 1
+fi
+
+echo "OK: $COUNT findings verified${WARNINGS:+ ($WARNINGS warning(s))}"