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

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

@@ -0,0 +1,208 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, readFile, rm } 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 { runDefineRefactorPlan } from "./define-refactor-plan";
+
+async function createProjectRoot(): Promise<string> {
+  return mkdtemp(join(tmpdir(), "nvst-define-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,
+  stateOverrides: {
+    currentPhase?: "define" | "prototype" | "refactor";
+    refactorPlanStatus?: "pending" | "pending_approval" | "approved";
+    prototypeApproved?: boolean;
+  } = {},
+): Promise<void> {
+  const currentPhase = stateOverrides.currentPhase ?? "refactor";
+  const refactorPlanStatus = stateOverrides.refactorPlanStatus ?? "pending";
+  const prototypeApproved = stateOverrides.prototypeApproved ?? true;
+
+  await mkdir(join(projectRoot, ".agents", "flow"), { recursive: true });
+
+  await writeState(projectRoot, {
+    current_iteration: "000013",
+    current_phase: currentPhase,
+    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: prototypeApproved,
+      },
+      refactor: {
+        evaluation_report: { status: "pending", file: null },
+        refactor_plan: { status: refactorPlanStatus, file: null },
+        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("define refactor-plan command", () => {
+  test("registers define refactor-plan command in CLI dispatch", async () => {
+    const source = await readFile(join(process.cwd(), "src", "cli.ts"), "utf8");
+
+    expect(source).toContain('import { runDefineRefactorPlan } from "./commands/define-refactor-plan";');
+    expect(source).toContain('if (subcommand === "refactor-plan") {');
+    expect(source).toContain("await runDefineRefactorPlan({ provider, force });");
+  });
+
+  test("rejects when prototype_approved is false", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { prototypeApproved: false });
+
+    await withCwd(projectRoot, async () => {
+      await expect(runDefineRefactorPlan({ provider: "codex" })).rejects.toThrow(
+        "Cannot define refactor plan: phases.prototype.prototype_approved must be true",
+      );
+    });
+  });
+
+  test("allows bypassing prototype_approved guard with force", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { prototypeApproved: false });
+
+    await withCwd(projectRoot, async () => {
+      await runDefineRefactorPlan(
+        { provider: "codex", force: true },
+        {
+          loadSkillFn: async () => "Refactor planning instructions",
+          invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          nowFn: () => new Date("2026-02-26T10:00:00.000Z"),
+        },
+      );
+    });
+
+    const state = await readState(projectRoot);
+    expect(state.phases.refactor.evaluation_report.status).toBe("created");
+    expect(state.phases.refactor.refactor_plan.status).toBe("pending_approval");
+  });
+
+  test("rejects when current_phase is define", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { currentPhase: "define", prototypeApproved: true });
+
+    await withCwd(projectRoot, async () => {
+      await expect(runDefineRefactorPlan({ provider: "codex" })).rejects.toThrow(
+        "Cannot define refactor plan: current_phase must be 'prototype' or 'refactor'",
+      );
+    });
+  });
+
+  test("accepts when current_phase is prototype and prototype_approved is true, transitions to refactor", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { currentPhase: "prototype" });
+
+    await withCwd(projectRoot, async () => {
+      await runDefineRefactorPlan(
+        { provider: "codex" },
+        {
+          loadSkillFn: async () => "Refactor planning instructions",
+          invokeAgentFn: async () => ({ exitCode: 0, stdout: "", stderr: "" }),
+          nowFn: () => new Date("2026-02-26T10:00:00.000Z"),
+        },
+      );
+    });
+
+    const state = await readState(projectRoot);
+    expect(state.current_phase).toBe("refactor");
+    expect(state.phases.refactor.evaluation_report.status).toBe("created");
+    expect(state.phases.refactor.refactor_plan.status).toBe("pending_approval");
+  });
+
+  test("rejects when refactor.refactor_plan.status is not pending", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot, { refactorPlanStatus: "approved" });
+
+    await withCwd(projectRoot, async () => {
+      await expect(runDefineRefactorPlan({ provider: "codex" })).rejects.toThrow(
+        "Cannot define refactor plan from status 'approved'. Expected pending.",
+      );
+    });
+  });
+
+  test("loads plan-refactor skill, invokes interactive agent, and persists pending_approval state", async () => {
+    const projectRoot = await createProjectRoot();
+    createdRoots.push(projectRoot);
+    await seedState(projectRoot);
+
+    let loadedSkill = "";
+    let invocation: { interactive: boolean | undefined; prompt: string } | undefined;
+
+    await withCwd(projectRoot, async () => {
+      await runDefineRefactorPlan(
+        { provider: "codex" },
+        {
+          loadSkillFn: async (_root, skillName) => {
+            loadedSkill = skillName;
+            return "Refactor planning instructions from SKILL.md";
+          },
+          invokeAgentFn: async (options): Promise<AgentResult> => {
+            invocation = {
+              interactive: options.interactive,
+              prompt: options.prompt,
+            };
+            return { exitCode: 0, stdout: "", stderr: "" };
+          },
+          nowFn: () => new Date("2026-02-26T10:00:00.000Z"),
+        },
+      );
+    });
+
+    expect(loadedSkill).toBe("plan-refactor");
+    if (invocation === undefined) {
+      throw new Error("Agent invocation was not captured");
+    }
+    expect(invocation.interactive).toBe(true);
+    expect(invocation.prompt).toContain("Refactor planning instructions from SKILL.md");
+    expect(invocation.prompt).toContain("### current_iteration");
+    expect(invocation.prompt).toContain("000013");
+
+    const state = await readState(projectRoot);
+    expect(state.phases.refactor.evaluation_report.status).toBe("created");
+    expect(state.phases.refactor.evaluation_report.file).toBe(
+      "it_000013_evaluation-report.md",
+    );
+    expect(state.phases.refactor.refactor_plan.status).toBe("pending_approval");
+    expect(state.phases.refactor.refactor_plan.file).toBe("it_000013_refactor-plan.md");
+    expect(state.last_updated).toBe("2026-02-26T10:00:00.000Z");
+    expect(state.updated_by).toBe("nvst:define-refactor-plan");
+  });
+});

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, {