@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

package/scripts/rules-guardian-audit.mjs

@@ -36,15 +36,15 @@ const SUPPORTED_WORKFLOWS = new Set([
 const CORE_PATTERN_SIGNALS = [
   {
     pattern: 'layer-separation',
-    snippet: 'Every layer has ONE job.',
+    snippet: '## Layer Boundaries (Mandatory)',
   },
   {
-    pattern: 'modular-monolith-default',
-    snippet: 'Default Architecture: Modular Monolith',
+    pattern: 'agent-decides-topology',
+    snippet: 'Do not force a default architecture label before the repo, delivery model, and boundary evidence are clear.',
   },
   {
     pattern: 'feature-based-grouping',
-    snippet: 'Project Structure: Feature-Based Grouping',
+    snippet: 'Group code by feature or domain',
   },
   {
     pattern: 'rules-as-guardian-cross-session',
@@ -55,7 +55,7 @@ const CORE_PATTERN_SIGNALS = [
 const REQUIRED_ARCHITECTURE_RULE_SNIPPETS = [
   '## Rules as Guardian (Cross-Session Consistency)',
   'Session handoff must include active architecture contract summary.',
-  'Detect drift before changing declared stack or core patterns.',
+  'Detect drift before changing runtime choices, topology, public contracts, or core patterns.',
   'Direction changes require explicit user confirmation before applying changes.',
 ];
 
@@ -66,7 +66,8 @@ const REQUIRED_PR_CHECKLIST_SNIPPETS = [
 ];
 
 const REQUIRED_REVIEW_PROMPT_SNIPPETS = [
-  'Enforce cross-session consistency guardian: session handoff must include active architecture contract summary, drift detection must warn before direction changes, and direction changes require explicit user confirmation.',
+  'Review the code with a production-risk mindset.',
+  'Do not invent stack-specific concerns unless the repo or changed files prove they apply.',
 ];
 
 function pushResult(results, isPassed, checkName, details) {
@@ -295,8 +296,8 @@ function parseBooleanFromEnvironment(rawEnvironmentValue) {
 
 function buildArchitectureContract(onboardingReport, corePatterns) {
   return {
-    stack: String(onboardingReport?.selectedStack || 'unknown').trim() || 'unknown',
-    blueprint: String(onboardingReport?.selectedBlueprint || 'unknown').trim() || 'unknown',
+    runtimeDecision: String(onboardingReport?.runtimeDecision?.mode || onboardingReport?.selectedStack || 'unknown').trim() || 'unknown',
+    architectureDecision: String(onboardingReport?.architectureDecision?.mode || onboardingReport?.selectedBlueprint || 'unknown').trim() || 'unknown',
     profile: String(onboardingReport?.selectedProfile || 'unknown').trim() || 'unknown',
     corePatterns: normalizeCorePatterns(corePatterns),
   };
@@ -312,7 +313,7 @@ function toComparableContractValue(value) {
 
 function detectContractDrift(baseContract, targetContract, driftSource) {
   const driftItems = [];
-  const fieldNames = ['stack', 'blueprint', 'profile', 'corePatterns'];
+  const fieldNames = ['runtimeDecision', 'architectureDecision', 'profile', 'corePatterns'];
 
   for (const fieldName of fieldNames) {
     const baseValue = toComparableContractValue(baseContract?.[fieldName]);
@@ -336,7 +337,7 @@ function buildSessionHandoffSummary(architectureContract) {
     ? architectureContract.corePatterns.join(', ')
     : 'none';
 
-  return `Architecture contract summary: stack=${architectureContract.stack}, blueprint=${architectureContract.blueprint}, profile=${architectureContract.profile}, corePatterns=${corePatternsSummary}.`;
+  return `Architecture contract summary: runtimeDecision=${architectureContract.runtimeDecision}, architectureDecision=${architectureContract.architectureDecision}, profile=${architectureContract.profile}, corePatterns=${corePatternsSummary}.`;
 }
 
 function assertSnippetCoverage(sourceLabel, sourcePath, requiredSnippets, failures, results) {
@@ -468,8 +469,8 @@ function runAudit() {
   );
 
   const proposedContract = {
-    stack: parsedArguments.proposedStack || activeContract.stack,
-    blueprint: parsedArguments.proposedBlueprint || activeContract.blueprint,
+    runtimeDecision: parsedArguments.proposedStack || activeContract.runtimeDecision,
+    architectureDecision: parsedArguments.proposedBlueprint || activeContract.architectureDecision,
     profile: activeContract.profile,
     corePatterns: parsedArguments.proposedCorePatterns.length > 0
       ? parsedArguments.proposedCorePatterns
@@ -573,4 +574,4 @@ function runAudit() {
   process.exit(reportPayload.passed ? 0 : 1);
 }
 
-runAudit();
+runAudit();

package/scripts/single-source-lazy-loading-audit.mjs

@@ -76,8 +76,8 @@ const REQUIRED_REVIEW_PROMPT_SNIPPETS = [
 
 const REQUIRED_COMPILER_SNIPPETS = [
   '## LAYER 2 POLICY: LAZY RULE LOADING',
-  'Load stack guidance only when task scope touches that stack.',
-  'Avoid eager loading unrelated stack profiles to prevent instruction conflicts.',
+  'Load runtime-specific guidance only when task scope touches that runtime.',
+  'Avoid eager loading unrelated runtime guidance to prevent instruction conflicts.',
   "stackLoadingMode: 'lazy'",
 ];
 
@@ -532,4 +532,4 @@ function runAudit() {
   process.exit(reportPayload.passed ? 0 : 1);
 }
 
-runAudit();
+runAudit();

package/scripts/sync-thin-adapters.mjs

@@ -45,7 +45,7 @@ If your host stops at this file instead of following the full chain, obey the Cr
 - For UI, UX, layout, screen, tailwind, frontend, or redesign requests: load [.agent-context/prompts/bootstrap-design.md](.agent-context/prompts/bootstrap-design.md) and [.agent-context/rules/frontend-architecture.md](.agent-context/rules/frontend-architecture.md) before editing code.
 - For UI scope: if \`docs/DESIGN.md\` or \`docs/design-intent.json\` is missing, materialize or refine them before implementing UI changes.
 - For refactor, improve, clean up, or fix requests: inspect the active rules and propose a plan before editing.
-- For new project or module requests: propose architecture before generating code.
+- For new project or module requests: clarify constraints, stack decisions, and required docs before generating code.
 - For ecosystem, framework, dependency, or Docker claims: perform live web research instead of relying on stale local heuristics.
 
 ## Mandatory Bootstrap Chain
@@ -57,11 +57,11 @@ If your host stops at this file instead of following the full chain, obey the Cr
 5. Enforce review contracts from [.agent-context/review-checklists/](.agent-context/review-checklists).
 6. Read change-risk maps and continuity state from [.agent-context/state/](.agent-context/state).
 7. Enforce policy thresholds from [.agent-context/policies/](.agent-context/policies).
-8. Use dynamic stack and architecture reasoning from project context docs and live research signals.
+8. Use dynamic stack, structure, and live research signals from project context docs.
 
 ## Trigger Rules
 
-- New project or module requests: propose architecture first and wait for approval.
+- New project or module requests: propose scope, constraints, and required docs first, then wait for approval.
 - Refactor or fix requests: propose plan first, then execute safely.
 - Completion: run [.agent-context/review-checklists/pr-checklist.md](.agent-context/review-checklists/pr-checklist.md) before declaring done.
 
@@ -92,7 +92,7 @@ If your host stops at this file, follow this minimum floor:
 4. Load request templates from [.agent-context/prompts/](../.agent-context/prompts).
 5. Apply review contracts from [.agent-context/review-checklists/](../.agent-context/review-checklists).
 6. Apply state awareness from [.agent-context/state/](../.agent-context/state) and thresholds from [.agent-context/policies/](../.agent-context/policies).
-7. Resolve stack and architecture choices dynamically from project context docs plus live evidence.
+7. Resolve stack, structure, and dependency choices from project context docs plus live evidence.
 
 ## Completion Gate
 
@@ -123,7 +123,7 @@ If your host stops at this file, follow this minimum floor:
 4. Load request templates from [.agent-context/prompts/](../.agent-context/prompts).
 5. Apply review contracts from [.agent-context/review-checklists/](../.agent-context/review-checklists).
 6. Apply state awareness from [.agent-context/state/](../.agent-context/state) and policy thresholds from [.agent-context/policies/](../.agent-context/policies).
-7. Resolve stack and architecture choices dynamically from project context docs plus live evidence.
+7. Resolve stack, structure, and dependency choices from project context docs plus live evidence.
 
 ## Completion Gate
 

package/scripts/ui-design-judge/constants.mjs

@@ -0,0 +1,24 @@
+// @ts-check
+
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export const REPOSITORY_ROOT = resolve(__dirname, '..', '..');
+export const DESIGN_INTENT_PATH = resolve(REPOSITORY_ROOT, 'docs', 'design-intent.json');
+export const DESIGN_GUIDE_PATH = resolve(REPOSITORY_ROOT, 'docs', 'DESIGN.md');
+export const MAX_DIFF_CHARS = 12000;
+export const UI_FILE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.vue', '.css', '.scss', '.sass']);
+export const DESIGN_EXECUTION_REQUIRED_CAPABILITIES = [
+  'requireSurfacePlan',
+  'requireComponentGraph',
+  'requireViewportMutationPlan',
+  'requireInteractionStateMatrix',
+  'requireContentPriorityMap',
+  'requireTaskFlowNarrative',
+  'requireSignatureMoveRationale',
+  'requireStructuredHandoff',
+  'requireRepoEvidenceAlignment',
+];

package/scripts/ui-design-judge/design-execution-summary.mjs

@@ -0,0 +1,259 @@
+// @ts-check
+
+import { existsSync, readFileSync } from 'node:fs';
+import {
+  DESIGN_EXECUTION_REQUIRED_CAPABILITIES,
+  DESIGN_GUIDE_PATH,
+  DESIGN_INTENT_PATH,
+} from './constants.mjs';
+
+export function normalizeStringArray(rawValue) {
+  if (!Array.isArray(rawValue)) {
+    return [];
+  }
+
+  return rawValue
+    .map((entryValue) => String(entryValue || '').trim())
+    .filter(Boolean);
+}
+
+export function loadDesignIntent() {
+  if (!existsSync(DESIGN_INTENT_PATH)) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(readFileSync(DESIGN_INTENT_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function loadDesignGuide() {
+  if (!existsSync(DESIGN_GUIDE_PATH)) {
+    return '';
+  }
+
+  return readFileSync(DESIGN_GUIDE_PATH, 'utf8');
+}
+
+function hasRepoEvidenceSummary(designIntentContent) {
+  return Boolean(
+    designIntentContent?.repoEvidence?.designEvidenceSummary
+    && typeof designIntentContent.repoEvidence.designEvidenceSummary === 'object'
+  );
+}
+
+function hasStructuredInspectionEvidence(designIntentContent) {
+  return Boolean(
+    designIntentContent?.repoEvidence?.designEvidenceSummary?.structuredInspection
+    && typeof designIntentContent.repoEvidence.designEvidenceSummary.structuredInspection === 'object'
+  );
+}
+
+function summarizeDesignExecutionHandoff(designIntentContent) {
+  const designExecutionHandoff = designIntentContent?.designExecutionHandoff
+  && typeof designIntentContent.designExecutionHandoff === 'object'
+    ? designIntentContent.designExecutionHandoff
+    : {};
+
+  const surfacePlan = Array.isArray(designExecutionHandoff.surfacePlan)
+    ? designExecutionHandoff.surfacePlan
+    : [];
+  const componentGraphNodes = Array.isArray(designExecutionHandoff.componentGraph?.nodes)
+    ? designExecutionHandoff.componentGraph.nodes
+    : [];
+  const componentGraphEdges = Array.isArray(designExecutionHandoff.componentGraph?.edges)
+    ? designExecutionHandoff.componentGraph.edges
+    : [];
+  const interactionStateMatrix = Array.isArray(designExecutionHandoff.interactionStateMatrix)
+    ? designExecutionHandoff.interactionStateMatrix
+    : [];
+  const taskFlowNarrative = normalizeStringArray(designExecutionHandoff.taskFlowNarrative);
+  const contentPriorityMap = designExecutionHandoff.contentPriorityMap
+  && typeof designExecutionHandoff.contentPriorityMap === 'object'
+    ? designExecutionHandoff.contentPriorityMap
+    : {};
+  const viewportMutationPlan = designExecutionHandoff.viewportMutationPlan
+  && typeof designExecutionHandoff.viewportMutationPlan === 'object'
+    ? designExecutionHandoff.viewportMutationPlan
+    : {};
+
+  function hasViewportMutationEntry(viewportKey) {
+    const viewportEntry = viewportMutationPlan?.[viewportKey];
+    return Boolean(
+      viewportEntry
+      && typeof viewportEntry === 'object'
+      && String(viewportEntry.primaryOperation || '').trim().length > 0
+      && Array.isArray(viewportEntry.requiredSurfaceActions)
+      && viewportEntry.requiredSurfaceActions.length > 0
+      && Array.isArray(viewportEntry.forbiddenPatterns)
+      && viewportEntry.forbiddenPatterns.length > 0
+    );
+  }
+
+  const artifactChecks = [
+    { name: 'surfacePlan', present: surfacePlan.length > 0 },
+    { name: 'componentGraphNodes', present: componentGraphNodes.length > 1 },
+    { name: 'componentGraphEdges', present: componentGraphEdges.length > 0 },
+    {
+      name: 'contentPriorityMap',
+      present: ['primary', 'secondary', 'deferred'].every((bucketKey) => Array.isArray(contentPriorityMap?.[bucketKey]) && contentPriorityMap[bucketKey].length > 0),
+    },
+    {
+      name: 'viewportMutationPlan',
+      present: ['mobile', 'tablet', 'desktop'].every((viewportKey) => hasViewportMutationEntry(viewportKey)),
+    },
+    { name: 'interactionStateMatrix', present: interactionStateMatrix.length > 0 },
+    { name: 'taskFlowNarrative', present: taskFlowNarrative.length > 1 },
+    { name: 'signatureMoveRationale', present: String(designExecutionHandoff.signatureMoveRationale || '').trim().length > 0 },
+  ];
+
+  const presentArtifacts = artifactChecks.filter((artifactCheck) => artifactCheck.present).map((artifactCheck) => artifactCheck.name);
+  const missingArtifacts = artifactChecks.filter((artifactCheck) => !artifactCheck.present).map((artifactCheck) => artifactCheck.name);
+  const implementationGuardrails = designExecutionHandoff.implementationGuardrails
+  && typeof designExecutionHandoff.implementationGuardrails === 'object'
+    ? designExecutionHandoff.implementationGuardrails
+    : {};
+
+  return {
+    present: Object.keys(designExecutionHandoff).length > 0,
+    version: typeof designExecutionHandoff.version === 'string' ? designExecutionHandoff.version : null,
+    handoffReady: (typeof designExecutionHandoff.version === 'string' && designExecutionHandoff.version === 'ui-handoff-v1')
+      && missingArtifacts.length === 0
+      && implementationGuardrails.requireBuildFromHandoff === true
+      && implementationGuardrails.requireGapNotesBeforeFallback === true
+      && implementationGuardrails.forbidGenericLayoutFallbackWithoutReason === true,
+    artifactCount: presentArtifacts.length,
+    presentArtifacts,
+    missingArtifacts,
+  };
+}
+
+export function summarizeDesignExecutionPolicy(designIntentContent) {
+  const designExecutionPolicy = designIntentContent?.designExecutionPolicy
+  && typeof designIntentContent.designExecutionPolicy === 'object'
+    ? designIntentContent.designExecutionPolicy
+    : {};
+
+  const requiredCapabilities = DESIGN_EXECUTION_REQUIRED_CAPABILITIES.map((capability) => ({
+    name: capability,
+    enabled: designExecutionPolicy[capability] === true,
+  }));
+  const enabledCapabilities = requiredCapabilities
+    .filter((capability) => capability.enabled)
+    .map((capability) => capability.name);
+  const missingCapabilities = requiredCapabilities
+    .filter((capability) => !capability.enabled)
+    .map((capability) => capability.name);
+  const semanticReviewFocus = normalizeStringArray(designExecutionPolicy.semanticReviewFocus);
+  const representationStrategy = typeof designExecutionPolicy.representationStrategy === 'string'
+    ? designExecutionPolicy.representationStrategy
+    : null;
+  const repoEvidenceAvailable = hasRepoEvidenceSummary(designIntentContent);
+  const structuredInspectionAvailable = hasStructuredInspectionEvidence(designIntentContent);
+  const screenshotDependencyForbidden = designExecutionPolicy.forbidScreenshotDependency === true;
+  const handoffFormatVersion = typeof designExecutionPolicy.handoffFormatVersion === 'string'
+    ? designExecutionPolicy.handoffFormatVersion
+    : null;
+  const handoffSummary = summarizeDesignExecutionHandoff(designIntentContent);
+  const policyPresent = Object.keys(designExecutionPolicy).length > 0;
+  const contractReady = policyPresent
+    && representationStrategy === 'surface-plan-v1'
+    && handoffFormatVersion === 'ui-handoff-v1'
+    && missingCapabilities.length === 0
+    && semanticReviewFocus.length >= 4
+    && screenshotDependencyForbidden
+    && handoffSummary.handoffReady
+    && repoEvidenceAvailable;
+
+  const notes = [];
+  if (!policyPresent) {
+    notes.push('designExecutionPolicy is missing from docs/design-intent.json.');
+  }
+  if (representationStrategy !== 'surface-plan-v1') {
+    notes.push('Structured design execution should declare representationStrategy "surface-plan-v1".');
+  }
+  if (handoffFormatVersion !== 'ui-handoff-v1') {
+    notes.push('Structured design execution should declare handoffFormatVersion "ui-handoff-v1".');
+  }
+  if (missingCapabilities.length > 0) {
+    notes.push(`Structured design execution is missing required capabilities: ${missingCapabilities.join(', ')}.`);
+  }
+  if (semanticReviewFocus.length < 4) {
+    notes.push('Structured design execution should declare semantic review focus dimensions before UI implementation review.');
+  }
+  if (!screenshotDependencyForbidden) {
+    notes.push('Structured design execution must explicitly forbid screenshot dependency as a baseline requirement.');
+  }
+  if (!handoffSummary.handoffReady) {
+    notes.push(`Structured design handoff is incomplete: ${handoffSummary.missingArtifacts.join(', ') || 'missing or invalid handoff metadata'}.`);
+  }
+  if (!repoEvidenceAvailable) {
+    notes.push('repoEvidence.designEvidenceSummary is missing or unreadable.');
+  } else if (!structuredInspectionAvailable) {
+    notes.push('repoEvidence.designEvidenceSummary.structuredInspection is missing; class and inline-style evidence will stay lower-confidence.');
+  }
+  if (notes.length === 0) {
+    notes.push('Structured design execution policy is present and ready for contract review.');
+  }
+
+  return {
+    policyPresent,
+    representationStrategy,
+    contractReady,
+    screenshotDependencyForbidden,
+    repoEvidenceAvailable,
+    structuredInspectionAvailable,
+    handoffPresent: handoffSummary.present,
+    handoffVersion: handoffSummary.version,
+    handoffReady: handoffSummary.handoffReady,
+    handoffArtifactCount: handoffSummary.artifactCount,
+    presentHandoffArtifacts: handoffSummary.presentArtifacts,
+    missingHandoffArtifacts: handoffSummary.missingArtifacts,
+    repoEvidenceSummaryVersion: repoEvidenceAvailable
+      ? String(designIntentContent.repoEvidence.designEvidenceSummary.summaryVersion || '')
+      : null,
+    requiredCapabilities: requiredCapabilities.map((capability) => capability.name),
+    enabledCapabilities,
+    missingCapabilities,
+    semanticReviewFocus,
+    notes,
+  };
+}
+
+export function summarizeReviewRubric(designIntentContent) {
+  const reviewRubric = designIntentContent?.reviewRubric && typeof designIntentContent.reviewRubric === 'object'
+    ? designIntentContent.reviewRubric
+    : {};
+
+  const dimensions = Array.isArray(reviewRubric.dimensions)
+    ? reviewRubric.dimensions
+      .map((dimension) => ({
+        key: String(dimension?.key || '').trim(),
+        blockingByDefault: dimension?.blockingByDefault === true,
+        question: String(dimension?.question || '').trim(),
+      }))
+      .filter((dimension) => Boolean(dimension.key))
+    : [];
+
+  return {
+    version: typeof reviewRubric.version === 'string' ? reviewRubric.version : null,
+    dimensions,
+    genericityAutoFail: reviewRubric.genericityAutoFail === true,
+    genericitySignals: normalizeStringArray(reviewRubric.genericitySignals),
+    validBoldSignals: normalizeStringArray(reviewRubric.validBoldSignals),
+    forbiddenPatterns: normalizeStringArray(designIntentContent?.forbiddenPatterns),
+    reportingRules: reviewRubric.reportingRules && typeof reviewRubric.reportingRules === 'object'
+      ? {
+        mustExplainGenericity: reviewRubric.reportingRules.mustExplainGenericity === true,
+        mustSeparateTasteFromFailure: reviewRubric.reportingRules.mustSeparateTasteFromFailure === true,
+        contractFidelityOverridesPersonalTaste: reviewRubric.reportingRules.contractFidelityOverridesPersonalTaste === true,
+      }
+      : {
+        mustExplainGenericity: false,
+        mustSeparateTasteFromFailure: false,
+        contractFidelityOverridesPersonalTaste: false,
+      },
+  };
+}

package/scripts/ui-design-judge/git-input.mjs

@@ -0,0 +1,131 @@
+// @ts-check
+
+import { execSync } from 'node:child_process';
+import { extname } from 'node:path';
+import { REPOSITORY_ROOT, UI_FILE_EXTENSIONS } from './constants.mjs';
+
+export function detectCiProvider() {
+  if (process.env.GITHUB_ACTIONS === 'true') {
+    return 'github';
+  }
+
+  if (process.env.GITLAB_CI === 'true') {
+    return 'gitlab';
+  }
+
+  return 'local';
+}
+
+function collectGitDiff(baseSha, headSha) {
+  const execOptions = {
+    cwd: REPOSITORY_ROOT,
+    encoding: /** @type {'utf-8'} */ ('utf-8'),
+    maxBuffer: 1024 * 1024 * 8,
+  };
+
+  return execSync(`git diff "${baseSha}...${headSha}"`, execOptions);
+}
+
+function collectGitChangedFiles(baseSha, headSha) {
+  const execOptions = {
+    cwd: REPOSITORY_ROOT,
+    encoding: /** @type {'utf-8'} */ ('utf-8'),
+    maxBuffer: 1024 * 1024 * 2,
+  };
+
+  const output = execSync(`git diff --name-only "${baseSha}...${headSha}"`, execOptions);
+  return output
+    .split(/\r?\n/u)
+    .map((filePath) => filePath.trim())
+    .filter(Boolean);
+}
+
+export function collectPullRequestDiff() {
+  if (process.env.PR_DIFF) {
+    return process.env.PR_DIFF;
+  }
+
+  const githubBaseSha = process.env.GITHUB_BASE_SHA;
+  const githubHeadSha = process.env.GITHUB_HEAD_SHA ?? 'HEAD';
+  if (githubBaseSha) {
+    return collectGitDiff(githubBaseSha, githubHeadSha);
+  }
+
+  const gitlabBaseSha = process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA;
+  const gitlabHeadSha = process.env.CI_COMMIT_SHA ?? 'HEAD';
+  if (gitlabBaseSha) {
+    return collectGitDiff(gitlabBaseSha, gitlabHeadSha);
+  }
+
+  try {
+    return execSync('git diff HEAD~1 HEAD', {
+      cwd: REPOSITORY_ROOT,
+      encoding: /** @type {'utf-8'} */ ('utf-8'),
+      maxBuffer: 1024 * 1024 * 8,
+    });
+  } catch {
+    try {
+      const emptyTreeSha = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+      return execSync(`git diff "${emptyTreeSha}" HEAD`, {
+        cwd: REPOSITORY_ROOT,
+        encoding: /** @type {'utf-8'} */ ('utf-8'),
+        maxBuffer: 1024 * 1024 * 8,
+      });
+    } catch {
+      return '';
+    }
+  }
+}
+
+export function collectChangedFiles() {
+  if (process.env.PR_DIFF) {
+    const filePathSet = new Set();
+    for (const diffHeaderMatch of process.env.PR_DIFF.matchAll(/^diff --git a\/(.+?) b\/(.+)$/gm)) {
+      filePathSet.add(diffHeaderMatch[2]);
+    }
+    return Array.from(filePathSet);
+  }
+
+  const githubBaseSha = process.env.GITHUB_BASE_SHA;
+  const githubHeadSha = process.env.GITHUB_HEAD_SHA ?? 'HEAD';
+  if (githubBaseSha) {
+    return collectGitChangedFiles(githubBaseSha, githubHeadSha);
+  }
+
+  const gitlabBaseSha = process.env.CI_MERGE_REQUEST_DIFF_BASE_SHA;
+  const gitlabHeadSha = process.env.CI_COMMIT_SHA ?? 'HEAD';
+  if (gitlabBaseSha) {
+    return collectGitChangedFiles(gitlabBaseSha, gitlabHeadSha);
+  }
+
+  try {
+    const output = execSync('git diff --name-only HEAD~1 HEAD', {
+      cwd: REPOSITORY_ROOT,
+      encoding: /** @type {'utf-8'} */ ('utf-8'),
+      maxBuffer: 1024 * 1024 * 2,
+    });
+    return output.split(/\r?\n/u).map((filePath) => filePath.trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function isUiRelevantFilePath(filePath) {
+  const normalizedFilePath = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+  const fileExtension = extname(normalizedFilePath);
+
+  if (!UI_FILE_EXTENSIONS.has(fileExtension)) {
+    return false;
+  }
+
+  return (
+    normalizedFilePath.startsWith('src/')
+    || normalizedFilePath.startsWith('app/')
+    || normalizedFilePath.startsWith('pages/')
+    || normalizedFilePath.startsWith('components/')
+    || normalizedFilePath.startsWith('styles/')
+    || normalizedFilePath.includes('/components/')
+    || normalizedFilePath.includes('/screens/')
+    || normalizedFilePath.includes('/layouts/')
+  );
+}

package/scripts/ui-design-judge/prompting.mjs

@@ -0,0 +1,73 @@
+// @ts-check
+
+import { MAX_DIFF_CHARS } from './constants.mjs';
+
+export function buildSystemPrompt() {
+  return [
+    'You are a Principal UI/UX Design Reviewer.',
+    'Compare the changed UI code against the provided design contract.',
+    'Treat docs/design-intent.json as the machine-readable source of truth.',
+    'Treat docs/DESIGN.md as explanatory context, not a generic style guide.',
+    'Treat designExecutionPolicy as the execution contract for how the UI must be planned, structured, and reviewed.',
+    'Treat designExecutionHandoff as the explicit bridge between design intent and implementation decisions.',
+    'Treat reviewRubric as the stable scoring frame for distinctiveness, contract fidelity, visual consistency, heuristic UX quality, and motion discipline.',
+    'Use repoEvidence.designEvidenceSummary as implementation evidence when deciding whether the diff follows the intended system.',
+    'Do not reward generic SaaS defaults or popular template patterns.',
+    'Do not penalize originality when the implementation still aligns with the contract.',
+    'Purposeful motion is allowed and can improve quality. Only flag motion when it drifts from the contract, ignores reduced-motion expectations, or adds avoidable performance/accessibility risk.',
+    'Only flag drift when there is a clear mismatch with the contract, accessibility non-negotiables, or cross-viewport adaptation rules.',
+    'Treat WCAG 2.2 AA failures as hard accessibility drift.',
+    'Treat APCA as advisory perceptual tuning only. Do not set blocking solely because APCA indicates a stronger readability adjustment when WCAG hard requirements still pass.',
+    'Check focus visibility, focus appearance, target size, keyboard access, accessible authentication, and status or dynamic state access when the diff touches those surfaces.',
+    'This audit always runs in advisory mode for this repository workflow.',
+    'Focus on color intent, typographic hierarchy, responsive re-layout, purposeful motion, component morphology across states, interaction behavior, and genericity drift.',
+    'If you call something generic, explain the specific genericity signal or anti-pattern that caused that judgment.',
+    'Separate taste from failure. A bold design that follows the contract must not be penalized only because it is unusual.',
+    'Return ONLY one JSON object on a single line prefixed with JSON_VERDICT:.',
+    'Schema:',
+    '{"alignmentScore": number|null, "genericityAssessment": {"status": "distinctive|mixed|generic|unclear", "reason": string}, "tasteVsFailureSeparated": boolean, "rubricBreakdown": [{"dimension": string, "score": number|null, "verdict": "strong|acceptable|weak|unclear", "reason": string, "blocking": boolean}], "notes": string[], "findings": [{"area": string, "severity": "high|medium|low", "problem": string, "evidence": string, "requiredAction": string, "blockingRecommended": boolean}]}',
+  ].join('\n');
+}
+
+export function buildUserMessage(designIntentContent, designGuideContent, diffContent, changedUiFiles, designExecutionSummary) {
+  const truncatedDiff = diffContent.length > MAX_DIFF_CHARS
+    ? `${diffContent.slice(0, MAX_DIFF_CHARS)}\n\n[DIFF TRUNCATED - ${diffContent.length - MAX_DIFF_CHARS} additional characters omitted]`
+    : diffContent;
+
+  return [
+    '## Changed UI Files',
+    changedUiFiles.length > 0 ? changedUiFiles.map((filePath) => `- ${filePath}`).join('\n') : '- none',
+    '',
+    '## design-intent.json',
+    '```json',
+    JSON.stringify(designIntentContent, null, 2),
+    '```',
+    '',
+    '## Review Rubric',
+    '```json',
+    JSON.stringify(designIntentContent?.reviewRubric || null, null, 2),
+    '```',
+    '',
+    '## Structured Design Handoff',
+    '```json',
+    JSON.stringify(designIntentContent?.designExecutionHandoff || null, null, 2),
+    '```',
+    '',
+    '## DESIGN.md',
+    '```md',
+    designGuideContent.trim() || '(missing DESIGN.md)',
+    '```',
+    '',
+    '## Structured Design Execution Summary',
+    '```json',
+    JSON.stringify(designExecutionSummary, null, 2),
+    '```',
+    '',
+    '## UI Diff',
+    '```diff',
+    truncatedDiff.trim() || '(no UI diff)',
+    '```',
+    '',
+    'Judge alignment to the contract. Avoid aesthetic bias toward generic web trends or toward motionless/static outputs.',
+  ].join('\n');
+}