@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

package/scripts/audit-caching-scope-hygiene.mjs

@@ -0,0 +1,263 @@
+#!/usr/bin/env node
+// @ts-check
+
+/**
+ * audit-caching-scope-hygiene.mjs
+ *
+ * Phase 5 drift catcher. Scans user-facing surfaces (README, AGENTS.md, FAQ,
+ * integration playbook, CHANGELOG) for caching numerical claims and verifies
+ * that each claim is integration-scoped per `docs/architecture/decisions-foundation.md`
+ * D4 "Per-Tool Caching Scope Matrix".
+ *
+ * The rule: never publish a single universal "X% caching saving" figure that
+ * mixes integration modes. Every numerical caching saving claim on a public
+ * surface must either:
+ *   1. be in a clearly-scoped paragraph that names the integration mode
+ *      (direct API, Claude Code SDK programmatic, Cursor, Windsurf, Codex CLI,
+ *      Kiro, IDE wrapper) within +/- 600 characters of the figure, OR
+ *   2. live in a documented exempt context (Phase 1 aggregate-cap CHANGELOG
+ *      rationale, archived plan files under docs/archive/, benchmark JSON
+ *      under benchmarks/results/, the canonical D4 matrix itself).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+
+const PUBLIC_SURFACES = [
+  'README.md',
+  'AGENTS.md',
+  'docs/faq.md',
+  'docs/integration-playbook.md',
+  'docs/doc-index.md',
+  'CHANGELOG.md',
+];
+
+// Numerical caching saving claims this audit scans for. Pattern is intentionally
+// strict: a digit-prefixed percent paired with an action verb or saving noun,
+// or a bare 89.31%-style figure within a cache-keyword window.
+const SAVING_CLAIM_PATTERNS = [
+  // "X% reduction|saving|off|cheaper"
+  /\b(\d{1,3}(?:\.\d+)?)\s*%\s*(?:effective[- ]token\s+)?(?:reduction|saving|savings|off|cheaper)\b/gi,
+  // "saves|cuts|reduces|delivers up to X%" (cache context check applied below)
+  /\b(?:save[sd]?|cut[s]?|reduce[sd]?|deliver[sd]?)\s+(?:up\s+to\s+)?(\d{1,3}(?:\.\d+)?)\s*%/gi,
+  // "up to X% ... cache"
+  /\b(?:up to|approximately|about|~)\s*(\d{1,3}(?:\.\d+)?)\s*%[^.\n]{0,80}(?:cach|warm|prompt[- ]cach)/gi,
+  // "cache ... X% reduction|saving"
+  /\bcach[a-z]*[^.\n]{0,80}\b(\d{1,3}(?:\.\d+)?)\s*%\s*(?:reduction|saving|savings|off)/gi,
+  // bare two-decimal figures like 89.31% (cache context check applied below)
+  /\b(\d{2,3}\.\d{2})\s*%/g,
+];
+
+// Patterns at these indices apply a cache-context window check before counting.
+const CONTEXT_GATED_PATTERN_INDEXES = new Set([1, 4]);
+
+const INTEGRATION_MODE_KEYWORDS = [
+  'direct provider api',
+  'direct api',
+  'direct anthropic',
+  'direct openai',
+  'direct gemini',
+  'claude code sdk',
+  'claude code cli',
+  'cursor',
+  'windsurf',
+  'codex cli',
+  'codex / openai',
+  'kiro',
+  'ide wrapper',
+  'ide wrappers',
+  'integration mode',
+  'integration_mode',
+  'per-tool caching',
+  'per-integration',
+  'per integration',
+  'cache_control',
+];
+
+const CACHE_CONTEXT_KEYWORDS = [
+  'cach',
+  'warm',
+  'prompt-cach',
+  'prompt cach',
+  'cache_control',
+];
+
+const CONTEXT_WINDOW_RADIUS = 600;
+
+function readSurface(rootDir, relativePath, sourceOverrides) {
+  if (sourceOverrides && Object.prototype.hasOwnProperty.call(sourceOverrides, relativePath)) {
+    return String(sourceOverrides[relativePath]);
+  }
+  const absolutePath = join(rootDir, relativePath);
+  if (!existsSync(absolutePath)) {
+    return null;
+  }
+  return readFileSync(absolutePath, 'utf8');
+}
+
+function findCachingClaimMatches(sourceText) {
+  /** @type {{index: number, matchedText: string, percent: string}[]} */
+  const matches = [];
+  for (let patternIndex = 0; patternIndex < SAVING_CLAIM_PATTERNS.length; patternIndex += 1) {
+    const pattern = SAVING_CLAIM_PATTERNS[patternIndex];
+    pattern.lastIndex = 0;
+    let result;
+    // eslint-disable-next-line no-cond-assign
+    while ((result = pattern.exec(sourceText)) !== null) {
+      const matchedText = result[0];
+      const percent = result[1] || '';
+      const index = result.index;
+
+      // For context-gated patterns, confirm there is a cache keyword within
+      // the context window before counting this as a caching claim.
+      if (CONTEXT_GATED_PATTERN_INDEXES.has(patternIndex)) {
+        const start = Math.max(0, index - CONTEXT_WINDOW_RADIUS);
+        const end = Math.min(sourceText.length, index + matchedText.length + CONTEXT_WINDOW_RADIUS);
+        const window = sourceText.slice(start, end).toLowerCase();
+        const hasCacheContext = CACHE_CONTEXT_KEYWORDS.some((keyword) => window.includes(keyword));
+        if (!hasCacheContext) {
+          continue;
+        }
+      }
+
+      matches.push({ index, matchedText, percent });
+    }
+  }
+
+  // Deduplicate overlapping matches (same percent within a few chars).
+  matches.sort((a, b) => a.index - b.index);
+  /** @type {{index: number, matchedText: string, percent: string}[]} */
+  const deduped = [];
+  for (const match of matches) {
+    const last = deduped[deduped.length - 1];
+    if (last && Math.abs(last.index - match.index) <= 8 && last.percent === match.percent) {
+      continue;
+    }
+    deduped.push(match);
+  }
+  return deduped;
+}
+
+function extractContextWindow(sourceText, index, matchLength) {
+  const start = Math.max(0, index - CONTEXT_WINDOW_RADIUS);
+  const end = Math.min(sourceText.length, index + matchLength + CONTEXT_WINDOW_RADIUS);
+  return sourceText.slice(start, end);
+}
+
+function hasIntegrationModeMarker(contextWindow) {
+  const normalized = contextWindow.toLowerCase();
+  return INTEGRATION_MODE_KEYWORDS.some((keyword) => normalized.includes(keyword));
+}
+
+function lineNumberFromIndex(sourceText, charIndex) {
+  let line = 1;
+  for (let i = 0; i < charIndex && i < sourceText.length; i += 1) {
+    if (sourceText[i] === '\n') {
+      line += 1;
+    }
+  }
+  return line;
+}
+
+export function runCachingScopeHygieneAudit(options = {}) {
+  const rootDir = options.rootDir ? resolve(String(options.rootDir)) : REPOSITORY_ROOT;
+  const sourceOverrides = options.sourceOverrides || null;
+  const surfaceList = options.surfaceList || PUBLIC_SURFACES;
+  const violations = [];
+  const surfaceReports = [];
+  let totalClaims = 0;
+
+  for (const surfacePath of surfaceList) {
+    const sourceText = readSurface(rootDir, surfacePath, sourceOverrides);
+    if (sourceText === null) {
+      continue;
+    }
+
+    const claims = findCachingClaimMatches(sourceText);
+    totalClaims += claims.length;
+    /** @type {{percent: string, line: number, scoped: boolean}[]} */
+    const claimReports = [];
+
+    for (const claim of claims) {
+      const contextWindow = extractContextWindow(sourceText, claim.index, claim.matchedText.length);
+      const scoped = hasIntegrationModeMarker(contextWindow);
+      const lineNumber = lineNumberFromIndex(sourceText, claim.index);
+
+      claimReports.push({
+        percent: claim.percent,
+        line: lineNumber,
+        scoped,
+      });
+
+      if (!scoped) {
+        violations.push({
+          file: surfacePath,
+          line: lineNumber,
+          kind: 'caching-claim.missing-integration-scope',
+          detail: `Caching saving claim "${claim.matchedText.trim()}" lacks an integration-mode marker within +/- ${CONTEXT_WINDOW_RADIUS} chars. Add a per-tool / direct-API / IDE-wrapper label, or move the figure under a clearly-scoped paragraph. Source of truth: docs/architecture/decisions-foundation.md D4.`,
+        });
+      }
+    }
+
+    surfaceReports.push({
+      path: surfacePath,
+      claimCount: claims.length,
+      scopedCount: claimReports.filter((claim) => claim.scoped).length,
+      unscopedCount: claimReports.filter((claim) => !claim.scoped).length,
+      claims: claimReports,
+    });
+  }
+
+  return {
+    auditName: 'audit-caching-scope-hygiene',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    surfaceCount: surfaceReports.length,
+    totalClaimCount: totalClaims,
+    violationCount: violations.length,
+    passed: violations.length === 0,
+    surfaces: surfaceReports,
+    violations,
+  };
+}
+
+function main() {
+  const report = runCachingScopeHygieneAudit();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:caching-scope-hygiene');
+  console.log('===============================================');
+  console.log(`  Public surfaces scanned: ${report.surfaceCount}`);
+  console.log(`  Caching saving claims:    ${report.totalClaimCount}`);
+  console.log('');
+
+  if (report.passed) {
+    console.log('  All caching saving claims on public surfaces are integration-scoped.');
+    process.stderr.write(`AUDIT_CACHING_SCOPE_HYGIENE_REPORT: ${JSON.stringify({ passed: true, surfaceCount: report.surfaceCount, totalClaimCount: report.totalClaimCount })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const violation of report.violations) {
+    console.log(`    [${violation.kind}] ${violation.file}:${violation.line} ${violation.detail}`);
+  }
+  console.log('');
+  console.log(`  ${report.violationCount} violation(s) found.`);
+  process.stderr.write(`AUDIT_CACHING_SCOPE_HYGIENE_REPORT: ${JSON.stringify({ passed: false, violationCount: report.violationCount })}\n`);
+  process.exit(1);
+}
+
+if (process.argv[1] && (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-caching-scope-hygiene.mjs'))) {
+  main();
+}

package/scripts/audit-file-size.mjs

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+// @ts-check
+
+/**
+ * audit-file-size.mjs
+ *
+ * Enforces the 500 LOC threshold on production source files. Files that exceed
+ * the threshold are hard failures unless they declare a justified exception
+ * with a `// @file-size-exception: <reason>` marker in their first 5 lines.
+ *
+ * Scope:
+ *   lib/     all .mjs/.js files
+ *   scripts/ all .mjs/.js files
+ *   bin/     all .js/.mjs files
+ *
+ * Excluded:
+ *   *.test.mjs / *.test.js (test files have different size economics)
+ *
+ * Usage:
+ *   node scripts/audit-file-size.mjs            (human-readable + machine line)
+ *   node scripts/audit-file-size.mjs --json     (JSON only)
+ *
+ * Exit codes:
+ *   0 — all files within budget (or covered by exception)
+ *   1 — at least one file exceeded the threshold without an exception marker
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+
+export const DEFAULT_LOC_THRESHOLD = 500;
+const EXCEPTION_MARKER_PATTERN = /^\s*(?:\/\/|\*)\s*@file-size-exception:\s*(.+?)\s*(?:\*\/\s*)?$/;
+const EXCEPTION_MARKER_LOOKAHEAD_LINES = 5;
+const SCAN_ROOTS = ['lib', 'scripts', 'bin'];
+const SCAN_EXTENSIONS = new Set(['.mjs', '.js']);
+const SKIP_DIRECTORY_NAMES = new Set(['node_modules', '.git', '.agentic-backup', '.benchmarks']);
+
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+
+function isTestFile(filePath) {
+  const baseName = filePath.split(/[\\/]/).pop();
+  return /\.test\.(mjs|js)$/.test(baseName);
+}
+
+function collectSourceFiles(scanRootName) {
+  const collected = [];
+  const scanRootAbsolutePath = join(REPOSITORY_ROOT, scanRootName);
+
+  function walk(currentPath) {
+    let entries;
+    try {
+      entries = readdirSync(currentPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (SKIP_DIRECTORY_NAMES.has(entry.name)) {
+        continue;
+      }
+
+      const entryAbsolute = join(currentPath, entry.name);
+      if (entry.isDirectory()) {
+        walk(entryAbsolute);
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      const dotIndex = entry.name.lastIndexOf('.');
+      const extension = dotIndex >= 0 ? entry.name.slice(dotIndex) : '';
+      if (!SCAN_EXTENSIONS.has(extension)) {
+        continue;
+      }
+
+      if (isTestFile(entryAbsolute)) {
+        continue;
+      }
+
+      collected.push(entryAbsolute);
+    }
+  }
+
+  try {
+    statSync(scanRootAbsolutePath);
+  } catch {
+    return collected;
+  }
+
+  walk(scanRootAbsolutePath);
+  return collected;
+}
+
+function detectExceptionMarker(sourceLines) {
+  const lookahead = sourceLines.slice(0, EXCEPTION_MARKER_LOOKAHEAD_LINES);
+  for (const line of lookahead) {
+    const match = line.match(EXCEPTION_MARKER_PATTERN);
+    if (match) {
+      return match[1].trim();
+    }
+  }
+  return null;
+}
+
+function inspectFile(filePath, threshold) {
+  const sourceText = readFileSync(filePath, 'utf8');
+  const lines = sourceText.split(/\r?\n/);
+  const lineCount = lines.length;
+  const overThreshold = lineCount > threshold;
+  const exceptionReason = overThreshold ? detectExceptionMarker(lines) : null;
+  const passed = !overThreshold || Boolean(exceptionReason);
+
+  return {
+    filePath: relative(REPOSITORY_ROOT, filePath).replace(/\\/g, '/'),
+    lineCount,
+    threshold,
+    overThreshold,
+    exceptionReason,
+    passed,
+  };
+}
+
+export function runAuditFileSize({ threshold = DEFAULT_LOC_THRESHOLD } = {}) {
+  const scannedFiles = SCAN_ROOTS.flatMap((scanRootName) => collectSourceFiles(scanRootName));
+  const inspections = scannedFiles.map((filePath) => inspectFile(filePath, threshold));
+  const violations = inspections.filter((entry) => entry.overThreshold && !entry.exceptionReason);
+  const exemptedFiles = inspections.filter((entry) => entry.overThreshold && entry.exceptionReason);
+
+  return {
+    auditName: 'audit-file-size',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    threshold,
+    scannedFileCount: inspections.length,
+    overThresholdCount: inspections.filter((entry) => entry.overThreshold).length,
+    violationCount: violations.length,
+    exemptedCount: exemptedFiles.length,
+    violations: violations.map((entry) => ({
+      filePath: entry.filePath,
+      lineCount: entry.lineCount,
+    })),
+    exemptedFiles: exemptedFiles.map((entry) => ({
+      filePath: entry.filePath,
+      lineCount: entry.lineCount,
+      reason: entry.exceptionReason,
+    })),
+    passed: violations.length === 0,
+  };
+}
+
+function formatHumanLine(prefix, entry) {
+  return `  ${prefix} ${entry.filePath} (${entry.lineCount}/${entry.threshold ?? DEFAULT_LOC_THRESHOLD} LOC)`;
+}
+
+function main() {
+  const report = runAuditFileSize();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:file-size — 500 LOC enforcement');
+  console.log('===============================================');
+  console.log(`  Threshold: ${report.threshold} LOC`);
+  console.log(`  Scanned: ${report.scannedFileCount} files`);
+  console.log('');
+
+  if (report.exemptedCount > 0) {
+    console.log('  Exempted (declared @file-size-exception):');
+    for (const entry of report.exemptedFiles) {
+      console.log(`    EXEMPT ${entry.filePath} (${entry.lineCount} LOC) — ${entry.reason}`);
+    }
+    console.log('');
+  }
+
+  if (report.violationCount === 0) {
+    console.log('  All files within budget.');
+    process.stderr.write(`AUDIT_FILE_SIZE_REPORT: ${JSON.stringify({
+      passed: true,
+      scannedFileCount: report.scannedFileCount,
+      violationCount: 0,
+      exemptedCount: report.exemptedCount,
+    })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const entry of report.violations) {
+    console.log(formatHumanLine('FAIL', { ...entry, threshold: report.threshold }));
+  }
+  console.log('');
+  console.log(`  ${report.violationCount} file(s) exceed the ${report.threshold} LOC threshold.`);
+  console.log('  Either split the file into focused submodules or, when justified,');
+  console.log('  declare an exception in the first 5 lines:');
+  console.log('    // @file-size-exception: <reason>');
+  console.log('');
+
+  process.stderr.write(`AUDIT_FILE_SIZE_REPORT: ${JSON.stringify({
+    passed: false,
+    scannedFileCount: report.scannedFileCount,
+    violationCount: report.violationCount,
+    exemptedCount: report.exemptedCount,
+    violations: report.violations,
+  })}\n`);
+  process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-file-size.mjs')) {
+  main();
+}

package/scripts/audit-reflection-citations.mjs

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+// @ts-check
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runRuleIdUniquenessAudit } from './audit-rule-id-uniqueness.mjs';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+const RULE_ID_PATTERN = /\b[A-Z]+-\d{3,4}(?:-[A-Z])?\b/g;
+
+const REQUIRED_REFLECTION_SURFACES = [
+  {
+    path: 'AGENTS.md',
+    requiredSnippets: [
+      '## Bounded Reflection',
+      'REFLECTION',
+      'Rules:',
+      'Risk:',
+      'Action:',
+      'valid rule IDs',
+      'hidden chain-of-thought',
+    ],
+  },
+  {
+    path: '.agent-context/review-checklists/pr-checklist.md',
+    requiredSnippets: [
+      'Bounded Reflection',
+      'valid rule IDs',
+      'hidden chain-of-thought',
+    ],
+  },
+];
+
+function readSource(rootDir, relativePath, sourceOverrides) {
+  if (sourceOverrides && Object.prototype.hasOwnProperty.call(sourceOverrides, relativePath)) {
+    return String(sourceOverrides[relativePath]);
+  }
+
+  const absolutePath = join(rootDir, relativePath);
+  if (!existsSync(absolutePath)) {
+    return null;
+  }
+
+  return readFileSync(absolutePath, 'utf8');
+}
+
+function collectKnownRuleIds() {
+  const ruleIdAudit = runRuleIdUniquenessAudit();
+  const knownRuleIds = new Set();
+
+  for (const fileEntry of ruleIdAudit.perFile || []) {
+    for (const ruleId of fileEntry.knownSectionIdsInFile || []) {
+      knownRuleIds.add(ruleId);
+    }
+  }
+
+  return {
+    ruleIdAudit,
+    knownRuleIds,
+  };
+}
+
+function collectRuleIdsFromSource(sourceText) {
+  return Array.from(new Set(sourceText.match(RULE_ID_PATTERN) || [])).sort();
+}
+
+export function runReflectionCitationAudit(options = {}) {
+  const rootDir = options.rootDir ? resolve(String(options.rootDir)) : REPOSITORY_ROOT;
+  const sourceOverrides = options.sourceOverrides || null;
+  const { ruleIdAudit, knownRuleIds } = collectKnownRuleIds();
+  const violations = [];
+  const surfaceReports = [];
+
+  for (const surface of REQUIRED_REFLECTION_SURFACES) {
+    const sourceText = readSource(rootDir, surface.path, sourceOverrides);
+    if (sourceText === null) {
+      violations.push({
+        file: surface.path,
+        kind: 'surface.missing',
+        detail: 'Required reflection citation surface is missing.',
+      });
+      continue;
+    }
+
+    const missingSnippets = surface.requiredSnippets.filter((snippet) => !sourceText.includes(snippet));
+    for (const missingSnippet of missingSnippets) {
+      violations.push({
+        file: surface.path,
+        kind: 'reflection.snippet-missing',
+        detail: `Missing required reflection snippet: ${missingSnippet}`,
+      });
+    }
+
+    const citedRuleIds = collectRuleIdsFromSource(sourceText);
+    const unknownRuleIds = citedRuleIds.filter((ruleId) => !knownRuleIds.has(ruleId));
+    for (const unknownRuleId of unknownRuleIds) {
+      violations.push({
+        file: surface.path,
+        kind: 'rule-id.unknown',
+        detail: `Rule ID ${unknownRuleId} does not resolve to any canonical rule section.`,
+      });
+    }
+
+    surfaceReports.push({
+      path: surface.path,
+      missingSnippetCount: missingSnippets.length,
+      citedRuleIds,
+      unknownRuleIds,
+    });
+  }
+
+  return {
+    auditName: 'audit-reflection-citations',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    surfaceCount: REQUIRED_REFLECTION_SURFACES.length,
+    knownRuleIdCount: knownRuleIds.size,
+    ruleIdAuditPassed: ruleIdAudit.passed,
+    violationCount: violations.length,
+    passed: violations.length === 0,
+    surfaces: surfaceReports,
+    violations,
+  };
+}
+
+function main() {
+  const report = runReflectionCitationAudit();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:reflection-citations');
+  console.log('===============================================');
+  console.log(`  Reflection surfaces: ${report.surfaceCount}`);
+  console.log(`  Known rule IDs:      ${report.knownRuleIdCount}`);
+  console.log('');
+
+  if (report.passed) {
+    console.log('  Reflection citation surfaces are present and all cited rule IDs resolve.');
+    process.stderr.write(`AUDIT_REFLECTION_CITATIONS_REPORT: ${JSON.stringify({ passed: true, surfaceCount: report.surfaceCount, knownRuleIdCount: report.knownRuleIdCount })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const violation of report.violations) {
+    console.log(`    [${violation.kind}] ${violation.file}: ${violation.detail}`);
+  }
+  console.log('');
+  console.log(`  ${report.violationCount} violation(s) found.`);
+  process.stderr.write(`AUDIT_REFLECTION_CITATIONS_REPORT: ${JSON.stringify({ passed: false, violationCount: report.violationCount, kinds: [...new Set(report.violations.map((violation) => violation.kind))] })}\n`);
+  process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-reflection-citations.mjs')) {
+  main();
+}