@emiliosp/pi-maestro 0.10.1 → 0.12.0

package/src/tools/child/record-verifier-handoff.ts

@@ -5,6 +5,7 @@
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
+
 import { BuilderAcceptanceCriterionSchema } from '#artifacts/builder-handoff/schema.ts';
 import {
   VERIFIER_HANDOFF_VERSION,
@@ -57,9 +58,7 @@ export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
         specId,
       });
 
-      const currentState = await readWorkflowState(
-        paths.getWorkflowPath(specId),
-      );
+      const currentState = await readWorkflowState(paths.getWorkflowPath(specId));
 
       const handoff = {
         version: VERIFIER_HANDOFF_VERSION,

package/src/tools/child/utils/resolveWorkflowContext.ts

@@ -11,10 +11,7 @@ export type ResolveWorkflowContextInput = {
   specId: string;
 };
 
-export const resolveWorkflowContext = async ({
-  cwd,
-  specId,
-}: ResolveWorkflowContextInput) => {
+export const resolveWorkflowContext = async ({ cwd, specId }: ResolveWorkflowContextInput) => {
   if (!isValidSpecId(specId)) {
     throw new Error(`Invalid spec ID: "${specId}".`);
   }

package/src/tools/main/create-spec.ts

@@ -5,6 +5,7 @@
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
+
 import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import { createSpec } from '#specs/create.ts';
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
@@ -13,7 +14,7 @@ export const CREATE_SPEC_TOOL = {
   NAME: 'maestro_create_spec',
   LABEL: 'Create Spec',
   DESCRIPTION:
-    'Create a new Maestro specification in drafting-spec phase from the approved template. Review the generated spec with the owner before marking it ready.',
+    'Create proposal.md and spec.md in drafting-spec from the bundled templates. Add design.md only when significant technical decisions are needed. Review all present documents with the owner before marking the specification ready.',
 } as const;
 
 const CreateSpecToolParameters = Type.Object(
@@ -44,7 +45,7 @@ export const registerCreateSpecTool = (pi: ExtensionAPI): void => {
         content: [
           {
             type: 'text',
-            text: `Spec ${created.specId} created in drafting-spec phase. Review ${created.specFilePath} with the owner before marking it ready.`,
+            text: `Spec ${created.specId} created in drafting-spec phase. Review ${created.proposalFilePath} and ${created.specFilePath} with the owner. Add ${created.designFilePath} only when significant technical decisions are needed; include it in the same approval.`,
           },
         ],
         details: created,

package/src/tools/main/mark-spec-ready.ts

@@ -5,6 +5,7 @@
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
+
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
@@ -14,7 +15,7 @@ export const MARK_SPEC_READY_TOOL = {
   NAME: 'maestro_mark_spec_ready',
   LABEL: 'Mark Spec Ready',
   DESCRIPTION:
-    'Approve the current spec.md only from drafting-spec after the owner replies GREEN FLAG, then move to ready-for-builder. Only the owner reply GREEN FLAG authorizes approval. After this transition succeeds, call maestro_run_builder in the foreground.',
+    'Approve proposal.md and spec.md together with design.md if present, only from drafting-spec after the owner replies GREEN FLAG. Freeze all present documents and move to ready-for-builder. Only the owner reply GREEN FLAG authorizes approval. After this transition succeeds, call maestro_run_builder in the foreground.',
 } as const;
 
 const MarkSpecReadyToolParameters = Type.Object(

package/src/tools/main/resolve-escalations.ts

@@ -5,6 +5,7 @@
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
+
 import {
   ESCALATION_ID_PATTERN,
   EscalationResolutionSchema,

package/src/tools/main/resolve-findings.ts

@@ -6,6 +6,7 @@
 import { StringEnum } from '@earendil-works/pi-ai';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { Type } from 'typebox';
+
 import { FINDING_DECISIONS } from '#artifacts/verifier-handoff/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
@@ -86,9 +87,7 @@ const formatResolution = (details: FindingResolutionDetails): string => {
   const summary = `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}.`;
 
   if (details.phase === WORKFLOW_PHASES.DRAFTING_SPEC) {
-    const requiringRevision = formatFindingIds(
-      details.findingsRequiringSpecRevisionIds,
-    );
+    const requiringRevision = formatFindingIds(details.findingsRequiringSpecRevisionIds);
 
     return `${summary} Findings requiring spec revision: ${requiringRevision}. The workflow is drafting-spec. Revise the same spec with the owner and obtain renewed GREEN FLAG. Then call maestro_mark_spec_ready separately before running the builder.`;
   }
@@ -97,7 +96,7 @@ const formatResolution = (details: FindingResolutionDetails): string => {
     return `${summary} The workflow is ready-for-builder. Run the builder separately.`;
   }
 
-  return `${summary} The workflow is candidate-ready.`;
+  return `${summary} The workflow is simplifier-running. Call maestro_run_simplifier next with this specId, without another approval or verifier pass.`;
 };
 
 export const registerResolveFindingsTool = (pi: ExtensionAPI): void => {
@@ -106,13 +105,7 @@ export const registerResolveFindingsTool = (pi: ExtensionAPI): void => {
     label: RESOLVE_FINDINGS_TOOL.LABEL,
     description: RESOLVE_FINDINGS_TOOL.DESCRIPTION,
     parameters: ResolveFindingsToolParameters,
-    async execute(
-      _toolCallId,
-      { specId, decisions },
-      _signal,
-      _onUpdate,
-      context,
-    ) {
+    async execute(_toolCallId, { specId, decisions }, _signal, _onUpdate, context) {
       const { paths } = await resolveToolRunContext(context.cwd);
 
       const resolved = await resolveFindings({
@@ -126,20 +119,13 @@ export const registerResolveFindingsTool = (pi: ExtensionAPI): void => {
         phase: resolved.state.phase,
         projectRoot: resolved.projectRoot,
         rejectedFindingIds: resolved.findings
-          .filter(
-            ({ decision }) => decision?.decision === FINDING_DECISIONS.REJECT,
-          )
+          .filter(({ decision }) => decision?.decision === FINDING_DECISIONS.REJECT)
           .map(({ id }) => id),
         findingsRequiringSpecRevisionIds: resolved.findings
-          .filter(
-            ({ decision }) =>
-              decision?.decision === FINDING_DECISIONS.REVISE_SPEC,
-          )
+          .filter(({ decision }) => decision?.decision === FINDING_DECISIONS.REVISE_SPEC)
           .map(({ id }) => id),
         findingsRequiringFixIds: resolved.findings
-          .filter(
-            ({ decision }) => decision?.decision === FINDING_DECISIONS.FIX_CODE,
-          )
+          .filter(({ decision }) => decision?.decision === FINDING_DECISIONS.FIX_CODE)
           .map(({ id }) => id),
       };
 

package/src/tools/main/run-builder.ts

@@ -4,9 +4,11 @@
  */
 
 import { randomUUID } from 'node:crypto';
+
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import type { SubagentDelegationRequest } from 'pi-subagents/delegation';
 import { Type } from 'typebox';
+
 import { readBuilderHandoff } from '#artifacts/builder-handoff/readBuilderHandoff.ts';
 import {
   BUILDER_HANDOFF_STATUSES,
@@ -14,8 +16,8 @@ import {
 } from '#artifacts/builder-handoff/schema.ts';
 import { AGENTS } from '#config/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-import type { MaestroPaths } from '#MaestroPaths.ts';
 import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
+import type { MaestroPaths } from '#MaestroPaths.ts';
 import {
   assertDelegationResponse,
   waitForDelegationResponse,
@@ -24,7 +26,7 @@ import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { prepareBuilderRun } from '#workflow/builder/prepareBuilderRun.ts';
 import { WORKFLOW_ROLES } from '#workflow/roles.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
+import { WORKFLOW_PHASES } from '#workflow/state/schema.ts';
 
 export const RUN_BUILDER_TOOL = {
   NAME: 'maestro_run_builder',
@@ -69,76 +71,54 @@ const readBuilderResult = async ({
     const state = await readWorkflowState(paths.getWorkflowPath(specId));
 
     if (state.specId !== specId) {
-      throw new Error(
-        `Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`,
-      );
+      throw new Error(`Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`);
     }
 
-    return await readTerminalBuilderResult({ paths, specId, state });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-
-    throw new Error(`Builder protocol error: ${message}.`, { cause: error });
-  }
-};
+    if (
+      state.phase !== WORKFLOW_PHASES.READY_FOR_VERIFIER &&
+      state.phase !== WORKFLOW_PHASES.ESCALATION_DECISIONS
+    ) {
+      throw new Error(`Builder returned with unexpected workflow phase "${state.phase}".`);
+    }
 
-type ReadTerminalBuilderResultInput = {
-  paths: MaestroPaths;
-  specId: string;
-  state: WorkflowState;
-};
+    const handoff = await readBuilderHandoff({
+      path: await paths.getActiveBuilderHandoffPath(specId),
+      specId,
+    });
 
-const readTerminalBuilderResult = async ({
-  paths,
-  specId,
-  state,
-}: ReadTerminalBuilderResultInput): Promise<BuilderRunResult> => {
-  if (
-    state.phase !== WORKFLOW_PHASES.READY_FOR_VERIFIER &&
-    state.phase !== WORKFLOW_PHASES.ESCALATION_DECISIONS
-  ) {
-    throw new Error(
-      `Builder returned with unexpected workflow phase "${state.phase}".`,
-    );
-  }
+    const expectedStatus =
+      state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER
+        ? BUILDER_HANDOFF_STATUSES.DONE
+        : BUILDER_HANDOFF_STATUSES.ESCALATION;
 
-  const handoff = await readBuilderHandoff({
-    path: await paths.getActiveBuilderHandoffPath(specId),
-    specId,
-  });
+    if (handoff.status !== expectedStatus) {
+      throw new Error(`Builder handoff status does not match workflow phase "${state.phase}".`);
+    }
 
-  const expectedStatus =
-    state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER
-      ? BUILDER_HANDOFF_STATUSES.DONE
-      : BUILDER_HANDOFF_STATUSES.ESCALATION;
+    if (state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER) {
+      return {
+        outcome: BUILDER_HANDOFF_STATUSES.DONE,
+        specId,
+        phase: state.phase,
+        handoff,
+      };
+    }
 
-  if (handoff.status !== expectedStatus) {
-    throw new Error(
-      `Builder handoff status does not match workflow phase "${state.phase}".`,
-    );
-  }
+    if (handoff.escalations.some(({ resolution }) => resolution !== null)) {
+      throw new Error('Current builder escalations already contain an owner resolution.');
+    }
 
-  if (state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER) {
     return {
-      outcome: BUILDER_HANDOFF_STATUSES.DONE,
+      outcome: BUILDER_HANDOFF_STATUSES.ESCALATION,
       specId,
       phase: state.phase,
       handoff,
     };
-  }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
 
-  if (handoff.escalations.some(({ resolution }) => resolution !== null)) {
-    throw new Error(
-      'Current builder escalations already contain an owner resolution.',
-    );
+    throw new Error(`Builder protocol error: ${message}.`, { cause: error });
   }
-
-  return {
-    outcome: BUILDER_HANDOFF_STATUSES.ESCALATION,
-    specId,
-    phase: state.phase,
-    handoff,
-  };
 };
 
 const formatBuilderResult = (result: BuilderRunResult): string => {

package/src/tools/main/run-simplifier.ts

@@ -0,0 +1,172 @@
+/**
+ * Objective: Run the simplifier in Git projects or explicitly skip unavailable Git.
+ * Used: After verification succeeds or the owner rejects all findings.
+ */
+
+import { randomUUID } from 'node:crypto';
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { SubagentDelegationRequest } from 'pi-subagents/delegation';
+import { Type } from 'typebox';
+
+import { readSimplifierHandoff } from '#artifacts/simplifier-handoff/readSimplifierHandoff.ts';
+import { AGENTS } from '#config/schema.ts';
+import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
+import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
+import type { MaestroPaths } from '#MaestroPaths.ts';
+import {
+  assertDelegationResponse,
+  waitForDelegationResponse,
+} from '#tools/utils/pi-subagent-delegation.ts';
+import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
+import { WORKFLOW_ROLES } from '#workflow/roles.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';
+
+export const RUN_SIMPLIFIER_TOOL = {
+  NAME: 'maestro_run_simplifier',
+  LABEL: 'Run Simplifier',
+  DESCRIPTION:
+    'Run the simplifier in the foreground from simplifier-running. If Git readiness cannot be confirmed, warn and complete without delegation.',
+} as const;
+
+const RunSimplifierToolParameters = Type.Object(
+  { specId: Type.String({ pattern: SPEC_ID_PATTERN.source }) },
+  { additionalProperties: false },
+);
+
+const MILLISECONDS_PER_MINUTE = 60_000;
+
+const GIT_SKIP_WARNING = 'Simplifier skipped: Git repository unavailable.';
+
+type GitReadinessInput = {
+  pi: ExtensionAPI;
+  projectRoot: string;
+};
+
+const isGitReady = async ({ pi, projectRoot }: GitReadinessInput): Promise<boolean> => {
+  try {
+    const result = await pi.exec('git', ['rev-parse', '--is-inside-work-tree'], {
+      cwd: projectRoot,
+    });
+
+    return result.code === 0 && result.stdout.trim() === 'true';
+  } catch {
+    return false;
+  }
+};
+
+type ReadSimplifierResultInput = {
+  paths: MaestroPaths;
+  specId: string;
+};
+
+const readSimplifierResult = async ({ paths, specId }: ReadSimplifierResultInput) => {
+  try {
+    const state = await readWorkflowState(paths.getWorkflowPath(specId));
+
+    if (state.specId !== specId) {
+      throw new Error(`Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`);
+    }
+
+    if (state.phase !== WORKFLOW_PHASES.CANDIDATE_READY) {
+      throw new Error(
+        `The simplifier returned without recording a valid terminal handoff. Workflow phase is "${state.phase}".`,
+      );
+    }
+
+    const handoff = await readSimplifierHandoff({
+      path: paths.getSimplifierHandoffPath(specId),
+      specId,
+      projectRoot: paths.getProjectRoot(),
+    });
+
+    return { specId, phase: state.phase, outcome: state.phase, handoff };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Simplifier protocol error: ${message}`, { cause: error });
+  }
+};
+
+export const registerRunSimplifierTool = (pi: ExtensionAPI): void => {
+  pi.registerTool({
+    name: RUN_SIMPLIFIER_TOOL.NAME,
+    label: RUN_SIMPLIFIER_TOOL.LABEL,
+    description: RUN_SIMPLIFIER_TOOL.DESCRIPTION,
+    parameters: RunSimplifierToolParameters,
+    async execute(toolCallId, { specId }, _signal, _onUpdate, context) {
+      const { paths, config, projectRoot } = await resolveToolRunContext(context.cwd);
+
+      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 run requires simplifier-running state, found "${state.phase}".`,
+        );
+      }
+
+      await refreshMaestroStatus(context);
+
+      if (!(await isGitReady({ pi, projectRoot }))) {
+        const nextState = transitionWorkflow({
+          state,
+          event: WORKFLOW_EVENTS.SIMPLIFIER_SKIPPED,
+        });
+
+        await writeWorkflowState({ path: workflowPath, state: nextState });
+        context.ui.notify(GIT_SKIP_WARNING, 'warning');
+
+        return {
+          content: [{ type: 'text', text: GIT_SKIP_WARNING }],
+          details: {
+            specId,
+            phase: nextState.phase,
+            skipped: true,
+            warning: GIT_SKIP_WARNING,
+          },
+        };
+      }
+
+      const request: SubagentDelegationRequest = {
+        requestId: randomUUID(),
+        ownerRunId: toolCallId,
+        nodeId: WORKFLOW_ROLES.SIMPLIFIER,
+        agent: AGENTS.SIMPLIFIER,
+        task: `Simplify accepted code for specId "${specId}" in the project directory "${projectRoot}". Discover all current staged, unstaged, and untracked code changes with Git, including pre-existing changes.`,
+        context: 'fresh',
+        cwd: projectRoot,
+        model: config.simplifier.model,
+        thinking: config.simplifier.thinking,
+        timeoutMs: config.simplifier.timeoutMinutes * MILLISECONDS_PER_MINUTE,
+        result: { kind: 'text' },
+      };
+
+      const response = await waitForDelegationResponse({
+        piEventsBus: pi.events,
+        request,
+      });
+
+      assertDelegationResponse(response);
+      const result = await readSimplifierResult({ paths, specId });
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Simplifier completed spec ${specId}. The workflow is candidate-ready. Report the saved simplifier summary and notes as its report, not verifier evidence.`,
+          },
+        ],
+        details: result,
+      };
+    },
+  });
+};

package/src/tools/main/run-verifier.ts

@@ -4,15 +4,17 @@
  */
 
 import { randomUUID } from 'node:crypto';
+
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import type { SubagentDelegationRequest } from 'pi-subagents/delegation';
 import { Type } from 'typebox';
+
 import { readVerifierHandoff } from '#artifacts/verifier-handoff/readVerifierHandoff.ts';
 import type { VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
 import { AGENTS } from '#config/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-import type { MaestroPaths } from '#MaestroPaths.ts';
 import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
+import type { MaestroPaths } from '#MaestroPaths.ts';
 import {
   assertDelegationResponse,
   waitForDelegationResponse,
@@ -20,7 +22,7 @@ import {
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { WORKFLOW_ROLES } from '#workflow/roles.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
+import { WORKFLOW_PHASES } from '#workflow/state/schema.ts';
 import { prepareVerifierRun } from '#workflow/verifier/prepareVerifierRun.ts';
 
 export const RUN_VERIFIER_TOOL = {
@@ -40,7 +42,7 @@ const RunVerifierToolParameters = Type.Object(
 const MILLISECONDS_PER_MINUTE = 60_000;
 
 type VerifierTerminalPhase =
-  | typeof WORKFLOW_PHASES.CANDIDATE_READY
+  | typeof WORKFLOW_PHASES.SIMPLIFIER_RUNNING
   | typeof WORKFLOW_PHASES.FINDING_DECISIONS;
 
 type VerifierRunResult = {
@@ -50,50 +52,6 @@ type VerifierRunResult = {
   handoff: VerifierHandoff;
 };
 
-type ReadTerminalVerifierResultInput = {
-  paths: MaestroPaths;
-  specId: string;
-  state: WorkflowState;
-};
-
-const readTerminalVerifierResult = async ({
-  paths,
-  specId,
-  state,
-}: ReadTerminalVerifierResultInput): Promise<VerifierRunResult> => {
-  if (
-    state.phase !== WORKFLOW_PHASES.CANDIDATE_READY &&
-    state.phase !== WORKFLOW_PHASES.FINDING_DECISIONS
-  ) {
-    throw new Error(
-      `Verifier returned with unexpected workflow phase "${state.phase}".`,
-    );
-  }
-
-  const handoff = await readVerifierHandoff({
-    path: await paths.getActiveVerifierHandoffPath(specId),
-    specId,
-  });
-
-  const expectedPhase =
-    handoff.findings.length > 0
-      ? WORKFLOW_PHASES.FINDING_DECISIONS
-      : WORKFLOW_PHASES.CANDIDATE_READY;
-
-  if (state.phase !== expectedPhase) {
-    throw new Error(
-      `Verifier handoff findings do not match workflow phase "${state.phase}".`,
-    );
-  }
-
-  return {
-    specId,
-    handoff,
-    outcome: state.phase,
-    phase: state.phase,
-  };
-};
-
 type ReadVerifierResultInput = {
   paths: MaestroPaths;
   specId: string;
@@ -107,22 +65,40 @@ const readVerifierResult = async ({
     const state = await readWorkflowState(paths.getWorkflowPath(specId));
 
     if (state.specId !== specId) {
-      throw new Error(
-        `Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`,
-      );
+      throw new Error(`Workflow spec ID mismatch: expected "${specId}", found "${state.specId}".`);
     }
 
     if (state.phase === WORKFLOW_PHASES.VERIFIER_RUNNING) {
-      throw new Error(
-        'The verifier returned without recording a valid terminal handoff.',
-      );
+      throw new Error('The verifier returned without recording a valid terminal handoff.');
     }
 
-    return await readTerminalVerifierResult({
-      paths,
+    if (
+      state.phase !== WORKFLOW_PHASES.SIMPLIFIER_RUNNING &&
+      state.phase !== WORKFLOW_PHASES.FINDING_DECISIONS
+    ) {
+      throw new Error(`Verifier returned with unexpected workflow phase "${state.phase}".`);
+    }
+
+    const handoff = await readVerifierHandoff({
+      path: await paths.getActiveVerifierHandoffPath(specId),
       specId,
-      state,
     });
+
+    const expectedPhase =
+      handoff.findings.length > 0
+        ? WORKFLOW_PHASES.FINDING_DECISIONS
+        : WORKFLOW_PHASES.SIMPLIFIER_RUNNING;
+
+    if (state.phase !== expectedPhase) {
+      throw new Error(`Verifier handoff findings do not match workflow phase "${state.phase}".`);
+    }
+
+    return {
+      specId,
+      handoff,
+      outcome: state.phase,
+      phase: state.phase,
+    };
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
 
@@ -131,8 +107,8 @@ const readVerifierResult = async ({
 };
 
 const formatVerifierResult = (result: VerifierRunResult): string => {
-  if (result.outcome === WORKFLOW_PHASES.CANDIDATE_READY) {
-    return `Verifier completed spec ${result.specId}. The workflow is candidate-ready.`;
+  if (result.outcome === WORKFLOW_PHASES.SIMPLIFIER_RUNNING) {
+    return `Verifier completed spec ${result.specId}. The workflow is simplifier-running. Call maestro_run_simplifier next with this specId, without another approval or verifier pass.`;
   }
 
   return `Verifier found ${result.handoff.findings.length} finding(s) for spec ${result.specId}. The workflow is waiting for owner decisions.`;

package/src/tools/utils/pi-subagent-delegation.ts

@@ -50,8 +50,7 @@ export const matchesDelegationRequest = ({
 
   return (
     response.requestId === request.requestId &&
-    (response.ownerRunId === undefined ||
-      response.ownerRunId === request.ownerRunId) &&
+    (response.ownerRunId === undefined || response.ownerRunId === request.ownerRunId) &&
     (response.nodeId === undefined || response.nodeId === request.nodeId)
   );
 };
@@ -65,20 +64,16 @@ export const waitForDelegationResponse = async ({
   piEventsBus,
   request,
 }: WaitForDelegationResponseInput): Promise<SubagentDelegationResponse> => {
-  const { promise, resolve } =
-    Promise.withResolvers<SubagentDelegationResponse>();
-
-  const unsubscribe = piEventsBus.on(
-    SUBAGENT_DELEGATION_RESPONSE_EVENT,
-    (payload) => {
-      if (!matchesDelegationRequest({ request, payload })) {
-        return;
-      }
-
-      // JUSTIFICATION: matchesDelegationRequest accepts only the response for this pi-subagents request.
-      resolve(payload as SubagentDelegationResponse);
-    },
-  );
+  const { promise, resolve } = Promise.withResolvers<SubagentDelegationResponse>();
+
+  const unsubscribe = piEventsBus.on(SUBAGENT_DELEGATION_RESPONSE_EVENT, (payload) => {
+    if (!matchesDelegationRequest({ request, payload })) {
+      return;
+    }
+
+    // JUSTIFICATION: matchesDelegationRequest accepts only the response for this pi-subagents request.
+    resolve(payload as SubagentDelegationResponse);
+  });
 
   try {
     try {
@@ -97,9 +92,7 @@ export const waitForDelegationResponse = async ({
   }
 };
 
-export function assertDelegationResponse(
-  response: SubagentDelegationResponse,
-): void {
+export function assertDelegationResponse(response: SubagentDelegationResponse): void {
   if (response.status === DELEGATION_STATUSES.COMPLETED) {
     return;
   }
@@ -121,7 +114,5 @@ export function assertDelegationResponse(
     throw new Error(`Delegation error: ${error}`);
   }
 
-  throw new Error(
-    `Protocol error: unsupported final response status "${response.status}".`,
-  );
+  throw new Error(`Protocol error: unsupported final response status "${response.status}".`);
 }