@ryuenn3123/agentic-senior-core 3.0.11 → 3.0.13

package/lib/cli/project-scaffolder.mjs

@@ -6,7 +6,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { ensureDirectory, askChoice, toTitleCase, pathExists } from './utils.mjs';
+import { ensureDirectory, askChoice, askYesNo, toTitleCase, pathExists } from './utils.mjs';
 
 const SUPPORTED_DOC_LANGUAGES = new Set(['en', 'id']);
 const PROJECT_DOC_FILE_NAMES = [
@@ -137,14 +137,18 @@ export function normalizeDocsLanguage(rawDocsLanguage = 'en') {
  * Returns a structured object with all user responses.
  */
 export async function runProjectDiscovery(userInterface, options = {}) {
-  console.log('\n--- Project Discovery ---');
-  console.log('I will ask a few questions to generate project-specific documentation.');
+  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('You can answer in your own language.');
   console.log('CLI prompts stay in English, but non-English answers are fully supported.\n');
 
   const defaultProjectName = (options.defaultProjectName || '').trim();
   const defaultProjectDescription = String(options.defaultProjectDescription || '').trim();
+  const defaultIncludeCiGuardrails = typeof options.defaultIncludeCiGuardrails === 'boolean'
+    ? options.defaultIncludeCiGuardrails
+    : true;
+  const shouldAskForCiGuardrails = options.askForCiGuardrails !== false;
   let projectName = '';
 
   const projectNamePrompt = defaultProjectName
@@ -171,6 +175,14 @@ export async function runProjectDiscovery(userInterface, options = {}) {
     projectDescription = defaultProjectDescription || `A ${projectName} project.`;
   }
 
+  const includeCiGuardrails = shouldAskForCiGuardrails
+    ? await askYesNo(
+      'Enable CI/CD quality checks (guardrails) and the LLM Judge policy?',
+      userInterface,
+      defaultIncludeCiGuardrails
+    )
+    : defaultIncludeCiGuardrails;
+
   const domainSelection = await askChoice(
     'Primary domain:',
     DOMAIN_CHOICES,
@@ -210,24 +222,18 @@ export async function runProjectDiscovery(userInterface, options = {}) {
     userInterface
   );
 
-  let features = await askFeatureList(userInterface);
-
-  if (features.length === 0) {
-    features.push('Core functionality (define during development)');
-  }
-
-  const additionalContext = (await userInterface.question('\nAdditional context (optional, press Enter to skip): ')).trim()
-    || 'No additional context provided.';
+  const features = await askFeatureList(userInterface);
 
   return {
     projectName,
     projectDescription,
+    includeCiGuardrails,
     primaryDomain,
     databaseChoice,
     authStrategy,
     dockerStrategy,
     features,
-    additionalContext,
+    additionalContext: 'No additional context provided.',
   };
 }
 
@@ -315,7 +321,7 @@ const DESIGN_REQUIRED_SECTIONS = [
   'Spacing, Layout Rhythm, and Density Strategy',
   'Responsive Strategy and Cross-Viewport Adaptation Matrix',
   'Interaction, Motion, and Feedback Rules',
-  'Component Language and Shared Patterns',
+  'Component Language, Morphology, and Shared Patterns',
   'Accessibility Non-Negotiables',
   'Anti-Patterns to Avoid',
   'Implementation Notes for Future UI Tasks',
@@ -343,6 +349,17 @@ function inferDesignKeywords(discoveryAnswers) {
         'Keep decision-critical information prominent while secondary merchandising stays quiet.',
         'Let imagery and spacing create premium perception before decorative effects do.',
       ],
+      motionPurpose: 'Use restrained motion to reinforce buying confidence, product continuity, and feedback. Motion should feel premium, not promotional.',
+      motionChoreography: 'Favor short hover/focus transitions, sheet choreography, and product-media continuity. Avoid looping hero motion, autoplay spectacle, and parallax-heavy scenes.',
+      motionDurations: {
+        desktop: 180,
+        mobile: 240,
+      },
+      componentMorphology: {
+        mobile: 'Product cards should compress supporting metadata, pin purchase actions closer to the thumb zone, and move comparison into progressive disclosure or bottom sheets.',
+        tablet: 'Cards and merch modules should preserve comparison affordances while reducing tertiary chrome and keeping visual hierarchy stable.',
+        desktop: 'Cards can expand media, comparison, and reassurance copy while keeping buying cues dominant and visually disciplined.',
+      },
       mutationRules: {
         mobile: 'Convert browsing into vertically stacked product cards, move cart and filter actions into sticky or bottom-sheet patterns, and keep thumb-reach actions persistent.',
         tablet: 'Preserve browsing flow with a two-column rhythm, collapse tertiary filters, and keep comparison moments visible without forcing desktop density.',
@@ -365,6 +382,17 @@ function inferDesignKeywords(discoveryAnswers) {
         'Use visual weight to separate signal from operational noise.',
         'Reserve strong accents for alerts, decisions, and state transitions only.',
       ],
+      motionPurpose: 'Use motion as operational feedback and state continuity, never as ambient decoration that competes with dense information.',
+      motionChoreography: 'Prefer fast transitions for filters, drawers, status reveals, and row expansion. Avoid floaty choreography and ornamental motion that slows scanning.',
+      motionDurations: {
+        desktop: 160,
+        mobile: 220,
+      },
+      componentMorphology: {
+        mobile: 'Data rows should become prioritized cards or grouped summaries, with filters and secondary tools moving into sheets or drawers.',
+        tablet: 'Operational panels should retain split-view logic where possible, while tertiary panels collapse behind explicit toggles.',
+        desktop: 'Dense tables, side panels, and comparison surfaces can remain visible simultaneously, with state treatments optimized for rapid scanning.',
+      },
       mutationRules: {
         mobile: 'Collapse dense tables into prioritized cards or row groups, move filters into drawers or sheets, and pin the most critical actions to the bottom reach zone.',
         tablet: 'Keep two-column or split-pane workflows, collapse tertiary panels, and maintain fast scan paths for operators using touch or keyboard.',
@@ -387,6 +415,17 @@ function inferDesignKeywords(discoveryAnswers) {
         'Use code-adjacent rhythm and hierarchy to build trust with technical users.',
         'Keep complexity legible through spacing, grouping, and explicit interaction states.',
       ],
+      motionPurpose: 'Use motion to clarify causality, reveal system state, and preserve context during multi-pane technical workflows.',
+      motionChoreography: 'Prefer subtle panel transitions, command feedback, and disclosure motion. Avoid ornamental sweeps that make technical work feel imprecise.',
+      motionDurations: {
+        desktop: 170,
+        mobile: 230,
+      },
+      componentMorphology: {
+        mobile: 'Technical panes should flatten into sequential sections, with commands and diagnostics colocated near the content they affect.',
+        tablet: 'Split views should survive where useful, with explicit panel toggles and condensed chrome for code-adjacent tasks.',
+        desktop: 'Navigation, documentation, diagnostics, and active work surfaces can remain concurrently visible when it improves expert comprehension.',
+      },
       mutationRules: {
         mobile: 'Switch multi-pane technical layouts into stacked sections, turn secondary navigation into segmented or sheet-based controls, and keep commands near the content they affect.',
         tablet: 'Retain split-view comprehension where possible, compress chrome, and keep documentation or diagnostics adjacent to the active task.',
@@ -409,6 +448,17 @@ function inferDesignKeywords(discoveryAnswers) {
         'Use contrast and spacing to guide attention between creation, moderation, and discovery.',
         'Give key interaction moments personality without sacrificing clarity.',
       ],
+      motionPurpose: 'Use motion to support reading rhythm, reveal structure, and reward contribution moments without overwhelming long-form consumption.',
+      motionChoreography: 'Favor reveal choreography for section transitions, lightweight feedback on participation, and measured media behavior. Avoid constant background motion.',
+      motionDurations: {
+        desktop: 190,
+        mobile: 250,
+      },
+      componentMorphology: {
+        mobile: 'Reading surfaces should dominate while secondary discovery and community tools collapse behind sheets, tabs, or segmented controls.',
+        tablet: 'Editorial modules can balance reading and discovery, provided the primary narrative flow remains obvious.',
+        desktop: 'Long-form content, secondary navigation, and related discovery modules can coexist without fragmenting the reading rhythm.',
+      },
       mutationRules: {
         mobile: 'Prioritize reading and contribution flows in a single-column narrative stack, tuck secondary discovery tools behind sheets, and keep primary creation actions within reach.',
         tablet: 'Balance narrative reading with supporting discovery modules, using two-column compositions only where hierarchy stays obvious.',
@@ -430,6 +480,17 @@ function inferDesignKeywords(discoveryAnswers) {
       'Use rhythm, hierarchy, and motion intentionally so the interface feels authored.',
       'Keep the system flexible enough to evolve with product scope without losing identity.',
     ],
+    motionPurpose: 'Allow motion when it improves continuity, feedback, or perceived craft. Avoid banning motion outright, but reject decorative movement with no product value.',
+    motionChoreography: 'Use short, purposeful transitions and keep heavier choreography rare, opt-in, and explainable in product terms.',
+    motionDurations: {
+      desktop: 180,
+      mobile: 240,
+    },
+    componentMorphology: {
+      mobile: 'Primary components should simplify structure, prioritize direct tasks, and collapse supporting detail into explicit disclosure.',
+      tablet: 'Components should preserve hierarchy and task continuity while reducing density and compressing tertiary chrome.',
+      desktop: 'Components can expose richer states, denser supporting information, and broader navigation affordances without losing clarity.',
+    },
     mutationRules: {
       mobile: 'Stack primary tasks vertically, convert secondary navigation into thumb-friendly overlays or sheets, and simplify dense comparison layouts into progressive disclosure.',
       tablet: 'Preserve hierarchy with fewer columns, condensed chrome, and adaptive navigation that maintains task continuity.',
@@ -453,7 +514,14 @@ function buildDesignIntentContractObject({
     primaryDomain,
     features,
   });
-  const designSignals = architectureRecommendation?.designGuidance?.normalizedSignals || null;
+  const normalizedPrimaryDomain = String(primaryDomain || '').trim().toLowerCase();
+  const resolvedSpacingPattern = inferredKeywords.densityMode === 'dense'
+    ? 'compact-grid'
+    : normalizedPrimaryDomain.includes('mobile')
+      ? 'mobile-first-single-axis'
+      : inferredKeywords.densityMode === 'focused'
+        ? 'high-contrast-rhythm'
+        : 'balanced-grid';
 
   return {
     mode: 'dynamic',
@@ -476,14 +544,14 @@ function buildDesignIntentContractObject({
     mathSystems: {
       typographyScaleRatio: inferredKeywords.typographyScaleRatio,
       baseGridUnit: inferredKeywords.baseGridUnit,
-      spacingPattern: designSignals?.spacingPattern || 'balanced-grid',
+      spacingPattern: resolvedSpacingPattern,
       densityMode: inferredKeywords.densityMode,
     },
     colorTruth: {
       format: 'OKLCH',
       allowHexDerivatives: true,
       requirePerceptualLightnessCurve: true,
-      paletteRoles: designSignals?.paletteRoles || ['base', 'surface', 'accent'],
+      paletteRoles: ['base', 'surface', 'accent'],
       intent: inferredKeywords.colorIntent,
     },
     crossViewportAdaptation: {
@@ -491,11 +559,28 @@ function buildDesignIntentContractObject({
       touchTargetMinPx: 44,
       mutationRules: inferredKeywords.mutationRules,
     },
+    motionSystem: {
+      allowMeaningfulMotion: true,
+      purpose: inferredKeywords.motionPurpose,
+      choreography: inferredKeywords.motionChoreography,
+      desktopDurationMs: inferredKeywords.motionDurations.desktop,
+      mobileDurationMs: inferredKeywords.motionDurations.mobile,
+      respectReducedMotion: true,
+      preferTransformAndOpacity: true,
+      avoidDecorativeMotionForItsOwnSake: true,
+    },
+    componentMorphology: {
+      requireStateBehaviorMatrix: true,
+      preserveIdentityAcrossViewports: true,
+      stateKeys: ['default', 'hover', 'focus', 'active', 'disabled', 'loading', 'error'],
+      viewportBehavior: inferredKeywords.componentMorphology,
+    },
     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.',
       'Cross-viewport behavior must reorganize tasks and navigation, not just scale the desktop layout down.',
+      'Motion may add character and continuity when it improves the product experience, but it must stay purposeful, performant, and optional for reduced-motion users.',
     ],
     forbiddenPatterns: [
       'generic-saas-hero',
@@ -509,6 +594,8 @@ function buildDesignIntentContractObject({
       requireViewportMutationRules: true,
       requirePerceptualColorRationale: true,
       allowHexDerivatives: true,
+      requireMotionRationale: true,
+      requireStateMorphology: true,
     },
     requiredDesignSections: DESIGN_REQUIRED_SECTIONS,
     implementation: {
@@ -517,6 +604,7 @@ function buildDesignIntentContractObject({
       requireDistinctVisualDirection: true,
       requireMachineReadableContract: true,
       requireViewportMutationRules: true,
+      requirePurposefulMotionGuidelines: true,
       bootstrapPrompt: '.agent-context/prompts/bootstrap-design.md',
       autoLoadedRuleFiles: [
         '.agent-context/prompts/bootstrap-design.md',
@@ -528,7 +616,6 @@ function buildDesignIntentContractObject({
         '.agent-context/rules/microservices.md',
       ],
     },
-    architectSignals: designSignals,
     ...supplementalFields,
   };
 }
@@ -589,6 +676,41 @@ export function validateDesignIntentContract(designIntentContract) {
     }
   }
 
+  if (!designIntentContract.motionSystem || typeof designIntentContract.motionSystem !== 'object') {
+    validationErrors.push('designIntent.motionSystem must exist.');
+  } else {
+    if (designIntentContract.motionSystem.allowMeaningfulMotion !== true) {
+      validationErrors.push('designIntent.motionSystem.allowMeaningfulMotion must equal true.');
+    }
+    if (!String(designIntentContract.motionSystem.purpose || '').trim()) {
+      validationErrors.push('designIntent.motionSystem.purpose must be a non-empty string.');
+    }
+    if (designIntentContract.motionSystem.respectReducedMotion !== true) {
+      validationErrors.push('designIntent.motionSystem.respectReducedMotion must equal true.');
+    }
+  }
+
+  if (!designIntentContract.componentMorphology || typeof designIntentContract.componentMorphology !== 'object') {
+    validationErrors.push('designIntent.componentMorphology must exist.');
+  } else {
+    if (designIntentContract.componentMorphology.requireStateBehaviorMatrix !== true) {
+      validationErrors.push('designIntent.componentMorphology.requireStateBehaviorMatrix must equal true.');
+    }
+    if (!Array.isArray(designIntentContract.componentMorphology.stateKeys) || designIntentContract.componentMorphology.stateKeys.length < 4) {
+      validationErrors.push('designIntent.componentMorphology.stateKeys must contain multiple interaction states.');
+    }
+    const viewportBehavior = designIntentContract.componentMorphology.viewportBehavior;
+    if (!viewportBehavior || typeof viewportBehavior !== 'object') {
+      validationErrors.push('designIntent.componentMorphology.viewportBehavior must exist.');
+    } else {
+      for (const viewportKey of ['mobile', 'tablet', 'desktop']) {
+        if (!String(viewportBehavior[viewportKey] || '').trim()) {
+          validationErrors.push(`designIntent.componentMorphology.viewportBehavior.${viewportKey} must be a non-empty string.`);
+        }
+      }
+    }
+  }
+
   if (!Array.isArray(designIntentContract.requiredDesignSections) || designIntentContract.requiredDesignSections.length !== DESIGN_REQUIRED_SECTIONS.length) {
     validationErrors.push('designIntent.requiredDesignSections must match the required design contract sections.');
   } else {
@@ -656,7 +778,7 @@ function buildProjectContextBootstrapPrompt({
 }) {
   const featuresList = Array.isArray(discoveryAnswers.features) && discoveryAnswers.features.length > 0
     ? discoveryAnswers.features.map((feature, featureIndex) => `${featureIndex + 1}. ${feature}`).join('\n')
-    : '1. Core functionality (define during implementation)';
+    : 'Derive the first concrete feature set from the project name, description, and domain. Do not invent arbitrary modules just to fill space.';
 
   const expectedDocsList = expectedDocFileNames
     .map((fileName, fileIndex) => `${fileIndex + 1}. docs/${fileName}`)
@@ -692,6 +814,11 @@ function buildProjectContextBootstrapPrompt({
     '3. Keep stack, database, and auth aligned with the project constraints below unless user explicitly requests migration.',
     '4. Output must be implementation-ready for engineers, not generic textbook explanation.',
     '5. For any research-backed claim, include citation metadata (source + fetchedAt timestamp) from the Architect Engine Snapshot.',
+    '6. Write for native English speakers at an 8th-grade reading level. Use clear, direct, plain language.',
+    '7. Avoid emoji, AI cliches, buzzwords, academic phrasing, padding, and generic filler.',
+    '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.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -719,8 +846,10 @@ function buildProjectContextBootstrapPrompt({
     '',
     '## Required Execution',
     '1. Create all required docs files listed above with complete Markdown content.',
-    '2. Keep content original, specific to this project, and actionable for implementation.',
-    '3. After writing docs, continue coding tasks using these docs as living project context.',
+    '2. Make the docs adaptive to the real repo and prompt context. These are living references, not frozen templates.',
+    '3. In docs/project-brief.md and docs/architecture-decision-record.md, include explicit sections for confirmed facts, assumptions to validate, and next validation actions whenever context is incomplete.',
+    '4. Keep content original, specific to this project, and actionable for implementation.',
+    '5. After writing docs, continue coding tasks using these docs as living project context.',
     '',
   ].join('\n');
 }
@@ -731,8 +860,6 @@ function buildDesignBootstrapPrompt({
   docsLanguage,
   architectureRecommendation,
 }) {
-  const designSignals = architectureRecommendation?.designGuidance?.normalizedSignals || null;
-  const designSignalsJson = JSON.stringify(designSignals, null, 2);
   const designIntentSeed = buildDesignIntentSeed({
     discoveryAnswers,
     initContext,
@@ -764,7 +891,7 @@ function buildDesignBootstrapPrompt({
     '6. Spacing, Layout Rhythm, and Density Strategy',
     '7. Responsive Strategy and Cross-Viewport Adaptation Matrix',
     '8. Motion and Interaction Principles',
-    '9. Component Language (cards, forms, nav, states)',
+    '9. Component Language and Morphology (cards, forms, nav, states)',
     '10. Accessibility Non-Negotiables',
     '11. Anti-Patterns to Avoid',
     '12. Implementation Notes for Future UI Tasks',
@@ -780,11 +907,13 @@ function buildDesignBootstrapPrompt({
     '8. mathSystems',
     '9. colorTruth',
     '10. crossViewportAdaptation',
-    '11. experiencePrinciples',
-    '12. forbiddenPatterns',
-    '13. validationHints',
-    '14. requiredDesignSections',
-    '15. implementation',
+    '11. motionSystem',
+    '12. componentMorphology',
+    '13. experiencePrinciples',
+    '14. forbiddenPatterns',
+    '15. validationHints',
+    '16. requiredDesignSections',
+    '17. implementation',
     '',
     '## Hard Rules',
     '1. No copy-paste from external style guides.',
@@ -795,7 +924,9 @@ function buildDesignBootstrapPrompt({
     '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. Responsive guidance must include layout mutation rules for mobile, tablet, and desktop. Shrinking the desktop layout is not enough.',
-    '9. 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.',
+    '9. Motion is allowed when it reinforces feedback, continuity, or hierarchy. Do not remove motion entirely, but reject decorative motion that harms clarity or performance.',
+    '10. Define component morphology across interaction states and viewports so cards, forms, nav, and feedback surfaces adapt coherently instead of only resizing.',
+    '11. 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.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -804,12 +935,6 @@ function buildDesignBootstrapPrompt({
     `- Stack: ${toTitleCase(initContext.stackFileName)}`,
     `- Blueprint: ${toTitleCase(initContext.blueprintFileName)}`,
     '',
-    '## Architect Design Signals (raw control vector)',
-    'Use this only as baseline fuel, then expand into full design direction with original reasoning:',
-    '```json',
-    designSignalsJson || 'null',
-    '```',
-    '',
     '## Seed Machine Contract',
     'Refine this seed instead of discarding it. Keep the final JSON aligned with the markdown design system.',
     '```json',
@@ -1019,6 +1144,7 @@ export async function loadProjectConfig(configFilePath) {
   return {
     projectName: configEntries.projectName || configEntries.name || '',
     projectDescription: configEntries.projectDescription || configEntries.description || '',
+    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)',

package/package.json

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

package/scripts/frontend-usability-audit.mjs

@@ -64,6 +64,8 @@ const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
   'Responsive Strategy and Cross-Viewport Adaptation Matrix',
   'colorTruth.format',
   'crossViewportAdaptation.mutationRules.mobile/tablet/desktop',
+  'motionSystem',
+  'componentMorphology',
 ];
 
 const REQUIRED_UI_DESIGN_JUDGE_SNIPPETS = [