vibecheck-ai 2.0.1 → 5.0.0

package/bin/runners/runIntent.js

@@ -0,0 +1,906 @@
+/**
+ * vibecheck intent - Intent Declaration CLI
+ * 
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * AGENT FIREWALL™ - INTENT DECLARATION COMMAND
+ * ═══════════════════════════════════════════════════════════════════════════════
+ * 
+ * Manage intent declarations for the Agent Firewall.
+ * Intent MUST be declared before AI code generation.
+ * If intent is missing → Agent Firewall defaults to BLOCK.
+ * 
+ * Subcommands:
+ *   set     - Declare a new intent
+ *   show    - Show current intent
+ *   clear   - Clear current intent
+ *   history - View intent history
+ *   verify  - Verify intent integrity
+ * 
+ * @module runIntent
+ * @version 2.0.0
+ */
+
+"use strict";
+
+const path = require("path");
+const fs = require("fs");
+
+// Lazy imports
+let _globalFlags = null;
+let _exitCodes = null;
+let _cliOutput = null;
+let _intentModule = null;
+
+function getGlobalFlags() {
+  if (!_globalFlags) {
+    _globalFlags = require("./lib/global-flags");
+  }
+  return _globalFlags;
+}
+
+function getExitCodes() {
+  if (!_exitCodes) {
+    _exitCodes = require("./lib/exit-codes");
+  }
+  return _exitCodes;
+}
+
+function getCliOutput() {
+  if (!_cliOutput) {
+    _cliOutput = require("./lib/unified-cli-output");
+  }
+  return _cliOutput;
+}
+
+function getIntentModule() {
+  if (!_intentModule) {
+    _intentModule = require("./lib/agent-firewall/intent");
+  }
+  return _intentModule;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CONSTANTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+const INTENT_VERSION = "2.0.0";
+
+const SUBCOMMANDS = {
+  set: { description: "Declare a new intent", pro: false },
+  show: { description: "Show current intent", pro: false },
+  clear: { description: "Clear current intent (archives to history)", pro: false },
+  history: { description: "View intent history", pro: false },
+  verify: { description: "Verify intent integrity", pro: false },
+  template: { description: "Show intent templates", pro: false },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HELP
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function printHelp() {
+  const { ansi } = getCliOutput();
+  
+  console.log(`
+${ansi.bold}${ansi.cyan}╔═══════════════════════════════════════════════════════════════════════════════╗
+║                                                                               ║
+║   ${ansi.reset}${ansi.bold}INTENT DECLARATION${ansi.cyan}                                                        ║
+║   ${ansi.reset}${ansi.dim}Agent Firewall™ Intent System${ansi.cyan}                                             ║
+║                                                                               ║
+╚═══════════════════════════════════════════════════════════════════════════════╝${ansi.reset}
+
+  ${ansi.bold}USAGE${ansi.reset}
+    ${ansi.cyan}vibecheck i${ansi.reset} "summary"              ${ansi.dim}Quick intent (auto-infers everything)${ansi.reset}
+    ${ansi.cyan}vibecheck intent${ansi.reset} <subcommand> [options]
+
+  ${ansi.dim}Declare your intent BEFORE AI code generation.
+  In observe mode, changes are logged for later approval.${ansi.reset}
+
+  ${ansi.bold}SUBCOMMANDS${ansi.reset}
+    ${ansi.cyan}set${ansi.reset}         Declare a new intent
+    ${ansi.cyan}show${ansi.reset}        Show current intent
+    ${ansi.cyan}clear${ansi.reset}       Clear current intent
+    ${ansi.cyan}history${ansi.reset}     View intent history
+    ${ansi.cyan}verify${ansi.reset}      Verify intent integrity
+    ${ansi.cyan}template${ansi.reset}    Show intent templates
+
+  ${ansi.bold}SET OPTIONS${ansi.reset}
+    ${ansi.cyan}--summary, -s <text>${ansi.reset}      Intent summary (required)
+    ${ansi.cyan}--constraint, -c <text>${ansi.reset}   Add constraint (repeatable)
+    ${ansi.cyan}--allow-file <path>${ansi.reset}       Allow file modification (repeatable)
+    ${ansi.cyan}--allow-route <route>${ansi.reset}     Allow route addition (repeatable)
+    ${ansi.cyan}--allow-env <var>${ansi.reset}         Allow env var (repeatable)
+    ${ansi.cyan}--scope-dir <dir>${ansi.reset}         Restrict to directory (repeatable)
+    ${ansi.cyan}--scope-domain <domain>${ansi.reset}   Restrict to domain (repeatable)
+    ${ansi.cyan}--expires <duration>${ansi.reset}      Set expiration (e.g., "1h", "30m")
+    ${ansi.cyan}--from-file <path>${ansi.reset}        Load intent from JSON file
+
+  ${ansi.bold}EXAMPLES${ansi.reset}
+    ${ansi.dim}# Simple intent${ansi.reset}
+    vibecheck intent set -s "Fix login button styling"
+
+    ${ansi.dim}# Intent with constraints${ansi.reset}
+    vibecheck intent set -s "Add user profile endpoint" \\
+      -c "No auth changes" \\
+      -c "Tests required" \\
+      --allow-file "src/routes/users.ts" \\
+      --allow-route "GET /api/users/:id"
+
+    ${ansi.dim}# Scoped intent${ansi.reset}
+    vibecheck intent set -s "Refactor auth module" \\
+      --scope-dir "src/auth/" \\
+      --scope-domain "auth"
+
+    ${ansi.dim}# From file${ansi.reset}
+    vibecheck intent set --from-file intent.json
+
+    ${ansi.dim}# Show current${ansi.reset}
+    vibecheck intent show
+
+    ${ansi.dim}# Clear${ansi.reset}
+    vibecheck intent clear
+
+  ${ansi.bold}DOMAINS${ansi.reset}
+    auth, payments, routes, contracts, ui, database, config, general
+
+  ${ansi.dim}────────────────────────────────────────────────────────────────────${ansi.reset}
+  ${ansi.dim}Documentation: https://docs.vibecheckai.dev/cli/intent${ansi.reset}
+  ${ansi.dim}Version: ${INTENT_VERSION}${ansi.reset}
+`);
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAIN ENTRY
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Main intent command handler
+ * @param {string[]} args - Command arguments
+ * @param {Object} context - Execution context
+ * @returns {Promise<number>} Exit code
+ */
+async function runIntent(args = [], context = {}) {
+  const { parseGlobalFlags, shouldSuppressOutput, isJsonMode } = getGlobalFlags();
+  const { EXIT } = getExitCodes();
+  
+  const { flags: globalFlags, cleanArgs } = parseGlobalFlags(args);
+  const quiet = shouldSuppressOutput(globalFlags);
+  const json = isJsonMode(globalFlags) || args.includes("--json");
+  const projectRoot = context.repoRoot || globalFlags.path || process.cwd();
+  
+  // Handle help
+  if (globalFlags.help || args.includes("--help") || args.includes("-h")) {
+    printHelp();
+    return EXIT.SUCCESS;
+  }
+  
+  // Check for QUICK INTENT MODE: vibecheck i "summary text"
+  // If first arg is a quoted string (not a subcommand), treat as quick intent
+  const firstArg = cleanArgs[0];
+  const isQuickMode = firstArg && 
+    !SUBCOMMANDS[firstArg] && 
+    !firstArg.startsWith("-") &&
+    firstArg.length > 2;
+  
+  if (isQuickMode) {
+    // Quick intent: vibecheck i "fix login bug"
+    const ctx = {
+      projectRoot,
+      json,
+      quiet,
+      args: cleanArgs,
+      originalArgs: args,
+      quickMode: true,
+    };
+    return await handleQuickSet(ctx);
+  }
+  
+  // Parse subcommand
+  const subcommand = firstArg || "show";
+  const subArgs = cleanArgs.slice(1);
+  
+  // Create context
+  const ctx = {
+    projectRoot,
+    json,
+    quiet,
+    args: subArgs,
+    originalArgs: args,
+  };
+  
+  try {
+    switch (subcommand) {
+      case "set":
+        return await handleSet(ctx);
+      case "show":
+        return await handleShow(ctx);
+      case "clear":
+        return await handleClear(ctx);
+      case "history":
+        return await handleHistory(ctx);
+      case "verify":
+        return await handleVerify(ctx);
+      case "template":
+        return await handleTemplate(ctx);
+      default:
+        return handleUnknown(subcommand, ctx);
+    }
+  } catch (error) {
+    return handleError(error, ctx);
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// HANDLERS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Handle QUICK set - vibecheck i "summary text"
+ * Auto-infers constraints, scope, and allowed files from context
+ */
+async function handleQuickSet(ctx) {
+  const { EXIT } = getExitCodes();
+  const { ansi, renderSuccess, renderError } = getCliOutput();
+  const { createIntent, IntentStore } = getIntentModule();
+  
+  // Import auto-detect module
+  let autoDetect;
+  try {
+    autoDetect = require("./lib/agent-firewall/intent/auto-detect");
+  } catch (e) {
+    if (ctx.json) {
+      console.log(JSON.stringify({ success: false, error: "Auto-detect module not available" }));
+    } else {
+      renderError("Auto-detect module not available");
+    }
+    return EXIT.INTERNAL_ERROR;
+  }
+  
+  // Get the summary from args - join all non-flag args
+  const summaryParts = ctx.args.filter(a => !a.startsWith("-"));
+  const userSummary = summaryParts.join(" ").trim();
+  
+  if (!userSummary) {
+    if (ctx.json) {
+      console.log(JSON.stringify({ success: false, error: "Summary required" }));
+    } else {
+      renderError("Summary required");
+      console.log(`\n  ${ansi.dim}Example: ${ansi.cyan}vibecheck i "fix login bug"${ansi.reset}\n`);
+    }
+    return EXIT.USER_ERROR;
+  }
+  
+  // Auto-detect context
+  const detected = autoDetect.autoDetectIntent(ctx.projectRoot, userSummary);
+  
+  // Create and store intent
+  const intent = createIntent(detected);
+  const store = new IntentStore(ctx.projectRoot);
+  const result = store.store(intent);
+  
+  if (ctx.json) {
+    console.log(JSON.stringify({
+      success: result.success,
+      quick_mode: true,
+      intent: {
+        hash: intent.hash,
+        summary: intent.summary,
+        constraints: intent.constraints,
+        allowed_changes: intent.allowed_changes?.length || 0,
+        scope: intent.scope,
+        created_at: intent.created_at,
+      },
+      auto_detected: detected._context,
+      error: result.error,
+    }, null, 2));
+  } else if (!ctx.quiet) {
+    if (result.success) {
+      console.log(`
+${ansi.green}${ansi.bold}╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║   ✓ QUICK INTENT SET                                              ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝${ansi.reset}
+
+  ${ansi.bold}Summary${ansi.reset}
+    ${intent.summary}`);
+      
+      if (intent.constraints.length > 0) {
+        console.log(`\n  ${ansi.bold}Auto-Inferred Constraints${ansi.reset}`);
+        for (const c of intent.constraints) {
+          console.log(`    ${ansi.yellow}•${ansi.reset} ${c}`);
+        }
+      }
+      
+      if (intent.allowed_changes && intent.allowed_changes.length > 0) {
+        console.log(`\n  ${ansi.bold}Auto-Allowed Files${ansi.reset} ${ansi.dim}(from git status)${ansi.reset}`);
+        for (const ac of intent.allowed_changes.slice(0, 5)) {
+          console.log(`    ${ansi.green}✓${ansi.reset} ${ac.target}`);
+        }
+        if (intent.allowed_changes.length > 5) {
+          console.log(`    ${ansi.dim}... and ${intent.allowed_changes.length - 5} more${ansi.reset}`);
+        }
+      }
+      
+      if (intent.scope) {
+        console.log(`\n  ${ansi.bold}Auto-Detected Scope${ansi.reset}`);
+        if (intent.scope.directories) {
+          console.log(`    ${ansi.dim}Directories:${ansi.reset} ${intent.scope.directories.join(", ")}`);
+        }
+        if (intent.scope.domains) {
+          console.log(`    ${ansi.dim}Domains:${ansi.reset} ${intent.scope.domains.join(", ")}`);
+        }
+      }
+      
+      // Show context used
+      const ctx_info = detected._context;
+      if (ctx_info) {
+        console.log(`\n  ${ansi.dim}Context: ${ctx_info.branch ? `branch=${ctx_info.branch}` : ""}${ctx_info.stagedFiles ? ` staged=${ctx_info.stagedFiles}` : ""}${ctx_info.modifiedFiles ? ` modified=${ctx_info.modifiedFiles}` : ""} type=${ctx_info.inferredType}${ansi.reset}`);
+      }
+      
+      console.log(`
+  ${ansi.dim}Hash: ${intent.hash.slice(0, 16)}...${ansi.reset}
+
+  ${ansi.bold}You're ready to vibe.${ansi.reset} ${ansi.dim}AI changes will be checked against this intent.${ansi.reset}
+`);
+    } else {
+      renderError(result.error || "Failed to store intent");
+    }
+  }
+  
+  return result.success ? EXIT.SUCCESS : EXIT.INTERNAL_ERROR;
+}
+
+/**
+ * Handle set subcommand
+ */
+async function handleSet(ctx) {
+  const { EXIT } = getExitCodes();
+  const { ansi, renderSuccess, renderError } = getCliOutput();
+  const { createIntent, IntentStore, CONSTRAINT_TEMPLATES } = getIntentModule();
+  
+  const args = ctx.originalArgs;
+  
+  // Check for --from-file
+  const fromFile = getArgValue(args, "--from-file");
+  
+  let intentData;
+  
+  if (fromFile) {
+    // Load from file
+    const filePath = path.resolve(ctx.projectRoot, fromFile);
+    if (!fs.existsSync(filePath)) {
+      if (ctx.json) {
+        console.log(JSON.stringify({ success: false, error: `File not found: ${fromFile}` }));
+      } else {
+        renderError(`File not found: ${fromFile}`);
+      }
+      return EXIT.USER_ERROR;
+    }
+    
+    try {
+      intentData = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+    } catch (e) {
+      if (ctx.json) {
+        console.log(JSON.stringify({ success: false, error: `Invalid JSON: ${e.message}` }));
+      } else {
+        renderError(`Invalid JSON in ${fromFile}: ${e.message}`);
+      }
+      return EXIT.USER_ERROR;
+    }
+  } else {
+    // Build from CLI args
+    const summary = getArgValue(args, "--summary") || getArgValue(args, "-s");
+    
+    if (!summary) {
+      if (ctx.json) {
+        console.log(JSON.stringify({ success: false, error: "Summary required. Use --summary or -s" }));
+      } else {
+        renderError("Summary required. Use --summary or -s");
+        console.log(`\n  ${ansi.dim}Example: vibecheck intent set -s "Add user profile endpoint"${ansi.reset}\n`);
+      }
+      return EXIT.USER_ERROR;
+    }
+    
+    const constraints = getAllArgValues(args, "--constraint", "-c");
+    const allowFiles = getAllArgValues(args, "--allow-file");
+    const allowRoutes = getAllArgValues(args, "--allow-route");
+    const allowEnvs = getAllArgValues(args, "--allow-env");
+    const scopeDirs = getAllArgValues(args, "--scope-dir");
+    const scopeDomains = getAllArgValues(args, "--scope-domain");
+    const expires = getArgValue(args, "--expires");
+    
+    // Build allowed_changes
+    const allowed_changes = [];
+    
+    for (const file of allowFiles) {
+      allowed_changes.push({ type: "file_modify", target: file });
+    }
+    for (const route of allowRoutes) {
+      allowed_changes.push({ type: "route_add", target: route });
+    }
+    for (const env of allowEnvs) {
+      allowed_changes.push({ type: "env_add", target: env });
+    }
+    
+    // Build scope
+    let scope = null;
+    if (scopeDirs.length > 0 || scopeDomains.length > 0) {
+      scope = {};
+      if (scopeDirs.length > 0) scope.directories = scopeDirs;
+      if (scopeDomains.length > 0) scope.domains = scopeDomains;
+    }
+    
+    intentData = {
+      summary,
+      constraints,
+      allowed_changes: allowed_changes.length > 0 ? allowed_changes : undefined,
+      scope,
+    };
+    
+    // Handle expiration
+    if (expires) {
+      const ms = parseDuration(expires);
+      if (ms) {
+        intentData.expires_at = new Date(Date.now() + ms).toISOString();
+      }
+    }
+  }
+  
+  // Create and store intent
+  const intent = createIntent(intentData);
+  const store = new IntentStore(ctx.projectRoot);
+  const result = store.store(intent);
+  
+  if (ctx.json) {
+    console.log(JSON.stringify({
+      success: result.success,
+      intent: {
+        hash: intent.hash,
+        summary: intent.summary,
+        constraints: intent.constraints,
+        created_at: intent.created_at,
+      },
+      error: result.error,
+    }, null, 2));
+  } else if (!ctx.quiet) {
+    if (result.success) {
+      console.log(`
+${ansi.green}${ansi.bold}╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║   ✓ INTENT DECLARED                                               ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝${ansi.reset}
+
+  ${ansi.bold}Summary${ansi.reset}
+    ${intent.summary}
+
+  ${ansi.bold}Constraints${ansi.reset}`);
+      
+      if (intent.constraints.length > 0) {
+        for (const c of intent.constraints) {
+          console.log(`    ${ansi.yellow}•${ansi.reset} ${c}`);
+        }
+      } else {
+        console.log(`    ${ansi.dim}(none)${ansi.reset}`);
+      }
+      
+      if (intent.allowed_changes && intent.allowed_changes.length > 0) {
+        console.log(`\n  ${ansi.bold}Allowed Changes${ansi.reset}`);
+        for (const ac of intent.allowed_changes) {
+          console.log(`    ${ansi.green}✓${ansi.reset} [${ac.type}] ${ac.target || ac.pattern}`);
+        }
+      }
+      
+      if (intent.scope) {
+        console.log(`\n  ${ansi.bold}Scope${ansi.reset}`);
+        if (intent.scope.directories) {
+          console.log(`    ${ansi.dim}Directories:${ansi.reset} ${intent.scope.directories.join(", ")}`);
+        }
+        if (intent.scope.domains) {
+          console.log(`    ${ansi.dim}Domains:${ansi.reset} ${intent.scope.domains.join(", ")}`);
+        }
+      }
+      
+      console.log(`
+  ${ansi.dim}Hash: ${intent.hash.slice(0, 16)}...${ansi.reset}
+  ${ansi.dim}Created: ${intent.created_at}${ansi.reset}
+
+  ${ansi.bold}The Agent Firewall will now enforce this intent.${ansi.reset}
+  ${ansi.dim}Changes outside this intent will be BLOCKED.${ansi.reset}
+`);
+    } else {
+      renderError(result.error || "Failed to store intent");
+    }
+  }
+  
+  return result.success ? EXIT.SUCCESS : EXIT.INTERNAL_ERROR;
+}
+
+/**
+ * Handle show subcommand
+ */
+async function handleShow(ctx) {
+  const { EXIT } = getExitCodes();
+  const { ansi, renderWarning } = getCliOutput();
+  const { IntentStore, verifyIntentIntegrity, isIntentExpired } = getIntentModule();
+  
+  const store = new IntentStore(ctx.projectRoot);
+  const intent = store.getCurrent({ allowMissing: true });
+  
+  if (!intent) {
+    if (ctx.json) {
+      console.log(JSON.stringify({ intent: null, message: "No intent declared" }));
+    } else if (!ctx.quiet) {
+      renderWarning("No intent declared");
+      console.log(`
+  ${ansi.dim}The Agent Firewall will BLOCK all AI changes.${ansi.reset}
+  ${ansi.dim}Declare an intent: ${ansi.cyan}vibecheck intent set -s "Your intent"${ansi.reset}
+`);
+    }
+    return EXIT.SUCCESS;
+  }
+  
+  // Check if it's the blocking intent
+  const isBlocking = intent.summary?.includes("NO INTENT DECLARED");
+  
+  // Verify integrity
+  const integrity = verifyIntentIntegrity(intent);
+  const expired = isIntentExpired(intent);
+  
+  if (ctx.json) {
+    console.log(JSON.stringify({
+      intent,
+      status: {
+        valid: integrity.valid && !expired && !isBlocking,
+        integrity: integrity.valid,
+        expired,
+        isBlocking,
+      },
+    }, null, 2));
+  } else if (!ctx.quiet) {
+    if (isBlocking) {
+      console.log(`
+${ansi.yellow}${ansi.bold}╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║   ⚠ NO INTENT DECLARED                                            ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝${ansi.reset}
+
+  ${ansi.yellow}All AI changes are currently BLOCKED.${ansi.reset}
+  ${ansi.dim}Declare an intent to allow specific changes.${ansi.reset}
+
+  ${ansi.bold}Example:${ansi.reset}
+    ${ansi.cyan}vibecheck intent set -s "Fix login button" --allow-file "src/Login.tsx"${ansi.reset}
+`);
+    } else {
+      const statusColor = integrity.valid && !expired ? ansi.green : ansi.red;
+      const statusText = integrity.valid && !expired ? "ACTIVE" : expired ? "EXPIRED" : "INVALID";
+      
+      console.log(`
+${ansi.cyan}${ansi.bold}╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║   CURRENT INTENT                                                  ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝${ansi.reset}
+
+  ${ansi.bold}Status${ansi.reset}
+    ${statusColor}${statusText}${ansi.reset}${expired ? ` ${ansi.dim}(expired at ${intent.expires_at})${ansi.reset}` : ""}
+
+  ${ansi.bold}Summary${ansi.reset}
+    ${intent.summary}
+
+  ${ansi.bold}Constraints${ansi.reset}`);
+      
+      if (intent.constraints && intent.constraints.length > 0) {
+        for (const c of intent.constraints) {
+          console.log(`    ${ansi.yellow}•${ansi.reset} ${c}`);
+        }
+      } else {
+        console.log(`    ${ansi.dim}(none)${ansi.reset}`);
+      }
+      
+      if (intent.allowed_changes && intent.allowed_changes.length > 0) {
+        console.log(`\n  ${ansi.bold}Allowed Changes${ansi.reset}`);
+        for (const ac of intent.allowed_changes) {
+          console.log(`    ${ansi.green}✓${ansi.reset} [${ac.type}] ${ac.target || ac.pattern}`);
+        }
+      }
+      
+      if (intent.scope) {
+        console.log(`\n  ${ansi.bold}Scope${ansi.reset}`);
+        if (intent.scope.directories) {
+          console.log(`    ${ansi.dim}Directories:${ansi.reset} ${intent.scope.directories.join(", ")}`);
+        }
+        if (intent.scope.domains) {
+          console.log(`    ${ansi.dim}Domains:${ansi.reset} ${intent.scope.domains.join(", ")}`);
+        }
+        if (intent.scope.excluded_paths) {
+          console.log(`    ${ansi.dim}Excluded:${ansi.reset} ${intent.scope.excluded_paths.join(", ")}`);
+        }
+      }
+      
+      console.log(`
+  ${ansi.dim}Hash: ${intent.hash.slice(0, 16)}...${ansi.reset}
+  ${ansi.dim}Version: ${intent.version || 1}${ansi.reset}
+  ${ansi.dim}Created: ${intent.created_at}${ansi.reset}
+`);
+    }
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+/**
+ * Handle clear subcommand
+ */
+async function handleClear(ctx) {
+  const { EXIT } = getExitCodes();
+  const { ansi, renderSuccess, renderWarning } = getCliOutput();
+  const { IntentStore } = getIntentModule();
+  
+  const store = new IntentStore(ctx.projectRoot);
+  
+  if (!store.hasIntent()) {
+    if (ctx.json) {
+      console.log(JSON.stringify({ success: true, message: "No intent to clear" }));
+    } else if (!ctx.quiet) {
+      renderWarning("No intent to clear");
+    }
+    return EXIT.SUCCESS;
+  }
+  
+  store.clear();
+  
+  if (ctx.json) {
+    console.log(JSON.stringify({ success: true, message: "Intent cleared and archived" }));
+  } else if (!ctx.quiet) {
+    renderSuccess("Intent cleared");
+    console.log(`
+  ${ansi.dim}The previous intent has been archived to history.${ansi.reset}
+  ${ansi.yellow}The Agent Firewall will now BLOCK all AI changes.${ansi.reset}
+  
+  ${ansi.dim}View history: ${ansi.cyan}vibecheck intent history${ansi.reset}
+`);
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+/**
+ * Handle history subcommand
+ */
+async function handleHistory(ctx) {
+  const { EXIT } = getExitCodes();
+  const { ansi } = getCliOutput();
+  const { IntentStore } = getIntentModule();
+  
+  const store = new IntentStore(ctx.projectRoot);
+  const history = store.getHistory(10);
+  
+  if (ctx.json) {
+    console.log(JSON.stringify({ history }, null, 2));
+  } else if (!ctx.quiet) {
+    console.log(`
+${ansi.bold}Intent History${ansi.reset} ${ansi.dim}(last 10)${ansi.reset}
+`);
+    
+    if (history.length === 0) {
+      console.log(`  ${ansi.dim}No history found${ansi.reset}\n`);
+    } else {
+      for (const intent of history) {
+        const date = new Date(intent.archived_at || intent.created_at).toLocaleString();
+        console.log(`  ${ansi.dim}${date}${ansi.reset}`);
+        console.log(`    ${intent.summary}`);
+        console.log(`    ${ansi.dim}Hash: ${intent.hash.slice(0, 12)}... | v${intent.version || 1}${ansi.reset}`);
+        console.log();
+      }
+    }
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+/**
+ * Handle verify subcommand
+ */
+async function handleVerify(ctx) {
+  const { EXIT } = getExitCodes();
+  const { ansi, renderSuccess, renderError } = getCliOutput();
+  const { IntentStore, verifyIntentIntegrity, isIntentExpired } = getIntentModule();
+  
+  const store = new IntentStore(ctx.projectRoot);
+  const intent = store.getCurrent({ allowMissing: true });
+  
+  if (!intent) {
+    if (ctx.json) {
+      console.log(JSON.stringify({ valid: false, reason: "NO_INTENT" }));
+    } else {
+      renderError("No intent to verify");
+    }
+    return EXIT.WARNINGS;
+  }
+  
+  const integrity = verifyIntentIntegrity(intent);
+  const expired = isIntentExpired(intent);
+  const isBlocking = intent.summary?.includes("NO INTENT DECLARED");
+  
+  const result = {
+    valid: integrity.valid && !expired && !isBlocking,
+    integrity: integrity.valid,
+    integrityReason: integrity.reason,
+    expired,
+    isBlocking,
+    hash: intent.hash,
+    computed_hash: integrity.computed_hash,
+  };
+  
+  if (ctx.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!ctx.quiet) {
+    if (result.valid) {
+      renderSuccess("Intent verified");
+      console.log(`
+  ${ansi.green}✓${ansi.reset} Integrity: ${integrity.reason}
+  ${ansi.green}✓${ansi.reset} Not expired
+  ${ansi.dim}Hash: ${intent.hash.slice(0, 16)}...${ansi.reset}
+`);
+    } else {
+      renderError("Intent verification failed");
+      console.log(`
+  ${!integrity.valid ? `${ansi.red}✗${ansi.reset} Integrity: ${integrity.reason}` : `${ansi.green}✓${ansi.reset} Integrity: OK`}
+  ${expired ? `${ansi.red}✗${ansi.reset} Expired` : `${ansi.green}✓${ansi.reset} Not expired`}
+  ${isBlocking ? `${ansi.yellow}!${ansi.reset} Blocking intent (no user intent declared)` : ""}
+`);
+    }
+  }
+  
+  return result.valid ? EXIT.SUCCESS : EXIT.WARNINGS;
+}
+
+/**
+ * Handle template subcommand
+ */
+async function handleTemplate(ctx) {
+  const { EXIT } = getExitCodes();
+  const { ansi } = getCliOutput();
+  const { CONSTRAINT_TEMPLATES } = getIntentModule();
+  
+  const templates = {
+    STRICT_BUGFIX: {
+      description: "For minimal, focused bug fixes",
+      constraints: CONSTRAINT_TEMPLATES.STRICT_BUGFIX,
+      example: 'vibecheck intent set -s "Fix login button" -c "No new routes" -c "Changes limited to specified file(s)" --allow-file "src/Login.tsx"',
+    },
+    FEATURE_ADDITION: {
+      description: "For adding new features",
+      constraints: CONSTRAINT_TEMPLATES.FEATURE_ADDITION,
+      example: 'vibecheck intent set -s "Add user profile endpoint" -c "Tests required" --allow-route "GET /api/users/:id"',
+    },
+    REFACTOR: {
+      description: "For refactoring without behavior changes",
+      constraints: CONSTRAINT_TEMPLATES.REFACTOR,
+      example: 'vibecheck intent set -s "Refactor auth module" -c "No behavior changes" --scope-dir "src/auth/"',
+    },
+    SECURITY_PATCH: {
+      description: "For security-sensitive changes",
+      constraints: CONSTRAINT_TEMPLATES.SECURITY_PATCH,
+      example: 'vibecheck intent set -s "Fix XSS vulnerability" -c "No permission relaxation" -c "Review required"',
+    },
+  };
+  
+  if (ctx.json) {
+    console.log(JSON.stringify(templates, null, 2));
+  } else if (!ctx.quiet) {
+    console.log(`
+${ansi.bold}Intent Templates${ansi.reset}
+`);
+    
+    for (const [name, template] of Object.entries(templates)) {
+      console.log(`${ansi.cyan}${ansi.bold}${name}${ansi.reset}`);
+      console.log(`  ${ansi.dim}${template.description}${ansi.reset}`);
+      console.log(`  ${ansi.bold}Constraints:${ansi.reset}`);
+      for (const c of template.constraints) {
+        console.log(`    ${ansi.yellow}•${ansi.reset} ${c}`);
+      }
+      console.log(`  ${ansi.bold}Example:${ansi.reset}`);
+      console.log(`    ${ansi.dim}${template.example}${ansi.reset}`);
+      console.log();
+    }
+  }
+  
+  return EXIT.SUCCESS;
+}
+
+/**
+ * Handle unknown subcommand
+ */
+function handleUnknown(subcommand, ctx) {
+  const { EXIT } = getExitCodes();
+  const { ansi } = getCliOutput();
+  
+  if (ctx.json) {
+    console.log(JSON.stringify({
+      success: false,
+      error: `Unknown subcommand: ${subcommand}`,
+      available: Object.keys(SUBCOMMANDS),
+    }));
+  } else {
+    console.log(`
+${ansi.red}Error: Unknown subcommand '${subcommand}'${ansi.reset}
+
+${ansi.dim}Available subcommands:${ansi.reset}
+${Object.keys(SUBCOMMANDS).map(s => `  ${ansi.cyan}${s}${ansi.reset}`).join("\n")}
+
+Run ${ansi.cyan}vibecheck intent --help${ansi.reset} for usage.
+`);
+  }
+  
+  return EXIT.USER_ERROR;
+}
+
+/**
+ * Handle error
+ */
+function handleError(error, ctx) {
+  const { EXIT } = getExitCodes();
+  const { renderError } = getCliOutput();
+  
+  if (ctx.json) {
+    console.log(JSON.stringify({ success: false, error: error.message }));
+  } else {
+    renderError(`Intent error: ${error.message}`);
+  }
+  
+  return EXIT.INTERNAL_ERROR;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+function getArgValue(args, ...flags) {
+  for (const flag of flags) {
+    const index = args.indexOf(flag);
+    if (index !== -1 && args[index + 1] && !args[index + 1].startsWith("-")) {
+      return args[index + 1];
+    }
+  }
+  return null;
+}
+
+function getAllArgValues(args, ...flags) {
+  const values = [];
+  for (let i = 0; i < args.length; i++) {
+    if (flags.includes(args[i]) && args[i + 1] && !args[i + 1].startsWith("-")) {
+      values.push(args[i + 1]);
+    }
+  }
+  return values;
+}
+
+function parseDuration(str) {
+  const match = str.match(/^(\d+)(s|m|h|d)$/);
+  if (!match) return null;
+  
+  const value = parseInt(match[1], 10);
+  const unit = match[2];
+  
+  const multipliers = {
+    s: 1000,
+    m: 60 * 1000,
+    h: 60 * 60 * 1000,
+    d: 24 * 60 * 60 * 1000,
+  };
+  
+  return value * multipliers[unit];
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// EXPORTS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+module.exports = {
+  runIntent,
+  SUBCOMMANDS,
+};