@monoes/monodesign 1.2.20 → 1.2.22

package/skill/scripts/hook-lib-findings.mjs

@@ -0,0 +1,201 @@
+import path from 'node:path';
+import { normalizeIgnoreValue, normalizeIgnoreRule, ignoreValueMatches, normalizeIgnoreValueEntries } from './hook-lib-ignore.mjs';
+import { ensureSession, ensureFile } from './hook-lib-cache.mjs';
+
+// Glob → RegExp. Supports `**`, `*`, `?`, and `{a,b}` alternation.
+function globToRegex(glob) {
+  let re = '^';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        re += '.*';
+        i += 2;
+        if (glob[i] === '/') i += 1;
+      } else {
+        re += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+      i += 1;
+    } else if (c === '{') {
+      const end = glob.indexOf('}', i);
+      if (end === -1) { re += '\\{'; i += 1; continue; }
+      const parts = glob.slice(i + 1, end).split(',').map((p) => p.replace(/[.+^$()|[\]\\]/g, '\\$&'));
+      re += `(?:${parts.join('|')})`;
+      i = end + 1;
+    } else if (/[.+^$()|[\]\\]/.test(c)) {
+      re += `\\${c}`;
+      i += 1;
+    } else {
+      re += c;
+      i += 1;
+    }
+  }
+  re += '$';
+  return new RegExp(re);
+}
+
+export function matchesAnyGlob(filePath, globs) {
+  if (!Array.isArray(globs) || globs.length === 0) return false;
+  const normalized = filePath.split(path.sep).join('/');
+  for (const glob of globs) {
+    try {
+      const re = globToRegex(String(glob));
+      if (re.test(normalized)) return true;
+      // Match against basename too for convenience: `*.generated.tsx` should
+      // catch `src/foo.generated.tsx` without requiring `**/`.
+      const base = normalized.split('/').pop();
+      if (re.test(base)) return true;
+    } catch {
+      /* malformed glob, skip */
+    }
+  }
+  return false;
+}
+
+export function filterFindings(findings, _content, _ext, config) {
+  if (!Array.isArray(findings) || findings.length === 0) return [];
+  const ignoreRules = new Set((config.ignoreRules || []).map((rule) => normalizeIgnoreRule(rule)));
+  const ignoreValues = normalizeIgnoreValueEntries(config.ignoreValues || []);
+  return findings.filter((f) => {
+    if (!f || typeof f !== 'object') return false;
+    if (ignoreRules.has(normalizeIgnoreRule(f.antipattern))) return false;
+    if (isIgnoredFindingValue(f, ignoreValues)) return false;
+    return true;
+  });
+}
+
+function isIgnoredFindingValue(finding, ignoreValues) {
+  if (!Array.isArray(ignoreValues) || ignoreValues.length === 0) return false;
+  const rule = normalizeIgnoreRule(finding.antipattern);
+  if (!rule) return false;
+  // File-scoped wildcards suppress rules with no extractable value, such as side-tab.
+  const value = extractFindingIgnoreValue(finding);
+  return ignoreValues.some((entry) => {
+    if (entry.rule !== rule) return false;
+    const wildcardValue = entry.value === '*';
+    if (!wildcardValue && (!value || !ignoreValueMatches(rule, entry.value, value))) return false;
+    if (!Array.isArray(entry.files) || entry.files.length === 0) return !wildcardValue;
+    return findingMatchesScopedIgnoreFile(finding, entry.files);
+  });
+}
+
+function findingMatchesScopedIgnoreFile(finding, globs) {
+  const filePath = String(finding?.file || '').trim();
+  if (!filePath) return false;
+  if (matchesAnyGlob(filePath, globs)) return true;
+
+  const normalized = filePath.split(path.sep).join('/');
+  const parts = normalized.split('/').filter(Boolean);
+  for (let i = 0; i < parts.length; i++) {
+    const suffix = parts.slice(i).join('/');
+    if (matchesAnyGlob(suffix, globs)) return true;
+  }
+  return false;
+}
+
+export function extractFindingIgnoreValue(finding) {
+  if (!finding || typeof finding !== 'object') return '';
+  const rule = normalizeIgnoreRule(finding.antipattern);
+  const directValueRules = new Set([
+    'overused-font',
+    'bounce-easing',
+    'design-system-font',
+    'design-system-color',
+    'design-system-radius',
+  ]);
+  if (!directValueRules.has(rule)) return '';
+  return normalizeIgnoreValue(extractFindingIgnoreValueRaw(finding, rule));
+}
+
+export function extractFindingIgnoreValueRaw(finding, rule = normalizeIgnoreRule(finding?.antipattern)) {
+  const direct = cleanIgnoreValueDisplay(finding.ignoreValue || finding.value || '');
+  if (direct) return direct;
+
+  const candidates = [finding.detail, finding.snippet].filter((v) => typeof v === 'string' && v);
+  for (const text of candidates) {
+    if (rule === 'bounce-easing') {
+      const motion = extractMotionIgnoreValue(text);
+      if (motion) return motion;
+      continue;
+    }
+
+    const primary = text.match(/Primary font:\s*([^()\n;]+)/i);
+    if (primary) return cleanIgnoreValueDisplay(primary[1]);
+
+    const family = text.match(/font-family\s*:\s*["']?([^'",;\n]+)/i);
+    if (family) return cleanIgnoreValueDisplay(family[1]);
+
+    const google = text.match(/[?&]family=([^&:;\n]+)/i);
+    if (google) {
+      try {
+        return cleanIgnoreValueDisplay(decodeURIComponent(google[1]));
+      } catch {
+        return cleanIgnoreValueDisplay(google[1]);
+      }
+    }
+  }
+
+  return '';
+}
+
+function extractMotionIgnoreValue(text) {
+  const tailwind = text.match(/\banimate-bounce\b/i);
+  if (tailwind) return cleanIgnoreValueDisplay(tailwind[0]);
+
+  const bezier = text.match(/cubic-bezier\([^)]+\)/i);
+  if (bezier) return cleanIgnoreValueDisplay(bezier[0]);
+
+  const animation = text.match(/animation(?:-name)?\s*:\s*([^;\n]+)/i);
+  if (animation) {
+    const token = animation[1]
+      .split(/[,\s]+/)
+      .find((part) => /bounce|elastic|wobble|jiggle|spring/i.test(part));
+    if (token) return cleanIgnoreValueDisplay(token);
+  }
+
+  return '';
+}
+
+function cleanIgnoreValueDisplay(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .replace(/\+/g, ' ')
+    .replace(/\s+/g, ' ');
+}
+
+export function dedupeAgainstCache(findings, cache, sessionId, filePath) {
+  if (!Array.isArray(findings) || findings.length === 0) return [];
+  const fileEntry = ensureFile(cache, sessionId, filePath);
+  const known = new Set(fileEntry.findings || []);
+  const fresh = [];
+  for (const f of findings) {
+    const key = findingCacheKey(f);
+    if (known.has(key)) continue;
+    known.add(key);
+    fresh.push(f);
+  }
+  return fresh;
+}
+
+export function rememberFindings(cache, sessionId, filePath, findings) {
+  const fileEntry = ensureFile(cache, sessionId, filePath);
+  const known = new Set(fileEntry.findings || []);
+  for (const f of findings) known.add(findingCacheKey(f));
+  fileEntry.findings = Array.from(known);
+  ensureSession(cache, sessionId).updatedAt = Date.now();
+}
+
+function findingCacheKey(finding) {
+  const line = finding?.line || 0;
+  const value = extractFindingIgnoreValue(finding);
+  if (line > 0 && value) return `${finding.antipattern}:${line}:${value}`;
+  if (line > 0) return `${finding.antipattern}:${line}`;
+  if (value) return `${finding.antipattern}:0:${value}`;
+  const snippet = String(finding?.snippet || '').trim().slice(0, 80);
+  return snippet ? `${finding.antipattern}:0:${snippet}` : `${finding.antipattern}:0`;
+}

package/skill/scripts/hook-lib-ignore.mjs

@@ -0,0 +1,205 @@
+import { uniqueStrings } from './hook-lib-config.mjs';
+
+export function normalizeIgnoreValue(value) {
+  return String(value || '')
+    .trim()
+    .replace(/^["']|["']$/g, '')
+    .replace(/\+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .toLowerCase();
+}
+
+export function normalizeIgnoreRule(rule) {
+  return String(rule || '').trim().toLowerCase();
+}
+
+function colorIgnoreKey(value) {
+  const color = parseIgnoreColor(value);
+  if (!color) return '';
+  return `${color.r},${color.g},${color.b},${Math.round(color.a * 255)}`;
+}
+
+function parseIgnoreColor(value) {
+  const text = String(value || '').trim().toLowerCase();
+  if (!text) return null;
+
+  const hex = text.match(/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i);
+  if (hex) return parseHexIgnoreColor(hex[1]);
+
+  const rgb = text.match(/^rgba?\((.*)\)$/i);
+  if (rgb) {
+    const parts = splitColorArgs(rgb[1]);
+    if (parts.length < 3 || parts.length > 4) return null;
+    const r = parseRgbChannel(parts[0]);
+    const g = parseRgbChannel(parts[1]);
+    const b = parseRgbChannel(parts[2]);
+    const a = parts[3] === undefined ? 1 : parseAlphaChannel(parts[3]);
+    if ([r, g, b, a].some((v) => v === null)) return null;
+    return { r, g, b, a };
+  }
+
+  const hsl = text.match(/^hsla?\((.*)\)$/i);
+  if (hsl) {
+    const parts = splitColorArgs(hsl[1]);
+    if (parts.length < 3 || parts.length > 4) return null;
+    const h = parseHueChannel(parts[0]);
+    const s = parsePercentChannel(parts[1]);
+    const l = parsePercentChannel(parts[2]);
+    const a = parts[3] === undefined ? 1 : parseAlphaChannel(parts[3]);
+    if ([h, s, l, a].some((v) => v === null)) return null;
+    return hslToRgb(h, s, l, a);
+  }
+
+  return null;
+}
+
+function parseHexIgnoreColor(hex) {
+  if (hex.length === 3 || hex.length === 4) {
+    const r = parseInt(hex[0] + hex[0], 16);
+    const g = parseInt(hex[1] + hex[1], 16);
+    const b = parseInt(hex[2] + hex[2], 16);
+    const a = hex.length === 4 ? parseInt(hex[3] + hex[3], 16) / 255 : 1;
+    return { r, g, b, a };
+  }
+  const r = parseInt(hex.slice(0, 2), 16);
+  const g = parseInt(hex.slice(2, 4), 16);
+  const b = parseInt(hex.slice(4, 6), 16);
+  const a = hex.length === 8 ? parseInt(hex.slice(6, 8), 16) / 255 : 1;
+  return { r, g, b, a };
+}
+
+function splitColorArgs(body) {
+  const text = String(body || '').trim();
+  if (!text) return [];
+  if (text.includes(',')) {
+    const parts = text.split(',').map((part) => part.trim()).filter(Boolean);
+    const last = parts[parts.length - 1];
+    if (last?.includes('/')) {
+      const split = last.split('/').map((part) => part.trim()).filter(Boolean);
+      return [...parts.slice(0, -1), ...split];
+    }
+    return parts;
+  }
+  return text.replace(/\s*\/\s*/g, ' / ').split(/\s+/).filter((part) => part && part !== '/');
+}
+
+function parseRgbChannel(raw) {
+  const text = String(raw || '').trim();
+  const match = text.match(/^(-?\d*\.?\d+)(%)?$/);
+  if (!match) return null;
+  const value = Number.parseFloat(match[1]);
+  if (!Number.isFinite(value)) return null;
+  const scaled = match[2] ? value * 2.55 : value;
+  if (scaled < 0 || scaled > 255) return null;
+  return Math.round(scaled);
+}
+
+function parseAlphaChannel(raw) {
+  const text = String(raw || '').trim();
+  const match = text.match(/^(-?\d*\.?\d+)(%)?$/);
+  if (!match) return null;
+  const value = Number.parseFloat(match[1]);
+  if (!Number.isFinite(value)) return null;
+  const alpha = match[2] ? value / 100 : value;
+  return alpha >= 0 && alpha <= 1 ? alpha : null;
+}
+
+function parseHueChannel(raw) {
+  const text = String(raw || '').trim();
+  const match = text.match(/^(-?\d*\.?\d+)(deg|rad|turn|grad)?$/);
+  if (!match) return null;
+  const value = Number.parseFloat(match[1]);
+  if (!Number.isFinite(value)) return null;
+  const unit = match[2] || 'deg';
+  if (unit === 'turn') return value * 360;
+  if (unit === 'rad') return value * (180 / Math.PI);
+  if (unit === 'grad') return value * 0.9;
+  return value;
+}
+
+function parsePercentChannel(raw) {
+  const text = String(raw || '').trim();
+  const match = text.match(/^(-?\d*\.?\d+)%$/);
+  if (!match) return null;
+  const value = Number.parseFloat(match[1]);
+  if (!Number.isFinite(value)) return null;
+  return value >= 0 && value <= 100 ? value / 100 : null;
+}
+
+function hslToRgb(hue, saturation, lightness, alpha) {
+  const h = (((hue % 360) + 360) % 360) / 360;
+  if (saturation === 0) {
+    const gray = clampByte(Math.round(lightness * 255));
+    return { r: gray, g: gray, b: gray, a: alpha };
+  }
+  const q = lightness < 0.5
+    ? lightness * (1 + saturation)
+    : lightness + saturation - lightness * saturation;
+  const p = 2 * lightness - q;
+  const toRgb = (t) => {
+    let channel = t;
+    if (channel < 0) channel += 1;
+    if (channel > 1) channel -= 1;
+    if (channel < 1 / 6) return p + (q - p) * 6 * channel;
+    if (channel < 1 / 2) return q;
+    if (channel < 2 / 3) return p + (q - p) * (2 / 3 - channel) * 6;
+    return p;
+  };
+  return {
+    r: clampByte(Math.round(toRgb(h + 1 / 3) * 255)),
+    g: clampByte(Math.round(toRgb(h) * 255)),
+    b: clampByte(Math.round(toRgb(h - 1 / 3) * 255)),
+    a: alpha,
+  };
+}
+
+function clampByte(value) {
+  return Math.min(255, Math.max(0, value));
+}
+
+export function ignoreValueMatches(rule, entryValue, findingValue) {
+  if (entryValue === findingValue) return true;
+  if (rule !== 'design-system-color') return false;
+  const entryColor = colorIgnoreKey(entryValue);
+  return Boolean(entryColor && entryColor === colorIgnoreKey(findingValue));
+}
+
+export function normalizeIgnoreValueEntries(entries) {
+  if (!Array.isArray(entries)) return [];
+  const out = [];
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') continue;
+    const rule = normalizeIgnoreRule(entry.rule);
+    const value = normalizeIgnoreValue(entry.value);
+    if (!rule || !value) continue;
+    const normalized = { rule, value };
+    const files = uniqueStrings([
+      ...(typeof entry.file === 'string' && entry.file.trim() ? [entry.file.trim()] : []),
+      ...(Array.isArray(entry.files) ? entry.files.filter(v => typeof v === 'string' && v.trim()).map(v => v.trim()) : []),
+    ]);
+    if (files.length > 0) normalized.files = files;
+    if (typeof entry.reason === 'string' && entry.reason.trim()) {
+      normalized.reason = entry.reason.trim();
+    }
+    if (typeof entry.createdAt === 'string' && entry.createdAt.trim()) {
+      normalized.createdAt = entry.createdAt.trim();
+    }
+    out.push(normalized);
+  }
+  return out;
+}
+
+export function mergeIgnoreValues(existing, incoming) {
+  const map = new Map();
+  for (const entry of normalizeIgnoreValueEntries(existing)) {
+    map.set(`${entry.rule}\0${entry.value}\0${ignoreValueFilesKey(entry.files)}`, entry);
+  }
+  for (const entry of normalizeIgnoreValueEntries(incoming)) {
+    map.set(`${entry.rule}\0${entry.value}\0${ignoreValueFilesKey(entry.files)}`, entry);
+  }
+  return Array.from(map.values());
+}
+
+function ignoreValueFilesKey(files) {
+  return Array.isArray(files) && files.length > 0 ? files.join('\x1f') : '';
+}

package/skill/scripts/hook-lib-render.mjs

@@ -0,0 +1,273 @@
+import path from 'node:path';
+import { MONODESIGN_COMMAND } from './lib/provider.mjs';
+import { ENVELOPE_PREFIX, ACK_EXTS, DEFAULT_CONFIG, matchConfiguredExtension } from './hook-lib-config.mjs';
+import { normalizeIgnoreRule } from './hook-lib-ignore.mjs';
+import { extractFindingIgnoreValue, extractFindingIgnoreValueRaw } from './hook-lib-findings.mjs';
+
+export function renderTemplate(findings, filePath, config, opts = {}) {
+  if (!Array.isArray(findings) || findings.length === 0) return '';
+  const limits = config?.limits || DEFAULT_CONFIG.limits;
+  const cap = Math.max(1, limits.maxFindings || DEFAULT_CONFIG.limits.maxFindings);
+  const maxChars = Math.max(500, limits.maxChars || DEFAULT_CONFIG.limits.maxChars);
+
+  const cwd = opts.cwd || process.cwd();
+  const display = relativize(filePath, cwd);
+  const total = findings.length;
+  const shown = findings.slice(0, cap);
+  const remaining = total - shown.length;
+
+  const header = `${ENVELOPE_PREFIX} Design hook findings requiring review in ${display} (${total} issue(s)):`;
+  const lines = shown.map((f) => formatFindingLine(f));
+  const more = remaining > 0
+    ? `... and ${remaining} more (see ${MONODESIGN_COMMAND} audit).`
+    : null;
+  const footer = directiveFooter(display);
+
+  const blocks = [header, ...lines];
+  if (more) blocks.push(more);
+  blocks.push('');
+  blocks.push(footer);
+  let text = blocks.join('\n');
+
+  if (text.length > maxChars) {
+    text = clampToBudget(header, lines, more, footer, maxChars);
+  }
+  return text;
+}
+
+export function renderGroupedTemplate(groups, config, opts = {}) {
+  const realGroups = groups.filter((group) => Array.isArray(group.findings) && group.findings.length > 0);
+  if (realGroups.length === 0) return '';
+  if (realGroups.length === 1) {
+    const [group] = realGroups;
+    return renderTemplate(group.findings, group.filePath, config, opts);
+  }
+
+  const limits = config?.limits || DEFAULT_CONFIG.limits;
+  const cap = Math.max(1, limits.maxFindings || DEFAULT_CONFIG.limits.maxFindings);
+  const maxChars = Math.max(500, limits.maxChars || DEFAULT_CONFIG.limits.maxChars);
+  const cwd = opts.cwd || process.cwd();
+  const total = realGroups.reduce((sum, group) => sum + group.findings.length, 0);
+  const header = `${ENVELOPE_PREFIX} Design hook findings requiring review across ${realGroups.length} files (${total} issue(s)):`;
+  const lines = [];
+  let shownCount = 0;
+
+  for (const group of realGroups) {
+    const display = relativize(group.filePath, cwd);
+    lines.push(`${display} (${group.findings.length} issue(s)):`);
+    const remainingCap = Math.max(0, cap - shownCount);
+    const shown = group.findings.slice(0, remainingCap);
+    for (const finding of shown) {
+      lines.push(formatFindingLine(finding));
+    }
+    shownCount += shown.length;
+    const hidden = group.findings.length - shown.length;
+    if (hidden > 0) {
+      lines.push(`- ... ${hidden} more in ${display} (see ${MONODESIGN_COMMAND} audit).`);
+    }
+  }
+
+  const footer = directiveFooter('the affected files', { grouped: true });
+  let text = [header, ...lines, '', footer].join('\n');
+  if (text.length > maxChars) {
+    text = clampGroupedToBudget(header, lines, footer, maxChars);
+  }
+  return text;
+}
+
+function clampGroupedToBudget(header, lines, footer, maxChars) {
+  const assemble = (linesArr, omitted) => [
+    header,
+    ...linesArr,
+    ...(omitted ? [`... and more (see ${MONODESIGN_COMMAND} audit).`] : []),
+    '',
+    footer,
+  ].join('\n');
+
+  const working = lines.slice();
+  let omitted = false;
+  let assembled = assemble(working, omitted);
+  while (assembled.length > maxChars && working.length > 1) {
+    working.pop();
+    omitted = true;
+    assembled = assemble(working, omitted);
+  }
+  if (assembled.length > maxChars) {
+    assembled = `${assembled.slice(0, maxChars - 1)}…`;
+  }
+  return assembled;
+}
+
+function clampToBudget(header, lines, more, footer, maxChars) {
+  const assemble = (linesArr, moreText) => {
+    const blocks = [header, ...linesArr];
+    if (moreText) blocks.push(moreText);
+    blocks.push('');
+    blocks.push(footer);
+    return blocks.join('\n');
+  };
+
+  const working = lines.slice();
+  let moreText = more;
+  let assembled = assemble(working, moreText);
+  while (assembled.length > maxChars && working.length > 1) {
+    working.pop();
+    moreText = `... and more (see ${MONODESIGN_COMMAND} audit).`;
+    assembled = assemble(working, moreText);
+  }
+  if (assembled.length > maxChars) {
+    assembled = `${assembled.slice(0, maxChars - 1)}…`;
+  }
+  return assembled;
+}
+
+function formatFindingLine(f) {
+  const prefix = f.line && f.line > 0 ? `- L${f.line}` : '-';
+  const desc = (f.description || '').trim();
+  const name = (f.name || '').trim();
+  // Description from the registry already ends in punctuation; join with a
+  // single space. `name` may have a trailing period already, keep it clean.
+  const nameSegment = name ? `${name.replace(/\.+\s*$/, '')}.` : '';
+  const ignoreCommand = formatFindingIgnoreCommand(f);
+  const ignoreSegment = ignoreCommand
+    ? ` If the user explicitly confirms this value is intentional: \`${ignoreCommand}\`.`
+    : '';
+  return `${prefix} [${f.antipattern}] ${nameSegment} ${desc}${ignoreSegment}`.replace(/\s+/g, ' ').trim();
+}
+
+function formatFindingIgnoreCommand(finding) {
+  if (!finding || typeof finding !== 'object') return '';
+  const rule = normalizeIgnoreRule(finding.antipattern);
+  if (!rule) return '';
+  const normalizedValue = extractFindingIgnoreValue(finding);
+  if (!normalizedValue) return '';
+  const value = extractFindingIgnoreValueRaw(finding);
+  const valueArg = quoteCommandArg(value);
+  const reason = quoteCommandArg(`User confirmed ${value} is intentional`);
+  return `${MONODESIGN_COMMAND} hooks ignore-value ${rule} ${valueArg} --shared --reason ${reason}`;
+}
+
+function quoteCommandArg(value) {
+  const text = String(value || '').trim();
+  if (/^[A-Za-z0-9._:-]+$/.test(text)) return text;
+  return `"${text.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+
+export function relativize(filePath, cwd) {
+  try {
+    const rel = path.relative(cwd, filePath).split(path.sep).join('/');
+    if (!rel || rel.startsWith('..')) return filePath;
+    return rel.split(path.sep).join('/');
+  } catch {
+    return filePath;
+  }
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Nudge/steer messages for the no-silent-fires policy.
+//
+// The hook is designed to be a conversational presence: every fire that
+// actually scans a file emits a developer-role message into the model's
+// next turn. Three states map to three templates:
+//
+//   1. **Fresh findings**  → `renderTemplate` (existing, imperative).
+//   2. **Pending findings** → `renderPendingAck` (re-nudge for issues the
+//                              model was already told about in this
+//                              session but hasn't fixed yet).
+//   3. **Truly clean**      → `renderCleanAck` (short positive nudge that
+//                              keeps the design discipline in context).
+//
+// All three are short (≤ ~40 tokens each) so the cumulative cost stays
+// bounded across a long active editing session. Users who explicitly want
+// silence-on-clean can set `MONODESIGN_HOOK_QUIET=1` — runHook checks that
+// env before emitting #2 or #3.
+//
+// Why not stay silent on dedup-clean? Earlier versions did. The model
+// quickly forgets the prior reminder once tool output scrolls past it, so
+// re-nudging on the same file with a short "still pending" line keeps the
+// pressure on. The wording deliberately points back to "earlier this
+// session" so the model knows it's a re-mind, not a new finding.
+// ────────────────────────────────────────────────────────────────────────
+
+const STEER_LINE = 'That does not mean the design is good: keep following the project design system and the monodesign skill guidance.';
+
+export function renderCleanAck(filePath, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const display = relativize(filePath, cwd);
+  return `${ENVELOPE_PREFIX} Design hook scanned ${display}. No deterministic design-quality issues found. ${STEER_LINE}`;
+}
+
+export function renderPendingAck(filePath, knownFindings, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const display = relativize(filePath, cwd);
+  const count = knownFindings.length;
+  // `knownFindings` here are the cache strings like "side-tab:3".
+  const sample = knownFindings.slice(0, 3).join(', ');
+  const more = count > 3 ? `, +${count - 3} more` : '';
+  return `${ENVELOPE_PREFIX} Design hook scanned ${display}. Still has ${count} finding(s) flagged earlier this session (${sample}${more}). Handle them before finalizing — the previous reminder still applies.`;
+}
+
+export function shouldEmitAckForFile(filePath, config = null) {
+  if (ACK_EXTS.has(path.extname(String(filePath || '')).toLowerCase())) return true;
+  // Configured html-engine extensions are declared UI markup, so they get the
+  // clean/pending acks; text-engine ones stay quiet like plain .ts/.js.
+  const configured = matchConfiguredExtension(filePath, config?.extensions);
+  return Boolean(configured && configured.engine === 'html');
+}
+
+export function designSystemOptions(config, detector, projectCwd) {
+  if (config?.designSystem?.enabled === false) return {};
+  if (!detector || typeof detector.loadDesignSystemForCwd !== 'function') return {};
+  try {
+    const designSystem = detector.loadDesignSystemForCwd(projectCwd);
+    return designSystem ? { designSystem } : {};
+  } catch {
+    return {};
+  }
+}
+
+export function appendDesignSystemNote(text, scanOptions) {
+  if (!text || !scanOptions?.designSystem?.mdNewerThanJson) return text;
+  return `${text}\n\n${ENVELOPE_PREFIX} DESIGN.md is newer than .monodesign/design.json. Run ${MONODESIGN_COMMAND} document to refresh the design-system sidecar.`;
+}
+
+// The directive footer is the part of the hook output that steers model
+// behavior. Three intentional moves:
+//   1. **Imperative, not advisory.** "Handle these..." beats "Consider
+//      revising..." which the model treats as a soft suggestion it can
+//      override when the user asked for any kind of throwaway / demo UI.
+//   2. **Explicit judgment clause.** Without it, the model will try to
+//      "fix" intentional motion, bad fixtures, anti-pattern examples in
+//      docs, or test cases. Naming the judgment inline beats hoping the
+//      model infers it from context.
+//   3. **Acknowledgement instruction.** Hook output is injected as
+//      developer-role context, not a chat turn, so the user never sees the
+//      raw envelope. Asking the model to surface the resolution in its
+//      reply is the cheapest way to make the feedback loop visible.
+function directiveFooter(display, opts = {}) {
+  const ignoreFileCommand = `${MONODESIGN_COMMAND} hooks ignore-file ${quoteCommandArg(display)}`;
+  const fileIgnoreGuidance = opts.grouped
+    ? `run \`${MONODESIGN_COMMAND} hooks ignore-file <path>\` for the specific file`
+    : `run \`${ignoreFileCommand}\``;
+  return [
+    'Handle these before finalizing: fix findings that are real design problems, or explicitly classify contextually intentional findings as false positives. Acknowledge what you changed or why you are leaving a finding unchanged.',
+    '',
+    'Use context judgment before editing. A finding is not automatically a defect; literal or domain-appropriate motion, intentional demos or fixtures, documentation of bad design, and user-confirmed choices can be valid as-is.',
+    '',
+    `Do not change intentional design just to satisfy the hook, and do not silence a real finding with an inline ignore comment to skip fixing it. Suppress a finding only after the user explicitly confirms it is intentional. Prefer a config ignore (one reviewable place, the commands below); reach for an inline \`monodesign-disable <rule>\` comment only when the waiver must travel with a file that leaves the repo, such as an exported or standalone document. Prefer the narrowest persisted exception: run the exact \`${MONODESIGN_COMMAND} hooks ignore-value ... --shared\` command shown next to a value-specific finding. For \`overused-font\`, use \`ignore-value\` for a specific font and use \`${MONODESIGN_COMMAND} hooks ignore-rule overused-font --all-values\` only when the user asks to ignore overused fonts generally. For file-specific findings without an ignore-value command, ${fileIgnoreGuidance}; use \`${MONODESIGN_COMMAND} hooks ignore-rule <id>\` only when the user asks to suppress the whole non-value-specific rule. Run ${MONODESIGN_COMMAND} audit for the full pass.`,
+  ].join('\n');
+}
+
+export function payload(text, eventName = 'PostToolUse', harness = 'claude') {
+  if (harness === 'cursor') {
+    return JSON.stringify({ additional_context: text });
+  }
+  // GitHub Copilot's postToolUse hook injects context via a top-level
+  // `additionalContext` string (alongside an optional `modifiedResult`).
+  if (harness === 'github') {
+    return JSON.stringify({ additionalContext: text });
+  }
+  return JSON.stringify({
+    hookSpecificOutput: { hookEventName: eventName, additionalContext: text },
+  });
+}