@ryuenn3123/agentic-senior-core 3.0.12 → 3.0.14

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.',
   };
 }
 
@@ -508,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',
@@ -531,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: {
@@ -603,7 +616,6 @@ function buildDesignIntentContractObject({
         '.agent-context/rules/microservices.md',
       ],
     },
-    architectSignals: designSignals,
     ...supplementalFields,
   };
 }
@@ -766,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}`)
@@ -802,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}`,
@@ -829,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');
 }
@@ -841,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,
@@ -918,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',
@@ -1133,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.12",
+  "version": "3.0.14",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -10,6 +10,7 @@
     "bin/",
     "lib/",
     "scripts/",
+    ".instructions.md",
     ".agent-context/",
     ".agents/",
     ".github/",

package/scripts/sync-thin-adapters.mjs

@@ -38,13 +38,14 @@ The canonical policy source is [.instructions.md](.instructions.md).
 
 ## Mandatory Bootstrap Chain
 
-1. Load [.instructions.md](.instructions.md) first as the single source of truth.
-2. Read baseline governance from [.agent-context/rules/](.agent-context/rules).
-3. Apply request templates from [.agent-context/prompts/](.agent-context/prompts).
-4. Enforce review contracts from [.agent-context/review-checklists/](.agent-context/review-checklists).
-5. Read change-risk maps and continuity state from [.agent-context/state/](.agent-context/state).
-6. Enforce policy thresholds from [.agent-context/policies/](.agent-context/policies).
-7. Use dynamic stack and architecture reasoning from project context docs and live research signals.
+1. Load [.instructions.md](.instructions.md) first as the canonical baseline.
+2. If \`.agent-instructions.md\` exists, read it next as the compiled project-specific snapshot.
+3. Read baseline governance from [.agent-context/rules/](.agent-context/rules).
+4. Apply request templates from [.agent-context/prompts/](.agent-context/prompts).
+5. Enforce review contracts from [.agent-context/review-checklists/](.agent-context/review-checklists).
+6. Read change-risk maps and continuity state from [.agent-context/state/](.agent-context/state).
+7. Enforce policy thresholds from [.agent-context/policies/](.agent-context/policies).
+8. Use dynamic stack and architecture reasoning from project context docs and live research signals.
 
 ## Trigger Rules
 
@@ -67,12 +68,13 @@ The canonical policy source for this repository is [.instructions.md](../.instru
 
 ## Required Load Order
 
-1. Read [.instructions.md](../.instructions.md) first.
-2. Read baseline rules in [.agent-context/rules/](../.agent-context/rules).
-3. Load request templates from [.agent-context/prompts/](../.agent-context/prompts).
-4. Apply review contracts from [.agent-context/review-checklists/](../.agent-context/review-checklists).
-5. Apply state awareness from [.agent-context/state/](../.agent-context/state) and thresholds from [.agent-context/policies/](../.agent-context/policies).
-6. Resolve stack and architecture choices dynamically from project context docs plus live evidence.
+1. Read [.instructions.md](../.instructions.md) first as the canonical baseline.
+2. If \`.agent-instructions.md\` exists, read it next as the compiled project-specific snapshot.
+3. Read baseline rules in [.agent-context/rules/](../.agent-context/rules).
+4. Load request templates from [.agent-context/prompts/](../.agent-context/prompts).
+5. Apply review contracts from [.agent-context/review-checklists/](../.agent-context/review-checklists).
+6. Apply state awareness from [.agent-context/state/](../.agent-context/state) and thresholds from [.agent-context/policies/](../.agent-context/policies).
+7. Resolve stack and architecture choices dynamically from project context docs plus live evidence.
 
 ## Completion Gate
 
@@ -91,12 +93,13 @@ Canonical policy source: [.instructions.md](../.instructions.md).
 
 ## Bootstrap Sequence
 
-1. Load [.instructions.md](../.instructions.md) first.
-2. Apply baseline rules from [.agent-context/rules/](../.agent-context/rules).
-3. Load request templates from [.agent-context/prompts/](../.agent-context/prompts).
-4. Apply review contracts from [.agent-context/review-checklists/](../.agent-context/review-checklists).
-5. Apply state awareness from [.agent-context/state/](../.agent-context/state) and policy thresholds from [.agent-context/policies/](../.agent-context/policies).
-6. Resolve stack and architecture choices dynamically from project context docs plus live evidence.
+1. Load [.instructions.md](../.instructions.md) first as the canonical baseline.
+2. If \`.agent-instructions.md\` exists, read it next as the compiled project-specific snapshot.
+3. Apply baseline rules from [.agent-context/rules/](../.agent-context/rules).
+4. Load request templates from [.agent-context/prompts/](../.agent-context/prompts).
+5. Apply review contracts from [.agent-context/review-checklists/](../.agent-context/review-checklists).
+6. Apply state awareness from [.agent-context/state/](../.agent-context/state) and policy thresholds from [.agent-context/policies/](../.agent-context/policies).
+7. Resolve stack and architecture choices dynamically from project context docs plus live evidence.
 
 ## Completion Gate
 

package/scripts/validate.mjs

@@ -778,6 +778,12 @@ async function validatePackageMetadata() {
   } else {
     pass('package.json has no unnecessary devDependencies');
   }
+
+  if (Array.isArray(packageJson.files) && packageJson.files.includes('.instructions.md')) {
+    pass('package.json publishes canonical .instructions.md');
+  } else {
+    fail('package.json must publish .instructions.md so init and upgrade can copy the canonical root instructions file');
+  }
 }
 
 async function validatePolicyFile() {