@quinteroac/agents-coding-toolkit 0.1.0-preview → 0.2.0

package/src/cli.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+describe("US-005: execute refactor CLI routing and help text", () => {
+  // AC01: cli.ts routes `execute refactor` to runExecuteRefactor handler
+  test("cli.ts routes execute refactor subcommand to runExecuteRefactor", async () => {
+    const source = await readFile(join(import.meta.dir, "cli.ts"), "utf8");
+    expect(source).toContain('import { runExecuteRefactor } from "./commands/execute-refactor"');
+    expect(source).toContain('if (subcommand === "refactor")');
+    expect(source).toContain("await runExecuteRefactor({ provider, force })");
+  });
+
+  // AC02: printUsage includes `execute refactor --agent <provider>` with a one-line description
+  test("printUsage includes execute refactor --agent <provider> with one-line description", async () => {
+    const source = await readFile(join(import.meta.dir, "cli.ts"), "utf8");
+    expect(source).toContain("execute refactor --agent <provider>");
+    expect(source).toContain("Execute approved refactor items via agent in order");
+  });
+
+  // AC03: Unknown options after --agent <provider> cause clear error and exit code 1
+  test("unknown options after --agent <provider> cause clear error message and exit code 1", async () => {
+    const cliPath = join(import.meta.dir, "cli.ts");
+    const proc = Bun.spawn(
+      ["bun", cliPath, "execute", "refactor", "--agent", "claude", "--unknown-flag"],
+      {
+        stdout: "pipe",
+        stderr: "pipe",
+      },
+    );
+    const exitCode = await proc.exited;
+    const stderrText = await new Response(proc.stderr).text();
+
+    expect(exitCode).toBe(1);
+    expect(stderrText).toContain("Unknown option(s) for execute refactor");
+    expect(stderrText).toContain("--unknown-flag");
+  });
+
+  // AC03: Multiple unknown options after --agent <provider> are all reported
+  test("multiple unknown options after --agent <provider> are all listed in error message", async () => {
+    const cliPath = join(import.meta.dir, "cli.ts");
+    const proc = Bun.spawn(
+      ["bun", cliPath, "execute", "refactor", "--agent", "claude", "--foo", "--bar"],
+      {
+        stdout: "pipe",
+        stderr: "pipe",
+      },
+    );
+    const exitCode = await proc.exited;
+    const stderrText = await new Response(proc.stderr).text();
+
+    expect(exitCode).toBe(1);
+    expect(stderrText).toContain("Unknown option(s) for execute refactor");
+    expect(stderrText).toContain("--foo");
+    expect(stderrText).toContain("--bar");
+  });
+});

package/src/cli.ts

@@ -1,21 +1,28 @@
 #!/usr/bin/env bun
 
 import { join } from "node:path";
-import { parseAgentArg } from "./agent";
+import { parseAgentArg, parseProvider, type AgentProvider } from "./agent";
+import { GuardrailAbortError } from "./guardrail";
 import { runApproveProjectContext } from "./commands/approve-project-context";
+import { runApprovePrototype } from "./commands/approve-prototype";
+import { runApproveRefactorPlan } from "./commands/approve-refactor-plan";
 import { runApproveRequirement } from "./commands/approve-requirement";
 import { runApproveTestPlan } from "./commands/approve-test-plan";
 import { runCreateIssue, runCreateIssueFromTestReport } from "./commands/create-issue";
 import { runCreateProjectContext } from "./commands/create-project-context";
 import { runCreatePrototype } from "./commands/create-prototype";
 import { runCreateTestPlan } from "./commands/create-test-plan";
+import { runDefineRefactorPlan } from "./commands/define-refactor-plan";
 import { runDefineRequirement } from "./commands/define-requirement";
 import { runDestroy } from "./commands/destroy";
 import { runExecuteAutomatedFix } from "./commands/execute-automated-fix";
 import { runExecuteManualFix } from "./commands/execute-manual-fix";
+import { runExecuteRefactor } from "./commands/execute-refactor";
 import { runExecuteTestPlan } from "./commands/execute-test-plan";
+import { runFlow } from "./commands/flow";
 import { runInit } from "./commands/init";
 import { runRefineProjectContext } from "./commands/refine-project-context";
+import { runRefineRefactorPlan } from "./commands/refine-refactor-plan";
 import { runRefineRequirement } from "./commands/refine-requirement";
 import { runRefineTestPlan } from "./commands/refine-test-plan";
 import { runStartIteration } from "./commands/start-iteration";
@@ -76,18 +83,43 @@ function parseOptionalIntegerFlag(
   return { value: parsed, remainingArgs };
 }
 
+function parseForce(args: string[]): { force: boolean; remainingArgs: string[] } {
+  const force = args.includes("--force");
+  return {
+    force,
+    remainingArgs: args.filter((arg) => arg !== "--force"),
+  };
+}
+
+function parseOptionalAgentArg(args: string[]): {
+  provider: AgentProvider | undefined;
+  remainingArgs: string[];
+} {
+  const { value, remainingArgs } = extractFlagValue(args, "--agent");
+  if (value === null) {
+    return { provider: undefined, remainingArgs };
+  }
+
+  return {
+    provider: parseProvider(value),
+    remainingArgs,
+  };
+}
+
 function printUsage() {
   console.log(`Usage: nvst <command> [options]
 
 Commands:
   init               Initialize toolkit files in the current directory
   start iteration    Start a new iteration (archives previous if exists)
-  create project-context --agent <provider> [--mode strict|yolo]
+  create project-context --agent <provider> [--mode strict|yolo] [--force]
                      Generate/update .agents/PROJECT_CONTEXT.md via agent
   create test-plan --agent <provider> [--force]
                      Generate test plan document for current iteration
   create prototype --agent <provider> [--iterations <N>] [--retry-on-fail <N>] [--stop-on-critical]
                      Initialize prototype build for current iteration
+  flow [--agent <provider>] [--force]
+                     Run the next pending flow step(s) until an approval gate or completion
   create issue --agent <provider>
                      Create issues interactively via agent
   create issue --test-execution-report
@@ -96,20 +128,30 @@ Commands:
                      Mark project context as approved
   approve test-plan
                      Mark test plan as approved and generate structured TP JSON
+  approve prototype
+                     Stage and commit all pending changes for current iteration
+  approve refactor-plan
+                     Mark refactor plan as approved and generate structured refactor PRD JSON
   refine project-context --agent <provider> [--challenge]
                      Refine project context via agent (editor or challenge mode)
-  define requirement --agent <provider>
+  define requirement --agent <provider> [--force]
                      Create requirement document via agent
-  refine requirement --agent <provider> [--challenge]
+  define refactor-plan --agent <provider> [--force]
+                     Create refactor plan document via agent
+  refine requirement --agent <provider> [--challenge] [--force]
                      Refine requirement document via agent
-  refine test-plan --agent <provider> [--challenge]
+  refine test-plan --agent <provider> [--challenge] [--force]
                      Refine test plan document via agent
-  execute test-plan --agent <provider>
+  refine refactor-plan --agent <provider> [--challenge] [--force]
+                     Refine refactor plan document via agent
+  execute test-plan --agent <provider> [--force]
                      Execute approved structured test-plan JSON via agent
   execute automated-fix --agent <provider> [--iterations <N>] [--retry-on-fail <N>]
                      Attempt automated fixes for open issues in current iteration
   execute manual-fix --agent <provider>
                      Find manual-fix issues for current iteration and confirm execution
+  execute refactor --agent <provider> [--force]
+                     Execute approved refactor items via agent in order
   approve requirement
                      Mark requirement definition as approved
   write-json --schema <name> --out <path> [--data '<json>']
@@ -122,7 +164,7 @@ Options:
   --iterations       Maximum prototype passes (integer >= 1)
   --retry-on-fail    Retry attempts per failed story (integer >= 0)
   --stop-on-critical Stop execution after critical failures
-  --force            Overwrite output file without confirmation
+  --force            Bypass flow guardrail confirmation (and overwrite test-plan output)
   --challenge        Run refine in challenger mode
   --clean            When used with destroy, also removes .agents/flow/archived
   -h, --help         Show this help message
@@ -153,8 +195,9 @@ async function main() {
   }
 
   if (command === "init") {
-    if (args.length > 0) {
-      console.error(`Unknown option(s) for init: ${args.join(" ")}`);
+    const { remainingArgs: unknownArgs } = parseForce(args);
+    if (unknownArgs.length > 0) {
+      console.error(`Unknown option(s) for init: ${unknownArgs.join(" ")}`);
       printUsage();
       process.exitCode = 1;
       return;
@@ -164,8 +207,9 @@ async function main() {
   }
 
   if (command === "destroy") {
-    const clean = args.includes("--clean");
-    const unknownArgs = args.filter((arg) => arg !== "--clean");
+    const { remainingArgs: argsWithoutForce } = parseForce(args);
+    const clean = argsWithoutForce.includes("--clean");
+    const unknownArgs = argsWithoutForce.filter((arg) => arg !== "--clean");
     if (unknownArgs.length > 0) {
       console.error(`Unknown option(s) for destroy: ${unknownArgs.join(" ")}`);
       printUsage();
@@ -177,7 +221,8 @@ async function main() {
   }
 
   if (command === "start") {
-    if (args[0] !== "iteration" || args.length !== 1) {
+    const { remainingArgs: argsWithoutForce } = parseForce(args);
+    if (argsWithoutForce[0] !== "iteration" || argsWithoutForce.length !== 1) {
       console.error(`Usage for start: nvst start iteration`);
       printUsage();
       process.exitCode = 1;
@@ -187,6 +232,26 @@ async function main() {
     return;
   }
 
+  if (command === "flow") {
+    try {
+      const { provider, remainingArgs: postAgentArgs } = parseOptionalAgentArg(args);
+      const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+      if (postForceArgs.length > 0) {
+        console.error(`Unknown option(s) for flow: ${postForceArgs.join(" ")}`);
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+      await runFlow({ provider, force });
+      return;
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : String(error));
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   if (command === "create") {
     if (args.length === 0) {
       console.error(
@@ -203,15 +268,16 @@ async function main() {
       try {
         const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
         const { mode, remainingArgs: postModeArgs } = parseMode(postAgentArgs);
+        const { force, remainingArgs: postForceArgs } = parseForce(postModeArgs);
 
-        if (postModeArgs.length > 0) {
-          console.error(`Unknown option(s) for create project-context: ${postModeArgs.join(" ")}`);
+        if (postForceArgs.length > 0) {
+          console.error(`Unknown option(s) for create project-context: ${postForceArgs.join(" ")}`);
           printUsage();
           process.exitCode = 1;
           return;
         }
 
-        await runCreateProjectContext({ provider, mode });
+        await runCreateProjectContext({ provider, mode, force });
         return;
       } catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -234,8 +300,9 @@ async function main() {
           remainingArgs: postRetryArgs,
         } = parseOptionalIntegerFlag(postIterationsArgs, "--retry-on-fail", 0);
 
-        const stopOnCritical = postRetryArgs.includes("--stop-on-critical");
-        const unknownArgs = postRetryArgs.filter((arg) => arg !== "--stop-on-critical");
+        const { force, remainingArgs: postForceArgs } = parseForce(postRetryArgs);
+        const stopOnCritical = postForceArgs.includes("--stop-on-critical");
+        const unknownArgs = postForceArgs.filter((arg) => arg !== "--stop-on-critical");
         if (unknownArgs.length > 0) {
           console.error(`Unknown option(s) for create prototype: ${unknownArgs.join(" ")}`);
           printUsage();
@@ -243,7 +310,7 @@ async function main() {
           return;
         }
 
-        await runCreatePrototype({ provider, iterations, retryOnFail, stopOnCritical });
+        await runCreatePrototype({ provider, iterations, retryOnFail, stopOnCritical, force });
         return;
       } catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -278,9 +345,10 @@ async function main() {
 
     if (subcommand === "issue") {
       const subArgs = args.slice(1);
+      const { remainingArgs: subArgsWithoutForce } = parseForce(subArgs);
 
       // Check for --help before parsing
-      if (subArgs.includes("--help") || subArgs.includes("-h")) {
+      if (subArgsWithoutForce.includes("--help") || subArgsWithoutForce.includes("-h")) {
         console.log(`Usage for create issue:
   nvst create issue --agent <provider>           Create issues interactively via agent
   nvst create issue --test-execution-report      Derive issues from test execution results
@@ -292,8 +360,8 @@ Providers: claude, codex, gemini, cursor`);
 
       try {
         // Check for --test-execution-report flag
-        if (subArgs.includes("--test-execution-report")) {
-          const remaining = subArgs.filter((a) => a !== "--test-execution-report");
+        if (subArgsWithoutForce.includes("--test-execution-report")) {
+          const remaining = subArgsWithoutForce.filter((a) => a !== "--test-execution-report");
           if (remaining.length > 0) {
             console.error(`Unknown option(s) for create issue --test-execution-report: ${remaining.join(" ")}`);
             printUsage();
@@ -304,7 +372,7 @@ Providers: claude, codex, gemini, cursor`);
           return;
         }
 
-        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(subArgs);
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(subArgsWithoutForce);
 
         if (postAgentArgs.length > 0) {
           console.error(`Unknown option(s) for create issue: ${postAgentArgs.join(" ")}`);
@@ -330,37 +398,67 @@ Providers: claude, codex, gemini, cursor`);
   }
 
   if (command === "define") {
-    if (args.length === 0 || args[0] !== "requirement") {
-      console.error(`Usage for define: nvst define requirement --agent <provider>`);
+    if (args.length === 0) {
+      console.error(`Usage for define: nvst define <requirement|refactor-plan> --agent <provider>`);
       printUsage();
       process.exitCode = 1;
       return;
     }
 
-    try {
-      const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+    const subcommand = args[0];
 
-      if (postAgentArgs.length > 0) {
-        console.error(`Unknown option(s) for define requirement: ${postAgentArgs.join(" ")}`);
+    if (subcommand === "requirement") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+        if (postForceArgs.length > 0) {
+          console.error(`Unknown option(s) for define requirement: ${postForceArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runDefineRequirement({ provider, force });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
         printUsage();
         process.exitCode = 1;
         return;
       }
+    }
 
-      await runDefineRequirement({ provider });
-      return;
-    } catch (error) {
-      console.error(error instanceof Error ? error.message : String(error));
-      printUsage();
-      process.exitCode = 1;
-      return;
+    if (subcommand === "refactor-plan") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+        if (postForceArgs.length > 0) {
+          console.error(`Unknown option(s) for define refactor-plan: ${postForceArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runDefineRefactorPlan({ provider, force });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
     }
+
+    console.error(`Unknown define subcommand: ${subcommand}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
   }
 
   if (command === "refine") {
     if (args.length === 0) {
       console.error(
-        `Usage for refine: nvst refine <requirement|project-context|test-plan> --agent <provider> [--challenge]`,
+        `Usage for refine: nvst refine <requirement|project-context|test-plan|refactor-plan> --agent <provider> [--challenge]`,
       );
       printUsage();
       process.exitCode = 1;
@@ -372,8 +470,9 @@ Providers: claude, codex, gemini, cursor`);
     if (subcommand === "requirement") {
       try {
         const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
-        const challenge = postAgentArgs.includes("--challenge");
-        const unknownArgs = postAgentArgs.filter((arg) => arg !== "--challenge");
+        const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+        const challenge = postForceArgs.includes("--challenge");
+        const unknownArgs = postForceArgs.filter((arg) => arg !== "--challenge");
 
         if (unknownArgs.length > 0) {
           console.error(`Unknown option(s) for refine requirement: ${unknownArgs.join(" ")}`);
@@ -382,7 +481,7 @@ Providers: claude, codex, gemini, cursor`);
           return;
         }
 
-        await runRefineRequirement({ provider, challenge });
+        await runRefineRequirement({ provider, challenge, force });
         return;
       } catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -395,8 +494,9 @@ Providers: claude, codex, gemini, cursor`);
     if (subcommand === "project-context") {
       try {
         const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
-        const challenge = postAgentArgs.includes("--challenge");
-        const unknownArgs = postAgentArgs.filter((arg) => arg !== "--challenge");
+        const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+        const challenge = postForceArgs.includes("--challenge");
+        const unknownArgs = postForceArgs.filter((arg) => arg !== "--challenge");
 
         if (unknownArgs.length > 0) {
           console.error(
@@ -407,7 +507,7 @@ Providers: claude, codex, gemini, cursor`);
           return;
         }
 
-        await runRefineProjectContext({ provider, challenge });
+        await runRefineProjectContext({ provider, challenge, force });
         return;
       } catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -420,8 +520,9 @@ Providers: claude, codex, gemini, cursor`);
     if (subcommand === "test-plan") {
       try {
         const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
-        const challenge = postAgentArgs.includes("--challenge");
-        const unknownArgs = postAgentArgs.filter((arg) => arg !== "--challenge");
+        const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+        const challenge = postForceArgs.includes("--challenge");
+        const unknownArgs = postForceArgs.filter((arg) => arg !== "--challenge");
 
         if (unknownArgs.length > 0) {
           console.error(`Unknown option(s) for refine test-plan: ${unknownArgs.join(" ")}`);
@@ -430,7 +531,31 @@ Providers: claude, codex, gemini, cursor`);
           return;
         }
 
-        await runRefineTestPlan({ provider, challenge });
+        await runRefineTestPlan({ provider, challenge, force });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
+    if (subcommand === "refactor-plan") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+        const challenge = postForceArgs.includes("--challenge");
+        const unknownArgs = postForceArgs.filter((arg) => arg !== "--challenge");
+
+        if (unknownArgs.length > 0) {
+          console.error(`Unknown option(s) for refine refactor-plan: ${unknownArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runRefineRefactorPlan({ provider, challenge, force });
         return;
       } catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -447,27 +572,44 @@ Providers: claude, codex, gemini, cursor`);
   }
 
   if (command === "approve") {
-    if (args.length !== 1) {
-      console.error(`Usage for approve: nvst approve <requirement|project-context|test-plan>`);
+    if (args.length === 0) {
+      console.error(`Usage for approve: nvst approve <requirement|project-context|test-plan|prototype|refactor-plan>`);
       printUsage();
       process.exitCode = 1;
       return;
     }
 
     const subcommand = args[0];
+    const { force, remainingArgs: unknownArgs } = parseForce(args.slice(1));
+    if (unknownArgs.length > 0) {
+      console.error(`Unknown option(s) for approve ${subcommand}: ${unknownArgs.join(" ")}`);
+      printUsage();
+      process.exitCode = 1;
+      return;
+    }
 
     if (subcommand === "requirement") {
-      await runApproveRequirement();
+      await runApproveRequirement({ force });
       return;
     }
 
     if (subcommand === "project-context") {
-      await runApproveProjectContext();
+      await runApproveProjectContext({ force });
       return;
     }
 
     if (subcommand === "test-plan") {
-      await runApproveTestPlan();
+      await runApproveTestPlan({ force });
+      return;
+    }
+
+    if (subcommand === "prototype") {
+      await runApprovePrototype({ force });
+      return;
+    }
+
+    if (subcommand === "refactor-plan") {
+      await runApproveRefactorPlan({ force });
       return;
     }
 
@@ -490,14 +632,15 @@ Providers: claude, codex, gemini, cursor`);
     if (subcommand === "test-plan") {
       try {
         const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
-        if (postAgentArgs.length > 0) {
-          console.error(`Unknown option(s) for execute test-plan: ${postAgentArgs.join(" ")}`);
+        const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+        if (postForceArgs.length > 0) {
+          console.error(`Unknown option(s) for execute test-plan: ${postForceArgs.join(" ")}`);
           printUsage();
           process.exitCode = 1;
           return;
         }
 
-        await runExecuteTestPlan({ provider });
+        await runExecuteTestPlan({ provider, force });
         return;
       } catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -516,11 +659,11 @@ Providers: claude, codex, gemini, cursor`);
         } = parseOptionalIntegerFlag(postAgentArgs, "--iterations", 1);
         const {
           value: retryOnFail,
-          remainingArgs: postRetryArgs,
+          remainingArgs: unknownArgs,
         } = parseOptionalIntegerFlag(postIterationsArgs, "--retry-on-fail", 0);
 
-        if (postRetryArgs.length > 0) {
-          console.error(`Unknown option(s) for execute automated-fix: ${postRetryArgs.join(" ")}`);
+        if (unknownArgs.length > 0) {
+          console.error(`Unknown option(s) for execute automated-fix: ${unknownArgs.join(" ")}`);
           printUsage();
           process.exitCode = 1;
           return;
@@ -539,8 +682,9 @@ Providers: claude, codex, gemini, cursor`);
     if (subcommand === "manual-fix") {
       try {
         const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
-        if (postAgentArgs.length > 0) {
-          console.error(`Unknown option(s) for execute manual-fix: ${postAgentArgs.join(" ")}`);
+        const { remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+        if (postForceArgs.length > 0) {
+          console.error(`Unknown option(s) for execute manual-fix: ${postForceArgs.join(" ")}`);
           printUsage();
           process.exitCode = 1;
           return;
@@ -556,6 +700,27 @@ Providers: claude, codex, gemini, cursor`);
       }
     }
 
+    if (subcommand === "refactor") {
+      try {
+        const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));
+        const { force, remainingArgs: postForceArgs } = parseForce(postAgentArgs);
+        if (postForceArgs.length > 0) {
+          console.error(`Unknown option(s) for execute refactor: ${postForceArgs.join(" ")}`);
+          printUsage();
+          process.exitCode = 1;
+          return;
+        }
+
+        await runExecuteRefactor({ provider, force });
+        return;
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        printUsage();
+        process.exitCode = 1;
+        return;
+      }
+    }
+
     console.error(`Unknown execute subcommand: ${subcommand}`);
     printUsage();
     process.exitCode = 1;
@@ -573,6 +738,10 @@ Providers: claude, codex, gemini, cursor`);
 }
 
 main().catch((error) => {
+  if (error instanceof GuardrailAbortError) {
+    // exitCode already set and "Aborted." already written by assertGuardrail
+    return;
+  }
   console.error("nvst failed:", error);
   process.exitCode = 1;
 });

package/src/commands/approve-project-context.ts

@@ -1,18 +1,25 @@
 import { join } from "node:path";
 
+import { assertGuardrail } from "../guardrail";
 import { exists, readState, writeState } from "../state";
 
-export async function runApproveProjectContext(): Promise<void> {
+export interface ApproveProjectContextOptions {
+    force?: boolean;
+}
+
+export async function runApproveProjectContext(opts: ApproveProjectContextOptions = {}): Promise<void> {
+    const { force = false } = opts;
     const projectRoot = process.cwd();
     const state = await readState(projectRoot);
 
     // US-002-AC01: Validate status is pending_approval
     const projectContext = state.phases.prototype.project_context;
-    if (projectContext.status !== "pending_approval") {
-        throw new Error(
-            `Cannot approve project context from status '${projectContext.status}'. Expected pending_approval.`,
-        );
-    }
+    await assertGuardrail(
+        state,
+        projectContext.status !== "pending_approval",
+        `Cannot approve project context from status '${projectContext.status}'. Expected pending_approval.`,
+        { force },
+    );
 
     // US-002-AC01: Validate project context file exists
     const contextFile = projectContext.file;