@ryuenn3123/agentic-senior-core 3.0.43 → 3.0.45

package/lib/cli/compiler.mjs

@@ -64,6 +64,8 @@ function buildAnchorCommitmentHeader(designIntent) {
   const conceptualAnchor = designIntent.conceptualAnchor || {};
   const derivedTokenLogic = designIntent.derivedTokenLogic || {};
   const creativeCommitment = designIntent.designExecutionHandoff?.creativeCommitment || {};
+  const designFlexibilityPolicy = designIntent.designFlexibilityPolicy || {};
+  const expressionFlexibility = designIntent.designExecutionHandoff?.expressionFlexibility || {};
   const anchorReference = conceptualAnchor.anchorReference || derivedTokenLogic.anchorReference;
   const conceptualAnchorName = conceptualAnchor.name || anchorReference;
   const signatureMove = conceptualAnchor.signatureMove
@@ -74,6 +76,12 @@ function buildAnchorCommitmentHeader(designIntent) {
   const typographicDecision = conceptualAnchor.typographicDecision
     || creativeCommitment.typographicDecision
     || derivedTokenLogic.typographyDerivationSource;
+  const flexibleAxes = Array.isArray(designFlexibilityPolicy.flexibleExpressionAxes)
+    ? designFlexibilityPolicy.flexibleExpressionAxes
+    : expressionFlexibility.flexibleAxes;
+  const lockedOutcomes = Array.isArray(expressionFlexibility.lockedOutcomes)
+    ? expressionFlexibility.lockedOutcomes
+    : designFlexibilityPolicy.lockedOutcomeTypes;
 
   if (!conceptualAnchorName && !anchorReference) {
     return [
@@ -92,6 +100,8 @@ function buildAnchorCommitmentHeader(designIntent) {
     `Signature Move: ${toSingleLine(signatureMove, 'MISSING - define one concrete authored move before UI implementation')}`,
     `Motion Signature: ${toSingleLine(signatureMotion, 'MISSING - define timing/easing/choreography before UI implementation')}`,
     `Typographic Decision: ${toSingleLine(typographicDecision, 'MISSING - define role contrast before UI implementation')}`,
+    `Locked Outcomes: ${toSingleLine(Array.isArray(lockedOutcomes) ? lockedOutcomes.join(', ') : '', 'user goals, accessibility, production readiness, forbidden patterns')}`,
+    `Flexible Expression: ${toSingleLine(Array.isArray(flexibleAxes) ? flexibleAxes.join(', ') : '', 'exact primitives, typeface, surface treatment, component skin, candidate moves')}`,
     'If the UI output does not reflect these lines, stop and revise the design contract before continuing.',
   ].join('\n');
 }
@@ -412,7 +422,9 @@ export async function buildCompiledRulesContent({
       '3. .agent-context/prompts/review-code.md -> review, audit, check, analyze',
       '4. .agent-context/prompts/bootstrap-design.md -> ui, ux, layout, screen, tailwind, frontend, redesign',
       'Documentation-first policy:',
-      '- Create or refine required project docs before implementation: docs/project-brief.md, docs/architecture-decision-record.md, docs/flow-overview.md, docs/api-contract.md when APIs, firmware endpoints, CLI commands, or web application flows exist, docs/database-schema.md when persistent data exists, and docs/DESIGN.md plus docs/design-intent.json for UI scope.',
+      '- Create or refine required project docs before implementation: README.md for every fresh or existing project; docs/project-brief.md; docs/architecture-decision-record.md; docs/flow-overview.md; docs/api-contract.md when APIs, firmware endpoints, CLI commands, or web application flows exist; docs/database-schema.md when persistent data exists; and docs/DESIGN.md plus docs/design-intent.json for UI scope.',
+      '- Keep README.md public and developer friendly, including for private projects: explain what the project is, who it is for, setup, usage, configuration, and links to deeper docs. Do not put secrets, internal agent notes, private reasoning, or governance policy dumps in it.',
+      '- Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
       '- Write formal project docs in English by default unless the user explicitly asks for another documentation language.',
       '- For docs-only/docs-first requests, do not write application, firmware, or UI code until the user asks or approves an implementation plan.',
       'UI trigger policy:',
@@ -533,6 +545,7 @@ export async function buildCompiledRulesContent({
   const hasBootstrapDesignPrompt = await pathExists(bootstrapDesignPromptPath);
 
   if (await pathExists(projectBriefPath)) {
+    const hasRootReadme = await pathExists(path.join(resolvedTargetDirectoryPath, 'README.md'));
     const projectDocsEntries = ['project-brief.md'];
     const candidateDocFileNames = [
       'architecture-decision-record.md',
@@ -555,15 +568,18 @@ export async function buildCompiledRulesContent({
         '## LAYER 9: PROJECT CONTEXT (MANDATORY)',
         'These documents describe the specific project being built.',
         'Read them before writing any application code:',
-        ...projectDocsEntries.map((docFileName, docIndex) => `${docIndex + 1}. docs/${docFileName}`),
+        ...(hasRootReadme ? ['1. README.md'] : []),
+        ...projectDocsEntries.map((docFileName, docIndex) => `${(hasRootReadme ? 2 : 1) + docIndex}. docs/${docFileName}`),
         '',
         'Universal SOP hard block policy:',
+        '- README.md must exist and read as a public and developer entrypoint.',
         '- Stop implementation if docs/project-brief.md is missing.',
         '- Stop implementation if docs/architecture-decision-record.md (alias: docs/Architecture-Decision-Record.md) is missing.',
         '- Stop implementation if docs/flow-overview.md is missing.',
         '- If the product uses persistent data, docs/database-schema.md must exist before coding continues.',
         '- If the product exposes API or web application flows, docs/api-contract.md must exist before coding continues.',
         '- For UI scope, stop implementation if docs/DESIGN.md or docs/design-intent.json is missing.',
+        '- Keep README.md overview-level, public, and developer friendly; do not put secrets, internal agent notes, private reasoning, or governance policy dumps in it.',
         '- Materialize missing docs first, then continue coding.',
         '- Bootstrap missing docs from real repo evidence and the latest user request. Do not write generic placeholder templates.',
         '- Separate confirmed facts from assumptions and end each major explanation with the next validation action.',
@@ -573,7 +589,7 @@ export async function buildCompiledRulesContent({
         'Latest user prompt defines current feature scope and product direction.',
         'Treat requested features as dynamic, but keep stack/database/auth constraints consistent',
         'with project docs unless the user explicitly asks for a migration.',
-        'When scope changes, implement the new request and update docs/* in the same change',
+        'When scope changes, implement the new request and update README.md plus docs/* in the same change when documented context changes',
         'so generated context stays aligned with the codebase.',
         'Update them as the project evolves. They are living references, not frozen specs.',
       ].join('\n')
@@ -595,6 +611,7 @@ export async function buildCompiledRulesContent({
         ...bootstrapPromptEntries.map((promptFilePath, promptIndex) => `${promptIndex + 1}. ${promptFilePath}`),
         '',
         'Bootstrap policy:',
+        '- Create README.md as a public and developer entrypoint before coding continues.',
         '- Hard block: do not write application code until docs/project-brief.md and docs/architecture-decision-record.md exist.',
         '- docs/flow-overview.md must also exist before coding continues.',
         '- Add docs/database-schema.md when persistent data is involved.',

package/lib/cli/project-scaffolder/design-contract/validation.mjs

@@ -113,6 +113,36 @@ export function validateDesignIntentContract(designIntentContract) {
     }
   }
 
+  if (!designIntentContract.designFlexibilityPolicy || typeof designIntentContract.designFlexibilityPolicy !== 'object') {
+    validationErrors.push('designIntent.designFlexibilityPolicy must exist.');
+  } else {
+    const designFlexibilityPolicy = designIntentContract.designFlexibilityPolicy;
+    if (designFlexibilityPolicy.mode !== 'locked-outcomes-flexible-expression') {
+      validationErrors.push('designIntent.designFlexibilityPolicy.mode must equal "locked-outcomes-flexible-expression".');
+    }
+    if (!hasNonEmptyString(designFlexibilityPolicy.contractRole)) {
+      validationErrors.push('designIntent.designFlexibilityPolicy.contractRole must be a non-empty string.');
+    }
+    if (!Array.isArray(designFlexibilityPolicy.lockedOutcomeTypes) || designFlexibilityPolicy.lockedOutcomeTypes.length < 4) {
+      validationErrors.push('designIntent.designFlexibilityPolicy.lockedOutcomeTypes must list the locked outcome categories.');
+    }
+    if (!Array.isArray(designFlexibilityPolicy.flexibleExpressionAxes) || designFlexibilityPolicy.flexibleExpressionAxes.length < 4) {
+      validationErrors.push('designIntent.designFlexibilityPolicy.flexibleExpressionAxes must list flexible expression axes.');
+    }
+    if (!hasNonEmptyString(designFlexibilityPolicy.tokenLockingRule)) {
+      validationErrors.push('designIntent.designFlexibilityPolicy.tokenLockingRule must be a non-empty string.');
+    }
+    if (!String(designFlexibilityPolicy.signatureMovePolicy || '').includes('candidate')) {
+      validationErrors.push('designIntent.designFlexibilityPolicy.signatureMovePolicy must separate candidate moves from required outcomes.');
+    }
+    if (!String(designFlexibilityPolicy.libraryVisualLanguagePolicy || '').includes('Libraries supply')) {
+      validationErrors.push('designIntent.designFlexibilityPolicy.libraryVisualLanguagePolicy must keep libraries from dictating visual language.');
+    }
+    if (!String(designFlexibilityPolicy.literalAnchorPolicy || '').includes('Translate anchors')) {
+      validationErrors.push('designIntent.designFlexibilityPolicy.literalAnchorPolicy must require non-literal anchor translation.');
+    }
+  }
+
   if (!designIntentContract.conceptualAnchor || typeof designIntentContract.conceptualAnchor !== 'object') {
     validationErrors.push('designIntent.conceptualAnchor must exist.');
   } else {
@@ -228,6 +258,20 @@ export function validateDesignIntentContract(designIntentContract) {
         validationErrors.push('designIntent.conceptualAnchor.visualRiskBudget.requireReducedMotionFallback must equal true.');
       }
     }
+    const literalTranslationPolicy = conceptualAnchor.literalTranslationPolicy;
+    if (!literalTranslationPolicy || typeof literalTranslationPolicy !== 'object') {
+      validationErrors.push('designIntent.conceptualAnchor.literalTranslationPolicy must exist.');
+    } else {
+      if (literalTranslationPolicy.preferNonLiteralTranslation !== true) {
+        validationErrors.push('designIntent.conceptualAnchor.literalTranslationPolicy.preferNonLiteralTranslation must equal true.');
+      }
+      if (!hasNonEmptyString(literalTranslationPolicy.allowedLiteralUse)) {
+        validationErrors.push('designIntent.conceptualAnchor.literalTranslationPolicy.allowedLiteralUse must be a non-empty string.');
+      }
+      if (!String(literalTranslationPolicy.forbiddenLiteralUse || '').includes('decorative wallpaper')) {
+        validationErrors.push('designIntent.conceptualAnchor.literalTranslationPolicy.forbiddenLiteralUse must reject decorative wallpaper.');
+      }
+    }
     if (
       !Array.isArray(conceptualAnchor.requiredDerivedAxes)
       || !conceptualAnchor.requiredDerivedAxes.includes('typography')
@@ -392,6 +436,20 @@ export function validateDesignIntentContract(designIntentContract) {
     if (designIntentContract.tokenSystem.componentTokensConsumeSemantic !== true) {
       validationErrors.push('designIntent.tokenSystem.componentTokensConsumeSemantic must equal true.');
     }
+    const tokenLockingPolicy = designIntentContract.tokenSystem.tokenLockingPolicy;
+    if (!tokenLockingPolicy || typeof tokenLockingPolicy !== 'object') {
+      validationErrors.push('designIntent.tokenSystem.tokenLockingPolicy must exist.');
+    } else {
+      if (tokenLockingPolicy.defaultLockState !== 'semantic-roles-locked-primitives-flexible') {
+        validationErrors.push('designIntent.tokenSystem.tokenLockingPolicy.defaultLockState must preserve semantic roles while keeping primitives flexible.');
+      }
+      if (!Array.isArray(tokenLockingPolicy.flexibleByDefault) || tokenLockingPolicy.flexibleByDefault.length < 4) {
+        validationErrors.push('designIntent.tokenSystem.tokenLockingPolicy.flexibleByDefault must list flexible primitive axes.');
+      }
+      if (!hasNonEmptyString(tokenLockingPolicy.promotionRule)) {
+        validationErrors.push('designIntent.tokenSystem.tokenLockingPolicy.promotionRule must be a non-empty string.');
+      }
+    }
     const fallbackPolicy = designIntentContract.tokenSystem.fallbackPolicy;
     if (!fallbackPolicy || typeof fallbackPolicy !== 'object') {
       validationErrors.push('designIntent.tokenSystem.fallbackPolicy must exist.');
@@ -589,6 +647,10 @@ export function validateDesignIntentContract(designIntentContract) {
       'requireStructuredHandoff',
       'requireRepoEvidenceAlignment',
       'forbidScreenshotDependency',
+      'separateRequiredOutcomesFromCandidateMoves',
+      'forbidCandidateMovesAsLockedRequirements',
+      'forbidLibraryThemeAsVisualAuthority',
+      'forbidLiteralAnchorChromeWithoutProductFunction',
       'requirePerSurfaceMutationOps',
       'forbidUniformSiblingSurfaceTreatment',
       'zeroBasedRedesignResetsPriorVisualsWhenRequested',
@@ -674,6 +736,23 @@ export function validateDesignIntentContract(designIntentContract) {
     if (!Array.isArray(designIntentContract.designExecutionHandoff.interactionStateMatrix) || designIntentContract.designExecutionHandoff.interactionStateMatrix.length < 1) {
       validationErrors.push('designIntent.designExecutionHandoff.interactionStateMatrix must list key component state expectations.');
     }
+    const expressionFlexibility = designIntentContract.designExecutionHandoff.expressionFlexibility;
+    if (!expressionFlexibility || typeof expressionFlexibility !== 'object') {
+      validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility must exist.');
+    } else {
+      if (!Array.isArray(expressionFlexibility.lockedOutcomes) || expressionFlexibility.lockedOutcomes.length < 3) {
+        validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility.lockedOutcomes must list locked outcomes.');
+      }
+      if (!Array.isArray(expressionFlexibility.candidateSignatureMoves) || expressionFlexibility.candidateSignatureMoves.length < 1) {
+        validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility.candidateSignatureMoves must include at least one candidate move placeholder.');
+      }
+      if (!Array.isArray(expressionFlexibility.flexibleAxes) || expressionFlexibility.flexibleAxes.length < 4) {
+        validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility.flexibleAxes must list flexible implementation axes.');
+      }
+      if (!String(expressionFlexibility.lockingRule || '').includes('candidate')) {
+        validationErrors.push('designIntent.designExecutionHandoff.expressionFlexibility.lockingRule must explain when candidate moves become required.');
+      }
+    }
     if (!Array.isArray(designIntentContract.designExecutionHandoff.taskFlowNarrative) || designIntentContract.designExecutionHandoff.taskFlowNarrative.length < 2) {
       validationErrors.push('designIntent.designExecutionHandoff.taskFlowNarrative must describe the key UI task flow in sequence.');
     }
@@ -707,6 +786,8 @@ export function validateDesignIntentContract(designIntentContract) {
         'requireBuildFromHandoff',
         'requireGapNotesBeforeFallback',
         'forbidGenericLayoutFallbackWithoutReason',
+        'requireLockedVsFlexibleDecisionReview',
+        'forbidCandidateMoveHardcoding',
         'forbidTestingDemoCopyInUi',
         'forbidTerminalOnlyUserFlows',
       ]) {

package/lib/cli/project-scaffolder/design-contract.mjs

@@ -21,9 +21,14 @@ const GENERICITY_DRIFT_SIGNALS = [
   'timid-anchor-that-renames-dashboard-or-admin-shell',
   'motion-suppressed-without-accessibility-or-performance-reason',
   'motion-or-3d-omitted-from-fear-without-fit-analysis',
+  'modern-library-rejected-from-dependency-fear-without-tradeoff-analysis',
+  'component-library-selected-by-habit-without-product-fit',
   'scale-only-responsive-layout',
   'zero-based-redesign-kept-prior-visual-dna',
   'restyle-instead-of-recomposition',
+  'literal-anchor-artifacts-used-as-required-ui-chrome',
+  'candidate-signature-move-treated-as-locked-implementation',
+  'library-theme-tokens-drive-visual-language',
 ];
 
 const FORBIDDEN_PATTERN_SIGNALS = [
@@ -41,6 +46,8 @@ const VALID_BOLD_SIGNALS = [
   'background-or-geometry-serves-product-function',
   'motion-or-spatial-experience-derived-from-anchor',
   'explicit-3d-canvas-fit-or-nonfit-decision',
+  'official-docs-backed-modern-library-choice',
+  'headless-or-component-primitive-restyled-to-product-language',
   'responsive-recomposition-by-task-priority',
   'purposeful-motion-with-reduced-motion-path',
 ];
@@ -176,7 +183,30 @@ function buildDesignIntentContractObject({
         'ui-primitives-or-rich-media',
         'typography-and-interaction',
       ],
-      finalDecisionAuthority: 'project-fit-accessibility-performance-maintainability-official-docs',
+      finalDecisionAuthority: 'project-fit-accessibility-performance-maintainability-delivery-speed-official-docs',
+    },
+    designFlexibilityPolicy: {
+      mode: 'locked-outcomes-flexible-expression',
+      contractRole: 'Use docs/design-intent.json as review invariants and handoff structure, not as a frozen visual recipe unless the user explicitly locks a decision.',
+      lockedOutcomeTypes: [
+        'confirmed-user-goals',
+        'repo-evidence-and-runtime-constraints',
+        'accessibility-and-production-readiness',
+        'forbidden-patterns-and-safety-gates',
+        'user-approved-brand-or-continuity-decisions',
+      ],
+      flexibleExpressionAxes: [
+        'exact-palette-primitives',
+        'font-family-selection',
+        'radius-shadow-and-surface-treatment',
+        'component-kit-theme-mapping',
+        'signature-move-implementation',
+        'literal-anchor-artifacts',
+      ],
+      tokenLockingRule: 'Semantic roles are required, but exact primitive values stay flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them.',
+      signatureMovePolicy: 'Record the required experience outcome separately from candidate implementation moves; replace a candidate move when another move better fits the product.',
+      libraryVisualLanguagePolicy: 'Libraries supply behavior, accessibility, primitives, and delivery speed; they must not dictate final composition, theme, morphology, or visual language.',
+      literalAnchorPolicy: 'Translate anchors into workflow, hierarchy, density, typography, material behavior, state language, and interaction grammar before requiring literal props, marks, or chrome.',
     },
     conceptualAnchor: {
       mode: 'required-when-no-external-research',
@@ -228,8 +258,14 @@ function buildDesignIntentContractObject({
         mode: 'high-distinctiveness-with-accessibility-and-performance-guardrails',
         allowRichMotionAndMicroInteraction: true,
         rejectTimidDefaultWhenAnchorSupportsExpressiveUi: true,
+        rejectDependencyFearAsDownshiftReason: true,
         requireReducedMotionFallback: true,
       },
+      literalTranslationPolicy: {
+        preferNonLiteralTranslation: true,
+        allowedLiteralUse: 'Only use literal anchor artifacts when they serve a named product function, control, state, or task overlay.',
+        forbiddenLiteralUse: 'Do not turn anchor artifacts into decorative wallpaper, required chrome, default texture, or unavoidable theme props.',
+      },
       requiredDerivedAxes: [
         'typography',
         'morphology',
@@ -267,7 +303,7 @@ function buildDesignIntentContractObject({
       spacingDerivationSource: 'Explain spacing rhythm, density, and exceptions from anchorReference. Spacing grids are layout math, not decorative background lines.',
       typographyDerivationSource: 'Explain display, body, metadata, and data roles from anchorReference.',
       motionDerivationSource: 'Explain duration, easing, choreography, and reduced-motion from anchorReference.',
-      validationRule: 'Every token must trace to anchorReference; revise tokens that cannot.',
+      validationRule: 'Every semantic token role must trace to anchorReference; keep exact primitive values flexible unless locked by repo evidence, accessibility validation, implementation constraints, or explicit user approval.',
     },
     motionPaletteDecision: {
       productCategorySignal: 'agent-inferred-starting-heuristic',
@@ -306,7 +342,7 @@ function buildDesignIntentContractObject({
           'spatial-or-3d-fit',
           'performance-and-reduced-motion-fallback',
         ],
-        rejectionRule: 'State a product reason and replacement interaction quality before omitting 3D/canvas.',
+        rejectionRule: 'State a product reason and replacement interaction quality before omitting 3D/canvas. Package count or vague performance fear is not enough.',
         reviewQuestion: 'Is the interaction as expressive as the product can responsibly support?',
       },
       reviewQuestion: 'What visible evidence proves this is product-specific?',
@@ -329,11 +365,12 @@ function buildDesignIntentContractObject({
     libraryDecisions: [
       {
         library: 'agent-defined-or-none',
-        purpose: 'Verify UI-related libraries against current official docs before imports.',
+        purpose: 'Select UI-related libraries dynamically from product fit, accessibility, interaction quality, maintenance, and current official docs before imports.',
         verifiedAt: null,
         sourceUrl: null,
         stableVersion: null,
         fallbackIfUnavailable: 'Use native CSS, browser APIs, or existing dependencies.',
+        selectionPolicy: 'Do not default to shadcn, native-only, Tailwind-only, or dependency avoidance by habit.',
       },
     ],
     mathSystems: {
@@ -357,6 +394,12 @@ function buildDesignIntentContractObject({
         forbidRawSpacingOutsidePrimitives: true,
         requireDocumentedExceptionForLegacyBypass: true,
       },
+      tokenLockingPolicy: {
+        defaultLockState: 'semantic-roles-locked-primitives-flexible',
+        lockedByDefault: ['semantic-role-purpose', 'accessibility-floor', 'state-role-meaning'],
+        flexibleByDefault: ['exact-color-values', 'font-family', 'radius-values', 'shadow-values', 'component-skin'],
+        promotionRule: 'Promote flexible tokens to locked only when user approval, repo evidence, accessibility validation, or implementation constraints require it.',
+      },
       namingConstraints: {
         forbidCurlyBracesInNames: true,
         forbidDotsInNames: true,
@@ -430,6 +473,10 @@ function buildDesignIntentContractObject({
       requireStructuredHandoff: true,
       requireRepoEvidenceAlignment: true,
       forbidScreenshotDependency: true,
+      separateRequiredOutcomesFromCandidateMoves: true,
+      forbidCandidateMovesAsLockedRequirements: true,
+      forbidLibraryThemeAsVisualAuthority: true,
+      forbidLiteralAnchorChromeWithoutProductFunction: true,
       handoffFormatVersion: 'ui-handoff-v1',
       requirePerSurfaceMutationOps: true,
       forbidUniformSiblingSurfaceTreatment: true,
@@ -531,6 +578,26 @@ function buildDesignIntentContractObject({
           notes: 'Refine states from project language and anchor; reject anonymous panels.',
         },
       ],
+      expressionFlexibility: {
+        lockedOutcomes: [
+          'preserve-primary-user-goal',
+          'preserve-accessibility-floor',
+          'preserve-production-content-policy',
+          'preserve-forbidden-patterns',
+        ],
+        candidateSignatureMoves: [
+          'agent-defined-candidate-move-not-locked-until-refined',
+        ],
+        flexibleAxes: [
+          'palette-primitives',
+          'typeface-choice',
+          'surface-treatment',
+          'component-library-skin',
+          'motion-implementation',
+          'anchor-artifact-literalness',
+        ],
+        lockingRule: 'A candidate move becomes required only after repo evidence, product function, accessibility need, or explicit user approval makes it necessary.',
+      },
       taskFlowNarrative: [
         `Entry: start ${projectName} from real evidence, not a generic opener.`,
         'Resolution: define proof, feedback, recovery, and next action.',
@@ -558,6 +625,8 @@ function buildDesignIntentContractObject({
         requireBuildFromHandoff: true,
         requireGapNotesBeforeFallback: true,
         forbidGenericLayoutFallbackWithoutReason: true,
+        requireLockedVsFlexibleDecisionReview: true,
+        forbidCandidateMoveHardcoding: true,
         forbidTestingDemoCopyInUi: true,
         forbidTerminalOnlyUserFlows: true,
       },

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

@@ -44,8 +44,11 @@ export function buildProjectContextBootstrapPrompt({
     ? discoveryAnswers.features.map((feature, featureIndex) => `${featureIndex + 1}. ${feature}`).join('\n')
     : '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}`)
+  const expectedDocsList = [
+    'README.md',
+    ...expectedDocFileNames.map((fileName) => `docs/${fileName}`),
+  ]
+    .map((filePath, fileIndex) => `${fileIndex + 1}. ${filePath}`)
     .join('\n');
 
   return [
@@ -73,7 +76,9 @@ export function buildProjectContextBootstrapPrompt({
     '10. Do not invent modules or architecture layers only to make the docs look complete.',
     '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.',
+    '13. Required docs coverage must include a public and developer README entrypoint, 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.',
+    '14. README.md must be public and developer friendly, including for private projects: what it is, who it is for, setup, core workflow, configuration, and links to deeper docs. Do not include secrets, internal agent notes, private reasoning, or governance policy dumps.',
+    '15. Keep docs complete but compact. Add extra docs files only for stable, distinct, or long workflows such as hardware setup, deployment, operations, testing validation, or troubleshooting.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -101,8 +106,9 @@ export function buildProjectContextBootstrapPrompt({
     '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.',
     '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.',
+    '4. Before implementation, use the docs to confirm stack, runtime, architecture, public contracts, data, validation, and delivery assumptions.',
+    '5. Keep content original, specific to this project, and actionable for implementation.',
+    '6. After writing docs, continue coding tasks using these docs as living project context.',
     '',
   ].join('\n');
 }
@@ -155,28 +161,29 @@ export function buildDesignBootstrapPrompt({
     '4. designPhilosophy',
     '5. visualDirection',
     '6. externalResearchIntake',
-    '7. conceptualAnchor',
-    '8. derivedTokenLogic',
-    '9. motionPaletteDecision',
-    '10. aiSafeUiAudit',
-    '11. productionContentPolicy',
-    '12. libraryResearchStatus',
-    '13. libraryDecisions',
-    '14. mathSystems',
-    '15. tokenSystem',
-    '16. colorTruth',
-    '17. crossViewportAdaptation',
-    '18. motionSystem',
-    '19. componentMorphology',
-    '20. accessibilityPolicy',
-    '21. designExecutionPolicy',
-    '22. designExecutionHandoff',
-    '23. reviewRubric',
-    '24. contextHygiene',
-    '25. forbiddenPatterns',
-    '26. requiredDesignSections',
-    '27. implementation',
-    '28. repoEvidence when onboarding or detector evidence exists',
+    '7. designFlexibilityPolicy',
+    '8. conceptualAnchor',
+    '9. derivedTokenLogic',
+    '10. motionPaletteDecision',
+    '11. aiSafeUiAudit',
+    '12. productionContentPolicy',
+    '13. libraryResearchStatus',
+    '14. libraryDecisions',
+    '15. mathSystems',
+    '16. tokenSystem',
+    '17. colorTruth',
+    '18. crossViewportAdaptation',
+    '19. motionSystem',
+    '20. componentMorphology',
+    '21. accessibilityPolicy',
+    '22. designExecutionPolicy',
+    '23. designExecutionHandoff',
+    '24. reviewRubric',
+    '25. contextHygiene',
+    '26. forbiddenPatterns',
+    '27. requiredDesignSections',
+    '28. implementation',
+    '29. repoEvidence when onboarding or detector evidence exists',
     '',
     '## Mechanical Gates',
     '1. Do not copy external style guides.',
@@ -191,6 +198,7 @@ export function buildDesignBootstrapPrompt({
     '10. Define viewport mutation rules for mobile, tablet, and desktop. Shrinking desktop is failure.',
     '11. Keep structured execution representation-first: surface plan, component graph, content-priority map, viewport mutation plan, and interaction-state matrix.',
     '12. Make design-intent.json carry designExecutionPolicy and designExecutionHandoff, not prose-only policy.',
+    '12a. Make design-intent.json carry designFlexibilityPolicy so locked outcomes, candidate moves, and flexible expression axes stay separate.',
     '13. Keep semantic review focused on contract fidelity, distinctiveness, hierarchy, state behavior, and viewport mutation.',
     '14. Treat WCAG 2.2 AA as the hard floor. Use APCA only as advisory tuning.',
     '15. Cover focus visibility, focus appearance, target size, accessible authentication, keyboard access, and dynamic status/state access.',
@@ -208,13 +216,18 @@ export function buildDesignBootstrapPrompt({
     '27. Reject anchors described only as modern, clean, premium, expressive, minimal, or bold.',
     '28. Set conceptualAnchor.anchorReference and make derivedTokenLogic.anchorReference match exactly.',
     '29. Fill derivedTokenLogic before code. If a token cannot trace to anchorReference, revise it.',
+    '29a. Lock semantic roles before exact values. Do not freeze fonts, color primitives, radius, shadows, or component-kit theme treatment unless repo evidence, accessibility validation, implementation constraints, or explicit user approval requires it.',
     '30. Research current official docs before importing any new UI-related library.',
-    '31. If research is unavailable, set libraryResearchStatus to pending-verification and use native CSS, browser APIs, or existing dependencies.',
-    '32. Define reviewRubric and require genericity findings to name the actual drift signal.',
-    '33. Separate taste from failure. Bold accessible work is valid.',
-    '34. For zero-based redesign, create visualResetStrategy and reset composition, hierarchy, palette/typography, motion or interaction, and responsive information architecture.',
-    '35. Treat productionContentPolicy as blocking: remove visible testing, demo, sample, placeholder, lorem, TODO, coming soon, and scaffold copy unless it is a real product state.',
-    '36. Do not make core user workflows terminal-only unless the product is explicitly a CLI, developer tool, or operational runbook.',
+    '31. Do not default to shadcn/ui, Tailwind-only, native-only, or any component kit by habit; choose the UI foundation from product fit, accessibility, interaction quality, runtime constraints, and official docs.',
+    '32. If research is unavailable, set libraryResearchStatus to pending-verification and use native CSS, browser APIs, or existing dependencies only when they can preserve the intended ambition.',
+    '33. Do not reject modern lightweight libraries solely because they add a dependency; package count or vague performance fear is not a blocker by itself.',
+    '34. Define reviewRubric and require genericity findings to name the actual drift signal.',
+    '35. Separate taste from failure. Bold accessible work is valid.',
+    '36. For zero-based redesign, create visualResetStrategy and reset composition, hierarchy, palette/typography, motion or interaction, and responsive information architecture.',
+    '37. Treat productionContentPolicy as blocking: remove visible testing, demo, sample, placeholder, lorem, TODO, coming soon, and scaffold copy unless it is a real product state.',
+    '38. Do not make core user workflows terminal-only unless the product is explicitly a CLI, developer tool, or operational runbook.',
+    '39. Separate required experience outcomes from candidate implementation moves. Candidate signature moves are proposals until product evidence, accessibility, or user approval makes them required.',
+    '40. Translate conceptual anchors non-literally first. Do not turn anchor artifacts into required chrome, decorative props, wallpaper, or theme objects unless they serve a named product function.',
     '',
     '## Creative Ambition Floor',
     'Before implementation, the design contract must name one authored visual bet, one product-derived palette move, one signature motion/spatial/interaction behavior, and one morphology or composition choice that would not appear in a generic AI template.',
@@ -224,11 +237,13 @@ export function buildDesignBootstrapPrompt({
     '',
     '## Token Derivation Audit',
     'Before implementation, docs/design-intent.json must include derivedTokenLogic.anchorReference plus colorDerivationSource, spacingDerivationSource, typographyDerivationSource, motionDerivationSource, and validationRule.',
-    'Every token must be explainable from anchorReference. If the rationale is only looks good, common practice, modern default, or framework default, derive the token again before UI code.',
+    'Every semantic token role must be explainable from anchorReference. If the rationale is only looks good, common practice, modern default, or framework default, derive the token again before UI code.',
+    'Keep exact primitive values flexible until repo evidence, accessibility validation, implementation constraints, or explicit user approval locks them.',
     '',
     '## Library Research Protocol',
     'If web search is available, verify every new UI, animation, scroll, 3D, canvas, chart, icon, styling, or primitive library against current official docs and record source URL, fetched date, stable compatible version, purpose, risk, and fallback.',
-    'If web search is unavailable or fails, set libraryResearchStatus to pending-verification, record LIBRARY_TO_VERIFY notes, and use native CSS, browser APIs, or already-present project dependencies until verification is possible.',
+    'If web search is unavailable or fails, set libraryResearchStatus to pending-verification, record LIBRARY_TO_VERIFY notes, and use native CSS, browser APIs, or already-present project dependencies only when they can preserve the intended ambition until verification is possible.',
+    'Select UI foundations dynamically. Use ready-made primitives or component kits for mechanics when they fit, but replace library-default visual language with project-specific composition, tokens, motion, state treatment, and morphology.',
     '',
     '## Project Inputs',
     `- Project name: ${discoveryAnswers.projectName}`,
@@ -252,6 +267,7 @@ export function buildDesignBootstrapPrompt({
     '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.',
+    '7a. Encode designFlexibilityPolicy and designExecutionHandoff.expressionFlexibility so future agents know what is locked and what can change.',
     '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.',
@@ -261,6 +277,7 @@ export function buildDesignBootstrapPrompt({
     '14. Preserve conceptualAnchor so prompt-only UI work has one cohesive non-template concept instead of a mixed collection of bold but unrelated visual decisions.',
     '15. Record conceptualAnchor.agentResearchMode, specificReferencePoint, signatureMotion, typographicDecision, visualRiskBudget, motionRiskBudget, and cohesionChecks so the final UI cannot quietly fall back to a timid dashboard/admin mental model.',
     '16. Preserve derivedTokenLogic, libraryResearchStatus, and libraryDecisions so token choices and dependency uncertainty stay visible before implementation.',
+    '16a. Preserve designFlexibilityPolicy so the machine contract guides consistency without freezing literal anchor artifacts, exact token primitives, or component-kit visual language.',
     '17. Preserve productionContentPolicy so UI output is ship-ready and not a testing-looking scaffold.',
     '18. After the contract exists, use it as a first-class source for future UI tasks.',
     '',

package/package.json

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

package/scripts/frontend-usability-audit.mjs

@@ -58,7 +58,7 @@ const REQUIRED_FRONTEND_RULE_SNIPPETS = [
   '## Activation',
   '## Authority',
   'Treat `.agent-context/` as design governance authority.',
-  'Treat `README.md` as overview/install/user context only',
+  'Treat `README.md` as public and developer overview, setup, usage, and user-facing context only',
   'Do not choose final style, framework, palette, typography, layout paradigm, or animation library offline.',
   'Keep design continuity opt-in.',
   'Repo evidence outranks memory residue.',
@@ -94,6 +94,8 @@ const REQUIRED_BOOTSTRAP_DESIGN_SNIPPETS = [
   'WCAG 2.2 AA is the hard floor',
   'APCA may be used only as advisory perceptual tuning',
   'unresearched dependency choices',
+  'Dynamic UI Foundation Selection',
+  'A new dependency, package count, or vague performance concern is not a blocker by itself.',
   'default component-kit styling without product rationale',
   'genericity findings that cannot name the exact drift signal',
 ];

package/scripts/sync-thin-adapters.mjs

@@ -59,7 +59,7 @@ function buildThinAdapter({
     'This repository is governed by a strict instruction contract.',
     `Use [${CANONICAL_SOURCE_PATH}](${canonicalLink}) as the canonical policy source.`,
     'Use .agent-context/ for technical rules, prompts, checklists, policies, and state.',
-    'Treat README.md as overview/install/user context only when governance files conflict.',
+    'Treat README.md as public and developer overview, setup, usage, and user-facing context only when governance files conflict.',
     '',
     '## Critical Bootstrap Floor',
     '',
@@ -70,6 +70,7 @@ function buildThinAdapter({
     '- For UI scope, include a one-line Motion/Palette Decision in the Bootstrap Receipt; product categories are heuristics, not style presets.',
     '- For UI scope, create or refine `docs/DESIGN.md` and `docs/design-intent.json` before UI implementation.',
     '- For documentation-first requests, create or refine required project docs in English by default and do not write application, firmware, or UI code until the user asks or approves.',
+    '- Create or refine root README.md as the public and developer entrypoint before implementation.',
     `- For backend, API, data, auth, error, event, queue, worker, or distributed-system requests, load only relevant global rules from .agent-context/rules/ ([link](${rulesLink})).`,
     '- For ecosystem, framework, dependency, or Docker claims, perform live web research.',
     '- Resolve runtime choices from project evidence and live official documentation; resolve structural planning from constraints and architecture boundaries.',