@ryuenn3123/agentic-senior-core 3.0.17 → 3.0.20

package/lib/cli/project-scaffolder/discovery.mjs

@@ -3,13 +3,18 @@ import fs from 'node:fs/promises';
 import { askChoice, askYesNo } from '../utils.mjs';
 import {
   ARCHITECTURE_STYLE_CHOICES,
-  AUTH_CHOICES,
-  DATABASE_CHOICES,
   DOCKER_STRATEGY_CHOICES,
-  DOMAIN_CHOICES,
   SUPPORTED_DOC_LANGUAGES,
 } from './constants.mjs';
 
+const PROJECT_SCOPE_CHOICES = [
+  'Frontend only',
+  'Backend only',
+  'Both (frontend + backend)',
+];
+
+const AGENT_RECOMMENDATION_REQUIRED = 'Agent recommendation required from current brief, repo evidence, and live official docs';
+
 function parseBooleanLikeValue(rawValue) {
   const normalizedValue = String(rawValue || '').trim().toLowerCase();
   if (['true', 'yes', 'y', '1'].includes(normalizedValue)) {
@@ -70,7 +75,7 @@ function resolveArchitectureStyle(rawArchitectureStyle) {
   const normalizedArchitectureStyle = String(rawArchitectureStyle || '').trim().toLowerCase();
 
   if (!normalizedArchitectureStyle) {
-    return ARCHITECTURE_STYLE_CHOICES[0];
+    return AGENT_RECOMMENDATION_REQUIRED;
   }
 
   if (normalizedArchitectureStyle === 'monolith' || normalizedArchitectureStyle === 'modular monolith') {
@@ -94,22 +99,6 @@ function resolveArchitectureStyle(rawArchitectureStyle) {
   return directMatch || ARCHITECTURE_STYLE_CHOICES[0];
 }
 
-async function askFeatureList(userInterface) {
-  console.log('\nList your key features (one per line, press Enter to finish):');
-
-  const features = [];
-  while (features.length < 10) {
-    const featureLine = (await userInterface.question(`  Feature ${features.length + 1}: `)).trim();
-    if (!featureLine) {
-      break;
-    }
-
-    features.push(featureLine);
-  }
-
-  return features;
-}
-
 export function normalizeDocsLanguage(rawDocsLanguage = 'en') {
   const normalizedDocsLanguage = String(rawDocsLanguage || 'en').trim().toLowerCase();
   return SUPPORTED_DOC_LANGUAGES.has(normalizedDocsLanguage) ? normalizedDocsLanguage : null;
@@ -117,8 +106,7 @@ export function normalizeDocsLanguage(rawDocsLanguage = 'en') {
 
 export async function runProjectDiscovery(userInterface, options = {}) {
   console.log('\n--- Project Setup ---');
-  console.log('I will ask one focused set of questions to bootstrap project context and documentation.');
-  console.log('This helps AI agents understand your project before writing code.\n');
+  console.log('I will ask the minimum needed questions, then let the AI agent recommend unresolved technical decisions from the brief, repo evidence, and live official docs.\n');
   console.log('You can answer in your own language.');
   console.log('CLI prompts stay in English, but non-English answers are fully supported.\n');
 
@@ -129,33 +117,25 @@ export async function runProjectDiscovery(userInterface, options = {}) {
     : true;
   const shouldAskForCiGuardrails = options.askForCiGuardrails !== false;
 
-  const projectNamePrompt = defaultProjectName
-    ? `Project name (press Enter to use folder name: ${defaultProjectName}): `
-    : 'Project name: ';
-
-  let projectName = (await userInterface.question(projectNamePrompt)).trim();
+  const projectName = defaultProjectName || 'Untitled project';
+  const briefPrompt = defaultProjectDescription
+    ? `One-line project brief (press Enter to use current brief): `
+    : 'One-line project brief (optional but recommended): ';
+  const projectBriefAnswer = (await userInterface.question(briefPrompt)).trim();
+  const projectDescription = projectBriefAnswer
+    || defaultProjectDescription
+    || 'Project brief unresolved. The AI agent must ask for or infer product context before implementation.';
+
+  const projectScope = await askChoice('Project scope:', PROJECT_SCOPE_CHOICES, userInterface);
+  const primaryDomain = projectScope === 'Frontend only'
+    ? 'Frontend/UI application'
+    : projectScope === 'Backend only'
+      ? 'Backend/API service'
+      : 'Fullstack product';
 
-  if (!projectName && defaultProjectName) {
-    projectName = defaultProjectName;
-  }
-
-  if (!projectName) {
-    throw new Error('Project name is required for documentation scaffolding.');
-  }
-
-  const projectDescriptionPrompt = defaultProjectDescription
-    ? `One-line description (press Enter to use: ${defaultProjectDescription}): `
-    : 'One-line description: ';
-
-  let projectDescription = (await userInterface.question(projectDescriptionPrompt)).trim();
-
-  if (!projectDescription) {
-    projectDescription = defaultProjectDescription || `A ${projectName} project.`;
-  }
-
-  const architectureStyle = await askChoice(
-    'Project topology:',
-    ARCHITECTURE_STYLE_CHOICES,
+  const dockerStrategy = await askChoice(
+    'Containerization strategy:',
+    DOCKER_STRATEGY_CHOICES,
     userInterface
   );
 
@@ -167,43 +147,17 @@ export async function runProjectDiscovery(userInterface, options = {}) {
     )
     : defaultIncludeCiGuardrails;
 
-  const domainSelection = await askChoice('Primary domain:', DOMAIN_CHOICES, userInterface);
-  let primaryDomain = domainSelection;
-  if (domainSelection === 'Other') {
-    primaryDomain = (await userInterface.question('Describe your domain: ')).trim() || 'Custom domain';
-  }
-
-  const databaseSelection = await askChoice('Database needs:', DATABASE_CHOICES, userInterface);
-  let databaseChoice = databaseSelection;
-  if (databaseSelection === 'Other') {
-    databaseChoice = (await userInterface.question('Describe your database setup: ')).trim() || 'Custom database';
-  }
-
-  const authSelection = await askChoice('Auth strategy:', AUTH_CHOICES, userInterface);
-  let authStrategy = authSelection;
-  if (authSelection === 'Other') {
-    authStrategy = (await userInterface.question('Describe your auth setup: ')).trim() || 'Custom auth';
-  }
-
-  const dockerStrategy = await askChoice(
-    'Containerization strategy:',
-    DOCKER_STRATEGY_CHOICES,
-    userInterface
-  );
-
-  const features = await askFeatureList(userInterface);
-
   return {
     projectName,
     projectDescription,
-    architectureStyle,
+    architectureStyle: AGENT_RECOMMENDATION_REQUIRED,
     includeCiGuardrails,
     primaryDomain,
-    databaseChoice,
-    authStrategy,
+    databaseChoice: AGENT_RECOMMENDATION_REQUIRED,
+    authStrategy: AGENT_RECOMMENDATION_REQUIRED,
     dockerStrategy,
-    features,
-    additionalContext: 'No additional context provided.',
+    features: [],
+    additionalContext: 'Fresh-project technical decisions are intentionally unresolved. The AI agent must recommend them from current context and official docs before coding.',
   };
 }
 
@@ -299,9 +253,9 @@ export async function loadProjectConfig(configFilePath) {
     projectDescription: configEntries.projectDescription || configEntries.description || '',
     architectureStyle: resolveArchitectureStyle(configEntries.architectureStyle || configEntries.topology || configEntries.serviceTopology),
     includeCiGuardrails: parseBooleanLikeValue(configEntries.includeCiGuardrails) ?? parseBooleanLikeValue(configEntries.ci) ?? true,
-    primaryDomain: configEntries.primaryDomain || configEntries.domain || 'API service',
-    databaseChoice: configEntries.databaseChoice || configEntries.database || 'None (stateless service)',
-    authStrategy: configEntries.authStrategy || configEntries.auth || 'None (public service)',
+    primaryDomain: configEntries.primaryDomain || configEntries.domain || AGENT_RECOMMENDATION_REQUIRED,
+    databaseChoice: configEntries.databaseChoice || configEntries.database || AGENT_RECOMMENDATION_REQUIRED,
+    authStrategy: configEntries.authStrategy || configEntries.auth || AGENT_RECOMMENDATION_REQUIRED,
     dockerStrategy: resolveDockerStrategy({
       dockerStrategy: configEntries.dockerStrategy || configEntries.containerStrategy,
       useDocker: configEntries.useDocker,

package/lib/cli/project-scaffolder/prompt-builders.mjs

@@ -1,6 +1,5 @@
 import { toTitleCase } from '../utils.mjs';
 import {
-  ARCHITECTURE_STYLE_CHOICES,
   PROJECT_DOC_SYNTHESIS_PROMPT_VERSION,
 } from './constants.mjs';
 import { buildDesignIntentSeed } from './design-contract.mjs';
@@ -10,7 +9,6 @@ export function buildProjectContextBootstrapPrompt({
   initContext,
   expectedDocFileNames,
   docsLanguage,
-  architectureRecommendation,
 }) {
   const featuresList = Array.isArray(discoveryAnswers.features) && discoveryAnswers.features.length > 0
     ? discoveryAnswers.features.map((feature, featureIndex) => `${featureIndex + 1}. ${feature}`).join('\n')
@@ -20,19 +18,6 @@ export function buildProjectContextBootstrapPrompt({
     .map((fileName, fileIndex) => `${fileIndex + 1}. docs/${fileName}`)
     .join('\n');
 
-  const architectureSnapshot = architectureRecommendation
-    ? JSON.stringify({
-      briefType: architectureRecommendation.briefType,
-      stack: architectureRecommendation.recommendedStackFileName,
-      blueprint: architectureRecommendation.recommendedBlueprintFileName,
-      confidenceLabel: architectureRecommendation.confidenceLabel,
-      confidenceScore: architectureRecommendation.confidenceScore,
-      signalSummary: architectureRecommendation.signalSummary,
-      uncertaintyNotes: architectureRecommendation.uncertaintyNotes,
-      failureModes: architectureRecommendation.failureModes,
-    }, null, 2)
-    : 'null';
-
   return [
     '# Bootstrap Prompt: Dynamic Project Context Synthesis',
     '',
@@ -47,8 +32,8 @@ export function buildProjectContextBootstrapPrompt({
     '',
     '## Hard Rules',
     '1. No copy-paste from external prose.',
-    '2. Every major section must explain rationale and tradeoffs.',
-    '3. Keep stack, database, and auth aligned with the project constraints below unless user explicitly requests migration.',
+    '2. Every major section must explain rationale, constraints, and required action.',
+    '3. Keep database, auth, runtime, and architecture aligned with explicit project constraints below unless user requests migration.',
     '4. Output must be implementation-ready for engineers, not generic textbook explanation.',
     '5. For any ecosystem or technology claim, perform live web research and include citation metadata (source + fetchedAt timestamp) rather than relying on offline heuristics.',
     '6. Write for native English speakers at an 8th-grade reading level. Use clear, direct, plain language.',
@@ -56,22 +41,23 @@ export function buildProjectContextBootstrapPrompt({
     '8. Separate confirmed facts from assumptions explicitly. When context is incomplete, add an `Assumptions to Validate` section and a `Next Validation Action` line.',
     '9. If user inputs conflict with repo evidence, call out the conflict and choose the safer interpretation instead of silently forcing a generic answer.',
     '10. Do not invent modules or architecture layers only to make the docs look complete.',
-    '11. Prefer the latest stable compatible framework and package versions. If an official framework setup flow yields newer, better-supported defaults than manual package assembly, prefer that path.',
-    '12. Treat project topology as a design constraint: if the project is a monolith, explain why that shape is sufficient; if it is a microservice or distributed system, explain the service boundary logic and why the split is justified.',
+    '11. If runtime or framework setup is unresolved, recommend the latest stable compatible option from the brief, constraints, and live official documentation before coding. If an official setup flow yields newer, better-supported defaults than manual package assembly, use that path after approval.',
+    '12. Treat topology as an agent decision unless the user explicitly constrained it. If monolith fits, explain why. If a service split fits, document the evidence and service boundary logic.',
+    '13. Required docs coverage must include feature plan, architecture rationale, flow, public API or integration contracts when relevant, data model when relevant, UI/design when relevant, security assumptions, testing strategy, runtime/deployment notes, and next validation actions.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
     `- Project description: ${discoveryAnswers.projectDescription}`,
-    `- Project topology: ${discoveryAnswers.architectureStyle || ARCHITECTURE_STYLE_CHOICES[0]}`,
+    `- Project topology decision: ${discoveryAnswers.architectureStyle}`,
     `- Primary domain: ${discoveryAnswers.primaryDomain}`,
     `- Database strategy: ${discoveryAnswers.databaseChoice}`,
     `- Auth strategy: ${discoveryAnswers.authStrategy}`,
     `- Docker strategy: ${discoveryAnswers.dockerStrategy}`,
     `- Runtime environment: ${initContext.runtimeEnvironmentLabel || initContext.runtimeEnvironmentKey || 'Linux'}`,
-    `- Selected stack: ${toTitleCase(initContext.stackFileName)}`,
-    `- Selected blueprint: ${toTitleCase(initContext.blueprintFileName)}`,
-    `- Additional stacks: ${Array.isArray(initContext.additionalStackFileNames) && initContext.additionalStackFileNames.length > 0 ? initContext.additionalStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ') : 'none'}`,
-    `- Additional blueprints: ${Array.isArray(initContext.additionalBlueprintFileNames) && initContext.additionalBlueprintFileNames.length > 0 ? initContext.additionalBlueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName)).join(', ') : 'none'}`,
+    `- Runtime constraint: ${initContext.stackFileName === 'agent-decision-runtime.md' ? 'agent recommendation required before coding' : toTitleCase(initContext.stackFileName)}`,
+    `- Architecture constraint: ${initContext.blueprintFileName === 'agent-decision-architecture.md' ? 'agent recommendation required before coding' : toTitleCase(initContext.blueprintFileName)}`,
+    `- Additional runtime constraints: ${Array.isArray(initContext.additionalStackFileNames) && initContext.additionalStackFileNames.length > 0 ? initContext.additionalStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ') : 'none'}`,
+    `- Additional architecture constraints: ${Array.isArray(initContext.additionalBlueprintFileNames) && initContext.additionalBlueprintFileNames.length > 0 ? initContext.additionalBlueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName)).join(', ') : 'none'}`,
     '',
     '## Key Features',
     featuresList,
@@ -79,11 +65,6 @@ export function buildProjectContextBootstrapPrompt({
     '## Additional Context',
     discoveryAnswers.additionalContext || 'No additional context provided.',
     '',
-    '## Architecture Brief Snapshot (for grounding)',
-    '```json',
-    architectureSnapshot,
-    '```',
-    '',
     '## Required Execution',
     '1. Create all required docs files listed above with complete Markdown content.',
     '2. Make the docs adaptive to the real repo and prompt context. These are living references, not frozen templates.',
@@ -98,12 +79,10 @@ export function buildDesignBootstrapPrompt({
   discoveryAnswers,
   initContext,
   docsLanguage,
-  architectureRecommendation,
 }) {
   const designIntentSeed = buildDesignIntentSeed({
     discoveryAnswers,
     initContext,
-    architectureRecommendation,
   });
 
   return [
@@ -133,7 +112,7 @@ export function buildDesignBootstrapPrompt({
     '8. Responsive Strategy and Cross-Viewport Adaptation Matrix',
     '9. Motion and Interaction Principles',
     '10. Component Language and Morphology (cards, forms, nav, states)',
-    '11. Context Hygiene and Approved Reference Boundaries',
+    '11. Context Hygiene and Source Boundaries',
     '12. Accessibility Non-Negotiables',
     '13. Anti-Patterns to Avoid',
     '14. Implementation Notes for Future UI Tasks',
@@ -153,47 +132,57 @@ export function buildDesignBootstrapPrompt({
     '12. motionSystem',
     '13. componentMorphology',
     '14. accessibilityPolicy',
-    '15. visualQaPolicy',
-    '16. contextHygiene',
-    '17. experiencePrinciples',
-    '18. forbiddenPatterns',
-    '19. validationHints',
-    '20. requiredDesignSections',
-    '21. implementation',
-    '22. repoEvidence when onboarding or detector evidence exists',
+    '15. designExecutionPolicy',
+    '16. designExecutionHandoff',
+    '17. reviewRubric',
+    '18. contextHygiene',
+    '19. experiencePrinciples',
+    '20. forbiddenPatterns',
+    '21. validationHints',
+    '22. requiredDesignSections',
+    '23. implementation',
+    '24. repoEvidence when onboarding or detector evidence exists',
     '',
     '## 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.',
+    '3. Do not choose the final style, framework, component library, animation library, palette, typography, or layout paradigm from this offline scaffold. If unresolved, require an agent recommendation from repo evidence and live official docs before coding.',
     '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.',
+    '5. Do not anchor the final design language to famous products, benchmark visuals, or external reference surfaces.',
     '6. Reject interchangeable hero layouts, generic SaaS gradients, and trend-chasing decoration unless the project context explicitly justifies them.',
     '7. Encode color intent in perceptual terms first. Hex values may exist only as implementation derivatives.',
-    '8. Token guidance must define primitive, semantic, and component layers plus aliasing rules. Component tokens should consume semantic aliases instead of raw values.',
+    '8. Token guidance must define primitive, semantic, and component layers plus aliasing rules. Component tokens must consume semantic aliases instead of raw values.',
     '9. Responsive guidance must include layout mutation rules for mobile, tablet, and desktop. Shrinking the desktop layout is not enough.',
-    '10. Motion can be bold, cinematic, or highly expressive when it improves memorability, hierarchy, feedback, or product confidence. Optimize it instead of flattening it. Only reject motion when it harms clarity, accessibility, or runtime performance.',
-    '11. Define component morphology across interaction states and viewports so cards, forms, nav, and feedback surfaces adapt coherently instead of only resizing.',
-    '12. Keep UI-only requests context-isolated. Load frontend design rules first and do not eagerly load backend-only rules unless the task explicitly crosses those boundaries.',
-    '13. Treat WCAG 2.2 AA as the hard accessibility floor. Use APCA only as advisory perceptual tuning, never as a reason to waive a WCAG failure.',
-    '14. Accessibility planning must explicitly cover focus visibility, focus appearance, target size, accessible authentication, keyboard access, and dynamic status/state access.',
-    '15. Hybrid visual QA must stay deterministic-first. Define screenshot-baseline expectations, dynamic masking rules, noise thresholds, required mobile/tablet/desktop coverage, and long-page capture strategy before relying on semantic review.',
-    '16. Do not treat one screenshot as enough for a long page. Require above-fold capture, full-page capture when stable, and anchor-based section or tiled-scroll captures for deep pages.',
-    '17. Only escalate visual diffs to a semantic judge when deterministic evidence shows meaningful drift or missing required coverage.',
-    '18. Treat prior website memory, unrelated project aesthetics, and remembered screenshots as tainted context unless the user explicitly approves continuity.',
-    '19. Design continuity is opt-in. If no approved continuity exists, synthesize from the current repo evidence, current brief, and current project docs only.',
-    '20. Make at least one memorable visual bet so the resulting system is recognizable and not template-neutral.',
+    '10. Do not let repeated surfaces, component-kit defaults, or safe typography become the final direction without explicit product rationale.',
+    '11. The LLM must choose color, type, spacing, density, morphology, and motion dynamically from the active project context instead of copying this seed.',
+    '12. Viewport mutation must be operation-based. For each viewport, define the primary mutation operation, required surface actions, and forbidden responsive fallback patterns.',
+    '13. Motion can be bold, cinematic, or highly expressive when it improves memorability, hierarchy, feedback, or product confidence. If a motion library is needed, research current official docs and select the latest stable compatible option instead of using an offline default. Only reject motion when it harms clarity, accessibility, or runtime performance.',
+    '14. Define component morphology across interaction states and viewports so cards, forms, nav, and feedback surfaces adapt coherently instead of only resizing.',
+    '15. Keep UI-only requests context-isolated. Load frontend design rules first and do not eagerly load backend-only or workflow-only rules unless the task explicitly crosses those boundaries.',
+    '16. Treat WCAG 2.2 AA as the hard accessibility floor. Use APCA only as advisory perceptual tuning, never as a reason to waive a WCAG failure.',
+    '17. Accessibility planning must explicitly cover focus visibility, focus appearance, target size, accessible authentication, keyboard access, and dynamic status/state access.',
+    '18. Structured design execution must stay representation-first. Define a surface plan, component graph, content-priority map, viewport mutation plan, and interaction-state matrix before relying on semantic review.',
+    '19. design-intent.json must carry an explicit structured handoff, not just policy flags. The handoff must make surface plans, component relationships, task flow, and signature moves executable before coding starts.',
+    '20. Do not depend on screenshot capture, browser automation, or image diff artifacts as the default path. The contract must be strong enough to guide precise UI from repo evidence, component logic, and user intent alone.',
+    '21. Semantic review must judge contract fidelity, distinctiveness, hierarchy, state behavior, and viewport mutation directly from the contract and changed UI code.',
+    '22. Treat prior website memory, unrelated project aesthetics, and remembered screenshots as tainted context unless the user explicitly approves continuity.',
+    '23. Design continuity is opt-in. If no approved continuity exists, synthesize from the current repo evidence, current brief, and current project docs only.',
+    '24. Make at least one memorable visual bet so the resulting system is recognizable and not template-neutral.',
+    '25. Define a stable review rubric for distinctiveness, contract fidelity, visual consistency, heuristic UX quality, and motion discipline.',
+    '26. Genericity findings must name the actual drift signal. Do not label something generic without explaining the anti-pattern or rubric dimension.',
+    '27. Review rubric must support automatic genericity failure when named drift signals dominate a redesign or new UI surface.',
+    '28. Separate taste from failure. Bold direction is allowed when it still follows the contract, serves the product, and stays accessible.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
     `- Product context: ${discoveryAnswers.projectDescription}`,
-    `- Project topology: ${discoveryAnswers.architectureStyle || ARCHITECTURE_STYLE_CHOICES[0]}`,
+    `- Project topology decision: ${discoveryAnswers.architectureStyle}`,
     `- Domain: ${discoveryAnswers.primaryDomain}`,
-    `- Stack: ${toTitleCase(initContext.stackFileName)}`,
-    `- Blueprint: ${toTitleCase(initContext.blueprintFileName)}`,
+    `- Runtime constraint: ${initContext.stackFileName === 'agent-decision-runtime.md' ? 'agent recommendation required before coding' : toTitleCase(initContext.stackFileName)}`,
+    `- Architecture constraint: ${initContext.blueprintFileName === 'agent-decision-architecture.md' ? 'agent recommendation required before coding' : toTitleCase(initContext.blueprintFileName)}`,
     '',
     '## Seed Machine Contract',
-    'Refine this seed instead of discarding it. Keep the final JSON aligned with the markdown design system.',
+    'Refine this scaffold seed instead of discarding it. Keep the structural fields that are already valid, but replace all placeholder expressive direction with agent-chosen decisions grounded in repo evidence, the active brief, and live official docs when technology choices matter.',
     '```json',
     designIntentSeed.trim(),
     '```',
@@ -203,11 +192,14 @@ export function buildDesignBootstrapPrompt({
     '2. Create or update docs/design-intent.json with machine-readable design intent.',
     '3. Keep both files synchronized: the markdown explains the rationale and the JSON captures the machine-readable contract.',
     '4. Encode accessibility as a split policy: WCAG 2.2 AA hard floor, APCA advisory readability tuning, and explicit hard-vs-advisory checks.',
-    '5. Encode hybrid visual QA as policy: deterministic-first screenshot review, approved masking categories, stability thresholds, required mobile/tablet/desktop coverage, long-page capture strategy, and semantic escalation boundaries.',
-    '6. Make long-page handling explicit: above-fold capture, full-page capture when stable, and anchor-based section or tiled-scroll captures when one image would miss deep content.',
-    '7. Preserve repoEvidence.designEvidenceSummary when onboarding or detector evidence exists instead of discarding it.',
-    '8. Ensure both files stay project-specific, dynamic, and practical for implementation and review.',
-    '9. After the contract exists, use it as a first-class source for future UI tasks.',
+    '5. Encode structured design execution as policy: representation strategy, surface plan, component graph, content-priority map, viewport mutation plan, interaction-state matrix, semantic review focus, and structured handoff requirements.',
+    '6. Encode an explicit structured handoff inside docs/design-intent.json: surface plan, component graph, content-priority map, viewport mutation plan, interaction-state matrix, task-flow narrative, and signature move rationale.',
+    '7. Encode a stable review rubric: required dimensions, genericity signals, valid bold signals, and reporting rules that separate taste from real failure.',
+    '8. Make the handoff executable without screenshot dependency. The contract must still guide high-precision UI generation from repo evidence and changed code alone.',
+    '9. Preserve repoEvidence.designEvidenceSummary when onboarding or detector evidence exists instead of discarding it.',
+    '10. If repoEvidence.designEvidenceSummary.structuredInspection exists, use it as stronger evidence for class surfaces, inline style bypasses, and expression-backed UI structure before defaulting to generic assumptions.',
+    '11. Ensure both files stay project-specific, dynamic, and practical for implementation and review. The seed may guide structure, but it must not decide style offline.',
+    '12. After the contract exists, use it as a first-class source for future UI tasks.',
     '',
   ].join('\n');
 }

package/lib/cli/project-scaffolder/storage.mjs

@@ -45,13 +45,11 @@ export async function generateProjectDocumentation(
   const materializedFileNames = [];
 
   const projectContextPromptFileName = 'bootstrap-project-context.md';
-  const architectureRecommendation = initContext.architectureRecommendation || null;
   const projectContextPromptContent = buildProjectContextBootstrapPrompt({
     discoveryAnswers,
     initContext: synthesisContext,
     expectedDocFileNames,
     docsLanguage: normalizedDocsLanguage,
-    architectureRecommendation,
   });
   await fs.writeFile(
     path.join(promptsDirectoryPath, projectContextPromptFileName),
@@ -66,7 +64,6 @@ export async function generateProjectDocumentation(
       discoveryAnswers,
       initContext: synthesisContext,
       docsLanguage: normalizedDocsLanguage,
-      architectureRecommendation,
     });
     await fs.writeFile(path.join(promptsDirectoryPath, designPromptFileName), designPromptContent, 'utf8');
     generatedPromptFileNames.push(designPromptFileName);
@@ -75,7 +72,6 @@ export async function generateProjectDocumentation(
     const designIntentSeedContent = buildDesignIntentSeed({
       discoveryAnswers,
       initContext: synthesisContext,
-      architectureRecommendation,
     });
     await fs.writeFile(path.join(docsDirectoryPath, designIntentSeedFileName), designIntentSeedContent, 'utf8');
     materializedFileNames.push(designIntentSeedFileName);

package/lib/cli/token-optimization.mjs

@@ -253,7 +253,7 @@ export function buildTokenOptimizationGuidanceBlock(tokenOptimizationState) {
   );
 
   const fallbackGuidance = [
-    '- Prefer command variants with bounded output (for example: git diff --stat, rg --max-count, and npm test -- --reporter=dot).',
+    '- Use command variants with bounded output such as git diff --stat, rg --max-count, and npm test -- --reporter=dot.',
     '- Request only the lines or sections required for the current decision.',
     '- If shell output is still large, summarize and continue iteratively instead of dumping full logs.',
   ];

package/lib/cli/utils.mjs

@@ -38,9 +38,9 @@ export function printUsage() {
   console.log('Options:');
   console.log('  --help       Show help');
   console.log('  --version    Show CLI version');
-  console.log(`  --preset     Use a plug-and-play starter preset (${presetNames})`);
-  console.log('  --stack      Override stack selection');
-  console.log('  --blueprint  Override blueprint selection');
+  console.log(`  --preset     Use a scope hint preset; it does not choose stack/framework (${presetNames})`);
+  console.log('  --stack      Explicit runtime constraint from the user');
+  console.log('  --blueprint  Explicit architecture constraint from the user');
   console.log('  --project-description  Project intent text used to build an offline architecture brief before agent-led live research');
   console.log('  --ci         Override CI/CD quality checks (guardrails) (true|false)');
   console.log('  --token-optimize  Explicitly enable token optimization policy during init (default behavior)');
@@ -211,7 +211,35 @@ async function collectRelativeTreeEntries(baseDirectoryPath, relativeRootPath) {
   return { files, directories };
 }
 
-async function buildManagedSourceManifest() {
+async function collectOptionalManagedEntries(baseDirectoryPath, options = {}) {
+  const files = new Set();
+  const directories = new Set();
+
+  if (options.includeMcpTemplate === true) {
+    const mcpServerEntrypointPath = path.join(baseDirectoryPath, 'scripts', 'mcp-server.mjs');
+    if (await pathExists(mcpServerEntrypointPath)) {
+      files.add('scripts/mcp-server.mjs');
+    }
+
+    const mcpServerHelpersDirectoryPath = path.join(baseDirectoryPath, 'scripts', 'mcp-server');
+    const mcpServerTreeEntries = await collectRelativeTreeEntries(
+      mcpServerHelpersDirectoryPath,
+      'scripts/mcp-server'
+    );
+
+    for (const relativeFilePath of mcpServerTreeEntries.files) {
+      files.add(relativeFilePath);
+    }
+
+    for (const relativeDirectoryPath of mcpServerTreeEntries.directories) {
+      directories.add(relativeDirectoryPath);
+    }
+  }
+
+  return { files, directories };
+}
+
+async function buildManagedSourceManifest(options = {}) {
   const sourceFiles = new Set();
   const sourceDirectories = new Set();
 
@@ -237,13 +265,21 @@ async function buildManagedSourceManifest() {
     sourceFiles.add(toPosixRelativePath(entryPointFileName));
   }
 
+  const optionalManagedEntries = await collectOptionalManagedEntries(REPO_ROOT, options);
+  for (const sourceFilePath of optionalManagedEntries.files) {
+    sourceFiles.add(sourceFilePath);
+  }
+  for (const sourceDirectoryPath of optionalManagedEntries.directories) {
+    sourceDirectories.add(sourceDirectoryPath);
+  }
+
   return {
     files: sourceFiles,
     directories: sourceDirectories,
   };
 }
 
-async function collectManagedTargetManifest(resolvedTargetDirectoryPath) {
+async function collectManagedTargetManifest(resolvedTargetDirectoryPath, options = {}) {
   const targetFiles = new Set();
   const targetDirectories = new Set();
 
@@ -269,6 +305,14 @@ async function collectManagedTargetManifest(resolvedTargetDirectoryPath) {
     targetFiles.add(toPosixRelativePath(entryPointFileName));
   }
 
+  const optionalManagedEntries = await collectOptionalManagedEntries(resolvedTargetDirectoryPath, options);
+  for (const targetFilePath of optionalManagedEntries.files) {
+    targetFiles.add(targetFilePath);
+  }
+  for (const targetDirectoryPath of optionalManagedEntries.directories) {
+    targetDirectories.add(targetDirectoryPath);
+  }
+
   return {
     files: targetFiles,
     directories: targetDirectories,
@@ -283,8 +327,8 @@ export async function analyzeManagedGovernanceSurface(
     ? options.preservePathPrefixes
     : ['.agent-context/state'];
 
-  const sourceManifest = await buildManagedSourceManifest();
-  const targetManifest = await collectManagedTargetManifest(resolvedTargetDirectoryPath);
+  const sourceManifest = await buildManagedSourceManifest(options);
+  const targetManifest = await collectManagedTargetManifest(resolvedTargetDirectoryPath, options);
 
   const staleFiles = [];
   const staleDirectories = [];
@@ -332,14 +376,18 @@ export async function analyzeManagedGovernanceSurface(
     managedTargetFileCount: targetManifest.files.size,
     managedTargetDirectoryCount: targetManifest.directories.size,
   };
-}export async function copyGovernanceAssetsToTarget(
+}
+
+export async function copyGovernanceAssetsToTarget(
   resolvedTargetDirectoryPath,
   options = {}
 ) {
   const shouldIncludeMcpTemplate = options.includeMcpTemplate === true;
   const shouldPruneManagedSurface = options.pruneManagedSurface === true;
   const managedSurfacePlan = shouldPruneManagedSurface
-    ? options.managedSurfacePlan || await analyzeManagedGovernanceSurface(resolvedTargetDirectoryPath)
+    ? options.managedSurfacePlan || await analyzeManagedGovernanceSurface(resolvedTargetDirectoryPath, {
+      includeMcpTemplate: shouldIncludeMcpTemplate,
+    })
     : null;
   const deletedManagedFiles = [];
   const deletedManagedDirectories = [];
@@ -415,6 +463,24 @@ export async function analyzeManagedGovernanceSurface(
     if (mcpServerSync.status === 'created') createdFiles.push('scripts/mcp-server.mjs');
     else if (mcpServerSync.status === 'updated') updatedFiles.push('scripts/mcp-server.mjs');
 
+    const sourceMcpHelpersDirectoryPath = path.join(REPO_ROOT, 'scripts', 'mcp-server');
+    if (await pathExists(sourceMcpHelpersDirectoryPath)) {
+      const mcpHelperTreeEntries = await collectRelativeTreeEntries(
+        sourceMcpHelpersDirectoryPath,
+        'scripts/mcp-server'
+      );
+
+      for (const relativeHelperFilePath of mcpHelperTreeEntries.files) {
+        const sourceHelperFilePath = path.join(REPO_ROOT, ...relativeHelperFilePath.split('/'));
+        const targetHelperFilePath = path.join(resolvedTargetDirectoryPath, ...relativeHelperFilePath.split('/'));
+        const helperSyncResult = await syncFile(sourceHelperFilePath, targetHelperFilePath);
+
+        if (helperSyncResult.status === 'created') createdFiles.push(relativeHelperFilePath);
+        else if (helperSyncResult.status === 'updated') updatedFiles.push(relativeHelperFilePath);
+        else if (helperSyncResult.status === 'unchanged') unchangedFiles.push(relativeHelperFilePath);
+      }
+    }
+
     // 1. VS Code (Workspace Local Settings)
     const vscodeMcpJsonPath = path.join(resolvedTargetDirectoryPath, '.vscode', 'mcp.json');
     const vscodeWorkspaceMcpConfig = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.17",
+  "version": "3.0.20",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -66,6 +66,6 @@
     "report:docs-quality-drift": "node ./scripts/docs-quality-drift-report.mjs",
     "report:governance-weekly": "node ./scripts/governance-weekly-report.mjs",
     "validate": "node ./scripts/validate.mjs",
-    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/enterprise-ops.test.mjs"
+    "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/ui-rubric-calibration.test.mjs ./tests/operations.test.mjs"
   }
 }