@aria_asi/cli 0.2.39 → 0.2.41

package/dist/assets/hooks/lib/cognitive-block-parser.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * cognitive-block-parser.mjs — structural parser for assistant cognitive blocks.
+ *
+ * Phase 0 audit Cluster H finding M0.H.X12: hook code parses
+ * `<cognition>`, `<applied_cognition>`, `<verify>`, `<expected>` XML-shaped
+ * blocks using inline regex (3+ files, slightly different patterns each).
+ * Whitespace + nesting + tag-malformation is brittle on regex.
+ *
+ * This helper provides ONE structural extractor. Returns a typed result
+ * so callers can branch on `.cognition` / `.applied` / `.verify` /
+ * `.expected` directly + see `.malformed` per block to surface tag-shape
+ * issues to operators.
+ *
+ * Doctrine bind:
+ *   - clean_cognition (one parser, one concern)
+ *   - truth_over_deception (regex over XML lies about parse semantics
+ *     when tags nest or split across newlines unexpectedly)
+ *   - axiom_runtime_rule.admit_ignorance (malformed cases surface in
+ *     the result instead of silently returning undefined)
+ *
+ * Mirror: this file MUST be byte-identical between
+ *   ops/claude-hooks/lib/cognitive-block-parser.mjs
+ *   packages/aria-connector/hooks/lib/cognitive-block-parser.mjs
+ */
+
+// Conservative pattern: open tag → minimal-greedy content → close tag.
+// We DO NOT support nested same-name blocks (a <cognition> inside a
+// <cognition> is treated as malformed). The cognition contract emits
+// these blocks at the assistant-text top level; nesting is malformed.
+//
+// Whitespace tolerated around the opening / closing tags.
+function buildBlockPattern(tag) {
+  return new RegExp(`<\\s*${tag}\\s*>([\\s\\S]*?)<\\s*/\\s*${tag}\\s*>`, 'i');
+}
+
+const BLOCKS = Object.freeze({
+  cognition: buildBlockPattern('cognition'),
+  applied_cognition: buildBlockPattern('applied_cognition'),
+  verify: buildBlockPattern('verify'),
+  expected: buildBlockPattern('expected'),
+  reflection: buildBlockPattern('reflection'),
+});
+
+/**
+ * Extract typed cognitive blocks from assistant text.
+ *
+ * @param {string} text  raw assistant prose (or undefined/empty)
+ * @returns {{
+ *   cognition: string | null,
+ *   applied_cognition: string | null,
+ *   verify: string | null,
+ *   expected: string | null,
+ *   reflection: string | null,
+ *   malformed: { tags_unclosed: string[], tags_duplicated: string[] },
+ * }}
+ */
+export function parseCognitiveBlocks(text) {
+  const result = {
+    cognition: null,
+    applied_cognition: null,
+    verify: null,
+    expected: null,
+    reflection: null,
+    malformed: {
+      tags_unclosed: [],
+      tags_duplicated: [],
+    },
+  };
+  const src = String(text || '');
+  if (!src) return result;
+
+  for (const [tag, rx] of Object.entries(BLOCKS)) {
+    const match = src.match(rx);
+    if (match && typeof match[1] === 'string') {
+      result[tag] = match[1].trim() || null;
+    }
+    // Malformed-tag check: count opening tags vs closing tags. Mismatch
+    // = unclosed (or unopened) tag — surface for operator visibility.
+    const openRx = new RegExp(`<\\s*${tag}\\s*>`, 'gi');
+    const closeRx = new RegExp(`<\\s*/\\s*${tag}\\s*>`, 'gi');
+    const opens = (src.match(openRx) || []).length;
+    const closes = (src.match(closeRx) || []).length;
+    if (opens !== closes) {
+      result.malformed.tags_unclosed.push(tag);
+    } else if (opens > 1) {
+      // Same tag appearing twice = duplicate; we only extract the first.
+      result.malformed.tags_duplicated.push(tag);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Convenience: extract just the cognition block content (or null).
+ */
+export function extractCognition(text) {
+  return parseCognitiveBlocks(text).cognition;
+}
+
+/**
+ * Convenience: returns true iff at least one structural cognitive block
+ * is present and well-formed.
+ */
+export function hasAnyCognitiveBlock(text) {
+  const r = parseCognitiveBlocks(text);
+  return Boolean(r.cognition || r.applied_cognition || r.verify || r.expected || r.reflection);
+}
+
+export default { parseCognitiveBlocks, extractCognition, hasAnyCognitiveBlock };

package/dist/assets/hooks/lib/doctrine-trigger-map-loader.mjs

@@ -0,0 +1,137 @@
+// ── doctrine-self-check-file: M0.H.X6 (2026-05-06) ──
+// File-level acks for trip-vocab in operator-facing diagnostic strings:
+// doctrine-self-check-file: \b(?:skeleton|stub)\b loader-naming-the-pattern-it-validates-against
+// doctrine-self-check-file: kill.?switch|env.?(?:var|variable).?(?:override|disable|bypass)|process\.env\.[A-Z_]+\s*===\s*['"]off['"] loader-naming-trigger-content-not-using-the-pattern
+
+// silent-by-design: docstring below names the prior antipattern shape
+// (try-empty-catch); the loader itself surfaces all errors to stderr.
+/**
+ * doctrine_trigger_map.json loader (M0.H.X6).
+ *
+ * Closes the audit finding M0.H.6 / M0.H.X6:
+ *   - Triggers compiled per-call via `new RegExp(...)` — no precompile cache
+ *   - Malformed regex entries silently skipped (prior shape: try-empty-catch)
+ *   - No JSON Schema validation — bad entries shipped to runtime
+ *
+ * This loader:
+ *   1. Validates the file shape against doctrine_trigger_map.schema.json
+ *      (presence + types + regex compilability) at load time
+ *   2. Precompiles every regex once + caches by trigger string
+ *   3. Surfaces validation failures to stderr instead of silent skip
+ *   4. Returns an array of typed entries ready for fast scanning
+ *
+ * The validation is structural-shape (not full JSON Schema runtime)
+ * because we don't want to add an `ajv`-class dependency to the hooks.
+ * The schema lives alongside as documentation + future-proof contract.
+ *
+ * Mirror: this file MUST be byte-identical between
+ *   ops/claude-hooks/lib/doctrine-trigger-map-loader.mjs
+ *   packages/aria-connector/hooks/lib/doctrine-trigger-map-loader.mjs
+ */
+
+import { existsSync, readFileSync, statSync } from 'node:fs';
+
+let _cache = null;
+// Cache key: { mtimeMs, path } — re-validates if either changed.
+
+/**
+ * Load + validate + precompile the doctrine trigger map.
+ *
+ * @param {string} mapPath - absolute path to doctrine_trigger_map.json
+ * @returns {{ triggers: Array<{ trigger: string, regex: RegExp, memory: string, teaching: string, counter_action: string }>, errors: string[] }}
+ *
+ * Throws if the file is missing or unparseable. Validation errors per
+ * entry surface in the returned `errors` array (not throw) so a single
+ * bad entry doesn't break the whole map; operator sees the entry name
+ * + reason via stderr.
+ */
+export function loadDoctrineTriggerMap(mapPath) {
+  if (!existsSync(mapPath)) {
+    throw new Error(`doctrine-trigger-map-loader: file missing at ${mapPath}`);
+  }
+  const stat = statSync(mapPath);
+  if (_cache && _cache.mtimeMs === stat.mtimeMs && _cache.path === mapPath) {
+    return { triggers: _cache.triggers, errors: _cache.errors };
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(mapPath, 'utf8');
+  } catch (err) {
+    throw new Error(`doctrine-trigger-map-loader: read failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`doctrine-trigger-map-loader: JSON parse failed: ${err instanceof Error ? err.message : String(err)}`);
+  }
+
+  if (!data || typeof data !== 'object' || !Array.isArray(data.triggers)) {
+    throw new Error(`doctrine-trigger-map-loader: expected { triggers: [...] }, got ${typeof data}`);
+  }
+
+  const triggers = [];
+  const errors = [];
+  for (let i = 0; i < data.triggers.length; i++) {
+    const entry = data.triggers[i];
+    const where = `entry[${i}]${entry && entry.trigger ? ` trigger="${String(entry.trigger).slice(0, 60)}"` : ''}`;
+    if (!entry || typeof entry !== 'object') {
+      errors.push(`${where}: not an object`);
+      continue;
+    }
+    if (typeof entry.trigger !== 'string' || entry.trigger.length < 2) {
+      errors.push(`${where}: trigger field missing or too short`);
+      continue;
+    }
+    if (typeof entry.memory !== 'string' || !/\.md$/.test(entry.memory)) {
+      errors.push(`${where}: memory field must be a .md filename`);
+      continue;
+    }
+    if (typeof entry.teaching !== 'string' || entry.teaching.length < 8) {
+      errors.push(`${where}: teaching field missing or too short`);
+      continue;
+    }
+    if (typeof entry.counter_action !== 'string' || entry.counter_action.length < 8) {
+      errors.push(`${where}: counter_action field missing or too short`);
+      continue;
+    }
+    let regex;
+    try {
+      regex = new RegExp(entry.trigger, 'gi');
+    } catch (err) {
+      errors.push(`${where}: regex compile failed: ${err instanceof Error ? err.message : String(err)}`);
+      continue;
+    }
+    triggers.push({
+      trigger: entry.trigger,
+      regex,
+      memory: entry.memory,
+      teaching: entry.teaching,
+      counter_action: entry.counter_action,
+    });
+  }
+
+  // Surface errors loud (M0.H.X6 — was silent skip before).
+  for (const e of errors) {
+    process.stderr.write(`[doctrine-trigger-map-loader] ${e}\n`);
+  }
+
+  _cache = {
+    mtimeMs: stat.mtimeMs,
+    path: mapPath,
+    triggers,
+    errors,
+  };
+  return { triggers, errors };
+}
+
+/**
+ * Force a cache invalidation (for tests).
+ */
+export function _resetDoctrineTriggerMapCache() {
+  _cache = null;
+}
+
+export default { loadDoctrineTriggerMap, _resetDoctrineTriggerMapCache };

package/dist/assets/hooks/lib/domain-output-quality.mjs

@@ -1,5 +1,15 @@
 // Domain-aware output QA for Aria stop gates.
 // Deterministic local checks complement remote Mizan; they do not replace it.
+//
+// ARIA_ALLOW_STUB — reason: this file contains detector regexes whose source
+// literally enumerates the doctrine-banned tokens (TODO, placeholder, stub,
+// mock, fake, pending, …) so the gate matches its own pattern source. The
+// detectors are real shipped enforcement, not stub semantics. Reviewable.
+
+import {
+  buildUniversalConnectorGoalContract,
+  evaluateGoalContractOutput,
+} from './goal-contract-quality.mjs';
 
 const DOMAIN_RULES = [
   {
@@ -36,6 +46,19 @@ function hasAny(text, patterns) {
   return patterns.some((pattern) => pattern.test(text));
 }
 
+function hasAestheticClaim(text) {
+  const source = String(text || '');
+  if (/\b(?:beautiful|polished|sleek|aesthetic|elegant)\b/i.test(source)) return true;
+  return /\b(?:clean|modern|nice)\b/i.test(source) &&
+    /\b(?:ui|ux|visual|design|layout|brand|screen|page|typography|spacing|palette|composition)\b/i.test(source);
+}
+
+function hasUiDesignObligation(source, userText) {
+  const combined = `${String(userText || '')}\n${String(source || '')}`;
+  return /\b(?:build|design|implement|create|style|layout|frontend|component|screen|page|modal|form|button|accessibility|responsive|mobile|desktop|css|tailwind|react)\b/i.test(combined) &&
+    !/\b(?:ui surfaces respond|endpoint or ui surfaces|screenshots? of the exact flows|marketing proof|smoke run)\b/i.test(combined);
+}
+
 function lineHits(text, rx, label) {
   const hits = [];
   const lines = String(text || '').split('\n');
@@ -45,6 +68,49 @@ function lineHits(text, rx, label) {
   return hits;
 }
 
+function jsonLikeRatio(text) {
+  const source = String(text || '');
+  if (!source.trim()) return 0;
+  return (source.match(/[{}[\]":,]/g) || []).length / source.length;
+}
+
+function requestedRawEvidence(userText) {
+  return /\b(?:exact(?:ly)?|raw|verbatim|json|receipt block|lifecycle block|active lifecycle|paste the receipt|show the full receipt|print the block)\b/i.test(String(userText || ''));
+}
+
+function hasAriaContinuationSignal(text) {
+  return /\b(?:aria|harness|codex|claude|opencode|ledger|autofire|qa-as-gate|quality canary|receipt|active lifecycle|gate|canary|phase\s*\d+|next highest-impact|continue|next best|next step|fire\s+\d*\s*skills?|production ready|what'?s left|how far from production)\b/i.test(String(text || ''));
+}
+
+function hasEvidenceAnchor(text) {
+  return /\b(?:artifact|report|ledger|smoke|script|command|source|observed|verified|stdout|sha256|from\s+`|file:|path:)\b/i.test(String(text || ''));
+}
+
+function hasConsultAsQualitySource(text) {
+  const source = String(text || '');
+  return (
+    /\bneed to call the consult api\b/i.test(source) ||
+    /\bconsult the api\b/i.test(source) ||
+    /\buse the consult response as the quality source\b/i.test(source) ||
+    /\b(?:\/consult|deepseek|modelused)\b.{0,80}\b(?:quality source|core quality engine|required|dependency|find the answer)\b/i.test(source)
+  );
+}
+
+function hasDeployPublicationObligation(source, userText) {
+  const combined = `${String(userText || '')}\n${String(source || '')}`;
+  if (/\b(?:deploy|rollout|migration|kubectl|docker push)\b/i.test(combined)) return true;
+  if (/\b(?:ship|publish|promote|release)\b.{0,80}\b(?:production|live|customer|public|prod)\b/i.test(combined)) return true;
+  if (/\b(?:production|live|customer|public|prod)\b.{0,80}\b(?:ship|publish|promote|release)\b/i.test(combined)) return true;
+  if (/\b(?:release note|release notes|before any release|pre-release|post-release|release boundary|release decision|release validator)\b/i.test(combined)) return false;
+  return /\brelease\b/i.test(combined) && /\b(?:rollback|readiness|health check|deploy|rollout|production|public|publish|promote)\b/i.test(combined);
+}
+
+function hasUnsupportedContinuationInventoryClaim(text) {
+  const source = String(text || '');
+  if (hasEvidenceAnchor(source)) return false;
+  return /\b(?:all six|\d+\s*\/\s*\d+|\d+\s+pending|highest daily invocation volume|target surfaces?|component bundles?|live extraction feeds?)\b/i.test(source);
+}
+
 export function extractCodeBlocks(text) {
   return [...String(text || '').matchAll(/```[a-z0-9_-]*\n([\s\S]*?)```/gi)].map((m) => m[1] || '');
 }
@@ -52,10 +118,18 @@ export function extractCodeBlocks(text) {
 export function analyzeDomainOutputQuality(text, options = {}) {
   const source = String(text || '');
   const lower = source.toLowerCase();
+  const userText = String(options.userText || '');
   const codeBlocks = options.codeBlocks || extractCodeBlocks(source);
   const domains = DOMAIN_RULES.filter((rule) => rule.signal.test(source)).map((rule) => rule.domain);
   const blockers = [];
   const warnings = [];
+  const repairs = [];
+  const ariaContinuation = hasAriaContinuationSignal(source) || hasAriaContinuationSignal(userText);
+  if (ariaContinuation && !domains.includes('aria-continuation')) domains.push('aria-continuation');
+  const block = (message, repair = '') => {
+    blockers.push(message);
+    if (repair) repairs.push(repair);
+  };
 
   if (domains.includes('code')) {
     for (const hit of lineHits(source, /\b(?:TODO|FIXME|XXX|implementation pending|not implemented|coming soon|placeholder)\b/i, 'code placeholder semantics')) blockers.push(hit);
@@ -66,14 +140,14 @@ export function analyzeDomainOutputQuality(text, options = {}) {
     }
   }
 
-  if (domains.includes('ui')) {
+  if (domains.includes('ui') && hasUiDesignObligation(source, userText)) {
     if (!hasAny(source, [/\b(?:mobile|responsive|breakpoint|small screen|desktop)\b/i])) blockers.push('ui: UI/design output must address desktop and mobile responsiveness');
     if (!hasAny(source, [/\b(?:accessib|aria-|keyboard|focus|screen reader|semantic html|label)\b/i])) blockers.push('ui: UI/design output must address accessibility, focus, labels, or semantic structure');
     if (/\b(?:button|input|form|modal|menu|dialog)\b/i.test(source) && !/\b(?:focus|keyboard|aria-|label|escape|tab order)\b/i.test(source)) blockers.push('ui: interactive elements need keyboard/focus/accessibility behavior');
   }
 
   if (domains.includes('beauty')) {
-    if (/\b(?:clean|modern|beautiful|polished|nice|sleek)\b/i.test(source) && !hasAny(source, [/\b(?:spacing|typography|contrast|hierarchy|rhythm|composition|palette|motion|density|visual language)\b/i])) blockers.push('beauty: aesthetic claim lacks concrete visual language such as spacing, typography, contrast, hierarchy, palette, or composition');
+    if (hasAestheticClaim(source) && !hasAny(source, [/\b(?:spacing|typography|contrast|hierarchy|rhythm|composition|palette|motion|density|visual language)\b/i])) blockers.push('beauty: aesthetic claim lacks concrete visual language such as spacing, typography, contrast, hierarchy, palette, or composition');
   }
 
   if (domains.includes('security')) {
@@ -82,7 +156,7 @@ export function analyzeDomainOutputQuality(text, options = {}) {
   }
 
   if (domains.includes('ops')) {
-    if (/\b(?:deploy|rollout|release|migration|kubectl|docker push)\b/i.test(source) && !/\b(?:rollback|health|smoke|verify|readiness|observability|monitor)\b/i.test(source)) blockers.push('ops: deploy/release output must include rollback plus health/smoke/readiness verification');
+    if (hasDeployPublicationObligation(source, userText) && !/\b(?:rollback|health|smoke|verify|readiness|observability|monitor)\b/i.test(source)) blockers.push('ops: deploy/release output must include rollback plus health/smoke/readiness verification');
     if (/\b(?:env var|config|secret)\b/i.test(source) && !/\b(?:scope|owner|runtime|restart|reload|secret)\b/i.test(source)) warnings.push('ops: runtime config changes should name scope and reload/restart expectations');
   }
 
@@ -95,9 +169,64 @@ export function analyzeDomainOutputQuality(text, options = {}) {
     if (/\b(?:should work|probably|presumably|i assume)\b/i.test(source)) blockers.push('writing: uncertainty must be stated as an evidence boundary, not an assumption');
   }
 
+  if (ariaContinuation) {
+    const goalContract = buildUniversalConnectorGoalContract({
+      userText,
+      phase: 'domain-output-quality',
+    });
+    const goalQa = evaluateGoalContractOutput(source, { userText, goalContract });
+    warnings.push(...goalQa.warnings);
+    repairs.push(...goalQa.repairs);
+    if (goalQa.hardBlock) {
+      goalQa.blockers.forEach((issue) => block(issue));
+    }
+
+    const rawAllowed = requestedRawEvidence(userText);
+    const receiptHeavy =
+      /\[ARIA PLAYGROUND ACTIVE LIFECYCLE RUN\]/i.test(source) &&
+      (source.split('\n').length > 30 || jsonLikeRatio(source) > 0.08);
+    if (receiptHeavy && !rawAllowed) {
+      block(
+        'aria-continuation: owner-visible answer is receipt-heavy; summarize status, evidence, QA finding/correction, and next action, then move receipts to artifact/debug evidence',
+        'Rewrite as: status line, 2-4 evidence bullets, QA finding/correction/verification, and the next highest-impact step; link or name the receipt artifact instead of pasting raw lifecycle JSON.',
+      );
+    }
+    if (/\bwhat would you like me to do next\b|\bhow would you like me to proceed\b/i.test(source)) {
+      block(
+        'aria-continuation: continuation output must name the next highest-impact step instead of making the owner choose the obvious next action',
+        'Rewrite by naming and executing the current next highest-impact step from the controlling ledger, then state the evidence needed to advance.',
+      );
+    }
+    if (/\b(?:add|create|turn on|tighten)\s+(?:stricter\s+)?(?:more\s+)?(?:stop\s+)?gates\b/i.test(source) && !/\bQA-as-gate|forced QA|repair-first|quality canary\b/i.test(source)) {
+      block(
+        'aria-continuation: gate-chasing default detected; use QA-as-gate and repair-first behavior unless this is a high-risk boundary',
+        'Rewrite by replacing the proposed gate with expected-vs-observed QA, correction, verification, learning, and a hard-stop boundary only for secret/destructive/deploy/publication/owner-contradicted/false-completion risk.',
+      );
+    }
+    if (hasConsultAsQualitySource(source)) {
+      block(
+        'aria-continuation: consult API dependency detected; /consult cannot be the core quality engine',
+        'Rewrite using local cognitive skills plus deterministic QA as the quality path. Treat Codex/Claude execution as optional evidence and Aria runtime as the sidecar/control plane, not /consult as the decision source.',
+      );
+    }
+    if (hasUnsupportedContinuationInventoryClaim(source)) {
+      block(
+        'aria-continuation: unsupported numeric or inventory claim detected; continuation evidence must cite a real artifact, command, ledger, source, or observed output',
+        'Rewrite by either removing the number/inventory claim or binding it to a concrete artifact, command output, ledger row, source file, observed runtime result, or report hash.',
+      );
+    }
+    if (/\b(?:production ready|ready for production|promotion pass|complete|verified|done)\b/i.test(source) && !/\b(?:actual goal|next highest-impact|qa(?:-as-gate)?|correction|verification|learning|evidence)\b/i.test(source)) {
+      block(
+        'aria-continuation: readiness/completion claim must bind to actual goal, QA-as-gate, correction, verification, learning, and evidence',
+        'Rewrite by bounding the claim as verified, blocked, or pending; include the actual goal, QA result, correction status, verification command/artifact, and next action.',
+      );
+    }
+  }
+
   return {
     domains: [...new Set(domains)],
     blockers: [...new Set(blockers)],
     warnings: [...new Set(warnings)],
+    repairs: [...new Set(repairs)],
   };
 }

package/dist/assets/hooks/lib/empty-catch-scanner.mjs

@@ -0,0 +1,91 @@
+// ── doctrine-self-check-file: M0.SELFREVIEW.15 (2026-05-06) ──
+// Scanner for empty-catch reintroduction. Closes the regression surface
+// where M0.H.X3 surfaced 86+ empty swallows but provided no CI guard
+// against future reintroduction.
+//
+// Doctrine bind:
+//   - feedback_no_graceful_degradation.md — silent swallows are graceful
+//     degradation. The hook stack's empty catches were the doctrine
+//     enforcer literally violating the doctrine 86 times. This scanner
+//     prevents that pattern reintroducing through future commits.
+
+/**
+ * Empty-catch detection.
+ *
+ * Patterns flagged:
+ *   - `} catch {}`                 // bare empty
+ *   - `} catch (e) {}`             // identifier with empty body
+ *   - `} catch (_) {}`             // underscore variant
+ *   - `} catch {\n}`               // multi-line empty (whitespace-only body)
+ *   - `} catch (e) {\n}`           // same with identifier
+ *
+ * Acknowledgment forms (escape hatch for documented silent-by-design):
+ *   1. Inline (within ±2 lines): // silent-by-design: <reason>
+ *   2. File-level: // empty-catch-allowed-file: <reason>
+ *
+ * Without an ack, an empty catch is a regression.
+ */
+
+const EMPTY_CATCH_PATTERNS = [
+  // Single-line empty catch
+  /\}\s*catch\s*(?:\([^)]*\))?\s*\{\s*\}/g,
+];
+
+const INLINE_ACK_RX = /\/\/\s*silent-by-design\s*:\s*(.+)/i;
+const FILE_ACK_RX = /\/\/\s*empty-catch-allowed-file\s*:\s*(.+)/i;
+
+/**
+ * Scan source text for empty catches.
+ *
+ * @param {string} source - file content
+ * @param {object} [opts]
+ * @param {string[]} [opts.addedLineNumbers] - 1-indexed line numbers that
+ *   count as "added" (so we only flag NEW empty catches in a diff context).
+ *   If absent, scan whole file.
+ * @returns {Array<{line_number, line_text, has_inline_acknowledgment, file_ack_present}>}
+ */
+export function scanForEmptyCatches(source, opts = {}) {
+  const lines = source.split('\n');
+  const fileAckPresent = lines.slice(0, 30).some((l) => FILE_ACK_RX.test(l));
+  const addedLineSet = opts.addedLineNumbers ? new Set(opts.addedLineNumbers) : null;
+
+  const violations = [];
+  for (const pattern of EMPTY_CATCH_PATTERNS) {
+    pattern.lastIndex = 0;
+    for (const m of source.matchAll(pattern)) {
+      const offset = m.index ?? 0;
+      const lineNumber = source.slice(0, offset).split('\n').length;
+      // If we have an addedLines filter, skip non-added matches
+      if (addedLineSet && !addedLineSet.has(lineNumber)) continue;
+      const lineText = lines[lineNumber - 1] ?? '';
+      // Inline ack: ±2 lines
+      const ackWindow = lines.slice(Math.max(0, lineNumber - 3), lineNumber + 2);
+      const hasInlineAck = ackWindow.some((l) => INLINE_ACK_RX.test(l));
+      violations.push({
+        match: m[0],
+        line_number: lineNumber,
+        line_text: lineText,
+        has_inline_acknowledgment: hasInlineAck,
+        file_ack_present: fileAckPresent,
+      });
+    }
+  }
+  // Filter out acknowledged ones
+  return violations.filter((v) => !v.has_inline_acknowledgment && !v.file_ack_present);
+}
+
+/**
+ * Format violations for human review.
+ */
+export function formatEmptyCatchViolations(violations, filePath) {
+  if (violations.length === 0) return '';
+  const lines = [`\n${filePath}:`];
+  for (const v of violations) {
+    lines.push(`  Line ${v.line_number}: ${v.line_text.trim()}`);
+    lines.push(`    Empty-catch detected. Doctrine: feedback_no_graceful_degradation.md`);
+    lines.push(`    Fix: surface to stderr OR add ack:`);
+    lines.push(`      // silent-by-design: <reason this swallow is truly safe>`);
+    lines.push('');
+  }
+  return lines.join('\n');
+}