@ryuenn3123/agentic-senior-core 3.0.19 → 3.0.21

package/CONTRIBUTING.md

@@ -10,13 +10,13 @@ Thanks for wanting to make AI agents write better code. Here's how to contribute
 |------|-------|-------------|
 | New rule | `.agent-context/rules/` | Universal engineering standard |
 | Stack strategy update | `.agent-context/rules/`, `.agent-context/state/stack-research-snapshot.json` | Dynamic language/runtime guidance and evidence |
-| Architecture playbook update | `.agent-context/prompts/`, `lib/cli/compiler.mjs` | Dynamic scaffolding and project-context guidance |
+| Structural planning guidance update | `.agent-context/prompts/`, `lib/cli/compiler.mjs` | Scope planning, docs bootstrap, and project-context guidance |
 | New checklist | `.agent-context/review-checklists/` | Self-audit guide |
 | State intelligence update | `.agent-context/state/` | Architecture boundaries and dependency map |
-| Override policy update | `.agent-override.md` | Scoped enterprise rule exceptions |
+| Override policy update | `.agent-override.md` | Scoped rule exceptions |
 | MCP workflow update | `mcp.json` | Self-healing automation flow |
-| Bug fix | Any file | Typos, broken links, incorrect examples |
-| Improvement | Any file | Sharper wording, better examples |
+| Bug fix | Any file | Typos, broken links, incorrect rules |
+| Improvement | Any file | Sharper wording, stricter boundaries |
 
 ---
 
@@ -24,19 +24,10 @@ Thanks for wanting to make AI agents write better code. Here's how to contribute
 
 This is the single most important rule: **every file must be "galak" (strict/fierce).**
 
-Your contribution MUST be opinionated, specific, and enforceable. We reject generic advice.
-
-```
-BAD  (generic, useless):
-  "Use descriptive variable names."
-
-GOOD (specific, enforceable):
-  "NEVER use single-letter variables except `i` in `for(let i=0; i<n; i++)`.
-   Function names MUST start with a verb. Booleans MUST use is/has/can prefix."
-```
+Your contribution MUST be opinionated, specific, and enforceable. We reject generic advice, externally anchored rules, and borrowed-pattern guidance that can become accidental style anchors.
 
 ### The Litmus Test
-- Does your rule include concrete BANNED / REQUIRED examples?
+- Does your rule include concrete BANNED / REQUIRED boundaries?
 - Would an AI agent be able to enforce it without ambiguity?
 - Does it teach the reader WHY, not just WHAT?
 
@@ -54,11 +45,11 @@ If all three are "yes", it belongs here.
 
 ---
 
-## How to Add or Adjust Architecture Playbooks
+## How to Add or Adjust Structural Planning Guidance
 
-1. Update the architecture options in `.agent-context/prompts/init-project.md` and related discovery guidance.
+1. Update the planning guidance in `.agent-context/prompts/init-project.md` and related discovery guidance.
 2. Update compiler/init behavior if generated project-context guidance or bootstrap flow changes.
-3. Keep transport/service/repository separation and validation boundaries explicit in examples.
+3. Keep system boundaries, required docs, and validation boundaries explicit without silently recommending a framework from offline heuristics.
 4. Run `npm run validate` and `npm test`.
 5. Open a PR.
 
@@ -70,10 +61,10 @@ If all three are "yes", it belongs here.
 2. Structure:
    - Opening quote (sets the tone)
    - Core principle (1-2 sentences)
-   - BANNED / REQUIRED sections with code examples
-   - Decision tree or quick reference (if applicable)
+   - BANNED / REQUIRED sections with enforceable boundaries
+   - Decision tree or quick ruleset when it reduces ambiguity
 3. Update `AGENTS.md` rules manifest table
-4. Update `review-checklists/pr-checklist.md` if the rule should be checked in reviews
+4. Update `review-checklists/pr-checklist.md` when the rule is part of review scope
 5. Validate and PR
 
 ---
@@ -95,7 +86,7 @@ If all three are "yes", it belongs here.
 ## What We Don't Accept
 
 - Generic content that reads like it was auto-generated without thought
-- Rules without concrete code examples
+- Rules without concrete enforcement boundaries
 - Stack profiles for languages the author doesn't actually use in production
 - Blueprints that are just folder structures without code patterns
 - PRs that don't update the relevant manifest files (AGENTS.md, checklists)

package/README.md

@@ -14,7 +14,7 @@ Latest release: 3.0.9 (2026-04-20).
 
 Highlights in 3.0.9:
 - Design bootstrap prompts now rely on shipped project evidence instead of assuming extra docs exist in every initialized repository.
-- Dynamic UI design guidance now emphasizes structure, rationale, and anti-generic constraints without anchoring to example brand systems.
+- Dynamic UI design guidance now emphasizes structure, rationale, and anti-generic constraints without anchoring to brand systems.
 - Init prompts now point agents at the active onboarding and compiled-rule context that actually exists in target projects.
 
 </div>
@@ -31,26 +31,12 @@ npx @ryuenn3123/agentic-senior-core init
 
 One command to initialize rules, checklists, and strict AI coding guidelines context for your project.
 
-> **See [docs/deep-dive.md](docs/deep-dive.md) and [docs/roadmap.md](docs/roadmap.md) for advanced configuration, architect mode, snapshot, and realtime options.**
+> **See [docs/deep-dive.md](docs/deep-dive.md) and [docs/roadmap.md](docs/roadmap.md) for advanced configuration, planning mode, snapshot, and realtime options.**
 
 - This command writes `.agent-context/state/v3-purge-audit.json` and reports whether static directory deletion is safe.
 
 ---
 
-## Before / After
-
-```text
-Before:
-"Build me a user registration API"
-=> one file, weak validation, no typed errors, weak structure
-
-After:
-"Build me a user registration API"
-=> layered modules, validated inputs, typed errors, tests, docs updates
-```
-
----
-
 ## MCP Quick Setup (VS Code)
 
 1. Generate workspace MCP config:
@@ -73,7 +59,7 @@ If you see `Property $schema is not allowed`, keep `.vscode/mcp.json` without `$
 
 | Command | Purpose |
 |---------|---------|
-| `agentic-senior-core init` | Initialize strict AI coding guidelines (Federated Governance baseline) |
+| `agentic-senior-core init` | Initialize the project guidance pack and compiled AI rulebook |
 | `agentic-senior-core upgrade --dry-run` | Preview safe upgrades |
 | `agentic-senior-core optimize --show` | Show token optimization state |
 | `npm run audit:v3-purge` | Run deep purge readiness audit (no deletion) |
@@ -97,9 +83,9 @@ Use `--no-prune` if you want to keep legacy managed files.
 
 ## Terminology Mapping (Final)
 
-| Canonical Enterprise Term | Developer-Facing Alias | Usage Rule |
-|---------------------------|------------------------|------------|
-| Federated Governance | Federated Rules Operations | Use canonical term in compliance/audit artifacts. |
+| Canonical Term | Developer-Facing Alias | Usage Rule |
+|----------------|------------------------|------------|
+| Federated Governance | Federated Rules Operations | Use canonical term in formal policy artifacts. |
 | Governance Engine | Rules Engine | Use alias in onboarding and day-to-day developer docs. |
 | Guardrails | Quality Checks | Use alias in implementation guidance and quickstart docs. |
 

package/lib/cli/commands/init.mjs

@@ -14,18 +14,17 @@ import {
   INIT_PRESETS,
   PROFILE_PRESETS,
   GOLDEN_STANDARD_PROFILE_NAME,
-  BLUEPRINT_RECOMMENDATIONS,
-  FALLBACK_STACK_FILE_NAMES,
-  FALLBACK_BLUEPRINT_FILE_NAMES,
+  AGENT_DECISION_STACK_FILE_NAME,
+  AGENT_DECISION_BLUEPRINT_FILE_NAME,
   RUNTIME_ENVIRONMENT_CHOICES,
 } from '../constants.mjs';
 
 import {
   ensureDirectory,
-  askChoice,
   askYesNo,
   toTitleCase,
   matchFileNameFromInput,
+  normalizeChoiceInput,
   collectFileNames,
   formatBlockingSeverities,
   formatDuration,
@@ -41,20 +40,13 @@ import {
 } from '../detector.mjs';
 import { compileDynamicContext, writeSelectedPolicy, writeOnboardingReport } from '../compiler.mjs';
 import {
-  filterStackFileNamesByCandidates,
-  filterBlueprintFileNamesByCandidates,
   normalizeAdditionalStackSelection,
   normalizeAdditionalBlueprintSelection,
-  deriveAdditionalBlueprintFileNamesFromStacks,
-  resolveScopeStackCandidates,
-  resolveScopeBlueprintCandidates,
 } from '../init-selection.mjs';
 import {
   buildExistingProjectMajorConstraints,
   resolveDetectedSetupDecision,
 } from '../init-detection-flow.mjs';
-// Existing project quick confirmation prompt string is preserved for validator coverage:
-// Use detected setup for this existing project?
 import { runPreflightChecks } from '../preflight.mjs';
 import { createBackup } from '../backup.mjs';
 import {
@@ -77,7 +69,6 @@ import {
   createMemoryContinuityState,
   writeMemoryContinuityState,
 } from '../memory-continuity.mjs';
-import { recommendArchitecture } from '../architect.mjs';
 
 export { REPO_ROOT } from '../constants.mjs';
 export {
@@ -85,13 +76,67 @@ export {
   normalizeRuntimeEnvironmentKey,
 } from '../init-options.mjs';
 export {
-  filterStackFileNamesByCandidates,
-  filterBlueprintFileNamesByCandidates,
   resolveProjectScopeKeyFromLabel,
   normalizeAdditionalStackSelection,
   normalizeAdditionalBlueprintSelection,
 } from '../init-selection.mjs';
 
+function normalizeContextLine(rawText) {
+  return String(rawText || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+async function readTextIfExists(filePath) {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function extractMarkdownContext(rawMarkdown) {
+  return String(rawMarkdown || '')
+    .split(/\r?\n/)
+    .map((line) => normalizeContextLine(line.replace(/^#+\s*/, '')))
+    .filter((line) => line && !line.startsWith('---') && !line.startsWith('```'))
+    .slice(0, 3)
+    .join(' ');
+}
+
+async function inferExistingProjectDescriptionHint(targetDirectoryPath) {
+  const evidence = [];
+  const packageJsonContent = await readTextIfExists(path.join(targetDirectoryPath, 'package.json'));
+
+  if (packageJsonContent) {
+    try {
+      const packageManifest = JSON.parse(packageJsonContent);
+      const packageSummary = [
+        normalizeContextLine(packageManifest.name),
+        normalizeContextLine(packageManifest.description),
+      ].filter(Boolean).join(': ');
+
+      if (packageSummary) {
+        evidence.push(`package.json: ${packageSummary}`);
+      }
+    } catch {
+      // Invalid package metadata should not block init; other files can still provide context.
+    }
+  }
+
+  for (const relativeDocPath of ['docs/project-brief.md', 'docs/README.md', 'README.md']) {
+    const docContext = extractMarkdownContext(
+      await readTextIfExists(path.join(targetDirectoryPath, relativeDocPath))
+    );
+
+    if (docContext) {
+      evidence.push(`${relativeDocPath}: ${docContext}`);
+    }
+  }
+
+  return evidence.slice(0, 3).join(' | ');
+}
+
 export function resolveRuntimeEnvironmentKeyFromLabel(selectedRuntimeEnvironmentLabel) {
   const runtimeEnvironmentEntry = RUNTIME_ENVIRONMENT_CHOICES.find(
     (runtimeEnvironmentChoice) => runtimeEnvironmentChoice.label === selectedRuntimeEnvironmentLabel
@@ -218,18 +263,17 @@ function resolveSilentCiGuardrailsDefault({
   };
 }
 
-async function askStackSelection(promptMessage, selectableStackFileNames, userInterface) {
-  const stackDisplayChoices = selectableStackFileNames.map((stackFileName) => toTitleCase(stackFileName));
-  const selectedDisplayChoice = await askChoice(promptMessage, stackDisplayChoices, userInterface);
-  const selectedIndex = stackDisplayChoices.indexOf(selectedDisplayChoice);
-  return selectableStackFileNames[selectedIndex] || selectableStackFileNames[0] || null;
-}
+function normalizeExplicitProfileFileName(rawInput, discoveredFileNames) {
+  const matchedFileName = Array.isArray(discoveredFileNames) && discoveredFileNames.length > 0
+    ? matchFileNameFromInput(rawInput, discoveredFileNames)
+    : null;
+
+  if (matchedFileName) {
+    return matchedFileName;
+  }
 
-async function askBlueprintSelection(promptMessage, selectableBlueprintFileNames, userInterface) {
-  const blueprintDisplayChoices = selectableBlueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName));
-  const selectedDisplayChoice = await askChoice(promptMessage, blueprintDisplayChoices, userInterface);
-  const selectedIndex = blueprintDisplayChoices.indexOf(selectedDisplayChoice);
-  return selectableBlueprintFileNames[selectedIndex] || selectableBlueprintFileNames[0] || null;
+  const normalizedBaseName = normalizeChoiceInput(String(rawInput || '').replace(/\.md$/i, ''));
+  return normalizedBaseName ? `${normalizedBaseName}.md` : null;
 }
 
 function buildInitExistingProjectDesignIntentSeed({
@@ -238,14 +282,14 @@ function buildInitExistingProjectDesignIntentSeed({
   selectedStackFileName,
   selectedBlueprintFileName,
   uiScopeSignals,
-  architectureProjectDescription,
+  projectDescriptionHint,
 }) {
   const projectName = String(packageManifest?.name || path.basename(targetDirectoryPath)).trim() || 'existing-ui-project';
   const isMobileUiProject = String(selectedStackFileName || '').toLowerCase().includes('react-native')
     || String(selectedStackFileName || '').toLowerCase().includes('flutter')
     || uiScopeSignals.signalReasons.some((signalReason) => signalReason.includes('android') || signalReason.includes('ios'));
   const resolvedDomain = isMobileUiProject ? 'Mobile app' : 'Web application';
-  const projectDescription = String(packageManifest?.description || architectureProjectDescription || '').trim()
+  const projectDescription = String(packageManifest?.description || projectDescriptionHint || '').trim()
     || `Existing ${resolvedDomain.toLowerCase()} detected during init. Create a project-specific dynamic design contract before shipping new UI work.`;
 
   return buildDesignIntentSeedFromSignals({
@@ -310,12 +354,6 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
   try {
     const discoveredStackFileNames = await collectFileNames(path.join(AGENT_CONTEXT_DIR, 'stacks'));
     const discoveredBlueprintFileNames = await collectFileNames(path.join(AGENT_CONTEXT_DIR, 'blueprints'));
-    const stackFileNames = discoveredStackFileNames.length > 0
-      ? discoveredStackFileNames
-      : FALLBACK_STACK_FILE_NAMES;
-    const blueprintFileNames = discoveredBlueprintFileNames.length > 0
-      ? discoveredBlueprintFileNames
-      : FALLBACK_BLUEPRINT_FILE_NAMES;
 
     if (discoveredStackFileNames.length === 0 || discoveredBlueprintFileNames.length === 0) {
       console.log('[INFO] Static stack/blueprint profiles are not fully present. Using compatibility labels for dynamic reasoning mode.');
@@ -324,25 +362,18 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     const selectedPreset = initOptions.preset ? INIT_PRESETS[initOptions.preset] || null : null;
 
     const selectedStackFileNameFromOption = initOptions.stack
-      ? matchFileNameFromInput(initOptions.stack, stackFileNames)
+      ? normalizeExplicitProfileFileName(initOptions.stack, discoveredStackFileNames)
       : null;
     const selectedBlueprintFileNameFromOption = initOptions.blueprint
-      ? matchFileNameFromInput(initOptions.blueprint, blueprintFileNames)
+      ? normalizeExplicitProfileFileName(initOptions.blueprint, discoveredBlueprintFileNames)
       : null;
-    if (initOptions.stack && !selectedStackFileNameFromOption) {
-      throw new Error(`Unknown stack: ${initOptions.stack}`);
-    }
-
-    if (initOptions.blueprint && !selectedBlueprintFileNameFromOption) {
-      throw new Error(`Unknown blueprint: ${initOptions.blueprint}`);
-    }
 
     if (initOptions.preset && !selectedPreset) {
       throw new Error(`Unknown preset: ${initOptions.preset}`);
     }
 
     console.log(`\nAgentic-Senior-Core CLI v${CLI_VERSION}`);
-    console.log('I will copy rules operations assets (Federated Governance baseline) into your target folder and compile a single rulebook for your AI tools.');
+    console.log('I will copy the project guidance pack into your target folder and compile a single rulebook for your AI tools.');
 
     if (selectedPreset) {
       console.log(`Using preset: ${initOptions.preset} (${selectedPreset.description}).`);
@@ -418,10 +449,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     if (projectDetection.hasExistingProjectFiles) {
       console.log('\nExisting project detection transparency:');
 
-      if (projectDetection.recommendedStackFileName) {
+      if (projectDetection.detectedStackFileName) {
         const confidenceScoreLabel = Number(projectDetection.confidenceScore || 0).toFixed(2);
         console.log(
-          `- Detected stack: ${toTitleCase(projectDetection.recommendedStackFileName)} (${projectDetection.confidenceLabel}, score ${confidenceScoreLabel})`
+          `- Detected stack: ${toTitleCase(projectDetection.detectedStackFileName)} (${projectDetection.confidenceLabel}, score ${confidenceScoreLabel})`
         );
 
         if (projectDetection.secondaryStackFileNames?.length) {
@@ -444,17 +475,10 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     }
 
     const hasReliableDetectedStack = projectDetection.hasExistingProjectFiles
-      && projectDetection.recommendedStackFileName
+      && projectDetection.detectedStackFileName
       && (projectDetection.confidenceLabel === 'high' || projectDetection.confidenceLabel === 'medium');
 
-    const shouldAutoApplyDetectedStack = hasReliableDetectedStack
-      && !selectedStackFileNameFromOption
-      && !selectedPreset?.stack
-      && !selectedPolicyProfile.defaultStackFileName;
-    let detectedBlueprintFileName = projectDetection.recommendedBlueprintFileName
-      || BLUEPRINT_RECOMMENDATIONS[projectDetection.recommendedStackFileName]
-      || null;
-
+    const shouldAutoApplyDetectedStack = false;
     let selectedManualStackFileName = null;
     let selectedManualBlueprintFileName = null;
     let selectedAdditionalStackFileNames = [];
@@ -462,8 +486,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     let detectedSetupWasApplied = false;
     let selectedProjectScopeKey = 'both';
     let selectedProjectScopeLabel = resolveProjectScopeLabelFromKey('both');
-    let architectureRecommendation = null;
-    let architectureProjectDescription = String(initOptions.projectDescription || '').trim();
+    let projectDescriptionHint = String(initOptions.projectDescription || '').trim();
     let discoveryAnswers = null;
     const ciGuardrailsSelection = resolveSilentCiGuardrailsDefault({
       initOptions,
@@ -476,17 +499,20 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     const shouldRunInteractiveScaffolding = isInteractiveSession
       && (initOptions.scaffoldDocs === true || (initOptions.scaffoldDocs !== false && isFreshProjectTarget));
 
+    if (projectDetection.hasExistingProjectFiles && !projectDescriptionHint) {
+      projectDescriptionHint = await inferExistingProjectDescriptionHint(resolvedTargetDirectoryPath);
+      if (projectDescriptionHint) {
+        console.log(`- Project context evidence: ${projectDescriptionHint}`);
+      } else {
+        console.log('- Project context evidence: unresolved from lightweight file scan; agent must inspect project files before coding.');
+      }
+    }
+    detectionTransparency.projectContextEvidence = projectDescriptionHint || null;
+
     const detectedSetupDecision = await resolveDetectedSetupDecision({
       shouldAutoApplyDetectedStack,
       projectDetection,
-      stackFileNames,
-      blueprintFileNames,
-      userInterface,
-      isInteractiveSession,
       detectionTransparency,
-      askYesNo,
-      askStackSelection,
-      askBlueprintSelection,
       initialSelectedManualStackFileName: selectedManualStackFileName,
       initialSelectedManualBlueprintFileName: selectedManualBlueprintFileName,
       initialSelectedAdditionalStackFileNames: selectedAdditionalStackFileNames,
@@ -496,15 +522,13 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     selectedManualStackFileName = detectedSetupDecision.selectedManualStackFileName;
     selectedManualBlueprintFileName = detectedSetupDecision.selectedManualBlueprintFileName;
     selectedAdditionalStackFileNames = detectedSetupDecision.selectedAdditionalStackFileNames;
-    detectedBlueprintFileName = detectedSetupDecision.detectedBlueprintFileName;
-
     if (initOptions.projectConfig) {
       discoveryAnswers = await loadProjectConfig(initOptions.projectConfig);
       console.log(`\nLoaded project configuration from: ${initOptions.projectConfig}`);
     } else if (shouldRunInteractiveScaffolding) {
       discoveryAnswers = await runProjectDiscovery(userInterface, {
         defaultProjectName: path.basename(resolvedTargetDirectoryPath),
-        defaultProjectDescription: architectureProjectDescription,
+        defaultProjectDescription: projectDescriptionHint,
         defaultIncludeCiGuardrails: ciGuardrailsSelection.value,
         askForCiGuardrails: ciGuardrailsSelection.shouldAsk,
       });
@@ -513,7 +537,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
     }
 
     if (discoveryAnswers?.projectDescription) {
-      architectureProjectDescription = discoveryAnswers.projectDescription;
+      projectDescriptionHint = discoveryAnswers.projectDescription;
     }
 
     if (discoveryAnswers) {
@@ -521,98 +545,26 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       selectedProjectScopeLabel = resolveProjectScopeLabelFromKey(selectedProjectScopeKey);
     }
 
-    const shouldUseSilentArchitectureSelection = !selectedStackFileNameFromOption
-      && !selectedPreset?.stack
-      && !shouldAutoApplyDetectedStack
-      && !selectedPolicyProfile.defaultStackFileName;
-
-    if (shouldUseSilentArchitectureSelection) {
-      const architectureScopeStackCandidates = filterStackFileNamesByCandidates(
-        stackFileNames,
-        resolveScopeStackCandidates(selectedProjectScopeKey)
-      );
-      const architectureScopeBlueprintCandidates = filterBlueprintFileNamesByCandidates(
-        blueprintFileNames,
-        resolveScopeBlueprintCandidates(selectedProjectScopeKey)
-      );
-
-      architectureRecommendation = recommendArchitecture({
-        projectDescription: architectureProjectDescription || `A software project named ${path.basename(resolvedTargetDirectoryPath)}.`,
-        projectDetection,
-        stackFileNames: architectureScopeStackCandidates,
-        blueprintFileNames: architectureScopeBlueprintCandidates,
-      });
-
-      architectureRecommendation.projectDomain = {
-        key: selectedProjectScopeKey,
-        label: selectedProjectScopeLabel,
-      };
-      architectureRecommendation.userVeto = {
-        applied: false,
-        selectedStackFileName: architectureRecommendation.recommendedStackFileName,
-        selectedBlueprintFileName: architectureRecommendation.recommendedBlueprintFileName,
-        source: projectDetection.hasExistingProjectFiles ? 'silent-existing-bootstrap' : 'silent-fresh-bootstrap',
-      };
-
-      selectedManualStackFileName = architectureRecommendation.recommendedStackFileName;
-      selectedManualBlueprintFileName = architectureRecommendation.recommendedBlueprintFileName;
-
-      if (!projectDetection.hasExistingProjectFiles) {
-        detectionTransparency.quickConfirmation.response = 'fresh-project-streamlined';
-        detectionTransparency.decision.mode = 'fresh-project-streamlined';
-      }
-    }
-
-    const blueprintDisplayChoices = blueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName));
-
     const selectedResolvedStackFileName = selectedStackFileNameFromOption
-      || selectedPreset?.stack
       || selectedManualStackFileName
-      || (detectedSetupWasApplied ? projectDetection.recommendedStackFileName : null)
       || selectedPolicyProfile.defaultStackFileName
-      || stackFileNames[0];
+      || AGENT_DECISION_STACK_FILE_NAME;
 
     selectedAdditionalStackFileNames = normalizeAdditionalStackSelection(
       selectedResolvedStackFileName,
       selectedAdditionalStackFileNames
     );
 
-    const recommendedBlueprintFileName = detectedSetupWasApplied
-      && detectedBlueprintFileName
-      ? detectedBlueprintFileName
-      : BLUEPRINT_RECOMMENDATIONS[selectedResolvedStackFileName] || null;
-
-    if (!recommendedBlueprintFileName && !selectedBlueprintFileNameFromOption && !selectedPolicyProfile.defaultBlueprintFileName) {
-      console.log('\nI could not map that stack to a first-party blueprint automatically, so I will ask you to choose one.');
-    }
-
     const selectedResolvedBlueprintFileName = selectedBlueprintFileNameFromOption
-      || selectedPreset?.blueprint
       || selectedManualBlueprintFileName
-      || recommendedBlueprintFileName
       || selectedPolicyProfile.defaultBlueprintFileName
-      || blueprintFileNames[
-        blueprintDisplayChoices.indexOf(
-          await askChoice('Which blueprint should I scaffold into the compiled rulebook?', blueprintDisplayChoices, userInterface)
-        )
-      ];
-
-    if (architectureRecommendation) {
-      architectureRecommendation.appliedStackFileName = selectedResolvedStackFileName;
-      architectureRecommendation.appliedBlueprintFileName = selectedResolvedBlueprintFileName;
-    }
-
-    const derivedAdditionalBlueprintFileNames = deriveAdditionalBlueprintFileNamesFromStacks(
-      selectedAdditionalStackFileNames,
-      blueprintFileNames,
-      selectedResolvedBlueprintFileName
-    );
+      || AGENT_DECISION_BLUEPRINT_FILE_NAME;
 
     selectedAdditionalBlueprintFileNames = normalizeAdditionalBlueprintSelection(
       selectedResolvedBlueprintFileName,
       selectedAdditionalBlueprintFileNames.length > 0
         ? selectedAdditionalBlueprintFileNames
-        : derivedAdditionalBlueprintFileNames
+        : []
     );
 
     detectionTransparency.decision.selectedStackFileName = selectedResolvedStackFileName;
@@ -696,7 +648,6 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
           additionalBlueprintFileNames: selectedAdditionalBlueprintFileNames,
           runtimeEnvironmentKey: selectedRuntimeEnvironmentKey,
           runtimeEnvironmentLabel: resolveRuntimeEnvironmentLabelFromKey(selectedRuntimeEnvironmentKey),
-          architectureRecommendation,
         },
         {
           docsLanguage: selectedDocsLanguage,
@@ -740,7 +691,7 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         selectedStackFileName: selectedResolvedStackFileName,
         selectedBlueprintFileName: selectedResolvedBlueprintFileName,
         uiScopeSignals: existingProjectUiScopeSignals,
-        architectureProjectDescription,
+        projectDescriptionHint,
       });
 
       await ensureDirectory(docsDirectoryPath);
@@ -798,7 +749,6 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         adapters: memoryContinuityState?.adapters || [],
         stateFile: isMemoryContinuityEnabled ? '.agent-context/state/memory-continuity.json' : null,
       },
-      architectRecommendation: architectureRecommendation,
       detectionTransparency,
       uiScopeSignals: existingProjectUiScopeSignals,
     });
@@ -814,11 +764,11 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
         console.log(`- Project topology: ${discoveryAnswers.architectureStyle}`);
       }
     }
-    console.log(`- Stack: ${toTitleCase(selectedResolvedStackFileName)}`);
+    console.log(`- Runtime decision: ${selectedResolvedStackFileName === AGENT_DECISION_STACK_FILE_NAME ? 'agent recommendation required from current repo/brief evidence' : toTitleCase(selectedResolvedStackFileName)}`);
     if (selectedAdditionalStackFileNames.length > 0) {
       console.log(`- Additional stacks: ${selectedAdditionalStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ')}`);
     }
-    console.log(`- Blueprint: ${toTitleCase(selectedResolvedBlueprintFileName)}`);
+    console.log(`- Architecture decision: ${selectedResolvedBlueprintFileName === AGENT_DECISION_BLUEPRINT_FILE_NAME ? 'agent recommendation required from current repo/brief evidence' : toTitleCase(selectedResolvedBlueprintFileName)}`);
     if (selectedAdditionalBlueprintFileNames.length > 0) {
       console.log(`- Additional blueprints: ${selectedAdditionalBlueprintFileNames.map((blueprintFileName) => toTitleCase(blueprintFileName)).join(', ')}`);
     }
@@ -854,7 +804,11 @@ export async function runInitCommand(targetDirectoryArgument, initOptions = {})
       console.log('- Token optimization policy: disabled (--no-token-optimize)');
     }
     console.log('\nPlain-language summary:');
-    console.log(`I prepared a repo-grounded rules operations pack (Federated Governance baseline) for a ${toTitleCase(selectedResolvedStackFileName)} project using the ${toTitleCase(selectedResolvedBlueprintFileName)} blueprint.`);
+    if (selectedResolvedStackFileName === AGENT_DECISION_STACK_FILE_NAME || selectedResolvedBlueprintFileName === AGENT_DECISION_BLUEPRINT_FILE_NAME) {
+      console.log('I prepared a repo-grounded guidance pack that asks your AI agent to recommend runtime and architecture choices from the current brief, repo evidence, and live research before coding.');
+    } else {
+      console.log(`I prepared a repo-grounded guidance pack using your explicit runtime constraint (${toTitleCase(selectedResolvedStackFileName)}) and architecture constraint (${toTitleCase(selectedResolvedBlueprintFileName)}).`);
+    }
     if (selectedAdditionalStackFileNames.length > 0) {
       console.log(`I also included additional stack context for ${selectedAdditionalStackFileNames.map((stackFileName) => toTitleCase(stackFileName)).join(', ')}.`);
     }

package/lib/cli/commands/launch.mjs

@@ -21,7 +21,7 @@ export async function runLaunchCommand() {
       'How do you want to start?',
       [
         'npm / npx path',
-        'Preset starter',
+        'Scope hint preset',
         'Interactive init wizard',
         'Enable token optimization',
         'Exit',
@@ -37,10 +37,10 @@ export async function runLaunchCommand() {
       return;
     }
 
-    if (launchChoice === 'Preset starter') {
+    if (launchChoice === 'Scope hint preset') {
       const presetNames = Object.keys(INIT_PRESETS);
       const selectedPresetName = await askChoice(
-        'Choose a starter preset:',
+        'Choose a scope hint preset:',
         presetNames.map((presetName) => `${presetName} - ${INIT_PRESETS[presetName].description}`),
         userInterface
       );

package/lib/cli/commands/optimize.mjs

@@ -3,6 +3,10 @@ import path from 'node:path';
 
 import { ensureDirectory, formatDuration } from '../utils.mjs';
 import { compileDynamicContext, loadOnboardingReportIfExists } from '../compiler.mjs';
+import {
+  AGENT_DECISION_STACK_FILE_NAME,
+  AGENT_DECISION_BLUEPRINT_FILE_NAME,
+} from '../constants.mjs';
 import {
   TOKEN_OPTIMIZATION_REPORT_FILE_NAME,
   normalizeAgentName,
@@ -115,14 +119,20 @@ export async function runOptimizeCommand(targetDirectoryArgument, optimizeOption
 
   await writeTokenOptimizationState(resolvedTargetDirectoryPath, tokenOptimizationState);
 
-  const selectedStackFileName = normalizeMarkdownFileName(onboardingReport.selectedStack, 'typescript.md');
-  const selectedAdditionalStackFileNames = Array.isArray(onboardingReport.selectedAdditionalStacks)
+  const hasExplicitRuntimeConstraint = onboardingReport?.runtimeDecision?.mode === 'explicit-constraint';
+  const hasExplicitArchitectureConstraint = onboardingReport?.architectureDecision?.mode === 'explicit-constraint';
+  const selectedStackFileName = hasExplicitRuntimeConstraint
+    ? normalizeMarkdownFileName(onboardingReport.selectedStack, AGENT_DECISION_STACK_FILE_NAME)
+    : AGENT_DECISION_STACK_FILE_NAME;
+  const selectedAdditionalStackFileNames = hasExplicitRuntimeConstraint && Array.isArray(onboardingReport.selectedAdditionalStacks)
     ? onboardingReport.selectedAdditionalStacks
       .map((stackFileName) => normalizeMarkdownFileName(stackFileName, ''))
       .filter((stackFileName) => stackFileName && stackFileName !== selectedStackFileName)
     : [];
-  const selectedBlueprintFileName = normalizeMarkdownFileName(onboardingReport.selectedBlueprint, 'api-nextjs.md');
-  const selectedAdditionalBlueprintFileNames = Array.isArray(onboardingReport.selectedAdditionalBlueprints)
+  const selectedBlueprintFileName = hasExplicitArchitectureConstraint
+    ? normalizeMarkdownFileName(onboardingReport.selectedBlueprint, AGENT_DECISION_BLUEPRINT_FILE_NAME)
+    : AGENT_DECISION_BLUEPRINT_FILE_NAME;
+  const selectedAdditionalBlueprintFileNames = hasExplicitArchitectureConstraint && Array.isArray(onboardingReport.selectedAdditionalBlueprints)
     ? onboardingReport.selectedAdditionalBlueprints
       .map((blueprintFileName) => normalizeMarkdownFileName(blueprintFileName, ''))
       .filter((blueprintFileName) => blueprintFileName && blueprintFileName !== selectedBlueprintFileName)