@ryuenn3123/agentic-senior-core 2.5.14 → 2.5.15

package/.agent-context/prompts/review-code.md

@@ -18,6 +18,7 @@ Use these checklists:
 5. Enforce documentation hard blockers on changed boundaries: public surface changes, API contract changes, and database structure changes must include synchronized documentation updates.
 6. Enforce context-triggered strict audits: review requests, PR-intent workflows, and major feature completion must run strict security and performance audits; small edits stay lightweight unless strict mode is explicitly forced.
 7. 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.
+8. Enforce explain-on-demand state visibility: default responses must avoid unnecessary state-file internals, state internals are exposed only on explicit request, and diagnostic mode must explain relevant state decisions when needed.
 
 For EVERY violation found:
 - State the exact file and line

package/.agent-context/review-checklists/frontend-excellence-rubric.md

@@ -38,12 +38,22 @@ Release recommendation:
 - [ ] Breakpoint transitions preserve hierarchy, spacing rhythm, and action clarity.
 - [ ] Navigation and key CTA remain explicit across viewport sizes.
 
-## 6. UX Narrative and Conversion Clarity
+## 6. Language and Content Consistency
+- [ ] Content language is consistent across headline, body, CTA, and system messages for the same screen flow.
+- [ ] Mixed-language output appears only when requested by user or product requirement.
+- [ ] Terminology stays stable for repeated actions and labels.
+
+## 7. Text Contrast and Collision Safety
+- [ ] Text-to-background contrast is checked for every semantic token pair used in UI.
+- [ ] No text color clashes with gradients, images, or accent surfaces.
+- [ ] Primary and secondary text remain readable in all supported breakpoints.
+
+## 8. UX Narrative and Conversion Clarity
 - [ ] First viewport communicates value proposition and primary action immediately.
 - [ ] Error, empty, and loading states provide clear next actions.
 - [ ] User journey avoids dead ends and hidden critical actions.
 
-## 7. Template Diversity and Originality
+## 9. Template Diversity and Originality
 - [ ] Output is not a copy of a generic starter template or repeated AI layout pattern.
 - [ ] Layout composition shows intentional variation in structure and hierarchy.
 - [ ] Visual intent, interaction quality, and conversion clarity are all explicitly reviewed together.

package/.agent-context/review-checklists/frontend-usability.md

@@ -6,6 +6,7 @@ Run this checklist before claiming frontend work is production-ready.
 - [ ] Typography scale is consistent and tokenized.
 - [ ] Color usage follows design tokens and avoids ad-hoc values.
 - [ ] Spacing and layout rhythm is coherent across pages.
+- [ ] Language and terminology stay consistent across headline, body, and CTA for the same flow.
 
 ## 2. Responsiveness
 - [ ] Core pages are usable at mobile, tablet, and desktop breakpoints.

package/.agent-context/review-checklists/pr-checklist.md

@@ -119,3 +119,8 @@ VERDICT: PASS / FAIL (X/Y items passed)
 - [ ] Session handoff includes active architecture contract summary
 - [ ] Drift detection warns before direction changes
 - [ ] Direction changes require explicit user confirmation
+
+### 13. Invisible State Management (Explain-on-Demand)
+- [ ] Default responses avoid unnecessary state-file internals
+- [ ] State internals are exposed only on explicit request
+- [ ] Diagnostic mode can explain relevant state decisions when needed

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

@@ -23,6 +23,15 @@ These guardrails are mandatory to preserve architecture direction across session
 - Direction changes require explicit user confirmation before applying changes.
 - When confirmation is provided, record the rationale in session notes or PR context.
 
+## Invisible State Management with Explain-on-Demand
+
+State internals must stay invisible by default.
+
+- Default responses must avoid unnecessary state-file internals.
+- State internals are exposed only on explicit user request.
+- Diagnostic mode explains relevant state decisions when needed.
+- Keep default explanations concise and outcome-first; show raw state details only in diagnostic mode.
+
 ## The Core Principle
 
 **Every layer has ONE job. Layer leaks are bugs — not "pragmatic shortcuts."**

package/.agent-context/rules/frontend-architecture.md

@@ -16,6 +16,13 @@ Mandatory behavior when triggered:
 - score and review generated UI work against visual intent, interaction quality, and conversion clarity
 - reject template-only repetitive outputs and force a distinct layout direction
 
+## UI Consistency Guardrails (Mandatory)
+
+- Content language must stay consistent per screen and flow unless user requests multilingual output.
+- Text color must remain contrast-safe against its background; no color collisions.
+- Layout must avoid overlap, clipped text, and misaligned key actions across breakpoints.
+- Keep spacing and positioning token-driven so repeated outputs stay stable.
+
 ## 1. File Structure (Feature-Driven Design)
 Organize your application by feature domain, not by file type.
 - **BANNED:** Monolithic directories like `/components` (with 500 files), `/hooks`, `/api`.

package/.agent-context/state/memory-continuity-benchmark.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-17T12:51:43.241Z",
+  "generatedAt": "2026-04-17T13:21:48.914Z",
   "reportName": "memory-continuity-benchmark",
   "schemaVersion": "1.0.0",
   "passed": true,

package/.cursorrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.5.14
+Generated by Agentic-Senior-Core CLI v2.5.15
 Timestamp: 2026-04-15T00:14:51.184Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/.windsurfrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v2.5.14
+Generated by Agentic-Senior-Core CLI v2.5.15
 Timestamp: 2026-04-15T00:14:51.184Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "2.5.14",
+  "version": "2.5.15",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -46,6 +46,7 @@
     "audit:documentation-boundary": "node ./scripts/documentation-boundary-audit.mjs",
     "audit:context-triggered": "node ./scripts/context-triggered-audit.mjs",
     "audit:rules-guardian": "node ./scripts/rules-guardian-audit.mjs",
+    "audit:explain-on-demand": "node ./scripts/explain-on-demand-audit.mjs",
     "gate:release": "node ./scripts/release-gate.mjs && node ./scripts/forbidden-content-check.mjs",
     "prepublishOnly": "npm run gate:release",
     "sbom:generate": "node ./scripts/generate-sbom.mjs",

package/scripts/explain-on-demand-audit.mjs

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+
+/**
+ * explain-on-demand-audit.mjs
+ *
+ * Enforces invisible state management defaults and explicit diagnostic
+ * visibility rules for state internals.
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const REPOSITORY_ROOT = resolve(__dirname, '..');
+
+const ONBOARDING_REPORT_PATH = '.agent-context/state/onboarding-report.json';
+const ARCHITECTURE_RULE_PATH = '.agent-context/rules/architecture.md';
+const PR_CHECKLIST_PATH = '.agent-context/review-checklists/pr-checklist.md';
+const REVIEW_PROMPT_PATH = '.agent-context/prompts/review-code.md';
+
+const DEFAULT_MODE = 'default';
+const SUPPORTED_MODES = new Set([DEFAULT_MODE, 'diagnostic']);
+const DEFAULT_WORKFLOW = 'standard';
+
+const REQUIRED_ARCHITECTURE_RULE_SNIPPETS = [
+  '## Invisible State Management with Explain-on-Demand',
+  'Default responses must avoid unnecessary state-file internals.',
+  'State internals are exposed only on explicit user request.',
+  'Diagnostic mode explains relevant state decisions when needed.',
+];
+
+const REQUIRED_PR_CHECKLIST_SNIPPETS = [
+  'Default responses avoid unnecessary state-file internals',
+  'State internals are exposed only on explicit request',
+  'Diagnostic mode can explain relevant state decisions when needed',
+];
+
+const REQUIRED_REVIEW_PROMPT_SNIPPETS = [
+  'Enforce explain-on-demand state visibility: default responses must avoid unnecessary state-file internals, state internals are exposed only on explicit request, and diagnostic mode must explain relevant state decisions when needed.',
+];
+
+const INTERNAL_STATE_SIGNAL_PATTERNS = [
+  /\.agent-context\/state\//i,
+  /\bautoDetection\b/i,
+  /\brankedCandidates\b/i,
+  /\bconfidenceGap\b/i,
+  /\bschemaVersion\b/i,
+];
+
+function pushResult(results, isPassed, checkName, details) {
+  results.push({
+    checkName,
+    passed: isPassed,
+    details,
+  });
+}
+
+function normalizeFilePath(filePath) {
+  return filePath.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function parseGitFileList(rawOutput) {
+  if (typeof rawOutput !== 'string' || rawOutput.trim().length === 0) {
+    return [];
+  }
+
+  return rawOutput
+    .split(/\r?\n/)
+    .map((filePath) => filePath.trim())
+    .filter((filePath) => filePath.length > 0)
+    .map(normalizeFilePath);
+}
+
+function runGitFileQuery(commandArguments) {
+  try {
+    const rawOutput = execFileSync('git', commandArguments, {
+      cwd: REPOSITORY_ROOT,
+      encoding: 'utf8',
+      maxBuffer: 1024 * 1024,
+    });
+
+    return parseGitFileList(rawOutput);
+  } catch {
+    return [];
+  }
+}
+
+function uniqueSorted(filePaths) {
+  return Array.from(new Set(filePaths)).sort((leftPath, rightPath) => leftPath.localeCompare(rightPath));
+}
+
+function collectChangedFiles() {
+  const workingTreeFiles = runGitFileQuery(['diff', '--name-only']);
+  const stagedFiles = runGitFileQuery(['diff', '--name-only', '--cached']);
+  const workingScopeFiles = uniqueSorted([...workingTreeFiles, ...stagedFiles]);
+
+  if (workingScopeFiles.length > 0) {
+    return {
+      source: 'working-tree-and-index',
+      files: workingScopeFiles,
+    };
+  }
+
+  const latestCommitRangeFiles = runGitFileQuery(['diff', '--name-only', 'HEAD~1..HEAD']);
+  if (latestCommitRangeFiles.length > 0) {
+    return {
+      source: 'latest-commit-range',
+      files: uniqueSorted(latestCommitRangeFiles),
+    };
+  }
+
+  const headCommitFiles = runGitFileQuery(['show', '--pretty=format:', '--name-only', 'HEAD']);
+  if (headCommitFiles.length > 0) {
+    return {
+      source: 'head-commit',
+      files: uniqueSorted(headCommitFiles),
+    };
+  }
+
+  return {
+    source: 'none',
+    files: [],
+  };
+}
+
+function readText(relativeFilePath) {
+  const absolutePath = resolve(REPOSITORY_ROOT, relativeFilePath);
+  if (!existsSync(absolutePath)) {
+    return '';
+  }
+
+  return readFileSync(absolutePath, 'utf8');
+}
+
+function parseOnboardingReport(onboardingReportContent) {
+  if (typeof onboardingReportContent !== 'string' || onboardingReportContent.trim().length === 0) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(onboardingReportContent);
+  } catch {
+    return null;
+  }
+}
+
+function parseCliArguments(argumentList) {
+  let mode = DEFAULT_MODE;
+  let workflow = DEFAULT_WORKFLOW;
+  let explicitStateRequest = false;
+
+  for (let argumentIndex = 0; argumentIndex < argumentList.length; argumentIndex += 1) {
+    const argumentValue = argumentList[argumentIndex];
+
+    if (argumentValue === '--state-debug') {
+      explicitStateRequest = true;
+      continue;
+    }
+
+    if (argumentValue === '--mode') {
+      const nextArgumentValue = argumentList[argumentIndex + 1];
+      if (nextArgumentValue && !nextArgumentValue.startsWith('--')) {
+        mode = nextArgumentValue;
+        argumentIndex += 1;
+      }
+      continue;
+    }
+
+    if (argumentValue.startsWith('--mode=')) {
+      mode = argumentValue.slice('--mode='.length);
+      continue;
+    }
+
+    if (argumentValue === '--workflow') {
+      const nextArgumentValue = argumentList[argumentIndex + 1];
+      if (nextArgumentValue && !nextArgumentValue.startsWith('--')) {
+        workflow = nextArgumentValue;
+        argumentIndex += 1;
+      }
+      continue;
+    }
+
+    if (argumentValue.startsWith('--workflow=')) {
+      workflow = argumentValue.slice('--workflow='.length);
+    }
+  }
+
+  const normalizedMode = String(mode || '').trim().toLowerCase();
+
+  return {
+    mode: SUPPORTED_MODES.has(normalizedMode) ? normalizedMode : DEFAULT_MODE,
+    workflow: String(workflow || '').trim().toLowerCase() || DEFAULT_WORKFLOW,
+    explicitStateRequest,
+  };
+}
+
+function assertSnippetCoverage(sourceLabel, sourcePath, requiredSnippets, failures, results) {
+  const sourceContent = readText(sourcePath);
+
+  if (!sourceContent) {
+    failures.push(`Missing ${sourceLabel} source: ${sourcePath}`);
+    pushResult(results, false, `${sourceLabel}-source-exists`, `Missing ${sourcePath}`);
+    return;
+  }
+
+  pushResult(results, true, `${sourceLabel}-source-exists`, `${sourcePath} is present`);
+
+  const missingSnippets = requiredSnippets.filter((requiredSnippet) => !sourceContent.includes(requiredSnippet));
+
+  if (missingSnippets.length > 0) {
+    failures.push(`Missing ${sourceLabel} snippets: ${missingSnippets.join(', ')}`);
+    pushResult(
+      results,
+      false,
+      `${sourceLabel}-source-coverage`,
+      `Missing snippets in ${sourcePath}: ${missingSnippets.join(', ')}`
+    );
+    return;
+  }
+
+  pushResult(results, true, `${sourceLabel}-source-coverage`, `${sourceLabel} snippets are complete`);
+}
+
+function buildDefaultResponseSummary(onboardingReport) {
+  const selectedStack = String(onboardingReport?.selectedStack || 'unknown-stack').trim() || 'unknown-stack';
+  const selectedBlueprint = String(onboardingReport?.selectedBlueprint || 'unknown-blueprint').trim() || 'unknown-blueprint';
+  const selectedProfile = String(onboardingReport?.selectedProfile || 'unknown-profile').trim() || 'unknown-profile';
+
+  return `Active setup summary: stack=${selectedStack}, blueprint=${selectedBlueprint}, profile=${selectedProfile}.`;
+}
+
+function detectInternalSignals(textValue) {
+  const normalizedText = String(textValue || '');
+  return INTERNAL_STATE_SIGNAL_PATTERNS.some((signalPattern) => signalPattern.test(normalizedText));
+}
+
+function buildDiagnosticDecisionSummaries(onboardingReport) {
+  const explanations = [];
+
+  const selectedStack = String(onboardingReport?.selectedStack || '').trim();
+  if (selectedStack) {
+    explanations.push(`Stack decision: selectedStack=${selectedStack}.`);
+  }
+
+  const selectedBlueprint = String(onboardingReport?.selectedBlueprint || '').trim();
+  if (selectedBlueprint) {
+    explanations.push(`Blueprint decision: selectedBlueprint=${selectedBlueprint}.`);
+  }
+
+  const selectedProfile = String(onboardingReport?.selectedProfile || '').trim();
+  if (selectedProfile) {
+    explanations.push(`Profile decision: selectedProfile=${selectedProfile}.`);
+  }
+
+  const detectionReasoning = String(onboardingReport?.autoDetection?.detectionReasoning || '').trim();
+  if (detectionReasoning) {
+    explanations.push(`Detection reasoning: ${detectionReasoning}`);
+  }
+
+  if (typeof onboardingReport?.ciGuardrailsEnabled === 'boolean') {
+    explanations.push(`CI guardrails decision: ciGuardrailsEnabled=${String(onboardingReport.ciGuardrailsEnabled)}.`);
+  }
+
+  return explanations;
+}
+
+function runAudit() {
+  const parsedArguments = parseCliArguments(process.argv.slice(2));
+  const changedScope = collectChangedFiles();
+  const changedFiles = changedScope.files;
+  const results = [];
+  const failures = [];
+  const warnings = [];
+
+  pushResult(results, true, 'context-workflow', `workflow=${parsedArguments.workflow}`);
+  pushResult(results, true, 'explain-mode', `mode=${parsedArguments.mode}`);
+  pushResult(
+    results,
+    true,
+    'state-debug-explicit-request',
+    parsedArguments.explicitStateRequest
+      ? 'Explicit state diagnostic request received'
+      : 'No explicit state diagnostic request provided'
+  );
+
+  assertSnippetCoverage(
+    'explain-on-demand-architecture-rule',
+    ARCHITECTURE_RULE_PATH,
+    REQUIRED_ARCHITECTURE_RULE_SNIPPETS,
+    failures,
+    results
+  );
+
+  assertSnippetCoverage(
+    'explain-on-demand-pr-checklist',
+    PR_CHECKLIST_PATH,
+    REQUIRED_PR_CHECKLIST_SNIPPETS,
+    failures,
+    results
+  );
+
+  assertSnippetCoverage(
+    'explain-on-demand-review-prompt',
+    REVIEW_PROMPT_PATH,
+    REQUIRED_REVIEW_PROMPT_SNIPPETS,
+    failures,
+    results
+  );
+
+  const onboardingReportContent = readText(ONBOARDING_REPORT_PATH);
+  const onboardingReport = parseOnboardingReport(onboardingReportContent);
+
+  if (!onboardingReportContent) {
+    failures.push(`Missing state source: ${ONBOARDING_REPORT_PATH}`);
+    pushResult(results, false, 'state-source', `Missing ${ONBOARDING_REPORT_PATH}`);
+  } else if (!onboardingReport) {
+    failures.push(`Invalid state source JSON: ${ONBOARDING_REPORT_PATH}`);
+    pushResult(results, false, 'state-source', `Cannot parse ${ONBOARDING_REPORT_PATH}`);
+  } else {
+    pushResult(results, true, 'state-source', `${ONBOARDING_REPORT_PATH} is present and valid`);
+  }
+
+  const defaultResponseSummary = buildDefaultResponseSummary(onboardingReport);
+  const defaultModeExposesStateInternals = detectInternalSignals(defaultResponseSummary);
+
+  if (defaultModeExposesStateInternals) {
+    failures.push('Default response exposes state internals');
+    pushResult(
+      results,
+      false,
+      'default-response-invisible-state',
+      'Default response leaks internal state details'
+    );
+  } else {
+    pushResult(
+      results,
+      true,
+      'default-response-invisible-state',
+      'Default response avoids unnecessary state-file internals'
+    );
+  }
+
+  const diagnosticDecisionSummaries = buildDiagnosticDecisionSummaries(onboardingReport);
+  const canExplainStateDecisions = diagnosticDecisionSummaries.length > 0;
+
+  if (parsedArguments.mode === 'diagnostic' && !parsedArguments.explicitStateRequest) {
+    failures.push('Diagnostic mode requested without explicit state request');
+    pushResult(
+      results,
+      false,
+      'diagnostic-explicit-request-gate',
+      'Diagnostic mode requires explicit request. Re-run with --state-debug when user asks for state-level details.'
+    );
+  } else {
+    pushResult(
+      results,
+      true,
+      'diagnostic-explicit-request-gate',
+      parsedArguments.mode === 'diagnostic'
+        ? 'Diagnostic mode is explicitly requested and permitted'
+        : 'Diagnostic mode not requested; default hidden-state behavior applies'
+    );
+  }
+
+  if (!canExplainStateDecisions) {
+    failures.push('Diagnostic mode cannot explain relevant state decisions');
+    pushResult(
+      results,
+      false,
+      'diagnostic-explain-state-decisions',
+      'No state decision explanations available'
+    );
+  } else {
+    pushResult(
+      results,
+      true,
+      'diagnostic-explain-state-decisions',
+      `Diagnostic mode can explain ${diagnosticDecisionSummaries.length} state decision points`
+    );
+  }
+
+  if (parsedArguments.mode === 'default' && parsedArguments.explicitStateRequest) {
+    warnings.push('Explicit state request was provided in default mode; internal state details remain hidden unless diagnostic mode is selected.');
+  }
+
+  const reportPayload = {
+    generatedAt: new Date().toISOString(),
+    auditName: 'explain-on-demand-audit',
+    workflow: parsedArguments.workflow,
+    mode: parsedArguments.mode,
+    source: changedScope.source,
+    changedFileCount: changedFiles.length,
+    changedFiles,
+    responsePolicy: {
+      defaultModeExposesStateInternals,
+      diagnosticRequiresExplicitRequest: true,
+      explicitStateRequestReceived: parsedArguments.explicitStateRequest,
+    },
+    defaultResponse: {
+      summary: defaultResponseSummary,
+      containsStateInternals: defaultModeExposesStateInternals,
+    },
+    diagnosticMode: {
+      requested: parsedArguments.mode === 'diagnostic',
+      allowed: parsedArguments.mode !== 'diagnostic' || parsedArguments.explicitStateRequest,
+      canExplainStateDecisions,
+      stateDecisionExplanations: parsedArguments.mode === 'diagnostic' && parsedArguments.explicitStateRequest
+        ? diagnosticDecisionSummaries
+        : [],
+      availableDecisionCount: diagnosticDecisionSummaries.length,
+    },
+    passed: failures.length === 0,
+    failureCount: failures.length,
+    failures,
+    warnings,
+    results,
+  };
+
+  console.log(JSON.stringify(reportPayload, null, 2));
+  process.exit(reportPayload.passed ? 0 : 1);
+}
+
+runAudit();

package/scripts/frontend-usability-audit.mjs

@@ -44,6 +44,8 @@ const REQUIRED_EXCELLENCE_RUBRIC_SNIPPETS = [
   'Typography Quality',
   'Color System Diversity and Contrast',
   'Interaction Choreography',
+  'Language and Content Consistency',
+  'Text Contrast and Collision Safety',
   'UX Narrative and Conversion Clarity',
   'Template Diversity and Originality',
   'Low-Diversity Template Output Policy',
@@ -55,6 +57,9 @@ const REQUIRED_FRONTEND_RULE_SNIPPETS = [
   'UI scope trigger signals',
   'visual intent, interaction quality, and conversion clarity',
   'template-only repetitive outputs',
+  'UI Consistency Guardrails (Mandatory)',
+  'Content language must stay consistent per screen and flow unless user requests multilingual output.',
+  'Text color must remain contrast-safe against its background; no color collisions.',
 ];
 
 function assertFileExists(relativeFilePath, failures) {

package/scripts/release-gate.mjs

@@ -33,6 +33,7 @@ const FRONTEND_AUDIT_SCRIPT_PATH = 'scripts/frontend-usability-audit.mjs';
 const DOCUMENTATION_BOUNDARY_AUDIT_SCRIPT_PATH = 'scripts/documentation-boundary-audit.mjs';
 const CONTEXT_TRIGGERED_AUDIT_SCRIPT_PATH = 'scripts/context-triggered-audit.mjs';
 const RULES_GUARDIAN_AUDIT_SCRIPT_PATH = 'scripts/rules-guardian-audit.mjs';
+const EXPLAIN_ON_DEMAND_AUDIT_SCRIPT_PATH = 'scripts/explain-on-demand-audit.mjs';
 const BACKEND_ARCHITECTURE_RULE_PATH = '.agent-context/rules/architecture.md';
 const BACKEND_REVIEW_CHECKLIST_PATH = '.agent-context/review-checklists/pr-checklist.md';
 const REFACTOR_PROMPT_PATH = '.agent-context/prompts/refactor.md';
@@ -63,6 +64,8 @@ const REQUIRED_FRONTEND_EXCELLENCE_RUBRIC_SNIPPETS = [
   'Typography Quality',
   'Color System Diversity and Contrast',
   'Interaction Choreography',
+  'Language and Content Consistency',
+  'Text Contrast and Collision Safety',
   'UX Narrative and Conversion Clarity',
   'Template Diversity and Originality',
   'Low-Diversity Template Output Policy',
@@ -509,6 +512,99 @@ function runReleaseGate() {
     }
   }
 
+  const explainOnDemandAuditExecution = runMachineReadableScript(
+    EXPLAIN_ON_DEMAND_AUDIT_SCRIPT_PATH,
+    ['--mode', 'default', '--workflow', 'pr-preparation']
+  );
+  if (!explainOnDemandAuditExecution.report) {
+    const failureDetails = explainOnDemandAuditExecution.executionErrorMessage
+      ? `Explain-on-demand audit execution failed before producing a machine-readable report: ${explainOnDemandAuditExecution.executionErrorMessage}`
+      : 'Explain-on-demand audit did not produce machine-readable JSON output';
+    pushResult(results, false, 'explain-on-demand-audit', failureDetails);
+  } else {
+    diagnostics.explainOnDemandAudit = explainOnDemandAuditExecution.report;
+    pushResult(
+      results,
+      true,
+      'explain-on-demand-audit',
+      `explain-on-demand-audit executed (passed=${explainOnDemandAuditExecution.report.passed}, mode=${explainOnDemandAuditExecution.report.mode}, failures=${explainOnDemandAuditExecution.report.failureCount})`
+    );
+
+    const defaultHiddenStatePolicyPassed = explainOnDemandAuditExecution.report?.responsePolicy?.defaultModeExposesStateInternals === false
+      && explainOnDemandAuditExecution.report?.defaultResponse?.containsStateInternals === false;
+
+    if (defaultHiddenStatePolicyPassed) {
+      pushResult(
+        results,
+        true,
+        'explain-on-demand-default-hidden-state',
+        'Default response mode hides unnecessary state-file internals'
+      );
+    } else {
+      pushResult(
+        results,
+        false,
+        'explain-on-demand-default-hidden-state',
+        'Default response mode exposes state internals or visibility flags are inconsistent'
+      );
+    }
+
+    const diagnosticExplicitRequestPolicyPassed = explainOnDemandAuditExecution.report?.responsePolicy?.diagnosticRequiresExplicitRequest === true;
+
+    if (diagnosticExplicitRequestPolicyPassed) {
+      pushResult(
+        results,
+        true,
+        'explain-on-demand-explicit-request-gate',
+        'State internals are gated behind explicit diagnostic request'
+      );
+    } else {
+      pushResult(
+        results,
+        false,
+        'explain-on-demand-explicit-request-gate',
+        'Explain-on-demand policy does not require explicit diagnostic request'
+      );
+    }
+
+    const diagnosticExplainabilityPassed = explainOnDemandAuditExecution.report?.diagnosticMode?.canExplainStateDecisions === true;
+
+    if (diagnosticExplainabilityPassed) {
+      pushResult(
+        results,
+        true,
+        'explain-on-demand-diagnostic-explainability',
+        'Diagnostic mode can explain relevant state decisions when requested'
+      );
+    } else {
+      pushResult(
+        results,
+        false,
+        'explain-on-demand-diagnostic-explainability',
+        'Explain-on-demand audit cannot provide diagnostic state decision explanations'
+      );
+    }
+
+    if (explainOnDemandAuditExecution.report.passed === true) {
+      pushResult(
+        results,
+        true,
+        'explain-on-demand-hard-rule',
+        'Explain-on-demand hard-rule passed'
+      );
+    } else {
+      const failedAuditDetails = Array.isArray(explainOnDemandAuditExecution.report.failures)
+        ? explainOnDemandAuditExecution.report.failures.join('; ')
+        : 'Unknown explain-on-demand audit failures';
+      pushResult(
+        results,
+        false,
+        'explain-on-demand-hard-rule',
+        `Explain-on-demand audit failed: ${failedAuditDetails}`
+      );
+    }
+  }
+
   const frontendParityChecklistContent = readText(FRONTEND_PARITY_CHECKLIST_PATH);
   if (!frontendParityChecklistContent) {
     pushResult(results, false, 'frontend-parity-checklist-exists', `Missing ${FRONTEND_PARITY_CHECKLIST_PATH}`);

package/scripts/validate.mjs

@@ -174,6 +174,7 @@ async function validateRequiredFiles() {
     'scripts/documentation-boundary-audit.mjs',
     'scripts/context-triggered-audit.mjs',
     'scripts/rules-guardian-audit.mjs',
+    'scripts/explain-on-demand-audit.mjs',
     'scripts/release-gate.mjs',
     'scripts/generate-sbom.mjs',
     'scripts/init-project.sh',