plankit-cli 1.4.0 → 1.5.0

package/README.md

@@ -64,6 +64,8 @@ plankit review my-feature
 | `plankit implement <feature> <phase>` | Validate phase context (spec + prior outputs) and prepare `outputs/phase-N-output.md`. |
 | `plankit review <feature>` | Run verification commands, mark README archived, and move the feature to `artifacts/archived/`. |
 | `plankit status [--json]` | List active and archived features. |
+| `plankit scan [dir] [--json] [--threshold <n>]` | Run zero-dependency static analysis, audit health (0-100), extract design tokens, and generate `artifacts/.plankit-index.json`. |
+| `plankit ui [--no-tui]` | Launch interactive terminal feature progress matrix & action dashboard. |
 | `plankit archive <feature>` | Move a feature to archived without running verification. |
 | `plankit version` / `--version` / `-v` | Print the installed version (`plankit-cli vX.Y.Z`). |
 | `plankit help` / `--help` / `-h` | Show usage. |
@@ -79,6 +81,9 @@ plankit review my-feature
 | `--agent <name>` | Select your coding agent during `init` (`opencode`, `gemini`, `codex`, `cursor`; default `opencode`). |
 | `--framework <name>` | Select framework command suite during `init` (`angular`, `vue`, `dotnet`, `none`, `all`; default `none`). |
 | `--frameworks <list>` | Comma-separated list of framework command suites (e.g. `vue,dotnet`). |
+| `--threshold <score>` | Fail `scan` command with exit code 1 if health score is below threshold (CI quality gate). |
+| `--json` | Output `scan` or `status` as machine-readable JSON. |
+| `--no-tui` | Render static ASCII table instead of interactive dashboard for `ui` command. |
 
 ### Plan options
 
@@ -164,6 +169,52 @@ plankit init --agent cursor
 
 ---
 
+## Static analysis engine (`plankit scan`)
+
+PlanKit ships with an ultra-fast, **zero-dependency static analyzer** that audits codebase modernization health without burning LLM tokens:
+
+```bash
+# Run audit and output terminal report + save artifacts/.plankit-index.json
+plankit scan
+
+# Output machine-readable JSON metrics
+plankit scan --json
+
+# CI Quality Gate: fail if health score drops below threshold
+plankit scan --threshold 80
+```
+
+### What it checks:
+- **Vue SFC Architecture**: Options API vs `<script setup>` ratio, TypeScript vs JavaScript, Pinia vs Vuex vs composables.
+- **Design Token Mining**: Automatically detects repeated hex colors, font sizes, margins, and paddings across templates and styles.
+- **.NET Architecture**: Target frameworks, layer dependency boundaries (Clean Architecture / Vertical Slices), and Minimal APIs vs Controllers.
+- **Modernization Hotspots**: Flags god components (> 400 lines), deprecated deep selectors (`::v-deep`, `/deep/`), mixins, and layer boundary violations.
+- **Index Generation**: Saves `artifacts/.plankit-index.json` so AI agents can query repository intelligence immediately.
+
+---
+
+## Interactive feature dashboard (`plankit ui`)
+
+Launch a terminal UI to visualize active features, phase completion status, and trigger development workflows with single keystrokes:
+
+```bash
+# Launch interactive TUI
+plankit ui
+
+# Non-interactive / CI ASCII table output
+plankit ui --no-tui
+```
+
+### Interactive Actions:
+- **`[↑/↓]` or `[j/k]`**: Navigate between active features.
+- **`[i]`**: Prepare and validate implementation context for the next pending phase.
+- **`[c]`**: Generate a design alignment and clarification artifact.
+- **`[r]`**: Review, verify DoD, and archive completed feature.
+- **`[s]`**: Run the repository static scan and view live health scorecard.
+- **`[q]`**: Exit dashboard.
+
+---
+
 ## Framework command suites
 
 During `plankit init`, PlanKit prompts you to choose optional framework-specific command suites (or pass `--framework <name>` / `--frameworks <names>`):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plankit-cli",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "PlanKit Command Suite CLI for AI Coding Assistants (Antigravity, OpenCode, Codex, Cursor)",
   "main": "src/cli.js",
   "bin": {

package/src/analyzer/dotnetScanner.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Fast static analyzer for .NET projects and solutions (.sln, .csproj, .cs).
+ */
+
+export function analyzeCsprojFile(filePath, content = null) {
+  const code = content !== null ? content : fs.readFileSync(filePath, 'utf8');
+  const fileName = path.basename(filePath);
+  const projectName = fileName.replace(/\.csproj$/i, '');
+
+  // Target Framework
+  const tfMatch = /<TargetFramework(?:s)?>([^<]+)<\/TargetFramework(?:s)?>/i.exec(code);
+  const targetFramework = tfMatch ? tfMatch[1].trim() : 'unknown';
+
+  // Nullable
+  const nullableMatch = /<Nullable>([^<]+)<\/Nullable>/i.exec(code);
+  const nullable = nullableMatch ? nullableMatch[1].trim().toLowerCase() === 'enable' : false;
+
+  // Project References
+  const projectReferences = [];
+  const refRegex = /<ProjectReference\s+Include=["']([^"']+)["']/gi;
+  let match;
+  while ((match = refRegex.exec(code)) !== null) {
+    const refPath = match[1].replace(/\\/g, '/');
+    const refProject = path.basename(refPath).replace(/\.csproj$/i, '');
+    projectReferences.push(refProject);
+  }
+
+  // Package References
+  const packageReferences = [];
+  const pkgRegex = /<PackageReference\s+Include=["']([^"']+)["'](?:\s+Version=["']([^"']+)["'])?/gi;
+  while ((match = pkgRegex.exec(code)) !== null) {
+    packageReferences.push({
+      name: match[1],
+      version: match[2] || 'unknown'
+    });
+  }
+
+  // Determine Layer (Clean Architecture heuristics)
+  let layer = 'other';
+  const lowerName = projectName.toLowerCase();
+  if (lowerName.includes('domain') || lowerName.includes('core')) {
+    layer = 'domain';
+  } else if (lowerName.includes('application') || lowerName.includes('usecase')) {
+    layer = 'application';
+  } else if (lowerName.includes('infrastructure') || lowerName.includes('data') || lowerName.includes('persistence')) {
+    layer = 'infrastructure';
+  } else if (lowerName.includes('api') || lowerName.includes('web') || lowerName.includes('server')) {
+    layer = 'api';
+  } else if (lowerName.includes('test')) {
+    layer = 'tests';
+  }
+
+  // Layer Boundary Violations
+  const violations = [];
+  if (layer === 'domain') {
+    for (const ref of projectReferences) {
+      const lowerRef = ref.toLowerCase();
+      if (lowerRef.includes('infra') || lowerRef.includes('api') || lowerRef.includes('web') || lowerRef.includes('app')) {
+        violations.push({
+          type: 'domain_layer_violation',
+          message: `Domain project "${projectName}" illegally references outer layer "${ref}"`
+        });
+      }
+    }
+  } else if (layer === 'application') {
+    for (const ref of projectReferences) {
+      const lowerRef = ref.toLowerCase();
+      if (lowerRef.includes('infra') || lowerRef.includes('api') || lowerRef.includes('web')) {
+        violations.push({
+          type: 'application_layer_violation',
+          message: `Application project "${projectName}" illegally references outer layer "${ref}"`
+        });
+      }
+    }
+  }
+
+  return {
+    filePath,
+    projectName,
+    targetFramework,
+    nullable,
+    layer,
+    projectReferences,
+    packageReferences,
+    violations
+  };
+}
+
+export function analyzeCSharpFile(filePath, content = null) {
+  const code = content !== null ? content : fs.readFileSync(filePath, 'utf8');
+  const lines = code.split(/\r?\n/).length;
+
+  const isMinimalApi = /\bapp\.Map(?:Get|Post|Put|Delete|Patch|Group)\b/.test(code) ||
+    /\bgroup\.Map(?:Get|Post|Put|Delete|Patch)\b/.test(code);
+  const isController = /:\s*(?:ControllerBase|Controller)\b/.test(code) || /\[ApiController\]/.test(code);
+  const hasFileScopedNamespace = /^namespace\s+[\w.]+\s*;/m.test(code);
+  const hasPrimaryConstructor = /(?:public|internal|private)\s+(?:class|record|struct)\s+\w+\s*\([^)]*\)\s*(?::|\{)/.test(code);
+
+  return {
+    filePath,
+    fileName: path.basename(filePath),
+    lines,
+    isMinimalApi,
+    isController,
+    hasFileScopedNamespace,
+    hasPrimaryConstructor
+  };
+}

package/src/analyzer/engine.js

@@ -0,0 +1,290 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { analyzeVueFile } from './vueScanner.js';
+import { analyzeCSharpFile, analyzeCsprojFile } from './dotnetScanner.js';
+
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'build',
+  'bin',
+  'obj',
+  'coverage',
+  '.gemini',
+  '.opencode',
+  '.codex',
+  'artifacts'
+]);
+
+export async function runAnalysis(targetDir, options = {}) {
+  const rootDir = path.resolve(targetDir);
+  const files = collectScannableFiles(rootDir);
+
+  const vueResults = [];
+  const csprojResults = [];
+  const csharpResults = [];
+
+  for (const file of files) {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === '.vue') {
+      vueResults.push(analyzeVueFile(file));
+    } else if (ext === '.csproj') {
+      csprojResults.push(analyzeCsprojFile(file));
+    } else if (ext === '.cs') {
+      csharpResults.push(analyzeCSharpFile(file));
+    }
+  }
+
+  const score = calculateHealthScore(vueResults, csprojResults, csharpResults);
+  const tokenCandidates = aggregateTokens(vueResults);
+  const hotspots = aggregateHotspots(vueResults, csprojResults);
+
+  const report = {
+    timestamp: new Date().toISOString(),
+    rootDir,
+    totalFilesScanned: files.length,
+    score,
+    vue: summarizeVueMetrics(vueResults),
+    dotnet: summarizeDotnetMetrics(csprojResults, csharpResults),
+    designTokens: tokenCandidates,
+    hotspots
+  };
+
+  if (options.saveIndex !== false) {
+    saveIndexFile(rootDir, report, options.artifactsDir || 'artifacts');
+  }
+
+  return report;
+}
+
+export function formatReport(report, useColors = true) {
+  const c = useColors
+    ? {
+        reset: '\x1b[0m',
+        bold: '\x1b[1m',
+        green: '\x1b[32m',
+        yellow: '\x1b[33m',
+        red: '\x1b[31m',
+        cyan: '\x1b[36m',
+        dim: '\x1b[2m'
+      }
+    : {
+        reset: '',
+        bold: '',
+        green: '',
+        yellow: '',
+        red: '',
+        cyan: '',
+        dim: ''
+      };
+
+  const scoreColor = report.score.total >= 80 ? c.green : (report.score.total >= 50 ? c.yellow : c.red);
+  const out = [];
+
+  out.push(`${c.bold}======================================================${c.reset}`);
+  out.push(`${c.bold}            PlanKit Repository Health Audit            ${c.reset}`);
+  out.push(`${c.bold}======================================================${c.reset}`);
+  out.push(`Root Directory: ${c.cyan}${report.rootDir}${c.reset}`);
+  out.push(`Files Scanned:  ${report.totalFilesScanned}`);
+  out.push(`Health Score:   ${scoreColor}${c.bold}${report.score.total} / 100${c.reset} (${report.score.grade})`);
+  out.push('');
+
+  // Vue summary if Vue files detected
+  if (report.vue && report.vue.totalSfc > 0) {
+    out.push(`${c.bold}Vue Architecture & Modernization Metrics:${c.reset}`);
+    out.push(`  SFC Count:               ${report.vue.totalSfc}`);
+    out.push(`  <script setup> Ratio:    ${c.green}${report.vue.scriptSetupPercent}%${c.reset} (${report.vue.scriptSetupCount}/${report.vue.totalSfc})`);
+    out.push(`  TypeScript Ratio:        ${c.green}${report.vue.tsPercent}%${c.reset} (${report.vue.tsCount}/${report.vue.totalSfc})`);
+    out.push(`  Pinia / Modern State:    ${report.vue.piniaCount} files (Vuex legacy: ${report.vue.vuexCount})`);
+    out.push(`  Maturity Distribution:  ${c.green}Preferred: ${report.vue.maturity.preferred}${c.reset} | ${c.yellow}Transitional: ${report.vue.maturity.transitional}${c.reset} | ${c.red}Legacy: ${report.vue.maturity.legacy}${c.reset}`);
+    out.push('');
+  }
+
+  // .NET summary if .NET files detected
+  if (report.dotnet && (report.dotnet.projectsCount > 0 || report.dotnet.csharpFilesCount > 0)) {
+    out.push(`${c.bold}.NET Solution Architecture Metrics:${c.reset}`);
+    out.push(`  Projects:                ${report.dotnet.projectsCount}`);
+    out.push(`  C# Source Files:         ${report.dotnet.csharpFilesCount}`);
+    out.push(`  Minimal APIs:            ${report.dotnet.minimalApiCount} | Controllers: ${report.dotnet.controllerCount}`);
+    if (report.dotnet.layerViolations.length > 0) {
+      out.push(`  ${c.red}Layer Boundary Violations:${c.reset} ${report.dotnet.layerViolations.length}`);
+    }
+    out.push('');
+  }
+
+  // Token candidates
+  if (report.designTokens && report.designTokens.frequentColors.length > 0) {
+    out.push(`${c.bold}Top Discovered Design Token Candidates (Colors):${c.reset}`);
+    for (const item of report.designTokens.frequentColors.slice(0, 5)) {
+      out.push(`  ${c.cyan}${item.color}${c.reset} (used in ${item.count} component/style rules)`);
+    }
+    out.push('');
+  }
+
+  // Hotspots
+  if (report.hotspots.length > 0) {
+    out.push(`${c.bold}Modernization Hotspots & Anti-Patterns (${report.hotspots.length}):${c.reset}`);
+    for (const h of report.hotspots.slice(0, 8)) {
+      out.push(`  - ${c.yellow}${h.file}${c.reset}: ${h.message}`);
+    }
+    if (report.hotspots.length > 8) {
+      out.push(`  ${c.dim}... and ${report.hotspots.length - 8} more in artifacts/.plankit-index.json${c.reset}`);
+    }
+    out.push('');
+  }
+
+  out.push(`${c.bold}======================================================${c.reset}`);
+  out.push(`Index saved to ${c.cyan}artifacts/.plankit-index.json${c.reset}`);
+  return out.join('\n');
+}
+
+function collectScannableFiles(dir, files = []) {
+  if (!fs.existsSync(dir)) return files;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith('.')) {
+      continue;
+    }
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      collectScannableFiles(fullPath, files);
+    } else if (entry.isFile()) {
+      const ext = path.extname(entry.name).toLowerCase();
+      if (['.vue', '.csproj', '.cs', '.ts', '.js'].includes(ext)) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  return files;
+}
+
+function calculateHealthScore(vueResults, csprojResults, csharpResults) {
+  let score = 100;
+
+  if (vueResults.length > 0) {
+    const total = vueResults.length;
+    const scriptSetup = vueResults.filter((r) => r.vueStyle === 'script_setup').length;
+    const ts = vueResults.filter((r) => r.language === 'ts').length;
+    const legacy = vueResults.filter((r) => r.maturity === 'legacy').length;
+    const vuex = vueResults.filter((r) => r.state === 'vuex').length;
+
+    // Deduct for non-script setup ratio
+    score -= Math.round(((total - scriptSetup) / total) * 35);
+    // Deduct for JS ratio (lack of TS)
+    score -= Math.round(((total - ts) / total) * 20);
+    // Deduct for legacy Vuex
+    if (vuex > 0) {
+      score -= Math.min(15, vuex * 3);
+    }
+    // Deduct for legacy anti-patterns (mixins, filters, etc.)
+    score -= Math.min(20, legacy * 4);
+  }
+
+  if (csprojResults.length > 0) {
+    const violations = csprojResults.flatMap((r) => r.violations).length;
+    score -= Math.min(25, violations * 10);
+  }
+
+  const finalScore = Math.max(0, Math.min(100, score));
+  let grade = 'A';
+  if (finalScore < 60) grade = 'F';
+  else if (finalScore < 70) grade = 'D';
+  else if (finalScore < 80) grade = 'C';
+  else if (finalScore < 90) grade = 'B';
+
+  return { total: finalScore, grade };
+}
+
+function summarizeVueMetrics(vueResults) {
+  const totalSfc = vueResults.length;
+  if (totalSfc === 0) return null;
+
+  const scriptSetupCount = vueResults.filter((r) => r.vueStyle === 'script_setup').length;
+  const tsCount = vueResults.filter((r) => r.language === 'ts').length;
+  const piniaCount = vueResults.filter((r) => r.state === 'pinia').length;
+  const vuexCount = vueResults.filter((r) => r.state === 'vuex').length;
+
+  const maturity = {
+    preferred: vueResults.filter((r) => r.maturity === 'preferred').length,
+    transitional: vueResults.filter((r) => r.maturity === 'transitional').length,
+    legacy: vueResults.filter((r) => r.maturity === 'legacy').length
+  };
+
+  return {
+    totalSfc,
+    scriptSetupCount,
+    scriptSetupPercent: Math.round((scriptSetupCount / totalSfc) * 100),
+    tsCount,
+    tsPercent: Math.round((tsCount / totalSfc) * 100),
+    piniaCount,
+    vuexCount,
+    maturity
+  };
+}
+
+function summarizeDotnetMetrics(csprojResults, csharpResults) {
+  if (csprojResults.length === 0 && csharpResults.length === 0) return null;
+
+  const layerViolations = csprojResults.flatMap((r) => r.violations);
+  const minimalApiCount = csharpResults.filter((r) => r.isMinimalApi).length;
+  const controllerCount = csharpResults.filter((r) => r.isController).length;
+
+  return {
+    projectsCount: csprojResults.length,
+    csharpFilesCount: csharpResults.length,
+    minimalApiCount,
+    controllerCount,
+    layerViolations
+  };
+}
+
+function aggregateTokens(vueResults) {
+  const colorCounts = new Map();
+  const spacingCounts = new Map();
+
+  for (const r of vueResults) {
+    for (const color of r.tokens.hexColors) {
+      colorCounts.set(color, (colorCounts.get(color) || 0) + 1);
+    }
+    for (const spacing of r.tokens.spacing) {
+      spacingCounts.set(spacing, (spacingCounts.get(spacing) || 0) + 1);
+    }
+  }
+
+  const frequentColors = Array.from(colorCounts.entries())
+    .map(([color, count]) => ({ color, count }))
+    .sort((a, b) => b.count - a.count);
+
+  const frequentSpacing = Array.from(spacingCounts.entries())
+    .map(([spacing, count]) => ({ spacing, count }))
+    .sort((a, b) => b.count - a.count);
+
+  return { frequentColors, frequentSpacing };
+}
+
+function aggregateHotspots(vueResults, csprojResults) {
+  const hotspots = [];
+  for (const r of vueResults) {
+    for (const h of r.hotspots) {
+      hotspots.push({ file: path.basename(r.filePath), relativePath: r.filePath, ...h });
+    }
+  }
+  for (const p of csprojResults) {
+    for (const v of p.violations) {
+      hotspots.push({ file: path.basename(p.filePath), relativePath: p.filePath, ...v });
+    }
+  }
+  return hotspots;
+}
+
+function saveIndexFile(rootDir, report, artifactsDirName = 'artifacts') {
+  const targetDir = path.join(rootDir, artifactsDirName);
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+  }
+  const indexPath = path.join(targetDir, '.plankit-index.json');
+  fs.writeFileSync(indexPath, JSON.stringify(report, null, 2), 'utf8');
+}

package/src/analyzer/vueScanner.js

@@ -0,0 +1,200 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Fast static analyzer for Vue SFC (.vue) and JS/TS files.
+ * Uses lightweight block extraction and heuristic parsing without external dependencies.
+ */
+
+export function analyzeVueFile(filePath, content = null) {
+  const code = content !== null ? content : fs.readFileSync(filePath, 'utf8');
+  const lines = code.split(/\r?\n/);
+  const lineCount = lines.length;
+
+  const templateBlock = extractBlock(code, 'template');
+  const scriptBlock = extractBlock(code, 'script');
+  const styleBlocks = extractAllBlocks(code, 'style');
+
+  const isScriptSetup = /<script\s+[^>]*setup/i.test(code);
+  const hasScript = scriptBlock !== null || isScriptSetup;
+  const scriptContent = scriptBlock ? scriptBlock.content : '';
+  const scriptAttributes = scriptBlock ? scriptBlock.attributes : '';
+
+  // Language detection
+  const isTs = /lang=["'](?:ts|typescript)["']/i.test(code) ||
+    filePath.endsWith('.ts') ||
+    filePath.endsWith('.tsx');
+  const language = isTs ? 'ts' : 'js';
+
+  // Vue style detection (Options API, Composition API, or <script setup>)
+  let vueStyle = 'unknown';
+  if (isScriptSetup) {
+    vueStyle = 'script_setup';
+  } else if (hasScript) {
+    if (/\bsetup\s*\([^)]*\)\s*\{/i.test(scriptContent) || /\bdefineComponent\s*\(/i.test(scriptContent)) {
+      vueStyle = 'composition';
+    } else if (/\b(?:data\s*\(\)|methods\s*:|computed\s*:|watch\s*:)/i.test(scriptContent)) {
+      vueStyle = 'options';
+    } else {
+      vueStyle = 'transitional';
+    }
+  }
+
+  // State detection
+  const hasPinia = /\b(?:use\w+Store|defineStore)\b/i.test(code);
+  const hasVuex = /\b(?:this\.\$store|mapState|mapGetters|mapActions|mapMutations|createNamespacedHelpers)\b/i.test(code);
+  const hasComposable = /\buse(?!Store\b)\w+\s*\(/i.test(code);
+  const hasLocal = /\b(?:ref|reactive|shallowRef)\s*\(/i.test(code);
+
+  let state = 'local';
+  if (hasPinia && hasVuex) {
+    state = 'mixed';
+  } else if (hasPinia) {
+    state = 'pinia';
+  } else if (hasVuex) {
+    state = 'vuex';
+  } else if (hasComposable) {
+    state = 'composable';
+  } else if (hasLocal) {
+    state = 'local';
+  }
+
+  // Data access detection
+  let dataAccess = 'unknown';
+  if (/\baxios\.(?:get|post|put|delete|patch)\b/i.test(code)) {
+    dataAccess = 'axios_component';
+  } else if (/\buseQuery\b|\buseMutation\b/i.test(code)) {
+    dataAccess = 'query_library';
+  } else if (/\b(?:useFetch|\$fetch)\b/i.test(code)) {
+    dataAccess = 'fetch_composable';
+  } else if (/\b(?:api|service|client)\.\w+\b/i.test(code)) {
+    dataAccess = 'api_service';
+  }
+
+  // Styling analysis
+  const stylingTypes = new Set();
+  let hasScoped = false;
+  let hasGlobal = false;
+  for (const style of styleBlocks) {
+    const isScoped = /\bscoped\b/i.test(style.attributes);
+    const isModule = /\bmodule\b/i.test(style.attributes);
+    const isScss = /lang=["'](?:scss|sass)["']/i.test(style.attributes);
+
+    if (isModule) stylingTypes.add('modules');
+    if (isScoped) {
+      hasScoped = true;
+      stylingTypes.add(isScss ? 'scoped_scss' : 'scoped_css');
+    } else {
+      hasGlobal = true;
+      stylingTypes.add(isScss ? 'global_scss' : 'global_css');
+    }
+  }
+  if (templateBlock && /\bclass=["'][^"']*\b(?:flex|grid|p-|m-|text-|bg-|w-|h-)\b/i.test(templateBlock.content)) {
+    stylingTypes.add('utility');
+  }
+  const styling = stylingTypes.size > 0 ? Array.from(stylingTypes) : ['scoped_css'];
+
+  // Design token discovery (hex colors, font sizes, margins, padding)
+  const tokens = extractTokens(code);
+
+  // Anti-patterns and hotspots
+  const hotspots = [];
+  if (lineCount > 400) {
+    hotspots.push({ type: 'god_component', message: `Large SFC (${lineCount} lines)` });
+  }
+  if (/\b(?:this\.\$)/.test(code)) {
+    hotspots.push({ type: 'deprecated_global_property', message: 'Uses legacy this.$ properties' });
+  }
+  if (/::v-deep|>>>|\/deep\//.test(code)) {
+    hotspots.push({ type: 'deprecated_deep_selector', message: 'Uses deprecated deep CSS selector (::v-deep or /deep/)' });
+  }
+  if (/\bmixins\s*:\s*\[/i.test(code)) {
+    hotspots.push({ type: 'vue_mixins', message: 'Uses Vue mixins (replace with composables)' });
+  }
+  if (/\bfilters\s*:\s*\{/i.test(code)) {
+    hotspots.push({ type: 'vue_filters', message: 'Uses Vue 2 filters (not supported in Vue 3)' });
+  }
+  if (/\b\$on\b|\b\$emit\b.*eventBus|new\s+Vue\(\)/i.test(code)) {
+    hotspots.push({ type: 'event_bus', message: 'Uses global event bus' });
+  }
+
+  // Maturity classification
+  let maturity = 'preferred';
+  if (vueStyle === 'options' || hotspots.some((h) => h.type === 'vue_mixins' || h.type === 'vue_filters')) {
+    maturity = 'legacy';
+  } else if (vueStyle === 'composition' || language === 'js' || state === 'vuex' || hasGlobal) {
+    maturity = 'transitional';
+  } else if (vueStyle === 'script_setup' && language === 'ts') {
+    maturity = 'preferred';
+  }
+
+  return {
+    filePath,
+    fileName: path.basename(filePath),
+    lineCount,
+    language,
+    vueStyle,
+    state,
+    dataAccess,
+    styling,
+    hasScoped,
+    hasGlobal,
+    tokens,
+    hotspots,
+    maturity
+  };
+}
+
+function extractBlock(code, tag) {
+  const openRegex = new RegExp(`<${tag}(\\s+[^>]*)?>`, 'i');
+  const match = openRegex.exec(code);
+  if (!match) return null;
+
+  const startIndex = match.index + match[0].length;
+  const closeTag = `</${tag}>`;
+  const endIndex = code.indexOf(closeTag, startIndex);
+  if (endIndex === -1) {
+    return {
+      attributes: match[1] || '',
+      content: code.slice(startIndex)
+    };
+  }
+
+  return {
+    attributes: match[1] || '',
+    content: code.slice(startIndex, endIndex)
+  };
+}
+
+function extractAllBlocks(code, tag) {
+  const blocks = [];
+  const regex = new RegExp(`<${tag}(\\s+[^>]*)?>([\\s\\S]*?)<\\/${tag}>`, 'gi');
+  let match;
+  while ((match = regex.exec(code)) !== null) {
+    blocks.push({
+      attributes: match[1] || '',
+      content: match[2]
+    });
+  }
+  return blocks;
+}
+
+function extractTokens(code) {
+  const hexColors = new Set();
+  const hexRegex = /#([0-9a-fA-F]{6}|[0-9a-fA-F]{3})\b/g;
+  let match;
+  while ((match = hexRegex.exec(code)) !== null) {
+    hexColors.add(match[0].toLowerCase());
+  }
+
+  const spacingValues = new Set();
+  const spacingRegex = /(?:margin|padding|gap|top|bottom|left|right):\s*([0-9]+(?:px|rem|em))/gi;
+  while ((match = spacingRegex.exec(code)) !== null) {
+    spacingValues.add(match[1].toLowerCase());
+  }
+
+  return {
+    hexColors: Array.from(hexColors),
+    spacing: Array.from(spacingValues)
+  };
+}

package/src/cli.js

@@ -23,6 +23,8 @@ import {
   normalizeFramework,
   parseFrameworksInput
 } from './commandBundles.js';
+import { runAnalysis, formatReport } from './analyzer/engine.js';
+import { loadDashboardData, renderStaticDashboard, runInteractiveDashboard } from './dashboard/dashboard.js';
 
 export async function runCli(args, context = {}) {
   const io = createIo(context);
@@ -50,6 +52,15 @@ export async function runCli(args, context = {}) {
       case 'status':
         showStatus(parsed, io);
         break;
+      case 'scan':
+      case 'health':
+      case 'audit':
+        await scanRepository(parsed, io);
+        break;
+      case 'ui':
+      case 'dashboard':
+        await showDashboard(parsed, io);
+        break;
       case 'archive':
         archiveFeature(parsed, io);
         break;
@@ -365,6 +376,49 @@ function archiveFeature(parsed, io) {
   io.stdout(`Feature "${featureName}" archived.`);
 }
 
+async function scanRepository(parsed, io) {
+  const { config } = loadConfig(io.cwd);
+  const targetDir = parsed.positionals[0] ? path.resolve(io.cwd, parsed.positionals[0]) : io.cwd;
+  const report = await runAnalysis(targetDir, {
+    artifactsDir: config.artifactsDir
+  });
+
+  if (parsed.flags.json) {
+    io.stdout(JSON.stringify(report, null, 2));
+  } else {
+    io.stdout(formatReport(report, io.isTTY));
+  }
+
+  if (parsed.flags.threshold) {
+    const threshold = Number.parseInt(parsed.flags.threshold, 10);
+    if (Number.isInteger(threshold) && report.score.total < threshold) {
+      throw new Error(`Health score ${report.score.total} is below required threshold ${threshold}`);
+    }
+  }
+}
+
+async function showDashboard(parsed, io) {
+  const { config } = loadConfig(io.cwd);
+  const data = loadDashboardData(io.cwd, config);
+
+  if (!io.isTTY || parsed.flags['no-tui']) {
+    renderStaticDashboard(data, io);
+    return;
+  }
+
+  await runInteractiveDashboard(io.cwd, io, config, {
+    implement: async (featureName, phaseNum) => {
+      prepareImplementation({ positionals: [featureName, String(phaseNum)], flags: {} }, io);
+    },
+    clarify: async (featureName) => {
+      clarifyFeature({ positionals: [featureName], flags: {} }, io);
+    },
+    review: async (featureName) => {
+      reviewFeature({ positionals: [featureName], flags: { 'skip-test': true, 'skip-build': true } }, io);
+    }
+  });
+}
+
 function moveFeatureToArchive(cwd, config, featureName, dryRun = false) {
   const sourceDir = requireFeatureDir(cwd, config, featureName);
   const targetDir = safeJoin(cwd, config.artifactsDir, 'archived', featureName);
@@ -734,6 +788,8 @@ Commands:
   implement <feature> <phase>       Validate phase context and prepare phase output artifact
   review <feature>                  Run verification and archive a completed feature
   status [--json]                   Show active and archived features
+  scan [dir]                        Run static analysis and generate artifacts/.plankit-index.json
+  ui                                Launch interactive feature progress dashboard
   archive <feature>                 Move a feature to archived without running verification
   version                          Show the installed PlankKit CLI version
   help                              Show this help message
@@ -746,6 +802,9 @@ Options:
   --framework <name>                Select framework command suite during init
                                     (angular, vue, dotnet, none, all; default: none)
   --frameworks <list>               Comma-separated list of framework suites during init
+  --threshold <score>               Fail scan if health score is below threshold
+  --json                            Output scan report or status as JSON
+  --no-tui                          Render static summary table instead of interactive dashboard
   --global-gemini-skills            Also install Gemini skills under the user profile
   --phases 3                        Generate N default phases during plan
   --phases "Design,Build,Test"      Generate named phases during plan

package/src/dashboard/dashboard.js

@@ -0,0 +1,272 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { listDirectories, safeJoin } from '../config.js';
+import { runAnalysis, formatReport } from '../analyzer/engine.js';
+
+export function loadDashboardData(cwd, config) {
+  const artifactsDir = safeJoin(cwd, config.artifactsDir || 'artifacts');
+  const currentDir = path.join(artifactsDir, 'current');
+  const archivedDir = path.join(artifactsDir, 'archived');
+
+  const activeNames = listDirectories(currentDir);
+  const archivedNames = listDirectories(archivedDir);
+
+  const activeFeatures = activeNames.map((name) => {
+    const featureDir = path.join(currentDir, name);
+    const phasesDir = path.join(featureDir, 'phases');
+    const outputsDir = path.join(featureDir, 'outputs');
+
+    const phaseFiles = fs.existsSync(phasesDir)
+      ? fs.readdirSync(phasesDir).filter((f) => f.startsWith('phase-') && f.endsWith('.md')).sort()
+      : [];
+    const outputFiles = fs.existsSync(outputsDir)
+      ? fs.readdirSync(outputsDir).filter((f) => f.startsWith('phase-') && f.endsWith('.md')).sort()
+      : [];
+
+    let state = null;
+    const stateFile = path.join(featureDir, 'plankit.json');
+    if (fs.existsSync(stateFile)) {
+      try {
+        state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+      } catch {
+        state = null;
+      }
+    }
+
+    const phases = phaseFiles.map((pf, idx) => {
+      const num = idx + 1;
+      const expectedOutput = `phase-${num}-output.md`;
+      const hasOutput = outputFiles.includes(expectedOutput);
+      return {
+        number: num,
+        specFile: pf,
+        hasOutput,
+        status: hasOutput ? 'DONE' : (num === outputFiles.length + 1 ? 'IN_PROGRESS' : 'PENDING')
+      };
+    });
+
+    const completedCount = phases.filter((p) => p.hasOutput).length;
+    const totalCount = phases.length || 1;
+    const progressPercent = Math.round((completedCount / totalCount) * 100);
+
+    return {
+      name,
+      phases,
+      phaseCount: phases.length,
+      completedCount,
+      progressPercent,
+      state
+    };
+  });
+
+  return {
+    activeFeatures,
+    archivedCount: archivedNames.length,
+    archivedNames
+  };
+}
+
+export function renderStaticDashboard(data, io) {
+  io.stdout('================================================================');
+  io.stdout('               PlanKit Feature Management Matrix               ');
+  io.stdout('================================================================');
+  io.stdout(`Active Features: ${data.activeFeatures.length} | Archived Features: ${data.archivedCount}`);
+  io.stdout('');
+
+  if (data.activeFeatures.length === 0) {
+    io.stdout('  No active features found in artifacts/current/.');
+    io.stdout('  Run "plankit plan <feature-name>" to start a feature.');
+    io.stdout('================================================================');
+    return;
+  }
+
+  io.stdout(padRight('Feature Name', 25) + padRight('Phases', 12) + padRight('Progress', 20) + 'Status');
+  io.stdout('-'.repeat(64));
+
+  data.activeFeatures.forEach((feat) => {
+    const progressText = `${progressBar(feat.progressPercent, 10)} ${feat.progressPercent}%`;
+    const statusText = feat.completedCount === feat.phaseCount ? 'READY_FOR_REVIEW' : `PHASE_${feat.completedCount + 1}`;
+    io.stdout(padRight(feat.name, 25) + padRight(`${feat.completedCount}/${feat.phaseCount}`, 12) + padRight(progressText, 20) + statusText);
+
+    feat.phases.forEach((p) => {
+      const check = p.hasOutput ? '[x]' : '[ ]';
+      io.stdout(`    ${check} Phase ${p.number}: ${p.specFile} (${p.status})`);
+    });
+    io.stdout('');
+  });
+
+  io.stdout('================================================================');
+}
+
+export async function runInteractiveDashboard(cwd, io, config, handlers = {}) {
+  const isTTY = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const data = loadDashboardData(cwd, config);
+
+  if (!isTTY) {
+    renderStaticDashboard(data, io);
+    return;
+  }
+
+  let selectedIndex = 0;
+  let statusMessage = 'Use [↑/↓] or [j/k] to navigate. Press [q] to exit.';
+
+  function refresh() {
+    const freshData = loadDashboardData(cwd, config);
+    console.clear();
+    console.log('\x1b[1m================================================================\x1b[0m');
+    console.log('\x1b[1m\x1b[36m             PlanKit Interactive Feature Dashboard             \x1b[0m');
+    console.log('\x1b[1m================================================================\x1b[0m');
+    console.log(`Active Features: \x1b[32m${freshData.activeFeatures.length}\x1b[0m | Archived Features: \x1b[33m${freshData.archivedCount}\x1b[0m`);
+    console.log('');
+
+    if (freshData.activeFeatures.length === 0) {
+      console.log('  No active features in artifacts/current/.');
+      console.log('  Press [p] to plan a new feature, or [q] to exit.');
+      console.log('\x1b[1m================================================================\x1b[0m');
+      console.log(`Status: ${statusMessage}`);
+      return;
+    }
+
+    if (selectedIndex >= freshData.activeFeatures.length) {
+      selectedIndex = freshData.activeFeatures.length - 1;
+    }
+
+    freshData.activeFeatures.forEach((feat, index) => {
+      const isSelected = index === selectedIndex;
+      const pointer = isSelected ? '\x1b[36m▶ \x1b[0m' : '  ';
+      const nameFmt = isSelected ? `\x1b[1m\x1b[36m${padRight(feat.name, 22)}\x1b[0m` : padRight(feat.name, 22);
+      const progress = `${progressBar(feat.progressPercent, 10)} ${feat.progressPercent}%`;
+      console.log(`${pointer}${nameFmt} ${padRight(progress, 18)} (${feat.completedCount}/${feat.phaseCount} phases)`);
+    });
+
+    console.log('');
+    const selectedFeature = freshData.activeFeatures[selectedIndex];
+    if (selectedFeature) {
+      console.log(`\x1b[1mPhase Breakdown for "${selectedFeature.name}":\x1b[0m`);
+      selectedFeature.phases.forEach((p) => {
+        const badge = p.hasOutput ? '\x1b[32m[COMPLETED]\x1b[0m' : '\x1b[33m[PENDING]\x1b[0m';
+        console.log(`  Phase ${p.number}: ${padRight(p.specFile, 32)} ${badge}`);
+      });
+    }
+
+    console.log('');
+    console.log('\x1b[1m----------------------------------------------------------------\x1b[0m');
+    console.log('\x1b[2mActions: [i] Implement Next Phase | [c] Clarify | [r] Review | [s] Scan | [q] Quit\x1b[0m');
+    console.log(`\x1b[33m${statusMessage}\x1b[0m`);
+  }
+
+  return new Promise((resolve) => {
+    readline.emitKeypressEvents(process.stdin);
+    if (process.stdin.setRawMode) {
+      process.stdin.setRawMode(true);
+    }
+    process.stdin.resume();
+
+    refresh();
+
+    const onKeypress = async (str, key) => {
+      if ((key && key.ctrl && key.name === 'c') || (key && key.name === 'q')) {
+        cleanup();
+        console.clear();
+        io.stdout('Exited PlanKit Dashboard.');
+        resolve();
+        return;
+      }
+
+      const freshData = loadDashboardData(cwd, config);
+      const currentFeature = freshData.activeFeatures[selectedIndex];
+
+      if (key && (key.name === 'up' || key.name === 'k')) {
+        if (selectedIndex > 0) selectedIndex -= 1;
+        statusMessage = `Selected ${freshData.activeFeatures[selectedIndex]?.name || ''}`;
+        refresh();
+      } else if (key && (key.name === 'down' || key.name === 'j')) {
+        if (selectedIndex < freshData.activeFeatures.length - 1) selectedIndex += 1;
+        statusMessage = `Selected ${freshData.activeFeatures[selectedIndex]?.name || ''}`;
+        refresh();
+      } else if (str === 's') {
+        cleanup();
+        console.clear();
+        io.stdout('Running PlanKit Static Analysis...\n');
+        const report = await runAnalysis(cwd, { artifactsDir: config.artifactsDir });
+        io.stdout(formatReport(report, true));
+        io.stdout('\nPress any key to return to dashboard...');
+        process.stdin.once('data', () => {
+          readline.emitKeypressEvents(process.stdin);
+          if (process.stdin.setRawMode) process.stdin.setRawMode(true);
+          process.stdin.resume();
+          process.stdin.on('keypress', onKeypress);
+          statusMessage = 'Completed static analysis scan.';
+          refresh();
+        });
+      } else if (str === 'i' && currentFeature && handlers.implement) {
+        const nextPhase = currentFeature.completedCount + 1;
+        if (nextPhase > currentFeature.phaseCount) {
+          statusMessage = `Feature "${currentFeature.name}" has completed all phases! Press [r] to review.`;
+          refresh();
+        } else {
+          cleanup();
+          console.clear();
+          io.stdout(`Preparing Phase ${nextPhase} for "${currentFeature.name}"...\n`);
+          try {
+            await handlers.implement(currentFeature.name, nextPhase);
+            statusMessage = `Phase ${nextPhase} prepared successfully for "${currentFeature.name}".`;
+          } catch (err) {
+            statusMessage = `Error: ${err.message}`;
+          }
+          resume();
+        }
+      } else if (str === 'c' && currentFeature && handlers.clarify) {
+        cleanup();
+        console.clear();
+        try {
+          await handlers.clarify(currentFeature.name);
+          statusMessage = `Clarifications prepared for "${currentFeature.name}".`;
+        } catch (err) {
+          statusMessage = `Error: ${err.message}`;
+        }
+        resume();
+      } else if (str === 'r' && currentFeature && handlers.review) {
+        cleanup();
+        console.clear();
+        try {
+          await handlers.review(currentFeature.name);
+          statusMessage = `Feature "${currentFeature.name}" reviewed and archived.`;
+        } catch (err) {
+          statusMessage = `Review error: ${err.message}`;
+        }
+        resume();
+      }
+    };
+
+    function cleanup() {
+      process.stdin.removeListener('keypress', onKeypress);
+      if (process.stdin.setRawMode) {
+        process.stdin.setRawMode(false);
+      }
+    }
+
+    function resume() {
+      readline.emitKeypressEvents(process.stdin);
+      if (process.stdin.setRawMode) {
+        process.stdin.setRawMode(true);
+      }
+      process.stdin.resume();
+      process.stdin.on('keypress', onKeypress);
+      refresh();
+    }
+
+    process.stdin.on('keypress', onKeypress);
+  });
+}
+
+function progressBar(percent, length = 10) {
+  const filled = Math.round((percent / 100) * length);
+  const empty = length - filled;
+  return `[${'='.repeat(filled)}${'-'.repeat(empty)}]`;
+}
+
+function padRight(str, len) {
+  return String(str).padEnd(len, ' ');
+}