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

package/src/commands/approve-requirement.ts

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { $ } from "bun";
 
 import { CLI_PATH } from "../cli-path";
+import { assertGuardrail } from "../guardrail";
 import type { Prd } from "../../scaffold/schemas/tmpl_prd";
 import { exists, readState, writeState, FLOW_REL_DIR } from "../state";
 
@@ -154,17 +155,75 @@ function parsePrd(markdown: string): Prd {
 // Main command
 // ---------------------------------------------------------------------------
 
-export async function runApproveRequirement(): Promise<void> {
+interface WriteJsonResult {
+  exitCode: number;
+  stderr: string;
+}
+
+interface ApproveRequirementDeps {
+  existsFn: (path: string) => Promise<boolean>;
+  invokeWriteJsonFn: (
+    projectRoot: string,
+    schemaName: string,
+    outPath: string,
+    data: string,
+  ) => Promise<WriteJsonResult>;
+  nowFn: () => Date;
+  readFileFn: typeof readFile;
+}
+
+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: ApproveRequirementDeps = {
+  existsFn: exists,
+  invokeWriteJsonFn: runWriteJsonCommand,
+  nowFn: () => new Date(),
+  readFileFn: readFile,
+};
+
+export async function runApproveRequirement(
+  optsOrDeps: { force?: boolean } | Partial<ApproveRequirementDeps> = {},
+  maybeDeps: Partial<ApproveRequirementDeps> = {},
+): Promise<void> {
+  const isDepsArg =
+    typeof optsOrDeps === "object"
+    && optsOrDeps !== null
+    && (
+      "existsFn" in optsOrDeps
+      || "invokeWriteJsonFn" in optsOrDeps
+      || "nowFn" in optsOrDeps
+      || "readFileFn" in optsOrDeps
+    );
+  const force = isDepsArg ? false : ((optsOrDeps as { force?: boolean }).force ?? false);
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
+  const deps = isDepsArg ? optsOrDeps : maybeDeps;
+  const mergedDeps: ApproveRequirementDeps = { ...defaultDeps, ...deps };
 
   // --- US-001: Validate status ---
   const requirementDefinition = state.phases.define.requirement_definition;
-  if (requirementDefinition.status !== "in_progress") {
-    throw new Error(
-      `Cannot approve requirement from status '${requirementDefinition.status}'. Expected in_progress.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    requirementDefinition.status !== "in_progress",
+    `Cannot approve requirement from status '${requirementDefinition.status}'. Expected in_progress.`,
+    { force },
+  );
 
   const requirementFile = requirementDefinition.file;
   if (!requirementFile) {
@@ -172,26 +231,26 @@ export async function runApproveRequirement(): Promise<void> {
   }
 
   const requirementPath = join(projectRoot, FLOW_REL_DIR, requirementFile);
-  if (!(await exists(requirementPath))) {
+  if (!(await mergedDeps.existsFn(requirementPath))) {
     throw new Error(`Cannot approve requirement: file not found at ${requirementPath}`);
   }
 
   // --- US-002: Parse PRD markdown and generate JSON ---
-  const markdown = await readFile(requirementPath, "utf-8");
+  const markdown = await mergedDeps.readFileFn(requirementPath, "utf-8");
   const prdData = parsePrd(markdown);
   const prdJsonFileName = `it_${state.current_iteration}_PRD.json`;
   const prdJsonRelPath = join(FLOW_REL_DIR, prdJsonFileName);
 
   // Invoke write-json CLI to validate and write the PRD JSON
-  const prdJsonString = JSON.stringify(prdData);
-  const result =
-    await $`bun ${CLI_PATH} write-json --schema prd --out ${prdJsonRelPath} --data ${prdJsonString}`
-      .cwd(projectRoot)
-      .nothrow()
-      .quiet();
+  const result = await mergedDeps.invokeWriteJsonFn(
+    projectRoot,
+    "prd",
+    prdJsonRelPath,
+    JSON.stringify(prdData),
+  );
 
   if (result.exitCode !== 0) {
-    const stderr = result.stderr.toString().trim();
+    const stderr = result.stderr.trim();
     console.error("PRD JSON generation failed. Requirement remains in_progress.");
     if (stderr) {
       console.error(stderr);
@@ -207,7 +266,7 @@ export async function runApproveRequirement(): Promise<void> {
   state.phases.define.prd_generation.status = "completed";
   state.phases.define.prd_generation.file = prdJsonFileName;
 
-  state.last_updated = new Date().toISOString();
+  state.last_updated = mergedDeps.nowFn().toISOString();
   state.updated_by = "nvst:approve-requirement";
 
   await writeState(projectRoot, state);

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

@@ -3,7 +3,7 @@ import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 
-import { TestPlanSchema } from "../../schemas/test-plan";
+import { TestPlanSchema } from "../../scaffold/schemas/tmpl_test-plan";
 import { readState, writeState } from "../state";
 import { parseTestPlan, runApproveTestPlan } from "./approve-test-plan";
 
@@ -68,7 +68,7 @@ describe("approve test-plan command", () => {
 
     expect(source).toContain('import { runApproveTestPlan } from "./commands/approve-test-plan";');
     expect(source).toContain('if (subcommand === "test-plan") {');
-    expect(source).toContain("await runApproveTestPlan();");
+    expect(source).toContain("await runApproveTestPlan({ force });");
   });
 
   test("requires test_plan.status to be pending_approval", async () => {

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

@@ -3,7 +3,8 @@ import { join } from "node:path";
 import { $ } from "bun";
 
 import { CLI_PATH } from "../cli-path";
-import type { TestPlan } from "../../schemas/test-plan";
+import { assertGuardrail } from "../guardrail";
+import type { TestPlan } from "../../scaffold/schemas/tmpl_test-plan";
 import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
 
 interface WriteJsonResult {
@@ -145,18 +146,31 @@ async function runWriteJsonCommand(
 }
 
 export async function runApproveTestPlan(
-  deps: Partial<ApproveTestPlanDeps> = {},
+  optsOrDeps: { force?: boolean } | Partial<ApproveTestPlanDeps> = {},
+  maybeDeps: Partial<ApproveTestPlanDeps> = {},
 ): Promise<void> {
+  const isDepsArg =
+    typeof optsOrDeps === "object"
+    && optsOrDeps !== null
+    && (
+      "existsFn" in optsOrDeps
+      || "invokeWriteJsonFn" in optsOrDeps
+      || "nowFn" in optsOrDeps
+      || "readFileFn" in optsOrDeps
+    );
+  const force = isDepsArg ? false : ((optsOrDeps as { force?: boolean }).force ?? false);
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
+  const deps = isDepsArg ? optsOrDeps : maybeDeps;
   const mergedDeps: ApproveTestPlanDeps = { ...defaultDeps, ...deps };
 
   const testPlan = state.phases.prototype.test_plan;
-  if (testPlan.status !== "pending_approval") {
-    throw new Error(
-      `Cannot approve test plan from status '${testPlan.status}'. Expected pending_approval.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    testPlan.status !== "pending_approval",
+    `Cannot approve test plan from status '${testPlan.status}'. Expected pending_approval.`,
+    { force },
+  );
 
   const testPlanFile = testPlan.file;
   if (!testPlanFile) {

package/src/commands/create-issue.test.ts

@@ -420,8 +420,8 @@ describe("create issue --test-execution-report CLI integration", () => {
     const exitCode = await proc.exited;
     const stderr = await new Response(proc.stderr).text();
     expect(stderr).not.toContain("Missing --agent");
-    if (exitCode !== 0) {
-      expect(stderr).toContain("test-execution-results");
+    if (exitCode !== 0 && stderr) {
+      expect(stderr).toMatch(/test-execution-results|not found|Test execution results/);
     }
   });
 

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

@@ -7,44 +7,50 @@ import {
   loadSkill,
   type AgentProvider,
 } from "../agent";
+import { assertGuardrail } from "../guardrail";
 import { exists, readState, writeState } from "../state";
 
 export interface CreateProjectContextOptions {
   provider: AgentProvider;
   mode: "strict" | "yolo";
+  force?: boolean;
 }
 
 export async function runCreateProjectContext(opts: CreateProjectContextOptions): Promise<void> {
-  const { provider, mode } = opts;
+  const { provider, mode, force = false } = opts;
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
 
-  if (state.phases.define.prd_generation.status !== "completed") {
-    throw new Error(
-      "Cannot create project context: define.prd_generation must be completed first.",
-    );
-  }
+  await assertGuardrail(
+    state,
+    state.phases.define.prd_generation.status !== "completed",
+    "Cannot create project context: define.prd_generation must be completed first.",
+    { force },
+  );
 
   const projectContext = state.phases.prototype.project_context;
-  if (projectContext.status === "pending_approval") {
-    throw new Error(
-      "Cannot create project context: project context is pending approval. " +
-      "Run `bun nvst approve project-context` or `bun nvst refine project-context` first.",
-    );
-  }
-
-  if (projectContext.status === "created") {
-    throw new Error(
-      "Cannot create project context: project context already exists. " +
-      "Use `bun nvst refine project-context` to iterate on it.",
-    );
-  }
-
-  if (projectContext.status !== "pending") {
-    throw new Error(
-      `Cannot create project context from status '${projectContext.status}'. Expected pending.`,
-    );
-  }
+  await assertGuardrail(
+    state,
+    projectContext.status === "pending_approval",
+    "Cannot create project context: project context is pending approval. " +
+    "Run `bun nvst approve project-context` or `bun nvst refine project-context` first.",
+    { force },
+  );
+
+  await assertGuardrail(
+    state,
+    projectContext.status === "created",
+    "Cannot create project context: project context already exists. " +
+    "Use `bun nvst refine project-context` to iterate on it.",
+    { force },
+  );
+
+  await assertGuardrail(
+    state,
+    projectContext.status !== "pending",
+    `Cannot create project context from status '${projectContext.status}'. Expected pending.`,
+    { force },
+  );
 
   const prdFile = state.phases.define.prd_generation.file;
   if (!prdFile) {

package/src/commands/create-prototype.test.ts

@@ -63,6 +63,20 @@ async function seedState(projectRoot: string, state: State): Promise<void> {
   await writeState(projectRoot, state);
 }
 
+const MINIMAL_PRD = {
+  goals: [] as string[],
+  userStories: [{ id: "US-001", title: "T", description: "D", acceptanceCriteria: [{ id: "AC1", text: "T" }] }],
+  functionalRequirements: [] as Array<{ id?: string; description: string }>,
+};
+
+async function seedPrd(projectRoot: string, iteration: string): Promise<void> {
+  await writeFile(
+    join(projectRoot, ".agents", "flow", `it_${iteration}_PRD.json`),
+    JSON.stringify(MINIMAL_PRD),
+    "utf8",
+  );
+}
+
 const createdRoots: string[] = [];
 
 afterEach(async () => {
@@ -73,7 +87,9 @@ describe("create prototype phase validation", () => {
   test("throws when current_phase is define and PRD is not completed", async () => {
     const root = await createProjectRoot();
     createdRoots.push(root);
-    await seedState(root, makeState({ currentPhase: "define", prdStatus: "pending", projectContextStatus: "pending" }));
+    const iteration = "000009";
+    await seedState(root, makeState({ currentPhase: "define", prdStatus: "pending", projectContextStatus: "pending", iteration }));
+    await seedPrd(root, iteration);
 
     await withCwd(root, async () => {
       await expect(runCreatePrototype({ provider: "claude" })).rejects.toThrow(
@@ -85,7 +101,9 @@ describe("create prototype phase validation", () => {
   test("throws when current_phase is define and project_context is not created", async () => {
     const root = await createProjectRoot();
     createdRoots.push(root);
-    await seedState(root, makeState({ currentPhase: "define", prdStatus: "completed", projectContextStatus: "pending" }));
+    const iteration = "000009";
+    await seedState(root, makeState({ currentPhase: "define", prdStatus: "completed", projectContextStatus: "pending", iteration }));
+    await seedPrd(root, iteration);
 
     await withCwd(root, async () => {
       await expect(runCreatePrototype({ provider: "claude" })).rejects.toThrow(
@@ -99,29 +117,27 @@ describe("create prototype phase validation", () => {
     createdRoots.push(root);
     const iteration = "000009";
     await seedState(root, makeState({ currentPhase: "define", prdStatus: "completed", projectContextStatus: "created", iteration }));
+    await seedPrd(root, iteration);
 
-    const prdContent = {
-      goals: ["Test"],
-      userStories: [
-        { id: "US-001", title: "One", description: "D", acceptanceCriteria: [{ id: "AC1", text: "T" }] },
-      ],
-      functionalRequirements: [{ id: "FR-001", description: "F" }],
-    };
+    await mkdir(join(root, ".agents"), { recursive: true });
     await writeFile(
-      join(root, ".agents", "flow", `it_${iteration}_PRD.json`),
-      JSON.stringify(prdContent),
+      join(root, ".agents", "PROJECT_CONTEXT.md"),
+      "# Project\n## Testing Strategy\n### Quality Checks\n```\nbun test\n```\n",
       "utf8",
     );
 
     const { $ } = await import("bun");
     await $`git init`.cwd(root).nothrow().quiet();
+    await $`git config user.email "test@test" && git config user.name "Test"`.cwd(root).nothrow().quiet();
+    await $`git add -A && git commit -m init`.cwd(root).nothrow().quiet();
 
     await withCwd(root, async () => {
       await expect(runCreatePrototype({ provider: "claude" })).rejects.toThrow(
-        "Required skill missing",
+        "Git working tree is dirty",
       );
     });
 
+    // Transition writes state before the git check; phase is prototype
     const updatedState = await readState(root);
     expect(updatedState.current_phase).toBe("prototype");
   });
@@ -129,7 +145,9 @@ describe("create prototype phase validation", () => {
   test("throws when current_phase is refactor", async () => {
     const root = await createProjectRoot();
     createdRoots.push(root);
-    await seedState(root, makeState({ currentPhase: "refactor" }));
+    const iteration = "000009";
+    await seedState(root, makeState({ currentPhase: "refactor", iteration }));
+    await seedPrd(root, iteration);
 
     await withCwd(root, async () => {
       await expect(runCreatePrototype({ provider: "claude" })).rejects.toThrow(

package/src/commands/create-prototype.ts

@@ -10,6 +10,7 @@ import {
   loadSkill,
   type AgentProvider,
 } from "../agent";
+import { assertGuardrail } from "../guardrail";
 import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
 
 export interface CreatePrototypeOptions {
@@ -17,6 +18,7 @@ export interface CreatePrototypeOptions {
   iterations?: number;
   retryOnFail?: number;
   stopOnCritical?: boolean;
+  force?: boolean;
 }
 
 const ProgressEntrySchema = z.object({
@@ -106,6 +108,7 @@ function parseQualityChecks(projectContextContent: string): string[] {
 export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<void> {
   const projectRoot = process.cwd();
   const state = await readState(projectRoot);
+  const force = opts.force ?? false;
 
   if (opts.iterations !== undefined && (!Number.isInteger(opts.iterations) || opts.iterations < 1)) {
     throw new Error(
@@ -167,21 +170,28 @@ export async function runCreatePrototype(opts: CreatePrototypeOptions): Promise<
       state.current_phase = "prototype";
       await writeState(projectRoot, state);
     } else {
-      throw new Error(
+      await assertGuardrail(
+        state,
+        true,
         "Cannot create prototype: current_phase is define and prerequisites are not met. Complete define phase and run `bun nvst create project-context --agent <provider>` then `bun nvst approve project-context` first.",
+        { force },
       );
     }
   } else if (state.current_phase !== "prototype") {
-    throw new Error(
+    await assertGuardrail(
+      state,
+      true,
       "Cannot create prototype: current_phase must be define (with approved PRD) or prototype. Complete define phase and run `bun nvst create project-context --agent <provider>` then `bun nvst approve project-context` first.",
+      { force },
     );
   }
 
-  if (state.phases.prototype.project_context.status !== "created") {
-    throw new Error(
-      "Cannot create prototype: prototype.project_context.status must be created. Run `bun nvst create project-context --agent <provider>` and `bun nvst approve project-context` first.",
-    );
-  }
+  await assertGuardrail(
+    state,
+    state.phases.prototype.project_context.status !== "created",
+    "Cannot create prototype: prototype.project_context.status must be created. Run `bun nvst create project-context --agent <provider>` and `bun nvst approve project-context` first.",
+    { force },
+  );
 
   const workingTreeAfterPhase = await dollar`git status --porcelain`.cwd(projectRoot).nothrow().quiet();
   if (workingTreeAfterPhase.exitCode !== 0) {

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

@@ -10,8 +10,9 @@ 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";
 
 export interface CreateTestPlanOptions {
   provider: AgentProvider;
@@ -155,11 +156,12 @@ export async function runCreateTestPlan(
   const state = await readState(projectRoot);
   const mergedDeps: CreateTestPlanDeps = { ...defaultDeps, ...deps };
 
-  if (state.phases.prototype.project_context.status !== "created") {
-    throw new Error(
-      "Cannot create test plan: prototype.project_context.status must be created. Run `bun nvst approve project-context` first.",
-    );
-  }
+  await assertGuardrail(
+    state,
+    state.phases.prototype.project_context.status !== "created",
+    "Cannot create test plan: prototype.project_context.status must be created. Run `bun nvst approve project-context` first.",
+    { force: opts.force },
+  );
 
   const iteration = state.current_iteration;
   const fileName = `it_${iteration}_test-plan.md`;