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

package/src/commands/create-prototype.ts

@@ -1,17 +1,25 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { $ as dollar } from "bun";
-import { z } from "zod";
 
 import { PrdSchema } from "../../scaffold/schemas/tmpl_prd";
+import {
+  PrototypeProgressSchema,
+  type PrototypeProgress,
+} from "../../scaffold/schemas/tmpl_prototype-progress";
 import {
   buildPrompt,
   invokeAgent,
   loadSkill,
+  type AgentInvokeOptions,
   type AgentProvider,
+  type AgentResult,
 } from "../agent";
 import { assertGuardrail } from "../guardrail";
+import { defaultReadLine } from "../readline";
+import { idsMatchExactly, sortedValues } from "../progress-utils";
 import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
+import { writeJsonArtifact, type WriteJsonArtifactFn } from "../write-json-artifact";
 
 export interface CreatePrototypeOptions {
   provider: AgentProvider;
@@ -21,41 +29,114 @@ export interface CreatePrototypeOptions {
   force?: boolean;
 }
 
-const ProgressEntrySchema = z.object({
-  use_case_id: z.string(),
-  status: z.enum(["pending", "failed", "completed"]),
-  attempt_count: z.number().int().nonnegative(),
-  last_agent_exit_code: z.number().int().nullable(),
-  quality_checks: z.array(
-    z.object({
-      command: z.string(),
-      exit_code: z.number().int(),
-    }),
-  ),
-  last_error_summary: z.string(),
-  updated_at: z.string(),
-});
-
-export const PrototypeProgressSchema = z.object({
-  entries: z.array(ProgressEntrySchema),
-});
-
-function sortedValues(values: string[]): string[] {
-  return [...values].sort((a, b) => a.localeCompare(b));
+const DECLINE_DIRTY_TREE_ABORT_MESSAGE = "Aborted. Commit or discard your changes and re-run `bun nvst create prototype`.";
+const DIRTY_TREE_COMMIT_PROMPT = "Working tree has uncommitted changes. Stage and commit them now to proceed? [y/N]";
+
+interface CreatePrototypeDeps {
+  invokeAgentFn: (options: AgentInvokeOptions) => Promise<AgentResult>;
+  loadSkillFn: (projectRoot: string, skillName: string) => Promise<string>;
+  checkGhAvailableFn: (projectRoot: string) => Promise<boolean>;
+  createPullRequestFn: (
+    projectRoot: string,
+    title: string,
+    body: string,
+  ) => Promise<{ exitCode: number; stderr: string }>;
+  logFn: (message: string) => void;
+  warnFn: (message: string) => void;
+  promptDirtyTreeCommitFn: (question: string) => Promise<boolean>;
+  gitAddAndCommitFn: (projectRoot: string, commitMessage: string) => Promise<void>;
+  writeJsonArtifactFn: WriteJsonArtifactFn;
+}
+
+const defaultDeps: CreatePrototypeDeps = {
+  invokeAgentFn: invokeAgent,
+  loadSkillFn: loadSkill,
+  checkGhAvailableFn: async (projectRoot) => {
+    const proc = Bun.spawn(["gh", "--version"], {
+      cwd: projectRoot,
+      stdout: "ignore",
+      stderr: "ignore",
+    });
+    return (await proc.exited) === 0;
+  },
+  createPullRequestFn: async (projectRoot, title, body) => {
+    const result = await dollar`gh pr create --title ${title} --body ${body}`
+      .cwd(projectRoot)
+      .nothrow()
+      .quiet();
+    return {
+      exitCode: result.exitCode,
+      stderr: result.stderr.toString().trim(),
+    };
+  },
+  logFn: console.log,
+  warnFn: console.warn,
+  promptDirtyTreeCommitFn: promptForDirtyTreeCommit,
+  gitAddAndCommitFn: runGitAddAndCommit,
+  writeJsonArtifactFn: writeJsonArtifact,
+};
+
+type ReadLineFn = () => Promise<string | null>;
+type WriteFn = (message: string) => void;
+type IsTTYFn = () => boolean;
+
+function defaultWrite(message: string): void {
+  process.stdout.write(`${message}\n`);
+}
+
+function defaultIsTTY(): boolean {
+  return process.stdin.isTTY === true;
 }
 
-function idsMatchExactly(left: string[], right: string[]): boolean {
-  if (left.length !== right.length) {
+export async function promptForDirtyTreeCommit(
+  question: string,
+  readLineFn: ReadLineFn = defaultReadLine,
+  writeFn: WriteFn = defaultWrite,
+  isTTYFn: IsTTYFn = defaultIsTTY,
+): Promise<boolean> {
+  if (!isTTYFn()) {
     return false;
   }
 
-  for (let i = 0; i < left.length; i += 1) {
-    if (left[i] !== right[i]) {
-      return false;
-    }
+  writeFn(question);
+
+  let line: string | null;
+  try {
+    line = await readLineFn();
+  } catch {
+    line = null;
   }
 
-  return true;
+  return line !== null && (line.trim() === "y" || line.trim() === "Y");
+}
+
+async function runGitAddAndCommit(projectRoot: string, commitMessage: string): Promise<void> {
+  const addResult = await dollar`git add -A`.cwd(projectRoot).nothrow().quiet();
+  if (addResult.exitCode !== 0) {
+    throw new Error(`Pre-prototype commit failed:\n${addResult.stderr.toString().trim()}`);
+  }
+
+  const commitResult = await dollar`git commit -m ${commitMessage}`.cwd(projectRoot).nothrow().quiet();
+  if (commitResult.exitCode !== 0) {
+    throw new Error(`Pre-prototype commit failed:\n${commitResult.stderr.toString().trim()}`);
+  }
+}
+
+export async function runPrePrototypeCommit(
+  projectRoot: string,
+  iteration: string,
+  gitAddAndCommitFn: (projectRoot: string, commitMessage: string) => Promise<void> = runGitAddAndCommit,
+): Promise<void> {
+  const commitMessage = `chore: pre-prototype commit it_${iteration}`;
+  try {
+    await gitAddAndCommitFn(projectRoot, commitMessage);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    if (reason.startsWith("Pre-prototype commit failed:\n")) {
+      throw error;
+    }
+    throw new Error(`Pre-prototype commit failed:\n${reason}`);
+  }
 }
 
 function parseQualityChecks(projectContextContent: string): string[] {
@@ -105,7 +186,11 @@ function parseQualityChecks(projectContextContent: string): string[] {
     .filter((line) => line.length > 0);
 }
 
-export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<void> {
+export async function runCreatePrototype(
+  opts: CreatePrototypeOptions,
+  deps: Partial<CreatePrototypeDeps> = {},
+): Promise<void> {
+  const mergedDeps: CreatePrototypeDeps = { ...defaultDeps, ...deps };
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
   const force = opts.force ?? false;
@@ -151,6 +236,8 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
     );
   }
 
+  let prePrototypeCommitDone = false;
+
   if (state.current_phase === "define") {
     if (
       state.phases.define.prd_generation.status === "completed" &&
@@ -163,9 +250,15 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
         );
       }
       if (workingTreeBeforeTransition.stdout.toString().trim().length > 0) {
-        throw new Error(
-          "Git working tree is dirty. Commit your changes or discard them before running `bun nvst create prototype` again.",
+        const shouldProceed = await mergedDeps.promptDirtyTreeCommitFn(
+          DIRTY_TREE_COMMIT_PROMPT,
         );
+        if (!shouldProceed) {
+          mergedDeps.logFn(DECLINE_DIRTY_TREE_ABORT_MESSAGE);
+          return;
+        }
+        await runPrePrototypeCommit(projectRoot, iteration, mergedDeps.gitAddAndCommitFn);
+        prePrototypeCommitDone = true;
       }
       state.current_phase = "prototype";
       await writeState(projectRoot, state);
@@ -193,16 +286,23 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
     { force },
   );
 
-  const workingTreeAfterPhase = await dollar`git status --porcelain`.cwd(projectRoot).nothrow().quiet();
-  if (workingTreeAfterPhase.exitCode !== 0) {
-    throw new Error(
-      "Unable to verify git working tree status. Ensure this directory is a git repository and git is installed.",
-    );
-  }
-  if (workingTreeAfterPhase.stdout.toString().trim().length > 0) {
-    throw new Error(
-      "Git working tree is dirty. Commit your changes or discard them before running `bun nvst create prototype` again.",
-    );
+  if (!prePrototypeCommitDone) {
+    const workingTreeAfterPhase = await dollar`git status --porcelain`.cwd(projectRoot).nothrow().quiet();
+    if (workingTreeAfterPhase.exitCode !== 0) {
+      throw new Error(
+        "Unable to verify git working tree status. Ensure this directory is a git repository and git is installed.",
+      );
+    }
+    if (workingTreeAfterPhase.stdout.toString().trim().length > 0) {
+      const shouldProceed = await mergedDeps.promptDirtyTreeCommitFn(
+        DIRTY_TREE_COMMIT_PROMPT,
+      );
+      if (!shouldProceed) {
+        mergedDeps.logFn(DECLINE_DIRTY_TREE_ABORT_MESSAGE);
+        return;
+      }
+      await runPrePrototypeCommit(projectRoot, iteration, mergedDeps.gitAddAndCommitFn);
+    }
   }
 
   const branchName = `feature/it_${iteration}`;
@@ -230,7 +330,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
   const progressFileName = `it_${iteration}_progress.json`;
   const progressPath = join(projectRoot, FLOW_REL_DIR, progressFileName);
   const storyIds = sortedValues(prdValidation.data.userStories.map((story) => story.id));
-  let progressData: z.infer<typeof PrototypeProgressSchema>;
+  let progressData: PrototypeProgress;
 
   if (await exists(progressPath)) {
     let parsedProgress: unknown;
@@ -273,7 +373,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
       })),
     };
 
-    await writeFile(progressPath, `${JSON.stringify(progress, null, 2)}\n`, "utf8");
+    await mergedDeps.writeJsonArtifactFn(progressPath, PrototypeProgressSchema, progress);
     progressData = progress;
   }
 
@@ -283,7 +383,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
   });
 
   if (eligibleStories.length === 0) {
-    console.log("No pending or failed user stories to implement. Exiting without changes.");
+    mergedDeps.logFn("No pending or failed user stories to implement. Exiting without changes.");
     return;
   }
 
@@ -295,7 +395,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
 
   let skillTemplate: string;
   try {
-    skillTemplate = await loadSkill(projectRoot, "implement-user-story");
+    skillTemplate = await mergedDeps.loadSkillFn(projectRoot, "implement-user-story");
   } catch {
     throw new Error(
       "Required skill missing: expected .agents/skills/implement-user-story/SKILL.md.",
@@ -334,7 +434,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
         user_story: JSON.stringify(story, null, 2),
       });
 
-      const agentResult = await invokeAgent({
+      const agentResult = await mergedDeps.invokeAgentFn({
         provider: opts.provider,
         prompt,
         cwd: projectRoot,
@@ -368,7 +468,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
         entry.last_error_summary = "Agent or quality check failed";
       }
 
-      await writeFile(progressPath, `${JSON.stringify(progressData, null, 2)}\n`, "utf8");
+      await mergedDeps.writeJsonArtifactFn(progressPath, PrototypeProgressSchema, progressData);
 
       if (allPassed) {
         const commitMessage = `feat: implement ${story.id} - ${story.title}`;
@@ -381,9 +481,9 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
           entry.status = "failed";
           entry.last_error_summary = "Git commit failed";
           entry.updated_at = new Date().toISOString();
-          await writeFile(progressPath, `${JSON.stringify(progressData, null, 2)}\n`, "utf8");
+          await mergedDeps.writeJsonArtifactFn(progressPath, PrototypeProgressSchema, progressData);
 
-          console.log(
+          mergedDeps.logFn(
             `iteration=it_${iteration} story=${story.id} attempt=${entry.attempt_count} outcome=commit_failed`,
           );
 
@@ -391,7 +491,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
             haltedByCritical = true;
           }
         } else {
-          console.log(
+          mergedDeps.logFn(
             `iteration=it_${iteration} story=${story.id} attempt=${entry.attempt_count} outcome=passed`,
           );
         }
@@ -399,7 +499,7 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
         break;
       }
 
-      console.log(
+      mergedDeps.logFn(
         `iteration=it_${iteration} story=${story.id} attempt=${entry.attempt_count} outcome=failed`,
       );
 
@@ -423,13 +523,25 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
   await writeState(projectRoot, state);
 
   if (storiesAttempted === 0) {
-    console.log("No user stories attempted.");
+    mergedDeps.logFn("No user stories attempted.");
     return;
   }
 
   if (allCompleted) {
-    console.log("Prototype implementation completed for all user stories.");
+    const ghAvailable = await mergedDeps.checkGhAvailableFn(projectRoot);
+    if (!ghAvailable) {
+      mergedDeps.logFn("gh CLI not found — skipping PR creation");
+    } else {
+      const prTitle = `feat: prototype it_${iteration}`;
+      const prBody = `Prototype for iteration it_${iteration}`;
+      const prResult = await mergedDeps.createPullRequestFn(projectRoot, prTitle, prBody);
+      if (prResult.exitCode !== 0) {
+        const suffix = prResult.stderr.length > 0 ? `: ${prResult.stderr}` : "";
+        mergedDeps.warnFn(`gh pr create failed (non-fatal)${suffix}`);
+      }
+    }
+    mergedDeps.logFn("Prototype implementation completed for all user stories.");
   } else {
-    console.log("Prototype implementation paused with remaining pending or failed stories.");
+    mergedDeps.logFn("Prototype implementation paused with remaining pending or failed stories.");
   }
 }

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

@@ -193,6 +193,66 @@ describe("execute automated-fix", () => {
     expect(providersUsed).toEqual(["cursor"]);
   });
 
+  // RI-005: execute-automated-fix is a phase-independent exception to the guardrail system.
+  // It must process issues regardless of current_phase because issues can arise and need
+  // fixing at any point in the workflow (prototype OR refactor phases).
+  test("RI-005: processes open issues regardless of current_phase (phase-independent guardrail exception)", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+
+    // Seed state with current_phase = "refactor", not the typical "prototype"
+    await mkdir(join(projectRoot, ".agents", "flow"), { recursive: true });
+    const { writeState } = await import("../state");
+    await writeState(projectRoot, {
+      current_iteration: "000009",
+      current_phase: "refactor",
+      phases: {
+        define: {
+          requirement_definition: { status: "approved", file: "it_000009_product-requirement-document.md" },
+          prd_generation: { status: "completed", file: "it_000009_PRD.json" },
+        },
+        prototype: {
+          project_context: { status: "created", file: ".agents/PROJECT_CONTEXT.md" },
+          test_plan: { status: "created", file: "it_000009_test-plan.md" },
+          tp_generation: { status: "created", file: "it_000009_test-plan.json" },
+          prototype_build: { status: "created", file: null },
+          test_execution: { status: "completed", file: null },
+          prototype_approved: true,
+        },
+        refactor: {
+          evaluation_report: { status: "created", file: null },
+          refactor_plan: { status: "approved", file: null },
+          refactor_execution: { status: "in_progress", file: null },
+          changelog: { status: "pending", file: null },
+        },
+      },
+      last_updated: "2026-02-22T00:00:00.000Z",
+      updated_by: "seed",
+      history: [],
+    });
+    await writeIssues(projectRoot, "000009", [
+      { id: "ISSUE-000009-001", title: "Refactor-phase issue", description: "fix me", status: "open" },
+    ]);
+
+    let invokeCount = 0;
+
+    await withCwd(projectRoot, async () => {
+      await runExecuteAutomatedFix(
+        { provider: "codex" },
+        {
+          loadSkillFn: async () => "debug workflow",
+          invokeAgentFn: async () => {
+            invokeCount += 1;
+            return { exitCode: 0, stdout: "ok", stderr: "" };
+          },
+          runCommitFn: async () => 0,
+        },
+      );
+    });
+
+    expect(invokeCount).toBe(1);
+  });
+
   test("logs informative message and exits without changes when zero open issues exist", async () => {
     const projectRoot = await createProjectRoot();
     createdRoots.push(projectRoot);
@@ -225,7 +285,8 @@ describe("execute automated-fix", () => {
     expect(logs).toContain("No open issues to process. Exiting without changes.");
   });
 
-  test("defaults --iterations to 1 and leaves remaining open issues untouched", async () => {
+  // US-001-AC01: When --iterations is not provided, all open issues are processed
+  test("US-001-AC01: processes all open issues when --iterations is not provided", async () => {
     const projectRoot = await createProjectRoot();
     createdRoots.push(projectRoot);
 
@@ -237,6 +298,7 @@ describe("execute automated-fix", () => {
     ]);
 
     let invokeCount = 0;
+    const logs: string[] = [];
 
     await withCwd(projectRoot, async () => {
       await runExecuteAutomatedFix(
@@ -248,6 +310,8 @@ describe("execute automated-fix", () => {
             return { exitCode: 0, stdout: "", stderr: "" };
           },
           runCommitFn: async () => 0,
+          logFn: (message) => logs.push(message),
+          nowFn: () => new Date("2026-02-22T12:00:00.000Z"),
         },
       );
     });
@@ -255,10 +319,14 @@ describe("execute automated-fix", () => {
     const issuesRaw = await readFile(join(projectRoot, ".agents", "flow", "it_000009_ISSUES.json"), "utf8");
     const issues = JSON.parse(issuesRaw) as Array<{ id: string; status: string }>;
 
-    expect(invokeCount).toBe(1);
+    // All 3 open issues should be processed
+    expect(invokeCount).toBe(3);
     expect(issues.find((issue) => issue.id === "ISSUE-000009-001")?.status).toBe("fixed");
-    expect(issues.find((issue) => issue.id === "ISSUE-000009-002")?.status).toBe("open");
-    expect(issues.find((issue) => issue.id === "ISSUE-000009-003")?.status).toBe("open");
+    expect(issues.find((issue) => issue.id === "ISSUE-000009-002")?.status).toBe("fixed");
+    expect(issues.find((issue) => issue.id === "ISSUE-000009-003")?.status).toBe("fixed");
+    // AC04: summary reflects all processed issues
+    expect(logs).toContain("Summary: Fixed=3 Failed=0");
+    expect(logs).toContain("Processed 3 open issue(s) at 2026-02-22T12:00:00.000Z");
   });
 
   test("processes only the first N open issues when --iterations is provided", async () => {
@@ -297,7 +365,7 @@ describe("execute automated-fix", () => {
     expect(issues.find((issue) => issue.id === "ISSUE-000009-003")?.status).toBe("open");
   });
 
-  test("skips issues with missing required fields and continues processing remaining open issues", async () => {
+  test("throws deterministic validation error when issues file contains entries with missing required fields", async () => {
     const projectRoot = await createProjectRoot();
     createdRoots.push(projectRoot);
 
@@ -308,34 +376,11 @@ describe("execute automated-fix", () => {
       { id: "ISSUE-000009-003", title: "Fixed", description: "skip", status: "fixed" },
     ]);
 
-    const logs: string[] = [];
-    const prompts: string[] = [];
-
     await withCwd(projectRoot, async () => {
-      await runExecuteAutomatedFix(
-        { provider: "codex", iterations: 3 },
-        {
-          loadSkillFn: async () => "debug workflow",
-          invokeAgentFn: async (options) => {
-            prompts.push(options.prompt);
-            return { exitCode: 0, stdout: "", stderr: "" };
-          },
-          runCommitFn: async () => 0,
-          logFn: (message) => logs.push(message),
-        },
+      await expect(runExecuteAutomatedFix({ provider: "codex" })).rejects.toThrow(
+        "Deterministic validation error: issues schema mismatch in .agents/flow/it_000009_ISSUES.json.",
       );
     });
-
-    expect(prompts).toHaveLength(1);
-    expect(prompts[0]).toContain('"id": "ISSUE-000009-001"');
-    expect(logs.some((line) => line.includes("Warning: Skipping issue at index 1"))).toBe(true);
-
-    const issuesRaw = await readFile(join(projectRoot, ".agents", "flow", "it_000009_ISSUES.json"), "utf8");
-    const issues = JSON.parse(issuesRaw) as Array<{ id: string; status: string }>;
-
-    expect(issues.find((issue) => issue.id === "ISSUE-000009-001")?.status).toBe("fixed");
-    expect(issues.find((issue) => issue.id === "ISSUE-000009-003")?.status).toBe("fixed");
-    expect(issues.some((issue) => issue.id === "ISSUE-000009-002")).toBe(false);
   });
 
   test("marks issue as retry when hypothesis is not confirmed and retries remain", async () => {
@@ -363,9 +408,9 @@ describe("execute automated-fix", () => {
             return { exitCode: 0, stdout: "", stderr: "" };
           },
           runCommitFn: async () => 0,
-          writeFileFn: async (path, data, options) => {
-            writtenSnapshots.push(String(data));
-            return writeFile(path, data, options);
+          writeJsonArtifactFn: async (path, _schema, data) => {
+            writtenSnapshots.push(JSON.stringify(data, null, 2));
+            await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, "utf8");
           },
         },
       );