@ryuenn3123/agentic-senior-core 3.0.37 → 3.0.38

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

@@ -92,6 +92,7 @@ export function buildDesignBootstrapPrompt({
     '',
     'You are the Lead UI/UX Art Director for this project.',
     'Create a dynamic design contract, not a fixed stylistic template.',
+    'Use imperative, compact, mechanical rules.',
     '',
     '## Mission',
     `Author docs/DESIGN.md in ${docsLanguage.toUpperCase()} language with strong art direction and engineering-ready guidance.`,
@@ -102,104 +103,88 @@ export function buildDesignBootstrapPrompt({
     '2. docs/design-intent.json',
     '',
     '## Required DESIGN.md Sections',
-    '1. Design Vision and Product Personality',
+    '1. Design Intent and Product Personality',
     '2. Audience and Use-Context Signals',
     '3. Visual Direction and Distinctive Moves',
-    '4. Color Science and Semantic Roles',
-    '5. Typographic Engineering and Hierarchy',
-    '6. Spacing, Layout Rhythm, and Density Strategy',
-    '7. Token Architecture and Alias Strategy',
-    '8. Responsive Strategy and Cross-Viewport Adaptation Matrix',
-    '9. Motion and Interaction Principles',
-    '10. Component Language and Morphology (cards, forms, nav, states)',
-    '11. Context Hygiene and Source Boundaries',
-    '12. Accessibility Non-Negotiables',
-    '13. Anti-Patterns to Avoid',
-    '14. Implementation Notes for Future UI Tasks',
+    '4. Color, Typography, Spacing, and Density Decisions',
+    '5. Token Architecture and Alias Strategy',
+    '6. Responsive Strategy and Cross-Viewport Adaptation Matrix',
+    '7. Motion and Interaction Rules',
+    '8. Component Language and Morphology',
+    '9. Context Hygiene and Source Boundaries',
+    '10. Accessibility Non-Negotiables',
+    '11. Anti-Patterns to Avoid',
+    '12. Implementation Notes for Future UI Tasks',
     '',
     '## Required design-intent.json Fields',
     '1. mode',
     '2. status',
     '3. project',
     '4. designPhilosophy',
-    '5. brandAdjectives',
-    '6. antiAdjectives',
-    '7. visualDirection',
+    '5. visualDirection',
+    '6. externalResearchIntake',
+    '7. conceptualAnchor',
     '8. derivedTokenLogic',
-    '9. aiSafeUiAudit',
-    '10. libraryResearchStatus',
-    '11. libraryDecisions',
-    '12. mathSystems',
-    '13. tokenSystem',
-    '14. colorTruth',
-    '15. crossViewportAdaptation',
-    '16. motionSystem',
-    '17. componentMorphology',
-    '18. accessibilityPolicy',
-    '19. designExecutionPolicy',
-    '20. designExecutionHandoff',
-    '21. reviewRubric',
-    '22. contextHygiene',
-    '23. experiencePrinciples',
+    '9. motionPaletteDecision',
+    '10. aiSafeUiAudit',
+    '11. libraryResearchStatus',
+    '12. libraryDecisions',
+    '13. mathSystems',
+    '14. tokenSystem',
+    '15. colorTruth',
+    '16. crossViewportAdaptation',
+    '17. motionSystem',
+    '18. componentMorphology',
+    '19. accessibilityPolicy',
+    '20. designExecutionPolicy',
+    '21. designExecutionHandoff',
+    '22. reviewRubric',
+    '23. contextHygiene',
     '24. forbiddenPatterns',
-    '25. validationHints',
-    '26. requiredDesignSections',
-    '27. implementation',
-    '28. repoEvidence when onboarding or detector evidence exists',
-    '',
-    '## Hard Rules',
-    '1. No copy-paste from external style guides.',
-    '2. Every major decision must include psychological/product rationale.',
-    '3. Do not choose the final style, framework, component library, animation library, palette, typography, or layout paradigm from this offline scaffold. If unresolved, require an agent recommendation from repo evidence and live official docs before coding.',
-    '4. Keep tone decisive like an art director, not generic AI boilerplate.',
-    '5. Do not anchor the final design language to famous products, benchmark visuals, or external reference surfaces.',
-    '6. Reject interchangeable hero layouts, generic SaaS gradients, and trend-chasing decoration unless the project context explicitly justifies them.',
-    '7. Encode color intent in perceptual terms first. Hex values may exist only as implementation derivatives.',
-    '8. Token guidance must define primitive, semantic, and component layers plus aliasing rules. Component tokens must consume semantic aliases instead of raw values.',
-    '9. Responsive guidance must include layout mutation rules for mobile, tablet, and desktop. Shrinking the desktop layout is not enough.',
-    '10. Do not let repeated surfaces, component-kit defaults, or safe typography become the final direction without explicit product rationale.',
-    '11. The LLM must choose color, type, spacing, density, morphology, and motion dynamically from the active project context instead of copying this seed.',
-    '12. Viewport mutation must be operation-based. For each viewport, define the primary mutation operation, required surface actions, and forbidden responsive fallback patterns.',
-    '13. Default to a rich motion plan for modern UI work. Motion can be bold, cinematic, spatial, scroll-linked, or highly expressive when it improves memorability, hierarchy, feedback, or product confidence. If a motion library is useful, research current official docs and select the latest stable compatible option instead of using an offline default. Solve clarity, accessibility, and runtime risks without falling back to a static interface by habit.',
-    '14. Define component morphology across interaction states and viewports so cards, forms, nav, and feedback surfaces adapt coherently instead of only resizing.',
-    '15. Keep UI-only requests context-isolated. Load frontend design rules first and do not eagerly load backend-only or workflow-only rules unless the task explicitly crosses those boundaries.',
-    '16. Treat WCAG 2.2 AA as the hard accessibility floor. Use APCA only as advisory perceptual tuning, never as a reason to waive a WCAG failure.',
-    '17. Accessibility planning must explicitly cover focus visibility, focus appearance, target size, accessible authentication, keyboard access, and dynamic status/state access.',
-    '18. Structured design execution must stay representation-first. Define a surface plan, component graph, content-priority map, viewport mutation plan, and interaction-state matrix before relying on semantic review.',
-    '19. design-intent.json must carry an explicit structured handoff, not just policy flags. The handoff must make surface plans, component relationships, task flow, and signature moves executable before coding starts.',
-    '20. Do not depend on screenshot capture, browser automation, or image diff artifacts as the default path. The contract must be strong enough to guide precise UI from repo evidence, component logic, and user intent alone.',
-    '21. Semantic review must judge contract fidelity, distinctiveness, hierarchy, state behavior, and viewport mutation directly from the contract and changed UI code.',
-    '22. Treat prior website memory, unrelated project aesthetics, and remembered screenshots as tainted context unless the user explicitly approves continuity.',
-    '23. Design continuity is opt-in. If no approved continuity exists, synthesize from the current repo evidence, current brief, and current project docs only.',
-    '24. Make at least one memorable visual bet so the resulting system is recognizable and not template-neutral.',
-    '24a. Do not ship AI-safe UI: predictable card stacks, rounded template panels, generic abstract logos, decorative grid wallpaper, beige or slate safety palettes, soft glow backgrounds, or first-output composition with only local copy swapped in are review findings.',
-    '24b. New screens and broad redesigns must expose at least three at-a-glance product-specific signals and pass the rename test: if the UI can be renamed to another product category without changing composition, palette, iconography, and motion language, revise it before coding.',
-    '24c. Background lines, grids, scanlines, noise, glows, blobs, logos, and geometric decoration must serve a named product function such as alignment, measurement, navigation, crop guidance, timeline reading, status, or motion continuity.',
-    '24d. Use visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity; readability must not become an excuse for cream, slate, monochrome, or gradient defaults.',
-    '24e. Complete the AI color audit before coding: palette choices must explain product evidence, semantic role behavior, and at least one color behavior that would not transfer cleanly to another product category.',
-    '24f. Meet the creative ambition floor before coding: name one authored visual bet, one product-derived palette move, one signature motion/spatial/interaction behavior, and one morphology or composition choice that breaks away from interchangeable card stacks when the product allows it.',
-    '24g. Treat motion, 3D, canvas, WebGL, scroll choreography, and modern animation libraries as first-class options. If they are omitted, document the product, content-density, device, performance, or accessibility reason and the replacement interaction quality.',
-    '25. Define a stable review rubric for distinctiveness, contract fidelity, visual consistency, heuristic UX quality, and motion discipline.',
-    '26. Genericity findings must name the actual drift signal. Do not label something generic without explaining the anti-pattern or rubric dimension.',
-    '27. Review rubric must support automatic genericity failure when named drift signals dominate a redesign or new UI surface.',
-    '28. Separate taste from failure. Bold direction is allowed when it still follows the contract, serves the product, and stays accessible.',
-    '29. If a future user asks for zero-based redesign ("redesign from zero", "redesain dari 0", "ulang dari 0", or "research ulang"), treat existing UI as content and behavior evidence only, not as visual continuity.',
-    '30. In zero-based redesign mode, the new contract must name the discarded prior visual DNA and materially reset composition, hierarchy, palette/typography, motion or interaction, and responsive information architecture.',
-    '31. If modern UI, animation, scroll, 3D, canvas, chart, or icon libraries are useful, choose them from current official docs and record source URL, fetched date, reason, risk, and accessibility fallback.',
-    '32. If the user supplies research files, library lists, screenshots, articles, or benchmark notes, read them as candidate evidence, summarize the useful signals, filter by project fit, and verify technology claims against current official docs before implementation.',
-    '33. If no user-supplied research or reference is supplied for UI work, activate the Dynamic Avant-Garde Anchor Engine before coding. User-supplied research means current-task evidence from the user; this scaffold, prior UI, and old design docs do not count as research.',
-    '34. Before broad compliance review, make a creative commitment and record it in the design contract: one specific real-world anchor reference, one signature motion behavior more specific than smooth transitions, and one typographic decision with meaningful role contrast.',
-    '35. In Dynamic Avant-Garde mode, perform agent-led research when available, then internally consider at least three high-variance conceptual anchors, discard the two safest or most predictable options, output only the chosen anchor, its specific reference point, and rationale, and forbid final anchors named dashboard, portal, cards, admin panel, SaaS shell, web app shell, or minimalist interface.',
-    '36. Reject anchors that can only be described with generic quality words such as modern, clean, premium, expressive, minimal, or bold. The anchor must name a material, instrument, artifact class, architecture, editorial genre, cinematic behavior, exhibition system, scientific apparatus, or industrial mechanism.',
-    '37. The chosen anchor must define a stable conceptualAnchor.anchorReference. derivedTokenLogic.anchorReference must match it exactly so validation does not depend on paraphrased prose.',
-    '38. Fill derivedTokenLogic with color, spacing, typography, and motion derivation sources before UI implementation. If a token cannot be explained from anchorReference, revise the token.',
-    '39. If live web research is unavailable or fails, do not hallucinate dependency APIs, package names, versions, or imports. 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.',
-    '40. Every libraryDecisions entry must either include current official-doc verification metadata or a fallbackIfUnavailable. Do not import a new library without verification or an accepted blocker.',
-    '41. The chosen anchor must drive typography, spacing, density, color behavior, morphology, motion, and responsive composition. Treat expressive motion, spatial transitions, micro-interactions, and modern animation libraries as first-class options; include performance notes and reduced-motion fallbacks instead of suppressing motion to look safe.',
+    '25. requiredDesignSections',
+    '26. implementation',
+    '27. repoEvidence when onboarding or detector evidence exists',
+    '',
+    '## Mechanical Gates',
+    '1. Do not copy external style guides.',
+    '2. Do not anchor the final design language to famous products, benchmark visuals, or external reference surfaces.',
+    '3. Do not choose final style, library, palette, typography, motion, or layout from this offline scaffold.',
+    '4. Use repo evidence, active brief, current docs, and current official docs for technology choices.',
+    '5. Keep UI-only requests context-isolated; load frontend rules first.',
+    '6. Preserve Design continuity is opt-in. Use current repo evidence unless the user approves continuity.',
+    '7. Treat prior website memory, unrelated project aesthetics, remembered screenshots, and old design docs as tainted unless approved.',
+    '8. Use primitive, semantic, and component tokens. Component tokens must consume semantic aliases.',
+    '9. Encode colorTruth in perceptual terms. Hex values are implementation derivatives.',
+    '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.',
+    '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.',
+    '16. Do not depend on screenshot capture, browser automation, or image diffs as the default quality path.',
+    '17. Make one memorable visual bet before code.',
+    '18. Do not ship AI-safe UI, decorative grid wallpaper, generic SaaS gradients, or default component-kit styling without product rationale.',
+    '19. Use visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.',
+    '20. Complete the AI color audit before code.',
+    '21. Treat motion, 3D, canvas, WebGL, scroll choreography, and modern animation libraries as first-class options.',
+    '22. If motion or spatial UI is omitted, document the product-fit reason and replacement interaction quality.',
+    '23. If the user supplies research files, library lists, screenshots, articles, or benchmark notes, read them as candidate evidence and verify technology claims.',
+    '24. If no user-supplied research or reference exists, activate the Dynamic Avant-Garde Anchor Engine before coding; old design docs do not count as research.',
+    '25. In Dynamic Avant-Garde mode, consider three high-variance anchors, discard the two safest or most predictable options, and output only the chosen anchor.',
+    '26. Reject final anchors named dashboard, portal, cards, admin panel, SaaS shell, web app shell, or minimalist interface.',
+    '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.',
+    '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.',
     '',
     '## 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.',
     'The ambition floor is not a fixed aesthetic. Quiet, dense, utilitarian, or text-heavy interfaces are allowed when the product requires them, but they still need a project-specific visual decision and a real reason for omitting richer motion, 3D, canvas, WebGL, scroll choreography, or animation libraries.',
+    'Use reduced-motion fallbacks instead of suppressing motion.',
     '',
     '## Token Derivation Audit',
     'Before implementation, docs/design-intent.json must include derivedTokenLogic.anchorReference plus colorDerivationSource, spacingDerivationSource, typographyDerivationSource, motionDerivationSource, and validationRule.',

package/lib/cli/utils/filesystem.mjs

@@ -0,0 +1,79 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function pathExists(targetPath) {
+  try {
+    await fs.stat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function ensureDirectory(directoryPath) {
+  await fs.mkdir(directoryPath, { recursive: true });
+}
+
+export async function copyDirectory(sourceDirectoryPath, targetDirectoryPath) {
+  if (path.resolve(sourceDirectoryPath) === path.resolve(targetDirectoryPath)) {
+    return;
+  }
+
+  await ensureDirectory(targetDirectoryPath);
+  const directoryEntries = await fs.readdir(sourceDirectoryPath, { withFileTypes: true });
+
+  for (const directoryEntry of directoryEntries) {
+    const sourceEntryPath = path.join(sourceDirectoryPath, directoryEntry.name);
+    const targetEntryPath = path.join(targetDirectoryPath, directoryEntry.name);
+
+    if (directoryEntry.isDirectory()) {
+      await copyDirectory(sourceEntryPath, targetEntryPath);
+      continue;
+    }
+
+    if (path.resolve(sourceEntryPath) === path.resolve(targetEntryPath)) {
+      continue;
+    }
+
+    await fs.copyFile(sourceEntryPath, targetEntryPath);
+  }
+}
+
+export function isAgenticManagedContent(content) {
+  const normalizedContent = Buffer.isBuffer(content)
+    ? content.toString('utf8')
+    : String(content || '');
+
+  return [
+    'Agentic-Senior-Core',
+    'AGENTIC-SENIOR-CORE',
+    'Adapter Mode: thin',
+    'Adapter Mode: legacy-thin',
+    'Canonical Snapshot SHA256',
+    'Canonical baseline: .instructions.md',
+  ].some((managedSignal) => normalizedContent.includes(managedSignal));
+}
+
+export async function syncFile(sourcePath, targetPath, options = {}) {
+  if (!(await pathExists(sourcePath))) return { status: 'skipped' };
+
+  if (!(await pathExists(targetPath))) {
+    await ensureDirectory(path.dirname(targetPath));
+    await fs.copyFile(sourcePath, targetPath);
+    return { status: 'created' };
+  }
+
+  const sourceContent = await fs.readFile(sourcePath);
+  const targetContent = await fs.readFile(targetPath);
+
+  if (sourceContent.equals(targetContent)) {
+    return { status: 'unchanged' };
+  }
+
+  if (options.preserveUserOwned === true && !isAgenticManagedContent(targetContent)) {
+    return { status: 'preserved' };
+  }
+
+  await fs.copyFile(sourcePath, targetPath);
+  return { status: 'updated' };
+}

package/lib/cli/utils/managed-surface.mjs

@@ -0,0 +1,237 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  REPO_ROOT,
+  entryPointFiles,
+  directoryCopies,
+} from '../constants.mjs';
+import { pathExists } from './filesystem.mjs';
+
+function toPosixRelativePath(relativePath) {
+  return relativePath.split(path.sep).join('/');
+}
+
+function isPathWithinPrefix(relativePath, prefixPath) {
+  const normalizedRelativePath = toPosixRelativePath(relativePath).replace(/\/+$/g, '');
+  const normalizedPrefixPath = toPosixRelativePath(prefixPath).replace(/\/+$/g, '');
+
+  if (!normalizedPrefixPath) {
+    return false;
+  }
+
+  return normalizedRelativePath === normalizedPrefixPath
+    || normalizedRelativePath.startsWith(`${normalizedPrefixPath}/`);
+}
+
+const localOnlyGovernanceFiles = new Set([
+  '.agent-context/state/active-memory.json',
+  '.agent-context/state/v3-purge-audit.json',
+]);
+
+function isLocalOnlyGovernanceFile(relativePath) {
+  return localOnlyGovernanceFiles.has(toPosixRelativePath(relativePath));
+}
+
+export async function collectRelativeTreeEntries(baseDirectoryPath, relativeRootPath) {
+  const files = [];
+  const directories = [];
+
+  if (!(await pathExists(baseDirectoryPath))) {
+    return { files, directories };
+  }
+
+  const normalizedRootPath = toPosixRelativePath(relativeRootPath);
+  directories.push(normalizedRootPath);
+
+  async function walkDirectory(currentDirectoryPath, currentRelativePath) {
+    const directoryEntries = await fs.readdir(currentDirectoryPath, { withFileTypes: true });
+
+    for (const directoryEntry of directoryEntries) {
+      const sourceEntryPath = path.join(currentDirectoryPath, directoryEntry.name);
+      const relativeEntryPath = toPosixRelativePath(path.join(currentRelativePath, directoryEntry.name));
+
+      if (directoryEntry.isDirectory()) {
+        directories.push(relativeEntryPath);
+        await walkDirectory(sourceEntryPath, relativeEntryPath);
+        continue;
+      }
+
+      if (isLocalOnlyGovernanceFile(relativeEntryPath)) {
+        continue;
+      }
+
+      files.push(relativeEntryPath);
+    }
+  }
+
+  await walkDirectory(baseDirectoryPath, normalizedRootPath);
+  return { files, directories };
+}
+
+async function collectOptionalManagedEntries(baseDirectoryPath, options = {}) {
+  const files = new Set();
+  const directories = new Set();
+
+  if (options.includeMcpTemplate === true) {
+    const mcpServerEntrypointPath = path.join(baseDirectoryPath, 'scripts', 'mcp-server.mjs');
+    if (await pathExists(mcpServerEntrypointPath)) {
+      files.add('scripts/mcp-server.mjs');
+    }
+
+    const mcpServerHelpersDirectoryPath = path.join(baseDirectoryPath, 'scripts', 'mcp-server');
+    const mcpServerTreeEntries = await collectRelativeTreeEntries(
+      mcpServerHelpersDirectoryPath,
+      'scripts/mcp-server'
+    );
+
+    for (const relativeFilePath of mcpServerTreeEntries.files) {
+      files.add(relativeFilePath);
+    }
+
+    for (const relativeDirectoryPath of mcpServerTreeEntries.directories) {
+      directories.add(relativeDirectoryPath);
+    }
+  }
+
+  return { files, directories };
+}
+
+async function buildManagedSourceManifest(options = {}) {
+  const sourceFiles = new Set();
+  const sourceDirectories = new Set();
+
+  for (const sourceDirectoryName of directoryCopies) {
+    const sourceDirectoryPath = path.join(REPO_ROOT, sourceDirectoryName);
+    const sourceTreeEntries = await collectRelativeTreeEntries(sourceDirectoryPath, sourceDirectoryName);
+
+    for (const sourceFilePath of sourceTreeEntries.files) {
+      sourceFiles.add(sourceFilePath);
+    }
+
+    for (const sourceDirectoryPathRelative of sourceTreeEntries.directories) {
+      sourceDirectories.add(sourceDirectoryPathRelative);
+    }
+  }
+
+  for (const entryPointFileName of entryPointFiles) {
+    const sourceFilePath = path.join(REPO_ROOT, entryPointFileName);
+    if (!(await pathExists(sourceFilePath))) {
+      continue;
+    }
+
+    sourceFiles.add(toPosixRelativePath(entryPointFileName));
+  }
+
+  const optionalManagedEntries = await collectOptionalManagedEntries(REPO_ROOT, options);
+  for (const sourceFilePath of optionalManagedEntries.files) {
+    sourceFiles.add(sourceFilePath);
+  }
+  for (const sourceDirectoryPath of optionalManagedEntries.directories) {
+    sourceDirectories.add(sourceDirectoryPath);
+  }
+
+  return {
+    files: sourceFiles,
+    directories: sourceDirectories,
+  };
+}
+
+async function collectManagedTargetManifest(resolvedTargetDirectoryPath, options = {}) {
+  const targetFiles = new Set();
+  const targetDirectories = new Set();
+
+  for (const sourceDirectoryName of directoryCopies) {
+    const targetDirectoryPath = path.join(resolvedTargetDirectoryPath, sourceDirectoryName);
+    const targetTreeEntries = await collectRelativeTreeEntries(targetDirectoryPath, sourceDirectoryName);
+
+    for (const targetFilePath of targetTreeEntries.files) {
+      targetFiles.add(targetFilePath);
+    }
+
+    for (const targetDirectoryPathRelative of targetTreeEntries.directories) {
+      targetDirectories.add(targetDirectoryPathRelative);
+    }
+  }
+
+  for (const entryPointFileName of entryPointFiles) {
+    const targetFilePath = path.join(resolvedTargetDirectoryPath, entryPointFileName);
+    if (!(await pathExists(targetFilePath))) {
+      continue;
+    }
+
+    targetFiles.add(toPosixRelativePath(entryPointFileName));
+  }
+
+  const optionalManagedEntries = await collectOptionalManagedEntries(resolvedTargetDirectoryPath, options);
+  for (const targetFilePath of optionalManagedEntries.files) {
+    targetFiles.add(targetFilePath);
+  }
+  for (const targetDirectoryPath of optionalManagedEntries.directories) {
+    targetDirectories.add(targetDirectoryPath);
+  }
+
+  return {
+    files: targetFiles,
+    directories: targetDirectories,
+  };
+}
+
+export async function analyzeManagedGovernanceSurface(
+  resolvedTargetDirectoryPath,
+  options = {}
+) {
+  const preservePathPrefixes = Array.isArray(options.preservePathPrefixes)
+    ? options.preservePathPrefixes
+    : ['.agent-context/state', '.gemini'];
+
+  const sourceManifest = await buildManagedSourceManifest(options);
+  const targetManifest = await collectManagedTargetManifest(resolvedTargetDirectoryPath, options);
+
+  const staleFiles = [];
+  const staleDirectories = [];
+  const preservedFiles = [];
+  const preservedDirectories = [];
+
+  const sortedTargetFiles = [...targetManifest.files].sort((leftPath, rightPath) => leftPath.localeCompare(rightPath));
+  const sortedTargetDirectories = [...targetManifest.directories].sort(
+    (leftPath, rightPath) => rightPath.length - leftPath.length || leftPath.localeCompare(rightPath)
+  );
+
+  for (const targetFilePath of sortedTargetFiles) {
+    if (sourceManifest.files.has(targetFilePath)) {
+      continue;
+    }
+
+    if (preservePathPrefixes.some((prefixPath) => isPathWithinPrefix(targetFilePath, prefixPath))) {
+      preservedFiles.push(targetFilePath);
+      continue;
+    }
+
+    staleFiles.push(targetFilePath);
+  }
+
+  for (const targetDirectoryPathRelative of sortedTargetDirectories) {
+    if (sourceManifest.directories.has(targetDirectoryPathRelative)) {
+      continue;
+    }
+
+    if (preservePathPrefixes.some((prefixPath) => isPathWithinPrefix(targetDirectoryPathRelative, prefixPath))) {
+      preservedDirectories.push(targetDirectoryPathRelative);
+      continue;
+    }
+
+    staleDirectories.push(targetDirectoryPathRelative);
+  }
+
+  return {
+    staleFiles,
+    staleDirectories,
+    preservedFiles,
+    preservedDirectories,
+    managedSourceFileCount: sourceManifest.files.size,
+    managedSourceDirectoryCount: sourceManifest.directories.size,
+    managedTargetFileCount: targetManifest.files.size,
+    managedTargetDirectoryCount: targetManifest.directories.size,
+  };
+}

package/lib/cli/utils/prompting.mjs

@@ -0,0 +1,44 @@
+export async function askChoice(promptMessage, options, userInterface) {
+  console.log(`\n${promptMessage}`);
+  options.forEach((choiceLabel, choiceIndex) => {
+    console.log(`  ${choiceIndex + 1}. ${choiceLabel}`);
+  });
+
+  while (true) {
+    const selectedRawInput = await userInterface.question('Choose a number (press Enter for 1): ');
+    const normalizedInput = selectedRawInput.trim();
+
+    if (!normalizedInput) {
+      return options[0];
+    }
+
+    const selectedIndex = Number.parseInt(normalizedInput, 10) - 1;
+
+    if (Number.isNaN(selectedIndex) || selectedIndex < 0 || selectedIndex >= options.length) {
+      console.log('Invalid choice. Please select a valid number.');
+      continue;
+    }
+
+    return options[selectedIndex];
+  }
+}
+
+export async function askYesNo(promptMessage, userInterface, defaultValue) {
+  const suffix = typeof defaultValue === 'boolean'
+    ? defaultValue ? ' (Y/n): ' : ' (y/N): '
+    : ' (y/n): ';
+
+  while (true) {
+    const answer = await userInterface.question(`\n${promptMessage}${suffix}`);
+    const normalizedAnswer = answer.trim().toLowerCase();
+
+    if (!normalizedAnswer && typeof defaultValue === 'boolean') {
+      return defaultValue;
+    }
+
+    if (normalizedAnswer === 'y' || normalizedAnswer === 'yes') return true;
+    if (normalizedAnswer === 'n' || normalizedAnswer === 'no') return false;
+
+    console.log("Please answer with 'y' or 'n'.");
+  }
+}