@ryuenn3123/agentic-senior-core 3.0.6 → 3.0.7

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

@@ -1,22 +1,48 @@
 
-# Bootstrap DESIGN.md (UI/UX Art Direction)
+# Bootstrap Dynamic Design Contract
 
-When a user requests frontend design or redesign, the agent should automatically synthesize a complete DESIGN.md covering:
-- Visual identity (color palette, typography, spacing, iconography)
-- Layout and navigation principles
-- Component library and atomic design system
-- Accessibility and responsive guidelines
-- User journey and interaction flows
-- Design tokens and handoff notes for developers
+When a user requests frontend design or redesign, the agent should automatically synthesize a dynamic design contract made of:
+- `docs/DESIGN.md` for human-readable design direction and implementation rationale
+- `docs/design-intent.json` for machine-readable intent, anti-generic constraints, and validation hints
+
+This contract is a structure and reasoning system, not a fixed visual template. It must adapt to product context, user needs, platform constraints, and current design signals.
 
 The agent must:
 1. Read [AGENTS.md](../../AGENTS.md) for project context and team roles.
 2. Scan all files in [.agent-context/rules/](../rules/) for UI/UX and accessibility standards.
 3. Reference [docs/deep-dive.md](../../docs/deep-dive.md) and [docs/faq.md](../../docs/faq.md) for architecture and product background.
-4. If [docs/DESIGN.md](../../docs/DESIGN.md) exists, check for drift and propose improvements instead of rewriting from scratch.
-5. All references to docs or rules must be clickable markdown links.
+4. If [docs/DESIGN.md](../../docs/DESIGN.md) or `docs/design-intent.json` already exists, check for drift and improve them instead of rewriting blindly.
+5. Treat any example structure or stylistic inspiration as non-normative. Use it only to judge depth and clarity, never to copy a visual language directly.
+6. All references to docs or rules must be clickable markdown links.
+
+Required `docs/DESIGN.md` sections:
+1. Design Intent and Product Personality
+2. Audience and Use-Context Signals
+3. Visual Direction and Distinctive Moves
+4. Color System and Semantic Roles
+5. Typography System and Hierarchy
+6. Spacing, Layout Rhythm, and Density Strategy
+7. Interaction, Motion, and Feedback Rules
+8. Component Language and Shared Patterns
+9. Accessibility Non-Negotiables
+10. Responsive Strategy
+11. Anti-Patterns to Avoid
+12. Implementation Notes for Future UI Tasks
+
+Required `docs/design-intent.json` fields:
+- `mode`
+- `status`
+- `project`
+- `brandAdjectives`
+- `antiAdjectives`
+- `visualDirection`
+- `experiencePrinciples`
+- `forbiddenPatterns`
+- `requiredDesignSections`
+- `implementation`
 
 Output:
-- Write a full DESIGN.md in markdown, with clear sections and clickable links to referenced docs/rules.
-- Use practical, modern, and accessible design language.
+- Create or update both `docs/DESIGN.md` and `docs/design-intent.json`.
+- Keep both files synchronized: the markdown explains the why, the JSON captures the contract in machine-readable form.
+- Use practical, modern, accessible language grounded in the project, not generic SaaS defaults.
 - Wait for user approval before generating Figma or code assets.

package/.agent-context/prompts/init-project.md

@@ -35,7 +35,7 @@ If the user specifies a framework/blueprint, the agent should:
 See [docs/roadmap.md](../../docs/roadmap.md) and [docs/deep-dive.md](../../docs/deep-dive.md) for the latest stack and blueprint list.
 
 ## UI/UX Bootstrap
-When a user requests frontend or UI/UX design, the agent should automatically execute the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize DESIGN.md.
+When a user requests frontend or UI/UX design, the agent should automatically execute the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize a dynamic design contract (`docs/DESIGN.md` + `docs/design-intent.json`).
 
 ---
 
@@ -97,6 +97,6 @@ See [docs/roadmap.md](../../docs/roadmap.md) and [docs/deep-dive.md](../../docs/
 
 ---
 
-## Bootstrap UI/UX (DESIGN.md)
+## Bootstrap UI/UX (Dynamic Design Contract)
 
-To start UI/UX design from scratch, use the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize `docs/DESIGN.md`.
+To start UI/UX design from scratch, use the [bootstrap-design.md](./bootstrap-design.md) prompt to synthesize `docs/DESIGN.md` and `docs/design-intent.json`.

package/.agent-context/prompts/refactor.md

@@ -15,7 +15,7 @@ Before making changes:
 3. Read .agent-context/rules/error-handling.md — fix error handling patterns.
 4. Resolve active language guidance from dynamic stack signals (TypeScript in this repository).
 5. Enforce backend universal principles: no clever hacks, no premature abstraction, readability over brevity.
-6. Enforce Universal SOP hard gate: stop implementation if `docs/architecture-decision-record.md` is missing, and for UI scope stop if `docs/DESIGN.md` is missing.
+6. Enforce Universal SOP hard gate: stop implementation if `docs/architecture-decision-record.md` is missing, and for UI scope stop if `docs/DESIGN.md` or `docs/design-intent.json` is missing.
 
 For every change you make, provide a Reasoning Chain:
 - What was wrong (rule reference)

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

@@ -20,7 +20,7 @@ Use these checklists:
 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.
 9. Enforce single-source and lazy-loading policy: canonical rule source must be explicitly enforced, language-specific guidance must load lazily based on detected scope, and conflicting duplicate rule instructions must not appear during normal flow.
-10. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (`docs/architecture-decision-record.md`, and for UI scope `docs/DESIGN.md`).
+10. Enforce Universal SOP hard gate: block coding flow when required project docs are missing (`docs/architecture-decision-record.md`, and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).
 
 For EVERY violation found:
 - State the exact file and line

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

@@ -135,4 +135,4 @@ VERDICT: PASS / FAIL (X/Y items passed)
 - [ ] Backend and frontend mindset checks are both applied when scope spans API and UI boundaries
 - [ ] Security and testing requirements remain mandatory after static template purge
 - [ ] Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing
-- [ ] UI implementation flow is blocked if `docs/DESIGN.md` is missing
+- [ ] UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing

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

@@ -21,7 +21,7 @@ The `.agent-context/rules/` directory is the default guidance source for impleme
 - Security and testing are non-negotiable baseline requirements.
 - Hard block before coding:
   - `docs/architecture-decision-record.md` (alias: `docs/Architecture-Decision-Record.md`) must exist.
-  - For UI scope, `docs/DESIGN.md` must exist.
+  - For UI scope, `docs/DESIGN.md` and `docs/design-intent.json` must exist.
 - If required project context docs are missing, stop implementation and bootstrap docs before writing application code.
 
 ## Rules as Guardian (Cross-Session Consistency)

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

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-04-19T03:52:25.678Z",
+  "generatedAt": "2026-04-20T00:30:26.121Z",
   "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 v3.0.6
+Generated by Agentic-Senior-Core CLI v3.0.7
 Timestamp: 2026-04-18T00:00:00.000Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json
@@ -46,4 +46,4 @@ Do not claim done before checklist pass.
 
 ## UNIVERSAL SOP HARD GATES
 - Stop coding if docs/architecture-decision-record.md (or docs/Architecture-Decision-Record.md) is missing.
-- For UI scope, stop coding if docs/DESIGN.md is missing.
+- For UI scope, stop coding if docs/DESIGN.md or docs/design-intent.json is missing.

package/.gemini/instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 354edbbfaedec284ddcc6d4a5bb5393a7f5385650d1a6ae84a2d9633b5a6d10d
+Canonical Snapshot SHA256: 08c326d79f2c0f4bd7ef106da3542ab0f78f4d02bc205d63598db34cf3f40731
 
 Canonical policy source: [.instructions.md](../.instructions.md).
 

package/.github/copilot-instructions.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 354edbbfaedec284ddcc6d4a5bb5393a7f5385650d1a6ae84a2d9633b5a6d10d
+Canonical Snapshot SHA256: 08c326d79f2c0f4bd7ef106da3542ab0f78f4d02bc205d63598db34cf3f40731
 
 The canonical policy source for this repository is [.instructions.md](../.instructions.md).
 

package/.windsurfrules

@@ -1,6 +1,6 @@
 # AGENTIC-SENIOR-CORE DYNAMIC GOVERNANCE RULESET
 
-Generated by Agentic-Senior-Core CLI v3.0.6
+Generated by Agentic-Senior-Core CLI v3.0.7
 Timestamp: 2026-04-18T00:00:00.000Z
 Selected profile: beginner
 Selected policy file: .agent-context/policies/llm-judge-threshold.json
@@ -46,4 +46,4 @@ Do not claim done before checklist pass.
 
 ## UNIVERSAL SOP HARD GATES
 - Stop coding if docs/architecture-decision-record.md (or docs/Architecture-Decision-Record.md) is missing.
-- For UI scope, stop coding if docs/DESIGN.md is missing.
+- For UI scope, stop coding if docs/DESIGN.md or docs/design-intent.json is missing.

package/AGENTS.md

@@ -2,7 +2,7 @@
 
 Adapter Mode: thin
 Adapter Source: .instructions.md
-Canonical Snapshot SHA256: 354edbbfaedec284ddcc6d4a5bb5393a7f5385650d1a6ae84a2d9633b5a6d10d
+Canonical Snapshot SHA256: 08c326d79f2c0f4bd7ef106da3542ab0f78f4d02bc205d63598db34cf3f40731
 
 This file is an adapter entrypoint for agent discovery.
 The canonical policy source is [.instructions.md](.instructions.md).

package/README.md

@@ -10,12 +10,12 @@
 **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.
 
-Latest release: 3.0.6 (2026-04-19).
+Latest release: 3.0.7 (2026-04-20).
 
-Highlights in 3.0.0:
-- Universal IDE adapter surface is completed and synchronized through thin adapters.
-- Scoped auto-docs sync rollout is active with explicit phase-1 boundaries and precision/recall evidence.
-- Init and scaffolding flow is slimmer, template-free on active path, and validated by deterministic release gates.
+Highlights in 3.0.7:
+- Dynamic UI design contract bootstrap now ships paired markdown and machine-readable intent.
+- Upgrade warns when existing UI repositories are missing required design contract files.
+- Init discovery stays slimmer by reusing architecture context and removing redundant wizard branches.
 
 </div>
 

package/lib/cli/commands/init.mjs

@@ -399,6 +399,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     )?.label || 'Both (frontend + backend)';
 
     let architectureRecommendation = null;
+    let architectureProjectDescription = '';
     let architectPreferenceState = await readArchitectPreferenceState();
     let architectPreferenceUpdated = false;
 
@@ -457,6 +458,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     selectedProjectScopeLabel = architectureSelection.selectedProjectScopeLabel;
     selectedManualStackFileName = architectureSelection.selectedManualStackFileName;
     selectedManualBlueprintFileName = architectureSelection.selectedManualBlueprintFileName;
+    architectureProjectDescription = architectureSelection.architectureProjectDescription;
     architectureRecommendation = architectureSelection.architectureRecommendation;
     architectPreferenceState = architectureSelection.architectPreferenceState;
     architectPreferenceUpdated = architectureSelection.architectPreferenceUpdated;
@@ -607,6 +609,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         } else {
           discoveryAnswers = await runProjectDiscovery(userInterface, {
             defaultProjectName: path.basename(resolvedTargetDirectoryPath),
+            defaultProjectDescription: architectureProjectDescription,
           });
         }
 
@@ -645,6 +648,9 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
           for (const generatedPromptFileName of scaffoldingResult.generatedPromptFileNames || []) {
             console.log(`  - .agent-context/prompts/${generatedPromptFileName}`);
           }
+          for (const materializedFileName of scaffoldingResult.materializedFileNames || []) {
+            console.log(`  - docs/${materializedFileName}`);
+          }
           console.log('Project docs will be authored dynamically by your IDE assistant from these prompts.');
         } else {
           console.log(`\nProject documentation generated in docs/:`);
@@ -674,6 +680,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       selectedProfileName,
       selectedProfilePack,
       selectedPreset: initOptions.preset || null,
+      projectScope: {
+        key: selectedProjectScopeKey,
+        label: selectedProjectScopeLabel,
+      },
       selectedStackFileName: selectedResolvedStackFileName,
       selectedAdditionalStackFileNames,
       selectedBlueprintFileName: selectedResolvedBlueprintFileName,
@@ -746,6 +756,9 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     console.log('- Generated files: .agent-instructions.md, .cursorrules, .windsurfrules, .clauderc, and .agent-context/state/onboarding-report.json');
     if (scaffoldingResult?.bootstrapMode === 'ai-synthesis') {
       console.log(`- Bootstrap prompts: ${(scaffoldingResult.generatedPromptFileNames || []).length} files generated in .agent-context/prompts/`);
+      if ((scaffoldingResult.materializedFileNames || []).length > 0) {
+        console.log(`- Seed docs: ${(scaffoldingResult.materializedFileNames || []).length} files generated in docs/`);
+      }
       console.log(`- Bootstrap docs language: ${scaffoldingResult.docsLanguage}`);
       console.log(`- Expected project docs after synthesis: ${scaffoldingResult.generatedFileNames.length} files in docs/`);
     } else if (scaffoldingResult) {
@@ -779,7 +792,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       console.log('\nPrompt starter examples (copy and adapt in your IDE):');
       console.log('- If docs/project-brief.md is missing, execute .agent-context/prompts/bootstrap-project-context.md now and create all required docs files.');
       if ((scaffoldingResult.generatedPromptFileNames || []).includes('bootstrap-design.md')) {
-        console.log('- If docs/DESIGN.md is missing, execute .agent-context/prompts/bootstrap-design.md now before building UI components.');
+        console.log('- If docs/DESIGN.md or docs/design-intent.json is missing, execute .agent-context/prompts/bootstrap-design.md now before building UI components.');
       }
       console.log(`- Build an MVP for ${promptProjectName} using the newly synthesized docs as strict project context.`);
       console.log('- When scope changes, update docs/* in the same change so future prompts stay aligned.');

package/lib/cli/commands/upgrade.mjs

@@ -29,6 +29,7 @@ import {
   detectProjectContext,
   buildDetectionSummary,
   formatDetectionCandidates,
+  collectProjectMarkers,
 } from '../detector.mjs';
 import {
   buildCompiledRulesContent,
@@ -103,6 +104,102 @@ function buildExistingProjectMajorConstraints() {
   ];
 }
 
+async function readPackageJsonIfExists(targetDirectoryPath) {
+  const packageJsonPath = path.join(targetDirectoryPath, 'package.json');
+  if (!(await pathExists(packageJsonPath))) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(await fs.readFile(packageJsonPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function detectUiScopeSignals({
+  targetDirectoryPath,
+  existingOnboardingReport,
+  selectedStackFileName,
+  selectedBlueprintFileName,
+}) {
+  const signalReasons = [];
+  const markerNames = await collectProjectMarkers(targetDirectoryPath);
+  const packageManifest = await readPackageJsonIfExists(targetDirectoryPath);
+
+  const persistedProjectScopeKey = String(existingOnboardingReport?.projectScope?.key || '').trim().toLowerCase();
+  if (persistedProjectScopeKey === 'frontend-only' || persistedProjectScopeKey === 'both') {
+    signalReasons.push(`onboarding project scope: ${persistedProjectScopeKey}`);
+  }
+
+  const selectedStackKey = String(selectedStackFileName || '').trim().toLowerCase();
+  if (selectedStackKey === 'react-native.md' || selectedStackKey === 'flutter.md') {
+    signalReasons.push(`selected stack implies UI runtime: ${selectedStackKey}`);
+  }
+
+  const selectedBlueprintKey = String(selectedBlueprintFileName || '').trim().toLowerCase();
+  if (selectedBlueprintKey.includes('frontend') || selectedBlueprintKey.includes('landing') || selectedBlueprintKey.includes('mobile-app')) {
+    signalReasons.push(`selected blueprint implies UI scope: ${selectedBlueprintKey}`);
+  }
+
+  const directUiMarkerNames = [
+    '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',
+  ];
+
+  const detectedUiMarkers = directUiMarkerNames.filter((markerName) => markerNames.has(markerName));
+  if (detectedUiMarkers.length > 0) {
+    signalReasons.push(`ui markers: ${detectedUiMarkers.join(', ')}`);
+  }
+
+  const dependencyMap = {
+    next: 'next',
+    react: 'react',
+    reactDom: 'react-dom',
+    reactNative: 'react-native',
+    expo: 'expo',
+    tailwindcss: 'tailwindcss',
+  };
+  const dependencySource = {
+    ...(packageManifest?.dependencies || {}),
+    ...(packageManifest?.devDependencies || {}),
+  };
+  const detectedUiDependencies = Object.values(dependencyMap).filter((dependencyName) => dependencySource[dependencyName]);
+  if (detectedUiDependencies.length > 0) {
+    signalReasons.push(`ui dependencies: ${detectedUiDependencies.join(', ')}`);
+  }
+
+  const hasStrongUiMarker = detectedUiMarkers.some((markerName) => (
+    markerName.startsWith('next.config')
+    || markerName === 'react-native.config.js'
+    || markerName === 'android'
+    || markerName === 'ios'
+  ));
+  const hasUiDependencies = detectedUiDependencies.length > 0;
+  const hasStructuralUiMarkers = detectedUiMarkers.length >= 2;
+
+  return {
+    isUiScopeLikely: signalReasons.length > 0 && (hasStrongUiMarker || hasUiDependencies || hasStructuralUiMarkers || persistedProjectScopeKey.length > 0),
+    signalReasons,
+  };
+}
+
 export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions = {}) {
   const resolvedTargetDirectoryPath = path.resolve(targetDirectoryArgument || '.');
 
@@ -167,6 +264,21 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
     const includeCiGuardrails = typeof existingOnboardingReport?.ciGuardrailsEnabled === 'boolean'
       ? existingOnboardingReport.ciGuardrailsEnabled
       : true;
+    const uiScopeSignals = await detectUiScopeSignals({
+      targetDirectoryPath: resolvedTargetDirectoryPath,
+      existingOnboardingReport,
+      selectedStackFileName,
+      selectedBlueprintFileName,
+    });
+    const designContractPaths = ['docs/DESIGN.md', 'docs/design-intent.json'];
+    const missingDesignContractPaths = [];
+
+    for (const designContractPath of designContractPaths) {
+      const absoluteDesignContractPath = path.join(resolvedTargetDirectoryPath, ...designContractPath.split('/'));
+      if (!(await pathExists(absoluteDesignContractPath))) {
+        missingDesignContractPaths.push(designContractPath);
+      }
+    }
 
     const detectionMajorConstraints = buildExistingProjectMajorConstraints();
     const detectionTransparency = {
@@ -288,6 +400,18 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
       console.log('Recommendation: regenerate docs with init --scaffold-docs or update the files manually to match the latest template version.');
     }
 
+    if (uiScopeSignals.isUiScopeLikely && missingDesignContractPaths.length > 0) {
+      console.log('\n[WARN] UI/frontend scope was detected, but the dynamic design contract is incomplete:');
+      for (const missingDesignContractPath of missingDesignContractPaths) {
+        console.log(`- Missing ${missingDesignContractPath}`);
+      }
+      if (uiScopeSignals.signalReasons.length > 0) {
+        console.log(`- Detection signals: ${uiScopeSignals.signalReasons.join('; ')}`);
+      }
+      console.log('Recommendation: create or refresh docs/DESIGN.md and docs/design-intent.json before allowing UI implementation work.');
+      console.log('Upgrade synchronizes governance assets, but it does not author project-specific design docs automatically.');
+    }
+
     if (upgradeOptions.dryRun) {
       console.log('\nDry run enabled. No files were modified.');
       return;
@@ -320,6 +444,7 @@ export async function runUpgradeCommand(targetDirectoryArgument, upgradeOptions
         targetDirectoryPath: resolvedTargetDirectoryPath,
         selectedProfileName,
         selectedProfilePack: existingOnboardingReport?.selectedProfilePack || null,
+        projectScope: existingOnboardingReport?.projectScope || null,
         selectedStackFileName,
         selectedAdditionalStackFileNames,
         selectedBlueprintFileName,

package/lib/cli/compiler.mjs

@@ -37,6 +37,7 @@ export async function writeOnboardingReport({
   selectedProfileName,
   selectedProfilePack,
   selectedPreset,
+  projectScope = null,
   selectedStackFileName,
   selectedAdditionalStackFileNames = [],
   selectedBlueprintFileName,
@@ -70,6 +71,7 @@ export async function writeOnboardingReport({
       }
       : null,
     selectedPreset,
+    projectScope,
     selectedStack: selectedStackFileName,
     selectedAdditionalStacks: selectedAdditionalStackFileNames,
     selectedBlueprint: selectedBlueprintFileName,
@@ -351,6 +353,8 @@ export async function buildCompiledRulesContent({
       'database-schema.md',
       'api-contract.md',
       'flow-overview.md',
+      'DESIGN.md',
+      'design-intent.json',
     ];
 
     for (const candidateFileName of candidateDocFileNames) {
@@ -369,7 +373,7 @@ export async function buildCompiledRulesContent({
         '',
         'Universal SOP hard block policy:',
         '- Stop implementation if docs/architecture-decision-record.md (alias: docs/Architecture-Decision-Record.md) is missing.',
-        '- For UI scope, stop implementation if docs/DESIGN.md is missing.',
+        '- For UI scope, stop implementation if docs/DESIGN.md or docs/design-intent.json is missing.',
         '- Materialize missing docs first, then continue coding.',
         '',
         'These docs were generated during project initialization and reflect the architecture,',
@@ -402,7 +406,7 @@ export async function buildCompiledRulesContent({
         '- Hard block: do not write application code until docs/project-brief.md and docs/architecture-decision-record.md exist.',
         '- If docs/project-brief.md is missing, execute bootstrap-project-context prompt immediately.',
         hasBootstrapDesignPrompt
-          ? '- For UI scope: if docs/DESIGN.md is missing, execute bootstrap-design prompt before implementing UI surfaces.'
+          ? '- For UI scope: if docs/DESIGN.md or docs/design-intent.json is missing, execute bootstrap-design prompt before implementing UI surfaces.'
           : '- For UI scope: add a design bootstrap prompt before implementing UI surfaces.',
         '- Save generated docs under docs/ and keep them updated when feature scope changes.',
         'Latest user prompt defines current feature scope and product direction.',

package/lib/cli/init-architecture-flow.mjs

@@ -62,6 +62,7 @@ export async function resolveArchitectureSelection({
       selectedProjectScopeLabel,
       selectedManualStackFileName,
       selectedManualBlueprintFileName,
+      architectureProjectDescription: '',
       architectureRecommendation,
       architectPreferenceState: nextArchitectPreferenceState,
       architectPreferenceUpdated,
@@ -224,6 +225,7 @@ export async function resolveArchitectureSelection({
     selectedProjectScopeLabel,
     selectedManualStackFileName,
     selectedManualBlueprintFileName,
+    architectureProjectDescription,
     architectureRecommendation,
     architectPreferenceState: nextArchitectPreferenceState,
     architectPreferenceUpdated,

package/lib/cli/project-scaffolder.mjs

@@ -6,7 +6,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { ensureDirectory, askChoice, askYesNo, toTitleCase, pathExists } from './utils.mjs';
+import { ensureDirectory, askChoice, toTitleCase, pathExists } from './utils.mjs';
 
 const SUPPORTED_DOC_LANGUAGES = new Set(['en', 'id']);
 const PROJECT_DOC_FILE_NAMES = [
@@ -16,6 +16,7 @@ const PROJECT_DOC_FILE_NAMES = [
   'api-contract.md',
   'flow-overview.md',
 ];
+const UI_DESIGN_CONTRACT_FILE_NAMES = ['DESIGN.md', 'design-intent.json'];
 
 // Legacy project docs may still carry this version header; keep for upgrade staleness checks.
 export const PROJECT_DOC_TEMPLATE_VERSION = '1.2.0';
@@ -54,57 +55,6 @@ const DOCKER_STRATEGY_CHOICES = [
   'Docker for both development and production',
 ];
 
-const DISCOVERY_MODE_CHOICES = [
-  'Quick mode (mostly choices, fastest)',
-  'Detailed mode (type your own answers)',
-];
-
-const DESCRIPTION_TEMPLATE_CHOICES = [
-  'Marketplace / commerce platform',
-  'Internal operations dashboard',
-  'SaaS workflow product',
-  'Developer platform / API product',
-  'Content and community platform',
-  'Other',
-];
-
-const FEATURE_PRESET_CHOICES = [
-  'MVP foundation (auth, core CRUD, role-based access)',
-  'Commerce flow (catalog, cart, checkout)',
-  'Operations flow (dashboard, approvals, reporting)',
-  'API platform flow (keys, rate-limit, webhooks)',
-  'Content flow (publish, moderation, search)',
-  'Other',
-];
-
-const FEATURE_PRESET_MAP = {
-  'MVP foundation (auth, core CRUD, role-based access)': [
-    'Authentication and user profiles',
-    'Core CRUD workflow for primary resources',
-    'Role-based access control',
-  ],
-  'Commerce flow (catalog, cart, checkout)': [
-    'Product catalog and filtering',
-    'Shopping cart and wishlist',
-    'Checkout and payment processing flow',
-  ],
-  'Operations flow (dashboard, approvals, reporting)': [
-    'Operational dashboard with KPIs',
-    'Approval workflow and audit trail',
-    'Reporting and export functionality',
-  ],
-  'API platform flow (keys, rate-limit, webhooks)': [
-    'API key management',
-    'Rate limiting and usage quotas',
-    'Webhook delivery and retry handling',
-  ],
-  'Content flow (publish, moderation, search)': [
-    'Draft and publish workflow',
-    'Moderation queue and policy checks',
-    'Search and discovery experience',
-  ],
-};
-
 function parseBooleanLikeValue(rawValue) {
   const normalizedValue = String(rawValue || '').trim().toLowerCase();
   if (['true', 'yes', 'y', '1'].includes(normalizedValue)) {
@@ -161,44 +111,6 @@ function resolveDockerStrategy({ dockerStrategy, useDocker, useDockerDevelopment
   return DOCKER_STRATEGY_CHOICES[0];
 }
 
-function parseDockerStrategy(dockerStrategy) {
-  const normalizedDockerStrategy = String(dockerStrategy || '').toLowerCase();
-
-  if (normalizedDockerStrategy.includes('both development and production')) {
-    return {
-      dockerStrategy: DOCKER_STRATEGY_CHOICES[3],
-      hasDocker: true,
-      useDockerDevelopment: true,
-      useDockerProduction: true,
-    };
-  }
-
-  if (normalizedDockerStrategy.includes('development only')) {
-    return {
-      dockerStrategy: DOCKER_STRATEGY_CHOICES[1],
-      hasDocker: true,
-      useDockerDevelopment: true,
-      useDockerProduction: false,
-    };
-  }
-
-  if (normalizedDockerStrategy.includes('production only')) {
-    return {
-      dockerStrategy: DOCKER_STRATEGY_CHOICES[2],
-      hasDocker: true,
-      useDockerDevelopment: false,
-      useDockerProduction: true,
-    };
-  }
-
-  return {
-    dockerStrategy: DOCKER_STRATEGY_CHOICES[0],
-    hasDocker: false,
-    useDockerDevelopment: false,
-    useDockerProduction: false,
-  };
-}
-
 async function askFeatureList(userInterface) {
   console.log('\nList your key features (one per line, press Enter to finish):');
 
@@ -231,67 +143,32 @@ export async function runProjectDiscovery(userInterface, options = {}) {
   console.log('You can answer in your own language.');
   console.log('CLI prompts stay in English, but non-English answers are fully supported.\n');
 
-  const selectedDiscoveryMode = await askChoice(
-    'How do you want to answer project questions?',
-    DISCOVERY_MODE_CHOICES,
-    userInterface
-  );
-
-  const isQuickMode = selectedDiscoveryMode === DISCOVERY_MODE_CHOICES[0];
-
   const defaultProjectName = (options.defaultProjectName || '').trim();
+  const defaultProjectDescription = String(options.defaultProjectDescription || '').trim();
   let projectName = '';
 
-  if (isQuickMode && defaultProjectName) {
-    const projectNameSource = await askChoice(
-      'Project name source:',
-      [
-        `Use folder name (${defaultProjectName})`,
-        'Type custom project name',
-      ],
-      userInterface
-    );
+  const projectNamePrompt = defaultProjectName
+    ? `Project name (press Enter to use folder name: ${defaultProjectName}): `
+    : 'Project name: ';
 
-    if (projectNameSource.startsWith('Use folder name')) {
-      projectName = defaultProjectName;
-    }
-  }
-
-  if (!projectName) {
-    const projectNamePrompt = defaultProjectName
-      ? `Project name (press Enter to use folder name: ${defaultProjectName}): `
-      : 'Project name: ';
+  projectName = (await userInterface.question(projectNamePrompt)).trim();
 
-    projectName = (await userInterface.question(projectNamePrompt)).trim();
-
-    if (!projectName && defaultProjectName) {
-      projectName = defaultProjectName;
-    }
+  if (!projectName && defaultProjectName) {
+    projectName = defaultProjectName;
   }
 
   if (!projectName) {
     throw new Error('Project name is required for documentation scaffolding.');
   }
 
-  let projectDescription = '';
-  if (isQuickMode) {
-    const selectedDescriptionTemplate = await askChoice(
-      'Project description template:',
-      DESCRIPTION_TEMPLATE_CHOICES,
-      userInterface
-    );
+  const projectDescriptionPrompt = defaultProjectDescription
+    ? `One-line description (press Enter to use: ${defaultProjectDescription}): `
+    : 'One-line description: ';
 
-    if (selectedDescriptionTemplate === 'Other') {
-      projectDescription = (await userInterface.question('One-line description: ')).trim();
-    } else {
-      projectDescription = `${selectedDescriptionTemplate} for ${projectName}.`;
-    }
-  } else {
-    projectDescription = (await userInterface.question('One-line description: ')).trim();
-  }
+  let projectDescription = (await userInterface.question(projectDescriptionPrompt)).trim();
 
   if (!projectDescription) {
-    projectDescription = `A ${projectName} project.`;
+    projectDescription = defaultProjectDescription || `A ${projectName} project.`;
   }
 
   const domainSelection = await askChoice(
@@ -327,79 +204,20 @@ export async function runProjectDiscovery(userInterface, options = {}) {
     authStrategy = (await userInterface.question('Describe your auth setup: ')).trim() || 'Custom auth';
   }
 
-  let dockerStrategy = DOCKER_STRATEGY_CHOICES[0];
-  if (isQuickMode) {
-    dockerStrategy = await askChoice(
-      'Containerization strategy:',
-      DOCKER_STRATEGY_CHOICES,
-      userInterface
-    );
-  } else {
-    const useDocker = await askYesNo(
-      'Use Docker for this project (development and/or production)?',
-      userInterface,
-      false
-    );
-
-    if (useDocker) {
-      const useDockerDevelopment = await askYesNo(
-        'Use Docker for development workflow?',
-        userInterface,
-        true
-      );
-      const useDockerProduction = await askYesNo(
-        'Use Docker for production runtime/build?',
-        userInterface,
-        true
-      );
-
-      dockerStrategy = resolveDockerStrategy({
-        useDocker,
-        useDockerDevelopment,
-        useDockerProduction,
-      });
-    }
-  }
-
-  const parsedDockerStrategy = parseDockerStrategy(dockerStrategy);
-
-  let features = [];
-  if (isQuickMode) {
-    const selectedFeaturePreset = await askChoice(
-      'Feature set:',
-      FEATURE_PRESET_CHOICES,
-      userInterface
-    );
+  const dockerStrategy = await askChoice(
+    'Containerization strategy:',
+    DOCKER_STRATEGY_CHOICES,
+    userInterface
+  );
 
-    if (selectedFeaturePreset === 'Other') {
-      features = await askFeatureList(userInterface);
-    } else {
-      features = FEATURE_PRESET_MAP[selectedFeaturePreset] || [];
-    }
-  } else {
-    features = await askFeatureList(userInterface);
-  }
+  let features = await askFeatureList(userInterface);
 
   if (features.length === 0) {
     features.push('Core functionality (define during development)');
   }
 
-  let additionalContext = 'No additional context provided.';
-  if (isQuickMode) {
-    const wantsAdditionalContext = await askYesNo(
-      'Add additional context now?',
-      userInterface,
-      false
-    );
-
-    if (wantsAdditionalContext) {
-      additionalContext = (await userInterface.question('Additional context: ')).trim()
-        || 'No additional context provided.';
-    }
-  } else {
-    additionalContext = (await userInterface.question('\nAdditional context (optional, press Enter to skip): ')).trim()
-      || 'No additional context provided.';
-  }
+  const additionalContext = (await userInterface.question('\nAdditional context (optional, press Enter to skip): ')).trim()
+    || 'No additional context provided.';
 
   return {
     projectName,
@@ -407,9 +225,7 @@ export async function runProjectDiscovery(userInterface, options = {}) {
     primaryDomain,
     databaseChoice,
     authStrategy,
-    dockerStrategy: parsedDockerStrategy.dockerStrategy,
-    useDockerDevelopment: parsedDockerStrategy.useDockerDevelopment,
-    useDockerProduction: parsedDockerStrategy.useDockerProduction,
+    dockerStrategy,
     features,
     additionalContext,
   };
@@ -490,6 +306,134 @@ function shouldBootstrapDesignDocument(discoveryAnswers, initContext) {
   return false;
 }
 
+function inferDesignKeywords(discoveryAnswers) {
+  const normalizedDescription = String(discoveryAnswers.projectDescription || '').toLowerCase();
+  const normalizedDomain = String(discoveryAnswers.primaryDomain || '').toLowerCase();
+  const normalizedFeatures = Array.isArray(discoveryAnswers.features)
+    ? discoveryAnswers.features.map((featureValue) => String(featureValue).toLowerCase()).join(' ')
+    : '';
+  const aggregateText = `${normalizedDescription} ${normalizedDomain} ${normalizedFeatures}`;
+
+  if (aggregateText.includes('commerce') || aggregateText.includes('catalog') || aggregateText.includes('checkout')) {
+    return {
+      brandAdjectives: ['clear', 'desirable', 'confident'],
+      antiAdjectives: ['cluttered', 'hesitant', 'coupon-noisy'],
+      distinctiveMoves: [
+        'Use product hierarchy and buying cues without turning the interface into a discount template.',
+        'Keep decision-critical information prominent while secondary merchandising stays quiet.',
+        'Let imagery and spacing create premium perception before decorative effects do.',
+      ],
+    };
+  }
+
+  if (aggregateText.includes('dashboard') || aggregateText.includes('operations') || aggregateText.includes('report')) {
+    return {
+      brandAdjectives: ['calm', 'precise', 'trustworthy'],
+      antiAdjectives: ['chaotic', 'gimmicky', 'visually exhausting'],
+      distinctiveMoves: [
+        'Prioritize scanning clarity and status recognition over decorative density.',
+        'Use visual weight to separate signal from operational noise.',
+        'Reserve strong accents for alerts, decisions, and state transitions only.',
+      ],
+    };
+  }
+
+  if (aggregateText.includes('developer') || aggregateText.includes('api') || aggregateText.includes('platform')) {
+    return {
+      brandAdjectives: ['precise', 'technical', 'transparent'],
+      antiAdjectives: ['vague', 'marketing-heavy', 'template-polished'],
+      distinctiveMoves: [
+        'Make structure and feedback feel exact without becoming sterile.',
+        'Use code-adjacent rhythm and hierarchy to build trust with technical users.',
+        'Keep complexity legible through spacing, grouping, and explicit interaction states.',
+      ],
+    };
+  }
+
+  if (aggregateText.includes('content') || aggregateText.includes('community') || aggregateText.includes('publish')) {
+    return {
+      brandAdjectives: ['editorial', 'warm', 'expressive'],
+      antiAdjectives: ['flat', 'anonymous', 'feed-generic'],
+      distinctiveMoves: [
+        'Build a strong reading rhythm so content feels curated rather than dumped into cards.',
+        'Use contrast and spacing to guide attention between creation, moderation, and discovery.',
+        'Give key interaction moments personality without sacrificing clarity.',
+      ],
+    };
+  }
+
+  return {
+    brandAdjectives: ['clear', 'human', 'distinct'],
+    antiAdjectives: ['generic', 'template-like', 'trend-chasing'],
+    distinctiveMoves: [
+      'Create a visual direction with one memorable tension instead of stacking fashionable effects.',
+      'Use rhythm, hierarchy, and motion intentionally so the interface feels authored.',
+      'Keep the system flexible enough to evolve with product scope without losing identity.',
+    ],
+  };
+}
+
+function buildDesignIntentSeed({
+  discoveryAnswers,
+  initContext,
+  architectureRecommendation,
+}) {
+  const inferredKeywords = inferDesignKeywords(discoveryAnswers);
+  const designSignals = architectureRecommendation?.designGuidance?.normalizedSignals || null;
+
+  return `${JSON.stringify({
+    mode: 'dynamic',
+    status: 'seed-needs-design-synthesis',
+    project: {
+      name: discoveryAnswers.projectName,
+      context: discoveryAnswers.projectDescription,
+      domain: discoveryAnswers.primaryDomain,
+      stack: toTitleCase(initContext.stackFileName),
+      blueprint: toTitleCase(initContext.blueprintFileName),
+    },
+    brandAdjectives: inferredKeywords.brandAdjectives,
+    antiAdjectives: inferredKeywords.antiAdjectives,
+    visualDirection: {
+      trendStance: 'trend-aware-not-trend-chasing',
+      distinctiveMoves: inferredKeywords.distinctiveMoves,
+      copiedReferenceAllowed: false,
+    },
+    experiencePrinciples: [
+      'Design must feel project-specific, not interchangeable with generic SaaS templates.',
+      'Major interface decisions must be explainable in product and user terms.',
+      'Accessibility, responsiveness, and implementation realism are non-negotiable.',
+    ],
+    forbiddenPatterns: [
+      'generic-saas-hero',
+      'copycat-brand-system',
+      'unjustified-default-gradients',
+      'placeholder-design-language',
+    ],
+    requiredDesignSections: [
+      'Design Intent and Product Personality',
+      'Audience and Use-Context Signals',
+      'Visual Direction and Distinctive Moves',
+      'Color System and Semantic Roles',
+      'Typography System and Hierarchy',
+      'Spacing, Layout Rhythm, and Density Strategy',
+      'Interaction, Motion, and Feedback Rules',
+      'Component Language and Shared Patterns',
+      'Accessibility Non-Negotiables',
+      'Responsive Strategy',
+      'Anti-Patterns to Avoid',
+      'Implementation Notes for Future UI Tasks',
+    ],
+    implementation: {
+      requiredDeliverables: ['docs/DESIGN.md', 'docs/design-intent.json'],
+      requireDesignRationale: true,
+      requireDistinctVisualDirection: true,
+      requireMachineReadableContract: true,
+      bootstrapPrompt: '.agent-context/prompts/bootstrap-design.md',
+    },
+    architectSignals: designSignals,
+  }, null, 2)}\n`;
+}
+
 function buildProjectContextBootstrapPrompt({
   discoveryAnswers,
   initContext,
@@ -576,35 +520,61 @@ function buildDesignBootstrapPrompt({
 }) {
   const designSignals = architectureRecommendation?.designGuidance?.normalizedSignals || null;
   const designSignalsJson = JSON.stringify(designSignals, null, 2);
+  const designIntentSeed = buildDesignIntentSeed({
+    discoveryAnswers,
+    initContext,
+    architectureRecommendation,
+  });
 
   return [
-    '# Bootstrap Prompt: Dynamic DESIGN.md Synthesis',
+    '# Bootstrap Prompt: Dynamic Design Contract Synthesis',
     '',
     `Protocol version: ${PROJECT_DOC_SYNTHESIS_PROMPT_VERSION}`,
     '',
     'You are the Lead UI/UX Art Director for this project.',
-    'Write docs/DESIGN.md from zero. Do not use generic template prose.',
+    'Create a dynamic design contract, not a fixed stylistic template.',
     '',
     '## Mission',
     `Author docs/DESIGN.md in ${docsLanguage.toUpperCase()} language with strong art direction and engineering-ready guidance.`,
+    'Keep docs/design-intent.json synchronized as the machine-readable source of design intent.',
+    '',
+    '## Deliverables',
+    '1. docs/DESIGN.md',
+    '2. docs/design-intent.json',
     '',
-    '## Required Sections',
+    '## Required DESIGN.md Sections',
     '1. Design Vision and Product Personality',
-    '2. Theme and Atmosphere Direction',
-    '3. Color System (tokens, semantic roles, accessibility rationale)',
-    '4. Typography System (pairing, scale, usage rules)',
-    '5. Spacing and Layout Rhythm',
-    '6. Motion and Interaction Principles',
-    '7. Component Language (cards, forms, nav, states)',
-    '8. Do and Don\'t Rules',
+    '2. Audience and Use-Context Signals',
+    '3. Visual Direction and Distinctive Moves',
+    '4. Color System (tokens, semantic roles, accessibility rationale)',
+    '5. Typography System (pairing, scale, usage rules)',
+    '6. Spacing, Layout Rhythm, and Density Strategy',
+    '7. Motion and Interaction Principles',
+    '8. Component Language (cards, forms, nav, states)',
     '9. Accessibility Non-Negotiables',
-    '10. Redesign Protocol (how to evolve without breaking design identity)',
+    '10. Responsive Strategy',
+    '11. Anti-Patterns to Avoid',
+    '12. Implementation Notes for Future UI Tasks',
+    '',
+    '## Required design-intent.json Fields',
+    '1. mode',
+    '2. status',
+    '3. project',
+    '4. brandAdjectives',
+    '5. antiAdjectives',
+    '6. visualDirection',
+    '7. experiencePrinciples',
+    '8. forbiddenPatterns',
+    '9. requiredDesignSections',
+    '10. implementation',
     '',
     '## Hard Rules',
     '1. No copy-paste from external style guides.',
     '2. Every major decision must include psychological/product rationale.',
     '3. Keep implementation feasible for the selected stack and blueprint.',
     '4. Keep tone decisive like an art director, not generic AI boilerplate.',
+    '5. Do not anchor the final design language to a famous brand reference. Translate inspiration into original project-specific principles.',
+    '6. Reject interchangeable hero layouts, generic SaaS gradients, and trend-chasing decoration unless the project context explicitly justifies them.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -619,10 +589,17 @@ function buildDesignBootstrapPrompt({
     designSignalsJson || 'null',
     '```',
     '',
+    '## Seed Machine Contract',
+    'Refine this seed instead of discarding it. Keep the final JSON aligned with the markdown design system.',
+    '```json',
+    designIntentSeed.trim(),
+    '```',
+    '',
     '## Required Execution',
-    '1. Create docs/DESIGN.md with complete content.',
-    '2. Ensure rules are practical for implementation and review.',
-    '3. After DESIGN.md exists, use it as first-class source for future UI tasks.',
+    '1. Create or update docs/DESIGN.md with complete content.',
+    '2. Create or update docs/design-intent.json with machine-readable design intent.',
+    '3. Ensure both files stay project-specific, dynamic, and practical for implementation and review.',
+    '4. After the contract exists, use it as a first-class source for future UI tasks.',
     '',
   ].join('\n');
 }
@@ -643,12 +620,14 @@ export async function generateProjectDocumentation(
 
   const docsDirectoryPath = path.join(targetDirectoryPath, 'docs');
   const promptsDirectoryPath = path.join(targetDirectoryPath, '.agent-context', 'prompts');
+  await ensureDirectory(docsDirectoryPath);
   await ensureDirectory(promptsDirectoryPath);
 
   const synthesisContext = buildSynthesisContext(discoveryAnswers, initContext);
   const { requiredDocFileNames } = resolveProjectDocTargets(discoveryAnswers);
   const expectedDocFileNames = [...requiredDocFileNames];
   const generatedPromptFileNames = [];
+  const materializedFileNames = [];
 
   const projectContextPromptFileName = 'bootstrap-project-context.md';
   const architectureRecommendation = initContext.architectureRecommendation || null;
@@ -677,8 +656,19 @@ export async function generateProjectDocumentation(
     await fs.writeFile(path.join(promptsDirectoryPath, designPromptFileName), designPromptContent, 'utf8');
     generatedPromptFileNames.push(designPromptFileName);
 
-    if (!expectedDocFileNames.includes('DESIGN.md')) {
-      expectedDocFileNames.push('DESIGN.md');
+    const designIntentSeedFileName = 'design-intent.json';
+    const designIntentSeedContent = buildDesignIntentSeed({
+      discoveryAnswers,
+      initContext: synthesisContext,
+      architectureRecommendation,
+    });
+    await fs.writeFile(path.join(docsDirectoryPath, designIntentSeedFileName), designIntentSeedContent, 'utf8');
+    materializedFileNames.push(designIntentSeedFileName);
+
+    for (const designContractFileName of UI_DESIGN_CONTRACT_FILE_NAMES) {
+      if (!expectedDocFileNames.includes(designContractFileName)) {
+        expectedDocFileNames.push(designContractFileName);
+      }
     }
   }
 
@@ -686,6 +676,7 @@ export async function generateProjectDocumentation(
     docsDirectoryPath,
     generatedFileNames: expectedDocFileNames,
     generatedPromptFileNames,
+    materializedFileNames,
     bootstrapMode: 'ai-synthesis',
     synthesisPromptVersion: PROJECT_DOC_SYNTHESIS_PROMPT_VERSION,
     templateVersion: PROJECT_DOC_TEMPLATE_VERSION,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.6",
+  "version": "3.0.7",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {

package/scripts/validate.mjs

@@ -211,19 +211,19 @@ const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     snippets: [
       '### 15. Universal SOP Consolidation',
       'Coding flow is blocked if `docs/architecture-decision-record.md` (or `docs/Architecture-Decision-Record.md`) is missing',
-      'UI implementation flow is blocked if `docs/DESIGN.md` is missing',
+      'UI implementation flow is blocked if `docs/DESIGN.md` or `docs/design-intent.json` is missing',
     ],
   },
   {
     path: '.agent-context/prompts/review-code.md',
     snippets: [
-      'Enforce Universal SOP hard gate: block coding flow when required project docs are missing (`docs/architecture-decision-record.md`, and for UI scope `docs/DESIGN.md`).',
+      'Enforce Universal SOP hard gate: block coding flow when required project docs are missing (`docs/architecture-decision-record.md`, and for UI scope `docs/DESIGN.md` plus `docs/design-intent.json`).',
     ],
   },
   {
     path: '.agent-context/prompts/refactor.md',
     snippets: [
-      '6. Enforce Universal SOP hard gate: stop implementation if `docs/architecture-decision-record.md` is missing, and for UI scope stop if `docs/DESIGN.md` is missing.',
+      '6. Enforce Universal SOP hard gate: stop implementation if `docs/architecture-decision-record.md` is missing, and for UI scope stop if `docs/DESIGN.md` or `docs/design-intent.json` is missing.',
     ],
   },
   {
@@ -231,7 +231,7 @@ const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
     snippets: [
       'Universal SOP hard block policy:',
       'Hard block: do not write application code until docs/project-brief.md and docs/architecture-decision-record.md exist.',
-      'For UI scope: if docs/DESIGN.md is missing, execute bootstrap-design prompt before implementing UI surfaces.',
+      'For UI scope: if docs/DESIGN.md or docs/design-intent.json is missing, execute bootstrap-design prompt before implementing UI surfaces.',
     ],
   },
 ];
@@ -250,10 +250,22 @@ const REQUIRED_TEMPLATE_FREE_BOOTSTRAP_SNIPPETS = [
     snippets: [
       'Project docs will be authored dynamically by your IDE assistant from these prompts.',
       'bootstrap-project-context.md',
+      'Seed docs:',
       'I prepared dynamic synthesis bootstrap prompts',
     ],
   },
 ];
+const REQUIRED_UPGRADE_UI_CONTRACT_WARNING_SNIPPETS = [
+  {
+    path: 'lib/cli/commands/upgrade.mjs',
+    snippets: [
+      'UI/frontend scope was detected, but the dynamic design contract is incomplete:',
+      'docs/design-intent.json',
+      'Upgrade synchronizes governance assets, but it does not author project-specific design docs automatically.',
+      'collectProjectMarkers',
+    ],
+  },
+];
 const FORBIDDEN_TEMPLATE_BOOTSTRAP_SNIPPETS = [
   {
     path: 'lib/cli/project-scaffolder.mjs',
@@ -1021,6 +1033,28 @@ async function validateTemplateFreeBootstrapCoverage() {
   }
 }
 
+async function validateUpgradeUiContractWarningCoverage() {
+  console.log('\nChecking upgrade UI contract warning coverage...');
+
+  for (const coverageRule of REQUIRED_UPGRADE_UI_CONTRACT_WARNING_SNIPPETS) {
+    const absoluteCoveragePath = join(ROOT_DIR, coverageRule.path);
+
+    if (!(await fileExists(absoluteCoveragePath))) {
+      fail(`Missing upgrade UI contract warning source: ${coverageRule.path}`);
+      continue;
+    }
+
+    const coverageContent = await readTextFile(absoluteCoveragePath);
+    for (const requiredSnippet of coverageRule.snippets) {
+      if (coverageContent.includes(requiredSnippet)) {
+        pass(`${coverageRule.path} includes upgrade UI contract warning snippet: ${requiredSnippet}`);
+      } else {
+        fail(`${coverageRule.path} is missing upgrade UI contract warning snippet: ${requiredSnippet}`);
+      }
+    }
+  }
+}
+
 async function validateDeterministicBoundaryEnforcementCoverage() {
   console.log('\nChecking deterministic boundary enforcement coverage...');
 
@@ -1289,6 +1323,7 @@ async function main() {
   await validateStackResearchEngineCoverage();
   await validateUniversalSopConsolidationCoverage();
   await validateTemplateFreeBootstrapCoverage();
+  await validateUpgradeUiContractWarningCoverage();
   await validateDeterministicBoundaryEnforcementCoverage();
   await validateStackResearchSnapshotState();
   await validateMcpConfiguration();