quiver-cli 1.3.0 → 1.3.1

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

@@ -10,8 +10,27 @@
  *
  *   node generate-image.mjs --prompt "..." --out mock.png [--size 1536x1024] [--quality medium]
  *   node generate-image.mjs --prompt-file prompt.txt --out mock.png
+ *   node generate-image.mjs --prompt "..." --out mock.png --ref screenshot.png [--ref more.png]
+ *
+ * --ref anchors generation on input image(s) via the edits endpoint: pass a
+ * captured screenshot of a representative existing page when comping a new
+ * surface for an established world, so the identity comes from the real UI.
+ *
+ *   node generate-image.mjs --plate <region-id> [--spec .impeccable/build/spec.json] [--quality high]
+ *
+ * --plate produces a shipping raster for one raster region of the measured
+ * comp spec (comp-spec.mjs): it crops the region from the approved comp,
+ * sends the crop as the reference with the spec's plate prompt (plus any
+ * --prompt you add), picks the closest supported output size to the region's
+ * aspect, writes the result to the region's `plate` path, embeds the prompt,
+ * and scores the plate against the comp crop with comp-diff so a plate that
+ * does not read as the region is reported (and, with --min, refused) here,
+ * before it lands on the page. In IMPECCABLE_IMAGE_GEN_FAKE mode the plate is
+ * the crop itself at 2x, so offline pipelines can walk the plate gate.
  */
 import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import zlib from 'node:zlib';
 
 function arg(name, fallback = null) {
@@ -181,6 +200,154 @@ function parseSize(sizeStr) {
   return [Number(m[1]), Number(m[2])];
 }
 
+// ---------------------------------------------------------------------------
+// Plate mode: one raster region of the measured spec -> a shipping plate.
+// ---------------------------------------------------------------------------
+const plateId = arg('plate');
+let plateCtx = null;
+if (plateId) {
+  const { loadSpec, platePrompt, plateReference, SPEC_PATH } = await import('./comp-spec.mjs');
+  const { decodePng, encodePng, loadRaster } = await import('./lib/png.mjs');
+  const { crop, resize } = await import('./lib/raster.mjs');
+  const specPath = arg('spec', SPEC_PATH);
+  const spec = loadSpec(specPath);
+  if (!spec) { console.error(`generate-image: no spec at ${specPath}; run comp-spec.mjs first`); process.exit(1); }
+  const region = spec.regions.find((r) => r.id === plateId);
+  if (!region) { console.error(`generate-image: no region ${plateId} in ${specPath}; ids: ${spec.regions.map((r) => r.id).join(', ')}`); process.exit(1); }
+  if (region.medium !== 'raster') { console.error(`generate-image: region ${plateId} is ${region.medium}, not a plate; set its kind to plate|image|texture in the regions file`); process.exit(1); }
+  let comp;
+  try { comp = loadRaster(spec.comp).image; } catch (e) { console.error(`generate-image: cannot read comp ${spec.comp}: ${e.message}`); process.exit(1); }
+  const ref = plateReference(comp, spec, region);
+  const refPath = path.join(path.dirname(specPath), 'crops', `${region.id}.png`);
+  fs.mkdirSync(path.dirname(refPath), { recursive: true });
+  fs.writeFileSync(refPath, encodePng(ref, { text: { 'impeccable:crop-of': `${spec.comp}#${region.id}` } }));
+  const out = arg('out', region.plate);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  // Closest supported size to the region's aspect; the page crops the rest
+  // with object-fit. The plates gate demands >= 1.5x the region's width
+  // (capped at 1536), so a square region wider than 682px cannot ship from
+  // 1024x1024: take the 1536-wide landscape frame instead and let cover crop.
+  const aspect = region.px.w / region.px.h;
+  const needW = Math.min(1536, Math.ceil(region.px.w * 1.5));
+  let size = arg('size');
+  if (!size) {
+    if (aspect > 1.2) size = '1536x1024';
+    else if (aspect < 0.83) size = needW > 1024 ? '1536x1024' : '1024x1536';
+    else size = needW > 1024 ? '1536x1024' : '1024x1024';
+  }
+  const extra = arg('prompt') || (arg('prompt-file') ? fs.readFileSync(arg('prompt-file'), 'utf8') : '');
+  // Chroma: an ink-on-ground plate (a line drawing, a figure on flat ground)
+  // is generated on a flat key color and keyed to alpha, so the page's own
+  // ground shows through instead of a second, mismatched paper. Default on
+  // for kind plate when the comp region reads as ink over one flat ground;
+  // --chroma / --no-chroma force it.
+  const wantsChroma = process.argv.includes('--chroma') ? true : process.argv.includes('--no-chroma') ? false : (region.kind === 'plate' && inkOnGround(region));
+  const chromaColor = '#00ff00';
+  const chromaLine = wantsChroma ? ` Render the artwork on a perfectly flat, uniform bright green background (${chromaColor}) that fills every pixel not covered by the artwork; no paper texture, no vignette, no shadow on the green; the green will be removed and the artwork composited onto the page's own surface.` : '';
+  const prompt = [platePrompt(spec, region), extra, chromaLine].filter(Boolean).join(' ');
+  plateCtx = { spec, specPath, region, ref, refPath, out, size, prompt, comp, encodePng, resize, chroma: wantsChroma ? chromaColor : null };
+  if (process.env.IMPECCABLE_IMAGE_GEN_FAKE) {
+    const up = resize(ref, ref.width * 2, ref.height * 2);
+    fs.writeFileSync(out, encodePng(up, { text: { 'impeccable:prompt': prompt, 'impeccable:fake': '1' } }));
+    fs.writeFileSync(`${out}.json`, JSON.stringify({ prompt, createdAt: new Date().toISOString(), tool: 'generate-image.mjs', model: 'fake', plate: region.id, refs: [refPath] }, null, 2));
+    console.log(`PLATE: ${out} (${up.width}x${up.height}, fake 2x crop of region ${region.id}, $0.00, no API call)`);
+    process.exit(0);
+  }
+  // fall through to the real call below with the crop as the single --ref
+}
+
+/** A region whose crop is dominated by one ground color with a dark second: ink on ground. */
+function inkOnGround(region) {
+  const pal = region.palette || [];
+  if (pal.length < 2) return false;
+  return pal[0].coverage >= 0.55;
+}
+
+function hexRgb(h) { const m = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(h); return m ? [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16)] : [0, 255, 0]; }
+
+/**
+ * Key a flat color to alpha with a soft edge: pixels within `hard` of the key
+ * go fully transparent, within `soft` fade, and green spill on edge pixels is
+ * pulled toward the ink color. Writes back in place. Returns keyed fraction.
+ */
+async function keyChroma(file, keyHex) {
+  const { decodePng, encodePng } = await import('./lib/png.mjs');
+  const img = decodePng(fs.readFileSync(file));
+  const [kr, kg, kb] = hexRgb(keyHex);
+  // sample the actual key from the corners: generators shift the green
+  const corners = [[2, 2], [img.width - 3, 2], [2, img.height - 3], [img.width - 3, img.height - 3]];
+  let sr = 0, sg = 0, sb = 0;
+  for (const [x, y] of corners) { const p = (y * img.width + x) * 4; sr += img.data[p]; sg += img.data[p + 1]; sb += img.data[p + 2]; }
+  const key = [sr / 4, sg / 4, sb / 4];
+  const isGreenish = key[1] > 120 && key[1] > key[0] * 1.4 && key[1] > key[2] * 1.4;
+  const K = isGreenish ? key : [kr, kg, kb];
+  const hard = 60, soft = 120;
+  let keyed = 0;
+  for (let i = 0; i < img.data.length; i += 4) {
+    const r = img.data[i], g = img.data[i + 1], b = img.data[i + 2];
+    const d = Math.sqrt((r - K[0]) ** 2 + (g - K[1]) ** 2 + (b - K[2]) ** 2);
+    // also treat "greener than both other channels by a margin" as key, for gradients the generator adds
+    const greenDom = g > 150 && g - Math.max(r, b) > 60;
+    if (d < hard || greenDom) { img.data[i + 3] = 0; keyed++; continue; }
+    if (d < soft) {
+      const a = (d - hard) / (soft - hard);
+      img.data[i + 3] = Math.round(img.data[i + 3] * a);
+      // despill: pull green down to the mean of the others on the fringe
+      const m = (r + b) / 2; img.data[i + 1] = Math.round(g * a + m * (1 - a));
+    }
+  }
+  // keep the tEXt chunks (the embedded prompt written before keying)
+  fs.writeFileSync(file, encodePng(img, { text: img.text && Object.keys(img.text).length ? img.text : null }));
+  return keyed / (img.data.length / 4);
+}
+
+async function scorePlate(ctx, outFile) {
+  try {
+    const { compare } = await import('./comp-diff.mjs');
+    const { decodePng } = await import('./lib/png.mjs');
+    let plate = decodePng(fs.readFileSync(outFile));
+    // a keyed plate ships over the page ground: composite it over the region's
+    // sampled ground before scoring, the way it will show
+    if (ctx.chroma) {
+      const { createImage, blit } = await import('./lib/raster.mjs');
+      const g = (ctx.region.palette && ctx.region.palette[0] && ctx.region.palette[0].hex) || '#ffffff';
+      const m = /^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i.exec(g);
+      const ground = m ? [parseInt(m[1], 16), parseInt(m[2], 16), parseInt(m[3], 16), 255] : [255, 255, 255, 255];
+      const over = createImage(plate.width, plate.height, ground);
+      blit(over, plate, 0, 0);
+      plate = over;
+    }
+    // a plate ships under object-fit: cover, so score it the way it will show
+    const res = compare({ comp: ctx.ref, build: plate, align: 'cover', kind: ctx.region.kind });
+    const s = res.whole;
+    const min = arg('min') ? parseFloat(arg('min')) : null;
+    const line = `PLATE-SCORE ${ctx.region.id} ${(s.overall * 100).toFixed(0)}% against the comp region (structure ${(s.structure * 100).toFixed(0)}%, color ${(s.color * 100).toFixed(0)}%, detail ${(s.detail * 100).toFixed(0)}%)`;
+    console.log(line);
+    const { plateVerdict } = await import('./build-phase.mjs');
+    const v = plateVerdict(ctx.region, s);
+    if (!v.ok) console.log(`PLATE-WARN the plate does not read as region ${ctx.region.id}: ${v.reasons.join('; ')}. Open ${outFile} beside ${ctx.refPath} and regenerate before building on it; the plates gate refuses it as it stands.`);
+    if (min != null && s.overall < min) { console.log(`PLATE-REJECTED below --min ${(min * 100).toFixed(0)}%`); process.exit(3); }
+  } catch (e) {
+    console.log(`PLATE-SCORE unavailable: ${e.message}`);
+  }
+}
+
+// A comp written into .impeccable/mocks/ while a direction is dealt but the
+// build phases never started is a comp round happening outside the state
+// file, and every session cut after it resumes with no state to follow. The
+// roll writes .impeccable/build/pending.json; build-phase.mjs start clears
+// it. Refuse mock output until start has run (or --force-mock).
+{
+  const outArg = arg('out') || (plateCtx && plateCtx.out) || '';
+  const intoMocks = /(^|[\\/])\.impeccable[\\/]mocks[\\/]/.test(outArg) && !/[\\/]decision[\\/]/.test(outArg);
+  const pending = fs.existsSync(path.join('.impeccable', 'build', 'pending.json'));
+  const state = fs.existsSync(path.join('.impeccable', 'build', 'state.json'));
+  if (intoMocks && pending && !state && !process.argv.includes('--force-mock')) {
+    console.error(`generate-image: a direction was chosen (concept-seed rolled) but build-phase.mjs start has not run, so this comp would be generated outside the build's state. Run: node ${path.dirname(fileURLToPath(import.meta.url))}/build-phase.mjs start --direction <seed key> --kind <assigned|pick|challenger|canon> first (it opens the comps phase), then generate. --force-mock overrides.`);
+    process.exit(4);
+  }
+}
+
 if (process.env.IMPECCABLE_IMAGE_GEN_FAKE) {
   const fakePromptFile = arg('prompt-file');
   const fakePrompt = fakePromptFile ? fs.readFileSync(fakePromptFile, 'utf8') : arg('prompt');
@@ -204,20 +371,52 @@ if (!key) {
   process.exit(1);
 }
 const promptFile = arg('prompt-file');
-const prompt = promptFile ? fs.readFileSync(promptFile, 'utf8') : arg('prompt');
-const out = arg('out');
+const prompt = plateCtx ? plateCtx.prompt : (promptFile ? fs.readFileSync(promptFile, 'utf8') : arg('prompt'));
+const out = plateCtx ? plateCtx.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 size = plateCtx ? plateCtx.size : arg('size', '1536x1024');
+const quality = arg('quality', plateCtx ? 'high' : 'medium');
+// Reference images (--ref, repeatable): route through the edits endpoint,
+// which accepts input images. This is how a comp for an established world
+// inherits the real UI's identity from a captured screenshot instead of a
+// prose paraphrase of it; the prompt then describes the NEW surface and the
+// reference carries palette, type, and component character.
+const refs = (() => {
+  const found = plateCtx ? [plateCtx.refPath] : [];
+  for (let i = 0; i < process.argv.length; i += 1) {
+    if (process.argv[i] === '--ref' && process.argv[i + 1] && !process.argv[i + 1].startsWith('--')) found.push(process.argv[i + 1]);
+  }
+  return found;
+})();
 
-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 }),
-});
+let response;
+if (refs.length) {
+  const form = new FormData();
+  form.append('model', 'gpt-image-2');
+  form.append('prompt', prompt);
+  form.append('size', size);
+  form.append('quality', quality);
+  form.append('n', '1');
+  for (const ref of refs) {
+    const bytes = fs.readFileSync(ref);
+    const type = ref.endsWith('.png') ? 'image/png' : ref.endsWith('.webp') ? 'image/webp' : 'image/jpeg';
+    form.append('image[]', new Blob([bytes], { type }), ref.split('/').pop());
+  }
+  response = await fetch('https://api.openai.com/v1/images/edits', {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${key}` },
+    body: form,
+  });
+} else {
+  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);
@@ -232,9 +431,17 @@ 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.
+let embedded = false;
 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));
+  const result = spawnSync(process.execPath, [fileURLToPath(new URL('./embed-prompt.mjs', import.meta.url)), out, '--prompt', prompt], { stdio: 'ignore' });
+  embedded = !result.error && result.status === 0;
+  if (!embedded) console.warn('generate-image: failed to embed prompt in the image');
+  fs.writeFileSync(`${out}.json`, JSON.stringify({ prompt, createdAt: new Date().toISOString(), tool: 'generate-image.mjs', model: 'gpt-image-2', ...(refs.length ? { refs } : {}) }, 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`);
+console.log(`IMAGE: ${out} (${size}, ${quality}, gpt-image-2, billed to your OpenAI key); ${embedded ? 'prompt embedded + sidecar' : 'sidecar'} at ${out}.json`);
+if (plateCtx && plateCtx.chroma) {
+  const frac = await keyChroma(out, plateCtx.chroma);
+  console.log(`PLATE-CHROMA keyed ${(frac * 100).toFixed(0)}% of pixels to alpha (${plateCtx.chroma}); place with a plain <img> over the page's own ground, no background on the plate. If the keyed fraction is under 20% the generator ignored the key: regenerate with --no-chroma and use mix-blend-mode: multiply instead.`);
+}
+if (plateCtx) await scorePlate(plateCtx, out);

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

@@ -10,7 +10,7 @@
  *   node hook-admin.mjs off                            # set enabled: false
  *   node hook-admin.mjs ignore-rule <rule-id>          # append to ignoreRules
  *   node hook-admin.mjs ignore-rule overused-font --all-values
- *   node hook-admin.mjs ignore-file <glob>             # append to ignoreFiles
+ *   node hook-admin.mjs ignore-file <glob> [--shared|--local]   # 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
@@ -35,6 +35,7 @@ import {
   ensureHookGitExcludes,
   normalizeIgnoreValue,
   normalizeIgnoreValueEntries,
+  extractFindingIgnoreValue,
 } from './hook-lib.mjs';
 
 const ACTIONS = new Set(['status', 'on', 'off', 'ignore-rule', 'ignore-file', 'ignore-value', 'reset']);
@@ -75,11 +76,11 @@ const HOOK_MANIFEST_TARGETS = [
     destRel: '.claude/settings.local.json',
     sharedDestRel: '.claude/settings.json',
     manifest: () => ({
-      description: 'Impeccable design detector: immediate-tier checks after Edit/Write/MultiEdit on UI files, full-rule deep pass on Stop.',
+      description: 'Impeccable design detector: immediate-tier checks after Edit/Write on UI files, full-rule deep pass on Stop.',
       hooks: {
         PostToolUse: [
           {
-            matcher: 'Edit|Write|MultiEdit',
+            matcher: 'Edit|Write',
             hooks: [
               {
                 type: 'command',
@@ -166,7 +167,7 @@ function readRawConfigFile(filePath) {
   }
 }
 
-const DETECTOR_CONFIG_KEYS = new Set(['ignoreRules', 'ignoreFiles', 'ignoreValues', 'designSystem']);
+const DETECTOR_CONFIG_KEYS = new Set(['ignoreRules', 'ignoreFiles', 'ignoreValues', 'designSystem', 'advisoryRules']);
 
 function hookSection(unified) {
   return unified && typeof unified === 'object' && !Array.isArray(unified) && unified.hook && typeof unified.hook === 'object' && !Array.isArray(unified.hook)
@@ -200,6 +201,15 @@ function stripDetectorKeys(raw) {
   return out;
 }
 
+function pickDetectorKeys(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (DETECTOR_CONFIG_KEYS.has(key)) out[key] = value;
+  }
+  return out;
+}
+
 // Write hook runtime config under `hook`, leaving detector filters in
 // `detector` and preserving sibling keys such as updateCheck.
 function writeHookConfig(cwd, hookConfig, opts = {}) {
@@ -207,10 +217,19 @@ function writeHookConfig(cwd, hookConfig, opts = {}) {
   if (opts.local) ensureHookGitExcludes(cwd);
   const existingRaw = readRawConfigFile(filePath).raw;
   const existing = existingRaw && typeof existingRaw === 'object' && !Array.isArray(existingRaw) ? existingRaw : {};
-  const existingHook = stripDetectorKeys(hookSection(existing));
+  const existingHookSection = hookSection(existing);
+  const existingHook = stripDetectorKeys(existingHookSection);
+  const legacyDetector = pickDetectorKeys(existingHookSection);
   // Merge over the existing hook object so fields the merge helpers don't manage
   // (consent, quiet, auditLog) survive an Impeccable hooks edit.
   const next = { ...existing, hook: { ...existingHook, ...hookConfig } };
+  if (Object.keys(legacyDetector).length > 0) {
+    const existingDetector = detectorSection(existing) || {};
+    next.detector = {
+      ...existingDetector,
+      ...mergeDetectorConfig(existingDetector, mergeDetectorConfig(legacyDetector)),
+    };
+  }
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, JSON.stringify(next, null, 2) + '\n');
   return filePath;
@@ -222,10 +241,14 @@ function writeDetectorConfig(cwd, detectorConfig, opts = {}) {
   const existingRaw = readRawConfigFile(filePath).raw;
   const existing = existingRaw && typeof existingRaw === 'object' && !Array.isArray(existingRaw) ? existingRaw : {};
   const nextHook = stripDetectorKeys(hookSection(existing));
-  const existingDetector = mergeDetectorConfig(detectorSection(existing));
+  const existingDetectorSection = detectorSection(existing) || {};
+  const existingDetector = mergeDetectorConfig(existingDetectorSection);
   const next = {
     ...existing,
-    detector: mergeDetectorConfig(detectorConfig, existingDetector),
+    detector: {
+      ...existingDetectorSection,
+      ...mergeDetectorConfig(detectorConfig, existingDetector),
+    },
   };
   if (Object.keys(nextHook).length > 0) next.hook = nextHook;
   else delete next.hook;
@@ -259,12 +282,18 @@ function mergeDetectorConfig(existing, seed = null) {
   if (seed?.designSystem && typeof seed.designSystem === 'object' && !Array.isArray(seed.designSystem)) {
     out.designSystem = { ...seed.designSystem };
   }
+  if (seed?.advisoryRules === 'include' || seed?.advisoryRules === 'exclude') {
+    out.advisoryRules = seed.advisoryRules;
+  }
   if (base.designSystem && typeof base.designSystem === 'object' && !Array.isArray(base.designSystem)) {
     out.designSystem = {
       ...(out.designSystem || {}),
       enabled: base.designSystem.enabled === false ? false : true,
     };
   }
+  if (base.advisoryRules === 'include' || base.advisoryRules === 'exclude') {
+    out.advisoryRules = base.advisoryRules;
+  }
   if (Array.isArray(base.ignoreRules)) {
     out.ignoreRules = Array.from(new Set([...out.ignoreRules, ...base.ignoreRules.map(String)]));
   }
@@ -558,12 +587,44 @@ function addIgnoreRule(cwd, args) {
   return `Added "${rule}" to detector.ignoreRules. Current: ${config.ignoreRules.join(', ')}`;
 }
 
-function addIgnoreFile(cwd, glob) {
+function parseIgnoreFileArgs(args) {
+  const positionals = [];
+  let shared = false;
+  let local = false;
+
+  for (const raw of args) {
+    const arg = String(raw || '');
+    if (arg === '--shared') {
+      shared = true;
+    } else if (arg === '--local') {
+      local = true;
+    } else if (arg === '--reason' || arg.startsWith('--reason=')) {
+      throw new Error('--reason is not supported for ignore-file because detector.ignoreFiles stores globs only; use ignore-value when a documented rule-specific exception fits');
+    } else if (arg.startsWith('--')) {
+      throw new Error(`Unknown ignore-file flag: ${arg}`);
+    } else {
+      positionals.push(arg);
+    }
+  }
+
+  if (shared && local) throw new Error('Pass only one scope flag: --shared or --local');
+  if (positionals.length > 1) throw new Error('Pass exactly one glob to ignore-file');
+
+  return {
+    glob: positionals[0],
+    local,
+  };
+}
+
+function addIgnoreFile(cwd, args) {
+  const parsed = parseIgnoreFileArgs(args);
+  const glob = parsed.glob;
   if (!glob) throw new Error(`Pass a glob, e.g. ${IMPECCABLE_COMMAND} hooks ignore-file "src/legacy/**"`);
-  const config = mergeDetectorConfig(readRawDetectorConfig(cwd));
+  const config = mergeDetectorConfig(readRawDetectorConfig(cwd, { local: parsed.local }));
   if (!config.ignoreFiles.includes(glob)) config.ignoreFiles.push(glob);
-  writeDetectorConfig(cwd, config);
-  return `Added "${glob}" to detector.ignoreFiles. Current: ${config.ignoreFiles.join(', ')}`;
+  const target = writeDetectorConfig(cwd, config, { local: parsed.local });
+  const scope = parsed.local ? 'local detector.ignoreFiles' : 'shared detector.ignoreFiles';
+  return `Added "${glob}" to ${scope} (${path.relative(cwd, target) || target}). Current: ${config.ignoreFiles.join(', ')}`;
 }
 
 // An empty glob used to be dropped by filter(Boolean), so `--file=` reported
@@ -653,6 +714,10 @@ function addIgnoreValue(cwd, args) {
     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}.`);
   }
 
+  if (parsed.value !== '*' && !extractFindingIgnoreValue({ antipattern: parsed.rule, ignoreValue: parsed.value })) {
+    throw new Error(`${parsed.rule} has no extractable ignore value. Use ${IMPECCABLE_COMMAND} hooks ignore-value ${parsed.rule} "*" --file <glob> to suppress it in matching files.`);
+  }
+
   const local = parsed.local;
   const config = mergeDetectorConfig(readRawDetectorConfig(cwd, { local }));
   // Key on the file scope too: the same rule/value legitimately appears more than
@@ -705,9 +770,22 @@ function reset(cwd) {
       }
     } catch { /* ignore */ }
   }
-  return removed.length
-    ? `Reset design hook config and cache (removed: ${removed.join(', ')}).`
-    : 'No hook config or cache to remove. Already at defaults.';
+  // `on` writes three things: config, consent, and hook entries in the
+  // provider manifests. Reset must undo all three (issue #512): a leftover
+  // manifest entry kept invoking the hook after the config that said "off"
+  // was deleted. Local destRel only, since `on` never writes the team-shared
+  // sharedDestRel. No skill-folder gate: a reset mid-uninstall (skill files
+  // gone, manifest still wired) is the case that most needs the prune.
+  const pruned = [];
+  for (const target of HOOK_MANIFEST_TARGETS) {
+    try {
+      if (pruneImpeccableHookFromManifest(path.join(cwd, target.destRel))) pruned.push(target.provider);
+    } catch { /* ignore */ }
+  }
+  const parts = [];
+  if (removed.length) parts.push(`Reset design hook config and cache (removed: ${removed.join(', ')}).`);
+  if (pruned.length) parts.push(`Removed hook entries from: ${pruned.join(', ')}.`);
+  return parts.length ? parts.join(' ') : 'No hook config or cache to remove. Already at defaults.';
 }
 
 function main() {
@@ -727,7 +805,7 @@ function main() {
       case 'on':     out = setEnabled(cwd, true); break;
       case 'off':    out = setEnabled(cwd, false); break;
       case 'ignore-rule': out = addIgnoreRule(cwd, rest); break;
-      case 'ignore-file': out = addIgnoreFile(cwd, rest[0]); break;
+      case 'ignore-file': out = addIgnoreFile(cwd, rest); break;
       case 'ignore-value': out = addIgnoreValue(cwd, rest); break;
       case 'reset':  out = reset(cwd); break;
     }

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

@@ -16,13 +16,18 @@ import path from 'node:path';
 
 import {
   ALLOWED_EXTS,
+  DEFAULT_CONFIG,
   EDIT_COUNT_THRESHOLD,
   GENERATED_PATH,
   SENSITIVE_PATH,
-  appendDesignSystemNote,
+  appendDesignSystemNoteOnce,
+  commitFooterShown,
+  designNoteReserve,
   designSystemOptions,
+  footerModeForSession,
   filterFindings,
   isNativePlatform,
+  isScanTargetInsideProject,
   loadDetector,
   matchConfiguredExtension,
   matchesAnyGlob,
@@ -161,7 +166,7 @@ function replaceOnce(original, oldString, newString) {
 }
 
 function readExistingProjectFile(filePath, cwd) {
-  if (!isInsideProject(filePath, cwd)) return null;
+  if (!isScanTargetInsideProject(filePath, cwd)) return null;
   if (SENSITIVE_PATH.test(filePath) || GENERATED_PATH.test(filePath)) return null;
   try {
     const stat = fs.statSync(filePath);
@@ -232,7 +237,7 @@ function shellCopiedFileContent(command, cwd) {
   const source = shellCopyPaths(command)?.source;
   if (!source) return '';
   const sourcePath = path.isAbsolute(source) ? source : path.resolve(cwd, source);
-  if (!isInsideProject(sourcePath, cwd)) return '';
+  if (!isScanTargetInsideProject(sourcePath, cwd)) return '';
   if (SENSITIVE_PATH.test(sourcePath) || GENERATED_PATH.test(sourcePath)) return '';
   try {
     const stat = fs.statSync(sourcePath);
@@ -328,15 +333,6 @@ function relativePath(filePath, cwd) {
   }
 }
 
-function isInsideProject(filePath, cwd) {
-  try {
-    const rel = path.relative(cwd, filePath);
-    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-  } catch {
-    return false;
-  }
-}
-
 // 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.
@@ -353,13 +349,32 @@ async function detectProposedHtml(detector, content, filePath, scanOptions) {
   }
 }
 
-function cursorBlockMessage(findings, filePath, config, cwd) {
-  const rendered = renderTemplate(findings, filePath, config, { cwd });
-  const blocked = rendered.replace(
+// Cursor caps deny messages around 4000 chars. The cap feeds through the
+// renderer's clamp, which preserves the policy footer, rather than tail-
+// slicing the rendered text, which cut the footer off any message the
+// default 8000-char budget let past 4000.
+const CURSOR_DENY_LIMIT = 4000;
+const BLOCK_PREFIX = 'Impeccable design hook blocked this write before it landed. ';
+
+function cursorBlockMessage(findings, filePath, config, cwd, footerMode, reserveChars) {
+  const limits = config?.limits || DEFAULT_CONFIG.limits;
+  // Charge the prefix via reserveChars, not by subtracting from maxChars:
+  // renderTemplate's 500-char floor re-raises any maxChars pushed below it,
+  // un-charging a prefix subtracted from maxChars (Greptile P1 on PR #508).
+  // reserveChars comes off after the floor, so the prefix is charged at every
+  // config tier and the final prefixed message plus a pending staleness note
+  // fits the binding limit. Default-config output is byte-identical.
+  const budget = Math.min(
+    limits.maxChars || DEFAULT_CONFIG.limits.maxChars,
+    CURSOR_DENY_LIMIT,
+  );
+  const rendered = renderTemplate(findings, filePath,
+    { ...config, limits: { ...limits, maxChars: budget } },
+    { cwd, footer: footerMode, reserveChars: (reserveChars || 0) + BLOCK_PREFIX.length });
+  return rendered.replace(
     '[impeccable@1] Design hook findings requiring review',
-    '[impeccable@1] Impeccable design hook blocked this write before it landed. Design hook findings requiring review',
+    `[impeccable@1] ${BLOCK_PREFIX}Design hook findings requiring review`,
   );
-  return blocked.length > 4000 ? `${blocked.slice(0, 3984)}\n...(truncated)` : blocked;
 }
 
 function findingSignature(findings) {
@@ -414,7 +429,7 @@ async function main() {
   };
 
   if (!filePath) return allow({ ...audit, skipped: 'no-file-path', durationMs: Date.now() - started });
-  if (!isInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
+  if (!isScanTargetInsideProject(filePath, cwd)) return allow({ ...audit, skipped: 'outside-project', durationMs: Date.now() - started });
   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 });
 
@@ -476,9 +491,16 @@ async function main() {
     });
   }
 
-  const message = appendDesignSystemNote(cursorBlockMessage(filtered, filePath, config, cwd), scanOptions);
   const sessionId = event.session_id || event.conversation_id || 'unknown';
   const cache = readCache(cwd);
+  // Repeated denials for the same session repeat the findings, not the
+  // policy: the full footer emits once per session, the short form after.
+  const footerMode = footerModeForSession(cache, sessionId);
+  const message = appendDesignSystemNoteOnce(
+    cursorBlockMessage(filtered, filePath, config, cwd, footerMode, designNoteReserve(scanOptions, cache, sessionId)),
+    scanOptions, cache, sessionId, config,
+  );
+  commitFooterShown(cache, sessionId, message);
   const denial = bumpCursorDenial(cache, sessionId, filePath, filtered);
   persistCache(cwd, cache);
   if (denial.count > EDIT_COUNT_THRESHOLD) {