@harness-engineering/cli 1.21.0 → 1.22.0

package/dist/{chunk-UEKQ5G3V.js → chunk-SOTTK27D.js}

@@ -1,3 +1,6 @@
+import {
+  generateAgentsMd
+} from "./chunk-OD3S2NHN.js";
 import {
   generateCIWorkflow
 } from "./chunk-SD3SQOZ2.js";
@@ -6,11 +9,14 @@ import {
   OutputMode,
   createCheckPhaseGateCommand,
   findFiles
-} from "./chunk-7G2ZUTZA.js";
+} from "./chunk-PUOMFNRO.js";
 import {
   createGenerateAgentDefinitionsCommand,
   generateAgentDefinitions
 } from "./chunk-6KWBH4EO.js";
+import {
+  TemplateEngine
+} from "./chunk-YLN34N65.js";
 import {
   listPersonas,
   loadPersona
@@ -20,13 +26,13 @@ import {
 } from "./chunk-TRAPF4IX.js";
 import {
   executeSkill
-} from "./chunk-M6TIO6NF.js";
+} from "./chunk-2PAPHA77.js";
 import {
   ALLOWED_PERSONA_COMMANDS
 } from "./chunk-TEFCFC4H.js";
 import {
   createCreateSkillCommand
-} from "./chunk-LRG3B43J.js";
+} from "./chunk-T5QWCVGK.js";
 import {
   logger
 } from "./chunk-EBJQ6N4M.js";
@@ -40,24 +46,26 @@ import {
 import {
   toKebabCase
 } from "./chunk-KET4QQZB.js";
-import {
-  generateAgentsMd
-} from "./chunk-OD3S2NHN.js";
 import {
   appendFrameworkAgents,
+  captureHealthSnapshot,
   createGenerateSlashCommandsCommand,
   generateSlashCommands,
   handleGetImpact,
   handleOrphanDeletion,
-  persistToolingConfig
-} from "./chunk-TMSGI27F.js";
+  isSnapshotFresh,
+  loadCachedSnapshot,
+  loadOrRebuildIndex,
+  persistToolingConfig,
+  recommend
+} from "./chunk-DJEBBENF.js";
 import {
   VALID_PLATFORMS
 } from "./chunk-CJDVBBPB.js";
 import {
   findConfigFile,
   resolveConfig
-} from "./chunk-SZ5TGZMI.js";
+} from "./chunk-GRJ7A4WT.js";
 import {
   resolveGlobalSkillsDir,
   resolvePersonasDir,
@@ -72,13 +80,10 @@ import {
 } from "./chunk-3WGJMBKH.js";
 import {
   SkillMetadataSchema
-} from "./chunk-HKUX2X7O.js";
+} from "./chunk-SE4YPMLH.js";
 import {
   CLI_VERSION
 } from "./chunk-BM3PWGXQ.js";
-import {
-  TemplateEngine
-} from "./chunk-YLN34N65.js";
 import {
   ArchBaselineManager,
   ArchConfigSchema,
@@ -87,8 +92,11 @@ import {
   BundleSchema,
   CriticalPathResolver,
   EntropyAnalyzer,
+  PredictionEngine,
   ProjectScanner,
   SecurityScanner,
+  SpecImpactEstimator,
+  TimelineManager,
   TypeScriptParser,
   addProvenance,
   appendLearning,
@@ -135,14 +143,14 @@ import {
   validateKnowledgeMap,
   writeConfig,
   writeLockfile
-} from "./chunk-YZYBQZVL.js";
+} from "./chunk-U44JNY3Y.js";
 import {
   Err,
   Ok
 } from "./chunk-ERS5EVUZ.js";
 
 // src/index.ts
-import { Command as Command70 } from "commander";
+import { Command as Command73 } from "commander";
 
 // src/commands/validate.ts
 import { Command } from "commander";
@@ -221,7 +229,7 @@ function createValidateCommand() {
       process.exit(result.error.exitCode);
     }
     if (opts.crossCheck) {
-      const { runCrossCheck: runCrossCheck2 } = await import("./validate-cross-check-PFRKABCS.js");
+      const { runCrossCheck: runCrossCheck2 } = await import("./validate-cross-check-VX2BAHQI.js");
       const cwd = process.cwd();
       const specsDir = path.join(cwd, "docs", "specs");
       const plansDir = path.join(cwd, "docs", "plans");
@@ -578,7 +586,7 @@ function registerBenchCommand(perf) {
   perf.command("bench [glob]").description("Run benchmarks via vitest bench").action(async (glob, _opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const cwd = process.cwd();
-    const { BenchmarkRunner } = await import("./dist-KV2ICL5X.js");
+    const { BenchmarkRunner } = await import("./dist-LCR2IO7U.js");
     const runner = new BenchmarkRunner();
     const benchFiles = runner.discover(cwd, glob);
     if (benchFiles.length === 0) {
@@ -646,7 +654,7 @@ function registerBaselinesCommands(perf) {
   baselines.command("update").description("Update baselines from latest benchmark run").action(async (_opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const cwd = process.cwd();
-    const { BenchmarkRunner } = await import("./dist-KV2ICL5X.js");
+    const { BenchmarkRunner } = await import("./dist-LCR2IO7U.js");
     const runner = new BenchmarkRunner();
     const manager = new BaselineManager(cwd);
     logger.info("Running benchmarks to update baselines...");
@@ -669,8 +677,8 @@ function registerBaselinesCommands(perf) {
 }
 async function getCommitHash(cwd) {
   try {
-    const { execSync: execSync5 } = await import("child_process");
-    return execSync5("git rev-parse --short HEAD", { cwd, encoding: "utf-8" }).trim();
+    const { execSync: execSync6 } = await import("child_process");
+    return execSync6("git rev-parse --short HEAD", { cwd, encoding: "utf-8" }).trim();
   } catch {
     return "unknown";
   }
@@ -679,7 +687,7 @@ function registerReportCommand(perf) {
   perf.command("report").description("Full performance report with metrics, trends, and hotspots").action(async (_opts, cmd) => {
     const globalOpts = cmd.optsWithGlobals();
     const cwd = process.cwd();
-    const { EntropyAnalyzer: EntropyAnalyzer2 } = await import("./dist-KV2ICL5X.js");
+    const { EntropyAnalyzer: EntropyAnalyzer2 } = await import("./dist-LCR2IO7U.js");
     const analyzer = new EntropyAnalyzer2({
       rootDir: path5.resolve(cwd),
       analyze: { complexity: true, coupling: true }
@@ -1060,7 +1068,11 @@ var ALL_MCP_TOOLS = [
   "search_skills",
   "code_outline",
   "code_search",
-  "code_unfold"
+  "code_unfold",
+  "get_decay_trends",
+  "check_traceability",
+  "predict_failures",
+  "recommend_skills"
 ];
 async function runCursorToolPicker() {
   try {
@@ -1975,7 +1987,7 @@ async function runAdd(componentType, name, options) {
         break;
       }
       case "skill": {
-        const { generateSkillFiles: generateSkillFiles2 } = await import("./create-skill-NDXQSTIK.js");
+        const { generateSkillFiles: generateSkillFiles2 } = await import("./create-skill-U3XCFRZN.js");
         generateSkillFiles2({
           name,
           description: `${name} skill`,
@@ -3987,7 +3999,8 @@ var VALID_CHECKS = [
   "security",
   "perf",
   "phase-gate",
-  "arch"
+  "arch",
+  "traceability"
 ];
 async function runCICheck(options) {
   const configResult = resolveConfig(options.configPath);
@@ -4073,7 +4086,8 @@ var ALL_CHECKS = [
   "security",
   "perf",
   "phase-gate",
-  "arch"
+  "arch",
+  "traceability"
 ];
 function buildSkipFlag(checks) {
   if (!checks) return "";
@@ -4753,7 +4767,7 @@ function createGenerateCommand3() {
 import { Command as Command46 } from "commander";
 import * as path38 from "path";
 async function runScan(projectPath) {
-  const { GraphStore, CodeIngestor, TopologicalLinker, KnowledgeIngestor, GitIngestor } = await import("./dist-U7EAO6T2.js");
+  const { GraphStore, CodeIngestor, TopologicalLinker, KnowledgeIngestor, GitIngestor } = await import("./dist-IA6XYKNO.js");
   const store = new GraphStore();
   const start = Date.now();
   await new CodeIngestor(store).ingest(projectPath);
@@ -4834,7 +4848,7 @@ async function runIngest(projectPath, source, opts) {
     SyncManager,
     JiraConnector,
     SlackConnector
-  } = await import("./dist-U7EAO6T2.js");
+  } = await import("./dist-IA6XYKNO.js");
   const graphDir = path39.join(projectPath, ".harness", "graph");
   const store = new GraphStore();
   await store.load(graphDir);
@@ -4927,7 +4941,7 @@ function createIngestCommand() {
 import { Command as Command48 } from "commander";
 import * as path40 from "path";
 async function runQuery(projectPath, rootNodeId, opts) {
-  const { GraphStore, ContextQL } = await import("./dist-U7EAO6T2.js");
+  const { GraphStore, ContextQL } = await import("./dist-IA6XYKNO.js");
   const store = new GraphStore();
   const graphDir = path40.join(projectPath, ".harness", "graph");
   const loaded = await store.load(graphDir);
@@ -4976,7 +4990,7 @@ import { Command as Command49 } from "commander";
 // src/commands/graph/status.ts
 import * as path41 from "path";
 async function runGraphStatus(projectPath) {
-  const { GraphStore } = await import("./dist-U7EAO6T2.js");
+  const { GraphStore } = await import("./dist-IA6XYKNO.js");
   const graphDir = path41.join(projectPath, ".harness", "graph");
   const store = new GraphStore();
   const loaded = await store.load(graphDir);
@@ -5016,7 +5030,7 @@ async function runGraphStatus(projectPath) {
 // src/commands/graph/export.ts
 import * as path42 from "path";
 async function runGraphExport(projectPath, format) {
-  const { GraphStore } = await import("./dist-U7EAO6T2.js");
+  const { GraphStore } = await import("./dist-IA6XYKNO.js");
   const graphDir = path42.join(projectPath, ".harness", "graph");
   const store = new GraphStore();
   const loaded = await store.load(graphDir);
@@ -5095,7 +5109,7 @@ function createGraphCommand() {
 import { Command as Command50 } from "commander";
 function createMcpCommand() {
   return new Command50("mcp").description("Start the MCP (Model Context Protocol) server on stdio").option("--tools <tools...>", "Only register the specified tools (used by Cursor integration)").action(async (opts) => {
-    const { startServer: startServer2 } = await import("./mcp-DF25USTE.js");
+    const { startServer: startServer2 } = await import("./mcp-LWHVQRG7.js");
     await startServer2(opts.tools);
   });
 }
@@ -6594,7 +6608,7 @@ function createIntegrationsCommand() {
 // src/commands/usage.ts
 import { Command as Command67 } from "commander";
 async function loadAndPriceRecords(cwd, includeClaudeSessions = false) {
-  const { readCostRecords, loadPricingData, calculateCost, parseCCRecords } = await import("./dist-KV2ICL5X.js");
+  const { readCostRecords, loadPricingData, calculateCost, parseCCRecords } = await import("./dist-LCR2IO7U.js");
   const records = readCostRecords(cwd);
   if (includeClaudeSessions) {
     const ccRecords = parseCCRecords();
@@ -6638,7 +6652,7 @@ function registerDailyCommand(usage) {
       }
       return;
     }
-    const { aggregateByDay } = await import("./dist-KV2ICL5X.js");
+    const { aggregateByDay } = await import("./dist-LCR2IO7U.js");
     const dailyData = aggregateByDay(records);
     const limited = dailyData.slice(0, days);
     if (globalOpts.json) {
@@ -6674,7 +6688,7 @@ function registerSessionsCommand(usage) {
       }
       return;
     }
-    const { aggregateBySession } = await import("./dist-KV2ICL5X.js");
+    const { aggregateBySession } = await import("./dist-LCR2IO7U.js");
     const sessionData = aggregateBySession(records);
     const limited = sessionData.slice(0, limit);
     if (globalOpts.json) {
@@ -6703,7 +6717,7 @@ function registerSessionCommand(usage) {
     const globalOpts = cmd.optsWithGlobals();
     const cwd = process.cwd();
     const records = await loadAndPriceRecords(cwd, globalOpts.includeClaudeSessions);
-    const { aggregateBySession } = await import("./dist-KV2ICL5X.js");
+    const { aggregateBySession } = await import("./dist-LCR2IO7U.js");
     const sessionData = aggregateBySession(records);
     const match = sessionData.find((s) => s.sessionId === id);
     if (!match) {
@@ -6769,7 +6783,7 @@ function registerLatestCommand(usage) {
       }
       return;
     }
-    const { aggregateBySession } = await import("./dist-KV2ICL5X.js");
+    const { aggregateBySession } = await import("./dist-LCR2IO7U.js");
     const sessionData = aggregateBySession(records);
     const latest = sessionData[0];
     if (!latest) {
@@ -6986,9 +7000,413 @@ function createScanConfigCommand() {
   return command;
 }
 
+// src/commands/snapshot.ts
+import { Command as Command70 } from "commander";
+import { execSync as execSync5 } from "child_process";
+import chalk8 from "chalk";
+function getCommitHash3(cwd) {
+  try {
+    return execSync5("git rev-parse --short HEAD", { cwd, encoding: "utf-8" }).toString().trim();
+  } catch {
+    return "unknown";
+  }
+}
+function resolveArchConfig(configPath) {
+  const configResult = resolveConfig(configPath);
+  if (!configResult.ok) {
+    return { error: configResult.error };
+  }
+  const archConfig = configResult.value.architecture ?? ArchConfigSchema.parse({});
+  return { archConfig };
+}
+function formatDelta(delta) {
+  if (delta === 0) return "0";
+  const sign = delta > 0 ? "+" : "";
+  const formatted = Number.isInteger(delta) ? String(delta) : delta.toFixed(2).replace(/\.?0+$/, "");
+  return `${sign}${formatted}`;
+}
+function directionSymbol(direction) {
+  switch (direction) {
+    case "improving":
+      return chalk8.green("improving");
+    case "declining":
+      return chalk8.red("declining");
+    case "stable":
+      return "=";
+  }
+}
+var CATEGORY_ORDER = [
+  "circular-deps",
+  "layer-violations",
+  "complexity",
+  "coupling",
+  "forbidden-imports",
+  "module-size",
+  "dependency-depth"
+];
+async function runSnapshotCapture(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const resolved = resolveArchConfig(options.configPath);
+  if (resolved.error) {
+    throw resolved.error;
+  }
+  const manager = new TimelineManager(cwd);
+  const timelineBefore = manager.load();
+  const previous = timelineBefore.snapshots.length > 0 ? timelineBefore.snapshots[timelineBefore.snapshots.length - 1] : void 0;
+  const results = await runAll(resolved.archConfig, cwd);
+  const commitHash = getCommitHash3(cwd);
+  const snapshot = manager.capture(results, commitHash);
+  return { snapshot, previous };
+}
+function printCaptureSummary(snapshot, previous) {
+  const date = snapshot.capturedAt.slice(0, 10);
+  const commit = snapshot.commitHash.slice(0, 7);
+  console.log("");
+  console.log(`Architecture Snapshot captured (${date}, ${commit})`);
+  console.log("");
+  const stabilityDelta = previous ? ` (${formatDelta(snapshot.stabilityScore - previous.stabilityScore)} from last)` : "";
+  console.log(`  Stability: ${snapshot.stabilityScore}/100${stabilityDelta}`);
+  console.log("");
+  const header = "  Category".padEnd(22) + "Value".padStart(7) + "Delta".padStart(8) + "   Trend";
+  console.log(header);
+  for (const category of CATEGORY_ORDER) {
+    const current = snapshot.metrics[category];
+    const prev = previous?.metrics[category];
+    const value = current?.value ?? 0;
+    const delta = prev ? value - prev.value : 0;
+    const valueFmt = Number.isInteger(value) ? String(value) : value.toFixed(2);
+    const deltaFmt = formatDelta(delta);
+    const direction = Math.abs(delta) < 2 ? "stable" : delta < 0 ? "improving" : "declining";
+    const line = `  ${category.padEnd(20)}${valueFmt.padStart(7)}${deltaFmt.padStart(8)}    ${directionSymbol(direction)}`;
+    console.log(line);
+  }
+  console.log("");
+}
+function printTrendsSummary(trends) {
+  if (trends.snapshotCount === 0) {
+    logger.warn("No snapshots found. Run `harness snapshot capture` first.");
+    return;
+  }
+  const fromDate = trends.from.slice(0, 10);
+  const toDate = trends.to.slice(0, 10);
+  console.log("");
+  console.log(`Architecture Trends (${trends.snapshotCount} snapshots, ${fromDate} to ${toDate})`);
+  console.log("");
+  const stabilityDelta = formatDelta(trends.stability.delta);
+  console.log(
+    `  Stability: ${trends.stability.current}/100 (was ${trends.stability.previous} on ${fromDate}, ${stabilityDelta})`
+  );
+  console.log("");
+  const header = "  Category".padEnd(22) + "Current".padStart(9) + "Start".padStart(9) + "Delta".padStart(9) + "   Trend";
+  console.log(header);
+  for (const category of CATEGORY_ORDER) {
+    const trend = trends.categories[category];
+    if (!trend) continue;
+    const currentFmt = Number.isInteger(trend.current) ? String(trend.current) : trend.current.toFixed(2);
+    const prevFmt = Number.isInteger(trend.previous) ? String(trend.previous) : trend.previous.toFixed(2);
+    const deltaFmt = formatDelta(trend.delta);
+    const line = `  ${category.padEnd(20)}${currentFmt.padStart(9)}${prevFmt.padStart(9)}${deltaFmt.padStart(9)}    ${directionSymbol(trend.direction)}`;
+    console.log(line);
+  }
+  console.log("");
+}
+function printSnapshotList(manager) {
+  const timeline = manager.load();
+  if (timeline.snapshots.length === 0) {
+    logger.warn("No snapshots found. Run `harness snapshot capture` first.");
+    return;
+  }
+  console.log("");
+  console.log(`Architecture Snapshots (${timeline.snapshots.length} total)`);
+  console.log("");
+  const header = "  #".padEnd(6) + "Date".padEnd(14) + "Commit".padEnd(12) + "Stability";
+  console.log(header);
+  timeline.snapshots.forEach((snap, idx) => {
+    const date = snap.capturedAt.slice(0, 10);
+    const commit = snap.commitHash.slice(0, 7);
+    const num = String(idx + 1);
+    const line = `  ${num.padEnd(4)}${date.padEnd(14)}${commit.padEnd(12)}${snap.stabilityScore}/100`;
+    console.log(line);
+  });
+  console.log("");
+}
+function createSnapshotCommand() {
+  const command = new Command70("snapshot").description("Architecture timeline snapshot commands");
+  command.command("capture").description("Capture current architecture metrics as a timeline snapshot").action(async (_opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const mode = globalOpts.json ? OutputMode.JSON : OutputMode.TEXT;
+    try {
+      const { snapshot, previous } = await runSnapshotCapture({
+        configPath: globalOpts.config
+      });
+      if (mode === OutputMode.JSON) {
+        console.log(JSON.stringify({ snapshot, previous: previous ?? null }, null, 2));
+      } else {
+        printCaptureSummary(snapshot, previous);
+      }
+    } catch (err) {
+      if (err instanceof CLIError) {
+        if (mode === OutputMode.JSON) {
+          console.log(JSON.stringify({ error: err.message }));
+        } else {
+          logger.error(err.message);
+        }
+        process.exit(err.exitCode);
+      }
+      throw err;
+    }
+  });
+  command.command("trends").description("Show architecture metric trends over time").option("--last <n>", "Number of recent snapshots to analyze", "10").option("--since <date>", "Show trends since ISO date").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const mode = globalOpts.json ? OutputMode.JSON : OutputMode.TEXT;
+    const cwd = process.cwd();
+    const manager = new TimelineManager(cwd);
+    const trends = manager.trends({
+      last: parseInt(opts.last, 10),
+      since: opts.since
+    });
+    if (mode === OutputMode.JSON) {
+      console.log(JSON.stringify(trends, null, 2));
+    } else {
+      printTrendsSummary(trends);
+    }
+  });
+  command.command("list").description("List all captured architecture snapshots").action(async (_opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const mode = globalOpts.json ? OutputMode.JSON : OutputMode.TEXT;
+    const cwd = process.cwd();
+    const manager = new TimelineManager(cwd);
+    if (mode === OutputMode.JSON) {
+      const timeline = manager.load();
+      console.log(JSON.stringify(timeline, null, 2));
+    } else {
+      printSnapshotList(manager);
+    }
+  });
+  return command;
+}
+
+// src/commands/predict.ts
+import { Command as Command71 } from "commander";
+import chalk9 from "chalk";
+var CATEGORY_ORDER2 = [
+  "circular-deps",
+  "layer-violations",
+  "complexity",
+  "coupling",
+  "forbidden-imports",
+  "module-size",
+  "dependency-depth"
+];
+function formatValue(value) {
+  if (Number.isInteger(value)) return String(value);
+  return value.toFixed(2);
+}
+function crossingLabel(weeks) {
+  if (weeks === null || weeks <= 0) return "--";
+  return `~${Math.round(weeks)} weeks`;
+}
+function severityPrefix(severity) {
+  switch (severity) {
+    case "critical":
+      return chalk9.red("[critical]");
+    case "warning":
+      return chalk9.yellow("[warning]");
+    case "info":
+      return chalk9.blue("[info]");
+  }
+}
+function printPredictionReport(result) {
+  const sf = result.stabilityForecast;
+  const horizonWeeks = 12;
+  console.log("");
+  console.log(
+    `Architecture Prediction (${horizonWeeks}-week horizon, ${result.snapshotsUsed} snapshots)`
+  );
+  console.log("");
+  console.log(
+    `  Stability: ${sf.current}/100 -> projected ${sf.projected12w}/100 in 12w (${sf.confidence} confidence)`
+  );
+  console.log("");
+  const header = "  " + "Category".padEnd(20) + "Current".padStart(9) + "Threshold".padStart(11) + "4w".padStart(7) + "8w".padStart(7) + "12w".padStart(7) + "   Crossing".padEnd(16) + "Confidence";
+  console.log(header);
+  for (const category of CATEGORY_ORDER2) {
+    const af = result.categories[category];
+    if (!af) continue;
+    const f = af.adjusted;
+    const line = "  " + category.padEnd(20) + formatValue(f.current).padStart(9) + formatValue(f.threshold).padStart(11) + formatValue(f.projectedValue4w).padStart(7) + formatValue(f.projectedValue8w).padStart(7) + formatValue(f.projectedValue12w).padStart(7) + ("   " + crossingLabel(f.thresholdCrossingWeeks)).padEnd(16) + f.confidence;
+    console.log(line);
+  }
+  if (result.warnings.length > 0) {
+    console.log("");
+    console.log("  Warnings:");
+    for (const w of result.warnings) {
+      console.log(`  ${severityPrefix(w.severity)} ${w.message}`);
+      if (w.contributingFeatures.length > 0) {
+        console.log(`    Accelerated by: ${w.contributingFeatures.join(", ")}`);
+      }
+    }
+  }
+  console.log("");
+}
+function runPredict(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const configResult = resolveConfig(options.configPath);
+  if (!configResult.ok) {
+    throw configResult.error;
+  }
+  const manager = new TimelineManager(cwd);
+  const estimator = options.noRoadmap === true ? null : new SpecImpactEstimator(cwd);
+  const engine = new PredictionEngine(cwd, manager, estimator);
+  const categories = options.category ? [options.category] : void 0;
+  return engine.predict({
+    ...options.horizon !== void 0 ? { horizon: options.horizon } : {},
+    includeRoadmap: options.noRoadmap !== true,
+    categories
+  });
+}
+function createPredictCommand() {
+  const command = new Command71("predict").description("Predict which architectural constraints will break and when").option("--category <name>", "Filter to a single metric category").option("--no-roadmap", "Baseline only \u2014 skip roadmap spec impact").option("--horizon <weeks>", "Forecast horizon in weeks (default: 12)", "12").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const mode = globalOpts.json ? OutputMode.JSON : OutputMode.TEXT;
+    try {
+      const result = runPredict({
+        configPath: globalOpts.config,
+        category: opts.category,
+        noRoadmap: opts.roadmap === false,
+        horizon: (() => {
+          const h = parseInt(opts.horizon, 10);
+          if (isNaN(h) || h < 1) throw new Error("--horizon must be a positive integer");
+          return h;
+        })()
+      });
+      if (mode === OutputMode.JSON) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        printPredictionReport(result);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (err instanceof CLIError) {
+        if (mode === OutputMode.JSON) {
+          console.log(JSON.stringify({ error: message }));
+        } else {
+          logger.error(message);
+        }
+        process.exit(err.exitCode);
+      }
+      if (mode === OutputMode.JSON) {
+        console.log(JSON.stringify({ error: message }));
+      } else {
+        logger.error(message);
+      }
+      process.exit(ExitCode.ERROR);
+    }
+  });
+  return command;
+}
+
+// src/commands/recommend.ts
+import { Command as Command72 } from "commander";
+import chalk10 from "chalk";
+async function runRecommend(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const top = options.top ?? 5;
+  let snapshot = null;
+  let usedCache = false;
+  if (!options.noCache) {
+    const cached = loadCachedSnapshot(cwd);
+    if (cached && isSnapshotFresh(cached, cwd)) {
+      snapshot = cached;
+      usedCache = true;
+    }
+  }
+  if (!snapshot) {
+    snapshot = await captureHealthSnapshot(cwd);
+  }
+  const configResult = resolveConfig();
+  const tierOverrides = configResult.ok ? configResult.value.skills?.tierOverrides : void 0;
+  const index = loadOrRebuildIndex("claude-code", cwd, tierOverrides);
+  const skills = {};
+  for (const [name, entry] of Object.entries(index.skills)) {
+    skills[name] = { addresses: entry.addresses, dependsOn: entry.dependsOn };
+  }
+  const result = recommend(snapshot, skills, { top });
+  return {
+    ...result,
+    snapshotAge: usedCache ? "cached" : "fresh"
+  };
+}
+function formatRecommendation(rec) {
+  const lines = [];
+  if (rec.urgency === "critical") {
+    lines.push(`  ${chalk10.red("[CRITICAL]")} ${rec.sequence}. ${rec.skillName}`);
+  } else {
+    lines.push(`  ${rec.sequence}. ${rec.skillName} (${rec.score.toFixed(2)})`);
+  }
+  for (const reason of rec.reasons) {
+    lines.push(`     ${chalk10.dim("\u2192")} ${reason}`);
+  }
+  return lines.join("\n");
+}
+function printRecommendations(result) {
+  if (result.recommendations.length === 0) {
+    console.log("");
+    console.log("No recommendations. Codebase health looks good!");
+    console.log("");
+    return;
+  }
+  console.log("");
+  console.log(
+    `Recommended workflow (${result.recommendations.length} skill${result.recommendations.length === 1 ? "" : "s"}):`
+  );
+  console.log("");
+  for (const rec of result.recommendations) {
+    console.log(formatRecommendation(rec));
+    console.log("");
+  }
+  console.log(`Sequence reasoning: ${result.sequenceReasoning}`);
+  console.log("");
+}
+function createRecommendCommand() {
+  const command = new Command72("recommend").description("Recommend skills based on codebase health analysis").option("--no-cache", "Force fresh health snapshot").option("--top <n>", "Max recommendations (default 5)", "5").action(async (opts, cmd) => {
+    const globalOpts = cmd.optsWithGlobals();
+    const mode = globalOpts.json ? OutputMode.JSON : OutputMode.TEXT;
+    try {
+      const top = parseInt(opts.top, 10);
+      if (isNaN(top) || top < 1) {
+        logger.error("--top must be a positive integer");
+        process.exit(1);
+      }
+      if (mode === OutputMode.TEXT) {
+        console.log("");
+        console.log("Analyzing codebase health...");
+      }
+      const result = await runRecommend({
+        noCache: opts.cache === false,
+        top
+      });
+      if (mode === OutputMode.JSON) {
+        console.log(JSON.stringify(result, null, 2));
+      } else {
+        printRecommendations(result);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      if (mode === OutputMode.JSON) {
+        console.log(JSON.stringify({ error: message }));
+      } else {
+        logger.error(message);
+      }
+      process.exit(1);
+    }
+  });
+  return command;
+}
+
 // src/index.ts
 function createProgram() {
-  const program = new Command70();
+  const program = new Command73();
   program.name("harness").description("CLI for Harness Engineering toolkit").version(CLI_VERSION).option("-c, --config <path>", "Path to config file").option("--json", "Output as JSON").option("--verbose", "Verbose output").option("--quiet", "Minimal output");
   program.addCommand(createValidateCommand());
   program.addCommand(createCheckDepsCommand());
@@ -7035,6 +7453,9 @@ function createProgram() {
   program.addCommand(createUsageCommand());
   program.addCommand(createTaintCommand());
   program.addCommand(createScanConfigCommand());
+  program.addCommand(createSnapshotCommand());
+  program.addCommand(createPredictCommand());
+  program.addCommand(createRecommendCommand());
   return program;
 }
 
@@ -7052,5 +7473,6 @@ export {
   runInstallConstraints,
   runUninstallConstraints,
   runUninstall,
+  runSnapshotCapture,
   createProgram
 };