@emiliosp/pi-maestro 0.10.0 → 0.11.0

package/src/workflow/simplifier/completeSimplifierPass.ts

@@ -0,0 +1,57 @@
+/**
+ * Objective: Save a validated simplifier handoff before completing the workflow.
+ * Used: When the simplifier records its single result.
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { assertSimplifierHandoff } from '#artifacts/simplifier-handoff/assertSimplifierHandoff.ts';
+import type { MaestroPaths } from '#MaestroPaths.ts';
+import { writeJson } from '#utils/write-json.ts';
+import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
+import { WORKFLOW_EVENTS, WORKFLOW_PHASES } from '#workflow/state/schema.ts';
+import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
+import { transitionWorkflow } from '#workflow/transitions.ts';
+
+type CompleteSimplifierPassInput = {
+  paths: MaestroPaths;
+  specId: string;
+  handoff: unknown;
+};
+
+export const completeSimplifierPass = async ({
+  paths,
+  specId,
+  handoff,
+}: CompleteSimplifierPassInput) => {
+  const workflowPath = paths.getWorkflowPath(specId);
+  const state = await readWorkflowState(workflowPath);
+
+  if (state.specId !== specId) {
+    throw new Error(
+      `Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`,
+    );
+  }
+
+  if (state.phase !== WORKFLOW_PHASES.SIMPLIFIER_RUNNING) {
+    throw new Error(
+      `Simplifier handoff requires simplifier-running state, found "${state.phase}".`,
+    );
+  }
+
+  const input = { handoff, specId, projectRoot: paths.getProjectRoot() };
+  assertSimplifierHandoff(input);
+
+  const handoffPath = paths.getSimplifierHandoffPath(specId);
+  await mkdir(dirname(handoffPath), { recursive: true });
+  await writeJson({ path: handoffPath, data: input.handoff });
+
+  const nextState = transitionWorkflow({
+    state,
+    event: WORKFLOW_EVENTS.SIMPLIFIER_DONE,
+  });
+
+  await writeWorkflowState({ path: workflowPath, state: nextState });
+
+  return { handoff: input.handoff, handoffPath, state: nextState };
+};

package/src/workflow/state/schema.ts

@@ -17,6 +17,7 @@ export const WORKFLOW_PHASES = {
   READY_FOR_VERIFIER: 'ready-for-verifier',
   VERIFIER_RUNNING: 'verifier-running',
   FINDING_DECISIONS: 'finding-decisions',
+  SIMPLIFIER_RUNNING: 'simplifier-running',
   CANDIDATE_READY: 'candidate-ready',
 } as const;
 
@@ -30,6 +31,8 @@ export const WORKFLOW_EVENTS = {
   RUN_VERIFIER: 'run-verifier',
   VERIFIER_FOUND_FINDINGS: 'verifier-found-findings',
   VERIFIER_DONE: 'verifier-done',
+  SIMPLIFIER_DONE: 'simplifier-done',
+  SIMPLIFIER_SKIPPED: 'simplifier-skipped',
   OWNER_REJECT_FINDINGS: 'owner-reject-findings',
   OWNER_REQUEST_FIXES: 'owner-request-fixes',
 } as const;
@@ -42,6 +45,7 @@ export const WorkflowPhaseSchema = Type.Union([
   Type.Literal(WORKFLOW_PHASES.READY_FOR_VERIFIER),
   Type.Literal(WORKFLOW_PHASES.VERIFIER_RUNNING),
   Type.Literal(WORKFLOW_PHASES.FINDING_DECISIONS),
+  Type.Literal(WORKFLOW_PHASES.SIMPLIFIER_RUNNING),
   Type.Literal(WORKFLOW_PHASES.CANDIDATE_READY),
 ]);
 

package/src/workflow/transitions.ts

@@ -55,10 +55,18 @@ export const WORKFLOW_TRANSITIONS: Record<WorkflowEvent, WorkflowTransition> = {
   },
   [WORKFLOW_EVENTS.VERIFIER_DONE]: {
     from: [WORKFLOW_PHASES.VERIFIER_RUNNING],
-    to: WORKFLOW_PHASES.CANDIDATE_READY,
+    to: WORKFLOW_PHASES.SIMPLIFIER_RUNNING,
   },
   [WORKFLOW_EVENTS.OWNER_REJECT_FINDINGS]: {
     from: [WORKFLOW_PHASES.FINDING_DECISIONS],
+    to: WORKFLOW_PHASES.SIMPLIFIER_RUNNING,
+  },
+  [WORKFLOW_EVENTS.SIMPLIFIER_DONE]: {
+    from: [WORKFLOW_PHASES.SIMPLIFIER_RUNNING],
+    to: WORKFLOW_PHASES.CANDIDATE_READY,
+  },
+  [WORKFLOW_EVENTS.SIMPLIFIER_SKIPPED]: {
+    from: [WORKFLOW_PHASES.SIMPLIFIER_RUNNING],
     to: WORKFLOW_PHASES.CANDIDATE_READY,
   },
   [WORKFLOW_EVENTS.OWNER_REQUEST_FIXES]: {
@@ -77,22 +85,21 @@ export const transitionWorkflow = ({
   event,
 }: TransitionWorkflowInput): WorkflowState => {
   assertWorkflowState(state);
-  const current = state;
   const transition = WORKFLOW_TRANSITIONS[event];
 
   if (transition === undefined) {
     throw new Error(`Unknown workflow event: "${event}".`);
   }
 
-  if (!transition.from.includes(current.phase)) {
+  if (!transition.from.includes(state.phase)) {
     throw new Error(
-      `Workflow event "${event}" is not allowed from phase "${current.phase}".`,
+      `Workflow event "${event}" is not allowed from phase "${state.phase}".`,
     );
   }
 
   return {
-    version: current.version,
-    specId: current.specId,
+    version: state.version,
+    specId: state.specId,
     phase: transition.to,
   };
 };

package/src/workflow/utils/getAgentRole.ts

@@ -1,6 +1,6 @@
 /**
  * Objective: Resolve the agent responsible for a workflow phase.
- * Used: When workflow logic maps persisted phases to builder or verifier roles.
+ * Used: When workflow logic maps persisted phases to agent roles.
  */
 
 import type { WorkflowRole } from '#workflow/roles.ts';
@@ -29,5 +29,9 @@ export const getAgentRole = (
     return WORKFLOW_ROLES.VERIFIER;
   }
 
+  if (phase === WORKFLOW_PHASES.SIMPLIFIER_RUNNING) {
+    return WORKFLOW_ROLES.SIMPLIFIER;
+  }
+
   return null;
 };

package/src/workflow/verifier/resolveFindings.ts

@@ -18,56 +18,42 @@ import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
 import { getWorkflowEventByVerifierHandoff } from '#workflow/verifier/utils/getWorkflowEventByVerifierHandoff.ts';
 
-type FindingDecisionRejected = {
-  findingId: string;
-  decision: typeof FINDING_DECISIONS.REJECT;
-  reason: string;
-};
-
-type FindingDecisionApproved = {
-  findingId: string;
-  decision: typeof FINDING_DECISIONS.FIX_CODE;
-};
+type SavedFindingDecision = NonNullable<VerifierFinding['decision']>;
 
-type FindingDecisionRevision = {
+export type FindingDecision = SavedFindingDecision & {
   findingId: string;
-  decision: typeof FINDING_DECISIONS.REVISE_SPEC;
-  reason: string;
-  specChange: string;
 };
 
-export type FindingDecision =
-  | FindingDecisionApproved
-  | FindingDecisionRejected
-  | FindingDecisionRevision;
-
 export type ResolvedFindings = {
   findings: VerifierFinding[];
   state: WorkflowState;
   projectRoot: string;
 };
 
-type AssertDecisionsInput = {
+type ApplyFindingDecisionsInput = {
   decisions: FindingDecision[];
   findings: VerifierFinding[];
 };
 
-function assertDecisions({ decisions, findings }: AssertDecisionsInput): void {
+const applyFindingDecisions = ({
+  decisions,
+  findings,
+}: ApplyFindingDecisionsInput): VerifierFinding[] => {
   const expectedIds = new Set(findings.map(({ id }) => id));
-  const seenIds = new Set<string>();
+  const decisionsById = new Map<string, FindingDecision>();
 
   for (const decision of decisions) {
     if (!expectedIds.has(decision.findingId)) {
       throw new Error(`Unknown finding ID: "${decision.findingId}".`);
     }
 
-    if (seenIds.has(decision.findingId)) {
+    if (decisionsById.has(decision.findingId)) {
       throw new Error(
         `Duplicate decision for finding "${decision.findingId}".`,
       );
     }
 
-    seenIds.add(decision.findingId);
+    decisionsById.set(decision.findingId, decision);
 
     if (
       decision.decision === FINDING_DECISIONS.REJECT &&
@@ -79,12 +65,17 @@ function assertDecisions({ decisions, findings }: AssertDecisionsInput): void {
     }
   }
 
-  const missing = findings.find(({ id }) => !seenIds.has(id));
+  const missing = findings.find(({ id }) => !decisionsById.has(id));
 
   if (missing !== undefined) {
     throw new Error(`Missing decision for finding "${missing.id}".`);
   }
-}
+
+  return findings.map((finding) => ({
+    ...finding,
+    decision: getSavedFindingDecision(decisionsById.get(finding.id)),
+  }));
+};
 
 type FindingWorkflow = {
   state: WorkflowState;
@@ -134,62 +125,25 @@ const readFindingWorkflow = async ({
   return { state, handoff };
 };
 
-type BuildFindingWorkflowInput = {
-  workflow: FindingWorkflow;
-  decisions: FindingDecision[];
-};
-
-const buildFindingWorkflow = ({
-  workflow,
-  decisions,
-}: BuildFindingWorkflowInput): FindingWorkflow => {
-  const { state, handoff } = workflow;
-  assertDecisions({ decisions, findings: handoff.findings });
-
-  const decisionsById = new Map(
-    decisions.map((decision) => [decision.findingId, decision]),
-  );
-
-  const findings = handoff.findings.map((finding) => {
-    const decision = decisionsById.get(finding.id);
-
-    if (decision?.decision === FINDING_DECISIONS.REVISE_SPEC) {
-      return {
-        ...finding,
-        decision: {
-          decision: FINDING_DECISIONS.REVISE_SPEC,
-          reason: decision.reason,
-          specChange: decision.specChange,
-        },
-      };
-    }
-
-    if (decision?.decision === FINDING_DECISIONS.REJECT) {
-      return {
-        ...finding,
-        decision: {
-          decision: FINDING_DECISIONS.REJECT,
-          reason: decision.reason.trim(),
-        },
-      };
-    }
-
-    return { ...finding, decision: { decision: FINDING_DECISIONS.FIX_CODE } };
-  });
-
-  const nextHandoff = { ...handoff, findings };
-
-  const nextState = transitionWorkflow({
-    state,
-    event: getWorkflowEventByVerifierHandoff(nextHandoff),
-  });
+const getSavedFindingDecision = (
+  decision: FindingDecision | undefined,
+): SavedFindingDecision => {
+  if (decision?.decision === FINDING_DECISIONS.REVISE_SPEC) {
+    return {
+      decision: FINDING_DECISIONS.REVISE_SPEC,
+      reason: decision.reason.trim(),
+      specChange: decision.specChange,
+    };
+  }
 
-  assertVerifierHandoff({
-    handoff: nextHandoff,
-    specId: state.specId,
-  });
+  if (decision?.decision === FINDING_DECISIONS.REJECT) {
+    return {
+      decision: FINDING_DECISIONS.REJECT,
+      reason: decision.reason.trim(),
+    };
+  }
 
-  return { state: nextState, handoff: nextHandoff };
+  return { decision: FINDING_DECISIONS.FIX_CODE };
 };
 
 type ResolveFindingsInput = {
@@ -203,23 +157,35 @@ export const resolveFindings = async ({
   specId,
   decisions,
 }: ResolveFindingsInput): Promise<ResolvedFindings> => {
-  const currentWorkflow = await readFindingWorkflow({ paths, specId });
+  const { state, handoff } = await readFindingWorkflow({ paths, specId });
 
-  const workflow = buildFindingWorkflow({
-    workflow: currentWorkflow,
+  const findings = applyFindingDecisions({
     decisions,
+    findings: handoff.findings,
+  });
+
+  const nextHandoff = { ...handoff, findings };
+
+  const nextState = transitionWorkflow({
+    state,
+    event: getWorkflowEventByVerifierHandoff(nextHandoff),
+  });
+
+  assertVerifierHandoff({
+    handoff: nextHandoff,
+    specId: state.specId,
   });
 
   const handoffPath = await paths.getActiveVerifierHandoffPath(specId);
-  await writeJson({ path: handoffPath, data: workflow.handoff });
+  await writeJson({ path: handoffPath, data: nextHandoff });
   await writeWorkflowState({
     path: paths.getWorkflowPath(specId),
-    state: workflow.state,
+    state: nextState,
   });
 
   return {
-    findings: workflow.handoff.findings,
-    state: workflow.state,
+    findings,
+    state: nextState,
     projectRoot: paths.getProjectRoot(),
   };
 };

package/templates/spec.md

@@ -25,7 +25,7 @@ Leave local implementation choices, test code, fixtures, mocks, and commands to
 
 ### Edge cases and error handling
 
-<Describe boundary conditions, failures, and required recovery behavior not already covered above. Cover each required case in the acceptance criteria.>
+<Describe boundary conditions, failures, and required recovery behavior not already covered above. Keep these requirements even when existing tests cover their scenarios.>
 
 ## 3. Technical decisions and prototypes
 
@@ -45,16 +45,20 @@ Leave local implementation choices, test code, fixtures, mocks, and commands to
 
 ## 4. Acceptance criteria
 
-<Give each criterion a unique ID and one observable claim. A probe is the scenario used to check that claim. Describe it in plain language.>
+<Inspect existing tests before writing criteria. Omit a criterion only if a test covers the same starting conditions, action, and expected result. Keep criteria when coverage is partial or uncertain. During review, remove criteria already covered by tests. Keep numbering continuous from AC1 and update affected references. Keep required behavior in section 2 even when its criterion is omitted.>
+
+<Give each criterion a unique ID, one observable claim, and one coverage label. A probe is the scenario used to check that claim. Describe it in plain language. Use success for a valid action that produces the required result. Use failure for an invalid action that is correctly rejected. Use unchanged when the criterion explicitly checks existing behavior that the change must preserve. The label describes the scenario, not the test outcome. A failure scenario passes when the invalid action is correctly rejected. Do not require all three categories.>
 
 ### AC1: <short observable claim>
 
-1. Probe: <starting conditions and action or observation, without prescribing test implementation>
-2. Expected result: <observable and measurable outcome>
-3. Example: <specific starting conditions, concrete input or action, and exact expected result for this probe, not a restatement of the claim>
+1. Coverage: <success | failure | unchanged>
+2. Probe: <starting conditions and action or observation, without prescribing test implementation>
+3. Expected result: <observable and measurable outcome>
+4. Example: <specific starting conditions, concrete input or action, and exact expected result for this probe, not a restatement of the claim>
 
 <!--
 Example:
+Coverage: success
 Probe: Save a change to an item's title, then reopen the item.
 Expected result: The saved title is still present.
 Example: An item's title is "Draft". Change it to "Ready", save, and reopen the item. The title is "Ready".