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

package/src/commands/define-refactor-plan.ts

@@ -0,0 +1,96 @@
+import {
+  buildPrompt,
+  invokeAgent,
+  loadSkill,
+  type AgentInvokeOptions,
+  type AgentProvider,
+  type AgentResult,
+} from "../agent";
+import { assertGuardrail } from "../guardrail";
+import { readState, writeState } from "../state";
+
+export interface DefineRefactorPlanOptions {
+  provider: AgentProvider;
+  force?: boolean;
+}
+
+interface DefineRefactorPlanDeps {
+  invokeAgentFn: (options: AgentInvokeOptions) => Promise<AgentResult>;
+  loadSkillFn: (projectRoot: string, skillName: string) => Promise<string>;
+  nowFn: () => Date;
+}
+
+const defaultDeps: DefineRefactorPlanDeps = {
+  invokeAgentFn: invokeAgent,
+  loadSkillFn: loadSkill,
+  nowFn: () => new Date(),
+};
+
+export async function runDefineRefactorPlan(
+  opts: DefineRefactorPlanOptions,
+  deps: Partial<DefineRefactorPlanDeps> = {},
+): Promise<void> {
+  const { provider, force = false } = opts;
+  const projectRoot = process.cwd();
+  const state = await readState(projectRoot);
+  const mergedDeps: DefineRefactorPlanDeps = { ...defaultDeps, ...deps };
+
+  await assertGuardrail(
+    state,
+    !state.phases.prototype.prototype_approved,
+    "Cannot define refactor plan: phases.prototype.prototype_approved must be true. Complete prototype (all tests passing) first.",
+    { force },
+  );
+
+  // Intentional auto-transition: if the user runs this command directly from
+  // the prototype phase (prototype_approved === true), we advance to "refactor"
+  // so they don't have to manually update the phase. US-001-AC01 says the phase
+  // must be "refactor", but accepting "prototype" here is a UX convenience that
+  // is safe because prototype_approved is already enforced above.
+  if (state.current_phase === "prototype") {
+    state.current_phase = "refactor";
+  } else if (state.current_phase !== "refactor") {
+    await assertGuardrail(
+      state,
+      true,
+      `Cannot define refactor plan: current_phase must be 'prototype' or 'refactor'. Current: '${state.current_phase}'.`,
+      { force },
+    );
+  }
+
+  const refactorPlan = state.phases.refactor.refactor_plan;
+  await assertGuardrail(
+    state,
+    refactorPlan.status !== "pending",
+    `Cannot define refactor plan from status '${refactorPlan.status}'. Expected pending.`,
+    { force },
+  );
+
+  const skillBody = await mergedDeps.loadSkillFn(projectRoot, "plan-refactor");
+  const prompt = buildPrompt(skillBody, {
+    current_iteration: state.current_iteration,
+  });
+  const result = await mergedDeps.invokeAgentFn({
+    provider,
+    prompt,
+    cwd: projectRoot,
+    interactive: true,
+  });
+
+  if (result.exitCode !== 0) {
+    throw new Error(`Agent invocation failed with exit code ${result.exitCode}.`);
+  }
+
+  state.phases.refactor.evaluation_report.status = "created";
+  state.phases.refactor.evaluation_report.file = `it_${state.current_iteration}_evaluation-report.md`;
+  refactorPlan.status = "pending_approval";
+  refactorPlan.file = `it_${state.current_iteration}_refactor-plan.md`;
+  state.last_updated = mergedDeps.nowFn().toISOString();
+  state.updated_by = "nvst:define-refactor-plan";
+
+  await writeState(projectRoot, state);
+
+  console.log(
+    "Evaluation report and refactor plan created. Refactor plan is pending approval.",
+  );
+}

package/src/commands/define-requirement.ts

@@ -1,25 +1,31 @@
 import { buildPrompt, invokeAgent, loadSkill, type AgentProvider } from "../agent";
+import { assertGuardrail } from "../guardrail";
 import { readState, writeState } from "../state";
 
 export interface DefineRequirementOptions {
   provider: AgentProvider;
+  force?: boolean;
 }
 
 export async function runDefineRequirement(opts: DefineRequirementOptions): Promise<void> {
-  const { provider } = opts;
+  const { provider, force = false } = opts;
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
 
-  if (state.current_phase !== "define") {
-    throw new Error("Cannot define requirement: current_phase must be 'define'.");
-  }
+  await assertGuardrail(
+    state,
+    state.current_phase !== "define",
+    "Cannot define requirement: current_phase must be 'define'.",
+    { force },
+  );
 
   const requirementDefinition = state.phases.define.requirement_definition;
-  if (requirementDefinition.status !== "pending") {
-    throw new Error(
-      `Cannot define requirement from status '${requirementDefinition.status}'. Expected pending.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    requirementDefinition.status !== "pending",
+    `Cannot define requirement from status '${requirementDefinition.status}'. Expected pending.`,
+    { force },
+  );
 
   const skillBody = await loadSkill(projectRoot, "create-pr-document");
   const prompt = buildPrompt(skillBody, {

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");
           },
         },
       );

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

@@ -1,4 +1,4 @@
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { $ as dollar } from "bun";
 
@@ -11,7 +11,8 @@ import {
   type AgentResult,
 } from "../agent";
 import { exists, FLOW_REL_DIR, readState } from "../state";
-import { type Issue } from "../../scaffold/schemas/tmpl_issues";
+import { type Issue, IssuesSchema } from "../../scaffold/schemas/tmpl_issues";
+import { writeJsonArtifact, type WriteJsonArtifactFn } from "../write-json-artifact";
 
 export interface ExecuteAutomatedFixOptions {
   provider: AgentProvider;
@@ -27,7 +28,7 @@ interface ExecuteAutomatedFixDeps {
   nowFn: () => Date;
   readFileFn: typeof readFile;
   runCommitFn: (projectRoot: string, message: string) => Promise<number>;
-  writeFileFn: typeof writeFile;
+  writeJsonArtifactFn: WriteJsonArtifactFn;
 }
 
 const defaultDeps: ExecuteAutomatedFixDeps = {
@@ -44,7 +45,7 @@ const defaultDeps: ExecuteAutomatedFixDeps = {
       .quiet();
     return result.exitCode;
   },
-  writeFileFn: writeFile,
+  writeJsonArtifactFn: writeJsonArtifact,
 };
 
 function isNetworkErrorText(text: string): boolean {
@@ -72,106 +73,12 @@ 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");
+  await deps.writeJsonArtifactFn(issuesPath, IssuesSchema, issues);
 }
 
 async function commitIssueUpdate(
@@ -185,6 +92,25 @@ async function commitIssueUpdate(
   return exitCode === 0;
 }
 
+/**
+ * Guardrail policy: `execute-automated-fix` is an explicit exception to the
+ * phase-based guardrail system used by `execute-test-plan` and
+ * `execute-refactor`. Those commands assert `current_phase` and prerequisite
+ * status fields via `assertGuardrail` before running, because they depend on
+ * phase-specific state transitions being in place.
+ *
+ * `execute-automated-fix` is deliberately phase-independent: issues can exist
+ * and require automated remediation at any point in the workflow (prototype or
+ * refactor phases, or during reruns after partial fixes). Its sole
+ * prerequisite is the existence of a valid issues file for the current
+ * iteration, which is already enforced by a hard error below. Adding a
+ * phase-based guardrail here would prevent legitimate use cases (e.g. fixing
+ * issues discovered late in a refactor pass) without adding safety value.
+ *
+ * `--force` is therefore not applicable to this command and is not accepted as
+ * a flag (any unrecognised option, including `--force`, is rejected by the CLI
+ * router before reaching this function).
+ */
 export async function runExecuteAutomatedFix(
   opts: ExecuteAutomatedFixOptions,
   deps: Partial<ExecuteAutomatedFixDeps> = {},
@@ -224,7 +150,14 @@ export async function runExecuteAutomatedFix(
     );
   }
 
-  const issues = sortIssuesById(parseIssuesForProcessing(parsedIssuesRaw, flowRelativePath, mergedDeps.logFn));
+  const issuesValidation = IssuesSchema.safeParse(parsedIssuesRaw);
+  if (!issuesValidation.success) {
+    throw new Error(
+      `Deterministic validation error: issues schema mismatch in ${flowRelativePath}.`,
+    );
+  }
+
+  const issues = sortIssuesById(issuesValidation.data);
   const openIssues = issues.filter((issue) => issue.status === "open");
 
   if (openIssues.length === 0) {
@@ -233,7 +166,7 @@ export async function runExecuteAutomatedFix(
   }
 
   const skillTemplate = await mergedDeps.loadSkillFn(projectRoot, "automated-fix");
-  const maxIssuesToProcess = opts.iterations ?? 1;
+  const maxIssuesToProcess = opts.iterations ?? openIssues.length;
   const issuesToProcess = openIssues.slice(0, maxIssuesToProcess);
   const maxRetries = opts.retryOnFail ?? 0;