@ryuenn3123/agentic-senior-core 3.0.49 → 4.0.0

package/mcp.json

@@ -1,25 +1,36 @@
 {
   "version": "1.1",
   "name": "agentic-senior-core",
-  "description": "MCP configuration for governance-aware diagnostics, scoped rule loading, and self-healing workflows with dynamic knowledge injection.",
+  "description": "MCP configuration for governance-aware diagnostics and scoped rule loading. Five knowledge layers ship as concrete file-backed surfaces today; four additional layers are declared as planned dynamic surfaces. See docs/architecture-vision.md for the roadmap.",
   "knowledgeLayers": {
     "enabled": true,
-    "description": "9-layer dynamic knowledge injection for AI agents",
+    "description": "Knowledge layer registry. 5 layers are file-backed and active today (rules, prompts, state, policies, project-context). 4 layers are reserved as planned dynamic surfaces (stack-strategies, architecture-playbooks, execution-contracts, governance-modes) and resolve to no-op until implemented in a later phase.",
+    "implementedLayerCount": 5,
+    "plannedLayerCount": 4,
+    "totalDeclaredLayers": 9,
+    "roadmapReference": "docs/architecture-vision.md",
     "layers": {
       "rules": {
         "path": ".agent-context/rules",
         "count": 15,
-        "autoLoad": true
+        "autoLoad": true,
+        "status": "implemented"
       },
       "stack-strategies": {
         "path": "dynamic",
         "autoLoad": true,
-        "type": "virtual"
+        "type": "virtual",
+        "status": "planned",
+        "plannedPhase": "phase-2-or-later",
+        "rationale": "Reserved for runtime-decision-signal cache derived from detected project stack."
       },
       "architecture-playbooks": {
         "path": "dynamic",
         "autoLoad": true,
-        "type": "virtual"
+        "type": "virtual",
+        "status": "planned",
+        "plannedPhase": "phase-2-or-later",
+        "rationale": "Reserved for structural-planning playbooks derived from repo evidence."
       },
       "execution-contracts": {
         "path": "dynamic",
@@ -29,12 +40,16 @@
           "review-checklists",
           "policies"
         ],
-        "type": "virtual"
+        "type": "virtual",
+        "status": "planned",
+        "plannedPhase": "phase-3-anti-halu",
+        "rationale": "Reserved for active-contract resolution. Today the agent reads prompts, review-checklists, and policies directly from their file-backed layers; the dedicated execution-contract resolver is planned for the validation MCP tools in Phase 3."
       },
       "prompts": {
         "path": ".agent-context/prompts",
         "count": 4,
         "autoLoad": true,
+        "status": "implemented",
         "templates": [
           "init-project",
           "bootstrap-design",
@@ -50,22 +65,28 @@
           "regulated",
           "startup"
         ],
-        "type": "virtual"
+        "type": "virtual",
+        "status": "planned",
+        "plannedPhase": "phase-2-or-later",
+        "rationale": "Reserved for governance-mode selection metadata. Profile selection lives in policy files today and the mode-resolver is planned."
       },
       "state": {
         "path": ".agent-context/state",
         "count": 22,
-        "autoLoad": true
+        "autoLoad": true,
+        "status": "implemented"
       },
       "policies": {
         "path": ".agent-context/policies",
         "count": 1,
-        "autoLoad": true
+        "autoLoad": true,
+        "status": "implemented"
       },
       "project-context": {
         "path": "docs",
         "count": 0,
         "autoLoad": false,
+        "status": "implemented",
         "sources": [
           "project-brief",
           "architecture-decision-record",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.49",
+  "version": "4.0.0",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -56,7 +56,14 @@
     "audit:rules-guardian": "node ./scripts/rules-guardian-audit.mjs",
     "audit:explain-on-demand": "node ./scripts/explain-on-demand-audit.mjs",
     "audit:single-source-lazy-loading": "node ./scripts/single-source-lazy-loading-audit.mjs",
+    "audit:cache-layer-contract": "node ./scripts/audit-cache-layer-contract.mjs",
+    "audit:reflection-citations": "node ./scripts/audit-reflection-citations.mjs",
+    "audit:caching-scope-hygiene": "node ./scripts/audit-caching-scope-hygiene.mjs",
+    "audit:release-bundle": "node ./scripts/audit-release-bundle.mjs",
+    "audit:file-size": "node ./scripts/audit-file-size.mjs",
+    "audit:rule-id-uniqueness": "node ./scripts/audit-rule-id-uniqueness.mjs",
     "audit:v3-purge": "node ./scripts/v3-purge-audit.mjs",
+    "build:release-bundle": "node ./scripts/build-release-benchmark-bundle.mjs",
     "sync:adapters": "node ./scripts/sync-thin-adapters.mjs",
     "check:adapters": "node ./scripts/sync-thin-adapters.mjs --check",
     "gate:release": "node ./scripts/release-gate.mjs && node ./scripts/forbidden-content-check.mjs",
@@ -69,11 +76,19 @@
     "benchmark:gate": "node ./scripts/benchmark-gate.mjs",
     "benchmark:intelligence": "node ./scripts/benchmark-intelligence.mjs",
     "benchmark:continuity": "node ./scripts/memory-continuity-benchmark.mjs",
+    "benchmark:cache-phase-2": "node ./benchmarks/token-usage/run-cache-simulation.mjs",
+    "benchmark:anti-halu": "node ./benchmarks/anti-halu/run-benchmark.mjs",
     "report:quality-trend": "node ./scripts/quality-trend-report.mjs",
     "report:docs-quality-drift": "node ./scripts/docs-quality-drift-report.mjs",
     "report:governance-weekly": "node ./scripts/governance-weekly-report.mjs",
     "clean:local": "node ./scripts/clean-local-artifacts.mjs",
     "validate": "node ./scripts/validate.mjs",
-    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/ui-rubric-calibration.test.mjs ./tests/operations.test.mjs ./tests/knowledge-injection.test.mjs"
+    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/ui-rubric-calibration.test.mjs ./tests/operations.test.mjs ./tests/knowledge-injection.test.mjs ./tests/migrate-rule-format.test.mjs ./tests/audit-caching-scope-hygiene.test.mjs ./benchmarks/token-usage/lib/token-counter.test.mjs ./benchmarks/token-usage/lib/provider-cache-matrix.test.mjs ./benchmarks/token-usage/lib/cache-layer-contract.test.mjs ./benchmarks/token-usage/lib/cache-economics.test.mjs"
+  },
+  "devDependencies": {
+    "@anthropic-ai/sdk": "^0.96.0",
+    "@google/genai": "^2.3.0",
+    "tiktoken": "^1.0.22",
+    "yaml": "^2.9.0"
   }
 }

package/scripts/audit-cache-layer-contract.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+/**
+ * audit-cache-layer-contract.mjs
+ *
+ * Phase 2 cache-layer integrity gate. Validates provider cache metadata,
+ * fixture segmentation, and the emitted cache simulation JSON without calling
+ * provider APIs.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+  CACHE_LAYER_DEFINITIONS,
+  CACHE_LAYER_IDS,
+  validateCacheLayerContract,
+} from '../benchmarks/token-usage/lib/cache-layer-contract.mjs';
+import {
+  CACHE_MATRIX_VERIFIED_AT,
+  PROVIDER_CACHE_MATRIX,
+  listProviderCacheEntries,
+} from '../benchmarks/token-usage/lib/provider-cache-matrix.mjs';
+import {
+  buildCacheLayeredScenarioPrompts,
+  loadFixtures,
+} from '../benchmarks/token-usage/runners/_shared.mjs';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+const DEFAULT_RESULT_PATH = join(REPOSITORY_ROOT, 'benchmarks', 'results', 'cache-phase-2-2026-05-16.json');
+const ARGS = new Set(process.argv.slice(2));
+const JSON_ONLY = ARGS.has('--json');
+
+const REQUIRED_PROVIDER_KEYS = [
+  'provider',
+  'sourceUrl',
+  'sourceType',
+  'verifiedAt',
+  'cacheMode',
+  'minimumCacheableTokens',
+  'costModel',
+];
+
+function addViolation(violations, kind, detail, context = {}) {
+  violations.push({ kind, detail, ...context });
+}
+
+function validateProviderMatrix(violations) {
+  for (const entry of listProviderCacheEntries()) {
+    for (const key of REQUIRED_PROVIDER_KEYS) {
+      if (!(key in entry)) {
+        addViolation(violations, 'provider-metadata.missing-key', `${entry.provider} missing ${key}`, { provider: entry.provider });
+      }
+    }
+
+    if (entry.sourceType === 'official-docs') {
+      if (typeof entry.sourceUrl !== 'string' || !entry.sourceUrl.startsWith('https://')) {
+        addViolation(violations, 'provider-metadata.invalid-source-url', `${entry.provider} official sourceUrl must be https`, { provider: entry.provider });
+      }
+      if (entry.verifiedAt !== CACHE_MATRIX_VERIFIED_AT) {
+        addViolation(violations, 'provider-metadata.invalid-verified-at', `${entry.provider} verifiedAt must be ${CACHE_MATRIX_VERIFIED_AT}`, { provider: entry.provider });
+      }
+    }
+
+    if (entry.provider === 'anthropic') {
+      const ttlOptions = entry.costModel?.ttlOptions;
+      if (ttlOptions?.['5m']?.writeMultiplier !== 1.25 || ttlOptions?.['5m']?.readMultiplier !== 0.1) {
+        addViolation(violations, 'provider-metadata.anthropic-5m-multiplier', 'Anthropic 5m cache multipliers drifted');
+      }
+      if (ttlOptions?.['1h']?.writeMultiplier !== 2.0 || ttlOptions?.['1h']?.readMultiplier !== 0.1) {
+        addViolation(violations, 'provider-metadata.anthropic-1h-multiplier', 'Anthropic 1h cache multipliers drifted');
+      }
+    }
+
+    if (['openai', 'gemini'].includes(entry.provider) && entry.costModel?.accurate !== false) {
+      addViolation(violations, 'provider-metadata.fake-universal-pricing', `${entry.provider} must not claim universal accurate pricing`, { provider: entry.provider });
+    }
+  }
+}
+
+function validateLayerDefinitions(violations) {
+  const definitionIds = Object.keys(CACHE_LAYER_DEFINITIONS);
+  const uniqueDefinitionIds = new Set(definitionIds);
+  if (definitionIds.length !== uniqueDefinitionIds.size) {
+    addViolation(violations, 'layer-definition.duplicate-id', 'Cache layer definition IDs must be unique');
+  }
+
+  const expectedIds = [
+    CACHE_LAYER_IDS.STATIC_PREFIX,
+    CACHE_LAYER_IDS.SEMI_STATIC_CONTEXT,
+    CACHE_LAYER_IDS.DYNAMIC_SUFFIX,
+  ];
+  if (JSON.stringify(definitionIds) !== JSON.stringify(expectedIds)) {
+    addViolation(violations, 'layer-definition.unexpected-order', `Expected ${expectedIds.join(', ')}, got ${definitionIds.join(', ')}`);
+  }
+}
+
+function validateFixtureSegmentation(violations) {
+  const fixtures = loadFixtures();
+  let auditedScenarioCount = 0;
+  for (const fixture of fixtures) {
+    const layered = buildCacheLayeredScenarioPrompts(fixture);
+    const scenarios = [
+      { name: 'always_included', contract: layered.alwaysIncluded },
+      { name: 'with_loaded_rules', contract: layered.withLoadedRules },
+    ];
+
+    for (const scenario of scenarios) {
+      auditedScenarioCount += 1;
+      try {
+        validateCacheLayerContract(scenario.contract);
+      } catch (error) {
+        addViolation(violations, 'fixture-segmentation.invalid-contract', error.message, {
+          fixture_id: fixture.id,
+          scenario: scenario.name,
+        });
+      }
+
+      const layerIds = scenario.contract.layers.map((layer) => layer.id);
+      if (new Set(layerIds).size !== layerIds.length) {
+        addViolation(violations, 'fixture-segmentation.duplicate-layer-id', 'Fixture contract contains duplicate layer IDs', {
+          fixture_id: fixture.id,
+          scenario: scenario.name,
+        });
+      }
+
+      for (const layer of [
+        scenario.contract.layer_1_static_prefix,
+        scenario.contract.layer_2_semi_static_context,
+      ]) {
+        if (layer.content.includes(fixture.user_message)) {
+          addViolation(violations, 'fixture-segmentation.dynamic-leak', `Fixture user message leaked into ${layer.id}`, {
+            fixture_id: fixture.id,
+            scenario: scenario.name,
+          });
+        }
+      }
+
+      if (scenario.contract.layer_3_dynamic_suffix.content.trim().length === 0) {
+        addViolation(violations, 'fixture-segmentation.missing-dynamic-layer', 'Layer 3 dynamic suffix is empty', {
+          fixture_id: fixture.id,
+          scenario: scenario.name,
+        });
+      }
+    }
+  }
+  return { fixtureCount: fixtures.length, auditedScenarioCount };
+}
+
+function validateSimulationResultJson(violations, resultPath = DEFAULT_RESULT_PATH) {
+  if (!existsSync(resultPath)) {
+    addViolation(violations, 'result-json.missing', `Missing cache simulation result: ${resultPath}`);
+    return { resultPath, resultCount: 0 };
+  }
+
+  const parsed = JSON.parse(readFileSync(resultPath, 'utf8'));
+  if (parsed.report_version !== '2.0.0') {
+    addViolation(violations, 'result-json.schema-version', `Unexpected report_version ${parsed.report_version}`);
+  }
+  if (!Array.isArray(parsed.results) || parsed.results.length === 0) {
+    addViolation(violations, 'result-json.results-empty', 'results must be a non-empty array');
+    return { resultPath, resultCount: 0 };
+  }
+
+  const expectedResultCount = parsed.fixture_count * parsed.provider_count * parsed.scenario_count;
+  if (parsed.results.length !== expectedResultCount) {
+    addViolation(violations, 'result-json.result-count', `Expected ${expectedResultCount} rows, got ${parsed.results.length}`);
+  }
+
+  for (const result of parsed.results) {
+    if (!result.token_counts || !result.economic_projection) {
+      addViolation(violations, 'result-json.missing-separation', 'Result must separate token_counts and economic_projection', {
+        fixture_id: result.fixture_id,
+        provider: result.provider,
+        scenario: result.scenario,
+      });
+      continue;
+    }
+    if (typeof result.token_counts.layer_3_dynamic_suffix !== 'number' || result.token_counts.layer_3_dynamic_suffix <= 0) {
+      addViolation(violations, 'result-json.missing-layer-3-tokens', 'Layer 3 token count must be present and positive', {
+        fixture_id: result.fixture_id,
+        provider: result.provider,
+        scenario: result.scenario,
+      });
+    }
+    if (result.economic_projection.accurate === true && (!result.source?.sourceUrl || !result.source?.verifiedAt)) {
+      addViolation(violations, 'result-json.accurate-without-source', 'Accurate projection requires official source metadata', {
+        fixture_id: result.fixture_id,
+        provider: result.provider,
+        scenario: result.scenario,
+      });
+    }
+    if (['openai', 'gemini'].includes(result.provider) && result.economic_projection.first_request_effective_tokens !== null) {
+      addViolation(violations, 'result-json.fake-openai-gemini-savings', `${result.provider} must not emit exact savings without pricing metadata`, {
+        fixture_id: result.fixture_id,
+        scenario: result.scenario,
+      });
+    }
+  }
+
+  return { resultPath, resultCount: parsed.results.length };
+}
+
+export function runCacheLayerContractAudit({ resultPath = DEFAULT_RESULT_PATH } = {}) {
+  const violations = [];
+  validateProviderMatrix(violations);
+  validateLayerDefinitions(violations);
+  const segmentationStats = validateFixtureSegmentation(violations);
+  const resultStats = validateSimulationResultJson(violations, resultPath);
+
+  return {
+    auditName: 'audit-cache-layer-contract',
+    reportVersion: '1.0.0',
+    generatedAt: new Date().toISOString(),
+    providerCount: Object.keys(PROVIDER_CACHE_MATRIX).length,
+    ...segmentationStats,
+    ...resultStats,
+    violationCount: violations.length,
+    violations,
+    passed: violations.length === 0,
+  };
+}
+
+function main() {
+  const report = runCacheLayerContractAudit();
+
+  if (JSON_ONLY) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    process.exit(report.passed ? 0 : 1);
+  }
+
+  console.log('===============================================');
+  console.log('  audit:cache-layer-contract');
+  console.log('===============================================');
+  console.log(`  Providers:          ${report.providerCount}`);
+  console.log(`  Fixtures:           ${report.fixtureCount}`);
+  console.log(`  Layered scenarios:  ${report.auditedScenarioCount}`);
+  console.log(`  Result rows:        ${report.resultCount}`);
+  console.log('');
+
+  if (report.passed) {
+    console.log('  Cache layer contract audit clean.');
+    process.stderr.write(`AUDIT_CACHE_LAYER_REPORT: ${JSON.stringify({ passed: true, providerCount: report.providerCount, resultCount: report.resultCount })}\n`);
+    process.exit(0);
+  }
+
+  console.log('  Violations:');
+  for (const violation of report.violations) {
+    console.log(`    [${violation.kind}] ${violation.detail}`);
+  }
+  process.stderr.write(`AUDIT_CACHE_LAYER_REPORT: ${JSON.stringify({ passed: false, violationCount: report.violationCount })}\n`);
+  process.exit(1);
+}
+
+if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('audit-cache-layer-contract.mjs')) {
+  main();
+}

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/plan/research-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, plan files under docs/plan/, 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/plan/research-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();
+}