@quinteroac/agents-coding-toolkit 0.1.0-preview

package/src/commands/execute-automated-fix.ts

@@ -0,0 +1,363 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { $ as dollar } from "bun";
+
+import {
+  buildPrompt,
+  invokeAgent,
+  loadSkill,
+  type AgentInvokeOptions,
+  type AgentProvider,
+  type AgentResult,
+} from "../agent";
+import { exists, FLOW_REL_DIR, readState } from "../state";
+import { type Issue } from "../../scaffold/schemas/tmpl_issues";
+
+export interface ExecuteAutomatedFixOptions {
+  provider: AgentProvider;
+  iterations?: number;
+  retryOnFail?: number;
+}
+
+interface ExecuteAutomatedFixDeps {
+  existsFn: (path: string) => Promise<boolean>;
+  invokeAgentFn: (options: AgentInvokeOptions) => Promise<AgentResult>;
+  loadSkillFn: (projectRoot: string, skillName: string) => Promise<string>;
+  logFn: (message: string) => void;
+  nowFn: () => Date;
+  readFileFn: typeof readFile;
+  runCommitFn: (projectRoot: string, message: string) => Promise<number>;
+  writeFileFn: typeof writeFile;
+}
+
+const defaultDeps: ExecuteAutomatedFixDeps = {
+  existsFn: exists,
+  invokeAgentFn: invokeAgent,
+  loadSkillFn: loadSkill,
+  logFn: console.log,
+  nowFn: () => new Date(),
+  readFileFn: readFile,
+  runCommitFn: async (projectRoot: string, message: string) => {
+    const result = await dollar`git add -A && git commit -m ${message}`
+      .cwd(projectRoot)
+      .nothrow()
+      .quiet();
+    return result.exitCode;
+  },
+  writeFileFn: writeFile,
+};
+
+function isNetworkErrorText(text: string): boolean {
+  const normalized = text.toLowerCase();
+  return [
+    "network",
+    "econnrefused",
+    "enotfound",
+    "eai_again",
+    "timed out",
+    "timeout",
+    "connection reset",
+    "connection refused",
+  ].some((token) => normalized.includes(token));
+}
+
+function isNetworkError(error: unknown): boolean {
+  if (error instanceof Error) {
+    return isNetworkErrorText(error.message);
+  }
+  return isNetworkErrorText(String(error));
+}
+
+function sortIssuesById(issues: Issue[]): Issue[] {
+  return [...issues].sort((left, right) => left.id.localeCompare(right.id));
+}
+
+const ALLOWED_ISSUE_STATUSES: Set<Issue["status"]> = new Set([
+  "open",
+  "fixed",
+  "retry",
+  "manual-fix",
+]);
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function parseIssuesForProcessing(
+  raw: unknown,
+  flowRelativePath: string,
+  logFn: (message: string) => void,
+): Issue[] {
+  if (!Array.isArray(raw)) {
+    throw new Error(
+      `Deterministic validation error: issues schema mismatch in ${flowRelativePath}.`,
+    );
+  }
+
+  const parsedIssues: Issue[] = [];
+  const seenIds = new Set<string>();
+
+  for (const [index, item] of raw.entries()) {
+    const issue = asRecord(item);
+    if (!issue) {
+      logFn(
+        `Warning: Skipping invalid issue at index ${index} in ${flowRelativePath}: expected an object.`,
+      );
+      continue;
+    }
+
+    const id = issue.id;
+    const title = issue.title;
+    const description = issue.description;
+    const status = issue.status;
+
+    const missingFields: string[] = [];
+    if (typeof id !== "string") {
+      missingFields.push("id");
+    }
+    if (typeof title !== "string") {
+      missingFields.push("title");
+    }
+    if (typeof description !== "string") {
+      missingFields.push("description");
+    }
+    if (typeof status !== "string") {
+      missingFields.push("status");
+    }
+
+    if (missingFields.length > 0) {
+      logFn(
+        `Warning: Skipping issue at index ${index} in ${flowRelativePath}: missing required field(s): ${missingFields.join(", ")}.`,
+      );
+      continue;
+    }
+
+    const validId = id as string;
+    const validTitle = title as string;
+    const validDescription = description as string;
+    const validStatus = status as Issue["status"];
+
+    if (!ALLOWED_ISSUE_STATUSES.has(validStatus)) {
+      logFn(
+        `Warning: Skipping issue ${validId} in ${flowRelativePath}: invalid status '${status}'.`,
+      );
+      continue;
+    }
+
+    if (seenIds.has(validId)) {
+      logFn(
+        `Warning: Skipping duplicate issue id '${validId}' in ${flowRelativePath}.`,
+      );
+      continue;
+    }
+
+    seenIds.add(validId);
+    parsedIssues.push({
+      id: validId,
+      title: validTitle,
+      description: validDescription,
+      status: validStatus,
+    });
+  }
+
+  return parsedIssues;
+}
+
+async function writeIssuesFile(
+  issuesPath: string,
+  issues: Issue[],
+  deps: ExecuteAutomatedFixDeps,
+): Promise<void> {
+  await deps.writeFileFn(issuesPath, `${JSON.stringify(issues, null, 2)}\n`, "utf8");
+}
+
+async function commitIssueUpdate(
+  projectRoot: string,
+  issueId: string,
+  issueStatus: Issue["status"],
+  deps: ExecuteAutomatedFixDeps,
+): Promise<boolean> {
+  const commitMessage = `fix: automated-fix ${issueId} -> ${issueStatus}`;
+  const exitCode = await deps.runCommitFn(projectRoot, commitMessage);
+  return exitCode === 0;
+}
+
+export async function runExecuteAutomatedFix(
+  opts: ExecuteAutomatedFixOptions,
+  deps: Partial<ExecuteAutomatedFixDeps> = {},
+): Promise<void> {
+  if (opts.iterations !== undefined && (!Number.isInteger(opts.iterations) || opts.iterations < 1)) {
+    throw new Error("Invalid --iterations value. Expected an integer >= 1.");
+  }
+
+  if (
+    opts.retryOnFail !== undefined &&
+    (!Number.isInteger(opts.retryOnFail) || opts.retryOnFail < 0)
+  ) {
+    throw new Error("Invalid --retry-on-fail value. Expected an integer >= 0.");
+  }
+
+  const mergedDeps = { ...defaultDeps, ...deps };
+  const projectRoot = process.cwd();
+  const state = await readState(projectRoot);
+
+  const iteration = state.current_iteration;
+  const fileName = `it_${iteration}_ISSUES.json`;
+  const issuesPath = join(projectRoot, FLOW_REL_DIR, fileName);
+
+  if (!(await mergedDeps.existsFn(issuesPath))) {
+    throw new Error(
+      `Issues file not found: expected ${join(FLOW_REL_DIR, fileName)}. Run \`bun nvst create issue --agent <provider>\` first.`,
+    );
+  }
+
+  let parsedIssuesRaw: unknown;
+  const flowRelativePath = join(FLOW_REL_DIR, fileName);
+  try {
+    parsedIssuesRaw = JSON.parse(await mergedDeps.readFileFn(issuesPath, "utf8"));
+  } catch {
+    throw new Error(
+      `Deterministic validation error: invalid issues JSON in ${flowRelativePath}.`,
+    );
+  }
+
+  const issues = sortIssuesById(parseIssuesForProcessing(parsedIssuesRaw, flowRelativePath, mergedDeps.logFn));
+  const openIssues = issues.filter((issue) => issue.status === "open");
+
+  if (openIssues.length === 0) {
+    mergedDeps.logFn("No open issues to process. Exiting without changes.");
+    return;
+  }
+
+  const skillTemplate = await mergedDeps.loadSkillFn(projectRoot, "automated-fix");
+  const maxIssuesToProcess = opts.iterations ?? 1;
+  const issuesToProcess = openIssues.slice(0, maxIssuesToProcess);
+  const maxRetries = opts.retryOnFail ?? 0;
+
+  let fixedCount = 0;
+  let failedCount = 0;
+
+  for (const issue of issuesToProcess) {
+    let retriesRemaining = maxRetries;
+
+    while (true) {
+      const prompt = buildPrompt(skillTemplate, {
+        iteration,
+        issue: JSON.stringify(issue, null, 2),
+      });
+
+      let result: AgentResult | null = null;
+      let invocationError: unknown = null;
+
+      try {
+        result = await mergedDeps.invokeAgentFn({
+          provider: opts.provider,
+          prompt,
+          cwd: projectRoot,
+          interactive: false,
+        });
+      } catch (error) {
+        invocationError = error;
+      }
+
+      if (invocationError) {
+        if (isNetworkError(invocationError)) {
+          issue.status = "manual-fix";
+          await writeIssuesFile(issuesPath, issues, mergedDeps);
+
+          const committed = await commitIssueUpdate(projectRoot, issue.id, issue.status, mergedDeps);
+          if (!committed) {
+            mergedDeps.logFn(`${issue.id}: Failed`);
+            mergedDeps.logFn(`Error: git commit failed for ${issue.id}`);
+          } else {
+            mergedDeps.logFn(`${issue.id}: Failed`);
+          }
+          failedCount += 1;
+          break;
+        }
+
+        if (retriesRemaining > 0) {
+          retriesRemaining -= 1;
+          issue.status = "retry";
+          await writeIssuesFile(issuesPath, issues, mergedDeps);
+          continue;
+        }
+
+        issue.status = "manual-fix";
+        await writeIssuesFile(issuesPath, issues, mergedDeps);
+
+        const committed = await commitIssueUpdate(projectRoot, issue.id, issue.status, mergedDeps);
+        if (!committed) {
+          mergedDeps.logFn(`${issue.id}: Failed`);
+          mergedDeps.logFn(`Error: git commit failed for ${issue.id}`);
+        } else {
+          mergedDeps.logFn(`${issue.id}: Failed`);
+        }
+
+        failedCount += 1;
+        break;
+      }
+
+      if (result === null) {
+        throw new Error("Agent invocation produced no result.");
+      }
+
+      if (result.exitCode === 0) {
+        issue.status = "fixed";
+        await writeIssuesFile(issuesPath, issues, mergedDeps);
+
+        const committed = await commitIssueUpdate(projectRoot, issue.id, issue.status, mergedDeps);
+        if (!committed) {
+          mergedDeps.logFn(`${issue.id}: Failed`);
+          mergedDeps.logFn(`Error: git commit failed for ${issue.id}`);
+          failedCount += 1;
+        } else {
+          mergedDeps.logFn(`${issue.id}: Fixed`);
+          fixedCount += 1;
+        }
+        break;
+      }
+
+      if (isNetworkErrorText(`${result.stderr}\n${result.stdout}`)) {
+        issue.status = "manual-fix";
+        await writeIssuesFile(issuesPath, issues, mergedDeps);
+
+        const committed = await commitIssueUpdate(projectRoot, issue.id, issue.status, mergedDeps);
+        if (!committed) {
+          mergedDeps.logFn(`${issue.id}: Failed`);
+          mergedDeps.logFn(`Error: git commit failed for ${issue.id}`);
+        } else {
+          mergedDeps.logFn(`${issue.id}: Failed`);
+        }
+        failedCount += 1;
+        break;
+      }
+
+      if (retriesRemaining > 0) {
+        retriesRemaining -= 1;
+        issue.status = "retry";
+        await writeIssuesFile(issuesPath, issues, mergedDeps);
+        continue;
+      }
+
+      issue.status = "manual-fix";
+      await writeIssuesFile(issuesPath, issues, mergedDeps);
+
+      const committed = await commitIssueUpdate(projectRoot, issue.id, issue.status, mergedDeps);
+      if (!committed) {
+        mergedDeps.logFn(`${issue.id}: Failed`);
+        mergedDeps.logFn(`Error: git commit failed for ${issue.id}`);
+      } else {
+        mergedDeps.logFn(`${issue.id}: Failed`);
+      }
+      failedCount += 1;
+      break;
+    }
+  }
+
+  mergedDeps.logFn(`Summary: Fixed=${fixedCount} Failed=${failedCount}`);
+  mergedDeps.logFn(`Processed ${issuesToProcess.length} open issue(s) at ${mergedDeps.nowFn().toISOString()}`);
+}

package/src/commands/execute-manual-fix.test.ts

@@ -0,0 +1,343 @@
+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 { writeState } from "../state";
+import { buildManualFixGuidancePrompt, runExecuteManualFix } from "./execute-manual-fix";
+
+async function createProjectRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "nvst-execute-manual-fix-"));
+}
+
+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, iteration = "000010") {
+  await mkdir(join(projectRoot, ".agents", "flow"), { recursive: true });
+  await writeState(projectRoot, {
+    current_iteration: iteration,
+    current_phase: "prototype",
+    phases: {
+      define: {
+        requirement_definition: { status: "approved", file: `it_${iteration}_product-requirement-document.md` },
+        prd_generation: { status: "completed", file: `it_${iteration}_PRD.json` },
+      },
+      prototype: {
+        project_context: { status: "created", file: ".agents/PROJECT_CONTEXT.md" },
+        test_plan: { status: "pending", file: null },
+        tp_generation: { status: "pending", file: null },
+        prototype_build: { status: "pending", file: null },
+        test_execution: { status: "pending", file: null },
+        prototype_approved: false,
+      },
+      refactor: {
+        evaluation_report: { status: "pending", file: null },
+        refactor_plan: { status: "pending", file: null },
+        refactor_execution: { status: "pending", file: null },
+        changelog: { status: "pending", file: null },
+      },
+    },
+    last_updated: "2026-02-23T00:00:00.000Z",
+    updated_by: "seed",
+    history: [],
+  });
+}
+
+async function writeIssues(projectRoot: string, iteration: string, data: unknown) {
+  const issuesPath = join(projectRoot, ".agents", "flow", `it_${iteration}_ISSUES.json`);
+  await writeFile(issuesPath, `${JSON.stringify(data, null, 2)}\n`, "utf8");
+  return issuesPath;
+}
+
+const createdRoots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(createdRoots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+describe("execute manual-fix command", () => {
+  test("registers execute manual-fix command in CLI", async () => {
+    const source = await readFile(join(process.cwd(), "src", "cli.ts"), "utf8");
+
+    expect(source).toContain('import { runExecuteManualFix } from "./commands/execute-manual-fix";');
+    expect(source).toContain('if (subcommand === "manual-fix") {');
+    expect(source).toContain("await runExecuteManualFix({ provider });");
+    expect(source).toContain("execute manual-fix --agent <provider>");
+  });
+
+  test("CLI exits with code 1 when --agent is missing", async () => {
+    const proc = Bun.spawn(
+      ["bun", "run", "src/cli.ts", "execute", "manual-fix"],
+      { cwd: process.cwd(), stdout: "pipe", stderr: "pipe" },
+    );
+    const exitCode = await proc.exited;
+    const stderr = await new Response(proc.stderr).text();
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Missing required --agent <provider> argument.");
+  });
+
+  test("CLI accepts --agent and rejects unknown providers", async () => {
+    const proc = Bun.spawn(
+      ["bun", "run", "src/cli.ts", "execute", "manual-fix", "--agent", "invalid-provider"],
+      { cwd: process.cwd(), stdout: "pipe", stderr: "pipe" },
+    );
+    const exitCode = await proc.exited;
+    const stderr = await new Response(proc.stderr).text();
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Unknown agent provider");
+  });
+
+  test("scans issues for current iteration, filters manual-fix status, prints count, and prompts to proceed", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+
+    await seedState(projectRoot, "000010");
+    await writeIssues(projectRoot, "000010", [
+      { id: "ISSUE-000010-001", title: "Open", description: "skip", status: "open" },
+      { id: "ISSUE-000010-002", title: "Manual A", description: "take", status: "manual-fix" },
+      { id: "ISSUE-000010-003", title: "Retry", description: "skip", status: "retry" },
+      { id: "ISSUE-000010-004", title: "Manual B", description: "take", status: "manual-fix" },
+    ]);
+
+    const logs: string[] = [];
+    const prompts: string[] = [];
+
+    await withCwd(projectRoot, async () => {
+      await runExecuteManualFix(
+        { provider: "codex" },
+        {
+          logFn: (message) => logs.push(message),
+          promptProceedFn: async (question) => {
+            prompts.push(question);
+            return false;
+          },
+        },
+      );
+    });
+
+    expect(logs).toContain(
+      "Found 2 issue(s) with status 'manual-fix' in .agents/flow/it_000010_ISSUES.json.",
+    );
+    expect(prompts).toHaveLength(1);
+    expect(prompts[0]).toContain("Proceed with manual-fix processing for 2 issue(s)");
+    expect(logs).toContain("Manual-fix execution cancelled.");
+  });
+
+  test("presents manual-fix issues one by one and runs interactive guidance for each issue", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+
+    await seedState(projectRoot, "000010");
+    await writeIssues(projectRoot, "000010", [
+      { id: "ISSUE-000010-001", title: "Open", description: "skip", status: "open" },
+      { id: "ISSUE-000010-002", title: "Manual A", description: "first manual", status: "manual-fix" },
+      { id: "ISSUE-000010-003", title: "Retry", description: "skip", status: "retry" },
+      { id: "ISSUE-000010-004", title: "Manual B", description: "second manual", status: "manual-fix" },
+    ]);
+
+    const logs: string[] = [];
+    const prompts: string[] = [];
+    const outcomePrompts: string[] = [];
+    const interactiveFlags: Array<boolean | undefined> = [];
+    const providersUsed: string[] = [];
+    const outcomes: Array<"fixed" | "skip" | "exit"> = ["skip", "skip"];
+
+    await withCwd(projectRoot, async () => {
+      await runExecuteManualFix(
+        { provider: "codex" },
+        {
+          logFn: (message) => logs.push(message),
+          promptProceedFn: async () => true,
+          promptIssueOutcomeFn: async (question) => {
+            outcomePrompts.push(question);
+            return outcomes.shift() ?? "skip";
+          },
+          invokeAgentFn: async (options) => {
+            prompts.push(options.prompt);
+            interactiveFlags.push(options.interactive);
+            providersUsed.push(options.provider);
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+        },
+      );
+    });
+
+    expect(logs).toContain(
+      "Found 2 issue(s) with status 'manual-fix' in .agents/flow/it_000010_ISSUES.json.",
+    );
+    expect(logs).toContain("Ready to process 2 manual-fix issue(s).");
+    expect(logs).toContain("Issue 1/2: ISSUE-000010-002 - Manual A");
+    expect(logs).toContain("Issue 2/2: ISSUE-000010-004 - Manual B");
+
+    expect(prompts).toHaveLength(2);
+    expect(prompts[0]).toContain("Issue ID: ISSUE-000010-002");
+    expect(prompts[1]).toContain("Issue ID: ISSUE-000010-004");
+
+    expect(interactiveFlags).toEqual([true, true]);
+    expect(providersUsed).toEqual(["codex", "codex"]);
+    expect(outcomePrompts).toEqual([
+      "Action? (f)ixed, (s)kip, (e)xit: ",
+      "Action? (f)ixed, (s)kip, (e)xit: ",
+    ]);
+  });
+
+  test("buildManualFixGuidancePrompt requires summary, reproduction strategy, fixes, and interactive Q&A loop", () => {
+    const prompt = buildManualFixGuidancePrompt(
+      {
+        id: "ISSUE-000010-002",
+        title: "Manual A",
+        description: "Service returns 500 on malformed payload.",
+        status: "manual-fix",
+      },
+      "000010",
+    );
+
+    expect(prompt).toContain("Iteration: 000010");
+    expect(prompt).toContain("Issue ID: ISSUE-000010-002");
+    expect(prompt).toContain("Start with a concise summary/analysis of the problem.");
+    expect(prompt).toContain("Suggest a concrete reproduction strategy or test case.");
+    expect(prompt).toContain("Suggest potential fixes or code changes with rationale.");
+    expect(prompt).toContain("continue in an interactive chat loop");
+    expect(prompt).toContain("Answer clarifying questions.");
+    expect(prompt).toContain("Provide code snippets when requested.");
+  });
+
+  test("US-003-AC02/AC04: marks issue fixed and persists updated status immediately", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+
+    await seedState(projectRoot, "000010");
+    await writeIssues(projectRoot, "000010", [
+      { id: "ISSUE-000010-001", title: "Manual A", description: "fix me", status: "manual-fix" },
+      { id: "ISSUE-000010-002", title: "Manual B", description: "keep", status: "manual-fix" },
+    ]);
+
+    const writes: string[] = [];
+    await withCwd(projectRoot, async () => {
+      await runExecuteManualFix(
+        { provider: "codex" },
+        {
+          promptProceedFn: async () => true,
+          promptIssueOutcomeFn: async () => "fixed",
+          invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          writeFileFn: async (path, data, options) => {
+            writes.push(String(data));
+            await writeFile(path, data, options);
+          },
+        },
+      );
+    });
+
+    expect(writes.length).toBeGreaterThan(0);
+    expect(writes[0]).toContain('"id": "ISSUE-000010-001"');
+    expect(writes[0]).toContain('"status": "fixed"');
+
+    const issuesRaw = await readFile(join(projectRoot, ".agents", "flow", "it_000010_ISSUES.json"), "utf8");
+    const issues = JSON.parse(issuesRaw) as Array<{ id: string; status: string }>;
+    expect(issues.find((issue) => issue.id === "ISSUE-000010-001")?.status).toBe("fixed");
+  });
+
+  test("US-003-AC03: skip leaves issue status as manual-fix and continues", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+
+    await seedState(projectRoot, "000010");
+    await writeIssues(projectRoot, "000010", [
+      { id: "ISSUE-000010-001", title: "Manual A", description: "first", status: "manual-fix" },
+      { id: "ISSUE-000010-002", title: "Manual B", description: "second", status: "manual-fix" },
+    ]);
+
+    let invokeCount = 0;
+    const responses: Array<"fixed" | "skip" | "exit"> = ["skip", "skip"];
+    await withCwd(projectRoot, async () => {
+      await runExecuteManualFix(
+        { provider: "codex" },
+        {
+          promptProceedFn: async () => true,
+          promptIssueOutcomeFn: async () => responses.shift() ?? "skip",
+          invokeAgentFn: async () => {
+            invokeCount += 1;
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+        },
+      );
+    });
+
+    expect(invokeCount).toBe(2);
+    const issuesRaw = await readFile(join(projectRoot, ".agents", "flow", "it_000010_ISSUES.json"), "utf8");
+    const issues = JSON.parse(issuesRaw) as Array<{ status: string }>;
+    expect(issues[0]?.status).toBe("manual-fix");
+    expect(issues[1]?.status).toBe("manual-fix");
+  });
+
+  test("US-003-AC01: prompts Mark as fixed/Skip/Exit and supports Exit to stop processing", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+
+    await seedState(projectRoot, "000010");
+    await writeIssues(projectRoot, "000010", [
+      { id: "ISSUE-000010-001", title: "Manual A", description: "first", status: "manual-fix" },
+      { id: "ISSUE-000010-002", title: "Manual B", description: "second", status: "manual-fix" },
+    ]);
+
+    const outcomePrompts: string[] = [];
+    let invokeCount = 0;
+    await withCwd(projectRoot, async () => {
+      await runExecuteManualFix(
+        { provider: "codex" },
+        {
+          promptProceedFn: async () => true,
+          promptIssueOutcomeFn: async (question) => {
+            outcomePrompts.push(question);
+            return "exit";
+          },
+          invokeAgentFn: async () => {
+            invokeCount += 1;
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+        },
+      );
+    });
+
+    expect(outcomePrompts).toEqual(["Action? (f)ixed, (s)kip, (e)xit: "]);
+    expect(invokeCount).toBe(1);
+  });
+
+  test("TC-003: handles 0 manual-fix issues gracefully", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+
+    await seedState(projectRoot, "000010");
+    await writeIssues(projectRoot, "000010", [
+      { id: "ISSUE-000010-001", title: "Open", description: "skip", status: "open" },
+    ]);
+
+    const logs: string[] = [];
+    const prompts: string[] = [];
+
+    await withCwd(projectRoot, async () => {
+      await runExecuteManualFix(
+        { provider: "codex" },
+        {
+          logFn: (message) => logs.push(message),
+          promptProceedFn: async (question) => {
+            prompts.push(question);
+            return true; // Say yes to proceed
+          },
+        },
+      );
+    });
+
+    expect(logs).toContain("Found 0 issue(s) with status 'manual-fix' in .agents/flow/it_000010_ISSUES.json.");
+    expect(prompts[0]).toContain("Proceed with manual-fix processing for 0 issue(s)");
+    expect(logs).toContain("No manual-fix issues to process. Exiting without changes.");
+  });
+});