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

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;
 

package/src/commands/execute-refactor.test.ts

@@ -283,8 +283,8 @@ describe("execute refactor command", () => {
     expect(capturedPrompts[0]).toContain("My Rationale");
   });
 
-  // AC08: Agent invoked in interactive mode
-  test("invokes agent in interactive mode", async () => {
+  // US-002-AC01: Agent invoked in non-interactive mode
+  test("invokes agent with interactive: false (non-interactive mode)", async () => {
     const projectRoot = await createProjectRoot();
     createdRoots.push(projectRoot);
     await seedState(projectRoot);
@@ -308,7 +308,7 @@ describe("execute refactor command", () => {
     });
 
     expect(capturedOptions).toHaveLength(1);
-    expect(capturedOptions[0].interactive).toBe(true);
+    expect(capturedOptions[0].interactive).toBe(false);
     expect(capturedOptions[0].provider).toBe("codex");
   });
 

package/src/commands/execute-refactor.ts

@@ -17,6 +17,7 @@ import {
 } from "../agent";
 import { CLI_PATH } from "../cli-path";
 import { assertGuardrail } from "../guardrail";
+import { applyStatusUpdate, idsMatchExactly, sortedValues } from "../progress-utils";
 import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
 
 export interface ExecuteRefactorOptions {
@@ -181,12 +182,9 @@ export async function runExecuteRefactor(
     }
 
     // AC05: Verify progress item IDs match refactor PRD item IDs
-    const expectedIds = [...refactorItems.map((item) => item.id)].sort((a, b) => a.localeCompare(b));
-    const existingIds = [...progressValidation.data.entries.map((entry) => entry.id)].sort((a, b) => a.localeCompare(b));
-    if (
-      expectedIds.length !== existingIds.length ||
-      expectedIds.some((id, i) => id !== existingIds[i])
-    ) {
+    const expectedIds = sortedValues(refactorItems.map((item) => item.id));
+    const existingIds = sortedValues(progressValidation.data.entries.map((entry) => entry.id));
+    if (!idsMatchExactly(existingIds, expectedIds)) {
       throw new Error(
         "Refactor execution progress file out of sync: entry ids do not match refactor PRD item ids.",
       );
@@ -226,8 +224,7 @@ export async function runExecuteRefactor(
     }
 
     // Set current item to in_progress before invoking agent (FR-4; observability on interrupt)
-    entry.status = "in_progress";
-    entry.updated_at = mergedDeps.nowFn().toISOString();
+    applyStatusUpdate(entry, "in_progress", mergedDeps.nowFn().toISOString());
     const writeInProgressResult = await mergedDeps.invokeWriteJsonFn(
       projectRoot,
       "refactor-execution-progress",
@@ -249,20 +246,19 @@ export async function runExecuteRefactor(
       item_rationale: item.rationale,
     });
 
-    // AC08: Invoke agent in interactive mode
+    // US-002-AC01: Invoke agent in non-interactive mode (autonomous execution)
     const agentResult = await mergedDeps.invokeAgentFn({
       provider: opts.provider,
       prompt,
       cwd: projectRoot,
-      interactive: true,
+      interactive: false,
     });
 
     // AC09 & AC10: Record result after each invocation, continue on failure
     const succeeded = agentResult.exitCode === 0;
-    entry.status = succeeded ? "completed" : "failed";
     entry.attempt_count = entry.attempt_count + 1;
     entry.last_agent_exit_code = agentResult.exitCode;
-    entry.updated_at = mergedDeps.nowFn().toISOString();
+    applyStatusUpdate(entry, succeeded ? "completed" : "failed", mergedDeps.nowFn().toISOString());
 
     const writeResult = await mergedDeps.invokeWriteJsonFn(
       projectRoot,

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

@@ -317,14 +317,15 @@ describe("execute test-plan command", () => {
       join(projectRoot, ".agents", "flow", "it_000005_test-execution-report.md"),
       "utf8",
     );
-    expect(markdownReportRaw).toContain("# Test Execution Report (Iteration 000005)");
-    expect(markdownReportRaw).toContain("- Total Tests: 3");
-    expect(markdownReportRaw).toContain("- Passed: 3");
-    expect(markdownReportRaw).toContain("- Failed: 0");
+    expect(markdownReportRaw).toContain("# Test Execution Report");
+    expect(markdownReportRaw).toContain("**Iteration:** it_000005");
+    expect(markdownReportRaw).toContain("**Total:** 3");
+    expect(markdownReportRaw).toContain("**Passed:** 3");
+    expect(markdownReportRaw).toContain("**Failed:** 0");
 
     const state = await readState(projectRoot);
     expect(state.phases.prototype.test_execution.status).toBe("completed");
-    expect(state.phases.prototype.prototype_approved).toBe(true);
+    expect(state.phases.prototype.prototype_approved).toBe(false);
     expect(state.updated_by).toBe("nvst:execute-test-plan");
   });
 
@@ -538,9 +539,9 @@ describe("execute test-plan command", () => {
       expect(rerunBatchPrompt).not.toContain("TC-US001-01");
     });
 
-    // After retry, all pass -> prototype approved
+    // After retry, all pass -> test execution completed but prototype_approved requires explicit approve
     const stateAfterRetry = await readState(projectRoot);
-    expect(stateAfterRetry.phases.prototype.prototype_approved).toBe(true);
+    expect(stateAfterRetry.phases.prototype.prototype_approved).toBe(false);
 
     const progressRaw = await readFile(
       join(projectRoot, ".agents", "flow", "it_000005_test-execution-progress.json"),
@@ -676,13 +677,12 @@ describe("execute test-plan command", () => {
           promptManualTestFn: async () => {
             return { status: "passed", evidence: "ok", notes: "ok" };
           },
-          writeFileFn: async (path, data) => {
+          writeJsonArtifactFn: async (path, _schema, data) => {
             const pathAsString = path.toString();
             if (pathAsString.endsWith("it_000005_test-execution-progress.json")) {
-              progressSnapshots.push(data.toString());
+              progressSnapshots.push(JSON.stringify(data, null, 2));
             }
-            await writeFile(pathAsString, data.toString(), "utf8");
-            return 0;
+            await writeFile(pathAsString, `${JSON.stringify(data, null, 2)}\n`, "utf8");
           },
         },
       );
@@ -1678,13 +1678,14 @@ describe("US-004: preserve report and state tracking compatibility", () => {
       "utf8",
     );
 
-    expect(markdownRaw).toContain("# Test Execution Report (Iteration 000005)");
-    expect(markdownRaw).toContain("- Test Plan: `it_000005_TP.json`");
-    expect(markdownRaw).toContain("- Total Tests: 3");
-    expect(markdownRaw).toContain("- Passed: 1");
-    expect(markdownRaw).toContain("- Failed: 2");
+    expect(markdownRaw).toContain("# Test Execution Report");
+    expect(markdownRaw).toContain("**Iteration:** it_000005");
+    expect(markdownRaw).toContain("**Test Plan:** `it_000005_TP.json`");
+    expect(markdownRaw).toContain("**Total:** 3");
+    expect(markdownRaw).toContain("**Passed:** 1");
+    expect(markdownRaw).toContain("**Failed:** 2");
     expect(markdownRaw).toContain("| Test ID | Description | Status | Correlated Requirements | Artifacts |");
-    expect(markdownRaw).toContain("| --- | --- | --- | --- | --- |");
+    expect(markdownRaw).toContain("|---------|-------------|--------|------------------------|-----------|");
     // All three test cases appear in table
     expect(markdownRaw).toContain("TC-US001-01");
     expect(markdownRaw).toContain("TC-US001-02");
@@ -1741,11 +1742,11 @@ describe("US-004: preserve report and state tracking compatibility", () => {
     expect(stateSnapshots[0]!.status).toBe("in_progress");
     expect(stateSnapshots[0]!.file).toBe("it_000005_test-execution-progress.json");
 
-    // After execution (all passed): completed and prototype approved
+    // After execution (all passed): completed; prototype_approved requires explicit approve command
     const finalState = await readState(projectRoot);
     expect(finalState.phases.prototype.test_execution.status).toBe("completed");
     expect(finalState.phases.prototype.test_execution.file).toBe("it_000005_test-execution-progress.json");
-    expect(finalState.phases.prototype.prototype_approved).toBe(true);
+    expect(finalState.phases.prototype.prototype_approved).toBe(false);
     expect(finalState.updated_by).toBe("nvst:execute-test-plan");
   });
 

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

@@ -12,8 +12,14 @@ import {
   type AgentResult,
 } from "../agent";
 import { assertGuardrail } from "../guardrail";
+import { applyStatusUpdate, idsMatchExactly, sortedValues } from "../progress-utils";
 import { exists, FLOW_REL_DIR, readState, writeState } from "../state";
+import { writeJsonArtifact, type WriteJsonArtifactFn } from "../write-json-artifact";
 import { TestPlanSchema, type TestPlan } from "../../scaffold/schemas/tmpl_test-plan";
+import {
+  TestExecutionProgressSchema,
+  type TestExecutionProgress,
+} from "../../scaffold/schemas/tmpl_test-execution-progress";
 import { extractJson } from "./create-issue";
 
 export interface ExecuteTestPlanOptions {
@@ -40,24 +46,6 @@ const BatchResultSchema = z.array(BatchResultItemSchema);
 
 type BatchResultItem = z.infer<typeof BatchResultItemSchema>;
 
-const TestExecutionProgressStatusSchema = z.enum(["pending", "in_progress", "passed", "failed"]);
-
-const TestExecutionProgressEntrySchema = z.object({
-  id: z.string(),
-  type: z.enum(["automated", "exploratory_manual"]),
-  status: TestExecutionProgressStatusSchema,
-  attempt_count: z.number().int().nonnegative(),
-  last_agent_exit_code: z.number().int().nullable(),
-  last_error_summary: z.string(),
-  updated_at: z.string(),
-});
-
-const TestExecutionProgressSchema = z.object({
-  entries: z.array(TestExecutionProgressEntrySchema),
-});
-
-type TestExecutionProgress = z.infer<typeof TestExecutionProgressSchema>;
-
 interface FlatTestCase {
   id: string;
   description: string;
@@ -133,6 +121,7 @@ interface ExecuteTestPlanDeps {
   promptManualTestFn: (testCase: FlatTestCase) => Promise<ManualTestUserInput>;
   readFileFn: typeof readFile;
   writeFileFn: typeof Bun.write;
+  writeJsonArtifactFn: WriteJsonArtifactFn;
 }
 
 const defaultDeps: ExecuteTestPlanDeps = {
@@ -144,6 +133,7 @@ const defaultDeps: ExecuteTestPlanDeps = {
   promptManualTestFn: promptManualTest,
   readFileFn: readFile,
   writeFileFn: Bun.write,
+  writeJsonArtifactFn: writeJsonArtifact,
 };
 
 function flattenTests(testPlan: TestPlan): FlatTestCase[] {
@@ -197,24 +187,6 @@ function derivePassFail(status: ExecutionPayload["status"]): "pass" | "fail" | n
   return null;
 }
 
-function sortedValues(values: string[]): string[] {
-  return [...values].sort((a, b) => a.localeCompare(b));
-}
-
-function idsMatchExactly(left: string[], right: string[]): boolean {
-  if (left.length !== right.length) {
-    return false;
-  }
-
-  for (let i = 0; i < left.length; i += 1) {
-    if (left[i] !== right[i]) {
-      return false;
-    }
-  }
-
-  return true;
-}
-
 function toArtifactSafeSegment(value: string): string {
   return value.replace(/[^a-zA-Z0-9_-]/g, "_");
 }
@@ -231,15 +203,16 @@ function buildMarkdownReport(report: TestExecutionReport): string {
   const failedCount = totalTests - passedCount;
 
   const lines = [
-    `# Test Execution Report (Iteration ${report.iteration})`,
+    "# Test Execution Report",
     "",
-    `- Test Plan: \`${report.testPlanFile}\``,
-    `- Total Tests: ${totalTests}`,
-    `- Passed: ${passedCount}`,
-    `- Failed: ${failedCount}`,
+    `**Iteration:** it_${report.iteration}`,
+    `**Test Plan:** \`${report.testPlanFile}\``,
+    `**Total:** ${totalTests}`,
+    `**Passed:** ${passedCount}`,
+    `**Failed:** ${failedCount}`,
     "",
     "| Test ID | Description | Status | Correlated Requirements | Artifacts |",
-    "| --- | --- | --- | --- | --- |",
+    "|---------|-------------|--------|------------------------|-----------|",
   ];
 
   for (const result of report.results) {
@@ -441,7 +414,7 @@ export async function runExecuteTestPlan(
   const executedTestIds: string[] = [];
 
   const writeProgress = async () => {
-    await mergedDeps.writeFileFn(progressPath, `${JSON.stringify(progress, null, 2)}\n`);
+    await mergedDeps.writeJsonArtifactFn(progressPath, TestExecutionProgressSchema, progress);
   };
 
   await mergedDeps.mkdirFn(join(projectRoot, FLOW_REL_DIR), { recursive: true });
@@ -460,8 +433,7 @@ export async function runExecuteTestPlan(
     for (const tc of pendingAutomatedTests) {
       const entry = progress.entries.find((e) => e.id === tc.id);
       if (entry) {
-        entry.status = "in_progress";
-        entry.updated_at = new Date().toISOString();
+        applyStatusUpdate(entry, "in_progress", new Date().toISOString());
       }
     }
     await writeProgress();
@@ -610,8 +582,7 @@ export async function runExecuteTestPlan(
       continue;
     }
 
-    progressEntry.status = "in_progress";
-    progressEntry.updated_at = new Date().toISOString();
+    applyStatusUpdate(progressEntry, "in_progress", new Date().toISOString());
     await writeProgress();
 
     const userInput = await mergedDeps.promptManualTestFn(testCase);
@@ -630,8 +601,7 @@ export async function runExecuteTestPlan(
     progressEntry.attempt_count += 1;
     progressEntry.last_agent_exit_code = null;
     progressEntry.last_error_summary = payload.status === "passed" ? "" : payload.notes;
-    progressEntry.status = payload.status === "passed" ? "passed" : "failed";
-    progressEntry.updated_at = new Date().toISOString();
+    applyStatusUpdate(progressEntry, payload.status === "passed" ? "passed" : "failed", new Date().toISOString());
     await writeProgress();
 
     await mergedDeps.writeFileFn(
@@ -714,9 +684,6 @@ export async function runExecuteTestPlan(
   const hasFailedTests = progress.entries.some((entry) => entry.status === "failed");
   state.phases.prototype.test_execution.status = hasFailedTests ? "failed" : "completed";
   state.phases.prototype.test_execution.file = progressFileName;
-  if (!hasFailedTests) {
-    state.phases.prototype.prototype_approved = true;
-  }
   state.last_updated = mergedDeps.nowFn().toISOString();
   state.updated_by = "nvst:execute-test-plan";
   await writeState(projectRoot, state);

package/src/commands/flow-config.ts

@@ -0,0 +1,79 @@
+export type FlowHandlerKey =
+  | "runCreateProjectContextFn"
+  | "runCreatePrototypeFn"
+  | "runCreateTestPlanFn"
+  | "runDefineRefactorPlanFn"
+  | "runDefineRequirementFn"
+  | "runExecuteRefactorFn"
+  | "runExecuteTestPlanFn";
+
+type FlowStepDefinition = {
+  id: string;
+  label: string;
+  requiresAgent: boolean;
+  handlerKey: FlowHandlerKey;
+};
+
+export const FLOW_STEPS = {
+  "define-requirement": {
+    id: "define-requirement",
+    label: "define requirement",
+    requiresAgent: true,
+    handlerKey: "runDefineRequirementFn",
+  },
+  "create-project-context": {
+    id: "create-project-context",
+    label: "create project-context",
+    requiresAgent: true,
+    handlerKey: "runCreateProjectContextFn",
+  },
+  "create-prototype": {
+    id: "create-prototype",
+    label: "create prototype",
+    requiresAgent: true,
+    handlerKey: "runCreatePrototypeFn",
+  },
+  "create-test-plan": {
+    id: "create-test-plan",
+    label: "create test-plan",
+    requiresAgent: true,
+    handlerKey: "runCreateTestPlanFn",
+  },
+  "execute-test-plan": {
+    id: "execute-test-plan",
+    label: "execute test-plan",
+    requiresAgent: true,
+    handlerKey: "runExecuteTestPlanFn",
+  },
+  "define-refactor-plan": {
+    id: "define-refactor-plan",
+    label: "define refactor-plan",
+    requiresAgent: true,
+    handlerKey: "runDefineRefactorPlanFn",
+  },
+  "execute-refactor": {
+    id: "execute-refactor",
+    label: "execute refactor",
+    requiresAgent: true,
+    handlerKey: "runExecuteRefactorFn",
+  },
+} as const satisfies Record<string, FlowStepDefinition>;
+
+export type FlowStepId = keyof typeof FLOW_STEPS;
+export type FlowStep = (typeof FLOW_STEPS)[FlowStepId];
+
+export const FLOW_APPROVAL_TARGETS = {
+  requirement: "requirement",
+  projectContext: "project-context",
+  testPlan: "test-plan",
+  prototype: "prototype",
+  refactorPlan: "refactor-plan",
+} as const;
+
+export type FlowApprovalTarget = (typeof FLOW_APPROVAL_TARGETS)[keyof typeof FLOW_APPROVAL_TARGETS];
+
+export const FLOW_APPROVAL_GATE_PREFIX = "Waiting for approval. Run: nvst approve";
+
+export function buildApprovalGateMessage(target: FlowApprovalTarget): string {
+  return `${FLOW_APPROVAL_GATE_PREFIX} ${target} to continue, then re-run nvst flow.`;
+}