@ryuenn3123/agentic-senior-core 3.0.37 → 3.0.38

package/lib/cli/utils.mjs

@@ -14,6 +14,29 @@ import {
   entryPointFiles,
   directoryCopies,
 } from './constants.mjs';
+import {
+  pathExists,
+  ensureDirectory,
+  syncFile,
+} from './utils/filesystem.mjs';
+import {
+  collectRelativeTreeEntries,
+  analyzeManagedGovernanceSurface,
+} from './utils/managed-surface.mjs';
+export {
+  pathExists,
+  ensureDirectory,
+  copyDirectory,
+  isAgenticManagedContent,
+  syncFile,
+} from './utils/filesystem.mjs';
+export {
+  analyzeManagedGovernanceSurface,
+} from './utils/managed-surface.mjs';
+export {
+  askChoice,
+  askYesNo,
+} from './utils/prompting.mjs';
 
 export function printUsage() {
   const presetNames = Object.keys(INIT_PRESETS).join(', ');
@@ -65,67 +88,6 @@ export function printUsage() {
   console.log('  --show       Print current token optimization state as JSON');
 }
 
-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);
-  }
-}
-
-/**
- * Synchronizes a single file between source and target, returning the operation status.
- */
-export async function syncFile(sourcePath, targetPath) {
-  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' };
-  }
-
-  await fs.copyFile(sourcePath, targetPath);
-  return { status: 'updated' };
-}
-
 /**
  * Intelligent MCP configuration synchronization.
  * Merges the agentic-senior-core server into existing config or creates new.
@@ -163,233 +125,6 @@ async function syncMcpConfig(mcpJsonPath, templateConfig) {
   }
 }
 
-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',
-]);
-
-function isLocalOnlyGovernanceFile(relativePath) {
-  return localOnlyGovernanceFiles.has(toPosixRelativePath(relativePath));
-}
-
-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'];
-
-  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,
-  };
-}
-
 export async function copyGovernanceAssetsToTarget(
   resolvedTargetDirectoryPath,
   options = {}
@@ -406,6 +141,7 @@ export async function copyGovernanceAssetsToTarget(
   const createdFiles = [];
   const updatedFiles = [];
   const unchangedFiles = [];
+  const preservedFiles = [];
 
   for (const sourceDirectoryName of directoryCopies) {
     const sourceDirectoryPath = path.join(REPO_ROOT, sourceDirectoryName);
@@ -417,11 +153,14 @@ export async function copyGovernanceAssetsToTarget(
     for (const relativeFilePath of sourceTree.files) {
       const sourcePath = path.join(REPO_ROOT, ...relativeFilePath.split('/'));
       const targetPath = path.join(resolvedTargetDirectoryPath, ...relativeFilePath.split('/'));
-      const syncResult = await syncFile(sourcePath, targetPath);
+      const syncResult = await syncFile(sourcePath, targetPath, {
+        preserveUserOwned: sourceDirectoryName === '.gemini',
+      });
       
       if (syncResult.status === 'created') createdFiles.push(relativeFilePath);
       else if (syncResult.status === 'updated') updatedFiles.push(relativeFilePath);
       else if (syncResult.status === 'unchanged') unchangedFiles.push(relativeFilePath);
+      else if (syncResult.status === 'preserved') preservedFiles.push(relativeFilePath);
     }
   }
 
@@ -437,10 +176,13 @@ export async function copyGovernanceAssetsToTarget(
       continue;
     }
 
-    const syncResult = await syncFile(sourceFilePath, targetFilePath);
+    const syncResult = await syncFile(sourceFilePath, targetFilePath, {
+      preserveUserOwned: true,
+    });
     if (syncResult.status === 'created') createdFiles.push(entryPointFileName);
     else if (syncResult.status === 'updated') updatedFiles.push(entryPointFileName);
     else if (syncResult.status === 'unchanged') unchangedFiles.push(entryPointFileName);
+    else if (syncResult.status === 'preserved') preservedFiles.push(entryPointFileName);
   }
 
   if (shouldPruneManagedSurface && managedSurfacePlan) {
@@ -595,55 +337,11 @@ export async function copyGovernanceAssetsToTarget(
     createdFiles,
     updatedFiles,
     unchangedFiles,
+    preservedFiles,
     managedSurfacePlan,
   };
 }
 
-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'.");
-  }
-}
-
 export function toTitleCase(fileName) {
   return fileName
     .replace(/\.md$/i, '')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryuenn3123/agentic-senior-core",
-  "version": "3.0.37",
+  "version": "3.0.38",
   "type": "module",
   "description": "Force your AI Agent to code like a Staff Engineer, not a Junior.",
   "bin": {
@@ -11,13 +11,31 @@
     "lib/",
     "scripts/",
     ".instructions.md",
-    ".agent-context/",
+    ".agent-context/policies/",
+    ".agent-context/prompts/",
+    ".agent-context/review-checklists/",
+    ".agent-context/rules/",
+    ".agent-context/state/README.md",
+    ".agent-context/state/architecture-map.md",
+    ".agent-context/state/dependency-map.md",
+    ".agent-context/state/benchmark-comparison-schema.json",
+    ".agent-context/state/benchmark-reproducibility.json",
+    ".agent-context/state/benchmark-thresholds.json",
+    ".agent-context/state/benchmark-watchlist.json",
+    ".agent-context/state/benchmark-writer-judge-config.json",
+    ".agent-context/state/memory-adapter-contract.json",
+    ".agent-context/state/memory-schema-v1.json",
+    ".agent-context/state/stack-research-snapshot.json",
     ".agents/",
+    ".cursor/",
     ".github/",
     ".gemini/",
+    ".windsurf/",
     ".cursorrules",
     ".windsurfrules",
     "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
     ".agent-override.md",
     "mcp.json",
     "README.md",
@@ -65,6 +83,7 @@
     "report:quality-trend": "node ./scripts/quality-trend-report.mjs",
     "report:docs-quality-drift": "node ./scripts/docs-quality-drift-report.mjs",
     "report:governance-weekly": "node ./scripts/governance-weekly-report.mjs",
+    "clean:local": "node ./scripts/clean-local-artifacts.mjs",
     "validate": "node ./scripts/validate.mjs",
     "test": "node --test ./tests/cli-smoke.test.mjs ./tests/mcp-server.test.mjs ./tests/llm-judge.test.mjs ./tests/ui-rubric-calibration.test.mjs ./tests/operations.test.mjs"
   }

package/scripts/clean-local-artifacts.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { rm, stat } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
+const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
+
+const LOCAL_ARTIFACT_PATHS = [
+  'test_output.txt',
+  'validate_output.txt',
+  'release-gate-report.json',
+  '.benchmarks',
+  '.agentic-backup',
+  '.agent-context/state/active-memory.json',
+  '.agent-context/state/v3-purge-audit.json',
+  '.agent-context/state/llm-judge-report.json',
+  '.agent-context/state/benchmark-analysis.json',
+  '.agent-context/state/benchmark-evidence-bundle.json',
+  '.agent-context/state/benchmark-history.json',
+  '.agent-context/state/benchmark-trend-report.csv',
+  '.agent-context/state/benchmark-trend-report.json',
+  '.agent-context/state/benchmark-writer-judge-matrix.json',
+  '.agent-context/state/docs-quality-drift-report.json',
+  '.agent-context/state/memory-continuity-benchmark.json',
+  '.agent-context/state/quality-trend-report.json',
+  '.agent-context/state/token-optimization-benchmark.json',
+  '.agent-context/state/weekly-governance-report.json',
+];
+
+function resolveLocalArtifactPath(relativePath) {
+  const resolvedPath = resolve(REPOSITORY_ROOT, relativePath);
+  const repositoryRelativePath = relative(REPOSITORY_ROOT, resolvedPath);
+
+  if (
+    repositoryRelativePath.startsWith('..')
+    || repositoryRelativePath === ''
+    || resolve(repositoryRelativePath) === repositoryRelativePath
+  ) {
+    throw new Error(`Refusing to clean path outside repository root: ${relativePath}`);
+  }
+
+  return resolvedPath;
+}
+
+async function pathExists(targetPath) {
+  try {
+    await stat(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+let removedCount = 0;
+let skippedCount = 0;
+
+for (const relativePath of LOCAL_ARTIFACT_PATHS) {
+  const targetPath = resolveLocalArtifactPath(relativePath);
+
+  if (!(await pathExists(targetPath))) {
+    skippedCount += 1;
+    continue;
+  }
+
+  await rm(targetPath, {
+    force: true,
+    recursive: true,
+  });
+
+  removedCount += 1;
+  console.log(`removed ${relativePath}`);
+}
+
+console.log(`local artifact cleanup complete: removed=${removedCount}, skipped=${skippedCount}`);

package/scripts/docs-quality-drift-report.mjs

@@ -26,8 +26,13 @@ const MONITORED_STATIC_FILE_PATHS = [
   'CHANGELOG.md',
   '.instructions.md',
   'AGENTS.md',
+  'CLAUDE.md',
+  'GEMINI.md',
   '.github/copilot-instructions.md',
+  '.github/instructions/agentic-senior-core.instructions.md',
   '.gemini/instructions.md',
+  '.cursor/rules/agentic-senior-core.mdc',
+  '.windsurf/rules/agentic-senior-core.md',
   'docs/deep_analysis_and_roadmap_backlog.md',
 ];
 

package/scripts/frontend-usability-audit.mjs

@@ -54,25 +54,29 @@ const REQUIRED_ARCHITECTURE_CHECKLIST_SNIPPETS = [
 
 const REQUIRED_FRONTEND_RULE_SNIPPETS = [
   'Frontend Design and Interaction Boundaries',
-  'UI work must load the smallest relevant surface, not the entire engineering handbook.',
-  '## Auto Activation',
-  'UI scope triggers:',
-  'Do not use this file to teach generic frontend basics the model already knows.',
-  '## Source Hygiene and Source Boundaries',
-  'This rule guides the LLM; it must not choose the final style',
-  'Design continuity is opt-in.',
-  'Repo evidence outranks memory residue every time.',
-  '## Accessibility Split',
-  'Treat WCAG 2.2 AA as the hard compliance floor.',
-  'Treat APCA as advisory perceptual tuning only.',
-  '## Anti-Generic UI Boundaries',
-  'Do not default to interchangeable dashboard chrome',
-  'Do not let repeated surfaces share the same visual treatment by habit.',
-  'Do not use default framework button and input treatment as the final UI language.',
-  '## Responsive Mutation Requirements',
-  'Responsive quality is not allowed to be scale-only.',
-  '## Surface and Morphology Requirements',
-  'Define the primary user task or reading path from current evidence',
+  'Load this rule for UI-facing work. Keep the loaded surface small.',
+  '## Activation',
+  '## Authority',
+  'Treat `.agent-context/` as design governance authority.',
+  'Treat `README.md` as overview/install/user 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.',
+  '## Required Design Contract',
+  '## Anti-Generic UI Gate',
+  'Do not ship interchangeable dashboard chrome',
+  'Do not let repeated surfaces share one visual treatment by habit',
+  'Use the rename test:',
+  'decorative geometry are invalid as wallpaper',
+  '## Dynamic Anchor Gate',
+  '## Motion, Palette, and 3D',
+  'Treat motion, 3D, WebGL, canvas, scroll choreography, and animation libraries as first-class options.',
+  'Prefer visually exploratory, product-derived palettes while preserving WCAG contrast and status clarity.',
+  '## Responsive Mutation',
+  'Responsive quality is not scale-only.',
+  '## Accessibility',
+  'WCAG 2.2 AA is the hard floor.',
+  'APCA is advisory perceptual tuning only.',
   '## Implementation Boundaries',
   'Do not hardcode Zustand, React Query, smart/dumb component doctrine',
 ];