@ryuenn3123/agentic-senior-core 3.0.50 → 4.0.1

package/scripts/migrate-rule-format.mjs

@@ -0,0 +1,192 @@
+#!/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/release-gate/constants.mjs

@@ -7,7 +7,7 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
 export const REPOSITORY_ROOT = resolve(__dirname, '..', '..');
-export const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
+export const VERSION_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 export const FRONTEND_AUDIT_SCRIPT_PATH = 'scripts/frontend-usability-audit.mjs';
 export const UI_DESIGN_JUDGE_SCRIPT_PATH = 'scripts/ui-design-judge.mjs';
 export const DOCUMENTATION_BOUNDARY_AUDIT_SCRIPT_PATH = 'scripts/documentation-boundary-audit.mjs';

package/scripts/release-gate/static-checks.mjs

@@ -47,7 +47,7 @@ export function runStaticReleaseChecks(results, diagnostics) {
   if (!releaseVersion || !VERSION_PATTERN.test(releaseVersion)) {
     pushResult(results, false, 'version-semver', `Invalid package version: ${String(releaseVersion)}`);
   } else {
-    pushResult(results, true, 'version-semver', `Version ${releaseVersion} matches x.y.z format`);
+    pushResult(results, true, 'version-semver', `Version ${releaseVersion} matches SemVer format`);
   }
 
   const changelogContent = readText(changelogPath);

package/scripts/rules-guardian-audit.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+// @file-size-exception: Pre-existing audit script (sequential rules-guardian checks); planned for split in Phase 1.
 /**
  * rules-guardian-audit.mjs
  *
@@ -36,7 +37,7 @@ const SUPPORTED_WORKFLOWS = new Set([
 const CORE_PATTERN_SIGNALS = [
   {
     pattern: 'layer-separation',
-    snippet: '## Layer Boundaries (Mandatory)',
+    snippet: '## ARCH-009: Layer Boundaries (Mandatory)',
   },
   {
     pattern: 'agent-decides-topology',
@@ -53,7 +54,7 @@ const CORE_PATTERN_SIGNALS = [
 ];
 
 const REQUIRED_ARCHITECTURE_RULE_SNIPPETS = [
-  '## Rules as Guardian (Cross-Session Consistency)',
+  '## ARCH-005: Rules as Guardian (Cross-Session Consistency)',
   'Session handoff must include active architecture contract summary.',
   'Detect drift before changing runtime choices, topology, public contracts, or core patterns.',
   'Direction changes require explicit user confirmation before applying changes.',
@@ -100,6 +101,7 @@ function runGitFileQuery(commandArguments) {
       cwd: REPOSITORY_ROOT,
       encoding: 'utf8',
       maxBuffer: 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
     });
 
     return parseGitFileList(rawOutput);
@@ -114,6 +116,7 @@ function runGitRawQuery(commandArguments) {
       cwd: REPOSITORY_ROOT,
       encoding: 'utf8',
       maxBuffer: 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
     });
   } catch {
     return '';

package/scripts/single-source-lazy-loading-audit.mjs

@@ -55,7 +55,7 @@ const STACK_CATALOG_FILE_NAMES = [
 const MAX_EAGER_STACK_MENTIONS = 4;
 
 const REQUIRED_ARCHITECTURE_RULE_SNIPPETS = [
-  '## Single Source of Truth and Lazy Rule Loading',
+  '## ARCH-007: Single Source of Truth and Lazy Rule Loading',
   'Canonical rule source is AGENTS.md.',
   'Load global domain rules lazily based on touched scope.',
   'Do not create or load stack-specific governance adapters as the baseline.',
@@ -121,6 +121,7 @@ function runGitFileQuery(commandArguments) {
       cwd: REPOSITORY_ROOT,
       encoding: 'utf8',
       maxBuffer: 1024 * 1024,
+      stdio: ['ignore', 'pipe', 'ignore'],
     });
 
     return parseGitFileList(rawOutput);

package/scripts/ui-design-judge/git-input.mjs

@@ -62,6 +62,7 @@ export function collectPullRequestDiff() {
       cwd: REPOSITORY_ROOT,
       encoding: /** @type {'utf-8'} */ ('utf-8'),
       maxBuffer: 1024 * 1024 * 8,
+      stdio: ['ignore', 'pipe', 'ignore'],
     });
   } catch {
     try {
@@ -70,6 +71,7 @@ export function collectPullRequestDiff() {
         cwd: REPOSITORY_ROOT,
         encoding: /** @type {'utf-8'} */ ('utf-8'),
         maxBuffer: 1024 * 1024 * 8,
+        stdio: ['ignore', 'pipe', 'ignore'],
       });
     } catch {
       return '';
@@ -103,6 +105,7 @@ export function collectChangedFiles() {
       cwd: REPOSITORY_ROOT,
       encoding: /** @type {'utf-8'} */ ('utf-8'),
       maxBuffer: 1024 * 1024 * 2,
+      stdio: ['ignore', 'pipe', 'ignore'],
     });
     return output.split(/\r?\n/u).map((filePath) => filePath.trim()).filter(Boolean);
   } catch {

package/scripts/validate/config.mjs

@@ -1,3 +1,4 @@
+// @file-size-exception: Pure config table aggregation (snippet expectation lists); deferred to Phase 1 split.
 export const ALLOWED_SEVERITIES = new Set(['critical', 'high', 'medium', 'low']);
 export const THIN_ADAPTER_PATHS = [
   'CLAUDE.md',
@@ -22,7 +23,7 @@ export const REQUIRED_HUMAN_WRITING_SNIPPETS = [
   {
     path: '.agent-context/rules/api-docs.md',
     snippets: [
-      '## Human Writing Standard (Mandatory)',
+      '## API-006: Human Writing Standard (Mandatory)',
       'This applies to documentation, release notes, onboarding text, review summaries, and agent-facing explanations.',
       'Style baseline findings are advisory by default and must not block endpoint-change commits that already include accurate docs/spec updates.',
       'Write formal project docs in English by default',
@@ -195,7 +196,7 @@ export const REQUIRED_UNIVERSAL_SOP_SNIPPETS = [
   {
     path: '.agent-context/rules/architecture.md',
     snippets: [
-      '## Universal SOP Baseline (Mandatory)',
+      '## ARCH-003: Universal SOP Baseline (Mandatory)',
       'Root `README.md` must exist for every fresh or existing project',
       '`docs/doc-index.md` must exist whenever `docs/` exists',
       'Security and testing are non-negotiable baseline requirements.',
@@ -300,6 +301,12 @@ export const REQUIRED_UI_DESIGN_AUTOMATION_SNIPPETS = [
       'Motion/Palette Decision',
       'product categories are heuristics',
       'perform live web research',
+      'research-design.md',
+      'researchDossier.metadata',
+      'researchVerifiedAt',
+      'freshnessWindowDays',
+      'Anti-repeat ledger',
+      'user-explicit redesign',
     ],
   },
   {
@@ -351,6 +358,24 @@ export const REQUIRED_UI_DESIGN_AUTOMATION_SNIPPETS = [
       'A new dependency, package count, or vague performance concern is not a blocker by itself.',
       'default component-kit styling without product rationale',
       'genericity findings that cannot name the exact drift signal',
+      'research-design.md',
+      'Section 3-5 gates from `research-design.md`',
+    ],
+  },
+  {
+    path: '.agent-context/prompts/research-design.md',
+    snippets: [
+      '# Research-Design Brief',
+      '## Section 3 — Category Code Identification',
+      '## Section 4 — Morphological Exploration',
+      '## Section 5 — Anchor Candidates',
+      'specificity self-test',
+      'uncomfortable combination',
+      'STRONG PASS',
+      'DISCARD',
+      'Anti-Repeat Ledger Gate',
+      'previousAnchors',
+      'previousMotionSignatures',
     ],
   },
   {

package/scripts/validate/coverage-checks.mjs

@@ -397,7 +397,7 @@ export async function validateInstructionAdapters(context) {
   const instructionFootprintLimits = [
     { path: 'AGENTS.md', maxLines: 180 },
     { path: '.agent-context/prompts/bootstrap-design.md', maxLines: 180 },
-    { path: '.agent-context/rules/frontend-architecture.md', maxLines: 110 },
+    { path: '.agent-context/rules/frontend-architecture.md', maxLines: 140 },
   ];
 
   for (const requiredBootstrapReceiptSnippet of requiredBootstrapReceiptSnippets) {

package/scripts/validate.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+// @file-size-exception: Pre-existing 600 LOC main validator orchestrator; planned for split in Phase 1 governance refactor.
 /**
  * validate.mjs — Repository Integrity Validator
  *
@@ -17,6 +18,12 @@ import { readdir, readFile, stat } from 'node:fs/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { ALLOWED_SEVERITIES } from './validate/config.mjs';
+import { runCacheLayerContractAudit } from './audit-cache-layer-contract.mjs';
+import { runCachingScopeHygieneAudit } from './audit-caching-scope-hygiene.mjs';
+import { runAuditFileSize } from './audit-file-size.mjs';
+import { runReflectionCitationAudit } from './audit-reflection-citations.mjs';
+import { runReleaseBundleAudit } from './audit-release-bundle.mjs';
+import { runRuleIdUniquenessAudit } from './audit-rule-id-uniqueness.mjs';
 import {
   validateDependencyFreshnessAutomationCoverage,
   validateDetectionTransparencyCoverage,
@@ -145,11 +152,13 @@ async function validateRequiredFiles() {
     'scripts/rules-guardian-audit.mjs',
     'scripts/explain-on-demand-audit.mjs',
     'scripts/single-source-lazy-loading-audit.mjs',
+    'scripts/audit-cache-layer-contract.mjs',
     'scripts/sync-thin-adapters.mjs',
     'scripts/v3-purge-audit.mjs',
     'scripts/release-gate.mjs',
     'scripts/generate-sbom.mjs',
     '.agent-context/policies/llm-judge-threshold.json',
+    '.agent-context/prompts/research-design.md',
     'mcp.json',
     'AGENTS.md',
     'CLAUDE.md',
@@ -358,7 +367,7 @@ async function validatePackageMetadata() {
   console.log('\nChecking package metadata...');
 
   const packageJson = JSON.parse(await readTextFile(PACKAGE_JSON_PATH));
-  const versionPattern = /^\d+\.\d+\.\d+$/;
+  const versionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 
   if (typeof packageJson.version !== 'string' || !versionPattern.test(packageJson.version)) {
     fail('package.json version must be a semantic version string');
@@ -495,6 +504,84 @@ async function validateDocumentationFlow() {
   }
 }
 
+async function validateFileSizeAudit() {
+  console.log('\nChecking file size threshold (audit:file-size)...');
+  const report = runAuditFileSize();
+
+  if (report.passed) {
+    pass(`File size audit clean: ${report.scannedFileCount} files scanned, ${report.exemptedCount} exempted under @file-size-exception`);
+  } else {
+    for (const violation of report.violations) {
+      fail(`File exceeds ${report.threshold} LOC: ${violation.filePath} (${violation.lineCount} LOC). Split into focused submodules or declare a justified // @file-size-exception: <reason> marker in the first 5 lines.`);
+    }
+  }
+}
+
+async function validateCacheLayerContractAudit() {
+  console.log('\nChecking cache layer contract (audit:cache-layer-contract)...');
+  const report = runCacheLayerContractAudit();
+
+  if (report.passed) {
+    pass(`Cache layer contract audit clean: ${report.providerCount} provider(s), ${report.fixtureCount} fixture(s), ${report.resultCount} result row(s)`);
+  } else {
+    for (const violation of report.violations) {
+      fail(`Cache layer contract violation [${violation.kind}]: ${violation.detail}`);
+    }
+  }
+}
+
+async function validateRuleIdUniquenessAudit() {
+  console.log('\nChecking rule ID uniqueness (audit:rule-id-uniqueness)...');
+  const report = runRuleIdUniquenessAudit();
+
+  if (report.passed) {
+    pass(`Rule ID audit clean: ${report.migratedFileCount} migrated rule file(s), ${report.skippedFileCount} pre-migration, ${report.knownSectionIdCount} section ID(s), ${report.refMentionCount} [REF:] mention(s) all resolve`);
+  } else {
+    for (const violation of report.violations) {
+      fail(`Rule ID violation [${violation.kind}] in ${violation.file}: ${violation.detail}`);
+    }
+  }
+}
+
+async function validateReflectionCitationAudit() {
+  console.log('\nChecking reflection citations (audit:reflection-citations)...');
+  const report = runReflectionCitationAudit();
+
+  if (report.passed) {
+    pass(`Reflection citation audit clean: ${report.surfaceCount} surface(s), ${report.knownRuleIdCount} known rule ID(s)`);
+  } else {
+    for (const violation of report.violations) {
+      fail(`Reflection citation violation [${violation.kind}] in ${violation.file}: ${violation.detail}`);
+    }
+  }
+}
+
+async function validateCachingScopeHygieneAudit() {
+  console.log('\nChecking caching scope hygiene (audit:caching-scope-hygiene)...');
+  const report = runCachingScopeHygieneAudit();
+
+  if (report.passed) {
+    pass(`Caching scope hygiene clean: ${report.surfaceCount} public surface(s), ${report.totalClaimCount} caching saving claim(s) all integration-scoped`);
+  } else {
+    for (const violation of report.violations) {
+      fail(`Caching scope hygiene violation [${violation.kind}] in ${violation.file}:${violation.line}: ${violation.detail}`);
+    }
+  }
+}
+
+async function validateReleaseBundleAudit() {
+  console.log('\nChecking release benchmark bundle (audit:release-bundle)...');
+  const report = runReleaseBundleAudit();
+
+  if (report.passed) {
+    pass(`Release bundle integrity clean: ${report.artifactCount} artifact(s), release_target=${report.releaseTarget}, release_status=${report.releaseStatus}`);
+  } else {
+    for (const violation of report.violations) {
+      fail(`Release bundle violation [${violation.kind}]: ${violation.detail}`);
+    }
+  }
+}
+
 async function validateMcpConfiguration() {
   console.log('\nChecking MCP configuration...');
 
@@ -576,6 +663,12 @@ async function main() {
   await validateHumanWritingGovernance(coverageValidationContext);
   await validateInstructionAdapters(coverageValidationContext);
   await validateSkillPurgeSurface(coverageValidationContext);
+  await validateCacheLayerContractAudit();
+  await validateReflectionCitationAudit();
+  await validateCachingScopeHygieneAudit();
+  await validateReleaseBundleAudit();
+  await validateFileSizeAudit();
+  await validateRuleIdUniquenessAudit();
 
   console.log('\n===============================================');
   console.log('  RESULTS');