@girardelli/architect 6.0.0 → 8.2.0

package/src/adapters/cli.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * Architect CLI v3.1
+ * Architect CLI v8.1
  * Enterprise Architecture Analysis — @girardelli/architect
  *
  * Uso:
@@ -13,12 +13,28 @@
  */
 
 import { architect, ProgressEvent } from '../core/architect.js';
+import { GenesisTerminal } from '../core/GenesisTerminal.js';
+import { c, ProgressReporter } from './progress-logger.js';
+import { AgentExecutor } from '@girardelli/architect-agents/src/core/agent-runtime/executor.js';
+import { InteractiveRefactor } from '../core/interactive-refactor.js';
+import { ForecastV2Engine } from '@girardelli/architect-core/src/core/analyzers/forecast-v2.js';
+import { GitHistoryAnalyzer } from '@girardelli/architect-core/src/infrastructure/git-history.js';
+import { TemporalScorer } from '@girardelli/architect-core/src/core/analyzers/temporal-scorer.js';
+import { PluginRegistry } from '@girardelli/architect-core/src/core/plugin-registry.js';
 import { ReportGenerator } from './reporter.js';
 import { HtmlReportGenerator } from './html-reporter.js';
 import { RefactorReportGenerator } from './refactor-reporter.js';
-import { writeFileSync, existsSync, mkdirSync } from 'fs';
-import { resolve, basename, dirname, join } from 'path';
-import { logger } from '../infrastructure/logger.js';
+import { writeFileSync, existsSync,  readFileSync } from 'fs';
+import { resolve, basename,  join } from 'path';
+import { logger } from '@girardelli/architect-core/src/infrastructure/logger.js';
+import { i18n } from '@girardelli/architect-core/src/core/i18n.js';
+import * as yaml from 'yaml';
+import chokidar from 'chokidar';
+import { ArchitectRules, ValidationResult } from '@girardelli/architect-core/src/core/types/architect-rules.js';
+import { RulesEngine } from '@girardelli/architect-core/src/core/rules-engine.js';
+import { execSync } from 'child_process';
+import { GithubActionAdapter } from './github-action.js';
+import * as github from '@actions/github';
 
 type OutputFormat = 'json' | 'markdown' | 'html';
 
@@ -26,245 +42,19 @@ interface CliOptions {
   command: string;
   path: string;
   format: OutputFormat;
-  output?: string;
+  output: string | undefined;
   verbose: boolean;
+  locale: string;
+  watch: boolean;
+  auto: boolean;
+  interactive: boolean;
 }
 
-// ── ANSI Colors & Styles ──
-const c = {
-  reset: '\x1b[0m',
-  bold: '\x1b[1m',
-  dim: '\x1b[2m',
-  italic: '\x1b[3m',
-  // Colors
-  red: '\x1b[38;5;196m',
-  green: '\x1b[38;5;46m',
-  blue: '\x1b[38;5;33m',
-  cyan: '\x1b[38;5;51m',
-  yellow: '\x1b[38;5;220m',
-  magenta: '\x1b[38;5;201m',
-  orange: '\x1b[38;5;208m',
-  white: '\x1b[38;5;255m',
-  gray: '\x1b[38;5;240m',
-  darkGray: '\x1b[38;5;236m',
-  // Bg
-  bgBlue: '\x1b[48;5;17m',
-  bgGreen: '\x1b[48;5;22m',
-  bgRed: '\x1b[48;5;52m',
-  bgCyan: '\x1b[48;5;23m',
-};
-
-// ── Phase config ──
-interface PhaseConfig {
-  icon: string;
-  label: string;
-  verb: string;
-  color: string;
-}
-
-const PHASES: Record<string, PhaseConfig> = {
-  scan:          { icon: '◉', label: 'FILE SCANNER',        verb: 'Scanning filesystem',         color: c.cyan },
-  dependencies:  { icon: '◉', label: 'DEPENDENCY MAPPER',   verb: 'Mapping import graph',        color: c.blue },
-  layers:        { icon: '◉', label: 'LAYER DETECTOR',      verb: 'Classifying architecture',    color: c.magenta },
-  antipatterns:  { icon: '◉', label: 'PATTERN ANALYZER',    verb: 'Detecting anti-patterns',     color: c.orange },
-  scoring:       { icon: '◉', label: 'QUALITY ENGINE',      verb: 'Computing quality metrics',   color: c.yellow },
-  normalize:     { icon: '◉', label: 'PATH NORMALIZER',     verb: 'Normalizing paths',           color: c.gray },
-  summarize:     { icon: '◉', label: 'AI SUMMARIZER',       verb: 'Generating project summary',  color: c.green },
-};
-
-const PHASE_ORDER = ['scan', 'dependencies', 'layers', 'antipatterns', 'scoring', 'normalize', 'summarize'];
-
-/**
- * Enterprise-Grade Progress Reporter
- * Real-time phase tracking with visual feedback
- */
-class ProgressReporter {
-  private startTime: number;
-  private phaseStart: number = 0;
-  private completedPhases: string[] = [];
-  private totalPhases: number;
-  private scanMetrics: Record<string, number | string> = {};
-
-  constructor() {
-    this.startTime = Date.now();
-    this.totalPhases = PHASE_ORDER.length;
-  }
-
-  /** Print the stylized header */
-  printHeader(projectPath: string): void {
-    const name = basename(projectPath);
-    const w = process.stderr;
-
-    w.write('\n');
-    w.write(`${c.darkGray}  ┌─────────────────────────────────────────────────────────────────┐${c.reset}\n`);
-    w.write(`${c.darkGray}  │${c.reset}  ${c.cyan}${c.bold}⚡ ARCHITECT v3.1${c.reset}  ${c.dim}Enterprise Architecture Intelligence${c.reset}     ${c.darkGray}│${c.reset}\n`);
-    w.write(`${c.darkGray}  │${c.reset}  ${c.dim}@girardelli/architect — powered by Girardelli Tecnologia${c.reset}    ${c.darkGray}│${c.reset}\n`);
-    w.write(`${c.darkGray}  └─────────────────────────────────────────────────────────────────┘${c.reset}\n`);
-    w.write('\n');
-    w.write(`  ${c.dim}Target:${c.reset} ${c.white}${c.bold}${name}${c.reset}\n`);
-    w.write(`  ${c.dim}Path:${c.reset}   ${c.gray}${projectPath}${c.reset}\n`);
-    w.write('\n');
-    w.write(`  ${c.dim}──── Analysis Pipeline ────────────────────────────────────────${c.reset}\n`);
-    w.write('\n');
-  }
-
-  /** Handle a progress event from the analyzer */
-  onProgress(event: ProgressEvent): void {
-    const phase = PHASES[event.phase];
-    if (!phase) return;
-
-    if (event.status === 'start') {
-      this.phaseStart = Date.now();
-      this.printPhaseStart(event.phase, phase);
-    } else if (event.status === 'complete') {
-      this.completedPhases.push(event.phase);
-      this.printPhaseComplete(event.phase, phase, event.metrics);
-      if (event.metrics) {
-        Object.assign(this.scanMetrics, event.metrics);
-      }
-    }
-  }
-
-  private printPhaseStart(key: string, phase: PhaseConfig): void {
-    const idx = PHASE_ORDER.indexOf(key) + 1;
-    const bar = this.buildProgressBar(this.completedPhases.length, this.totalPhases);
-    process.stderr.write(
-      `  ${c.dim}[${idx}/${this.totalPhases}]${c.reset} ${phase.color}${phase.icon}${c.reset} ${c.bold}${phase.label}${c.reset} ${c.dim}— ${phase.verb}...${c.reset}  ${bar}\n`
-    );
-  }
 
-  private printPhaseComplete(key: string, phase: PhaseConfig, metrics?: Record<string, number | string>): void {
-    const elapsed = Date.now() - this.phaseStart;
-    const metricStr = metrics ? this.formatMetrics(key, metrics) : '';
-    process.stderr.write(
-      `  ${c.dim}     └─${c.reset} ${c.green}✓${c.reset} ${c.dim}${this.formatTime(elapsed)}${c.reset}${metricStr}\n`
-    );
-  }
-
-  private formatMetrics(phase: string, m: Record<string, number | string>): string {
-    const parts: string[] = [];
-    switch (phase) {
-      case 'scan':
-        parts.push(`${c.white}${m.files}${c.reset}${c.dim} files${c.reset}`);
-        parts.push(`${c.white}${Number(m.lines).toLocaleString()}${c.reset}${c.dim} lines${c.reset}`);
-        parts.push(`${c.white}${m.languages}${c.reset}${c.dim} langs${c.reset}`);
-        break;
-      case 'dependencies':
-        parts.push(`${c.white}${m.edges}${c.reset}${c.dim} edges${c.reset}`);
-        parts.push(`${c.white}${m.modules}${c.reset}${c.dim} modules${c.reset}`);
-        break;
-      case 'layers':
-        parts.push(`${c.white}${m.layers}${c.reset}${c.dim} layers${c.reset}`);
-        parts.push(`${c.white}${m.classified}${c.reset}${c.dim} classified${c.reset}`);
-        break;
-      case 'antipatterns':
-        if (Number(m.total) === 0) {
-          parts.push(`${c.green}clean${c.reset}`);
-        } else {
-          parts.push(`${c.yellow}${m.total}${c.reset}${c.dim} found${c.reset}`);
-          if (Number(m.critical) > 0) parts.push(`${c.red}${m.critical} critical${c.reset}`);
-          if (Number(m.high) > 0) parts.push(`${c.orange}${m.high} high${c.reset}`);
-        }
-        break;
-      case 'scoring': {
-        const overall = Number(m.overall);
-        const scoreColor = overall >= 80 ? c.green : overall >= 60 ? c.yellow : c.red;
-        parts.push(`${scoreColor}${c.bold}${overall}/100${c.reset}`);
-        parts.push(`${c.dim}M:${m.modularity} C:${m.coupling} Co:${m.cohesion} L:${m.layering}${c.reset}`);
-        break;
-      }
-      case 'summarize':
-        parts.push(`${c.white}${m.modules}${c.reset}${c.dim} modules${c.reset}`);
-        parts.push(`${c.white}${m.techStack}${c.reset}${c.dim} technologies${c.reset}`);
-        break;
-    }
-    return parts.length ? `  ${c.dim}│${c.reset} ${parts.join(`${c.dim} · ${c.reset}`)}` : '';
-  }
-
-  private buildProgressBar(done: number, total: number): string {
-    const width = 20;
-    const filled = Math.round((done / total) * width);
-    const empty = width - filled;
-    const pct = Math.round((done / total) * 100);
-    const bar = `${c.cyan}${'█'.repeat(filled)}${c.darkGray}${'░'.repeat(empty)}${c.reset}`;
-    return `${c.dim}[${c.reset}${bar}${c.dim}]${c.reset} ${c.dim}${pct}%${c.reset}`;
-  }
-
-  private formatTime(ms: number): string {
-    if (ms < 1000) return `${ms}ms`;
-    return `${(ms / 1000).toFixed(1)}s`;
-  }
-
-  /** Print extra phase for refactor/agents/report generation */
-  printExtraPhase(label: string, verb: string, color: string = c.cyan): void {
-    this.phaseStart = Date.now();
-    const idx = this.completedPhases.length + 1;
-    process.stderr.write(
-      `  ${c.dim}[${idx}/—]${c.reset} ${color}◉${c.reset} ${c.bold}${label}${c.reset} ${c.dim}— ${verb}...${c.reset}\n`
-    );
-  }
-
-  printExtraComplete(detail: string): void {
-    const elapsed = Date.now() - this.phaseStart;
-    process.stderr.write(
-      `  ${c.dim}     └─${c.reset} ${c.green}✓${c.reset} ${c.dim}${this.formatTime(elapsed)}${c.reset}  ${detail}\n`
-    );
-  }
-
-  /** Final summary with score visualization */
-  printSummary(score: number, breakdown: Record<string, number>, stats: {
-    files: number; lines: number; antiPatterns: number;
-    refactorSteps?: number; refactorOps?: number; agents?: number;
-  }): void {
-    const totalTime = Date.now() - this.startTime;
-    const w = process.stderr;
-
-    w.write('\n');
-    w.write(`  ${c.dim}──── Results ──────────────────────────────────────────────────${c.reset}\n`);
-    w.write('\n');
-
-    // Score meter
-    const scoreColor = score >= 80 ? c.green : score >= 60 ? c.yellow : c.red;
-    const meterWidth = 40;
-    const filled = Math.round((score / 100) * meterWidth);
-    const meter = `${scoreColor}${'━'.repeat(filled)}${c.darkGray}${'━'.repeat(meterWidth - filled)}${c.reset}`;
-    const grade = score >= 90 ? 'A+' : score >= 80 ? 'A' : score >= 70 ? 'B' : score >= 60 ? 'C' : score >= 50 ? 'D' : 'F';
-
-    w.write(`  ${c.bold}  ARCHITECTURE SCORE${c.reset}\n`);
-    w.write(`  ${meter} ${scoreColor}${c.bold}${score}/100${c.reset} ${c.dim}(${grade})${c.reset}\n`);
-    w.write('\n');
-    w.write(`  ${c.dim}  Modularity${c.reset}  ${this.miniBar(breakdown.modularity)} ${c.white}${breakdown.modularity}${c.reset}\n`);
-    w.write(`  ${c.dim}  Coupling${c.reset}    ${this.miniBar(breakdown.coupling)} ${c.white}${breakdown.coupling}${c.reset}\n`);
-    w.write(`  ${c.dim}  Cohesion${c.reset}    ${this.miniBar(breakdown.cohesion)} ${c.white}${breakdown.cohesion}${c.reset}\n`);
-    w.write(`  ${c.dim}  Layering${c.reset}    ${this.miniBar(breakdown.layering)} ${c.white}${breakdown.layering}${c.reset}\n`);
-    w.write('\n');
-
-    // Stats line
-    w.write(`  ${c.cyan}📁${c.reset} ${c.white}${stats.files}${c.reset}${c.dim} files${c.reset}`);
-    w.write(`  ${c.cyan}📝${c.reset} ${c.white}${stats.lines.toLocaleString()}${c.reset}${c.dim} lines${c.reset}`);
-    w.write(`  ${c.cyan}⚠️${c.reset}  ${c.white}${stats.antiPatterns}${c.reset}${c.dim} anti-patterns${c.reset}`);
-    if (stats.refactorSteps !== undefined) {
-      w.write(`  ${c.cyan}🔧${c.reset} ${c.white}${stats.refactorSteps}${c.reset}${c.dim} steps${c.reset}`);
-    }
-    if (stats.agents !== undefined) {
-      w.write(`  ${c.cyan}🤖${c.reset} ${c.white}${stats.agents}${c.reset}${c.dim} agents${c.reset}`);
-    }
-    w.write('\n');
 
-    // Timing
-    w.write(`\n  ${c.dim}⏱  Completed in ${this.formatTime(totalTime)}${c.reset}\n`);
-    w.write('\n');
-  }
+// ── CLI Parsing ──
 
-  private miniBar(value: number): string {
-    const w = 15;
-    const f = Math.round((value / 100) * w);
-    const color = value >= 80 ? c.green : value >= 60 ? c.yellow : c.red;
-    return `${color}${'▓'.repeat(f)}${c.darkGray}${'░'.repeat(w - f)}${c.reset}`;
-  }
-}
 
-// ── CLI Parsing ──
 
 function parseArgs(args: string[]): CliOptions {
   const command = args[0] || 'analyze';
@@ -275,19 +65,41 @@ function parseArgs(args: string[]): CliOptions {
   const output = outputIdx >= 0 ? args[outputIdx + 1] : undefined;
   const verbose = args.includes('--verbose') || args.includes('-v');
 
-  return { command, path: resolve(pathArg), format, output, verbose };
+  const localeIdx = args.indexOf('--locale');
+  let locale: string = 'en'; // default
+  if (localeIdx >= 0 && args[localeIdx + 1]) {
+    locale = args[localeIdx + 1]!;
+  } else {
+    // Attempt detect via ENV
+    const envLang = process.env['LANG'] || process.env['LANGUAGE'] || '';
+    if (envLang.toLowerCase().includes('pt')) {
+      locale = 'pt-BR';
+    }
+  }
+
+  const watch = args.includes('--watch') || args.includes('-w');
+  const auto = args.includes('--auto');
+  const interactive = args.includes('--interactive') || args.includes('-i');
+
+  return { command, path: resolve(pathArg), format, output: output || undefined, verbose, locale, watch, auto, interactive };
 }
 
 function printUsage(): void {
   console.log(`
-${c.cyan}${c.bold}⚡ Architect v3.1${c.reset} — Enterprise Architecture Intelligence
+${c.cyan}${c.bold}⚡ Architect Agent v7.0${c.reset} — Enterprise Architecture Intelligence
 
 ${c.bold}Usage:${c.reset}
   architect <command> [path] [options]
 
 ${c.bold}Commands:${c.reset}
   ${c.cyan}analyze${c.reset}         Full architecture analysis (default)
-  ${c.cyan}refactor${c.reset}        Generate refactoring plan with actionable steps
+  ${c.cyan}genesis${c.reset}         [NEW] Interactive God Mode Terminal (TUI)
+  ${c.cyan}execute${c.reset}         Autonomous Agent Runtime - auto-refactor project
+  ${c.cyan}check${c.reset}           Run architecture-as-code validation against .architect.rules.yml
+  ${c.cyan}pr-review${c.reset}       Run in GitHub Actions to comment on PRs with Score Delta
+  ${c.cyan}refactor${c.reset}        Generate refactoring plan (use --interactive for guided mode)
+  ${c.cyan}forecast${c.reset}        Predict architecture score decay using ML regression
+  ${c.cyan}plugin${c.reset}          Manage plugins (install, list, search, remove)
   ${c.cyan}agents${c.reset}          Generate/audit .agent/ directory with AI agents
   ${c.cyan}diagram${c.reset}         Generate architecture diagram only
   ${c.cyan}score${c.reset}           Calculate quality score only
@@ -297,13 +109,19 @@ ${c.bold}Commands:${c.reset}
 ${c.bold}Options:${c.reset}
   --format <type>   Output format: html, json, markdown (default: html)
   --output <file>   Output file path
+  --locale <lang>   Language (en or pt-BR)
   --verbose, -v     Enable verbose debug logging
+  --watch, -w       Watch mode (re-run check on file changes)
+  --auto            Agent YOLO Mode - auto-approve structural changes
+  --interactive, -i Interactive refactoring: step-by-step with re-analysis
   --help            Show this help message
 
 ${c.bold}Examples:${c.reset}
-  ${c.dim}$${c.reset} architect analyze ./src
+  ${c.dim}$${c.reset} architect execute ./src
+  ${c.dim}$${c.reset} architect execute ./src --auto
+  ${c.dim}$${c.reset} architect refactor ./src --interactive
+  ${c.dim}$${c.reset} architect forecast ./src
   ${c.dim}$${c.reset} architect analyze ./src --format html --output report.html
-  ${c.dim}$${c.reset} architect score ./src --format json
 
 ${c.dim}@girardelli/architect — Girardelli Tecnologia${c.reset}
   `);
@@ -319,14 +137,23 @@ async function main(): Promise<void> {
 
   const options = parseArgs(args);
   logger.setup({ verbose: options.verbose, json: options.format === 'json' });
+  
+  // Set global locale
+  i18n.setLocale(options.locale as 'en' | 'pt-BR');
 
   try {
     switch (options.command) {
+      case 'genesis': {
+        const terminal = new GenesisTerminal(architect);
+        await terminal.start();
+        break;
+      }
+
       case 'analyze': {
         const progress = new ProgressReporter();
         progress.printHeader(options.path);
 
-        const report = await architect.analyze(options.path, (e) => progress.onProgress(e));
+        const report = await architect.analyze(options.path, (e: ProgressEvent) => progress.onProgress(e));
 
         // Refactoring
         progress.printExtraPhase('REFACTOR ENGINE', 'Building refactoring plan', c.orange);
@@ -379,10 +206,21 @@ async function main(): Promise<void> {
       }
 
       case 'refactor': {
+        // ── Interactive mode (Fase 3.3) ──
+        if (options.interactive) {
+          const interactive = new InteractiveRefactor({
+            projectPath: options.path,
+            autoMode: options.auto,
+          });
+          await interactive.run();
+          break;
+        }
+
+        // ── Standard refactor plan generation ──
         const progress = new ProgressReporter();
         progress.printHeader(options.path);
 
-        const report = await architect.analyze(options.path, (e) => progress.onProgress(e));
+        const report = await architect.analyze(options.path, (e: ProgressEvent) => progress.onProgress(e));
 
         progress.printExtraPhase('REFACTOR ENGINE', 'Building refactoring plan', c.orange);
         const plan = architect.refactor(report, options.path);
@@ -406,11 +244,236 @@ async function main(): Promise<void> {
         break;
       }
 
+      case 'check': {
+        const rulesPath = join(options.path, '.architect.rules.yml');
+
+        const executeCheck = async (): Promise<boolean> => {
+          if (!existsSync(rulesPath)) {
+            logger.error(`Rules file not found at: ${rulesPath}`);
+            logger.error(`Create a '.architect.rules.yml' file to use the 'check' command.`);
+            return false;
+          }
+
+          let rules: ArchitectRules;
+          try {
+            const raw = readFileSync(rulesPath, 'utf8');
+            rules = yaml.parse(raw) as ArchitectRules;
+          } catch (e: any) {
+            logger.error(`Failed to parse ${rulesPath}: ${e.message}`);
+            return false;
+          }
+
+          process.stderr.write(`\n  ${c.cyan}◉${c.reset} ${c.bold}RULES ENGINE${c.reset} ${c.dim}— Validating against .architect.rules.yml...${c.reset}\n`);
+
+          const report = await architect.analyze(options.path);
+          const engine = new RulesEngine();
+          const result = engine.validate(report, rules);
+
+          if (result.violations.length === 0) {
+            process.stderr.write(`\n  ${c.green}✓ All quality gates and boundaries passed!${c.reset} ${c.dim}(Score: ${report.score.overall}/100)${c.reset}\n\n`);
+            return true;
+          }
+
+          process.stderr.write(`\n  ${c.red}✗ Architecture validation failed!${c.reset} ${c.dim}(Score: ${report.score.overall}/100)${c.reset}\n\n`);
+
+          let errors = 0;
+          let warnings = 0;
+
+          for (const v of result.violations) {
+            if (v.level === 'error') {
+              errors++;
+              process.stderr.write(`  ${c.red}[ERROR]${c.reset} ${c.bold}${v.rule}${c.reset}: ${v.message}\n`);
+            } else {
+              warnings++;
+              process.stderr.write(`  ${c.yellow}[WARN]${c.reset} ${c.bold}${v.rule}${c.reset}: ${v.message}\n`);
+            }
+          }
+
+          process.stderr.write(`\n  ${c.dim}Total: ${errors} errors, ${warnings} warnings.${c.reset}\n\n`);
+          return result.success;
+        };
+
+        if (options.watch) {
+          process.stderr.write(`\n  ${c.dim}👀 Watch mode enabled. Listening for changes in ${options.path}...${c.reset}\n`);
+          
+          await executeCheck();
+          
+          const watcher = chokidar.watch([
+            join(options.path, '**/*.ts'),
+            join(options.path, '**/*.js'),
+            rulesPath
+          ], {
+            ignored: /(^|[\/\\])\../, // ignore dotfiles
+            persistent: true,
+            ignoreInitial: true,
+          });
+
+          watcher.on('all', async (_event, path) => {
+            console.clear();
+            process.stderr.write(`  ${c.dim}↻ File changed: ${basename(path)}. Re-running checks...${c.reset}\n`);
+            await executeCheck();
+          });
+          
+          // Keep process alive
+          return new Promise(() => {});
+        } else {
+          const success = await executeCheck();
+          if (!success) process.exit(1);
+        }
+        break;
+      }
+
+      case 'pr-review': {
+        const githubToken = process.env['GITHUB_TOKEN'];
+        if (!githubToken) {
+          logger.error('GITHUB_TOKEN environment variable is required for pr-review');
+          process.exit(1);
+          return;
+        }
+
+        if (!github.context.payload.pull_request) {
+          logger.error('Not running in a Pull Request context. Exiting.');
+          process.exit(0);
+          return;
+        }
+
+        process.stderr.write(`\n  ${c.cyan}◉${c.reset} ${c.bold}PR REVIEWER${c.reset} ${c.dim}— Analyzing HEAD vs BASE...${c.reset}\n`);
+
+        const headReport = await architect.analyze(options.path);
+
+        let baseReport = null;
+        try {
+          const baseRef = github.context.payload.pull_request['base']['ref'];
+          process.stderr.write(`  ${c.dim}↳ Fetching and checking out base branch: ${baseRef}${c.reset}\n`);
+          
+          execSync(`git fetch origin ${baseRef} || true`, { stdio: 'ignore', cwd: options.path });
+          const currentBranch = execSync(`git rev-parse --abbrev-ref HEAD`, { cwd: options.path }).toString().trim();
+          execSync(`git checkout ${baseRef}`, { stdio: 'ignore', cwd: options.path });
+          
+          process.stderr.write(`  ${c.dim}↳ Analyzing base branch...${c.reset}\n`);
+          baseReport = await architect.analyze(options.path);
+
+          process.stderr.write(`  ${c.dim}↳ Reverting to original branch: ${currentBranch}${c.reset}\n`);
+          execSync(`git checkout ${currentBranch}`, { stdio: 'ignore', cwd: options.path });
+        } catch (e: any) {
+          logger.error(`Failed to analyze base branch: ${e.message}`);
+          process.stderr.write(`  ${c.yellow}⚠️ Falling back to single-scan (no delta)${c.reset}\n`);
+          // Ensure we try to checkout back just in case
+          try { execSync(`git checkout -`, { stdio: 'ignore', cwd: options.path }); } catch {}
+        }
+
+        let validationResult: ValidationResult | undefined;
+        const rulesPath = join(options.path, '.architect.rules.yml');
+        if (existsSync(rulesPath)) {
+          process.stderr.write(`  ${c.dim}↳ Validating Architecture Rules...${c.reset}\n`);
+          const raw = readFileSync(rulesPath, 'utf8');
+          const rules = yaml.parse(raw) as ArchitectRules;
+          const engine = new RulesEngine();
+          validationResult = engine.validate(headReport, rules);
+        }
+
+        process.stderr.write(`  ${c.dim}↳ Posting comment to GitHub PR #${github.context.payload.pull_request.number}...${c.reset}\n`);
+        const adapter = new GithubActionAdapter(githubToken);
+        await adapter.postComment(headReport, baseReport, validationResult);
+        
+        process.stderr.write(`\n  ${c.green}✓ PR Comment successfully posted!${c.reset}\n\n`);
+
+        if (validationResult && !validationResult.success) {
+          process.stderr.write(`  ${c.red}✗ Architecture rules validation failed (Action blocked).${c.reset}\n\n`);
+          process.exit(1);
+        }
+        break;
+      }
+
+      case 'forecast': {
+        const progress = new ProgressReporter();
+        progress.printHeader(options.path);
+
+        // Phase 1: Analyze
+        const fReport = await architect.analyze(options.path, (e: ProgressEvent) => progress.onProgress(e));
+
+        // Phase 2: Git history
+        progress.printExtraPhase('GIT HISTORY', 'Analyzing commit timeline', c.magenta);
+        const gitAnalyzer = new GitHistoryAnalyzer();
+        const gitReport = await gitAnalyzer.analyze(options.path);
+        progress.printExtraComplete(
+          `${c.white}${gitReport.totalCommits}${c.reset}${c.dim} commits · ${c.reset}${c.white}${gitReport.modules.length}${c.reset}${c.dim} modules · ${c.reset}${c.white}${gitReport.periodWeeks}${c.reset}${c.dim} weeks${c.reset}`
+        );
+
+        // Phase 3: Temporal scoring
+        progress.printExtraPhase('TEMPORAL SCORER', 'Computing velocity-adjusted scores', c.orange);
+        const scorer = new TemporalScorer();
+        const staticScores = new Map<string, number>();
+        for (const mod of gitReport.modules) {
+          staticScores.set(mod.modulePath, fReport.score.overall);
+        }
+        const temporalReport = scorer.score(gitReport, staticScores);
+        progress.printExtraComplete(
+          `${c.white}${temporalReport.overallTrend}${c.reset}${c.dim} · temporal score: ${c.reset}${c.white}${temporalReport.overallTemporalScore}${c.reset}`
+        );
+
+        // Phase 4: Forecast V2
+        progress.printExtraPhase('FORECAST V2', 'Running ML-based decay prediction', c.cyan);
+        const forecastEngine = new ForecastV2Engine();
+        const forecastResult = forecastEngine.predict(fReport, gitReport, temporalReport);
+        progress.printExtraComplete(`${c.white}${forecastResult.overallRisk}${c.reset}${c.dim} risk · ${c.reset}${c.white}${forecastResult.atRiskModules.length}${c.reset}${c.dim} modules at risk${c.reset}`);
+
+        // Output
+        if (options.format === 'json') {
+          const projectName = String(fReport.projectInfo.name || basename(options.path)).replace(/[^a-zA-Z0-9-]/g, '-');
+          const outputPath = options.output || `forecast-${projectName}.json`;
+          writeFileSync(outputPath, JSON.stringify(forecastResult, null, 2));
+          process.stderr.write(`\n  ${c.green}✓${c.reset} Forecast saved: ${outputPath}\n\n`);
+        } else {
+          // Pretty print to terminal
+          const fc = forecastResult.projectForecast;
+          const riskColor = forecastResult.overallRisk === 'critical' ? c.red
+            : forecastResult.overallRisk === 'high' ? c.orange
+            : forecastResult.overallRisk === 'medium' ? c.yellow
+            : c.green;
+
+          process.stderr.write(`\n  ${c.bold}ARCHITECTURE FORECAST${c.reset}\n`);
+          process.stderr.write(`  ${riskColor}${c.bold}${forecastResult.overallRisk.toUpperCase()} RISK${c.reset}\n\n`);
+          process.stderr.write(`  ${forecastResult.headline}\n\n`);
+
+          process.stderr.write(`  ${c.dim}Score:${c.reset} ${c.white}${Math.round(fc.currentScore)}${c.reset} ${c.dim}→${c.reset} `);
+          const deltaColor = fc.scoreDelta < 0 ? c.red : fc.scoreDelta > 0 ? c.green : c.dim;
+          process.stderr.write(`${deltaColor}${Math.round(fc.predictedScore)}${c.reset} ${c.dim}(${fc.scoreDelta > 0 ? '+' : ''}${fc.scoreDelta.toFixed(1)})${c.reset}\n`);
+          process.stderr.write(`  ${c.dim}Weekly Δ:${c.reset} ${deltaColor}${fc.weeklyDelta > 0 ? '+' : ''}${fc.weeklyDelta.toFixed(2)}${c.reset}${c.dim}/week${c.reset}\n`);
+          process.stderr.write(`  ${c.dim}R²:${c.reset} ${c.white}${fc.regression.rSquared}${c.reset}  ${c.dim}Confidence:${c.reset} ${c.white}${Math.round(fc.confidence * 100)}%${c.reset}\n`);
+
+          if (fc.weeksToThreshold !== Infinity) {
+            process.stderr.write(`  ${c.red}⚠ Critical threshold (${fc.threshold}) in ~${fc.weeksToThreshold} weeks${c.reset}\n`);
+          }
+
+          if (forecastResult.atRiskModules.length > 0) {
+            process.stderr.write(`\n  ${c.bold}AT-RISK MODULES${c.reset}\n`);
+            for (const mod of forecastResult.atRiskModules.slice(0, 5)) {
+              const mColor = mod.riskLevel === 'critical' ? c.red : mod.riskLevel === 'high' ? c.orange : c.yellow;
+              process.stderr.write(`  ${mColor}[${mod.riskLevel}]${c.reset} ${c.bold}${mod.modulePath}${c.reset} ${c.dim}(${mod.currentScore} → ${mod.predictedScore}, Δ${mod.weeklyDelta.toFixed(2)}/w)${c.reset}\n`);
+              for (const driver of mod.drivers.slice(0, 2)) {
+                process.stderr.write(`    ${c.dim}↳ ${driver}${c.reset}\n`);
+              }
+            }
+          }
+
+          if (forecastResult.recommendations.length > 0) {
+            process.stderr.write(`\n  ${c.bold}RECOMMENDATIONS${c.reset}\n`);
+            for (const rec of forecastResult.recommendations) {
+              process.stderr.write(`  ${c.cyan}→${c.reset} ${rec}\n`);
+            }
+          }
+
+          process.stderr.write(`\n`);
+        }
+        break;
+      }
+
       case 'agents': {
         const progress = new ProgressReporter();
         progress.printHeader(options.path);
 
-        const report = await architect.analyze(options.path, (e) => progress.onProgress(e));
+        const report = await architect.analyze(options.path, (e: ProgressEvent) => progress.onProgress(e));
 
         progress.printExtraPhase('REFACTOR ENGINE', 'Building refactoring plan', c.orange);
         const plan = architect.refactor(report, options.path);
@@ -452,6 +515,21 @@ async function main(): Promise<void> {
         break;
       }
 
+      case 'execute': {
+        const progress = new ProgressReporter();
+        progress.printHeader(options.path);
+
+        const report = await architect.analyze(options.path, (e: ProgressEvent) => progress.onProgress(e));
+
+        progress.printExtraPhase('REFACTOR ENGINE', 'Building automated refactoring plan', c.orange);
+        const plan = architect.refactor(report, options.path);
+        progress.printExtraComplete(`${c.white}${plan.steps.length}${c.reset}${c.dim} steps generated${c.reset}`);
+
+        const executor = new AgentExecutor(options.auto);
+        await executor.executePlan(plan);
+        break;
+      }
+
       case 'diagram': {
         const diagram = await architect.diagram(options.path);
         if (options.output) {
@@ -508,6 +586,141 @@ async function main(): Promise<void> {
         break;
       }
 
+      case 'plugin': {
+        const registry = new PluginRegistry(options.path);
+        registry.load();
+
+        // Sub-commands: plugin install <spec>, plugin list, plugin search <query>, plugin remove <name>, plugin enable <name>, plugin disable <name>
+        const subCommand = args[1] ?? 'list';
+        const pluginArg = args[2] ?? '';
+
+        switch (subCommand) {
+          case 'install': {
+            if (!pluginArg) {
+              logger.error('Usage: architect plugin install <package-or-path>');
+              process.exit(1);
+              break;
+            }
+
+            process.stderr.write(`\n  ${c.cyan}◉${c.reset} ${c.bold}PLUGIN INSTALL${c.reset}\n`);
+
+            let entry;
+            if (pluginArg.startsWith('./') || pluginArg.startsWith('../') || pluginArg.startsWith('/')) {
+              process.stderr.write(`  ${c.dim}Installing local plugin: ${pluginArg}${c.reset}\n`);
+              entry = registry.installLocal(pluginArg);
+            } else {
+              process.stderr.write(`  ${c.dim}Installing from npm: ${pluginArg}${c.reset}\n`);
+              entry = registry.installNpm(pluginArg);
+            }
+
+            process.stderr.write(`  ${c.green}✓${c.reset} Installed ${c.bold}${entry.name}${c.reset}@${entry.version} (${entry.source})\n\n`);
+            break;
+          }
+
+          case 'list': {
+            const plugins = registry.list();
+            process.stderr.write(`\n  ${c.bold}INSTALLED PLUGINS${c.reset} — ${plugins.length} total\n\n`);
+
+            if (plugins.length === 0) {
+              process.stderr.write(`  ${c.dim}No plugins installed. Use 'architect plugin install <package>' to add one.${c.reset}\n\n`);
+            } else {
+              for (const p of plugins) {
+                const statusIcon = p.enabled ? `${c.green}●${c.reset}` : `${c.dim}○${c.reset}`;
+                const hooks: string[] = [];
+                if (p.manifest?.hooks.antiPatterns) hooks.push('anti-patterns');
+                if (p.manifest?.hooks.refactorRules) hooks.push('refactor-rules');
+                if (p.manifest?.hooks.scoreModifiers) hooks.push('score-modifiers');
+                const hooksStr = hooks.length > 0 ? ` ${c.dim}[${hooks.join(', ')}]${c.reset}` : '';
+                process.stderr.write(`  ${statusIcon} ${c.bold}${p.name}${c.reset}@${p.version} ${c.dim}(${p.source})${c.reset}${hooksStr}\n`);
+              }
+              process.stderr.write('\n');
+            }
+            break;
+          }
+
+          case 'search': {
+            if (!pluginArg) {
+              logger.error('Usage: architect plugin search <query>');
+              process.exit(1);
+              break;
+            }
+
+            process.stderr.write(`\n  ${c.bold}PLUGIN SEARCH${c.reset} — "${pluginArg}"\n\n`);
+            const results = registry.searchNpm(pluginArg);
+
+            if (results.length === 0) {
+              process.stderr.write(`  ${c.dim}No plugins found matching "${pluginArg}".${c.reset}\n\n`);
+            } else {
+              for (const r of results.slice(0, 10)) {
+                const installed = registry.has(r.name) ? ` ${c.green}[installed]${c.reset}` : '';
+                process.stderr.write(`  ${c.bold}${r.name}${c.reset}@${r.version}${installed}\n`);
+                if (r.description) {
+                  process.stderr.write(`    ${c.dim}${r.description}${c.reset}\n`);
+                }
+              }
+              process.stderr.write('\n');
+            }
+            break;
+          }
+
+          case 'remove': {
+            if (!pluginArg) {
+              logger.error('Usage: architect plugin remove <name>');
+              process.exit(1);
+              break;
+            }
+
+            const removed = registry.uninstall(pluginArg);
+            if (removed) {
+              process.stderr.write(`\n  ${c.green}✓${c.reset} Removed plugin: ${c.bold}${pluginArg}${c.reset}\n\n`);
+            } else {
+              process.stderr.write(`\n  ${c.red}✗${c.reset} Plugin not found: ${pluginArg}\n\n`);
+            }
+            break;
+          }
+
+          case 'enable': {
+            if (!pluginArg) {
+              logger.error('Usage: architect plugin enable <name>');
+              process.exit(1);
+              break;
+            }
+            const ok = registry.setEnabled(pluginArg, true);
+            if (ok) {
+              process.stderr.write(`\n  ${c.green}✓${c.reset} Enabled plugin: ${c.bold}${pluginArg}${c.reset}\n\n`);
+            } else {
+              process.stderr.write(`\n  ${c.red}✗${c.reset} Plugin not found: ${pluginArg}\n\n`);
+            }
+            break;
+          }
+
+          case 'disable': {
+            if (!pluginArg) {
+              logger.error('Usage: architect plugin disable <name>');
+              process.exit(1);
+              break;
+            }
+            const ok = registry.setEnabled(pluginArg, false);
+            if (ok) {
+              process.stderr.write(`\n  ${c.yellow}○${c.reset} Disabled plugin: ${c.bold}${pluginArg}${c.reset}\n\n`);
+            } else {
+              process.stderr.write(`\n  ${c.red}✗${c.reset} Plugin not found: ${pluginArg}\n\n`);
+            }
+            break;
+          }
+
+          default:
+            process.stderr.write(`\n  ${c.bold}Plugin Commands:${c.reset}\n`);
+            process.stderr.write(`  ${c.cyan}architect plugin install <package-or-path>${c.reset}  Install a plugin\n`);
+            process.stderr.write(`  ${c.cyan}architect plugin list${c.reset}                      List installed plugins\n`);
+            process.stderr.write(`  ${c.cyan}architect plugin search <query>${c.reset}             Search npm for plugins\n`);
+            process.stderr.write(`  ${c.cyan}architect plugin remove <name>${c.reset}              Remove a plugin\n`);
+            process.stderr.write(`  ${c.cyan}architect plugin enable <name>${c.reset}              Enable a plugin\n`);
+            process.stderr.write(`  ${c.cyan}architect plugin disable <name>${c.reset}             Disable a plugin\n\n`);
+        }
+        break;
+      }
+
       default:
         logger.error(`Unknown command: ${options.command}`);
         process.exit(1);