The design language that makes your AI harness better at design.
JavaScript
Denoise the design hook and let agents self-serve confident ignores (#508)
Abdul Wahabdc4e4a4bd612
diff --git a/skill/reference/hooks.md b/skill/reference/hooks.mdindex fa6222274..d6df929de 100644--- a/skill/reference/hooks.md+++ b/skill/reference/hooks.md@@ -48,14 +48,20 @@ The first argument is the action. Defaults to `status`.5. If `<action>` is `ignore-value`, `ignore-file`, or `ignore-rule`, just print the script output. The default scope is shared `.impeccable/config.json`; add `--local` only when the user explicitly asks for a private exception.6. If `<action>` is `status`, just print the script output. Do not add commentary unless the user asked a follow-up question.-## Intentional findings+## Triage findings-The hook itself never writes ignore config. Persist an exception only after the user explicitly confirms the flagged issue is intentional, and always go through `hook-admin.mjs`.+The hook itself never writes ignore config; every exception goes through `hook-admin.mjs`. Triage each finding into one of three outcomes:++- **Real design problem**: fix it. Never add an ignore to skip a fix or to push a blocked write through.+- **Confident false positive or sanctioned exception**: persist the narrowest ignore yourself and disclose it in your reply. The bar is evidence you can name: an intentional demo or fixture, documentation of bad design, literal or domain-appropriate motion (a ball that bounces), or a choice the user already confirmed. Put that evidence in `--reason` as `"<who decided: evidence>"`; write "user confirmed" only when the user actually did.+- **Unsure**: leave the finding standing and ask the user in one line. Ask once; a one-line question costs less than the hook re-firing on every later edit.++Self-serve stops at `ignore-value`. `ignore-file` and `ignore-rule` silence too much to add on your own judgment; ask the user first.Prefer the narrowest exception:-- If the finding line shows an exact `ignore-value` command, run that command. This writes shared `.impeccable/config.json` by default.-- For value-specific findings such as `overused-font` and `bounce-easing`, use `ignore-value` when the user confirms the specific value. Do not use `ignore-rule overused-font` for a specific font.+- If the finding line shows an `ignore-value <rule> <value>` pair, pass it to `hook-admin.mjs ignore-value` with your `--reason`. This writes shared `.impeccable/config.json` by default.+- For value-specific findings such as `overused-font` and `bounce-easing`, use `ignore-value` for the specific value. Do not use `ignore-rule overused-font` for a specific font.- If the finding has no value-specific command, such as `side-tab`, scope that one rule to the file: `ignore-value <id> "*" --file <path>`. Run `npx impeccable detect <path>` first to see what actually fires there.- Reach for `ignore-file <path>` only when the whole file is out of scope for design review: a fixture, a generated artifact, a deliberate slop demo. It silences every rule for that file permanently, including rules that have not been written yet. A real UI surface with one noisy rule wants the file-scoped value ignore above.- Use `ignore-rule <id>` only when the user asks to suppress that whole rule across the project. For broad overused-font suppression, use `ignore-rule overused-font --all-values` only when the user asks to ignore overused fonts generally.@@ -67,10 +73,10 @@ Example value-specific exception:node {{scripts_path}}/hook-admin.mjs ignore-value overused-font Inter --shared --reason "User confirmed Inter is intentional"```-Example intentional motion exception:+Example self-served exception, with the evidence named:```bash-node {{scripts_path}}/hook-admin.mjs ignore-value bounce-easing bounce-ball --shared --reason "User confirmed ball bounce animation is intentional"+node {{scripts_path}}/hook-admin.mjs ignore-value bounce-easing bounce-ball --shared --reason "Agent: literal ball-bounce animation, bounce easing is the subject"```Example whole-rule font exception:diff --git a/skill/scripts/hook-before-edit.mjs b/skill/scripts/hook-before-edit.mjsindex 1dcde6ef3..04050a8eb 100644--- a/skill/scripts/hook-before-edit.mjs+++ b/skill/scripts/hook-before-edit.mjs@@ -16,11 +16,15 @@ 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,@@ -345,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) {@@ -468,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) {diff --git a/skill/scripts/hook-lib.mjs b/skill/scripts/hook-lib.mjsindex 9170aa696..794ac59a1 100644--- a/skill/scripts/hook-lib.mjs+++ b/skill/scripts/hook-lib.mjs@@ -22,6 +22,9 @@* dedupeAgainstCache(findings, cache, sessionId, filePath)* renderTemplate(findings, filePath, config, opts)* renderCleanAck(filePath, opts) / renderPendingAck(filePath, known, opts)+ * appendDesignSystemNote(text, scanOptions) / appendDesignSystemNoteOnce(text, scanOptions, cache, sessionId, config)+ * designNoteReserve(scanOptions, cache, sessionId)+ * footerModeForSession(cache, sessionId) / commitFooterShown(cache, sessionId, text)* shouldEmitAckForFile(filePath, config?)* writeAuditLog(env, entry)* loadDetector() -> Promise<{ detectText, detectHtml }>@@ -970,7 +973,13 @@ 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);+ // reserveChars holds back room for a note the caller appends after render+ // (the DESIGN.md staleness note), so the final payload stays inside the+ // configured budget. It comes off after the 500-char floor, so at floor+ // configs the note keeps guaranteed delivery room; the clamp budget can+ // therefore sit below 500, which clampLastLine's footer-preserving+ // fallback handles (Bugbot on PR #508).+ const maxChars = Math.max(500, limits.maxChars || DEFAULT_CONFIG.limits.maxChars) - (opts.reserveChars || 0);const cwd = opts.cwd || process.cwd();const display = relativize(filePath, cwd);@@ -979,11 +988,12 @@ export function renderTemplate(findings, filePath, config, opts = {}) {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 seenRules = new Set();+ const lines = shown.map((f) => formatDedupedFindingLine(f, seenRules));const more = remaining > 0? `... and ${remaining} more (see ${IMPECCABLE_COMMAND} audit).`: null;- const footer = directiveFooter(display);+ const footer = directiveFooter({ mode: opts.footer });const blocks = [header, ...lines];if (more) blocks.push(more);@@ -1007,12 +1017,15 @@ function renderGroupedTemplate(groups, 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 maxChars = Math.max(500, limits.maxChars || DEFAULT_CONFIG.limits.maxChars) - (opts.reserveChars || 0);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;+ // One seen-set across all groups: a rule already described under one file+ // is not re-described under the next.+ const seenRules = new Set();for (const group of realGroups) {const display = relativize(group.filePath, cwd);@@ -1020,7 +1033,7 @@ function renderGroupedTemplate(groups, config, opts = {}) {const remainingCap = Math.max(0, cap - shownCount);const shown = group.findings.slice(0, remainingCap);for (const finding of shown) {- lines.push(formatFindingLine(finding));+ lines.push(formatDedupedFindingLine(finding, seenRules));}shownCount += shown.length;const hidden = group.findings.length - shown.length;@@ -1029,7 +1042,7 @@ function renderGroupedTemplate(groups, config, opts = {}) {}}- const footer = directiveFooter('the affected files', { grouped: true });+ const footer = directiveFooter({ mode: opts.footer });let text = [header, ...lines, '', footer].join('\n');if (text.length > maxChars) {text = clampGroupedToBudget(header, lines, footer, maxChars);@@ -1037,76 +1050,131 @@ function renderGroupedTemplate(groups, config, opts = {}) {return text;}+// The clamp contract, shared by both budget functions: the footer is policy,+// not detail, so it survives every clamp. Try the requested footer first;+// when it cannot fit even after dropping finding lines, retry with the short+// policy rather than sacrifice findings that fit beside it. A result that+// dropped every finding line (a grouped render can fit a bare file header)+// does not count as a fit: findings are why the emission exists.+const isFindingLine = (line) => line.startsWith('- ');++function footerFallbacks(footer) {+ const short = directiveFooter({ mode: 'short' });+ return footer === short ? [footer] : [footer, short];+}+function clampGroupedToBudget(header, lines, footer, maxChars) {- const assemble = (linesArr, omitted) => [+ const assemble = (linesArr, omitted, footerText) => [header,...linesArr,...(omitted ? [`... and more (see ${IMPECCABLE_COMMAND} audit).`] : []),'',- footer,+ footerText,].join('\n');- let 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)}…`;+ for (const footerText of footerFallbacks(footer)) {+ let working = lines.slice();+ let omitted = false;+ let assembled = assemble(working, omitted, footerText);+ while (assembled.length > maxChars && working.length > 1) {+ working.pop();+ omitted = true;+ assembled = assemble(working, omitted, footerText);+ }+ if (assembled.length <= maxChars && working.some(isFindingLine)) return assembled;}- return assembled;+ return clampLastLine((linesArr, footerText) => assemble(linesArr, true, footerText),+ lines.find(isFindingLine) || lines[0], maxChars);}function clampToBudget(header, lines, more, footer, maxChars) {- const assemble = (linesArr, moreText) => {+ const assemble = (linesArr, moreText, footerText) => {const blocks = [header, ...linesArr];if (moreText) blocks.push(moreText);blocks.push('');- blocks.push(footer);+ blocks.push(footerText);return blocks.join('\n');};- let working = lines.slice();- let moreText = more;- let assembled = assemble(working, moreText);- while (assembled.length > maxChars && working.length > 1) {- working.pop();- moreText = `... and more (see ${IMPECCABLE_COMMAND} audit).`;- assembled = assemble(working, moreText);- }- if (assembled.length > maxChars) {- assembled = `${assembled.slice(0, maxChars - 1)}…`;- }- return assembled;-}--function formatFindingLine(f) {+ let lastMore = more;+ for (const footerText of footerFallbacks(footer)) {+ let working = lines.slice();+ let moreText = more;+ let assembled = assemble(working, moreText, footerText);+ while (assembled.length > maxChars && working.length > 1) {+ working.pop();+ moreText = `... and more (see ${IMPECCABLE_COMMAND} audit).`;+ assembled = assemble(working, moreText, footerText);+ }+ lastMore = moreText;+ if (assembled.length <= maxChars) return assembled;+ }+ return clampLastLine((linesArr, footerText) => assemble(linesArr, lastMore, footerText),+ lines.find(isFindingLine) || lines[0], maxChars);+}++// Last resort with one finding line left: the short policy gets the budget+// first, the line is clipped to what remains. The pre-fix tail-slice cut+// whatever happened to be last, which was always the footer.+function clampLastLine(build, line, maxChars) {+ const footerText = directiveFooter({ mode: 'short' });+ const bare = build([], footerText);+ // +1 for the newline the line itself brings when it joins the blocks.+ const room = maxChars - bare.length - 1;+ if (room >= 24) {+ const clipped = line.length > room ? `${line.slice(0, room - 1)}…` : line;+ return build([clipped], footerText);+ }+ // No room for even a clipped finding line: the note reservation can pull+ // the budget below the 500-char floor, and a deep file path can push the+ // header past what remains beside the short policy (Bugbot on PR #508).+ // Drop the line, and if the bare header + policy still overflow, clip the+ // head. Never tail-slice: the footer sits at the end, so a tail slice is+ // exactly the footer cut this renderer exists to prevent.+ if (bare.length <= maxChars) return bare;+ const head = bare.slice(0, Math.max(0, maxChars - footerText.length - 4));+ return `${head}…\n\n${footerText}`;+}++// `compact` drops the registry description: within one emission the first+// occurrence of a rule carries the full description and repeats keep only the+// rule id, name, and their own ignore hint (values differ per line, so the+// hint must survive the dedupe).+function formatFindingLine(f, opts = {}) {const prefix = f.line && f.line > 0 ? `- L${f.line}` : '-';- const desc = (f.description || '').trim();+ const desc = opts.compact ? '' : (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}\`.`- : '';+ const ignoreHint = formatFindingIgnoreHint(f);+ const ignoreSegment = ignoreHint ? ` If intentional: \`${ignoreHint}\`.` : '';return `${prefix} [${f.antipattern}] ${nameSegment} ${desc}${ignoreSegment}`.replace(/\s+/g, ' ').trim();}-function formatFindingIgnoreCommand(finding) {+// Dedupe applied in shown-line order, so the first rendered occurrence of a+// rule always carries the description. The budget clamps pop lines from the+// end, which can never orphan a compact repeat before its described first+// occurrence.+function formatDedupedFindingLine(finding, seenRules) {+ const rule = normalizeIgnoreRule(finding?.antipattern);+ const compact = rule ? seenRules.has(rule) : false;+ if (rule) seenRules.add(rule);+ return formatFindingLine(finding, { compact });+}++// The rule/value pair the footer's `hook-admin.mjs ignore-value` command+// takes. Deliberately just the args: the executable prefix, the --reason+// contract, and the disclosure rule live in the directive footer, stated once+// instead of per line.+function formatFindingIgnoreHint(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 `${IMPECCABLE_COMMAND} hooks ignore-value ${rule} ${valueArg} --shared --reason ${reason}`;+ const valueArg = quoteCommandArg(extractFindingIgnoreValueRaw(finding));+ return `ignore-value ${rule} ${valueArg}`;}function quoteCommandArg(value) {@@ -1606,36 +1674,105 @@ export function designSystemOptions(config, detector, projectCwd) {}}+const DESIGN_STALE_NOTE = `${ENVELOPE_PREFIX} DESIGN.md is newer than .impeccable/design.json. Run ${IMPECCABLE_COMMAND} document to refresh the design-system sidecar.`;+export function appendDesignSystemNote(text, scanOptions) {if (!text || !scanOptions?.designSystem?.mdNewerThanJson) return text;- return `${text}\n\n${ENVELOPE_PREFIX} DESIGN.md is newer than .impeccable/design.json. Run ${IMPECCABLE_COMMAND} document to refresh the design-system sidecar.`;+ return `${text}\n\n${DESIGN_STALE_NOTE}`;+}++// Session-scoped once-only gate for repeat-prone message parts. Returns true+// the first time a flag is consumed in a session and false after, mirroring+// the `cleanAcked` mechanic: the mtime skew (and the policy footer) do not+// change between edits, so re-stating them on every emission spends context+// to say nothing new. Callers must persist the cache for the flag to stick.+function consumeSessionNoticeFlag(cache, sessionId, flag) {+ const session = ensureSession(cache, sessionId);+ if (session[flag]) return false;+ session[flag] = true;+ session.updatedAt = Date.now();+ return true;+}++// Once-per-session variant of appendDesignSystemNote for the emission paths+// that have cache access. The staleness note names standing project state,+// not new information, so one mention per session is enough. The note is+// appended after the renderer has clamped to the configured budget: render+// paths reserve room for it via designNoteReserve, and the size check here+// is the safety net for the ack paths, deferring (without consuming the+// flag) to a later emission rather than busting maxChars.+export function appendDesignSystemNoteOnce(text, scanOptions, cache, sessionId, config) {+ if (!text || !scanOptions?.designSystem?.mdNewerThanJson) return text;+ const maxChars = Math.max(500, config?.limits?.maxChars || DEFAULT_CONFIG.limits.maxChars);+ if (text.length + DESIGN_STALE_NOTE.length + 2 > maxChars) return text;+ if (!consumeSessionNoticeFlag(cache, sessionId, 'designNoteShown')) return text;+ return appendDesignSystemNote(text, scanOptions);+}++// Render-time reservation for the note above: how many characters the+// renderer must hold back so a pending staleness note still fits inside the+// configured budget. Zero once the session has seen the note. Without the+// reservation, a session whose every emission fills the budget would defer+// the note forever.+export function designNoteReserve(scanOptions, cache, sessionId) {+ if (!scanOptions?.designSystem?.mdNewerThanJson) return 0;+ if (ensureSession(cache, sessionId).designNoteShown) return 0;+ return DESIGN_STALE_NOTE.length + 2;+}++// Full directive footer once per session, the short reminder after. Fresh+// emissions and Cursor denials share the session flag (`footerShown`), so a+// session pays the full policy exactly once however it first fires. The mode+// is a peek: the clamp can downgrade a requested full footer under a tight+// budget, so the flag commits only when the complete full policy actually+// reached the output. Matching the whole footer text (not a sentinel) keeps+// the flag honest against any truncation that spares the opening words.+export function footerModeForSession(cache, sessionId) {+ return ensureSession(cache, sessionId).footerShown ? 'short' : 'full';+}++export function commitFooterShown(cache, sessionId, text) {+ if (!text || !text.includes(directiveFooter())) return;+ const session = ensureSession(cache, sessionId);+ if (session.footerShown) return;+ session.footerShown = true;+ session.updatedAt = Date.now();}+const HOOK_ADMIN_COMMAND = `node ${quoteCommandArg(path.join(__dirname, 'hook-admin.mjs'))}`;+// 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 = {}) {- // Offer the rule-scoped-to-file form first. `ignore-file` silences every rule- // for the path forever, which is far more than one noisy rule on a real UI- // surface justifies, and it was previously the only option named here.- const target = opts.grouped ? '<path>' : quoteCommandArg(display);- const fileIgnoreGuidance = `run \`${IMPECCABLE_COMMAND} hooks ignore-value <id> "*" --file ${target}\` to scope just that rule to the file, or \`${IMPECCABLE_COMMAND} hooks ignore-file ${target}\` only when the whole file is out of scope for design review (a fixture, a generated artifact, a deliberate demo)`;+// behavior. Intentional moves, in order:+// 1. **Imperative, not advisory.** "Triage each finding..." beats+// "Consider revising...", which the model treats as a soft suggestion.+// 2. **Positive triage branches.** Fix / suppress-and-disclose / ask. The+// suppress branch names the calibration examples (demo, fixture,+// documented bad design, user-confirmed choice) because the agent now+// acts on its own confidence and needs the bar stated.+// 3. **Executable ignore path.** The old footer named only the slash+// command, which an agent reacting to hook output cannot run; the+// hook-admin.mjs invocation is runnable as-is and keeps agents out of+// hand-editing config.json.+// 4. **Honest provenance.** The --reason is the audit trail; "user+// confirmed" appears only when the user actually did.+// 5. **Acknowledgement instruction.** Hook output is injected as+// developer-role context, so the reply is where the user sees the+// resolution, including any ignore the agent persisted.+// 6. **Once per session.** The full policy emits on the session's first+// fire; later emissions carry the one-line short form (mode 'short').+function directiveFooter(opts = {}) {+ if (opts.mode === 'short') {+ // No command path here: the session's first emission already gave the+ // runnable hook-admin.mjs invocation, and restating ~70 chars of absolute+ // path on every repeat is the duplication this mode exists to cut.+ return 'Triage per the session policy: fix real problems; persist confident false-positive or sanctioned-exception ignores via `hook-admin.mjs ignore-value` and disclose them in your reply; unsure, ask in one line.';+ }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 \`impeccable-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 \`${IMPECCABLE_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 \`${IMPECCABLE_COMMAND} hooks ignore-rule overused-font --all-values\` only when the user asks to ignore overused fonts generally. For a finding whose line shows no exact ignore-value command, such as \`side-tab\`, ${fileIgnoreGuidance}; use \`${IMPECCABLE_COMMAND} hooks ignore-rule <id>\` only when the user asks to suppress the whole non-value-specific rule. Run ${IMPECCABLE_COMMAND} audit for the full pass.`,+ 'Triage each finding, then state in your reply what you fixed, what you suppressed, and what you left standing:',+ '- Real design problem: fix it. Keep intentional design as designed.',+ `- Confident false positive or sanctioned exception (an intentional demo or fixture, documentation of bad design, literal or domain-appropriate motion, a choice the user confirmed): persist the narrowest ignore yourself and disclose it. Run \`${HOOK_ADMIN_COMMAND} ignore-value <rule> "<value>" --reason "<who decided: evidence>"\` with the pair shown on the finding line, or value "*" plus \`--file <path>\` when the line shows none. Write "user confirmed" in a reason only when the user did.`,+ '- Unsure: leave it as is and ask the user in one line.',+ `Self-serve ends at ignore-value: \`ignore-file\` and \`ignore-rule\` need the user's explicit approval, and never add an ignore to push a blocked write through. Full suppression ladder: ${IMPECCABLE_COMMAND} hooks.`,].join('\n');}@@ -1857,20 +1994,23 @@ export async function runHook({ stdinJson, env = {}, cwd = process.cwd(), now =}}- // Persist only when the write is earned: fresh findings justify creating- // `.impeccable/` (dedup and suppression need it), deferred findings do- // too (the Stop deep pass needs the touched-file list to surface them),- // and an already-present `.impeccable/` dir marks a project that opted- // in. A non-UI edit, or a clean UI edit in a project with no Impeccable- // footprint, must be a no-op on disk (issues #344, #305).- if (freshGroups.length > 0 || deferredTotal > 0- || (cacheDirty && fs.existsSync(path.join(projectCwd, '.impeccable')))) {- persistCache(projectCwd, cache);- }-+ // The session notice flags mutate the cache, so they must settle before+ // the persist that makes them stick across events.if (freshGroups.length > 0) {const firstGroup = freshGroups[0];- const text = appendDesignSystemNote(renderGroupedTemplate(freshGroups, config, { cwd: projectCwd }), scanOptions);+ const footerMode = footerModeForSession(cache, sessionId);+ const text = appendDesignSystemNoteOnce(+ renderGroupedTemplate(freshGroups, config, {+ cwd: projectCwd,+ footer: footerMode,+ reserveChars: designNoteReserve(scanOptions, cache, sessionId),+ }),+ scanOptions, cache, sessionId, config,+ );+ commitFooterShown(cache, sessionId, text);+ // Fresh findings always earn the cache write, including creating+ // `.impeccable/`: dedup, suppression, and the notice flags need it.+ persistCache(projectCwd, cache);const allFindings = freshGroups.flatMap((group) => group.findings);return {exitCode: 0,@@ -1893,6 +2033,33 @@ export async function runHook({ stdinJson, env = {}, cwd = process.cwd(), now =};}+ // Resolve the ack emission before the persist below: appendDesignSystem-+ // NoteOnce consumes a session flag, and the flag only sticks when the+ // write happens after it. Quiet mode emits nothing, so it consumes+ // nothing. The clean arm mirrors the branch order further down: pending+ // outranks suppression, suppression outranks clean.+ let ack = null;+ if (!quietMode && pendingWinner && shouldEmitAckForFile(pendingWinner.filePath, config)) {+ ack = {+ kind: 'pending',+ text: appendDesignSystemNoteOnce(renderPendingAck(pendingWinner.filePath, pendingWinner.known, { cwd: projectCwd }), scanOptions, cache, sessionId, config),+ };+ } else if (!quietMode && !suppressionWinner && cleanWinner && !cleanAckDeduped && shouldEmitAckForFile(cleanWinner.filePath, config)) {+ ack = {+ kind: 'clean',+ text: appendDesignSystemNoteOnce(renderCleanAck(cleanWinner.filePath, { cwd: projectCwd }), scanOptions, cache, sessionId, config),+ };+ }++ // Persist only when the write is earned: deferred findings need the+ // touched-file list for the Stop deep pass, and an already-present+ // `.impeccable/` dir marks a project that opted in. A non-UI edit, or a+ // clean UI edit in a project with no Impeccable footprint, must be a+ // no-op on disk (issues #344, #305).+ if (deferredTotal > 0 || (cacheDirty && fs.existsSync(path.join(projectCwd, '.impeccable')))) {+ persistCache(projectCwd, cache);+ }+if (detectorThrewAny && !pendingWinner && !cleanWinner) {return result({ emitted: false, error: 'detector-threw', durationMs: Date.now() - started });}@@ -1901,8 +2068,8 @@ export async function runHook({ stdinJson, env = {}, cwd = process.cwd(), now =return result({ emitted: false, quiet: true, durationMs: Date.now() - started });}- if (pendingWinner && shouldEmitAckForFile(pendingWinner.filePath, config)) {- const text = appendDesignSystemNote(renderPendingAck(pendingWinner.filePath, pendingWinner.known, { cwd: projectCwd }), scanOptions);+ if (ack?.kind === 'pending') {+ const text = ack.text;return {exitCode: 0,stdout: payload(text, 'PostToolUse', harness),@@ -1935,8 +2102,8 @@ export async function runHook({ stdinJson, env = {}, cwd = process.cwd(), now =};}- if (cleanWinner && !cleanAckDeduped && shouldEmitAckForFile(cleanWinner.filePath, config)) {- const text = appendDesignSystemNote(renderCleanAck(cleanWinner.filePath, { cwd: projectCwd }), scanOptions);+ if (ack?.kind === 'clean') {+ const text = ack.text;return {exitCode: 0,stdout: payload(text, 'PostToolUse', harness),@@ -2120,11 +2287,22 @@ export async function runStopHook({ stdinJson, env = {}, cwd = process.cwd(), noreturn result({ emitted: false, skipped: 'stop-clean', durationMs: Date.now() - started });}+ // A per-edit fire earlier in this session already consumed the footer+ // flag, so the Stop wall of text carries the one-line short footer.+ const footerMode = footerModeForSession(cache, sessionId);+ const text = appendDesignSystemNoteOnce(+ renderGroupedTemplate(freshGroups, config, {+ cwd: projectCwd,+ footer: footerMode,+ reserveChars: designNoteReserve(scanOptions, cache, sessionId),+ }),+ scanOptions, cache, sessionId, config,+ );+ commitFooterShown(cache, sessionId, text);+// Fresh findings earn the cache write so the next Stop fire is silent- // unless new issues appear.+ // unless new issues appear; the notice flags ride along.persistCache(projectCwd, cache);-- const text = appendDesignSystemNote(renderGroupedTemplate(freshGroups, config, { cwd: projectCwd }), scanOptions);return {exitCode: 0,stdout: payload(text, 'Stop', harness),diff --git a/tests/hook.test.mjs b/tests/hook.test.mjsindex d4c9589db..412c04ccb 100644--- a/tests/hook.test.mjs+++ b/tests/hook.test.mjs@@ -50,6 +50,7 @@ import {coLocatedStylesheets,runHook,runStopHook,+ commitFooterShown,IMMEDIATE_TIER_RULES,splitFindingsByTier,perEditTieringActive,@@ -1093,59 +1094,96 @@ describe('renderTemplate()', () => {const text = renderTemplate(findings, '/x/Card.tsx', DEFAULT_CONFIG, { cwd: '/x' });assert.ok(text.startsWith(`${ENVELOPE_PREFIX} Design hook findings requiring review in Card.tsx (12 issue(s)):`));assert.match(text, /\.\.\. and 7 more \(see \/impeccable audit\)\./);- // Exactly 5 finding lines.- const lines = text.split('\n').filter((l) => l.startsWith('- '));+ // Exactly 5 finding lines. The footer's triage bullets also start with+ // "- ", so count only lines carrying a rule id.+ const lines = text.split('\n').filter((l) => /^- L\d+ \[/.test(l));assert.equal(lines.length, 5);assert.ok(text.length <= DEFAULT_CONFIG.limits.maxChars);});- it('emits a directive footer (imperative + judgment clause + confirmed ignore guidance)', () => {- // Steers the model: imperative "handle", explicit context judgment- // before editing, and "acknowledge" so the user sees the resolution- // in the chat reply. See `directiveFooter()` in hook-lib.mjs for- // the rationale.+ it('emits a directive footer (triage branches + executable self-serve ignore + honest provenance)', () => {+ // Steers the model: imperative triage into fix / suppress-and-disclose /+ // ask, a runnable hook-admin.mjs path for the self-served ignore, and the+ // provenance rule for --reason. See `directiveFooter()` in hook-lib.mjs+ // for the rationale.const text = renderTemplate([finding('side-tab', 1, { name: 'X' })],'/x/Card.tsx', DEFAULT_CONFIG, { cwd: '/x' });- assert.match(text, /Handle these before finalizing/);- assert.match(text, /fix findings that are real design problems/);- assert.match(text, /classify contextually intentional findings as false positives/);- assert.match(text, /Use context judgment before editing/);- assert.match(text, /not automatically a defect/);+ assert.match(text, /Triage each finding/);+ assert.match(text, /what you fixed, what you suppressed, and what you left standing/);+ assert.match(text, /Real design problem: fix it\. Keep intentional design as designed\./);+ assert.match(text, /Confident false positive or sanctioned exception/);assert.match(text, /literal or domain-appropriate motion/);- assert.match(text, /Do not change intentional design just to satisfy the hook/);- assert.match(text, /Suppress a finding only after the user explicitly confirms it is intentional/);- assert.match(text, /do not silence a real finding with an inline ignore comment/);- assert.match(text, /inline `impeccable-disable <rule>` comment only when the waiver must travel with a file/);- assert.match(text, /ignore-value \.\.\. --shared/);- assert.match(text, /ignore-rule overused-font --all-values/);- assert.match(text, /\/impeccable hooks ignore-file Card\.tsx/);- assert.match(text, /ignore-rule <id>/);- assert.match(text, /\/impeccable audit/);+ assert.match(text, /persist the narrowest ignore yourself and disclose it/);+ // quoteCommandArg quotes the hook-admin.mjs path per platform (single+ // quotes on POSIX, double on Windows; #533), so match either close quote.+ assert.match(text, /hook-admin\.mjs['"] ignore-value <rule> "<value>" --reason "<who decided: evidence>"/);+ assert.match(text, /Write "user confirmed" in a reason only when the user did/);+ assert.match(text, /Unsure: leave it as is and ask the user in one line/);+ assert.match(text, /Self-serve ends at ignore-value/);+ assert.match(text, /never add an ignore to push a blocked write through/);+ assert.match(text, /Full suppression ladder: \/impeccable hooks/);+ });++ it('renders the one-line short footer when opts.footer is "short"', () => {+ const text = renderTemplate(+ [finding('side-tab', 1, { name: 'X' })],+ '/x/Card.tsx', DEFAULT_CONFIG, { cwd: '/x', footer: 'short' }+ );+ assert.match(text, /Triage per the session policy/);+ // The short form names the tool without the absolute path; the runnable+ // invocation lives only in the session's first (full) footer. The quoted+ // path would render as `node '...'` on POSIX or `node "..."` on Windows,+ // so reject both.+ assert.match(text, /`hook-admin\.mjs ignore-value`/);+ assert.doesNotMatch(text, /node ['"]/);+ assert.match(text, /unsure, ask in one line/);+ assert.doesNotMatch(text, /Triage each finding/);+ assert.doesNotMatch(text, /Self-serve ends at ignore-value/);+ });++ it('dedupes rule descriptions within one emission, keeping per-line ignore hints', () => {+ const desc = 'Long registry description that should appear once.';+ const text = renderTemplate(+ [+ finding('overused-font', 2, { name: 'Overused font', description: desc, snippet: 'font-family: "Roboto"' }),+ finding('overused-font', 9, { name: 'Overused font', description: desc, snippet: 'font-family: "Inter"' }),+ ],+ '/x/fonts.css', DEFAULT_CONFIG, { cwd: '/x' }+ );+ const occurrences = text.split(desc).length - 1;+ assert.equal(occurrences, 1);+ // The repeat keeps the rule id, name, and its own value-specific hint.+ assert.match(text, /- L9 \[overused-font\] Overused font\. If intentional: `ignore-value overused-font Inter`\./);+ assert.match(text, /`ignore-value overused-font Roboto`/);});- it('shows the exact value-specific command for overused-font findings', () => {+ it('shows the value-specific ignore hint for overused-font findings', () => {const text = renderTemplate([finding('overused-font', 1, { name: 'Overused font', snippet: 'body { font-family: "Roboto", sans-serif; }' })],'/x/fonts.css', DEFAULT_CONFIG, { cwd: '/x' });- assert.match(text, /\/impeccable hooks ignore-value overused-font Roboto --shared/);- assert.match(text, /ignore-rule overused-font --all-values/);+ // The line carries just the rule/value pair; the runnable hook-admin.mjs+ // prefix and the --reason contract are stated once in the footer.+ assert.match(text, /If intentional: `ignore-value overused-font Roboto`\./);});- it('shows the exact value-specific command for bounce-easing findings', () => {+ it('shows the value-specific ignore hint for bounce-easing findings', () => {const text = renderTemplate([finding('bounce-easing', 1, { name: 'Bounce or elastic easing', snippet: 'animation: bounce-ball' })],'/x/main.css', DEFAULT_CONFIG, { cwd: '/x' });- assert.match(text, /\/impeccable hooks ignore-value bounce-easing bounce-ball --shared/);+ assert.match(text, /If intentional: `ignore-value bounce-easing bounce-ball`\./);});it('single-quotes a hostile font value so the suggestion cannot inject a shell command (#476)', () => {- // The suggested command comes straight from scanned file content. A- // double-quoted arg would leave $(...) live for whoever runs the- // suggestion; single quotes neutralize it.+ // The suggested pair comes straight from scanned file content. A+ // double-quoted arg would leave $(...) live for whoever pastes it into+ // the footer's hook-admin.mjs command; single quotes neutralize it. The+ // hint format is now the bare `ignore-value <rule> '<value>'` pair (the+ // runnable command prefix, --shared/--reason contract live in the+ // footer), but the value still goes through quoteCommandArg.const text = renderTemplate([finding('overused-font', 1, {name: 'Overused font',@@ -1153,29 +1191,55 @@ describe('renderTemplate()', () => {})],'/x/fonts.css', DEFAULT_CONFIG, { cwd: '/x' });- assert.match(text, /ignore-value overused-font '\$\(touch pwned\)' --shared/);+ assert.match(text, /ignore-value overused-font '\$\(touch pwned\)'/);assert.doesNotMatch(text, /ignore-value overused-font "\$\(touch pwned\)"/);});- it('quotes the --file path per platform: single quotes on POSIX, double quotes on Windows (#533)', () => {- // The suggested command is run on the same machine the hook fired on.- // POSIX needs single quotes so $(...) in a filename cannot execute; Windows- // cmd.exe treats single quotes as literal, so a path with spaces must stay- // double-quoted or the ignore scope is split at the space.+ it('quotes a hint value per platform: single quotes on POSIX, double quotes on Windows (#533)', () => {+ // #533 originally targeted the footer's concrete `--file <path>`+ // suggestion; directiveFooter() now carries only literal placeholders+ // (`--file <path>`), so that surface is gone. The quoting-sensitive+ // surface that remains user-visible is the per-finding ignore hint,+ // whose value comes straight from scanned file content and is meant to+ // be pasted into the footer's command on this same machine. POSIX needs+ // single quotes so $(...) cannot execute; Windows cmd.exe treats single+ // quotes as literal, so a value with spaces must stay double-quoted or+ // the ignore scope is split at the space.const original = process.platform;const renderFor = (platform) => {Object.defineProperty(process, 'platform', { value: platform, configurable: true });try {return renderTemplate(- [finding('side-tab', 1, { name: 'Side tab' })],- '/x/My Components/Card.tsx', DEFAULT_CONFIG, { cwd: '/x' }+ [finding('overused-font', 1, {+ name: 'Overused font',+ snippet: 'h1 { font-family: "Space Grotesk Var", sans-serif; }',+ })],+ '/x/fonts.css', DEFAULT_CONFIG, { cwd: '/x' });} finally {Object.defineProperty(process, 'platform', { value: original, configurable: true });}};- assert.match(renderFor('linux'), /--file 'My Components\/Card\.tsx'/);- assert.match(renderFor('win32'), /--file "My Components\/Card\.tsx"/);+ assert.match(renderFor('linux'), /ignore-value overused-font 'Space Grotesk Var'/);+ assert.match(renderFor('win32'), /ignore-value overused-font "Space Grotesk Var"/);+ });++ it('keeps the policy footer when reserveChars presses against the 500-char floor', () => {+ // Bugbot on PR #508: the note reservation used to be subtracted after+ // the 500-char floor, so the clamp could run at ~366 chars, below the+ // budget clampLastLine assumes safe, and the hard tail slice cut the+ // policy footer. The reserve now comes off before the floor; when the+ // floor wins, the note defers instead.+ const config = { ...DEFAULT_CONFIG, limits: { ...DEFAULT_CONFIG.limits, maxChars: 500 } };+ const longPath = `/x/${'deeply-nested/'.repeat(6)}Component.tsx`;+ const text = renderTemplate(+ Array.from({ length: 6 }, (_, i) =>+ finding('side-tab', i + 1, { name: 'Side tab', description: 'Colored side border.' })),+ longPath, config, { cwd: '/x', reserveChars: 134 }+ );+ assert.ok(text.length <= 500, `stays inside the floored budget (got ${text.length})`);+ assert.match(text, /unsure, ask in one line\.$/);+ assert.doesNotMatch(text, /…$/);});it('drops the L<line> prefix when line is 0', () => {@@ -1205,6 +1269,32 @@ describe('renderTemplate()', () => {{ cwd: '/x' });assert.ok(text.length <= 500);});++ it('keeps a policy footer when the clamp cuts down to one finding line', () => {+ // At the minimum budget the full footer cannot fit beside a long finding,+ // so the clamp clips the finding line and downgrades to the short policy+ // instead of slicing the footer off the tail.+ const huge = [finding('side-tab', 1, { name: 'X', description: 'y'.repeat(2000) })];+ const text = renderTemplate(huge, '/x/a.tsx',+ { ...DEFAULT_CONFIG, limits: { maxFindings: 5, maxChars: 500 } },+ { cwd: '/x' });+ assert.ok(text.length <= 500);+ assert.match(text, /\[side-tab\]/, 'the finding is still identified');+ assert.match(text, /Triage per the session policy/, 'a clamped emission still carries the policy');+ });++ it('keeps findings that fit beside the short policy instead of dropping them for the full one', () => {+ const findings = [1, 2, 3].map((line) =>+ finding('side-tab', line, { name: 'X', description: 'short issue' }));+ const text = renderTemplate(findings, '/x/a.tsx',+ { ...DEFAULT_CONFIG, limits: { maxFindings: 5, maxChars: 500 } },+ { cwd: '/x' });+ assert.ok(text.length <= 500);+ assert.match(text, /- L1 /);+ assert.match(text, /- L2 /);+ assert.match(text, /- L3 /, 'all findings survive; the clamp must not drop lines chasing the full policy');+ assert.match(text, /Triage per the session policy/);+ });});describe('writeAuditLog()', () => {@@ -1609,7 +1699,7 @@ rounded:});assert.match(withDesign.stdout, /Design hook findings requiring review/);assert.match(withDesign.stdout, /design-system-font/);- assert.match(withDesign.stdout, /ignore-value design-system-font Poppins --shared/);+ assert.match(withDesign.stdout, /If intentional: `ignore-value design-system-font Poppins`/);});it('respects detector.designSystem.enabled=false', async () => {@@ -2193,6 +2283,116 @@ describe('runHook() — the session cache tracks the current scan', () => {});});+describe('runHook() — session-scoped notices', () => {+ let cwd;+ beforeEach(() => {+ cwd = mkTmp();+ fs.mkdirSync(path.join(cwd, '.impeccable'), { recursive: true });+ });+ afterEach(() => fs.rmSync(cwd, { recursive: true, force: true }));++ const event = (file, sessionId = 'sid-1') => JSON.stringify({+ session_id: sessionId, cwd, hook_event_name: 'PostToolUse',+ tool_name: 'Edit', tool_input: { file_path: file },+ });++ it('emits the full directive footer once per session, then the short reminder', async () => {+ const a = path.join(cwd, 'a.css');+ const b = path.join(cwd, 'b.css');+ fs.writeFileSync(a, 'noop');+ fs.writeFileSync(b, 'noop');+ const det = fakeDetector([finding('tiny-text', 1, { name: 'Tiny text' })]);++ const r1 = await runHook({ stdinJson: event(a), env: {}, cwd, detector: det });+ assert.match(r1.stdout, /Triage each finding/, 'first fresh emission carries the full policy');++ const r2 = await runHook({ stdinJson: event(b), env: {}, cwd, detector: det });+ assert.match(r2.stdout, /Triage per the session policy/);+ assert.doesNotMatch(r2.stdout, /Triage each finding/, 'repeat emissions carry the short reminder');++ // A new session pays the full policy again.+ const r3 = await runHook({ stdinJson: event(a, 'sid-2'), env: {}, cwd, detector: det });+ assert.match(r3.stdout, /Triage each finding/);+ });++ it('mentions the DESIGN.md staleness note once per session', async () => {+ const a = path.join(cwd, 'a.css');+ const b = path.join(cwd, 'b.css');+ fs.writeFileSync(a, 'noop');+ fs.writeFileSync(b, 'noop');+ const det = {+ ...fakeDetector([finding('tiny-text', 1, { name: 'Tiny text' })]),+ loadDesignSystemForCwd: () => ({ present: true, mdNewerThanJson: true }),+ };++ const r1 = await runHook({ stdinJson: event(a), env: {}, cwd, detector: det });+ assert.match(r1.stdout, /DESIGN\.md is newer than \.impeccable\/design\.json/);++ const r2 = await runHook({ stdinJson: event(b), env: {}, cwd, detector: det });+ assert.ok(r2.audit.emitted, 'second file still emits findings');+ assert.doesNotMatch(r2.stdout, /DESIGN\.md is newer/, 'the staleness note does not repeat within a session');+ });++ it('delivers the staleness note inside the budget on a full first emission', async () => {+ fs.writeFileSync(getConfigPath(cwd), JSON.stringify({+ hook: { limits: { maxChars: 500 } },+ }));+ const a = path.join(cwd, 'a.css');+ const b = path.join(cwd, 'b.css');+ fs.writeFileSync(a, 'noop');+ fs.writeFileSync(b, 'noop');+ const det = {+ ...fakeDetector([finding('tiny-text', 1, { name: 'Tiny text', description: 'y'.repeat(600) })]),+ loadDesignSystemForCwd: () => ({ present: true, mdNewerThanJson: true }),+ };++ // A finding this long would fill the whole budget; the renderer must+ // reserve room so the note still lands without busting maxChars.+ const r1 = await runHook({ stdinJson: event(a), env: {}, cwd, detector: det });+ const ctx1 = JSON.parse(r1.stdout).hookSpecificOutput.additionalContext;+ assert.ok(ctx1.length <= 500, `final emission honors maxChars (got ${ctx1.length})`);+ assert.match(ctx1, /DESIGN\.md is newer/, 'the note is delivered on the first emission, not deferred past it');++ const r2 = await runHook({ stdinJson: event(b), env: {}, cwd, detector: det });+ const ctx2 = JSON.parse(r2.stdout).hookSpecificOutput.additionalContext;+ assert.doesNotMatch(ctx2, /DESIGN\.md is newer/, 'one mention per session');+ });++ it('keeps the full-footer flag unspent when the clamp downgrades the footer', async () => {+ fs.writeFileSync(getConfigPath(cwd), JSON.stringify({+ hook: { limits: { maxChars: 500 } },+ }));+ const a = path.join(cwd, 'a.css');+ fs.writeFileSync(a, 'noop');+ const det = fakeDetector([finding('tiny-text', 1, { name: 'Tiny text', description: 'y'.repeat(600) })]);++ // 500 chars cannot hold the full policy, so the emission carries the+ // short form. The session must not be marked as having seen the full+ // footer it never received.+ const r1 = await runHook({ stdinJson: event(a), env: {}, cwd, detector: det });+ assert.match(r1.stdout, /Triage per the session policy/);+ assert.doesNotMatch(r1.stdout, /Triage each finding/);+ const cache = readCache(cwd);+ assert.ok(!cache.sessions['sid-1'].footerShown, 'a downgraded footer does not spend the session flag');+ });++ it('commits the footer flag only for the complete full policy, not its opening words', () => {+ const cache = { version: 1, sessions: {} };+ const full = renderTemplate(+ [finding('tiny-text', 1, { name: 'Tiny text' })],+ '/x/a.css', DEFAULT_CONFIG, { cwd: '/x' },+ );++ // A tail truncation can spare "Triage each finding" while cutting the+ // policy body. That must not count as delivered.+ commitFooterShown(cache, 'sid-1', full.slice(0, full.length - 40));+ assert.ok(!cache.sessions['sid-1']?.footerShown, 'a truncated policy must not spend the flag');++ commitFooterShown(cache, 'sid-1', full);+ assert.ok(cache.sessions['sid-1'].footerShown, 'the intact policy commits the flag');+ });+});+describe('runHook() — clean-ack noise', () => {let cwd;beforeEach(() => {@@ -2998,7 +3198,9 @@ describe('Cursor hook scripts', () => {assert.equal(payload.permission, 'deny');assert.match(payload.user_message, /blocked this write/);assert.match(payload.user_message, /side-tab/);- assert.match(payload.agent_message, /Handle these before finalizing/);+ assert.match(payload.agent_message, /Triage each finding/);+ assert.match(payload.agent_message, /Full suppression ladder/, 'the deny message carries the complete policy, not a truncated head');+ assert.ok(payload.agent_message.length <= 4000, 'the deny message respects the Cursor cap');const entries = fs.readFileSync(logPath, 'utf-8').trim().split('\n').map((line) => JSON.parse(line));assert.equal(entries[0].event, 'preToolUse');@@ -3006,6 +3208,71 @@ describe('Cursor hook scripts', () => {assert.equal(entries[0].blockedFindings, 1);});+ it('preToolUse delivers the stale-sidecar note within a 500-char budget (PR #508)', () => {+ fs.mkdirSync(path.join(cwd, '.impeccable'), { recursive: true });+ fs.writeFileSync(getConfigPath(cwd), JSON.stringify({+ hook: { limits: { maxChars: 500 } },+ }));++ const designMd = path.join(cwd, 'DESIGN.md');+ const sidecarPath = path.join(cwd, '.impeccable', 'design.json');+ fs.writeFileSync(designMd, `---+typography:+ body:+ fontFamily: "IBM Plex Sans, Arial, sans-serif"+colors:+ ink: "#241f1a"+rounded:+ "2xl": "80px"+---++# Design System+`);+ fs.writeFileSync(sidecarPath, JSON.stringify({+ extensions: {+ colorMeta: {+ accent: {+ canonical: '#b8422e',+ tonalRamp: ['#d55a42'],+ },+ },+ roundedMeta: {+ lg: { canonical: '24px' },+ },+ },+ }));+ const past = new Date(Date.now() - 10000);+ fs.utimesSync(sidecarPath, past, past);++ const filePath = path.join(cwd, 'src/Card.html');+ const out = execFileSync(process.execPath, [path.join('skill', 'scripts', 'hook-before-edit.mjs')], {+ cwd: path.resolve('.'),+ input: JSON.stringify({+ hook_event_name: 'preToolUse',+ session_id: 'sid-508',+ cwd,+ tool_name: 'Write',+ tool_input: {+ file_path: filePath,+ content: `+ <style>+ .card { border-left: 4px solid #7c3aed; border-radius: 16px; }+ </style>+ <div class="card">Hello</div>+ `,+ },+ }),+ env: { ...process.env, IMPECCABLE_HOOK_LOG: '' },+ encoding: 'utf-8',+ });++ const payload = JSON.parse(out);+ assert.equal(payload.permission, 'deny');+ assert.match(payload.agent_message, /DESIGN\.md is newer/);+ assert.ok(payload.agent_message.length <= 500, `deny message length ${payload.agent_message.length} exceeds 500-char budget`);+ assert.equal(readCache(cwd).sessions['sid-508'].designNoteShown, true);+ });+it('preToolUse allows writes with findings when the project platform is native', () => {// Same slop content the deny test blocks, but the project declares a// native platform, so the web rule engine must stand aside.@@ -3546,6 +3813,26 @@ describe('runStopHook()', () => {assert.equal(stop.emission.kind, 'stop-deep-pass');});+ it('keeps a policy footer when the grouped Stop render is clamped to the minimum budget', async () => {+ const sid = 'stop-clamp';+ fs.mkdirSync(path.join(cwd, '.impeccable'), { recursive: true });+ fs.writeFileSync(getConfigPath(cwd), JSON.stringify({ hook: { limits: { maxChars: 500 } } }));+ const a = write('src/A.tsx', 'noop');+ const b = write('src/B.tsx', 'noop');+ const det = fakeDetector([finding('side-tab', 1, { name: 'X', description: 'y'.repeat(2000) })]);++ // Two touched files with deferred findings so the Stop pass groups them.+ await runHook({ stdinJson: JSON.stringify(editEvent(a, sid)), env: {}, cwd, detector: det });+ await runHook({ stdinJson: JSON.stringify(editEvent(b, sid)), env: {}, cwd, detector: det });++ const stop = await runStopHook({ stdinJson: JSON.stringify(stopEvent(sid)), env: {}, cwd, detector: det });+ assert.equal(stop.audit.emitted, true);+ const ctx = JSON.parse(stop.stdout).hookSpecificOutput.additionalContext;+ assert.ok(ctx.length <= 500, `grouped emission honors maxChars (got ${ctx.length})`);+ assert.match(ctx, /Triage per the session policy/, 'a clamped grouped emission still carries the policy');+ assert.match(ctx, /\[side-tab\]/, 'a clamped grouped emission keeps finding detail, not just a file header');+ });+it('exits silent and fast when the session touched no UI files', async () => {const r = await runStopHook({ stdinJson: JSON.stringify(stopEvent('stop-untouched')), env: {}, cwd });assert.equal(r.exitCode, 0);