@ryuenn3123/agentic-senior-core 2.5.22 → 3.0.0

package/scripts/documentation-boundary-audit.mjs

@@ -15,6 +15,13 @@ import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const REPOSITORY_ROOT = resolve(__dirname, '..');
+const DOCUMENTATION_BOUNDARY_AUDIT_REPORT_VERSION = '2.1.0';
+const AUTO_DOCS_SYNC_SCOPE_PHASE = 'phase-1';
+const AUTO_DOCS_SYNC_SCOPE_BOUNDARIES = [
+  'public-surface',
+  'api-contract',
+  'database-structure',
+];
 
 const CORE_DOCUMENTATION_FILES = new Set(['README.md', 'CHANGELOG.md']);
 
@@ -22,6 +29,12 @@ const BOUNDARY_RULES = [
   {
     boundaryName: 'public-surface',
     requirement: 'Public surface changes must update README.md, CHANGELOG.md, or docs/* in the same scope.',
+    suggestedDocumentationUpdates: [
+      'README.md',
+      'CHANGELOG.md',
+      'docs/architecture-decision-record.md',
+      'docs/flow-overview.md',
+    ],
     trigger(filePath) {
       return /^(bin\/|lib\/|scripts\/)/.test(filePath) && !isDocumentationFilePath(filePath);
     },
@@ -32,6 +45,12 @@ const BOUNDARY_RULES = [
   {
     boundaryName: 'api-contract',
     requirement: 'API endpoint or contract changes must update API/OpenAPI documentation in the same scope.',
+    suggestedDocumentationUpdates: [
+      'docs/api-contract.md',
+      'docs/flow-overview.md',
+      '.agent-context/rules/api-docs.md',
+      'README.md',
+    ],
     trigger(filePath) {
       return !isDocumentationFilePath(filePath)
         && /(api|openapi|contract|controller|route|endpoint)/i.test(filePath);
@@ -45,6 +64,12 @@ const BOUNDARY_RULES = [
   {
     boundaryName: 'database-structure',
     requirement: 'Database structure changes must update schema or migration documentation in the same scope.',
+    suggestedDocumentationUpdates: [
+      'docs/database-schema.md',
+      'docs/flow-overview.md',
+      '.agent-context/rules/database-design.md',
+      'README.md',
+    ],
     trigger(filePath) {
       return !isDocumentationFilePath(filePath)
         && /(database|schema|migration|repository|sql|prisma|typeorm|knex)/i.test(filePath);
@@ -135,6 +160,9 @@ function isDocumentationFilePath(filePath) {
 
 function evaluateBoundary(boundaryRule, changedFiles, changedDocumentationFiles) {
   const boundaryChangedFiles = changedFiles.filter((filePath) => boundaryRule.trigger(filePath));
+  const expectedDocumentationPaths = Array.isArray(boundaryRule.suggestedDocumentationUpdates)
+    ? boundaryRule.suggestedDocumentationUpdates
+    : [];
 
   if (boundaryChangedFiles.length === 0) {
     return {
@@ -144,12 +172,21 @@ function evaluateBoundary(boundaryRule, changedFiles, changedDocumentationFiles)
       passed: true,
       changedFiles: [],
       documentationFiles: [],
+      expectedDocumentationPaths,
+      missingDocumentationUpdates: false,
+      suggestedActions: [],
       details: 'Boundary not triggered by changed scope.',
     };
   }
 
   const matchingDocumentationFiles = changedDocumentationFiles.filter((filePath) => boundaryRule.docsMatcher(filePath));
   const boundaryPassed = matchingDocumentationFiles.length > 0;
+  const suggestedActions = boundaryPassed
+    ? []
+    : [
+      `Update one or more boundary docs: ${expectedDocumentationPaths.join(', ')}`,
+      'Re-run scripts/documentation-boundary-audit.mjs before merge.',
+    ];
 
   const details = boundaryPassed
     ? `Boundary triggered and synchronized with documentation updates: ${matchingDocumentationFiles.join(', ')}`
@@ -162,6 +199,9 @@ function evaluateBoundary(boundaryRule, changedFiles, changedDocumentationFiles)
     passed: boundaryPassed,
     changedFiles: boundaryChangedFiles,
     documentationFiles: matchingDocumentationFiles,
+      expectedDocumentationPaths,
+      missingDocumentationUpdates: !boundaryPassed,
+      suggestedActions,
     details,
   };
 }
@@ -175,25 +215,72 @@ function runDocumentationBoundaryAudit() {
     evaluateBoundary(boundaryRule, changedFiles, changedDocumentationFiles)
   ));
 
-  const failures = boundaryResults
+  const violations = boundaryResults
     .filter((boundaryResult) => boundaryResult.triggered && !boundaryResult.passed)
-    .map((boundaryResult) => {
-      const affectedFiles = boundaryResult.changedFiles.join(', ');
-      return `${boundaryResult.boundaryName}: ${boundaryResult.requirement} Changed files: ${affectedFiles}`;
-    });
+    .map((boundaryResult) => ({
+      boundaryName: boundaryResult.boundaryName,
+      requirement: boundaryResult.requirement,
+      changedFiles: boundaryResult.changedFiles,
+      expectedDocumentationPaths: boundaryResult.expectedDocumentationPaths,
+      suggestedActions: boundaryResult.suggestedActions,
+      diagnosticCode: `BOUNDARY_${boundaryResult.boundaryName.toUpperCase().replace(/-/g, '_')}_DOCS_SYNC_REQUIRED`,
+    }));
+
+  const failures = violations.map((violation) => {
+    const affectedFiles = violation.changedFiles.join(', ');
+    return `${violation.boundaryName}: ${violation.requirement} Changed files: ${affectedFiles}`;
+  });
 
   const reportPayload = {
     generatedAt: new Date().toISOString(),
+    reportVersion: DOCUMENTATION_BOUNDARY_AUDIT_REPORT_VERSION,
     auditName: 'documentation-boundary-audit',
     source: changedScope.source,
     changedFileCount: changedFiles.length,
     changedFiles,
     boundaryResults,
+    violations,
     passed: failures.length === 0,
     failureCount: failures.length,
     failures,
   };
 
+  const triggeredBoundaryResults = boundaryResults.filter((boundaryResult) => boundaryResult.triggered);
+  const passedTriggeredBoundaryResults = triggeredBoundaryResults.filter((boundaryResult) => boundaryResult.passed);
+  const scopeMatchedDocumentationFiles = uniqueSorted(
+    triggeredBoundaryResults.flatMap((boundaryResult) => boundaryResult.documentationFiles),
+  );
+  const scopeMatchedDocumentationFileSet = new Set(scopeMatchedDocumentationFiles);
+  const outOfScopeDocumentationFiles = changedDocumentationFiles.filter(
+    (filePath) => !scopeMatchedDocumentationFileSet.has(filePath),
+  );
+
+  const precisionNumerator = scopeMatchedDocumentationFiles.length;
+  const precisionDenominator = changedDocumentationFiles.length;
+  const recallNumerator = passedTriggeredBoundaryResults.length;
+  const recallDenominator = triggeredBoundaryResults.length;
+
+  const precision = precisionDenominator > 0 ? precisionNumerator / precisionDenominator : 1;
+  const recall = recallDenominator > 0 ? recallNumerator / recallDenominator : 1;
+
+  reportPayload.autoDocsSyncScope = {
+    phase: AUTO_DOCS_SYNC_SCOPE_PHASE,
+    bounded: true,
+    explicitBoundaries: AUTO_DOCS_SYNC_SCOPE_BOUNDARIES,
+  };
+
+  reportPayload.rolloutMetrics = {
+    measuredAt: reportPayload.generatedAt,
+    precision,
+    recall,
+    precisionNumerator,
+    precisionDenominator,
+    recallNumerator,
+    recallDenominator,
+    scopeMatchedDocumentationFiles,
+    outOfScopeDocumentationFiles,
+  };
+
   console.log(JSON.stringify(reportPayload, null, 2));
   process.exit(reportPayload.passed ? 0 : 1);
 }

package/scripts/forbidden-content-check.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, statSync, readdirSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
 import { join, relative } from 'node:path';
 
 const ROOT_DIR = process.cwd();

package/scripts/frontend-usability-audit.mjs

@@ -21,8 +21,8 @@ const REQUIRED_FILES = [
   'docs/v1.7-issue-breakdown.md',
   'docs/v1.7-execution-playbook.md',
   '.agent-context/rules/frontend-architecture.md',
-  '.agent-context/review-checklists/frontend-usability.md',
-  '.agent-context/review-checklists/frontend-excellence-rubric.md',
+  '.agent-context/review-checklists/pr-checklist.md',
+  '.agent-context/review-checklists/architecture-review.md',
 ];
 
 const REQUIRED_ROADMAP_SNIPPETS = [
@@ -32,24 +32,17 @@ const REQUIRED_ROADMAP_SNIPPETS = [
   'Delivered Scope',
 ];
 
-const REQUIRED_CHECKLIST_SNIPPETS = [
-  'Responsiveness',
-  'Accessibility',
-  'Performance',
-  'Documentation and Release Evidence',
+const REQUIRED_PR_CHECKLIST_SNIPPETS = [
+  '### 2. Architecture (→ rules/architecture.md)',
+  '### 10. Documentation',
+  '### 15. Universal SOP Consolidation',
 ];
 
-const REQUIRED_EXCELLENCE_RUBRIC_SNIPPETS = [
-  'Visual Direction and Identity',
-  'Typography Quality',
-  'Color System Diversity and Contrast',
-  'Interaction Choreography',
-  'Language and Content Consistency',
-  'Text Contrast and Collision Safety',
-  'UX Narrative and Conversion Clarity',
-  'Template Diversity and Originality',
-  'Low-Diversity Template Output Policy',
-  'Awwwards-level reference quality',
+const REQUIRED_ARCHITECTURE_CHECKLIST_SNIPPETS = [
+  '## Backend Universal Principles',
+  'No clever hacks in backend and shared core modules',
+  'No premature abstraction',
+  'Readability over brevity',
 ];
 
 const REQUIRED_FRONTEND_RULE_SNIPPETS = [
@@ -86,17 +79,17 @@ function runAudit() {
 
   const roadmapPath = 'docs/roadmap.md';
   const frontendRulePath = '.agent-context/rules/frontend-architecture.md';
-  const checklistPath = '.agent-context/review-checklists/frontend-usability.md';
-  const excellenceRubricPath = '.agent-context/review-checklists/frontend-excellence-rubric.md';
+  const prChecklistPath = '.agent-context/review-checklists/pr-checklist.md';
+  const architectureChecklistPath = '.agent-context/review-checklists/architecture-review.md';
 
   if (existsSync(resolve(REPOSITORY_ROOT, roadmapPath))) {
     const roadmapContent = readFileSync(resolve(REPOSITORY_ROOT, roadmapPath), 'utf8');
     assertContains('Roadmap', roadmapPath, roadmapContent, REQUIRED_ROADMAP_SNIPPETS, failures);
   }
 
-  if (existsSync(resolve(REPOSITORY_ROOT, checklistPath))) {
-    const checklistContent = readFileSync(resolve(REPOSITORY_ROOT, checklistPath), 'utf8');
-    assertContains('Checklist', checklistPath, checklistContent, REQUIRED_CHECKLIST_SNIPPETS, failures);
+  if (existsSync(resolve(REPOSITORY_ROOT, prChecklistPath))) {
+    const checklistContent = readFileSync(resolve(REPOSITORY_ROOT, prChecklistPath), 'utf8');
+    assertContains('PR checklist', prChecklistPath, checklistContent, REQUIRED_PR_CHECKLIST_SNIPPETS, failures);
   }
 
   if (existsSync(resolve(REPOSITORY_ROOT, frontendRulePath))) {
@@ -104,13 +97,13 @@ function runAudit() {
     assertContains('Frontend rule', frontendRulePath, frontendRuleContent, REQUIRED_FRONTEND_RULE_SNIPPETS, failures);
   }
 
-  if (existsSync(resolve(REPOSITORY_ROOT, excellenceRubricPath))) {
-    const excellenceRubricContent = readFileSync(resolve(REPOSITORY_ROOT, excellenceRubricPath), 'utf8');
+  if (existsSync(resolve(REPOSITORY_ROOT, architectureChecklistPath))) {
+    const excellenceRubricContent = readFileSync(resolve(REPOSITORY_ROOT, architectureChecklistPath), 'utf8');
     assertContains(
-      'Frontend excellence rubric',
-      excellenceRubricPath,
+      'Architecture checklist',
+      architectureChecklistPath,
       excellenceRubricContent,
-      REQUIRED_EXCELLENCE_RUBRIC_SNIPPETS,
+      REQUIRED_ARCHITECTURE_CHECKLIST_SNIPPETS,
       failures
     );
   }

package/scripts/governance-weekly-report.mjs

@@ -12,7 +12,6 @@ import fs from 'node:fs/promises';
 import { spawnSync } from 'node:child_process';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { calculateTrustScore } from './trust-scorer.mjs';
 
 const SCRIPT_FILE_PATH = fileURLToPath(import.meta.url);
 const SCRIPT_DIR = dirname(SCRIPT_FILE_PATH);
@@ -23,7 +22,20 @@ const ARGUMENT_FLAGS = new Set(process.argv.slice(2));
 const isStdoutOnlyMode = ARGUMENT_FLAGS.has('--stdout-only');
 const WEEKLY_WINDOW_DAYS = 7;
 const HISTORY_LIMIT = 26;
-const REQUIRED_VERIFIED_DOMAINS = new Set(['cli', 'frontend', 'fullstack', 'distribution', 'review-quality']);
+const REQUIRED_VERIFIED_DOMAINS = new Set([
+  'canonical-instructions',
+  'pr-checklist',
+  'architecture-review',
+  'mcp-server',
+  'state-continuity',
+]);
+const GOVERNANCE_SURFACE_PATHS = {
+  'canonical-instructions': '.instructions.md',
+  'pr-checklist': '.agent-context/review-checklists/pr-checklist.md',
+  'architecture-review': '.agent-context/review-checklists/architecture-review.md',
+  'mcp-server': 'scripts/mcp-server.mjs',
+  'state-continuity': '.agent-context/state',
+};
 
 function readJsonOrNull(filePath) {
   if (!existsSync(filePath)) {
@@ -139,13 +151,6 @@ function collectCommitSignals(windowDays) {
 }
 
 async function collectSkillTrustSignals() {
-  const skillDirectoryPath = join(REPOSITORY_ROOT, '.agent-context', 'skills');
-  const skillDirectoryEntries = await fs.readdir(skillDirectoryPath, { withFileTypes: true });
-  const skillDomainNames = skillDirectoryEntries
-    .filter((directoryEntry) => directoryEntry.isDirectory())
-    .map((directoryEntry) => directoryEntry.name)
-    .sort((leftDomainName, rightDomainName) => leftDomainName.localeCompare(rightDomainName));
-
   const trustRows = [];
   const tierCounts = {
     verified: 0,
@@ -153,17 +158,26 @@ async function collectSkillTrustSignals() {
     experimental: 0,
   };
 
-  for (const skillDomainName of skillDomainNames) {
-    const trustResult = await calculateTrustScore(join(skillDirectoryPath, skillDomainName));
+  const sortedDomainNames = Array.from(REQUIRED_VERIFIED_DOMAINS).sort((leftName, rightName) => {
+    return leftName.localeCompare(rightName);
+  });
+
+  for (const skillDomainName of sortedDomainNames) {
+    const relativeSurfacePath = GOVERNANCE_SURFACE_PATHS[skillDomainName];
+    const absoluteSurfacePath = join(REPOSITORY_ROOT, relativeSurfacePath);
+    const surfaceExists = existsSync(absoluteSurfacePath);
+    const trustTier = surfaceExists ? 'verified' : 'experimental';
+    const trustScore = surfaceExists ? 100 : 0;
 
-    if (typeof tierCounts[trustResult.tier] === 'number') {
-      tierCounts[trustResult.tier] += 1;
+    if (typeof tierCounts[trustTier] === 'number') {
+      tierCounts[trustTier] += 1;
     }
 
     trustRows.push({
       domain: skillDomainName,
-      tier: trustResult.tier,
-      score: trustResult.score,
+      tier: trustTier,
+      score: trustScore,
+      sourcePath: relativeSurfacePath,
     });
   }
 

package/scripts/llm-judge.mjs

@@ -53,9 +53,6 @@ const IS_DRY_RUN = process.argv.includes('--dry-run');
 const SHOULD_EMIT_MACHINE_REPORT = process.env.LLM_JUDGE_EMIT_JSON !== 'false';
 const MACHINE_REPORT_PATH = process.env.LLM_JUDGE_OUTPUT_PATH || DEFAULT_MACHINE_REPORT_PATH;
 
-/** @type {string[]} Source code file extensions to include in the diff */
-const SOURCE_CODE_EXTENSIONS = ['*.ts', '*.tsx', '*.js', '*.mjs', '*.cjs', '*.py', '*.go', '*.java', '*.cs', '*.rb', '*.php'];
-
 /** @type {Record<string, string>} */
 const SEVERITY_NORMALIZATION_TABLE = {
   critical: 'critical',
@@ -184,12 +181,12 @@ function collectPullRequestDiff() {
   console.log('  Source: local HEAD~1..HEAD fallback');
   try {
     return execSync('git diff HEAD~1 HEAD', execOptions);
-  } catch (err) {
+  } catch {
     try {
       // Initial commit has no parent — diff against empty tree
       const emptyTreeSha = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
       return execSync(`git diff "${emptyTreeSha}" HEAD`, execOptions);
-    } catch (e2) {
+    } catch {
       console.warn('  ⚠️   Unable to execute git diff. Defaulting to empty diff.');
       return '';
     }