@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.0

package/.agent-context/rules/testing.md

@@ -1,22 +1,42 @@
+---
+id_prefix: TEST
+domain: testing
+priority: high
+scope: all-tasks
+applies_to:
+  - backend
+  - frontend
+  - fullstack
+keywords:
+  - testing
+  - test
+  - behavior
+  - contract
+  - failure
+  - boundaries
+---
+
 # Testing Boundary
 
-Use the test runner and style already present in the repo. If no test setup exists, the LLM must recommend a current, lightweight, project-fit setup from official docs before adding one.
+Use the test runner and style already present in the repo.
 
-Test what can break:
-- business rules, validation, authorization, state transitions, and error paths
-- public APIs, UI flows, integration boundaries, and data contracts touched by the change
-- regressions around bugs being fixed
-- critical accessibility or responsive behavior when UI is in scope
+## TEST-001: Test Scope
 
-Backend/API test rules:
-- API tests must cover request validation, authorization boundaries, success responses, documented error shapes, pagination defaults, and empty states for touched endpoints.
-- Sensitive mutations such as payments, orders, status changes, inventory adjustments, and account/security changes must include duplicate-submit or retry tests when idempotency is required.
-- Data-access changes must include evidence for query shape, transaction behavior, rollback or recovery paths, and N+1 prevention when relational reads are touched.
-- Event or worker changes must test retry, duplicate-message handling, dead-letter or recovery behavior, and outbox relay semantics when those paths exist.
-- Distributed consistency changes must test the local transaction, publish/retry behavior, and compensating action or recovery path rather than only the happy path.
-- Tests should make the API contract obvious from the fixture names, inputs, and expected response shape.
-- Tests must exercise the failure paths the code claims to handle, not only the happy path. Prefer property-based or generated-input tests for invariants (validation, ordering, idempotency), explicit failure-injection tests for retry and recovery code, and contract tests at service boundaries when consumer and producer ownership is split.
+1. If no test setup exists, recommend a current, lightweight, project-fit setup from official docs before adding one.
+2. Test what can break: business rules, validation, authorization, state transitions, and error paths.
+3. Test public APIs, UI flows, integration boundaries, and data contracts touched by the change.
+4. Test regressions around bugs being fixed.
+5. Test critical accessibility or responsive behavior when UI is in scope.
+6. Do not test framework internals, third-party library behavior, private implementation trivia, or snapshots that only freeze noise.
+7. Tests should describe behavior, keep setup readable, and mock only at real boundaries such as network, filesystem, clock, database, or external services.
 
-Do not test framework internals, third-party library behavior, private implementation trivia, or snapshots that only freeze noise.
+## TEST-002: Backend and API Test Rules
 
-Tests should describe behavior, keep setup readable, and mock only at real boundaries such as network, filesystem, clock, database, or external services.
+1. API tests must cover request validation, authorization boundaries, success responses, documented error shapes, pagination defaults, and empty states for touched endpoints.
+2. Sensitive mutations such as payments, orders, status changes, inventory adjustments, and account/security changes must include duplicate-submit or retry tests when idempotency is required.
+3. Data-access changes must include evidence for query shape, transaction behavior, rollback or recovery paths, and N+1 prevention when relational reads are touched.
+4. Event or worker changes must test retry, duplicate-message handling, dead-letter or recovery behavior, and outbox relay semantics when those paths exist.
+5. Distributed consistency changes must test the local transaction, publish/retry behavior, and compensating action or recovery path rather than only the happy path.
+6. Tests should make the API contract obvious from the fixture names, inputs, and expected response shape.
+7. Tests must exercise the failure paths the code claims to handle, not only the happy path.
+8. Prefer property-based or generated-input tests for invariants such as validation, ordering, and idempotency; prefer explicit failure-injection tests for retry and recovery code; prefer contract tests at service boundaries when consumer and producer ownership is split.

package/AGENTS.md

@@ -8,7 +8,7 @@ Act as a Principal Engineer. Ship maintainable, validated, production-ready work
 ## Authority
 This repository is governed by a strict instruction contract.
 
-Use `AGENTS.md` as the canonical baseline. Use `.agent-context/` as technical authority for rules, prompts, checklists, state, and policies. Use `README.md` only for public and developer overview, setup, usage, and user-facing context when stricter governance files conflict.
+Use `AGENTS.md` as the canonical baseline. Use `.agent-context/` as technical authority for rules, prompts, checklists, state, and policies. Follow stricter `.agent-context/` rules even if the user asks otherwise; when refusing or redirecting a conflicting request, cite the rule ID such as `ARCH-005` or `API-001`. Use `README.md` only for public and developer overview, setup, usage, and user-facing context when stricter governance files conflict.
 
 Write instructions as imperative gates:
 - Use direct commands.
@@ -36,7 +36,7 @@ Location: `.agent-context/rules/`.
 
 Load only relevant rule files. Do not read the entire rule directory by default.
 
-Available rules: `naming-conv.md`, `architecture.md`, `security.md`, `performance.md`, `error-handling.md`, `testing.md`, `git-workflow.md`, `efficiency-vs-hype.md`, `api-docs.md`, `microservices.md`, `event-driven.md`, `database-design.md`, `realtime.md`, `frontend-architecture.md`, `docker-runtime.md`.
+Available rules: `naming-conv.md` (`NAME-*`, v4), `architecture.md` (`ARCH-*`, v4), `security.md` (`SEC-*`, v4), `performance.md` (`PERF-*`, v4), `error-handling.md` (`ERR-*`, v4), `testing.md` (`TEST-*`, v4), `git-workflow.md` (`GIT-*`, v4), `efficiency-vs-hype.md` (`DEP-*`, v4), `api-docs.md` (`API-*`, v4), `microservices.md` (`SVC-*`, v4), `event-driven.md` (`EVT-*`, v4), `database-design.md` (`DATA-*`, v4), `realtime.md` (`RT-*`, v4), `frontend-architecture.md` (`FE-*`, v4), `docker-runtime.md` (`DOCK-*`, v4).
 
 For Docker or Compose work, load `docker-runtime.md` and verify the latest official Docker docs before authoring container assets. Also perform live web research for Docker and framework/package setup claims. For framework or package setup work, use the latest stable compatible dependency set and official setup flow unless a documented compatibility constraint blocks it. Prefer official framework scaffolders when they create the supported project shape; manual file assembly needs a repo, prototype, learning, or architecture reason. New dependencies are allowed when they improve efficiency, delivery time, correctness, accessibility, UX, or maintainability. Do not treat dependency avoidance or vague performance fear as a default reason to skip a modern maintained library.
 
@@ -146,16 +146,16 @@ Trigger: ui, ux, layout, screen, tailwind, frontend, redesign.
 9. Do not let conceptual anchors collapse into room, darkroom, counting room, control room, war room, studio, lab, cockpit, or command center by habit. Prefer artifacts, workflows, custody chains, instruments, data behaviors, material systems, editorial systems, service rituals, or interaction mechanisms unless a physical place model is core to the product.
 10. External websites and benchmark examples are candidate evidence for constraints, mechanics, and quality bars only. Do not copy their layout rhythm, palette, component skin, visual metaphor, or brand posture without explicit user approval and product-fit rationale.
 
-## Reasoning Chain
-
-When rejecting an approach or enforcing a rule, use:
+## Bounded Reflection
+For risky actions (file edits, public contracts, rule conflicts/refusals, release/publish gates, or security/data/API/testing/architecture boundaries), show this compact block before action or refusal:
 
 ```text
-REASONING CHAIN
-Problem: [risk]
-Required Action: [boundary]
-Why Required: [project protection]
+REFLECTION
+Rules: ARCH-003, TEST-001
+Risk: one-line risk or conflict
+Action: one-line bounded next step
 ```
+Use valid rule IDs only; do not quote full rule prose, expose hidden chain-of-thought, or require the block for trivial replies.
 
 ## Definition of Done
 

package/README.md

@@ -10,7 +10,7 @@
 **Production-grade Rules Engine (Governance Engine) for AI coding agents.**
 Works with Cursor, Windsurf, GitHub Copilot, Claude Code, Gemini, and other LLM-powered IDE workflows.
 
-Current package version: 3.0.48.
+Current package version: 4.0.0. Last published version before this release: 3.0.50.
 
 Highlights:
 - Uses `AGENTS.md` as the canonical instruction entrypoint.
@@ -22,6 +22,15 @@ Highlights:
 
 ---
 
+## What's New in v4
+
+The internal `.agent-context/rules/` pack is now numbered Markdown with YAML frontmatter and stable section IDs (e.g. `FE-004`, `ARCH-009`, `API-006`). This is a breaking change for downstream consumers that parse rule headings; the migration guide lives in `CHANGELOG.md` under `4.0.0`. Repository-wide impact:
+
+- Rules are now citable by ID, which the new bounded reflection block in `AGENTS.md` and the validation MCP tools (`lookup_rule`, `validate_against_rules`, `audit_compliance`) rely on.
+- A three-layer prompt caching contract (D4 in `docs/plan/research-foundation.md`) is now enforced by `npm run audit:cache-layer-contract`.
+- A provider-free anti-halu benchmark is included (`benchmarks/anti-halu/`); pass rate and citation validity are reproducible locally.
+- Caching numbers are scoped per integration. The 89.31% Anthropic warm-cache effective reduction reported in `benchmarks/results/cache-phase-2-2026-05-16.json` applies to direct provider API and Claude Code SDK programmatic mode only. IDE wrapper integrations (Cursor, Windsurf, Codex CLI, Kiro) receive prefix stability without a measurable per-pack saving. See `docs/integration-playbook.md` for the per-tool matrix and `docs/benchmark-reference.md` for the required reporting JSON shape.
+
 
 ## 60-Second Start
 

package/lib/cli/commands/init.mjs

@@ -1,3 +1,4 @@
+// @file-size-exception: Interactive CLI flow with sequential prompts; planned for split in Phase 1 commands refactor.
 /**
  * Init Command — Interactive project initialization.
  * Depends on: constants, utils, detector, compiler

package/lib/cli/compiler.mjs

@@ -1,3 +1,4 @@
+// @file-size-exception: Multiple compilation passes (rule + state + adapter); planned for split in Phase 1 compiler refactor.
 /**
  * Context Compiler — Rulebook compilation and state persistence.
  * Depends on: constants.mjs, utils.mjs

package/lib/cli/detector/constants.mjs

@@ -0,0 +1,135 @@
+/**
+ * Static configuration sets and known-marker tables for the project context
+ * detector. Centralized so workspace traversal, UI signal analysis, and stack
+ * detection share one source of truth.
+ */
+
+import { FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES } from './design-evidence.mjs';
+
+export const WORKSPACE_SCAN_MAX_DEPTH = 3;
+export const WORKSPACE_SCAN_MAX_DIRECTORIES = 120;
+
+export const WORKSPACE_SCAN_IGNORE_DIRECTORY_NAMES = new Set([
+  ...FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES,
+  '.agent-context',
+  '.agents',
+  '.cursor',
+  '.gemini',
+  '.github',
+  '.idea',
+  '.vscode',
+  '.windsurf',
+  '.zed',
+]);
+
+export const WORKSPACE_CONTAINER_DIRECTORY_NAMES = new Set([
+  'admin', 'admins',
+  'api', 'apis',
+  'app', 'apps',
+  'backend', 'backends',
+  'client', 'clients',
+  'dashboard', 'dashboards',
+  'frontend', 'frontends',
+  'mobile', 'mobiles',
+  'package', 'packages', 'pkg',
+  'server', 'servers',
+  'service', 'services',
+  'site', 'sites',
+  'ui', 'web',
+  'worker', 'workers',
+]);
+
+export const WORKSPACE_ROOT_MARKER_FILE_NAMES = new Set([
+  'lerna.json',
+  'nx.json',
+  'pnpm-workspace.yaml',
+  'turbo.json',
+]);
+
+export const DIRECT_UI_MARKER_NAMES = [
+  'src',
+  'next.config.js',
+  'next.config.mjs',
+  'next.config.ts',
+  'tailwind.config.js',
+  'tailwind.config.mjs',
+  'tailwind.config.ts',
+  'vite.config.js',
+  'vite.config.mjs',
+  'vite.config.ts',
+  'react-native.config.js',
+  'app',
+  'pages',
+  'components',
+  'public',
+  'styles',
+  'android',
+  'ios',
+  'index.html',
+];
+
+export const PROJECT_MARKER_FILE_NAMES = new Set([
+  'Cargo.toml',
+  'Gemfile',
+  'build.gradle',
+  'build.gradle.kts',
+  'composer.json',
+  'go.mod',
+  'package.json',
+  'pom.xml',
+  'pubspec.yaml',
+  'pyproject.toml',
+  'react-native.config.js',
+  'requirements.txt',
+  'tsconfig.json',
+  ...DIRECT_UI_MARKER_NAMES,
+]);
+
+export const INTERNAL_GOVERNANCE_SURFACE_NAMES = new Set([
+  '.agent-context',
+  '.agent-instructions.md',
+  '.agentic-backup',
+  '.agents',
+  '.clauderc',
+  '.cursorrules',
+  '.cursor',
+  '.gemini',
+  '.github',
+  '.instructions.md',
+  '.vscode',
+  '.windsurf',
+  '.windsurfrules',
+  '.zed',
+  'AGENTS.md',
+  'CLAUDE.md',
+  'GEMINI.md',
+  'mcp.json',
+]);
+
+const WORKSPACE_KEYWORD_FRAGMENTS = [
+  'admin', 'api', 'app', 'backend', 'client', 'dashboard',
+  'frontend', 'mobile', 'package', 'server', 'service',
+  'site', 'ui', 'web', 'worker',
+];
+
+export function looksLikeWorkspaceSearchCandidate(directoryName) {
+  const normalizedDirectoryName = String(directoryName || '').trim().toLowerCase();
+
+  if (!normalizedDirectoryName) {
+    return false;
+  }
+
+  if (WORKSPACE_CONTAINER_DIRECTORY_NAMES.has(normalizedDirectoryName)) {
+    return true;
+  }
+
+  return WORKSPACE_KEYWORD_FRAGMENTS.some((keyword) => normalizedDirectoryName.includes(keyword));
+}
+
+export function hasProjectMarkers(markerNames) {
+  return Array.from(markerNames).some((markerName) => (
+    PROJECT_MARKER_FILE_NAMES.has(markerName)
+    || markerName.endsWith('.csproj')
+    || markerName.endsWith('.sln')
+  ));
+}

package/lib/cli/detector/design-evidence/collector.mjs

@@ -0,0 +1,256 @@
+/**
+ * Top-level orchestrator for the design evidence scan. Resolves which roots to
+ * scan, walks the filesystem, and aggregates results from the inspection
+ * passes into a single summary plus a flat metrics object that downstream
+ * consumers (detector + UI rubric calibration) read.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  ANIMATION_PATTERN,
+  ARBITRARY_BREAKPOINT_PATTERN,
+  COLOR_PATTERN,
+  CSS_VARIABLE_DEFINITION_PATTERN,
+  CSS_VARIABLE_REFERENCE_PATTERN,
+  DURATION_PATTERN,
+  FONT_FAMILY_PATTERN,
+  FONT_SIZE_PATTERN,
+  FRONTEND_FILE_SCAN_LIMIT,
+  FRONTEND_FILE_SIZE_LIMIT_BYTES,
+  FRONTEND_SCAN_DIRECTORY_NAMES,
+  LETTER_SPACING_PATTERN,
+  LINE_HEIGHT_PATTERN,
+  MEDIA_QUERY_PATTERN,
+  MEDIA_WIDTH_PATTERN,
+  PROP_DRILLING_PATTERN,
+  RAW_RADIUS_PATTERN,
+  RAW_SHADOW_PATTERN,
+  RAW_SPACING_PATTERN,
+  TAILWIND_BREAKPOINT_PATTERN,
+  TRANSITION_PATTERN,
+} from './constants.mjs';
+import { collectFrontendSourceFilePaths, registerSurfaceFile } from './file-traversal.mjs';
+import { collectStructuredAttributeEvidence } from './structured-attribute-evidence.mjs';
+import { createDesignEvidenceSummary } from './summary.mjs';
+import {
+  categorizeCssVariable,
+  countPatternMatches,
+  incrementCountMap,
+  inferColorKind,
+  pushSampleValue,
+} from './utility-helpers.mjs';
+
+function resolveCandidateDirectoryPaths(targetDirectoryPath, markerNames, scanRootDirectoryPaths) {
+  const candidateDirectoryPaths = FRONTEND_SCAN_DIRECTORY_NAMES
+    .filter((directoryName) => markerNames.has(directoryName))
+    .map((directoryName) => path.join(targetDirectoryPath, directoryName));
+  const explicitScanRootDirectoryPaths = Array.isArray(scanRootDirectoryPaths)
+    ? scanRootDirectoryPaths.filter(
+      (scanRootDirectoryPath) => typeof scanRootDirectoryPath === 'string' && scanRootDirectoryPath.trim().length > 0,
+    )
+    : [];
+  if (explicitScanRootDirectoryPaths.length > 0) {
+    return Array.from(new Set(explicitScanRootDirectoryPaths));
+  }
+  if (candidateDirectoryPaths.length > 0) {
+    return candidateDirectoryPaths;
+  }
+  return [targetDirectoryPath];
+}
+
+export async function collectFrontendDesignEvidence({
+  targetDirectoryPath,
+  markerNames,
+  scanRootDirectoryPaths = [],
+}) {
+  const resolvedCandidateDirectoryPaths = resolveCandidateDirectoryPaths(
+    targetDirectoryPath,
+    markerNames,
+    scanRootDirectoryPaths,
+  );
+  const scannedFilePaths = [];
+  const scanRootRelativePaths = resolvedCandidateDirectoryPaths
+    .map((candidateDirectoryPath) => (
+      path.relative(targetDirectoryPath, candidateDirectoryPath).replace(/\\/g, '/') || '.'
+    ));
+  const designEvidenceSummary = createDesignEvidenceSummary(scanRootRelativePaths);
+  const cssVariableSamples = new Set();
+  const colorSamples = new Set();
+  const spacingSamples = new Set();
+  const radiusSamples = new Set();
+  const shadowSamples = new Set();
+  const fontFamilySamples = new Set();
+  const fontSizeSamples = new Set();
+  const lineHeightSamples = new Set();
+  const letterSpacingSamples = new Set();
+  const durationSamples = new Set();
+  const structuredClassAttributeSamples = new Set();
+  const structuredInlineStyleSamples = new Set();
+  const structuredUtilityFamilySamples = new Set();
+  const seenSurfaceFiles = new Set();
+  let hardcodedColorCount = 0;
+  let propDrillingCandidateCount = 0;
+  let mediaQueryCount = 0;
+  let tailwindBreakpointUsageCount = 0;
+  let arbitraryBreakpointCount = 0;
+  const uniqueMediaWidths = new Set();
+
+  for (const candidateDirectoryPath of resolvedCandidateDirectoryPaths) {
+    await collectFrontendSourceFilePaths(candidateDirectoryPath, scannedFilePaths);
+    if (scannedFilePaths.length >= FRONTEND_FILE_SCAN_LIMIT) {
+      break;
+    }
+  }
+
+  designEvidenceSummary.scannedFileCount = scannedFilePaths.length;
+
+  for (const scannedFilePath of scannedFilePaths) {
+    let sourceText;
+
+    try {
+      const fileStat = await fs.stat(scannedFilePath);
+      if (fileStat.size > FRONTEND_FILE_SIZE_LIMIT_BYTES) {
+        continue;
+      }
+
+      sourceText = await fs.readFile(scannedFilePath, 'utf8');
+    } catch {
+      continue;
+    }
+
+    registerSurfaceFile(designEvidenceSummary, targetDirectoryPath, scannedFilePath, seenSurfaceFiles);
+    collectStructuredAttributeEvidence(
+      sourceText,
+      designEvidenceSummary,
+      structuredClassAttributeSamples,
+      structuredInlineStyleSamples,
+      structuredUtilityFamilySamples,
+    );
+
+    for (const cssVariableMatch of sourceText.matchAll(CSS_VARIABLE_DEFINITION_PATTERN)) {
+      designEvidenceSummary.cssVariables.definitionCount += 1;
+      const variableName = cssVariableMatch[1];
+      const categoryKey = categorizeCssVariable(variableName);
+      incrementCountMap(designEvidenceSummary.cssVariables.categoryCounts, categoryKey);
+      pushSampleValue(designEvidenceSummary.cssVariables.sampleNames, variableName, cssVariableSamples);
+    }
+
+    for (const cssVariableReferenceMatch of sourceText.matchAll(CSS_VARIABLE_REFERENCE_PATTERN)) {
+      designEvidenceSummary.cssVariables.referenceCount += 1;
+      pushSampleValue(
+        designEvidenceSummary.cssVariables.sampleNames,
+        cssVariableReferenceMatch[1],
+        cssVariableSamples,
+      );
+    }
+
+    for (const colorMatch of sourceText.matchAll(COLOR_PATTERN)) {
+      const colorValue = colorMatch[0];
+      hardcodedColorCount += 1;
+      designEvidenceSummary.colors.hardcodedCount += 1;
+      incrementCountMap(designEvidenceSummary.colors.kindCounts, inferColorKind(colorValue));
+      pushSampleValue(designEvidenceSummary.colors.sampleValues, colorValue, colorSamples);
+    }
+
+    propDrillingCandidateCount += countPatternMatches(sourceText, PROP_DRILLING_PATTERN);
+    mediaQueryCount += countPatternMatches(sourceText, MEDIA_QUERY_PATTERN);
+    tailwindBreakpointUsageCount += countPatternMatches(sourceText, TAILWIND_BREAKPOINT_PATTERN);
+    arbitraryBreakpointCount += countPatternMatches(sourceText, ARBITRARY_BREAKPOINT_PATTERN);
+    designEvidenceSummary.tailwind.breakpointUsageCount += countPatternMatches(sourceText, TAILWIND_BREAKPOINT_PATTERN);
+    designEvidenceSummary.tailwind.arbitraryBreakpointCount += countPatternMatches(sourceText, ARBITRARY_BREAKPOINT_PATTERN);
+
+    for (const rawSpacingMatch of sourceText.matchAll(RAW_SPACING_PATTERN)) {
+      designEvidenceSummary.spacing.rawValueCount += 1;
+      pushSampleValue(designEvidenceSummary.spacing.sampleValues, rawSpacingMatch[1], spacingSamples);
+    }
+
+    for (const rawRadiusMatch of sourceText.matchAll(RAW_RADIUS_PATTERN)) {
+      designEvidenceSummary.radius.rawValueCount += 1;
+      pushSampleValue(designEvidenceSummary.radius.sampleValues, rawRadiusMatch[1], radiusSamples);
+    }
+
+    for (const rawShadowMatch of sourceText.matchAll(RAW_SHADOW_PATTERN)) {
+      designEvidenceSummary.shadow.rawValueCount += 1;
+      pushSampleValue(designEvidenceSummary.shadow.sampleValues, rawShadowMatch[1], shadowSamples);
+    }
+
+    for (const fontFamilyMatch of sourceText.matchAll(FONT_FAMILY_PATTERN)) {
+      designEvidenceSummary.typography.fontFamilyCount += 1;
+      pushSampleValue(designEvidenceSummary.typography.fontFamilySamples, fontFamilyMatch[1], fontFamilySamples);
+    }
+
+    for (const fontSizeMatch of sourceText.matchAll(FONT_SIZE_PATTERN)) {
+      designEvidenceSummary.typography.fontSizeCount += 1;
+      pushSampleValue(designEvidenceSummary.typography.fontSizeSamples, fontSizeMatch[1], fontSizeSamples);
+    }
+
+    for (const lineHeightMatch of sourceText.matchAll(LINE_HEIGHT_PATTERN)) {
+      designEvidenceSummary.typography.lineHeightCount += 1;
+      pushSampleValue(designEvidenceSummary.typography.lineHeightSamples, lineHeightMatch[1], lineHeightSamples);
+    }
+
+    for (const letterSpacingMatch of sourceText.matchAll(LETTER_SPACING_PATTERN)) {
+      designEvidenceSummary.typography.letterSpacingCount += 1;
+      pushSampleValue(
+        designEvidenceSummary.typography.letterSpacingSamples,
+        letterSpacingMatch[1],
+        letterSpacingSamples,
+      );
+    }
+
+    designEvidenceSummary.motion.transitionCount += countPatternMatches(sourceText, TRANSITION_PATTERN);
+    designEvidenceSummary.motion.animationCount += countPatternMatches(sourceText, ANIMATION_PATTERN);
+
+    for (const durationMatch of sourceText.matchAll(DURATION_PATTERN)) {
+      designEvidenceSummary.motion.durationCount += 1;
+      pushSampleValue(designEvidenceSummary.motion.durationSamples, durationMatch[0], durationSamples);
+    }
+
+    for (const mediaWidthMatch of sourceText.matchAll(MEDIA_WIDTH_PATTERN)) {
+      uniqueMediaWidths.add(mediaWidthMatch[1]);
+    }
+  }
+
+  designEvidenceSummary.tailwind.utilityFamilyCounts = {
+    ...designEvidenceSummary.structuredInspection.utilityFamilyCounts,
+  };
+  designEvidenceSummary.tailwind.utilityFamilySamples = [
+    ...designEvidenceSummary.structuredInspection.utilityFamilySamples,
+  ];
+
+  designEvidenceSummary.tokenBypassSignals = {
+    hardcodedColorCount: designEvidenceSummary.colors.hardcodedCount,
+    rawSpacingCount: designEvidenceSummary.spacing.rawValueCount,
+    rawRadiusCount: designEvidenceSummary.radius.rawValueCount,
+    rawShadowCount: designEvidenceSummary.shadow.rawValueCount,
+    inlineHardcodedColorCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.hardcodedColorCount,
+    inlineRawSpacingCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawSpacingCount,
+    inlineRawRadiusCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawRadiusCount,
+    inlineRawShadowCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawShadowCount,
+    inlineCssVariableReferenceCount: designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.cssVariableReferenceCount,
+  };
+
+  return {
+    frontendEvidenceMetrics: {
+      scannedFileCount: scannedFilePaths.length,
+      hardcodedColorCount,
+      propDrillingCandidateCount,
+      mediaQueryCount,
+      tailwindBreakpointUsageCount,
+      arbitraryBreakpointCount,
+      uniqueMediaWidthCount: uniqueMediaWidths.size,
+      structuredClassAttributeCount: designEvidenceSummary.structuredInspection.classAttributeCount,
+      boundClassExpressionCount: designEvidenceSummary.structuredInspection.boundClassExpressionCount,
+      inlineStyleObjectCount: designEvidenceSummary.structuredInspection.inlineStyleObjectCount,
+      inlineStyleBindingCount: designEvidenceSummary.structuredInspection.inlineStyleBindingCount,
+      inlineStyleTokenBypassCount:
+        designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.hardcodedColorCount
+        + designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawSpacingCount
+        + designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawRadiusCount
+        + designEvidenceSummary.structuredInspection.inlineTokenBypassSignals.rawShadowCount,
+    },
+    designEvidenceSummary,
+  };
+}

package/lib/cli/detector/design-evidence/constants.mjs

@@ -0,0 +1,39 @@
+/**
+ * Static configuration and regex patterns for the lightweight static design
+ * evidence scan. Kept in one place so the scanner internals stay pattern-driven
+ * and reviewable.
+ */
+
+export const FRONTEND_SCAN_DIRECTORY_NAMES = ['src', 'app', 'pages', 'components', 'styles'];
+export const FRONTEND_SCAN_FILE_EXTENSIONS = new Set([
+  '.js', '.jsx', '.ts', '.tsx', '.vue', '.css', '.scss', '.sass',
+]);
+export const FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES = new Set([
+  '.git', 'node_modules', '.next', 'dist', 'build', 'coverage',
+]);
+export const FRONTEND_FILE_SCAN_LIMIT = 200;
+export const FRONTEND_FILE_SIZE_LIMIT_BYTES = 200_000;
+export const DESIGN_EVIDENCE_SAMPLE_LIMIT = 12;
+
+export const COLOR_PATTERN = /#[0-9a-fA-F]{3,8}\b|rgba?\([^)]+\)|hsla?\([^)]+\)|oklch\([^)]+\)/g;
+export const PROP_DRILLING_PATTERN = /<[A-Z][A-Za-z0-9_.:-]*(?:\s+[A-Za-z0-9_:-]+=\{[^}]+\}){5,}/g;
+export const MEDIA_QUERY_PATTERN = /@media\b/g;
+export const TAILWIND_BREAKPOINT_PATTERN = /\b(?:sm|md|lg|xl|2xl):/g;
+export const ARBITRARY_BREAKPOINT_PATTERN = /\b(?:min|max)-\[[^\]]+\]:/g;
+export const CSS_VARIABLE_DEFINITION_PATTERN = /--([a-zA-Z0-9-_]+)\s*:/g;
+export const CSS_VARIABLE_REFERENCE_PATTERN = /var\(--([a-zA-Z0-9-_]+)\)/g;
+export const RAW_SPACING_PATTERN = /\b(?:margin|padding|gap|column-gap|row-gap|min-width|max-width|min-height|max-height|width|height|top|right|bottom|left|inset|spaceBetween|paddingInline|paddingBlock|marginInline|marginBlock|gapX|gapY|spaceX|spaceY)\b[^;\n:]*[:=]\s*['"`{(]*(-?[0-9.]+(?:px|rem|em|vh|vw))/gi;
+export const RAW_RADIUS_PATTERN = /\b(?:border-radius|borderRadius)\b[^;\n:]*[:=]\s*['"`{(]*([0-9.]+(?:px|rem|em)|9999px)/gi;
+export const RAW_SHADOW_PATTERN = /\b(?:box-shadow|boxShadow)\b[^;\n:]*[:=]\s*['"`{(]*([^;\n}]+)/gi;
+export const FONT_FAMILY_PATTERN = /\b(?:font-family|fontFamily)\b[^;\n:]*[:=]\s*['"`{(]*([^;\n}]+)/gi;
+export const FONT_SIZE_PATTERN = /\b(?:font-size|fontSize)\b[^;\n:]*[:=]\s*['"`{(]*([0-9.]+(?:px|rem|em))/gi;
+export const LINE_HEIGHT_PATTERN = /\b(?:line-height|lineHeight)\b[^;\n:]*[:=]\s*['"`{(]*([0-9.]+(?:px|rem|em)?)/gi;
+export const LETTER_SPACING_PATTERN = /\b(?:letter-spacing|letterSpacing)\b[^;\n:]*[:=]\s*['"`{(]*([0-9.-]+(?:px|rem|em))/gi;
+export const TRANSITION_PATTERN = /\btransition(?:-[a-z]+)?\b/g;
+export const ANIMATION_PATTERN = /\banimation(?:-[a-z]+)?\b/g;
+export const DURATION_PATTERN = /\b\d+(?:\.\d+)?m?s\b/g;
+export const MEDIA_WIDTH_PATTERN = /\((?:min|max)-width:\s*([0-9.]+(?:px|rem|em))\)/g;
+export const STRING_CLASS_ATTRIBUTE_PATTERN = /\b(?:className|class)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{`([^`]*)`\}|\{"([^"]*)"\}|\{'([^']*)'\})/g;
+export const EXPRESSION_CLASS_ATTRIBUTE_PATTERN = /\b(?:className|class|:class)\s*=\s*\{([^}\n]+)\}/g;
+export const JSX_INLINE_STYLE_PATTERN = /\bstyle\s*=\s*\{\{([\s\S]*?)\}\}/g;
+export const VUE_INLINE_STYLE_PATTERN = /\b:style\s*=\s*["']\{([^"']*)\}["']/g;

package/lib/cli/detector/design-evidence/file-traversal.mjs

@@ -0,0 +1,83 @@
+/**
+ * Filesystem traversal and surface-file classification for the design evidence
+ * scan. Bounded by FRONTEND_FILE_SCAN_LIMIT so the scan never blows up on huge
+ * monorepos.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  DESIGN_EVIDENCE_SAMPLE_LIMIT,
+  FRONTEND_FILE_SCAN_LIMIT,
+  FRONTEND_SCAN_FILE_EXTENSIONS,
+  FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES,
+} from './constants.mjs';
+
+export async function collectFrontendSourceFilePaths(directoryPath, collectedFilePaths = []) {
+  if (collectedFilePaths.length >= FRONTEND_FILE_SCAN_LIMIT) {
+    return collectedFilePaths;
+  }
+
+  let directoryEntries;
+  try {
+    directoryEntries = await fs.readdir(directoryPath, { withFileTypes: true });
+  } catch {
+    return collectedFilePaths;
+  }
+
+  for (const directoryEntry of directoryEntries) {
+    if (collectedFilePaths.length >= FRONTEND_FILE_SCAN_LIMIT) {
+      break;
+    }
+
+    if (directoryEntry.isDirectory()) {
+      if (FRONTEND_SCAN_IGNORE_DIRECTORY_NAMES.has(directoryEntry.name)) {
+        continue;
+      }
+
+      await collectFrontendSourceFilePaths(path.join(directoryPath, directoryEntry.name), collectedFilePaths);
+      continue;
+    }
+
+    const fileExtension = path.extname(directoryEntry.name).toLowerCase();
+    if (FRONTEND_SCAN_FILE_EXTENSIONS.has(fileExtension)) {
+      collectedFilePaths.push(path.join(directoryPath, directoryEntry.name));
+    }
+  }
+
+  return collectedFilePaths;
+}
+
+export function registerSurfaceFile(summary, targetDirectoryPath, scannedFilePath, seenSurfaceFiles) {
+  const relativeFilePath = path.relative(targetDirectoryPath, scannedFilePath).replace(/\\/g, '/');
+  const normalizedBaseName = path.basename(scannedFilePath, path.extname(scannedFilePath)).toLowerCase();
+  const looksLikeComponent = /[A-Z]/.test(path.basename(scannedFilePath, path.extname(scannedFilePath)))
+    || relativeFilePath.includes('/components/')
+    || relativeFilePath.startsWith('components/');
+  const looksLikePage = normalizedBaseName === 'page'
+    || normalizedBaseName === 'index'
+    || relativeFilePath.includes('/pages/')
+    || relativeFilePath.startsWith('pages/')
+    || relativeFilePath.includes('/app/');
+  const looksLikeLayout = normalizedBaseName === 'layout' || relativeFilePath.includes('/layouts/');
+
+  if (looksLikeComponent) {
+    summary.componentInventory.componentFileCount += 1;
+  }
+
+  if (looksLikePage) {
+    summary.componentInventory.pageFileCount += 1;
+  }
+
+  if (looksLikeLayout) {
+    summary.componentInventory.layoutFileCount += 1;
+  }
+
+  if ((looksLikeComponent || looksLikePage || looksLikeLayout) && !seenSurfaceFiles.has(relativeFilePath)) {
+    seenSurfaceFiles.add(relativeFilePath);
+    if (summary.componentInventory.surfaceFileSamples.length < DESIGN_EVIDENCE_SAMPLE_LIMIT) {
+      summary.componentInventory.surfaceFileSamples.push(relativeFilePath);
+    }
+  }
+}