@ryuenn3123/agentic-senior-core 4.0.2 → 4.1.0

package/scripts/migrate-rule-format/roundtrip-validate.mjs

@@ -1,89 +0,0 @@
-// @ts-check
-
-/**
- * Roundtrip substance validator.
- *
- * After rendering the new format, we extract the substantial-word set from
- * both the original v3 file and the rendered v4 file, then compute set overlap.
- * Drop in overlap below the threshold means the migration almost certainly
- * lost real content; the helper surfaces the lost words so the human migrator
- * can decide whether the loss is intentional (renamed terms) or a bug.
- */
-
-const STOPWORD_SET = new Set([
-  'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'are', 'was',
-  'were', 'has', 'have', 'had', 'not', 'but', 'can', 'will', 'must', 'use',
-  'used', 'using', 'when', 'then', 'than', 'they', 'their', 'them', 'who',
-  'what', 'why', 'how', 'all', 'any', 'one', 'two', 'three', 'four', 'five',
-  'six', 'seven', 'eight', 'nine', 'ten', 'each', 'such', 'some', 'most',
-  'more', 'less', 'only', 'also', 'just', 'over', 'under', 'between', 'across',
-  'before', 'after', 'because', 'while', 'until', 'unless', 'within',
-  'without', 'inside', 'outside', 'about', 'around', 'against', 'through',
-  'throughout', 'during', 'including', 'include', 'includes', 'see', 'note',
-  'rule', 'rules', 'agent', 'agents', 'project', 'repo', 'code', 'file',
-  'files', 'item', 'items', 'list', 'lists', 'thing', 'things', 'value',
-  'values', 'should', 'shall', 'may', 'might', 'could', 'would', 'does',
-  'doing', 'done', 'make', 'makes', 'making', 'made', 'set', 'sets',
-]);
-
-function tokenize(text) {
-  const lowered = text.toLowerCase();
-  // Strip fenced code blocks first (multi-line ``` ... ``` spans).
-  const noFenced = lowered.replace(/```[\s\S]*?```/g, ' ');
-  // Strip inline code spans, but only within a single line so that an
-  // unmatched backtick on a code-heavy line cannot eat the rest of the file.
-  const noInline = noFenced.replace(/`[^`\n]+`/g, ' ');
-  const words = noInline.match(/[a-z][a-z0-9]+(?:-[a-z0-9]+)*/g) ?? [];
-  return words.filter((word) => word.length >= 4 && !STOPWORD_SET.has(word));
-}
-
-/**
- * @param {string} originalSourceText
- * @param {string} renderedSourceText
- * @param {{ minimumOverlapPercent?: number }} [options]
- * @returns {{
- *   passed: boolean,
- *   originalSubstantialWordCount: number,
- *   renderedSubstantialWordCount: number,
- *   overlapPercent: number,
- *   lostWords: string[],
- *   newWords: string[],
- *   minimumRequired: number,
- * }}
- */
-export function roundtripSubstanceCheck(originalSourceText, renderedSourceText, options = {}) {
-  const minimumOverlapPercent = options.minimumOverlapPercent ?? 95;
-  const originalWordCounts = new Map();
-  for (const word of tokenize(originalSourceText)) {
-    originalWordCounts.set(word, (originalWordCounts.get(word) || 0) + 1);
-  }
-  const renderedWordSet = new Set(tokenize(renderedSourceText));
-
-  const lostWords = [];
-  let preservedDistinctWordCount = 0;
-  for (const [word, count] of originalWordCounts.entries()) {
-    if (renderedWordSet.has(word)) {
-      preservedDistinctWordCount += 1;
-    } else {
-      lostWords.push(`${word} (x${count})`);
-    }
-  }
-
-  const originalDistinctCount = originalWordCounts.size;
-  const overlapPercent = originalDistinctCount > 0
-    ? (preservedDistinctWordCount / originalDistinctCount) * 100
-    : 100;
-
-  const originalWordSet = new Set(originalWordCounts.keys());
-  const newWords = [...renderedWordSet].filter((word) => !originalWordSet.has(word));
-
-  return {
-    passed: overlapPercent >= minimumOverlapPercent,
-    originalSubstantialWordCount: originalDistinctCount,
-    renderedSubstantialWordCount: renderedWordSet.size,
-    overlapPercent: Math.round(overlapPercent * 100) / 100,
-    lostWords: lostWords.sort().slice(0, 50),
-    newWords: newWords.sort().slice(0, 50),
-    minimumRequired: minimumOverlapPercent,
-  };
-}

package/scripts/migrate-rule-format.mjs

@@ -1,192 +0,0 @@
-#!/usr/bin/env node
-// @ts-check
-
-/**
- * scripts/migrate-rule-format.mjs
- *
- * Phase 1 Task 1.2 migration helper. Converts a legacy v3 rule file into the
- * canonical v4 format defined in docs/architecture/format-spec.md. Output is written
- * to a `.candidate.md` sibling so the human migrator can review the diff
- * before replacing the original.
- *
- * Usage:
- *   node scripts/migrate-rule-format.mjs <path-to-rule-file>
- *   node scripts/migrate-rule-format.mjs <path> --json
- *   node scripts/migrate-rule-format.mjs <path> --apply
- *
- * Flags:
- *   --json    Print the structured report to stdout (JSON only, no human prose).
- *   --apply   Overwrite the source file with the rendered v4 content. Default
- *             behavior writes a .candidate.md file and leaves the source alone.
- *
- * The helper does not commit, does not stage, and does not call any network.
- *
- * Exit codes:
- *   0 — rendered cleanly + roundtrip overlap >= 95%
- *   1 — roundtrip overlap below threshold OR parser warnings present
- *   2 — input path missing or filename not in the locked prefix table
- */
-
-import { readFileSync, writeFileSync } from 'node:fs';
-import { basename, dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-import { countTokens } from '../benchmarks/token-usage/lib/token-counter.mjs';
-import { getPrefixEntry } from './migrate-rule-format/id-prefix-table.mjs';
-import { parseLegacyRuleFile } from './migrate-rule-format/parse-legacy.mjs';
-import { renderNewFormat } from './migrate-rule-format/render-new.mjs';
-import { roundtripSubstanceCheck } from './migrate-rule-format/roundtrip-validate.mjs';
-
-const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
-const REPOSITORY_ROOT = resolve(dirname(SCRIPT_FILE_PATH), '..');
-
-/**
- * @param {string} ruleFileAbsolutePath
- * @returns {Promise<{
- *   sourcePath: string,
- *   filename: string,
- *   prefix: string,
- *   sectionAssignments: Array<{ sectionTitle: string, sectionId: string, itemCount: number }>,
- *   warnings: string[],
- *   roundtrip: ReturnType<typeof roundtripSubstanceCheck>,
- *   tokenSavings: { original: number, rendered: number, deltaPercent: number },
- *   candidatePath: string,
- *   rendered: string,
- * }>}
- */
-export async function migrateOneRuleFile(ruleFileAbsolutePath) {
-  const filename = basename(ruleFileAbsolutePath);
-  const prefixEntry = getPrefixEntry(filename);
-  const originalSource = readFileSync(ruleFileAbsolutePath, 'utf8');
-  const parsed = parseLegacyRuleFile(originalSource);
-  const { rendered, sectionAssignments, warnings } = renderNewFormat(prefixEntry, parsed);
-  const roundtrip = roundtripSubstanceCheck(originalSource, rendered);
-
-  const originalTokenCount = await countTokens(originalSource, 'openai', 'gpt-4o-2024-08-06');
-  const renderedTokenCount = await countTokens(rendered, 'openai', 'gpt-4o-2024-08-06');
-  const tokenSavings = {
-    original: originalTokenCount.token_count,
-    rendered: renderedTokenCount.token_count,
-    deltaPercent: Math.round(
-      ((renderedTokenCount.token_count - originalTokenCount.token_count) / originalTokenCount.token_count) * 10000,
-    ) / 100,
-  };
-
-  const candidatePath = ruleFileAbsolutePath.replace(/\.md$/, '.candidate.md');
-
-  return {
-    sourcePath: ruleFileAbsolutePath,
-    filename,
-    prefix: prefixEntry.prefix,
-    sectionAssignments,
-    warnings,
-    roundtrip,
-    tokenSavings,
-    candidatePath,
-    rendered,
-  };
-}
-
-function formatHumanReport(report) {
-  const lines = [];
-  lines.push('=================================================');
-  lines.push(`  migrate-rule-format: ${report.filename}`);
-  lines.push('=================================================');
-  lines.push(`  Prefix         : ${report.prefix}`);
-  lines.push(`  Section count  : ${report.sectionAssignments.length}`);
-  lines.push(`  Token (orig)   : ${report.tokenSavings.original}`);
-  lines.push(`  Token (new)    : ${report.tokenSavings.rendered}`);
-  const sign = report.tokenSavings.deltaPercent <= 0 ? '' : '+';
-  lines.push(`  Token delta    : ${sign}${report.tokenSavings.deltaPercent}%`);
-  lines.push(`  Roundtrip      : ${report.roundtrip.passed ? 'PASS' : 'FAIL'} (${report.roundtrip.overlapPercent}% overlap, min ${report.roundtrip.minimumRequired}%)`);
-  lines.push('');
-
-  lines.push('  Sections assigned:');
-  for (const assignment of report.sectionAssignments) {
-    lines.push(`    ${assignment.sectionId.padEnd(12)} ${assignment.itemCount} items   ${assignment.sectionTitle}`);
-  }
-  lines.push('');
-
-  if (report.warnings.length > 0) {
-    lines.push('  Warnings:');
-    for (const warning of report.warnings) {
-      lines.push(`    ! ${warning}`);
-    }
-    lines.push('');
-  }
-
-  if (report.roundtrip.lostWords.length > 0) {
-    lines.push(`  Substantial words present in original, missing in rendered (${report.roundtrip.lostWords.length} of distinct):`);
-    for (const word of report.roundtrip.lostWords.slice(0, 30)) {
-      lines.push(`    - ${word}`);
-    }
-    if (report.roundtrip.lostWords.length > 30) {
-      lines.push(`    ... ${report.roundtrip.lostWords.length - 30} more (see JSON report)`);
-    }
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-async function runCli() {
-  const argv = process.argv.slice(2);
-  if (argv.length === 0) {
-    console.error('usage: node scripts/migrate-rule-format.mjs <path-to-rule-file> [--json] [--apply]');
-    process.exit(2);
-  }
-
-  const inputPath = argv[0];
-  const jsonMode = argv.includes('--json');
-  const applyMode = argv.includes('--apply');
-  const ruleFileAbsolutePath = resolve(REPOSITORY_ROOT, inputPath);
-
-  let report;
-  try {
-    report = await migrateOneRuleFile(ruleFileAbsolutePath);
-  } catch (migrationError) {
-    if (jsonMode) {
-      process.stdout.write(`${JSON.stringify({ passed: false, error: migrationError.message }, null, 2)}\n`);
-    } else {
-      console.error(`migrate-rule-format failed: ${migrationError.message}`);
-    }
-    process.exit(2);
-  }
-
-  if (applyMode) {
-    writeFileSync(ruleFileAbsolutePath, report.rendered, 'utf8');
-  } else {
-    writeFileSync(report.candidatePath, report.rendered, 'utf8');
-  }
-
-  const exitCode = report.roundtrip.passed && report.warnings.length === 0 ? 0 : 1;
-
-  if (jsonMode) {
-    process.stdout.write(`${JSON.stringify({
-      passed: report.roundtrip.passed,
-      filename: report.filename,
-      prefix: report.prefix,
-      sectionCount: report.sectionAssignments.length,
-      sectionAssignments: report.sectionAssignments,
-      warnings: report.warnings,
-      roundtrip: report.roundtrip,
-      tokenSavings: report.tokenSavings,
-      candidatePath: applyMode ? report.sourcePath : report.candidatePath,
-      mode: applyMode ? 'apply' : 'candidate',
-    }, null, 2)}\n`);
-    process.exit(exitCode);
-  }
-
-  console.log(formatHumanReport(report));
-  if (applyMode) {
-    console.log(`  APPLIED in place: ${report.sourcePath}`);
-  } else {
-    console.log(`  Candidate written: ${report.candidatePath}`);
-    console.log('  Review the diff, then re-run with --apply when satisfied.');
-  }
-  process.exit(exitCode);
-}
-
-if (import.meta.url === `file://${process.argv[1].replace(/\\/g, '/')}` || process.argv[1].endsWith('migrate-rule-format.mjs')) {
-  runCli();
-}

package/scripts/v3-purge-audit.mjs

@@ -1,236 +0,0 @@
-#!/usr/bin/env node
-
-import { readdir, readFile, stat, writeFile, mkdir } from 'node:fs/promises';
-import { dirname, extname, join, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
-const ROOT_DIR = resolve(dirname(SCRIPT_FILE_PATH), '..');
-const STATE_OUTPUT_PATH = join(ROOT_DIR, '.agent-context', 'state', 'v3-purge-audit.json');
-
-const STATIC_DIRECTORIES = [
-  '.agent-context/stacks',
-  '.agent-context/blueprints',
-  '.agent-context/profiles',
-];
-
-const REFERENCE_TOKENS = [
-  '.agent-context/stacks/',
-  '.agent-context/blueprints/',
-  '.agent-context/profiles/',
-];
-
-const NON_BLOCKING_REFERENCE_FILE_PATHS = new Set([
-  '.agent-context/state/v3-purge-audit.json',
-  'scripts/v3-purge-audit.mjs',
-]);
-
-const RUNTIME_BLOCKING_PATH_PATTERNS = [
-  /^AGENTS\.md$/,
-  /^CLAUDE\.md$/,
-  /^GEMINI\.md$/,
-  /^\.instructions\.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$/,
-  /^mcp\.json$/,
-  /^lib\//,
-  /^scripts\//,
-  /^tests\//,
-  /^\.agent-context\/prompts\//,
-  /^\.agents\/workflows\//,
-  /^\.agent-context\/review-checklists\//,
-];
-
-const SKIP_DIRECTORY_NAMES = new Set([
-  '.git',
-  'node_modules',
-  '.benchmarks',
-  '.agentic-backup',
-]);
-
-const TEXT_EXTENSIONS = new Set([
-  '.md',
-  '.mjs',
-  '.js',
-  '.json',
-  '.yml',
-  '.yaml',
-  '.txt',
-  '.ts',
-  '.tsx',
-  '.cjs',
-  '.sh',
-  '.ps1',
-]);
-
-function isTextCandidate(fileName) {
-  const extension = extname(fileName).toLowerCase();
-  return TEXT_EXTENSIONS.has(extension);
-}
-
-async function pathStatOrNull(targetPath) {
-  try {
-    return await stat(targetPath);
-  } catch {
-    return null;
-  }
-}
-
-async function listAllFiles(directoryPath) {
-  const discoveredFilePaths = [];
-
-  async function walk(currentPath) {
-    const directoryEntries = await readdir(currentPath, { withFileTypes: true });
-
-    for (const entry of directoryEntries) {
-      if (entry.isDirectory() && SKIP_DIRECTORY_NAMES.has(entry.name)) {
-        continue;
-      }
-
-      const entryPath = join(currentPath, entry.name);
-
-      if (entry.isDirectory()) {
-        await walk(entryPath);
-        continue;
-      }
-
-      if (!isTextCandidate(entry.name)) {
-        continue;
-      }
-
-      discoveredFilePaths.push(entryPath);
-    }
-  }
-
-  await walk(directoryPath);
-  return discoveredFilePaths;
-}
-
-async function collectDirectoryEntryCount(absoluteDirectoryPath) {
-  const directoryStats = await pathStatOrNull(absoluteDirectoryPath);
-  if (!directoryStats || !directoryStats.isDirectory()) {
-    return 0;
-  }
-
-  let fileCount = 0;
-
-  async function walk(currentPath) {
-    const directoryEntries = await readdir(currentPath, { withFileTypes: true });
-
-    for (const entry of directoryEntries) {
-      const entryPath = join(currentPath, entry.name);
-      if (entry.isDirectory()) {
-        await walk(entryPath);
-        continue;
-      }
-
-      fileCount += 1;
-    }
-  }
-
-  await walk(absoluteDirectoryPath);
-  return fileCount;
-}
-
-async function runAudit() {
-  const allTextFilePaths = await listAllFiles(ROOT_DIR);
-  const matchesByFile = [];
-  const tokenMatchCounts = Object.fromEntries(REFERENCE_TOKENS.map((token) => [token, 0]));
-  let runtimeBlockingFileCount = 0;
-  let documentationReferenceFileCount = 0;
-
-  function isRuntimeBlockingFile(relativeFilePath) {
-    return RUNTIME_BLOCKING_PATH_PATTERNS.some((pattern) => pattern.test(relativeFilePath));
-  }
-
-  for (const absoluteFilePath of allTextFilePaths) {
-    const relativeFilePath = relative(ROOT_DIR, absoluteFilePath).replace(/\\/g, '/');
-
-    if (NON_BLOCKING_REFERENCE_FILE_PATHS.has(relativeFilePath)) {
-      continue;
-    }
-
-    const fileContent = await readFile(absoluteFilePath, 'utf8');
-
-    const matchedTokens = REFERENCE_TOKENS.filter((token) => fileContent.includes(token));
-    if (matchedTokens.length === 0) {
-      continue;
-    }
-
-    for (const matchedToken of matchedTokens) {
-      tokenMatchCounts[matchedToken] += 1;
-    }
-
-    const classification = isRuntimeBlockingFile(relativeFilePath)
-      ? 'runtime-blocking'
-      : 'documentation-reference';
-
-    if (classification === 'runtime-blocking') {
-      runtimeBlockingFileCount += 1;
-    } else {
-      documentationReferenceFileCount += 1;
-    }
-
-    matchesByFile.push({
-      filePath: relativeFilePath,
-      matchedTokens,
-      classification,
-    });
-  }
-
-  const directoryAudit = [];
-  for (const relativeDirectoryPath of STATIC_DIRECTORIES) {
-    const absoluteDirectoryPath = join(ROOT_DIR, relativeDirectoryPath);
-    const directoryStat = await pathStatOrNull(absoluteDirectoryPath);
-
-    directoryAudit.push({
-      path: relativeDirectoryPath,
-      exists: Boolean(directoryStat && directoryStat.isDirectory()),
-      fileCount: await collectDirectoryEntryCount(absoluteDirectoryPath),
-    });
-  }
-
-  const report = {
-    generatedAt: new Date().toISOString(),
-    auditName: 'v3-purge-audit',
-    source: 'working-tree',
-    deletionCandidates: directoryAudit,
-    referenceSummary: {
-      scannedTextFileCount: allTextFilePaths.length,
-      blockingFileCount: matchesByFile.length,
-      runtimeBlockingFileCount,
-      documentationReferenceFileCount,
-      tokenMatchCounts,
-    },
-    blockingReferences: matchesByFile,
-    readyForMassDeletion: runtimeBlockingFileCount === 0,
-    nextActions: runtimeBlockingFileCount === 0
-      ? [
-        documentationReferenceFileCount === 0
-          ? 'No runtime blockers detected. Mass deletion can proceed after explicit user confirmation.'
-          : 'No runtime blockers detected. Optional docs cleanup can be done after explicit user confirmation for mass deletion.',
-      ]
-      : [
-        'Refactor blocking references before removing static directories.',
-        'Rerun `npm run audit:v3-purge` and require readyForMassDeletion=true before deletion.',
-      ],
-  };
-
-  await mkdir(dirname(STATE_OUTPUT_PATH), { recursive: true });
-  await writeFile(STATE_OUTPUT_PATH, JSON.stringify(report, null, 2) + '\n', 'utf8');
-
-  console.log(JSON.stringify(report, null, 2));
-
-  if (process.argv.includes('--strict') && !report.readyForMassDeletion) {
-    process.exitCode = 1;
-  }
-}
-
-runAudit().catch((error) => {
-  console.error('[FATAL] v3-purge-audit failed');
-  console.error(error instanceof Error ? error.stack : String(error));
-  process.exitCode = 1;
-});