@quinteroac/agents-coding-toolkit 0.1.0-preview → 0.1.1-preview.0

package/src/commands/execute-refactor.ts

@@ -0,0 +1,336 @@
+import { $ } from "bun";
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { RefactorPrdSchema } from "../../scaffold/schemas/tmpl_refactor-prd";
+import {
+  RefactorExecutionProgressSchema,
+  type RefactorExecutionProgress,
+} from "../../scaffold/schemas/tmpl_refactor-execution-progress";
+import {
+  buildPrompt,
+  invokeAgent,
+  loadSkill,
+  type AgentInvokeOptions,
+  type AgentProvider,
+  type AgentResult,
+} from "../agent";
+import { CLI_PATH } from "../cli-path";
+import { assertGuardrail } from "../guardrail";
+import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
+
+export interface ExecuteRefactorOptions {
+  provider: AgentProvider;
+  force?: boolean;
+}
+
+export { RefactorExecutionProgressSchema };
+export type { RefactorExecutionProgress };
+
+interface WriteJsonResult {
+  exitCode: number;
+  stderr: string;
+}
+
+interface ExecuteRefactorDeps {
+  existsFn: (path: string) => Promise<boolean>;
+  invokeAgentFn: (options: AgentInvokeOptions) => Promise<AgentResult>;
+  invokeWriteJsonFn: (
+    projectRoot: string,
+    schemaName: string,
+    outPath: string,
+    data: string,
+  ) => Promise<WriteJsonResult>;
+  loadSkillFn: (projectRoot: string, skillName: string) => Promise<string>;
+  logFn: (message: string) => void;
+  nowFn: () => Date;
+  readFileFn: typeof readFile;
+  writeFileFn: typeof writeFile;
+}
+
+async function runWriteJsonCommand(
+  projectRoot: string,
+  schemaName: string,
+  outPath: string,
+  data: string,
+): Promise<WriteJsonResult> {
+  const result =
+    await $`bun ${CLI_PATH} write-json --schema ${schemaName} --out ${outPath} --data ${data}`
+      .cwd(projectRoot)
+      .nothrow()
+      .quiet();
+  return {
+    exitCode: result.exitCode,
+    stderr: result.stderr.toString().trim(),
+  };
+}
+
+const defaultDeps: ExecuteRefactorDeps = {
+  existsFn: exists,
+  invokeAgentFn: invokeAgent,
+  invokeWriteJsonFn: runWriteJsonCommand,
+  loadSkillFn: loadSkill,
+  logFn: console.log,
+  nowFn: () => new Date(),
+  readFileFn: readFile,
+  writeFileFn: writeFile,
+};
+
+export async function runExecuteRefactor(
+  opts: ExecuteRefactorOptions,
+  deps: Partial<ExecuteRefactorDeps> = {},
+): Promise<void> {
+  const mergedDeps: ExecuteRefactorDeps = { ...defaultDeps, ...deps };
+  const force = opts.force ?? false;
+  const projectRoot = process.cwd();
+  const state = await readState(projectRoot);
+
+  // AC02: Reject if current_phase !== "refactor"
+  await assertGuardrail(
+    state,
+    state.current_phase !== "refactor",
+    `Cannot execute refactor: current_phase must be 'refactor'. Current phase: '${state.current_phase}'.`,
+    { force },
+  );
+
+  // AC03: Reject if refactor_plan.status !== "approved"
+  await assertGuardrail(
+    state,
+    state.phases.refactor.refactor_plan.status !== "approved",
+    `Cannot execute refactor: refactor_plan.status must be 'approved'. Current status: '${state.phases.refactor.refactor_plan.status}'. Run \`bun nvst approve refactor-plan\` first.`,
+    { force },
+  );
+
+  // AC04: Reject if refactor_execution.status is already "completed"
+  await assertGuardrail(
+    state,
+    state.phases.refactor.refactor_execution.status === "completed",
+    "Cannot execute refactor: refactor_execution.status is already 'completed'.",
+    { force },
+  );
+
+  // AC05: Read and validate refactor-prd.json
+  const iteration = state.current_iteration;
+  const refactorPrdFileName = `it_${iteration}_refactor-prd.json`;
+  const refactorPrdPath = join(projectRoot, FLOW_REL_DIR, refactorPrdFileName);
+
+  if (!(await mergedDeps.existsFn(refactorPrdPath))) {
+    throw new Error(
+      `Refactor PRD file missing: expected ${join(FLOW_REL_DIR, refactorPrdFileName)}. Run \`bun nvst approve refactor-plan\` first.`,
+    );
+  }
+
+  let parsedPrd: unknown;
+  try {
+    parsedPrd = JSON.parse(await mergedDeps.readFileFn(refactorPrdPath, "utf8"));
+  } catch {
+    throw new Error(
+      `Invalid refactor PRD JSON in ${join(FLOW_REL_DIR, refactorPrdFileName)}.`,
+    );
+  }
+
+  const prdValidation = RefactorPrdSchema.safeParse(parsedPrd);
+  if (!prdValidation.success) {
+    throw new Error(
+      `Refactor PRD schema mismatch in ${join(FLOW_REL_DIR, refactorPrdFileName)}.`,
+    );
+  }
+
+  const refactorItems = prdValidation.data.refactorItems;
+
+  // Load skill
+  let skillTemplate: string;
+  try {
+    skillTemplate = await mergedDeps.loadSkillFn(projectRoot, "execute-refactor-item");
+  } catch {
+    throw new Error(
+      "Required skill missing: expected .agents/skills/execute-refactor-item/SKILL.md.",
+    );
+  }
+
+  // AC13: Progress file name
+  const progressFileName = `it_${iteration}_refactor-execution-progress.json`;
+  const progressPath = join(projectRoot, FLOW_REL_DIR, progressFileName);
+
+  // AC06: Set refactor_execution.status = "in_progress" before processing
+  // AC13: Set refactor_execution.file
+  state.phases.refactor.refactor_execution.status = "in_progress";
+  state.phases.refactor.refactor_execution.file = progressFileName;
+  state.last_updated = mergedDeps.nowFn().toISOString();
+  state.updated_by = "nvst:execute-refactor";
+  await writeState(projectRoot, state);
+
+  // Initialize or load progress file
+  let progressData: RefactorExecutionProgress;
+
+  if (await mergedDeps.existsFn(progressPath)) {
+    let parsedProgress: unknown;
+    try {
+      parsedProgress = JSON.parse(await mergedDeps.readFileFn(progressPath, "utf8"));
+    } catch {
+      throw new Error(
+        `Invalid progress JSON in ${join(FLOW_REL_DIR, progressFileName)}.`,
+      );
+    }
+
+    const progressValidation = RefactorExecutionProgressSchema.safeParse(parsedProgress);
+    if (!progressValidation.success) {
+      throw new Error(
+        `Progress schema mismatch in ${join(FLOW_REL_DIR, progressFileName)}.`,
+      );
+    }
+
+    // AC05: Verify progress item IDs match refactor PRD item IDs
+    const expectedIds = [...refactorItems.map((item) => item.id)].sort((a, b) => a.localeCompare(b));
+    const existingIds = [...progressValidation.data.entries.map((entry) => entry.id)].sort((a, b) => a.localeCompare(b));
+    if (
+      expectedIds.length !== existingIds.length ||
+      expectedIds.some((id, i) => id !== existingIds[i])
+    ) {
+      throw new Error(
+        "Refactor execution progress file out of sync: entry ids do not match refactor PRD item ids.",
+      );
+    }
+
+    progressData = progressValidation.data;
+  } else {
+    const now = mergedDeps.nowFn().toISOString();
+    progressData = {
+      entries: refactorItems.map((item) => ({
+        id: item.id,
+        title: item.title,
+        status: "pending" as const,
+        attempt_count: 0,
+        last_agent_exit_code: null,
+        updated_at: now,
+      })),
+    };
+    const writeResult = await mergedDeps.invokeWriteJsonFn(
+      projectRoot,
+      "refactor-execution-progress",
+      join(FLOW_REL_DIR, progressFileName),
+      JSON.stringify(progressData),
+    );
+    if (writeResult.exitCode !== 0) {
+      throw new Error(
+        `Failed to write refactor execution progress: ${writeResult.stderr || "write-json exited non-zero"}.`,
+      );
+    }
+  }
+
+  // AC07, AC08, AC09, AC10: Process each item in order
+  for (const item of refactorItems) {
+    const entry = progressData.entries.find((e) => e.id === item.id);
+    if (!entry || entry.status === "completed") {
+      continue;
+    }
+
+    // Set current item to in_progress before invoking agent (FR-4; observability on interrupt)
+    entry.status = "in_progress";
+    entry.updated_at = mergedDeps.nowFn().toISOString();
+    const writeInProgressResult = await mergedDeps.invokeWriteJsonFn(
+      projectRoot,
+      "refactor-execution-progress",
+      join(FLOW_REL_DIR, progressFileName),
+      JSON.stringify(progressData),
+    );
+    if (writeInProgressResult.exitCode !== 0) {
+      throw new Error(
+        `Failed to write refactor execution progress: ${writeInProgressResult.stderr || "write-json exited non-zero"}.`,
+      );
+    }
+
+    // AC07: Build prompt with skill and item context (FR-6 variable names)
+    const prompt = buildPrompt(skillTemplate, {
+      current_iteration: iteration,
+      item_id: item.id,
+      item_title: item.title,
+      item_description: item.description,
+      item_rationale: item.rationale,
+    });
+
+    // AC08: Invoke agent in interactive mode
+    const agentResult = await mergedDeps.invokeAgentFn({
+      provider: opts.provider,
+      prompt,
+      cwd: projectRoot,
+      interactive: true,
+    });
+
+    // AC09 & AC10: Record result after each invocation, continue on failure
+    const succeeded = agentResult.exitCode === 0;
+    entry.status = succeeded ? "completed" : "failed";
+    entry.attempt_count = entry.attempt_count + 1;
+    entry.last_agent_exit_code = agentResult.exitCode;
+    entry.updated_at = mergedDeps.nowFn().toISOString();
+
+    const writeResult = await mergedDeps.invokeWriteJsonFn(
+      projectRoot,
+      "refactor-execution-progress",
+      join(FLOW_REL_DIR, progressFileName),
+      JSON.stringify(progressData),
+    );
+    if (writeResult.exitCode !== 0) {
+      throw new Error(
+        `Failed to write refactor execution progress: ${writeResult.stderr || "write-json exited non-zero"}.`,
+      );
+    }
+
+    mergedDeps.logFn(
+      `iteration=it_${iteration} item=${item.id} outcome=${entry.status}`,
+    );
+  }
+
+  // US-003: Generate markdown execution report (written regardless of failures)
+  const reportFileName = `it_${iteration}_refactor-execution-report.md`;
+  const reportPath = join(projectRoot, FLOW_REL_DIR, reportFileName);
+  const reportContent = buildRefactorExecutionReport(iteration, progressData);
+  await mergedDeps.writeFileFn(reportPath, reportContent, "utf8");
+
+  // AC11 & AC12: Update state based on overall result
+  const allCompleted = progressData.entries.every((entry) => entry.status === "completed");
+
+  if (allCompleted) {
+    // AC11: All completed → set status to "completed"
+    state.phases.refactor.refactor_execution.status = "completed";
+  }
+  // AC12: Any failure → stays "in_progress" (already set above)
+
+  state.last_updated = mergedDeps.nowFn().toISOString();
+  state.updated_by = "nvst:execute-refactor";
+  await writeState(projectRoot, state);
+
+  if (allCompleted) {
+    mergedDeps.logFn("Refactor execution completed for all items.");
+  } else {
+    mergedDeps.logFn("Refactor execution paused with remaining pending or failed items.");
+  }
+}
+
+export function buildRefactorExecutionReport(
+  iteration: string,
+  progress: RefactorExecutionProgress,
+): string {
+  const total = progress.entries.length;
+  const completed = progress.entries.filter((e) => e.status === "completed").length;
+  const failed = progress.entries.filter((e) => e.status === "failed").length;
+
+  const tableRows = progress.entries
+    .map((e) => {
+      const exitCode = e.last_agent_exit_code === null ? "N/A" : String(e.last_agent_exit_code);
+      return `| ${e.id} | ${e.title} | ${e.status} | ${exitCode} |`;
+    })
+    .join("\n");
+
+  return `# Refactor Execution Report
+
+**Iteration:** it_${iteration}
+**Total:** ${total}
+**Completed:** ${completed}
+**Failed:** ${failed}
+
+| RI ID | Title | Status | Agent Exit Code |
+|-------|-------|--------|-----------------|
+${tableRows}
+`;
+}

package/src/commands/execute-test-plan.test.ts

@@ -114,7 +114,7 @@ describe("execute test-plan command", () => {
     expect(source).toContain("if (command === \"execute\") {");
     expect(source).toContain('if (subcommand === "test-plan") {');
     expect(source).toContain("const { provider, remainingArgs: postAgentArgs } = parseAgentArg(args.slice(1));");
-    expect(source).toContain("await runExecuteTestPlan({ provider });");
+    expect(source).toContain("await runExecuteTestPlan({ provider, force });");
     expect(source).toContain("execute test-plan --agent <provider>");
   });
 
@@ -324,6 +324,7 @@ describe("execute test-plan command", () => {
 
     const state = await readState(projectRoot);
     expect(state.phases.prototype.test_execution.status).toBe("completed");
+    expect(state.phases.prototype.prototype_approved).toBe(true);
     expect(state.updated_by).toBe("nvst:execute-test-plan");
   });
 
@@ -537,6 +538,10 @@ describe("execute test-plan command", () => {
       expect(rerunBatchPrompt).not.toContain("TC-US001-01");
     });
 
+    // After retry, all pass -> prototype approved
+    const stateAfterRetry = await readState(projectRoot);
+    expect(stateAfterRetry.phases.prototype.prototype_approved).toBe(true);
+
     const progressRaw = await readFile(
       join(projectRoot, ".agents", "flow", "it_000005_test-execution-progress.json"),
       "utf8",
@@ -1736,10 +1741,11 @@ describe("US-004: preserve report and state tracking compatibility", () => {
     expect(stateSnapshots[0]!.status).toBe("in_progress");
     expect(stateSnapshots[0]!.file).toBe("it_000005_test-execution-progress.json");
 
-    // After execution (all passed): completed
+    // After execution (all passed): completed and prototype approved
     const finalState = await readState(projectRoot);
     expect(finalState.phases.prototype.test_execution.status).toBe("completed");
     expect(finalState.phases.prototype.test_execution.file).toBe("it_000005_test-execution-progress.json");
+    expect(finalState.phases.prototype.prototype_approved).toBe(true);
     expect(finalState.updated_by).toBe("nvst:execute-test-plan");
   });
 
@@ -1779,6 +1785,7 @@ describe("US-004: preserve report and state tracking compatibility", () => {
 
     const finalState = await readState(projectRoot);
     expect(finalState.phases.prototype.test_execution.status).toBe("failed");
+    expect(finalState.phases.prototype.prototype_approved).toBe(false);
     expect(finalState.phases.prototype.test_execution.file).toBe("it_000005_test-execution-progress.json");
     expect(finalState.updated_by).toBe("nvst:execute-test-plan");
   });

package/src/commands/execute-test-plan.ts

@@ -11,12 +11,14 @@ import {
   type AgentProvider,
   type AgentResult,
 } from "../agent";
+import { assertGuardrail } from "../guardrail";
 import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
-import { TestPlanSchema, type TestPlan } from "../../schemas/test-plan";
+import { TestPlanSchema, type TestPlan } from "../../scaffold/schemas/tmpl_test-plan";
 import { extractJson } from "./create-issue";
 
 export interface ExecuteTestPlanOptions {
   provider: AgentProvider;
+  force?: boolean;
 }
 
 const ExecutionPayloadSchema = z.object({
@@ -321,13 +323,15 @@ export async function runExecuteTestPlan(
   const projectRoot = process.cwd();
   const mergedDeps: ExecuteTestPlanDeps = { ...defaultDeps, ...deps };
   const state = await readState(projectRoot);
+  const force = opts.force ?? false;
 
   const tpGeneration = state.phases.prototype.tp_generation;
-  if (tpGeneration.status !== "created") {
-    throw new Error(
-      `Cannot execute test plan: prototype.tp_generation.status must be created. Current status: '${tpGeneration.status}'. Run \`bun nvst approve test-plan\` first.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    tpGeneration.status !== "created",
+    `Cannot execute test plan: prototype.tp_generation.status must be created. Current status: '${tpGeneration.status}'. Run \`bun nvst approve test-plan\` first.`,
+    { force },
+  );
 
   if (!tpGeneration.file) {
     throw new Error("Cannot execute test plan: prototype.tp_generation.file is missing.");
@@ -710,6 +714,9 @@ export async function runExecuteTestPlan(
   const hasFailedTests = progress.entries.some((entry) => entry.status === "failed");
   state.phases.prototype.test_execution.status = hasFailedTests ? "failed" : "completed";
   state.phases.prototype.test_execution.file = progressFileName;
+  if (!hasFailedTests) {
+    state.phases.prototype.prototype_approved = true;
+  }
   state.last_updated = mergedDeps.nowFn().toISOString();
   state.updated_by = "nvst:execute-test-plan";
   await writeState(projectRoot, state);

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

@@ -2,26 +2,28 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 
 import { buildPrompt, invokeAgent, loadSkill, type AgentProvider } from "../agent";
+import { assertGuardrail } from "../guardrail";
 import { exists, readState, writeState } from "../state";
 
 export interface RefineProjectContextOptions {
     provider: AgentProvider;
     challenge: boolean;
+    force?: boolean;
 }
 
 export async function runRefineProjectContext(opts: RefineProjectContextOptions): Promise<void> {
-    const { provider, challenge } = opts;
+    const { provider, challenge, force = false } = opts;
     const projectRoot = process.cwd();
     const state = await readState(projectRoot);
 
     // US-003-AC01: Validate status is pending_approval or created
     const projectContext = state.phases.prototype.project_context;
-    if (projectContext.status !== "pending_approval" && projectContext.status !== "created") {
-        throw new Error(
-            `Cannot refine project context from status '${projectContext.status}'. ` +
-            "Expected pending_approval or created.",
-        );
-    }
+    await assertGuardrail(
+        state,
+        projectContext.status !== "pending_approval" && projectContext.status !== "created",
+        `Cannot refine project context from status '${projectContext.status}'. Expected pending_approval or created.`,
+        { force },
+    );
 
     // Validate file reference exists in state
     const contextFile = projectContext.file;

package/src/commands/refine-refactor-plan.test.ts

@@ -0,0 +1,210 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import type { AgentResult } from "../agent";
+import { readState, writeState } from "../state";
+import { runRefineRefactorPlan } from "./refine-refactor-plan";
+
+async function createProjectRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "nvst-refine-refactor-plan-"));
+}
+
+async function withCwd<T>(cwd: string, fn: () => Promise<T>): Promise<T> {
+  const previous = process.cwd();
+  process.chdir(cwd);
+  try {
+    return await fn();
+  } finally {
+    process.chdir(previous);
+  }
+}
+
+async function seedState(
+  projectRoot: string,
+  status: "pending" | "pending_approval" | "approved",
+  file: string | null,
+): Promise<void> {
+  await mkdir(join(projectRoot, ".agents", "flow"), { recursive: true });
+
+  await writeState(projectRoot, {
+    current_iteration: "000013",
+    current_phase: "refactor",
+    phases: {
+      define: {
+        requirement_definition: { status: "approved", file: "it_000013_product-requirement-document.md" },
+        prd_generation: { status: "completed", file: "it_000013_PRD.json" },
+      },
+      prototype: {
+        project_context: { status: "created", file: ".agents/PROJECT_CONTEXT.md" },
+        test_plan: { status: "created", file: "it_000013_test-plan.md" },
+        tp_generation: { status: "created", file: "it_000013_TEST-PLAN.json" },
+        prototype_build: { status: "created", file: "it_000013_progress.json" },
+        test_execution: { status: "completed", file: "it_000013_test-execution-report.json" },
+        prototype_approved: true,
+      },
+      refactor: {
+        evaluation_report: { status: "created", file: "it_000013_evaluation-report.md" },
+        refactor_plan: { status, file },
+        refactor_execution: { status: "pending", file: null },
+        changelog: { status: "pending", file: null },
+      },
+    },
+    last_updated: "2026-02-26T00:00:00.000Z",
+    updated_by: "seed",
+    history: [],
+  });
+}
+
+const createdRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(createdRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("refine refactor-plan command", () => {
+  test("registers refine refactor-plan command in CLI dispatch", async () => {
+    const source = await readFile(join(process.cwd(), "src", "cli.ts"), "utf8");
+
+    expect(source).toContain('import { runRefineRefactorPlan } from "./commands/refine-refactor-plan";');
+    expect(source).toContain('if (subcommand === "refactor-plan") {');
+    expect(source).toContain('const challenge = postForceArgs.includes("--challenge");');
+    expect(source).toContain("await runRefineRefactorPlan({ provider, challenge, force });");
+  });
+
+  test("requires refactor.refactor_plan.status to be pending_approval", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "approved", "it_000013_refactor-plan.md");
+
+    await withCwd(projectRoot, async () => {
+      await expect(
+        runRefineRefactorPlan(
+          { provider: "codex", challenge: false },
+          {
+            loadSkillFn: async () => "unused",
+            invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          },
+        ),
+      ).rejects.toThrow(
+        "Cannot refine refactor plan from status 'approved'. Expected pending_approval.",
+      );
+    });
+  });
+
+  test("rejects when refactor.refactor_plan.file is missing", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending_approval", null);
+
+    await withCwd(projectRoot, async () => {
+      await expect(
+        runRefineRefactorPlan(
+          { provider: "codex", challenge: false },
+          {
+            loadSkillFn: async () => "unused",
+            invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          },
+        ),
+      ).rejects.toThrow("Cannot refine refactor plan: refactor.refactor_plan.file is missing.");
+    });
+  });
+
+  test("rejects when refactor plan file does not exist on disk", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending_approval", "it_000013_refactor-plan.md");
+
+    await withCwd(projectRoot, async () => {
+      await expect(
+        runRefineRefactorPlan(
+          { provider: "codex", challenge: false },
+          {
+            loadSkillFn: async () => "unused",
+            invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          },
+        ),
+      ).rejects.toThrow("Cannot refine refactor plan: file not found at");
+    });
+  });
+
+  test("loads refine-refactor-plan skill, reads file context, invokes interactively, and does not mutate state", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending_approval", "it_000013_refactor-plan.md");
+
+    const refactorPlanPath = join(projectRoot, ".agents", "flow", "it_000013_refactor-plan.md");
+    await writeFile(refactorPlanPath, "# Current Refactor Plan\n- Refactor module A\n", "utf8");
+
+    let loadedSkill = "";
+    let invocation: { interactive: boolean | undefined; prompt: string } | undefined;
+    const stateBefore = JSON.stringify(await readState(projectRoot));
+
+    await withCwd(projectRoot, async () => {
+      await runRefineRefactorPlan(
+        { provider: "codex", challenge: false },
+        {
+          loadSkillFn: async (_root, skillName) => {
+            loadedSkill = skillName;
+            return "Refine refactor plan skill";
+          },
+          invokeAgentFn: async (options): Promise<AgentResult> => {
+            invocation = {
+              interactive: options.interactive,
+              prompt: options.prompt,
+            };
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+        },
+      );
+    });
+
+    expect(loadedSkill).toBe("refine-refactor-plan");
+    if (invocation === undefined) {
+      throw new Error("Agent invocation was not captured");
+    }
+
+    expect(invocation.interactive).toBe(true);
+    expect(invocation.prompt).toContain("### current_iteration");
+    expect(invocation.prompt).toContain("000013");
+    expect(invocation.prompt).toContain("### refactor_plan_file");
+    expect(invocation.prompt).toContain("it_000013_refactor-plan.md");
+    expect(invocation.prompt).toContain("### refactor_plan_content");
+    expect(invocation.prompt).toContain("# Current Refactor Plan");
+
+    const stateAfter = JSON.stringify(await readState(projectRoot));
+    expect(stateAfter).toBe(stateBefore);
+  });
+
+  test("passes mode=challenger in prompt context when challenge mode is enabled", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, "pending_approval", "it_000013_refactor-plan.md");
+
+    const refactorPlanPath = join(projectRoot, ".agents", "flow", "it_000013_refactor-plan.md");
+    await writeFile(refactorPlanPath, "# Current Refactor Plan\n- Refactor module B\n", "utf8");
+
+    let invocationPrompt = "";
+    const stateBefore = JSON.stringify(await readState(projectRoot));
+
+    await withCwd(projectRoot, async () => {
+      await runRefineRefactorPlan(
+        { provider: "codex", challenge: true },
+        {
+          loadSkillFn: async () => "Refine refactor plan skill",
+          invokeAgentFn: async (options): Promise<AgentResult> => {
+            invocationPrompt = options.prompt;
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+        },
+      );
+    });
+
+    expect(invocationPrompt).toContain("### mode");
+    expect(invocationPrompt).toContain("challenger");
+
+    const stateAfter = JSON.stringify(await readState(projectRoot));
+    expect(stateAfter).toBe(stateBefore);
+  });
+});