quiver-cli 0.7.0 → 1.0.0

package/template/.agents/skills/design/impeccable/scripts/generate-image.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+/**
+ * API image generation fallback: renders a mock or world board with the
+ * user's own OpenAI key when the harness has no native image generation.
+ *
+ * context.mjs reports availability (it checks OPENAI_API_KEY); harness-native
+ * generation always wins when present. This uses gpt-image-2 and spends the
+ * user's API credit (roughly $0.05-0.25 per image at default quality), so the
+ * skill states that before the first call in a session.
+ *
+ *   node generate-image.mjs --prompt "..." --out mock.png [--size 1536x1024] [--quality medium]
+ *   node generate-image.mjs --prompt-file prompt.txt --out mock.png
+ */
+import fs from 'node:fs';
+import zlib from 'node:zlib';
+
+function arg(name, fallback = null) {
+  const i = process.argv.indexOf(`--${name}`);
+  if (i === -1) return fallback;
+  const v = process.argv[i + 1];
+  return v && !v.startsWith('--') ? v : fallback;
+}
+
+// ---------------------------------------------------------------------------
+// Fake mode (IMPECCABLE_IMAGE_GEN_FAKE=1)
+//
+// Deterministic offline stand-in for the OpenAI call: same prompt -> identical
+// bytes, no network, no key, cost line reads $0.00. Used by the new-work smoke
+// suite so the concept/serve-question/image chain can run without spend. The
+// output renders the prompt over a 2-3 color palette hashed from the prompt,
+// plus a "SYNTHETIC COMP" corner label. SVG carries the readable text; the
+// raster (.png/.webp/.jpg) fallback carries palette stripes and stows the
+// prompt + marker in a PNG tEXt chunk so downstream stays a valid image.
+// ---------------------------------------------------------------------------
+
+// FNV-1a 32-bit: tiny, dependency-free, stable across runs and platforms.
+function hash32(str) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 0x01000193);
+  }
+  return h >>> 0;
+}
+
+function hslToRgb(hDeg, s, l) {
+  const h = ((hDeg % 360) + 360) % 360 / 360;
+  const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+  const p = 2 * l - q;
+  const hue = (t) => {
+    let tt = t;
+    if (tt < 0) tt += 1;
+    if (tt > 1) tt -= 1;
+    if (tt < 1 / 6) return p + (q - p) * 6 * tt;
+    if (tt < 1 / 2) return q;
+    if (tt < 2 / 3) return p + (q - p) * (2 / 3 - tt) * 6;
+    return p;
+  };
+  return [hue(h + 1 / 3), hue(h), hue(h - 1 / 3)].map((c) => Math.round(c * 255));
+}
+
+const toHex = ([r, g, b]) =>
+  '#' + [r, g, b].map((c) => c.toString(16).padStart(2, '0')).join('');
+
+// Two or three deterministic swatches derived from the prompt hash. The band
+// count itself is prompt-derived, so different prompts differ in palette.
+function palette(prompt) {
+  const h = hash32(prompt);
+  const base = h % 360;
+  const bands = 2 + (h >>> 9) % 2; // 2 or 3
+  const spread = 40 + (h >>> 3) % 120;
+  const out = [];
+  for (let i = 0; i < bands; i++) {
+    const hue = base + i * spread;
+    const light = 0.32 + ((h >>> (i * 5)) % 40) / 100; // 0.32 - 0.71
+    out.push(hslToRgb(hue, 0.55, light));
+  }
+  return out;
+}
+
+function svgFake(prompt, [w, h]) {
+  const colors = palette(prompt).map(toHex);
+  const stops = colors
+    .map((c, i) => `<stop offset="${Math.round((i / (colors.length - 1)) * 100)}%" stop-color="${c}"/>`)
+    .join('');
+  // Greedy word wrap tuned to the canvas width so the prompt stays legible.
+  const perLine = Math.max(12, Math.floor(w / 26));
+  const words = String(prompt).replace(/\s+/g, ' ').trim().split(' ');
+  const lines = [];
+  let cur = '';
+  for (const word of words) {
+    if ((cur + ' ' + word).trim().length > perLine) {
+      if (cur) lines.push(cur);
+      cur = word;
+    } else {
+      cur = (cur + ' ' + word).trim();
+    }
+    if (lines.length >= 10) break;
+  }
+  if (cur && lines.length < 11) lines.push(cur);
+  const escape = (s) => String(s).replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
+  const fontSize = Math.round(w / 24);
+  const startY = h / 2 - ((lines.length - 1) * fontSize * 1.3) / 2;
+  const text = lines
+    .map((line, i) => `<text x="${w / 2}" y="${Math.round(startY + i * fontSize * 1.3)}" font-family="Helvetica, Arial, sans-serif" font-size="${fontSize}" fill="#ffffff" text-anchor="middle" dominant-baseline="middle">${escape(line)}</text>`)
+    .join('');
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
+  <defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1">${stops}</linearGradient></defs>
+  <rect width="${w}" height="${h}" fill="url(#g)"/>
+  <rect x="0" y="0" width="${w}" height="${h}" fill="#000000" fill-opacity="0.22"/>
+  ${text}
+  <rect x="${w - Math.round(w / 4.2)}" y="${h - Math.round(h / 16)}" width="${Math.round(w / 4.2)}" height="${Math.round(h / 16)}" fill="#000000" fill-opacity="0.55"/>
+  <text x="${w - Math.round(w / 8.4)}" y="${h - Math.round(h / 32)}" font-family="Helvetica, Arial, sans-serif" font-size="${Math.round(w / 60)}" letter-spacing="2" fill="#ffffff" text-anchor="middle" dominant-baseline="middle">SYNTHETIC COMP</text>
+</svg>
+`;
+}
+
+// Minimal valid PNG: palette stripes plus a tEXt chunk carrying the marker and
+// prompt, so a .png/.webp fake stays a decodable image and still contains the
+// "SYNTHETIC" bytes downstream tools look for.
+function crc32(buf) {
+  let c = 0xffffffff;
+  for (let i = 0; i < buf.length; i++) {
+    c ^= buf[i];
+    for (let k = 0; k < 8; k++) c = (c & 1) ? (0xedb88320 ^ (c >>> 1)) : (c >>> 1);
+  }
+  return (c ^ 0xffffffff) >>> 0;
+}
+
+function pngChunk(type, data) {
+  const typeBuf = Buffer.from(type, 'latin1');
+  const body = Buffer.concat([typeBuf, data]);
+  const len = Buffer.alloc(4);
+  len.writeUInt32BE(data.length, 0);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([len, body, crc]);
+}
+
+function pngFake(prompt, [w, h]) {
+  const colors = palette(prompt); // [[r,g,b], ...]
+  const bandH = Math.ceil(h / colors.length);
+  // Raw image: each scanline prefixed with a 0 filter byte, RGB pixels.
+  const stride = w * 3;
+  const raw = Buffer.alloc(h * (stride + 1));
+  for (let y = 0; y < h; y++) {
+    const rowStart = y * (stride + 1);
+    raw[rowStart] = 0;
+    const [r, g, b] = colors[Math.min(colors.length - 1, Math.floor(y / bandH))];
+    for (let x = 0; x < w; x++) {
+      const p = rowStart + 1 + x * 3;
+      raw[p] = r;
+      raw[p + 1] = g;
+      raw[p + 2] = b;
+    }
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(w, 0);
+  ihdr.writeUInt32BE(h, 4);
+  ihdr[8] = 8;  // bit depth
+  ihdr[9] = 2;  // color type: truecolor RGB
+  const idat = zlib.deflateSync(raw, { level: 9 });
+  const textData = Buffer.concat([
+    Buffer.from('Comment', 'latin1'),
+    Buffer.from([0]),
+    Buffer.from(`SYNTHETIC COMP: ${String(prompt).replace(/\s+/g, ' ').trim()}`, 'latin1'),
+  ]);
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    pngChunk('IHDR', ihdr),
+    pngChunk('tEXt', textData),
+    pngChunk('IDAT', idat),
+    pngChunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+function parseSize(sizeStr) {
+  const m = String(sizeStr).match(/^(\d+)x(\d+)$/);
+  if (!m) return [1536, 1024];
+  return [Number(m[1]), Number(m[2])];
+}
+
+if (process.env.IMPECCABLE_IMAGE_GEN_FAKE) {
+  const fakePromptFile = arg('prompt-file');
+  const fakePrompt = fakePromptFile ? fs.readFileSync(fakePromptFile, 'utf8') : arg('prompt');
+  const fakeOut = arg('out');
+  if (!fakePrompt || !fakeOut) {
+    console.error('generate-image: --prompt (or --prompt-file) and --out are required.');
+    process.exit(1);
+  }
+  const dims = parseSize(arg('size', '1536x1024'));
+  const bytes = fakeOut.endsWith('.svg')
+    ? Buffer.from(svgFake(fakePrompt, dims), 'utf8')
+    : pngFake(fakePrompt, dims);
+  fs.writeFileSync(fakeOut, bytes);
+  console.log(`IMAGE: ${fakeOut} (${dims[0]}x${dims[1]}, fake synthetic comp, $0.00, no API call)`);
+  process.exit(0);
+}
+
+const key = process.env.OPENAI_API_KEY;
+if (!key) {
+  console.error('generate-image: OPENAI_API_KEY is not set; use the harness-native image tool instead.');
+  process.exit(1);
+}
+const promptFile = arg('prompt-file');
+const prompt = promptFile ? fs.readFileSync(promptFile, 'utf8') : arg('prompt');
+const out = arg('out');
+if (!prompt || !out) {
+  console.error('generate-image: --prompt (or --prompt-file) and --out are required.');
+  process.exit(1);
+}
+const size = arg('size', '1536x1024');
+const quality = arg('quality', 'medium');
+
+const response = await fetch('https://api.openai.com/v1/images/generations', {
+  method: 'POST',
+  headers: { Authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+  body: JSON.stringify({ model: 'gpt-image-2', prompt, size, quality, n: 1 }),
+});
+if (!response.ok) {
+  console.error(`generate-image: API error ${response.status}: ${(await response.text()).slice(0, 300)}`);
+  process.exit(1);
+}
+const json = await response.json();
+const b64 = json?.data?.[0]?.b64_json;
+if (!b64) {
+  console.error('generate-image: no image in response');
+  process.exit(1);
+}
+fs.writeFileSync(out, Buffer.from(b64, 'base64'));
+// The prompt travels with the asset: embedded in the file itself (EXIF-class
+// metadata via embed-prompt.mjs) so intent survives copies across harnesses,
+// plus a sidecar for anything that indexes rather than opens the image.
+try {
+  const { spawnSync } = await import('node:child_process');
+  spawnSync(process.execPath, [new URL('./embed-prompt.mjs', import.meta.url).pathname, out, '--prompt', prompt], { stdio: 'ignore' });
+  fs.writeFileSync(`${out}.json`, JSON.stringify({ prompt, createdAt: new Date().toISOString(), tool: 'generate-image.mjs', model: 'gpt-image-2' }, null, 2));
+} catch { /* embedding is best-effort */ }
+console.log(`IMAGE: ${out} (${size}, ${quality}, gpt-image-2, billed to your OpenAI key); prompt embedded + sidecar at ${out}.json`);

package/template/.agents/skills/design/impeccable/scripts/hook-admin.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * `/impeccable hooks <on|off|status|reset>` — manage the design hook runtime
+ * The Impeccable hooks command manages the design hook runtime
  * via the `hook` key and shared detector ignores via the `detector` key in
  * .impeccable/config.json / .impeccable/config.local.json.
  *
@@ -13,6 +13,8 @@
  *   node hook-admin.mjs ignore-file <glob>             # append to ignoreFiles
  *   node hook-admin.mjs ignore-value <rule> <value>    # append to shared ignoreValues
  *   node hook-admin.mjs ignore-value <rule> <value> --local
+ *   node hook-admin.mjs ignore-value <rule> "*" --file <glob>   # rule off in <glob> only
+ *   node hook-admin.mjs ignore-value <rule> "*"                 # refused: scope it or use ignore-rule
  *   node hook-admin.mjs reset                          # remove all config + cache
  *
  * Designed to be invoked by the LLM from the reference/hooks.md flow.
@@ -21,6 +23,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { IMPECCABLE_COMMAND } from './lib/provider.mjs';
 
 import {
   getConfigPath,
@@ -44,6 +47,26 @@ const IMPECCABLE_HOOK_COMMAND_MARKERS = [
 ];
 const TIMEOUT_SECONDS = 5;
 const STATUS_MESSAGE = 'Checking UI changes';
+// The Stop deep pass scans every UI file touched in the session with the full
+// rule set, so it gets a longer budget than the per-edit pass. Only Claude
+// Code and Codex dispatch a native Stop hook event, so only those manifests
+// carry the entry. Keep these shapes in sync with
+// scripts/lib/transformers/hooks.js in the repo.
+const STOP_TIMEOUT_SECONDS = 30;
+const STOP_STATUS_MESSAGE = 'Design deep pass';
+
+function stopManifestEntry(command) {
+  return {
+    hooks: [
+      {
+        type: 'command',
+        command,
+        timeout: STOP_TIMEOUT_SECONDS,
+        statusMessage: STOP_STATUS_MESSAGE,
+      },
+    ],
+  };
+}
 
 const HOOK_MANIFEST_TARGETS = [
   {
@@ -52,7 +75,7 @@ const HOOK_MANIFEST_TARGETS = [
     destRel: '.claude/settings.local.json',
     sharedDestRel: '.claude/settings.json',
     manifest: () => ({
-      description: 'Impeccable design detector: runs after Edit/Write/MultiEdit on UI files and surfaces findings as system reminders.',
+      description: 'Impeccable design detector: immediate-tier checks after Edit/Write/MultiEdit on UI files, full-rule deep pass on Stop.',
       hooks: {
         PostToolUse: [
           {
@@ -67,6 +90,7 @@ const HOOK_MANIFEST_TARGETS = [
             ],
           },
         ],
+        Stop: [stopManifestEntry('node "${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/hook.mjs"')],
       },
     }),
   },
@@ -75,7 +99,6 @@ const HOOK_MANIFEST_TARGETS = [
     skillRel: '.agents/skills/impeccable',
     destRel: '.codex/hooks.json',
     manifest: () => ({
-      description: 'Impeccable design detector: runs after Edit/Write/apply_patch on UI files and surfaces findings as system reminders.',
       hooks: {
         PostToolUse: [
           {
@@ -83,13 +106,14 @@ const HOOK_MANIFEST_TARGETS = [
             hooks: [
               {
                 type: 'command',
-                command: 'node "$(git rev-parse --show-toplevel)/.agents/skills/impeccable/scripts/hook.mjs"',
+                command: 'node ".agents/skills/impeccable/scripts/hook.mjs"',
                 timeout: TIMEOUT_SECONDS,
                 statusMessage: STATUS_MESSAGE,
               },
             ],
           },
         ],
+        Stop: [stopManifestEntry('node ".agents/skills/impeccable/scripts/hook.mjs"')],
       },
     }),
   },
@@ -185,7 +209,7 @@ function writeHookConfig(cwd, hookConfig, opts = {}) {
   const existing = existingRaw && typeof existingRaw === 'object' && !Array.isArray(existingRaw) ? existingRaw : {};
   const existingHook = stripDetectorKeys(hookSection(existing));
   // Merge over the existing hook object so fields the merge helpers don't manage
-  // (consent, quiet, auditLog) survive a `/impeccable hooks` edit.
+  // (consent, quiet, auditLog) survive an Impeccable hooks edit.
   const next = { ...existing, hook: { ...existingHook, ...hookConfig } };
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, JSON.stringify(next, null, 2) + '\n');
@@ -265,7 +289,10 @@ function mergeIgnoreValueEntries(existing, incoming) {
 }
 
 function ignoreValueEntryKey(entry) {
-  const files = Array.isArray(entry.files) && entry.files.length > 0 ? entry.files.join('\x1f') : '';
+  // Sorted: a file scope is a set. Comparing stored order made an on-disk scope
+  // miss the sorted argv form, so a re-add duplicated the entry and a remove
+  // silently failed. Every key that hashes `files` must sort — there are four.
+  const files = Array.isArray(entry.files) && entry.files.length > 0 ? [...entry.files].sort().join('\x1f') : '';
   return `${entry.rule}\0${entry.value}\0${files}`;
 }
 
@@ -283,7 +310,14 @@ function statusReport(cwd) {
     if (info.exists) return relPath;
     return `${relPath} (${absent})`;
   };
-  const ignoreValues = cfg.ignoreValues.map((entry) => `${entry.rule}=${entry.value}`);
+  // Show the file scope. Dropping it rendered a file-scoped entry as
+  // `design-system-font-size=*`, which reads as the project-wide wildcard this
+  // command refuses — the opposite of what is on disk. Matches the
+  // `rule=value [files]` shape `impeccable ignores list` already prints.
+  const ignoreValues = cfg.ignoreValues.map((entry) => {
+    const scope = Array.isArray(entry.files) && entry.files.length ? ` [${entry.files.join(', ')}]` : '';
+    return `${entry.rule}=${entry.value}${scope}`;
+  });
 
   const lines = [
     `Impeccable design hook`,
@@ -514,9 +548,9 @@ function parseIgnoreRuleArgs(args) {
 function addIgnoreRule(cwd, args) {
   const parsed = parseIgnoreRuleArgs(args);
   const rule = parsed.rule;
-  if (!rule) throw new Error('Pass a rule id, e.g. /impeccable hooks ignore-rule side-tab');
+  if (!rule) throw new Error(`Pass a rule id, e.g. ${IMPECCABLE_COMMAND} hooks ignore-rule side-tab`);
   if (rule === 'overused-font' && !parsed.allValues) {
-    throw new Error('overused-font is value-specific by default. Use /impeccable hooks ignore-value overused-font <font> for a confirmed font, or /impeccable hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.');
+    throw new Error(`overused-font is value-specific by default. Use ${IMPECCABLE_COMMAND} hooks ignore-value overused-font <font> for a confirmed font, or ${IMPECCABLE_COMMAND} hooks ignore-rule overused-font --all-values only when the user asked to ignore overused fonts generally.`);
   }
   const config = mergeDetectorConfig(readRawDetectorConfig(cwd));
   if (!config.ignoreRules.includes(rule)) config.ignoreRules.push(rule);
@@ -525,21 +559,36 @@ function addIgnoreRule(cwd, args) {
 }
 
 function addIgnoreFile(cwd, glob) {
-  if (!glob) throw new Error('Pass a glob, e.g. /impeccable hooks ignore-file "src/legacy/**"');
+  if (!glob) throw new Error(`Pass a glob, e.g. ${IMPECCABLE_COMMAND} hooks ignore-file "src/legacy/**"`);
   const config = mergeDetectorConfig(readRawDetectorConfig(cwd));
   if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
   writeDetectorConfig(cwd, config);
   return `Added "${glob}" to detector.ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
 }
 
+// An empty glob used to be dropped by filter(Boolean), so `--file=` reported
+// success and wrote an entry with no files: the user asked to scope a rule to one
+// file and silently got the project-wide suppression instead. Refuse it.
+function requireGlob(raw, flag) {
+  const glob = String(raw ?? '').trim();
+  if (!glob) throw new Error(`${flag} requires a non-empty glob`);
+  // A following flag is not a glob. `--file --reason "why"` consumed `--reason`
+  // as the scope and left the reason text to fold into the value, storing
+  // value="* why" files=["--reason"] and reporting success. Same silent-no-op
+  // class as an unknown flag folding into the value; refuse it the same way.
+  if (glob.startsWith('--')) throw new Error(`${flag} requires a glob, got the flag ${glob}`);
+  return glob;
+}
+
 function parseIgnoreValueArgs(args) {
   const positionals = [];
+  const files = [];
   let shared = false;
   let local = false;
   let reason = '';
 
   for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
+    const arg = String(args[i] || '');
     if (arg === '--shared') {
       shared = true;
     } else if (arg === '--local') {
@@ -550,8 +599,20 @@ function parseIgnoreValueArgs(args) {
         chunks.push(args[++i]);
       }
       reason = chunks.join(' ').trim();
-    } else if (String(arg).startsWith('--reason=')) {
-      reason = String(arg).slice('--reason='.length).trim();
+    } else if (arg.startsWith('--reason=')) {
+      reason = arg.slice('--reason='.length).trim();
+    } else if (arg === '--file' || arg === '--files') {
+      if (i + 1 >= args.length) throw new Error(`${arg} requires a glob`);
+      files.push(requireGlob(args[++i], arg));
+    } else if (arg.startsWith('--file=')) {
+      files.push(requireGlob(arg.slice('--file='.length), '--file'));
+    } else if (arg.startsWith('--files=')) {
+      files.push(requireGlob(arg.slice('--files='.length), '--files'));
+    } else if (arg.startsWith('--')) {
+      // Otherwise a typo folds into the value: `ignore-value overused-font Inter
+      // --shard` stored the value "inter --shard", which matches no finding, and
+      // reported success. Matches `impeccable ignores add-value`.
+      throw new Error(`Unknown ignore-value flag: ${arg}`);
     } else {
       positionals.push(arg);
     }
@@ -561,6 +622,9 @@ function parseIgnoreValueArgs(args) {
   return {
     rule: String(rule || '').trim().toLowerCase(),
     value: normalizeIgnoreValue(valueParts.join(' ')),
+    // Sorted: the dedup key compares the files array, so an unsorted scope made
+    // `--file b.css --file a.css` a different entry from `--file a.css --file b.css`.
+    files: Array.from(new Set(files.filter(Boolean))).sort(),
     shared,
     local,
     reason,
@@ -570,17 +634,31 @@ function parseIgnoreValueArgs(args) {
 function addIgnoreValue(cwd, args) {
   const parsed = parseIgnoreValueArgs(args);
   if (!parsed.rule || !parsed.value) {
-    throw new Error('Pass a rule id and value, e.g. /impeccable hooks ignore-value overused-font Inter');
+    throw new Error(`Pass a rule id and value, e.g. ${IMPECCABLE_COMMAND} hooks ignore-value overused-font Inter`);
   }
 
   if (parsed.shared && parsed.local) {
     throw new Error('Pass only one scope flag: --shared or --local');
   }
 
+  // A bare `*` would suppress the rule everywhere, which is ignore-rule's job and
+  // not what a finding in one file justifies. detector.ignoreValues honours a
+  // `files` scope, so require one — matching `impeccable ignores add-value`.
+  if (parsed.value === '*' && parsed.files.length === 0) {
+    // `ignore-rule overused-font` refuses on its own without --all-values, so
+    // naming the bare form here would hand the user a second error.
+    const projectWide = parsed.rule === 'overused-font'
+      ? `${IMPECCABLE_COMMAND} hooks ignore-rule ${parsed.rule} --all-values`
+      : `${IMPECCABLE_COMMAND} hooks ignore-rule ${parsed.rule}`;
+    throw new Error(`Wildcard value ignores must be scoped with --file <glob>, e.g. ${IMPECCABLE_COMMAND} hooks ignore-value design-system-font-size "*" --file "src/widget.js". To suppress the rule project-wide use ${projectWide}.`);
+  }
+
   const local = parsed.local;
   const config = mergeDetectorConfig(readRawDetectorConfig(cwd, { local }));
-  const key = `${parsed.rule}\0${parsed.value}`;
-  const existing = config.ignoreValues.find((entry) => `${entry.rule}\0${entry.value}` === key);
+  // Key on the file scope too: the same rule/value legitimately appears more than
+  // once with different scopes, and a rule+value-only key overwrote them.
+  const key = ignoreValueEntryKey({ rule: parsed.rule, value: parsed.value, files: parsed.files });
+  const existing = config.ignoreValues.find((entry) => ignoreValueEntryKey(entry) === key);
 
   if (existing) {
     if (parsed.reason) existing.reason = parsed.reason;
@@ -588,15 +666,17 @@ function addIgnoreValue(cwd, args) {
     const entry = {
       rule: parsed.rule,
       value: parsed.value,
-      createdAt: new Date().toISOString(),
     };
+    if (parsed.files.length) entry.files = parsed.files;
+    entry.createdAt = new Date().toISOString();
     if (parsed.reason) entry.reason = parsed.reason;
     config.ignoreValues.push(entry);
   }
 
   const target = writeDetectorConfig(cwd, config, { local });
   const scope = local ? 'local detector.ignoreValues' : 'shared detector.ignoreValues';
-  return `Added ${parsed.rule}=${parsed.value} to ${scope} (${path.relative(cwd, target) || target}).`;
+  const scopeSuffix = parsed.files.length ? ` scoped to ${parsed.files.join(', ')}` : '';
+  return `Added ${parsed.rule}=${parsed.value}${scopeSuffix} to ${scope} (${path.relative(cwd, target) || target}).`;
 }
 
 function reset(cwd) {

package/template/.agents/skills/design/impeccable/scripts/hook-before-edit.mjs

@@ -11,6 +11,7 @@
  */
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 
 import {
@@ -21,13 +22,17 @@ import {
   appendDesignSystemNote,
   designSystemOptions,
   filterFindings,
+  isNativePlatform,
   loadDetector,
+  matchConfiguredExtension,
   matchesAnyGlob,
   persistCache,
   readCache,
   readConfig,
   renderTemplate,
+  resolveCacheCwd,
   resolveProjectCwd,
+  resolveProjectPlatform,
   truthy,
   writeAuditLog,
 } from './hook-lib.mjs';
@@ -332,6 +337,22 @@ function isInsideProject(filePath, cwd) {
   }
 }
 
+// The static HTML engine reads its input from disk, but preToolUse only has
+// the proposed content. Stage it in a temp file so html-engine targets get the
+// same DOM-structural rules pre-write that runHook applies post-edit.
+async function detectProposedHtml(detector, content, filePath, scanOptions) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'impeccable-pre-'));
+  const tmpFile = path.join(dir, path.basename(filePath));
+  try {
+    fs.writeFileSync(tmpFile, content);
+    const findings = await detector.detectHtml(tmpFile, scanOptions);
+    // Findings carry the temp path; remap so file-scoped ignores still match.
+    return (findings || []).map((f) => (f && typeof f === 'object' ? { ...f, file: filePath } : f));
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
 function cursorBlockMessage(findings, filePath, config, cwd) {
   const rendered = renderTemplate(findings, filePath, config, { cwd });
   const blocked = rendered.replace(
@@ -379,9 +400,12 @@ async function main() {
     return allow({ skipped: 'stdin-empty' });
   }
 
-  const cwd = resolveProjectCwd(event);
+  const sessionCwd = resolveProjectCwd(event);
   const started = Date.now();
-  const filePath = proposedFilePath(event, cwd);
+  const filePath = proposedFilePath(event, sessionCwd);
+  // Re-key config/cache to the edited file's project root when the session
+  // was launched from a non-project umbrella directory (issue #305).
+  const cwd = resolveCacheCwd(filePath, sessionCwd);
   const audit = {
     harness: 'cursor',
     cwd,
@@ -394,9 +418,13 @@ async function main() {
   if (SENSITIVE_PATH.test(filePath)) return allow({ ...audit, skipped: 'sensitive', durationMs: Date.now() - started });
   if (GENERATED_PATH.test(filePath)) return allow({ ...audit, skipped: 'generated', durationMs: Date.now() - started });
 
+  // Config is read before the extension gate so `detector.extensions` entries
+  // (e.g. `.blade.php` template files, issue #316) can widen it.
+  const config = readConfig(cwd);
   const ext = path.extname(filePath).toLowerCase();
-  audit.ext = ext;
-  if (!ALLOWED_EXTS.has(ext)) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
+  const configuredExt = matchConfiguredExtension(filePath, config.extensions);
+  audit.ext = configuredExt ? configuredExt.ext : ext;
+  if (!ALLOWED_EXTS.has(ext) && !configuredExt) return allow({ ...audit, skipped: 'extension', durationMs: Date.now() - started });
 
   const contentResult = proposedContent(event, cwd, filePath);
   if (contentResult && typeof contentResult === 'object' && contentResult.skipped) {
@@ -405,9 +433,14 @@ async function main() {
   const content = typeof contentResult === 'string' ? contentResult : '';
   if (!content) return allow({ ...audit, skipped: 'no-proposed-content', durationMs: Date.now() - started });
 
-  const config = readConfig(cwd);
   if (config.enabled === false) return allow({ ...audit, skipped: 'config-disabled', durationMs: Date.now() - started });
 
+  // Web rule engine, native project: stand aside (see resolveProjectPlatform).
+  const platform = resolveProjectPlatform(cwd);
+  if (isNativePlatform(platform)) {
+    return allow({ ...audit, skipped: 'native-platform', platform, durationMs: Date.now() - started });
+  }
+
   const rel = relativePath(filePath, cwd);
   if (matchesAnyGlob(rel, config.ignoreFiles) || matchesAnyGlob(filePath, config.ignoreFiles)) {
     return allow({ ...audit, skipped: 'config-ignore-file', durationMs: Date.now() - started });
@@ -419,9 +452,16 @@ async function main() {
   }
   const scanOptions = designSystemOptions(config, detector, cwd);
 
+  // Mirror runHook's engine routing so template issues the HTML engine catches
+  // post-edit cannot slip past the pre-write gate.
+  const useHtmlEngine = configuredExt
+    ? configuredExt.engine === 'html'
+    : (ext === '.html' || ext === '.htm');
   let findings = [];
   try {
-    findings = await detector.detectText(content, filePath, scanOptions);
+    findings = useHtmlEngine && typeof detector.detectHtml === 'function'
+      ? await detectProposedHtml(detector, content, filePath, scanOptions)
+      : await detector.detectText(content, filePath, scanOptions);
   } catch {
     return allow({ ...audit, error: 'detector-threw', durationMs: Date.now() - started });
   }