@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-architecture-check/index.mjs

@@ -0,0 +1,691 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawnSync } from 'node:child_process';
+
+const sourceExtensions = new Set(['.mjs', '.cjs', '.js', '.jsx', '.ts', '.tsx']);
+const ignoredDirectories = new Set([
+  '.git',
+  '.tmp',
+  '.cursor',
+  '.vibecoding',
+  '.vibecoding-state',
+  'node_modules',
+  'fork',
+  'dist',
+  'build',
+  'coverage',
+]);
+
+const defaultRoleBudgets = {
+  entry: { warnAboveLines: 1500, warnAboveFunctions: 25, warnFunctionBodyAboveLines: 40 },
+  dispatcher: { warnAboveLines: 800, warnAboveFunctions: 20, warnFunctionBodyAboveLines: 50 },
+  checkRunner: { warnAboveLines: 2500, warnAboveFunctions: 80, warnFunctionBodyAboveLines: 120 },
+  commandWrapper: { warnAboveLines: 800, warnAboveFunctions: 40, warnFunctionBodyAboveLines: 100 },
+  smoke: { warnAboveLines: 1200, warnAboveFunctions: 30, warnFunctionBodyAboveLines: 160 },
+  core: { warnAboveLines: 1200, warnAboveFunctions: 50, warnFunctionBodyAboveLines: 120 },
+  state: { warnAboveLines: 1000, warnAboveFunctions: 45, warnFunctionBodyAboveLines: 120 },
+  source: { warnAboveLines: 1000, warnAboveFunctions: 45, warnFunctionBodyAboveLines: 120 },
+};
+
+const defaultArchitectureConfig = {
+  roleBudgets: defaultRoleBudgets,
+  forbiddenDependencies: [
+    { from: 'core', to: ['command', 'check', 'doctor', 'dispatch', 'cli'] },
+    { from: 'state', to: ['presentation', 'doctor', 'check'] },
+    { from: 'commandWrapper', to: ['doctor', 'checkRunner'] },
+  ],
+  riskZones: ['daemon', 'scheduler', 'source apply', 'source --apply', 'merge --apply', 'queue', 'lease', 'retry', 'persistent state', 'writeStateArtifact', 'writeJsonEnvelope', 'fs.writeFileSync', 'fs.rmSync', 'fs.mkdirSync'],
+  stateBoundaryHints: ['.vibecoding-state', 'writeStateArtifact', 'writeJsonEnvelope', 'validateState', 'workflowPath', 'stateDirectory', 'fs.writeFileSync', 'fs.rmSync', 'fs.mkdirSync'],
+  contractSyncHints: ['runtime-cli-usage', 'runtime-cli-args', 'runtime-cli-dispatch', 'tools/vibe-runtime/README.md', 'tools/vibe-runtime-check/index.mjs', 'tools/vibe-doctor/index.mjs', 'tools/vibe-release-check', 'templates/CLAUDE.md', 'templates/AGENTS.md', 'skills/'],
+  roleOverrides: [],
+  highRiskPaths: ['tools/vibe-runtime/index.mjs'],
+  highRiskTerms: ['runExecute', 'runSubagents', 'runDaemon', 'runMerge', 'source --apply', 'merge --apply', 'scheduler --once', 'queueScanEnvelope', 'leaseAuditEnvelope', 'boundedRetryPolicy'],
+  baselinedWarnings: [],
+};
+
+function loadArchitectureConfig(root) {
+  const file = path.join(root, 'architecture.boundaries.json');
+  if (!fs.existsSync(file)) return defaultArchitectureConfig;
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return {
+      ...defaultArchitectureConfig,
+      ...parsed,
+      roleBudgets: { ...defaultArchitectureConfig.roleBudgets, ...(parsed.roleBudgets || {}) },
+      roleOverrides: Array.isArray(parsed.roleOverrides) ? parsed.roleOverrides : defaultArchitectureConfig.roleOverrides,
+      baselinedWarnings: parsed.baselinedWarnings || defaultArchitectureConfig.baselinedWarnings,
+    };
+  } catch {
+    return defaultArchitectureConfig;
+  }
+}
+
+const domainHints = [
+  'runtime',
+  'release',
+  'doctor',
+  'architecture',
+  'workflow',
+  'subagent',
+  'daemon',
+  'scheduler',
+  'source',
+  'merge',
+  'reply',
+  'token',
+  'learning',
+  'governance',
+  'planner',
+  'router',
+  'orchestrator',
+  'platform',
+  'methodology',
+  'verification',
+  'evidence',
+];
+
+function usage() {
+  return `Vibecoding Architecture Check\n\nUsage:\n  node tools/vibe-architecture-check/index.mjs [--root <path>] [--json]\n\nOptions:\n  --root <path>  Repository root to check. Defaults to current working directory.\n  --json         Print machine-readable output.\n  --help, -h     Show this help.\n\nThis check is read-only and warning-only. It reports architecture drift signals but does not fail the gate.\n`;
+}
+
+function parseArgs(argv) {
+  const options = { root: process.cwd(), json: false, help: false };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--json') options.json = true;
+    else if (arg === '--root') {
+      const value = argv[index + 1];
+      if (!value) throw new Error('--root requires a path');
+      options.root = path.resolve(value);
+      index += 1;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return options;
+}
+
+function toPosix(relativePath) {
+  return relativePath.split(path.sep).join('/');
+}
+
+function relativeTo(root, file) {
+  return toPosix(path.relative(root, file));
+}
+
+function isIgnoredDirectory(name) {
+  return ignoredDirectories.has(name);
+}
+
+function collectSourceFiles(root, directory = root, files = []) {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!isIgnoredDirectory(entry.name)) collectSourceFiles(root, path.join(directory, entry.name), files);
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const extension = path.extname(entry.name);
+    if (sourceExtensions.has(extension)) files.push(path.join(directory, entry.name));
+  }
+  return files;
+}
+
+function lineCount(text) {
+  if (!text) return 0;
+  return text.split(/\r?\n/).length;
+}
+
+function configuredRoleOverride(relativePath, config) {
+  const normalized = relativePath.replace(/\\/g, '/');
+  const overrides = Array.isArray(config?.roleOverrides) ? config.roleOverrides : [];
+  const match = overrides.find((override) => override?.path && override?.role && globPatternToRegex(override.path).test(normalized));
+  return match?.role || '';
+}
+
+function classifyRole(relativePath, config = defaultArchitectureConfig) {
+  const normalized = relativePath.replace(/\\/g, '/');
+  const override = configuredRoleOverride(normalized, config);
+  if (override) return override;
+  const base = path.posix.basename(normalized);
+  if (/tools\/[^/]+-check\/index\.mjs$/.test(normalized) || normalized === 'tools/vibe-doctor/index.mjs') return 'checkRunner';
+  if (/tools\/vibe-release-check\/index\.mjs$/.test(normalized)) return 'checkRunner';
+  if (/(^|\/)index\.(mjs|cjs|js|ts|tsx)$/.test(normalized) || /(^|\/)main\.(mjs|cjs|js|ts|tsx)$/.test(normalized)) return 'entry';
+  if (base.includes('dispatch') || base.includes('cli-args') || base.includes('cli-usage')) return 'dispatcher';
+  if (base.includes('command-container')) return 'commandWrapper';
+  if (base.endsWith('-command.mjs') || base.endsWith('-command.js') || base.endsWith('-command.ts')) return 'commandWrapper';
+  if (base.includes('smoke')) return 'smoke';
+  if (/tools\/vibe-release-check\/release-check-[^/]+-suite\.mjs$/.test(normalized)) return 'smoke';
+  if (base.includes('state') || base.includes('artifact') || base.includes('envelope')) return 'state';
+  if (/tools\/vibe-runtime\/runtime-/.test(normalized) || /tools\/vibe-release-check\/release-check-/.test(normalized)) return 'core';
+  return 'source';
+}
+
+function functionMatches(text) {
+  const patterns = [
+    /(?:^|\n)\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z_$][\w$]*)\s*\(/g,
+    /(?:^|\n)\s*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?\([^=]*\)\s*=>/g,
+    /(?:^|\n)\s*(?:export\s+)?const\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?[A-Za-z_$][\w$]*\s*=>/g,
+  ];
+  return patterns.flatMap((pattern) => [...text.matchAll(pattern)].map((match) => ({ name: match[1], index: match.index || 0 })));
+}
+
+function estimateLongFunctions(text) {
+  const starts = functionMatches(text).sort((a, b) => a.index - b.index);
+  const lineOffsets = [0];
+  for (let index = 0; index < text.length; index += 1) {
+    if (text[index] === '\n') lineOffsets.push(index + 1);
+  }
+  const lineOf = (offset) => {
+    let low = 0;
+    let high = lineOffsets.length - 1;
+    while (low <= high) {
+      const mid = Math.floor((low + high) / 2);
+      if (lineOffsets[mid] <= offset) low = mid + 1;
+      else high = mid - 1;
+    }
+    return Math.max(1, high + 1);
+  };
+  return starts.map((start, index) => {
+    const next = starts[index + 1]?.index ?? text.length;
+    return { name: start.name, lines: Math.max(1, lineOf(next) - lineOf(start.index)) };
+  });
+}
+
+function parseImports(text) {
+  return [...text.matchAll(/import\s+(?:[^'";]+?\s+from\s+)?['"]([^'"]+)['"]/g)].map((match) => match[1]);
+}
+
+function domainHintSet(relativePath, text) {
+  const haystack = `${relativePath}\n${functionMatches(text).map((item) => item.name).join('\n')}`.toLowerCase();
+  return domainHints.filter((hint) => haystack.includes(hint));
+}
+
+function addWarning(warnings, file, rule, detail, fix = '') {
+  warnings.push({ file, rule, detail, fix });
+}
+
+function escapeRegexChar(value) {
+  return /[.+^${}()|[\]\\]/.test(value) ? `\\${value}` : value;
+}
+
+function globPatternToRegex(pattern) {
+  const normalized = String(pattern || '').replace(/\\/g, '/');
+  let source = '';
+  for (let index = 0; index < normalized.length; index += 1) {
+    const char = normalized[index];
+    if (char === '*') {
+      if (normalized[index + 1] === '*') {
+        source += '.*';
+        index += 1;
+      } else {
+        source += '[^/]*';
+      }
+    } else {
+      source += escapeRegexChar(char);
+    }
+  }
+  return new RegExp(`^${source}$`);
+}
+
+function warningMatchesBaseline(warning, baseline) {
+  const rules = Array.isArray(baseline.rules) ? baseline.rules : [baseline.rule].filter(Boolean);
+  if (rules.length > 0 && !rules.includes(warning.rule)) return false;
+  const pathPattern = baseline.path || baseline.file;
+  if (!pathPattern) return false;
+  return globPatternToRegex(pathPattern).test(warning.file);
+}
+
+function summarizeBaselinedWarnings(warnings, baselines) {
+  const matched = warnings
+    .map((warning) => ({
+      warning,
+      baseline: baselines.find((candidate) => warningMatchesBaseline(warning, candidate)),
+    }))
+    .filter((item) => item.baseline);
+  const byRule = {};
+  const byFile = {};
+  const byFileRule = {};
+  const byBaseline = {};
+  const byBaselineFiles = {};
+  const matchedBaselineRules = new Set();
+  for (const { warning, baseline } of matched) {
+    byRule[warning.rule] = (byRule[warning.rule] || 0) + 1;
+    byFile[warning.file] = (byFile[warning.file] || 0) + 1;
+    const fileRuleKey = `${warning.file} :: ${warning.rule}`;
+    byFileRule[fileRuleKey] = (byFileRule[fileRuleKey] || 0) + 1;
+    const baselinePath = baseline.path || baseline.file || '<unknown>';
+    const baselineRuleKey = `${baselinePath} :: ${warning.rule}`;
+    byBaseline[baselineRuleKey] = (byBaseline[baselineRuleKey] || 0) + 1;
+    byBaselineFiles[baselineRuleKey] ||= {};
+    byBaselineFiles[baselineRuleKey][warning.file] = (byBaselineFiles[baselineRuleKey][warning.file] || 0) + 1;
+    matchedBaselineRules.add(baselineRuleKey);
+  }
+  const unusedBaselineRules = baselines.flatMap((baseline) => {
+    const baselinePath = baseline.path || baseline.file || '<unknown>';
+    const rules = Array.isArray(baseline.rules) ? baseline.rules : [baseline.rule].filter(Boolean);
+    return rules
+      .map((rule) => `${baselinePath} :: ${rule}`)
+      .filter((key) => !matchedBaselineRules.has(key));
+  });
+  return {
+    by_rule: Object.fromEntries(Object.entries(byRule).sort((left, right) => left[0].localeCompare(right[0]))),
+    top_baselines: Object.entries(byBaseline)
+      .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+      .slice(0, 20)
+      .map(([baseline, count]) => ({ baseline, count })),
+    top_files: Object.entries(byFile)
+      .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+      .slice(0, 20)
+      .map(([file, count]) => ({ file, count })),
+    top_file_rules: Object.entries(byFileRule)
+      .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+      .slice(0, 20)
+      .map(([file_rule, count]) => ({ file_rule, count })),
+    low_count_baseline_rule_files: Object.entries(byBaseline)
+      .filter(([, count]) => count <= 3)
+      .sort((left, right) => left[1] - right[1] || left[0].localeCompare(right[0]))
+      .map(([baseline, count]) => ({
+        baseline,
+        count,
+        files: Object.entries(byBaselineFiles[baseline] || {})
+          .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+          .map(([file, file_count]) => ({ file, count: file_count })),
+      })),
+    unused_baseline_rules: unusedBaselineRules.sort(),
+  };
+}
+
+function applyWarningBaselines(warnings, config) {
+  const baselines = Array.isArray(config.baselinedWarnings) ? config.baselinedWarnings : [];
+  if (baselines.length === 0) return { activeWarnings: warnings, baselinedWarningCount: 0, baselinedWarningBreakdown: { by_rule: {}, top_baselines: [] } };
+  const activeWarnings = warnings.filter((warning) => !baselines.some((baseline) => warningMatchesBaseline(warning, baseline)));
+  return {
+    activeWarnings,
+    baselinedWarningCount: warnings.length - activeWarnings.length,
+    baselinedWarningBreakdown: summarizeBaselinedWarnings(warnings, baselines),
+  };
+}
+
+function textIncludesAny(text, terms = []) {
+  const lower = text.toLowerCase();
+  return terms.filter((term) => lower.includes(String(term).toLowerCase()));
+}
+
+function textIncludesRiskTerms(text, terms = []) {
+  const lower = text.toLowerCase();
+  return terms.filter((term) => {
+    const value = String(term).toLowerCase();
+    if (/^[a-z0-9]+$/.test(value)) return new RegExp(`\\b${value}\\b`).test(lower);
+    return lower.includes(value);
+  });
+}
+
+function ruleRoleBudget({ warnings, relativePath, role, budget, lines, functionCount, functions }) {
+  const longFunctions = functions.filter((item) => item.lines > budget.warnFunctionBodyAboveLines);
+
+  if (lines > budget.warnAboveLines) {
+    addWarning(
+      warnings,
+      relativePath,
+      'file-role-budget',
+      `${role} file has ${lines} lines; budget=${budget.warnAboveLines}`,
+      'Confirm the file still owns a single responsibility, or split command/core/helper/check modules.',
+    );
+  }
+
+  if (functionCount > budget.warnAboveFunctions) {
+    addWarning(
+      warnings,
+      relativePath,
+      'function-density',
+      `${role} file has ${functionCount} functions; budget=${budget.warnAboveFunctions}`,
+      'Check whether multiple domains or validation families have accumulated in one file.',
+    );
+  }
+
+  for (const item of longFunctions.slice(0, 5)) {
+    addWarning(
+      warnings,
+      relativePath,
+      'long-function',
+      `${item.name} is approximately ${item.lines} lines; budget=${budget.warnFunctionBodyAboveLines}`,
+      'Consider extracting pure helpers or a named domain module before adding more behavior.',
+    );
+  }
+
+  if (['entry', 'dispatcher', 'checkRunner'].includes(role) && longFunctions.length > 0) {
+    addWarning(
+      warnings,
+      relativePath,
+      'entry-like-domain-logic',
+      `${role} contains ${longFunctions.length} large function(s): ${longFunctions.slice(0, 5).map((item) => item.name).join(', ')}`,
+      'Entry, dispatcher, and check runner files should stay close to wiring/reporting only.',
+    );
+  }
+}
+
+function dependencyTargetMatches(specifier, target) {
+  const normalized = specifier.replace(/\\/g, '/').toLowerCase();
+  const value = String(target).toLowerCase();
+  if (value === 'cli') return /(^|[-_/])cli([-_/]|$)|cli-args|cli-usage/.test(normalized);
+  if (value === 'check') return /(^|[-_/])check([-_/]|$)|runtime-check|release-check/.test(normalized);
+  if (value === 'command') return /(^|[-_/])command([-_/]|$)|-command\b/.test(normalized);
+  if (value === 'dispatch') return /dispatch/.test(normalized);
+  if (value === 'doctor') return /doctor/.test(normalized);
+  if (value === 'presentation') return /print|report|console|doctor/.test(normalized);
+  return normalized.includes(value);
+}
+
+function isReleaseCheckSameFamilyImport(relativePath, specifier) {
+  const normalizedPath = relativePath.replace(/\\/g, '/');
+  const normalizedSpecifier = specifier.replace(/\\/g, '/');
+  if (!normalizedPath.startsWith('tools/vibe-release-check/')) return false;
+  return normalizedSpecifier.startsWith('./release-check-')
+    || normalizedSpecifier.startsWith('./command-manifest/release-check-');
+}
+
+function ruleDependencyDirection({ warnings, relativePath, role, imports, config }) {
+  const rules = config.forbiddenDependencies || defaultArchitectureConfig.forbiddenDependencies;
+  const matchedRules = rules.filter((rule) => rule.from === role);
+  for (const rule of matchedRules) {
+    const badImports = imports.filter((specifier) => !isReleaseCheckSameFamilyImport(relativePath, specifier) && (rule.to || []).some((target) => dependencyTargetMatches(specifier, target)));
+    if (badImports.length === 0) continue;
+    addWarning(
+      warnings,
+      relativePath,
+      'dependency-direction',
+      `${role} module imports forbidden upper/side-layer specifier(s): ${badImports.join(', ')}`,
+      `Keep ${role} dependencies pointed toward lower-level owner modules, not ${rule.to.join(', ')}.`,
+    );
+  }
+}
+
+function isCommandDepsModule(relativePath) {
+  return /(^|\/)runtime-[^/]+-command-deps\.mjs$/.test(relativePath.replace(/\\/g, '/'));
+}
+
+const commandWrapperDelegatedStateHints = new Set([
+  'writeStateArtifact',
+  'writeJsonEnvelope',
+  'validateState',
+  'workflowPath',
+  'stateDirectory',
+]);
+
+function stateBoundaryMatchesForRole(role, matches) {
+  if (role !== 'commandWrapper') return matches;
+  return matches.filter((match) => !commandWrapperDelegatedStateHints.has(match));
+}
+
+function isRuntimeCommandImplementation(relativePath, role) {
+  const normalized = relativePath.replace(/\\/g, '/');
+  if (role !== 'commandWrapper') return false;
+  return /^tools\/vibe-runtime\/runtime-[^/]+-command\.mjs$/.test(normalized)
+    || normalized === 'tools/vibe-runtime/runtime-control-plane-command.mjs'
+    || normalized === 'tools/vibe-runtime/runtime-interaction-command.mjs';
+}
+
+function ruleStateBoundary({ warnings, relativePath, role, text, config }) {
+  if (isCommandDepsModule(relativePath)) return;
+  const matches = stateBoundaryMatchesForRole(role, textIncludesAny(text, config.stateBoundaryHints || []));
+  if (matches.length === 0) return;
+  if (['core', 'source', 'commandWrapper'].includes(role)) {
+    addWarning(
+      warnings,
+      relativePath,
+      'state-boundary',
+      `${role} file contains state/IO lifecycle hints: ${matches.slice(0, 6).join(', ')}`,
+      'Confirm state creation, validation, consumption, and migration stay in the correct owner module.',
+    );
+  }
+}
+
+function ruleContractSync({ warnings, relativePath, role, text, config }) {
+  if (isCommandDepsModule(relativePath) || isRuntimeCommandImplementation(relativePath, role) || role === 'readOnlyEnvelopeModel') return;
+  const commandSurfaceChanged = /run[A-Z][A-Za-z0-9_]*|--[a-z0-9-]+|writeJsonEnvelope|validate[A-Z][A-Za-z0-9_]*/.test(text);
+  if (!commandSurfaceChanged) return;
+  const contractHints = textIncludesAny(`${relativePath}\n${text}`, config.contractSyncHints || []);
+  if (['entry', 'dispatcher'].includes(role) && contractHints.length === 0) {
+    addWarning(
+      warnings,
+      relativePath,
+      'contract-sync',
+      `${role} file appears to define command/validation surface without local contract-sync markers`,
+      'Check whether CLI usage, README markers, doctor/runtime-check, release-check smoke, templates, or skills need updates.',
+    );
+  }
+}
+
+function ruleFactoryPressure({ warnings, relativePath, text }) {
+  for (const match of text.matchAll(/function\s+(create[A-Za-z0-9_]+)\s*\(deps\)\s*\{[\s\S]*?const\s*\{([\s\S]*?)\}\s*=\s*deps/g)) {
+    const names = match[2].split(',').map((item) => item.trim()).filter(Boolean);
+    if (names.length > 40) {
+      addWarning(
+        warnings,
+        relativePath,
+        'factory-pressure',
+        `${match[1]} destructures ${names.length} dependency item(s)`,
+        'Large factory dependency surfaces usually mean domains should be split or deps grouped by responsibility.',
+      );
+    }
+  }
+}
+
+function ruleIoPurity({ warnings, relativePath, role, text }) {
+  if (role !== 'core') return;
+  const ioHints = textIncludesAny(text, ['process.', 'console.', 'fs.writeFileSync', 'fs.rmSync', 'fs.mkdirSync', 'spawnSync(']);
+  if (ioHints.length > 0) {
+    addWarning(
+      warnings,
+      relativePath,
+      'io-purity',
+      `core module contains IO/presentation hints: ${ioHints.slice(0, 6).join(', ')}`,
+      'Keep pure envelope/core logic separate from CLI output, process state, and filesystem writes where practical.',
+    );
+  }
+}
+
+function isReleaseCheckSmokeHarness(relativePath, role) {
+  const normalized = relativePath.replace(/\\/g, '/');
+  return ['smoke', 'scenarioSmoke'].includes(role) && normalized.startsWith('tools/vibe-release-check/');
+}
+
+function isRuntimeRiskSurfaceOwner(relativePath, role) {
+  const normalized = relativePath.replace(/\\/g, '/');
+  if (normalized === 'tools/vibe-runtime/runtime-command-surface-registry.mjs') return role === 'config';
+  if (normalized === 'tools/vibe-runtime/runtime-state-io.mjs') return role === 'state';
+  if (normalized === 'tools/vibe-runtime/runtime-state-risk-paths.mjs') return role === 'state';
+  if (normalized === 'tools/vibe-runtime/runtime-retry-run-gate-model.mjs') return role === 'state';
+  if (normalized === 'tools/vibe-runtime/runtime-scheduler-risk-artifacts.mjs') return role === 'schedulerRiskOwner';
+  if (normalized === 'tools/vibe-runtime/runtime-subagents-risk-artifacts.mjs') return role === 'subagentsRiskOwner';
+  if (role !== 'dispatcher') return false;
+  return [
+    'tools/vibe-runtime/runtime-cli-args.mjs',
+    'tools/vibe-runtime/runtime-cli-command-specs.mjs',
+    'tools/vibe-runtime/runtime-cli-usage.mjs',
+  ].includes(normalized);
+}
+
+function isRiskGovernanceOwner(relativePath, role) {
+  const normalized = relativePath.replace(/\\/g, '/');
+  if (['runtimeCompositionRoot', 'sourceMergeCommand', 'readOnlyEnvelopeModel'].includes(role)) return true;
+  if (isRuntimeRiskSurfaceOwner(normalized, role)) return true;
+  if (normalized === 'tools/vibe-architecture-check/index.mjs') return true;
+  if (normalized === 'tools/vibe-doctor/index.mjs') return true;
+  return role === 'installer' && normalized === 'tools/vibe-init/index.mjs';
+}
+
+function isExampleSmokeHarness(relativePath, role) {
+  const normalized = relativePath.replace(/\\/g, '/');
+  return role === 'smoke' && normalized.startsWith('examples/');
+}
+
+function ruleRiskZoneTouch({ warnings, relativePath, role, text, config }) {
+  const configuredTerms = [...(config.riskZones || []), ...(config.highRiskTerms || [])];
+  const highRiskTerms = role === 'commandWrapper'
+    ? configuredTerms.filter((term) => String(term) !== 'writeJsonEnvelope')
+    : configuredTerms;
+  const matches = textIncludesRiskTerms(text, highRiskTerms);
+  if (matches.length === 0) return;
+  if (isRiskGovernanceOwner(relativePath, role) || isReleaseCheckSmokeHarness(relativePath, role) || isExampleSmokeHarness(relativePath, role)) return;
+  const highRiskPath = (config.highRiskPaths || []).some((item) => relativePath === item || relativePath.startsWith(`${item}/`));
+  if (highRiskPath || matches.length >= 2) {
+    addWarning(
+      warnings,
+      relativePath,
+      'risk-zone-touch',
+      `file touches high-risk architecture terms: ${matches.slice(0, 8).join(', ')}`,
+      'Execution, scheduler, daemon, source apply, merge, retry, queue, lease, and persistent state changes need explicit plan and stronger verification.',
+    );
+  }
+}
+
+function ruleOwnerDrift({ warnings, relativePath, role, text, lines }) {
+  if (role === 'runtimeCompositionRoot') return;
+  const hintedDomains = domainHintSet(relativePath, text);
+  if (hintedDomains.length > 8 && lines > 500) {
+    addWarning(
+      warnings,
+      relativePath,
+      'owner-drift',
+      `file references many domain hints: ${hintedDomains.join(', ')}`,
+      'Check whether unrelated domains have accumulated in one owner module.',
+    );
+  }
+}
+
+function ruleEvolutionPressure({ warnings, relativePath, role, text, lines }) {
+  const todoCount = (text.match(/\b(?:todo|fixme|hack)\b/gi) || []).length;
+  const genericHelperCount = (text.match(/\b(?:helper|utils?|common|shared|misc)\b/gi) || []).length;
+  if (todoCount >= 5) {
+    addWarning(
+      warnings,
+      relativePath,
+      'evolution-pressure',
+      `file contains ${todoCount} explicit debt marker(s)`,
+      'Confirm unresolved design debt is tracked intentionally before adding more behavior.',
+    );
+  }
+  if (lines > 500 && genericHelperCount >= 10 && role !== 'entry') {
+    addWarning(
+      warnings,
+      relativePath,
+      'evolution-pressure',
+      `large ${role} file has many generic helper/shared naming hints`,
+      'Prefer named domain modules over broad helper buckets when extending behavior.',
+    );
+  }
+}
+
+function analyzeFile(root, absoluteFile, warnings, config) {
+  const relativePath = relativeTo(root, absoluteFile);
+  const text = fs.readFileSync(absoluteFile, 'utf8');
+  const role = classifyRole(relativePath, config);
+  const budget = (config.roleBudgets || defaultRoleBudgets)[role] || (config.roleBudgets || defaultRoleBudgets).source;
+  const lines = lineCount(text);
+  const functions = estimateLongFunctions(text);
+  const functionCount = functions.length;
+  const imports = parseImports(text);
+
+  ruleRoleBudget({ warnings, relativePath, role, budget, lines, functionCount, functions });
+  ruleDependencyDirection({ warnings, relativePath, role, imports, config });
+  ruleStateBoundary({ warnings, relativePath, role, text, config });
+  ruleContractSync({ warnings, relativePath, role, text, config });
+  ruleFactoryPressure({ warnings, relativePath, text });
+  ruleIoPurity({ warnings, relativePath, role, text });
+  ruleRiskZoneTouch({ warnings, relativePath, role, text, config });
+  ruleEvolutionPressure({ warnings, relativePath, role, text, lines });
+  ruleOwnerDrift({ warnings, relativePath, role, text, lines });
+
+  return { file: relativePath, role, lines, functions: functionCount, imports: imports.length };
+}
+
+function diffGrowthWarnings(root, warnings, config) {
+  const result = spawnSync('git', ['diff', '--numstat', '--', '*.mjs', '*.js', '*.ts', '*.tsx', '*.jsx', '*.cjs'], {
+    cwd: root,
+    encoding: 'utf8',
+    timeout: 15000,
+  });
+  if (result.status !== 0) return;
+  for (const line of result.stdout.split(/\r?\n/)) {
+    if (!line.trim()) continue;
+    const [addedText, removedText, ...fileParts] = line.split(/\s+/);
+    const added = Number(addedText);
+    const removed = Number(removedText);
+    const file = fileParts.join(' ');
+    if (!Number.isFinite(added) || !Number.isFinite(removed) || !file) continue;
+    const growth = added - removed;
+    if (growth <= 80) continue;
+    const role = classifyRole(file.replace(/\\/g, '/'), config);
+    addWarning(
+      warnings,
+      file.replace(/\\/g, '/'),
+      'diff-aware-growth',
+      `current diff grows this ${role} file by +${growth} lines (${added} added, ${removed} removed)`,
+      'Large net growth should include an explicit owner-module decision or extraction plan.',
+    );
+  }
+}
+
+function analyze(root) {
+  if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`Root not found: ${root}`);
+  const warnings = [];
+  const config = loadArchitectureConfig(root);
+  const files = collectSourceFiles(root).sort();
+  const fileStats = files.map((file) => analyzeFile(root, file, warnings, config));
+  diffGrowthWarnings(root, warnings, config);
+  const { activeWarnings, baselinedWarningCount, baselinedWarningBreakdown } = applyWarningBaselines(warnings, config);
+  const roleCounts = fileStats.reduce((acc, item) => {
+    acc[item.role] = (acc[item.role] || 0) + 1;
+    return acc;
+  }, {});
+  return {
+    ok: true,
+    result: 'passed',
+    warning_count: activeWarnings.length,
+    baselined_warning_count: baselinedWarningCount,
+    baselined_warning_breakdown: baselinedWarningBreakdown,
+    checked_files: fileStats.length,
+    role_counts: roleCounts,
+    warnings: activeWarnings,
+  };
+}
+
+function printText(root, report) {
+  console.log('Vibecoding Architecture Check');
+  console.log(`Root: ${root}`);
+  console.log(`Checked files: ${report.checked_files}`);
+  console.log('');
+  if (report.warnings.length === 0) {
+    console.log('[ok] no architecture drift warnings');
+  } else {
+    for (const warning of report.warnings) {
+      console.log(`[warn] ${warning.file}: ${warning.rule}`);
+      console.log(`       ${warning.detail}`);
+      if (warning.fix) console.log(`       fix: ${warning.fix}`);
+    }
+  }
+  console.log('');
+  console.log('Result: passed');
+  console.log(`Warnings: ${report.warning_count}`);
+  if (report.baselined_warning_count) console.log(`Baselined warnings: ${report.baselined_warning_count}`);
+}
+
+try {
+  const options = parseArgs(process.argv.slice(2));
+  if (options.help) {
+    console.log(usage());
+    process.exit(0);
+  }
+  const root = path.resolve(options.root);
+  const report = analyze(root);
+  if (options.json) console.log(`${JSON.stringify({ command: 'architecture-check', root, ...report }, null, 2)}\n`);
+  else printText(root, report);
+} catch (error) {
+  console.error(`Error: ${error.message}`);
+  process.exit(1);
+}