@ryuenn3123/agentic-senior-core 4.3.2 → 4.3.4

package/scripts/validate.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// @file-size-exception: Pre-existing 600 LOC main validator orchestrator; planned for split in Phase 1 governance refactor.
+// Phase 1 governance refactor completed: monolithic script split into modular sub-files.
 /**
  * validate.mjs — Repository Integrity Validator
  *
@@ -42,6 +42,23 @@ import {
   validateUniversalSopConsolidationCoverage,
   validateUpgradeUiContractWarningCoverage,
 } from './validate/coverage-checks.mjs';
+import {
+  validateRequiredFiles,
+  validateRuleFiles,
+  validateChecklistConsolidation,
+} from './validate/file-structure.mjs';
+import {
+  validateMarkdownFiles,
+  validateCrossReferences,
+  validateAgentsManifest,
+  validateDocumentationFlow,
+} from './validate/markdown-content.mjs';
+import {
+  validatePackageMetadata,
+  validatePolicyFile,
+  validateVersionConsistency,
+  validateMcpConfiguration,
+} from './validate/project-metadata.mjs';
 
 const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
 const ROOT_DIR = resolve(dirname(SCRIPT_FILE_PATH), '..');
@@ -128,390 +145,6 @@ function normalizeLineEndings(content) {
   return content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
 }
 
-async function validateRequiredFiles() {
-  console.log('\nChecking required files...');
-
-  const requiredFiles = [
-    'bin/agentic-senior-core.js',
-    'scripts/validate.mjs',
-    'scripts/llm-judge.mjs',
-    'scripts/detection-benchmark.mjs',
-    'scripts/benchmark-evidence-bundle.mjs',
-    'scripts/benchmark-writer-judge-matrix.mjs',
-    'scripts/benchmark-gate.mjs',
-    'scripts/benchmark-intelligence.mjs',
-    'scripts/memory-continuity-benchmark.mjs',
-    'scripts/docs-quality-drift-report.mjs',
-    'scripts/governance-weekly-report.mjs',
-    'scripts/mcp-server.mjs',
-    'scripts/mcp-server/constants.mjs',
-    'scripts/mcp-server/tool-registry.mjs',
-    'scripts/mcp-server/tools.mjs',
-    'scripts/frontend-usability-audit.mjs',
-    'scripts/ui-design-judge.mjs',
-    'scripts/documentation-boundary-audit.mjs',
-    'scripts/context-triggered-audit.mjs',
-    'scripts/rules-guardian-audit.mjs',
-    'scripts/explain-on-demand-audit.mjs',
-    'scripts/single-source-lazy-loading-audit.mjs',
-    'scripts/audit-cache-layer-contract.mjs',
-    'scripts/audit-typography-palette-anti-repeat.mjs',
-    'lib/cli/audits/typography-palette-anti-repeat-audit.mjs',
-    'lib/cli/commands/audit-design-anti-repeat.mjs',
-    'scripts/sync-thin-adapters.mjs',
-    'scripts/release-gate.mjs',
-    'scripts/generate-sbom.mjs',
-    '.agent-context/policies/llm-judge-threshold.json',
-    '.agent-context/prompts/compact-natural-mode.md',
-    '.agent-context/prompts/research-design.md',
-    'mcp.json',
-    'AGENTS.md',
-    'CLAUDE.md',
-    'GEMINI.md',
-    'README.md',
-    'CHANGELOG.md',
-    'docs/doc-index.md',
-    'docs/project-brief.md',
-    'docs/flow-overview.md',
-    'docs/api-contract.md',
-    'docs/faq.md',
-    'docs/deep-dive.md',
-    'docs/archive/HISTORY.md',
-    'docs/archive/CHANGELOG-archive.md',
-    '.agent-context/state/benchmark-reproducibility.json',
-    '.agent-context/state/benchmark-writer-judge-config.json',
-    '.agent-context/state/memory-schema-v1.json',
-    '.agent-context/state/memory-adapter-contract.json',
-    '.vscode/mcp.json',
-    '.github/workflows/release-gate.yml',
-    '.github/workflows/sbom-compliance.yml',
-    '.github/workflows/benchmark-intelligence.yml',
-    '.github/workflows/docs-quality-drift-report.yml',
-    '.github/workflows/governance-weekly-report.yml',
-    'tests/cli-smoke.test.mjs',
-    'tests/mcp-server.test.mjs',
-    'tests/llm-judge.test.mjs',
-    'tests/operations.test.mjs',
-    'LICENSE',
-    '.gitignore',
-  ];
-
-  for (const requiredFilePath of requiredFiles) {
-    const absoluteRequiredFilePath = join(ROOT_DIR, requiredFilePath);
-
-    if (await fileExists(absoluteRequiredFilePath)) {
-      pass(requiredFilePath);
-      continue;
-    }
-
-    fail(`Missing required file: ${requiredFilePath}`);
-  }
-}
-
-async function validateMarkdownFiles() {
-  console.log('\nChecking markdown content...');
-
-  const markdownFilePaths = await collectFiles(ROOT_DIR, (fileName) => fileName.endsWith('.md'));
-
-  for (const markdownFilePath of markdownFilePaths) {
-    const markdownContent = await readTextFile(markdownFilePath);
-    const relativeMarkdownPath = relative(ROOT_DIR, markdownFilePath);
-
-    if (markdownContent.trim().length === 0) {
-      fail(`Empty markdown file: ${relativeMarkdownPath}`);
-      continue;
-    }
-
-    pass(`${relativeMarkdownPath} (${markdownContent.length} chars)`);
-  }
-}
-
-async function validateRuleFiles() {
-  console.log('\nChecking rule, checklist, prompt, and state files...');
-
-  const expectedPaths = [
-    'rules/naming-conv.md',
-    'rules/architecture.md',
-    'rules/security.md',
-    'rules/performance.md',
-    'rules/error-handling.md',
-    'rules/testing.md',
-    'rules/git-workflow.md',
-    'rules/efficiency-vs-hype.md',
-    'rules/api-docs.md',
-    'rules/microservices.md',
-    'rules/event-driven.md',
-    'rules/database-design.md',
-    'rules/realtime.md',
-    'rules/frontend-architecture.md',
-    'rules/docker-runtime.md',
-    'rules/observability.md',
-    'rules/resilience.md',
-    'rules/migrations.md',
-    'rules/background-jobs.md',
-    'rules/config-and-flags.md',
-    'rules/api-versioning.md',
-    'review-checklists/pr-checklist.md',
-    'review-checklists/architecture-review.md',
-    'prompts/init-project.md',
-    'prompts/compact-natural-mode.md',
-    'prompts/bootstrap-design.md',
-    'prompts/refactor.md',
-    'prompts/review-code.md',
-    'state/architecture-map.md',
-    'state/dependency-map.md',
-  ];
-
-  for (const expectedPath of expectedPaths) {
-    const absoluteExpectedPath = join(AGENT_CONTEXT_DIR, expectedPath);
-
-    if (!(await fileExists(absoluteExpectedPath))) {
-      fail(`Missing agent context file: .agent-context/${expectedPath}`);
-      continue;
-    }
-
-    const fileContent = await readTextFile(absoluteExpectedPath);
-    if (fileContent.trim().length < 100) {
-      fail(`Agent context file is suspiciously short: .agent-context/${expectedPath}`);
-      continue;
-    }
-
-    pass(`.agent-context/${expectedPath}`);
-  }
-}
-
-async function validateChecklistConsolidation() {
-  console.log('\nChecking review checklist consolidation...');
-
-  const reviewChecklistDirectoryPath = join(AGENT_CONTEXT_DIR, 'review-checklists');
-  const checklistEntries = await readdir(reviewChecklistDirectoryPath, { withFileTypes: true });
-  const checklistFileNames = checklistEntries
-    .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
-    .map((entry) => entry.name)
-    .sort((leftName, rightName) => leftName.localeCompare(rightName));
-
-  const expectedChecklistFileNames = ['architecture-review.md', 'pr-checklist.md'];
-
-  if (checklistFileNames.length <= 2) {
-    pass(`Checklist count is consolidated (${checklistFileNames.length}/2)`);
-  } else {
-    fail(`Checklist count exceeds limit (${checklistFileNames.length}/2): ${checklistFileNames.join(', ')}`);
-  }
-
-  for (const expectedChecklistFileName of expectedChecklistFileNames) {
-    if (checklistFileNames.includes(expectedChecklistFileName)) {
-      pass(`Checklist exists: .agent-context/review-checklists/${expectedChecklistFileName}`);
-    } else {
-      fail(`Missing consolidated checklist: .agent-context/review-checklists/${expectedChecklistFileName}`);
-    }
-  }
-}
-
-async function validateCrossReferences() {
-  console.log('\nChecking internal links...');
-
-  const markdownFilePaths = await collectFiles(ROOT_DIR, (fileName) => fileName.endsWith('.md'));
-  const linkPattern = /\[([^\]]*)\]\((?!https?:\/\/|#)([^)]+)\)/g;
-  let checkedLinkCount = 0;
-
-  for (const markdownFilePath of markdownFilePaths) {
-    const markdownContent = await readTextFile(markdownFilePath);
-    const currentFileDirectory = dirname(markdownFilePath);
-    const relativeMarkdownPath = relative(ROOT_DIR, markdownFilePath);
-    let linkMatch = linkPattern.exec(markdownContent);
-
-    while (linkMatch) {
-      const rawLinkTarget = linkMatch[2].split('#')[0];
-      if (rawLinkTarget) {
-        checkedLinkCount += 1;
-        const resolvedLinkPath = resolve(currentFileDirectory, rawLinkTarget);
-
-        if (await fileExists(resolvedLinkPath)) {
-          pass(`${relativeMarkdownPath} → ${linkMatch[2]}`);
-        } else {
-          fail(`Broken link in ${relativeMarkdownPath}: ${linkMatch[2]}`);
-        }
-      }
-
-      linkMatch = linkPattern.exec(markdownContent);
-    }
-  }
-
-  if (checkedLinkCount === 0) {
-    warn('No internal links were found in markdown files');
-  }
-}
-
-async function validateAgentsManifest() {
-  console.log('\nChecking AGENTS.md manifest links...');
-
-  const agentsContent = await readTextFile(join(ROOT_DIR, 'AGENTS.md'));
-  const fileReferencePattern = /\[`?([^`\]]+)`?\]\(([^)]+)\)/g;
-  let manifestLinkCount = 0;
-  let fileReferenceMatch = fileReferencePattern.exec(agentsContent);
-
-  while (fileReferenceMatch) {
-    const manifestLinkTarget = fileReferenceMatch[2];
-
-    if (!manifestLinkTarget.startsWith('http')) {
-      manifestLinkCount += 1;
-      const resolvedManifestLinkPath = resolve(ROOT_DIR, manifestLinkTarget);
-
-      if (await fileExists(resolvedManifestLinkPath)) {
-        pass(`AGENTS.md → ${manifestLinkTarget}`);
-      } else {
-        fail(`AGENTS.md references missing file: ${manifestLinkTarget}`);
-      }
-    }
-
-    fileReferenceMatch = fileReferencePattern.exec(agentsContent);
-  }
-
-  if (manifestLinkCount === 0) {
-    warn('AGENTS.md does not contain any local manifest links');
-  }
-}
-
-async function validatePackageMetadata() {
-  console.log('\nChecking package metadata...');
-
-  const packageJson = JSON.parse(await readTextFile(PACKAGE_JSON_PATH));
-  const versionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
-
-  if (typeof packageJson.version !== 'string' || !versionPattern.test(packageJson.version)) {
-    fail('package.json version must be a semantic version string');
-  } else {
-    pass(`package.json version ${packageJson.version}`);
-  }
-
-  if (packageJson.scripts?.validate === 'node ./scripts/validate.mjs') {
-    pass('package.json validate script is Node-first');
-  } else {
-    fail('package.json validate script must use node ./scripts/validate.mjs');
-  }
-
-  if (packageJson.scripts?.test) {
-    pass('package.json test script exists');
-  } else {
-    fail('package.json test script is missing');
-  }
-
-  if (packageJson.devDependencies && Object.keys(packageJson.devDependencies).length > 0) {
-    warn('package.json still has devDependencies; review whether they are necessary');
-  } else {
-    pass('package.json has no unnecessary devDependencies');
-  }
-
-  if (Array.isArray(packageJson.files) && packageJson.files.includes('AGENTS.md')) {
-    pass('package.json publishes canonical AGENTS.md');
-  } else {
-    fail('package.json must publish AGENTS.md so init and upgrade can copy the canonical root instructions file');
-  }
-
-  if (await fileExists(BUN_LOCK_PATH)) {
-    fail('bun.lock must not be tracked while npm is the package manager source of truth');
-  } else {
-    pass('No bun.lock drift file present');
-  }
-}
-
-async function validatePolicyFile() {
-  console.log('\nChecking LLM Judge policy...');
-
-  const policyContent = await readTextFile(POLICY_FILE_PATH);
-  const parsedPolicy = JSON.parse(policyContent);
-  const selectedProfileName = parsedPolicy.selectedProfile;
-  const profileThresholds = parsedPolicy.profileThresholds;
-
-  if (typeof selectedProfileName !== 'string') {
-    fail('Policy file must define selectedProfile as a string');
-  } else {
-    pass(`LLM Judge selected profile: ${selectedProfileName}`);
-  }
-
-  if (!profileThresholds || typeof profileThresholds !== 'object') {
-    fail('Policy file must define profileThresholds');
-    return;
-  }
-
-  for (const [profileName, profileSettings] of Object.entries(profileThresholds)) {
-    if (!Array.isArray(profileSettings.blockingSeverities)) {
-      fail(`Policy profile ${profileName} must define blockingSeverities`);
-      continue;
-    }
-
-    const invalidSeverity = profileSettings.blockingSeverities.find((severity) => !ALLOWED_SEVERITIES.has(severity));
-    if (invalidSeverity) {
-      fail(`Policy profile ${profileName} uses unsupported severity: ${invalidSeverity}`);
-      continue;
-    }
-
-    pass(`Policy profile ${profileName} blocking severities are valid`);
-  }
-
-  if (typeof profileThresholds[selectedProfileName] === 'object') {
-    pass('Policy selectedProfile points to a valid profile');
-  } else {
-    fail('Policy selectedProfile must match one of the configured profileThresholds');
-  }
-}
-
-async function validateVersionConsistency() {
-  console.log('\nChecking release version consistency...');
-
-  const packageJson = JSON.parse(await readTextFile(PACKAGE_JSON_PATH));
-  const packageVersion = packageJson.version;
-  const changelogContent = await readTextFile(CHANGELOG_PATH);
-
-  if (changelogContent.includes(`## ${packageVersion}`)) {
-    pass(`CHANGELOG.md contains release entry for ${packageVersion}`);
-  } else {
-    fail(`CHANGELOG.md is missing a ## ${packageVersion} heading`);
-  }
-
-  if (await fileExists(PACKAGE_LOCK_PATH)) {
-    const packageLock = JSON.parse(await readTextFile(PACKAGE_LOCK_PATH));
-    const rootLockVersion = packageLock.packages?.['']?.version;
-    if (packageLock.version === packageVersion && rootLockVersion === packageVersion) {
-      pass(`package-lock.json matches package version ${packageVersion}`);
-    } else {
-      fail(`package-lock.json version drift: expected ${packageVersion}, found ${packageLock.version || 'missing'} / ${rootLockVersion || 'missing'}`);
-    }
-  } else {
-    fail('package-lock.json is required for npm release consistency');
-  }
-
-  for (const generatedRuleFileName of GENERATED_RULE_FILES) {
-    const generatedRuleContent = await readTextFile(join(ROOT_DIR, generatedRuleFileName));
-
-    if (generatedRuleContent.includes(`Generated by Agentic-Senior-Core CLI v${packageVersion}`)) {
-      pass(`${generatedRuleFileName} matches package version ${packageVersion}`);
-    } else {
-      fail(`${generatedRuleFileName} does not match package version ${packageVersion}`);
-    }
-  }
-}
-
-async function validateDocumentationFlow() {
-  console.log('\nChecking documentation flow...');
-
-  const readmeContent = await readTextFile(README_PATH);
-  const requiredReadmeSnippets = [
-    'npx @ryuenn3123/agentic-senior-core init',
-    'npm run validate',
-    'docs/faq.md',
-    'docs/deep-dive.md',
-    'docs/archive/HISTORY.md',
-  ];
-
-  for (const requiredReadmeSnippet of requiredReadmeSnippets) {
-    if (readmeContent.includes(requiredReadmeSnippet)) {
-      pass(`README.md mentions ${requiredReadmeSnippet}`);
-    } else {
-      fail(`README.md must mention ${requiredReadmeSnippet}`);
-    }
-  }
-}
 
 async function validateFileSizeAudit() {
   console.log('\nChecking file size threshold (audit:file-size)...');
@@ -619,45 +252,6 @@ async function validateReleaseBundleAudit() {
   }
 }
 
-async function validateMcpConfiguration() {
-  console.log('\nChecking MCP configuration...');
-
-  const mcpConfiguration = JSON.parse(await readTextFile(join(ROOT_DIR, 'mcp.json')));
-  const workspaceMcpConfiguration = JSON.parse(await readTextFile(join(ROOT_DIR, '.vscode', 'mcp.json')));
-  const workspaceServerConfig = workspaceMcpConfiguration.servers?.['agentic-senior-core'];
-
-  if (mcpConfiguration.knowledgeLayers?.enabled === true) {
-    pass('Root MCP config has knowledgeLayers enabled');
-  } else {
-    fail('Root MCP config must have knowledgeLayers.enabled: true');
-  }
-
-  if (typeof workspaceMcpConfiguration.$schema === 'undefined') {
-    pass('Workspace MCP config omits $schema (supported by current VS Code MCP schema inference)');
-  } else if (workspaceMcpConfiguration.$schema === 'vscode://schemas/mcp') {
-    pass('Workspace MCP config uses trusted VS Code schema');
-  } else {
-    fail('Workspace MCP config $schema must be omitted or set to vscode://schemas/mcp');
-  }
-
-  if (workspaceServerConfig?.command === 'node') {
-    pass('Workspace MCP server command uses Node');
-  } else {
-    fail('Workspace MCP server command must use Node');
-  }
-
-  if (workspaceServerConfig?.cwd === '${workspaceFolder}') {
-    pass('Workspace MCP server cwd uses ${workspaceFolder}');
-  } else {
-    fail('Workspace MCP server cwd must be ${workspaceFolder}');
-  }
-
-  if (Array.isArray(workspaceServerConfig?.args) && workspaceServerConfig.args.includes('./scripts/mcp-server.mjs')) {
-    pass('Workspace MCP server points to scripts/mcp-server.mjs');
-  } else {
-    fail('Workspace MCP server must include ./scripts/mcp-server.mjs argument');
-  }
-}
 
 async function main() {
   console.log('===============================================');
@@ -675,16 +269,29 @@ async function main() {
     readTextFile,
   };
 
-  await validateRequiredFiles();
-  await validateMarkdownFiles();
-  await validateRuleFiles();
-  await validateChecklistConsolidation();
-  await validateAgentsManifest();
-  await validateCrossReferences();
-  await validatePackageMetadata();
-  await validatePolicyFile();
-  await validateVersionConsistency();
-  await validateDocumentationFlow();
+  const generalValidationContext = {
+    ...coverageValidationContext,
+    PACKAGE_JSON_PATH,
+    PACKAGE_LOCK_PATH,
+    BUN_LOCK_PATH,
+    CHANGELOG_PATH,
+    README_PATH,
+    POLICY_FILE_PATH,
+    GENERATED_RULE_FILES,
+    collectFiles,
+    warn,
+  };
+
+  await validateRequiredFiles(generalValidationContext);
+  await validateMarkdownFiles(generalValidationContext);
+  await validateRuleFiles(generalValidationContext);
+  await validateChecklistConsolidation(generalValidationContext);
+  await validateAgentsManifest(generalValidationContext);
+  await validateCrossReferences(generalValidationContext);
+  await validatePackageMetadata(generalValidationContext);
+  await validatePolicyFile(generalValidationContext);
+  await validateVersionConsistency(generalValidationContext);
+  await validateDocumentationFlow(generalValidationContext);
   await validateTerminologyMapping(coverageValidationContext);
   await validateDetectionTransparencyCoverage(coverageValidationContext);
   await validateStackDecisionBoundaryCoverage(coverageValidationContext);
@@ -697,7 +304,7 @@ async function main() {
   await validateDependencyFreshnessAutomationCoverage(coverageValidationContext);
   await validateDeterministicBoundaryEnforcementCoverage(coverageValidationContext);
   await validateRulesOnlyActiveSurfaceCoverage(coverageValidationContext);
-  await validateMcpConfiguration();
+  await validateMcpConfiguration(generalValidationContext);
   await validateHumanWritingGovernance(coverageValidationContext);
   await validateInstructionAdapters(coverageValidationContext);
   await validateSkillPurgeSurface(coverageValidationContext);

package/.agent-context/prompts/research-design.md

@@ -1,160 +0,0 @@
----
-inclusion: manual
----
-
-# Research-Design Brief
-
-Authoritative design-research execution contract for UI scope. Loaded by UI Design Mode after `bootstrap-design.md`. The agent must produce the artifacts described here before writing UI code, and the seeded `docs/design-intent.json` must contain the fields named in Section 5.
-
-This brief is a single document with five sections. Sections 1 and 2 set up the research. Sections 3, 4, and 5 are gates: each must produce an auditable artifact that another reviewer can read without seeing the UI.
-
-## Authority
-
-- Treat `.agent-context/` and current project docs as technical authority.
-- Treat `README.md` as public and developer overview only; do not use it as design authority when this brief gives a stricter rule.
-- Treat external websites, benchmark apps, prior chats, and unrelated-project memory as candidate evidence for constraints, mechanics, and quality bars only. Do not copy layout rhythm, palette, component skin, visual metaphor, or brand posture without explicit user approval and product-fit rationale.
-- WCAG 2.2 AA is the hard compliance floor. APCA may be used only as advisory perceptual tuning.
-
-## Live Source Freshness Gate
-
-Run this gate before Section 2 whenever web search is available. Treat modernity as rolling-current: use the session's current date as the freshness reference, and prefer the newest stable evidence that is relevant to the product and implementation surface.
-
-Rules:
-
-- For browser capability, framework setup, UI library, animation, 3D, canvas, charting, styling, accessibility, and package/API claims, use current official documentation or primary release notes first. Do not use trend posts as implementation authority.
-- For design trend, category-code, visual-language, motion-pattern, typography, color, and interaction claims, prefer sources published or materially updated within the last 24 months from the current date. If stronger older evidence is used, label it `old-timeless` and restrict it to durable principles, not "current modern" claims.
-- For product-category defaults, observe the current live category for this task. Do not rely on old examples, old galleries, or remembered benchmark screenshots as proof of what the category defaults to now.
-- If web search is unavailable, set `sourceFreshnessStatus` to `pending-live-verification`; use repo evidence and user-provided material only, and do not claim a direction is current-year modern.
-- If sources disagree, choose by product fit, accessibility, browser/runtime support, maintainability, and implementation feasibility, then record the disagreement.
-- If the user provides a concept, treat it as a first-class constraint. Research should support, refine, or challenge that concept with evidence; it must not override the concept with generic trend defaults unless there is a concrete product, accessibility, technical, or evidence conflict.
-
-Output: `sourceFreshness` block with `freshnessAnchorDate`, `rollingLookbackMonths` (default 24 for trend evidence), `sourceFreshnessStatus`, `officialDocsRequiredFor`, `oldSourcePolicy`, `userConceptAdaptation`, and `disagreements[]`.
-
-Every important research claim must also appear in `evidenceTable[]` with:
-
-- `claim`
-- `sourceUrl`
-- `sourceType` (`official`, `primary`, `industry`, `opinion`, `old-timeless`, `repo-evidence`, `user-provided`)
-- `publishedOrUpdatedAt` when visible, otherwise `unknown`
-- `fetchedAt`
-- `confidence` (`high`, `medium`, `low`)
-- `decisionImpact`
-
-Research vocabulary is internal-only. Use `sourceFreshness`, `evidenceTable[]`, `researchDossier`, `anchor`, `categoryCodes`, `morphologicalExploration`, and `renameTest` to audit decisions, but do not expose those labels in UI copy, public-facing docs, section headings, or final user-facing rationale unless the user explicitly asks for the research trace.
-
-## Anti-Repeat Ledger Gate (read first)
-
-If `docs/design-intent.json` already exists and carries `researchDossier.metadata.antiRepeatLedger`, treat every entry under `previousAnchors`, `previousPalettes`, `previousMotionSignatures`, and `previousStructuralFingerprints` as a hard blocklist before producing any candidate in Sections 3-5.
-
-Rules:
-
-- The five Section 5 anchor candidates must each differ from every blocklisted entry on at least conceptual family, hierarchy implication, and motion implication.
-- Restating an existing direction with new wording is REVISE, not pass.
-- A user-explicit redesign request ("redesign from zero", "redesain dari 0", "ulang dari 0", "research ulang", or any explicit reset) bypasses the freshness gate but does not weaken the ledger; previously shipped direction stays blocklisted unless the user explicitly says "revive existing direction".
-- Ledger entries are signature-level descriptors, not raw token dumps; treat them as direction summaries.
-
-If the ledger is empty or `researchDossier.metadata.researchVerifiedAt` is null because the contract is a fresh seed, the ledger is informational only and does not add blocklist entries.
-
-## Section 1 — Product Reading
-
-Before any visual choice, write a structured product reading:
-
-- Product type and core verb (what the user does, not what the UI shows).
-- Three highest-stakes user moments, ordered by frequency.
-- Data shapes that dominate the screen (timeseries, ledger, list, document, control, telemetry, conversational, spatial, other).
-- Latency profile (real-time, soft real-time, batch, ambient).
-- Failure modes the UI must absorb visibly (partial, stale, optimistic, conflict, offline, permission, rate-limit, none).
-- Context of use (one-shot, sustained focus, glance-and-go, background monitor, shared display, embedded).
-- Known constraints (device, runtime, accessibility, regulatory, performance budget, brand continuity).
-
-Output: `productReading` block. Each field must be one sentence, evidence-backed from repo or brief. Speculation is not allowed; if a field is unknown, name it as such and stop until the user resolves it.
-
-## Default Detection Protocol
-
-Before fetching any reference, use the `productReading` output to derive search direction. Do not self-select from a fixed category list.
-
-1. **Name defaults.** Name three design directions the agent is most tempted to use for this brief. For each, write one sentence naming the specific visual pattern (layout, palette, density, motion, typography, composition).
-
-2. **Argue against each default.** For each default, write one sentence on why it would flatten what is specific about THIS product's core verb, data shape, or context of use. The argument must reference a `productReading` field, not a generic aesthetic opinion.
-
-3. **Derive search direction from the argument.** The rejection argument reveals what the product needs that the default cannot provide. Use that need as the search query for `web_search` and `web_fetch`. Search by the product's core characteristic pair (medium x intent), not by product category name. Example: core verb "demonstrate" + data shape "narrative" -> search "editorial portfolio interaction design" not "portfolio sites."
-
-4. **Cross-domain pull.** Identify one domain that shares the same interaction model but a different visual vocabulary. Pull one reference from there. Example: portfolio -> scientific publication, exhibition catalog, film press kit -- anything with "demonstrate body of work" as the core verb but a different surface expectation.
-
-5. **Gallery check.** Find state-of-the-art quality references for the derived direction by searching the web. CRITICAL: DO NOT use gallery homepages or discovery platforms as references. You must drill down to find a specific featured product/website, fetch THAT specific product's URL, and use it as evidence.
-
-DO NOT fetch: Wikipedia, Dribbble templates, or generic blog posts about "best UI design practices."
-
-For each reference: fetch the actual product page this session, record what mechanic or hierarchy is borrowed, and explicitly state what is NOT borrowed (palette, component skin, layout rhythm).
-
-If the anchor concept you're considering would make sense to someone from 1920, it's too archival. The anchor must be legible to someone who uses the web today.
-
-## Section 2 — Reference Intake
-
-Reference material is fuel for variance, not a style source.
-
-- Capture between three and seven references per dimension that needs exploration: hierarchy, density, type system, motion, state language, material logic, color behavior.
-- For each reference, record: source URL or citation, what is borrowed (mechanic, behavior, hierarchy, density, type pairing, motion choreography), and what is explicitly not borrowed (palette, component skin, layout rhythm, brand posture).
-- References live in `referenceIntake[]`. The agent may not select an anchor in Section 5 that copies a reference's surface; only the borrowed mechanic is allowed to flow downstream.
-
-If references are not provided by the user and web search is unavailable, set `referenceIntakeStatus` to `internal-evidence-only` and constrain Sections 3 to 5 to repo evidence and project docs.
-
-## Section 3 — Creative Direction
-
-Before UI code, commit to a specific visual direction. The agent tends to converge toward generic, "on distribution" outputs. In frontend design this creates what users call the "AI slop" aesthetic. This section exists to prevent that.
-
-### 3a. Category defaults to avoid
-
-Name at least three specific cliches your product category will fall into without intervention. Be specific enough that someone unfamiliar with the project can visualize the exact aesthetic trap from the text alone.
-
-Common AI-safe cliches to name and reject when your product sits anywhere near them:
-
-- `dev-tool default: condensed tabular numerics with minimal chrome and monospace code blocks on dark slate background, sans-serif metadata at 11-12px, monochrome status dots`
-- `AI-startup landing default: purple-to-pink gradient hero with floating 3D glass cards, sans-serif display type at 700-900 weight, vague hero copy, three-up feature grid`
-- `SaaS admin default: left-side icon-only nav, top utility bar, three-card KPI row above a single data table, neutral grey-on-white with one accent color`
-- `marketing site default: hero image with one-line headline plus subhead, three feature tiles below, two pricing tiers, testimonial carousel, footer link grid`
-
-Each category default must include a one-sentence rejection note explaining the trap it sets.
-
-Output: `categoryCodes[]` with at least three entries in `docs/design-intent.json`. Each entry has `description`, `categoryDefaultReason`, and `rejectionNote`.
-
-### 3b. Anchor reference
-
-Pick one concrete, googleable real-world reference whose mechanics (not surface) translate to your UI. The anchor must be specific enough that renaming the product to a different category breaks coherence.
-
-Hard constraints:
-- Reject generic quality words as anchors: "modern", "clean", "premium", "expressive", "minimal", "bold", "futuristic", "elegant" are not anchors.
-- Specific premium digital products are valid anchors when the borrowed element is an interaction mechanic, hierarchy pattern, or motion behavior -- not a palette or brand.
-- Do not default to spatial place metaphors (room, darkroom, control room, studio, lab, cockpit, command center). Prefer artifacts, workflows, instruments, data behaviors, materials, editorial systems, or interaction mechanisms.
-- Draw from IDE themes, cultural aesthetics, cinematic campaigns, editorial systems, material artifacts, or specific product experiences for inspiration.
-
-Output: `conceptualAnchor.anchorReference` in `docs/design-intent.json`.
-
-### 3c. Four creative commitments (record before coding)
-
-1. **Typography**: Choose distinctive fonts with meaningful role contrast. Avoid overused families (Inter, Roboto, Arial, Space Grotesk, system fonts). Pick choices that elevate the aesthetic. Record one variable-axis or pairing decision.
-2. **Color and palette**: Commit to a cohesive product-derived palette. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Name what product evidence makes the palette fit and one color behavior that would not transfer to another category.
-3. **Motion and interaction**: Define one signature motion behavior more specific than "smooth." Focus on high-impact moments: one well-orchestrated page load with staggered reveals creates more delight than scattered micro-interactions. Use CSS-only or a modern motion library.
-4. **Composition**: Make one composition choice that avoids interchangeable card stacks. Create atmosphere and depth rather than defaulting to solid backgrounds.
-
-Avoid generic AI-generated aesthetics:
-- Overused font families and cliched color schemes (particularly purple gradients)
-- Predictable layouts and cookie-cutter component patterns
-- Solid-color backgrounds without atmosphere or depth
-
-Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. The agent still tends to converge on common choices across generations; resist this.
-
-Output: Record all four commitments in `docs/design-intent.json` before UI code. The `derivedTokenLogic.tokenContinuityClassification` must classify each of typography, palette, motion, and spacing as `anchor-derived`, `continuity-retained`, or `newly-introduced` with rationale.
-
-## Done Criteria
-
-The brief is complete when:
-
-1. `productReading` is filled with evidence-backed sentences.
-2. `referenceIntake[]` records the borrowed mechanic and the explicit non-copy boundary per reference (or `referenceIntakeStatus: internal-evidence-only` is set).
-3. `categoryCodes[]` has at least three entries with rejection notes.
-4. One anchor reference is recorded that passes the specificity test (renaming the product to a different category breaks coherence).
-5. Four creative commitments are recorded with product-derived rationale.
-6. Generic anchors and spatial-place defaults are rejected with the rejection reason recorded.
-
-Only after the brief is complete does the agent move on to `docs/DESIGN.md` and the rest of `docs/design-intent.json` (token logic, motion budget, accessibility policy, review rubric, library decisions, etc., per `bootstrap-design.md`).