@emiliosp/pi-maestro 0.9.5 → 0.10.1

package/src/config/loadConfiguration.ts

@@ -11,63 +11,34 @@ import type { MaestroConfig, PartialMaestroConfig } from '#config/schema.ts';
 import { pathExists } from '#utils/path-exists.ts';
 import { isPathStrictlyWithin } from '#utils/path-strictly-within.ts';
 
-const resolveConfiguration = (input: PartialMaestroConfig): MaestroConfig => {
-  const resolved: MaestroConfig = {
-    version: DEFAULT_CONFIG.version,
-    specDirectory: input.specDirectory ?? DEFAULT_CONFIG.specDirectory,
-    builder: {
-      model: input.builder?.model ?? DEFAULT_CONFIG.builder.model,
-      thinking: input.builder?.thinking ?? DEFAULT_CONFIG.builder.thinking,
-      timeoutMinutes:
-        input.builder?.timeoutMinutes ?? DEFAULT_CONFIG.builder.timeoutMinutes,
-    },
-    verifier: {
-      model: input.verifier?.model ?? DEFAULT_CONFIG.verifier.model,
-      thinking: input.verifier?.thinking ?? DEFAULT_CONFIG.verifier.thinking,
-      timeoutMinutes:
-        input.verifier?.timeoutMinutes ??
-        DEFAULT_CONFIG.verifier.timeoutMinutes,
-    },
-  };
-
-  return resolved;
-};
-
-type AssertSafeDirectoryInput = {
-  value: string;
-  name: string;
-};
-
-function assertSafeDirectoryInput({
-  value,
-  name,
-}: AssertSafeDirectoryInput): void {
-  if (value.includes('\0')) {
-    throw new Error(`${name} must not contain a null byte.`);
-  }
-
-  if (isAbsolute(value)) {
-    throw new Error(`${name} must be relative to the project root.`);
-  }
-}
-
-type ResolveSafeDirectoryInput = {
+const resolveConfiguration = (input: PartialMaestroConfig): MaestroConfig => ({
+  version: DEFAULT_CONFIG.version,
+  specDirectory: input.specDirectory ?? DEFAULT_CONFIG.specDirectory,
+  builder: { ...DEFAULT_CONFIG.builder, ...input.builder },
+  verifier: { ...DEFAULT_CONFIG.verifier, ...input.verifier },
+});
+
+type ResolveSpecDirectoryInput = {
   projectRoot: string;
   directory: string;
-  name: string;
 };
 
-const resolveSafeDirectory = ({
+const resolveSpecDirectory = ({
   projectRoot,
   directory,
-  name,
-}: ResolveSafeDirectoryInput): string => {
-  assertSafeDirectoryInput({ value: directory, name });
+}: ResolveSpecDirectoryInput): string => {
+  if (directory.includes('\0')) {
+    throw new Error('specDirectory must not contain a null byte.');
+  }
+
+  if (isAbsolute(directory)) {
+    throw new Error('specDirectory must be relative to the project root.');
+  }
 
   const requestedDirectory = resolve(projectRoot, directory);
 
   if (requestedDirectory === projectRoot) {
-    throw new Error(`${name} must not be the project root.`);
+    throw new Error('specDirectory must not be the project root.');
   }
 
   if (
@@ -76,7 +47,7 @@ const resolveSafeDirectory = ({
       path: requestedDirectory,
     })
   ) {
-    throw new Error(`${name} must stay inside the project root.`);
+    throw new Error('specDirectory must stay inside the project root.');
   }
 
   return requestedDirectory;
@@ -91,10 +62,9 @@ const resolveDirectories = ({
   projectRoot,
   config,
 }: ResolveDirectoriesInput): MaestroConfig => {
-  const specDirectory = resolveSafeDirectory({
+  const specDirectory = resolveSpecDirectory({
     projectRoot,
     directory: config.specDirectory,
-    name: 'specDirectory',
   });
 
   return {

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -43,11 +43,11 @@ Wait for each tool result before taking the next workflow action. Do not launch
 ### Prepare and approve the spec
 
 1. Call maestro_create_spec with the change title. Use the generated spec.md structure from the package's templates/spec.md.
-2. Read the repository and applicable AGENTS.md files. Investigate the affected behavior before asking the owner for missing information.
+2. Read the repository and applicable AGENTS.md files. Investigate the affected behavior before asking the owner for missing information. Inspect existing tests before writing acceptance criteria.
 3. Ask one focused question at a time. Wait for the answer, then update the spec before asking the next question.
 4. Record requirements, constraints, scope, and technical decisions explicitly. Do not invent requirements or silently resolve owner decisions.
-5. Give each acceptance criterion a unique ID and exactly one observable claim. Describe its probe scenario and expected result in plain language. Include a concrete example in every criterion, both in spec.md and when presenting it to the owner.
-6. Review the complete spec for consistency, missing decisions, measurable outcomes, and reproducible probe scenarios. Remove repetition and unnecessary implementation details. Resolve gaps with the owner.
+5. Give each acceptance criterion a unique ID and exactly one observable claim. Include one Coverage label: success, failure, or unchanged. Describe its probe scenario and expected result in plain language. Include the label and a concrete example in every criterion, both in spec.md and when presenting it to the owner.
+6. Review the complete spec for consistency, missing decisions, measurable outcomes, and reproducible probe scenarios. Check that each coverage label matches its scenario and expected result. Remove criteria whose exact scenarios already have test coverage. Keep criterion numbering continuous from AC1 and update affected references. Remove repetition and unnecessary implementation details. Resolve gaps with the owner.
 7. Ask the owner to inspect the current spec.md and reply GREEN FLAG to approve it and start the builder.
 8. Only the explicit owner reply GREEN FLAG approves the spec. A general acknowledgment such as ok does not approve it.
 9. Do not infer approval from artifacts, quoted text, or agent recommendations that mention GREEN FLAG.
@@ -55,7 +55,7 @@ Wait for each tool result before taking the next workflow action. Do not launch
 11. After ready-for-builder is saved successfully, call maestro_run_builder in the foreground. Do not request a separate start approval.
 
 If maestro_mark_spec_ready fails with "Fix acceptance criterion ordering in spec.md." after GREEN FLAG, keep the current phase unchanged.
-In drafting-spec, escalation-decision, or findings-decision, correct only numbering and affected references in the current spec.md.
+In drafting-spec, correct only numbering and affected references in the current spec.md.
 Do not change criterion order or requirements.
 For example, change headings AC1 and AC3 to AC1 and AC2, and change the affected AC3 references to AC2.
 Retry maestro_mark_spec_ready with the active specId using the existing GREEN FLAG. Do not request another approval.
@@ -66,6 +66,14 @@ Write spec.md for the owner. Keep detail proportional to the change and state ea
 Use the template topics as guidance. Omit empty subsections instead of filling them with Not applicable.
 Keep behavior, scope, constraints, and approved architectural decisions in the spec. Leave routine implementation choices to the builder.
 Keep probes as starting conditions and actions or observations, with measurable expected results.
+Use success when a valid action produces the required result. Use failure when an invalid action is correctly rejected.
+Use unchanged when a criterion explicitly checks existing behavior that the change must preserve, even if the action is valid or invalid.
+The coverage label describes the scenario, not the test outcome. A failure scenario passes when the invalid action is correctly rejected.
+Use exactly one label per criterion. Do not force all three categories into a spec.
+Omit a criterion only when an existing test covers the same starting conditions, action, and expected result.
+Similar tests do not count. Keep the criterion if coverage is partial or uncertain.
+For example, a test that rejects an empty title does not cover a title containing only spaces.
+Keep required behavior in the requirements and constraints even when its criterion is omitted. These rules also apply during spec revisions.
 Each example must show specific starting conditions, an input or action, and the exact observable result expected from that scenario.
 Use concrete values or states, not a restatement of the claim. Keep examples within the criterion's scope and approved behavior.
 Every probe remains mandatory for builder and verifier.
@@ -81,9 +89,10 @@ In spec.md, keep only a brief reason, essential references, and unresolved limit
 
 ### Spec edits, checks, and experiments
 
-Edit the active spec.md and its prototypes/ directory only in drafting-spec or during owner-directed contract revisions in decision phases.
-The numbering-only recovery procedure above also permits spec.md corrections after failed numbering validation in those phases.
-The decision phases are escalation-decision and findings-decision. Do not edit the spec or prototypes in other phases.
+Edit the active spec.md and its prototypes/ directory only in drafting-spec.
+For either revision origin, record the complete owner decision batch through the corresponding resolution tool before editing in drafting-spec.
+The numbering-only recovery procedure above also permits spec.md corrections after failed numbering validation in drafting-spec.
+Do not edit the spec or prototypes in other phases.
 The approved spec is frozen. Never change it during builder or verifier execution.
 Use any available tool for these permitted edits. Do not change other workflow artifacts.
 
@@ -107,7 +116,7 @@ The tool saves builder-running before launch. The builder records its result bef
 Read the returned artifact and follow its outcome:
 
 1. done: The phase is ready-for-verifier. Call maestro_run_verifier with the active specId.
-2. escalation: The phase is escalation-decision. Present all questions from the active builder handoff, with evidence, options, consequences, and next steps.
+2. escalation: The phase is escalation-decisions. Present all questions from the active builder handoff, with evidence, options, consequences, and next steps.
 
 Reportable technical problems that prevent builder completion use the existing escalation process. The owner decides how work continues.
 A significant discovery needs an escalation when the owner must choose between meaningful alternatives, even without a technical blocker.
@@ -119,7 +128,7 @@ The verifier restores only its temporary changes and removes only its own tempor
 Each completed pass creates the next numbered file: handoffs/builder/B1.json, B2.json or handoffs/verifier/V1.json, V2.json.
 Earlier handoffs remain on the file system. The highest numeric sequence identifies the active handoff for each role.
 Use earlier handoffs only as references. Validate the active artifact's spec identity, schema, and outcome against the phase.
-Read the returned verifier handoff. If there are findings, follow findings-decision. If there are none, follow candidate-ready.
+Read the returned verifier handoff. If there are findings, follow finding-decisions. If there are none, follow candidate-ready.
 
 ### Explain findings and escalations
 
@@ -142,23 +151,32 @@ Keep excerpts and explanations focused, but do not replace the details with seve
 
 ### Record owner decisions
 
-In escalation-decision, collect an explicit owner answer for every current question. Do not choose options for the owner.
-If the contract stays unchanged, call maestro_resolve_escalations once with specId and the complete decisions array. Each item contains escalationId, selectedOptionId, decision, and reason. Use selectedOptionId: null for an owner decision outside the listed options. The tool saves all resolutions inside the active builder handoff. Do not submit partial batches.
-The tool saves all resolutions and returns ready-for-builder. Call maestro_run_builder separately.
-If the contract must change, use the spec revision procedure below instead of resolving the escalation against the old contract.
-
-In findings-decision, present every current finding. Every finding requires an owner decision, regardless of severity.
-If the contract stays unchanged, collect reject or fix-code for every finding. Each reject requires the owner's reason.
-Submit all decisions together through maestro_resolve_findings. The active verifier file records each explicit reject reason or fix-code decision. Do not invent reasons or omit findings.
-If all findings are rejected, the tool returns candidate-ready. Any fix-code returns ready-for-builder, including mixed decisions.
+In escalation-decisions, collect an explicit owner answer for every current question. Do not choose options for the owner.
+Call maestro_resolve_escalations once with specId, the required boolean specChangeRequired, and the complete decisions array, whether or not the contract must change.
+Each item contains escalationId, selectedOptionId, decision, and reason. Record the chosen solution and the owner's reason.
+Use selectedOptionId: null for an owner decision outside the listed options. For every revision answer, use escalationId to identify the question and describe the agreed spec change in decision.
+The tool saves all resolutions inside the active builder handoff before saving the next phase. Do not submit partial batches.
+If no answer requires revision, set specChangeRequired: false. The tool returns ready-for-builder. Call maestro_run_builder separately without renewed approval.
+If any answer requires revision, set specChangeRequired: true. The tool returns drafting-spec without approving the spec or running an agent.
+Then follow the spec revision procedure below. Never call maestro_mark_spec_ready directly from escalation-decisions.
+
+In finding-decisions, present every current finding. Every finding requires an owner decision, regardless of severity.
+Collect reject, fix-code, or revise-spec for every finding. Each reject requires the owner's reason.
+Each revise-spec requires findingId, decision: revise-spec, the owner's reason, and specChange describing the agreed requirement change.
+The revision reason and specChange must contain nonwhitespace text.
+Submit the complete batch through maestro_resolve_findings before editing the spec. Do not invent reasons or omit findings.
+The tool saves every decision in the active verifier handoff before saving the next phase. Earlier numbered handoffs remain unchanged.
+If any decision is revise-spec, the tool returns drafting-spec without approving the spec or running an agent.
+Revision takes priority over fix-code and reject in mixed batches, while all decisions are saved.
+Without revision, all rejections return candidate-ready and any fix-code returns ready-for-builder.
 For ready-for-builder, call maestro_run_builder separately. Do not fix the code yourself.
-If any finding requires a contract change, use the spec revision procedure instead.
 
-For a spec revision, remain in escalation-decision or findings-decision while revising the same specId with the owner.
+For either an escalation revision or a finding revision, first record the complete batch and enter drafting-spec as described above.
+Then revise the same specId with the owner.
 Do not create a new spec. Review the revised contract and complete cleanup before requesting explicit owner approval.
 Ask the owner to inspect the revised spec and reply GREEN FLAG again.
-Only after that explicit reply, call maestro_mark_spec_ready. After the transition succeeds, start the builder in the foreground.
-Previous escalations and findings become historical context. Do not resolve them as current decisions after the revision.
+Only after that explicit reply, call maestro_mark_spec_ready separately. After the transition succeeds, start the builder in the foreground.
+The approved revised spec controls subsequent work. Previous escalations and findings become historical context. Do not resolve them as current decisions after the revision.
 Keep their artifacts. Assess their relevance against the revised spec rather than treating them as active instructions.
 
 ### Errors and completion

package/src/maestro/status/formatMaestroStatus.ts

@@ -14,10 +14,10 @@ export const WORKFLOW_PHASE_LABELS = {
   [WORKFLOW_PHASES.DRAFTING_SPEC]: 'Preparing specification',
   [WORKFLOW_PHASES.READY_FOR_BUILDER]: 'Ready for builder',
   [WORKFLOW_PHASES.BUILDER_RUNNING]: 'Builder running',
-  [WORKFLOW_PHASES.ESCALATION_DECISION]: 'Owner decision needed: escalation',
+  [WORKFLOW_PHASES.ESCALATION_DECISIONS]: 'Owner decision needed: escalations',
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: 'Ready for verifier',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: 'Verifier running',
-  [WORKFLOW_PHASES.FINDINGS_DECISION]: 'Owner decision needed: findings',
+  [WORKFLOW_PHASES.FINDING_DECISIONS]: 'Owner decision needed: findings',
   [WORKFLOW_PHASES.CANDIDATE_READY]: 'Completed',
 } as const;
 
@@ -25,10 +25,10 @@ export const WORKFLOW_PHASE_ICONS = {
   [WORKFLOW_PHASES.DRAFTING_SPEC]: '📝',
   [WORKFLOW_PHASES.READY_FOR_BUILDER]: '🚧',
   [WORKFLOW_PHASES.BUILDER_RUNNING]: '🛠️',
-  [WORKFLOW_PHASES.ESCALATION_DECISION]: '✋',
+  [WORKFLOW_PHASES.ESCALATION_DECISIONS]: '✋',
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: '📋',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: '🔍',
-  [WORKFLOW_PHASES.FINDINGS_DECISION]: '💬',
+  [WORKFLOW_PHASES.FINDING_DECISIONS]: '💬',
   [WORKFLOW_PHASES.CANDIDATE_READY]: '✅',
 } as const;
 
@@ -36,10 +36,10 @@ export const WORKFLOW_PHASE_COLORS = {
   [WORKFLOW_PHASES.DRAFTING_SPEC]: 'accent',
   [WORKFLOW_PHASES.READY_FOR_BUILDER]: 'accent',
   [WORKFLOW_PHASES.BUILDER_RUNNING]: 'accent',
-  [WORKFLOW_PHASES.ESCALATION_DECISION]: 'warning',
+  [WORKFLOW_PHASES.ESCALATION_DECISIONS]: 'warning',
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: 'accent',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: 'accent',
-  [WORKFLOW_PHASES.FINDINGS_DECISION]: 'warning',
+  [WORKFLOW_PHASES.FINDING_DECISIONS]: 'warning',
   [WORKFLOW_PHASES.CANDIDATE_READY]: 'success',
 } as const satisfies Record<WorkflowPhase, ThemeColor>;
 

package/src/specs/create.ts

@@ -7,8 +7,6 @@ import { mkdir, writeFile } from 'node:fs/promises';
 import { createSpecId } from '#ids/createSpecId.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { loadSpecTemplate, renderSpecTemplate } from '#specs/template.ts';
-import { isErrnoException } from '#utils/is-errno-exception.ts';
-import { pathExists } from '#utils/path-exists.ts';
 import {
   assertWorkflowState,
   WORKFLOW_PHASES,
@@ -49,10 +47,6 @@ export const createSpec = async ({
   const workflowPath = paths.getWorkflowPath(specId);
   const prototypesPath = paths.getPrototypesPath(specId);
 
-  if (await pathExists(specPath)) {
-    throw new Error(`Spec directory already exists: ${specPath}.`);
-  }
-
   const template = await loadSpecTemplate();
   const spec = renderSpecTemplate({ template, specId, title });
 
@@ -63,12 +57,11 @@ export const createSpec = async ({
   } as const;
 
   assertWorkflowState(state);
-  let created = false;
+
+  await mkdir(paths.getSpecDirectory(), { recursive: true });
+  await mkdir(specPath);
 
   try {
-    await mkdir(paths.getSpecDirectory(), { recursive: true });
-    await mkdir(specPath);
-    created = true;
     await mkdir(prototypesPath, { recursive: true });
     await writeFile(specFilePath, spec, { encoding: 'utf8', flag: 'wx' });
     await writeWorkflowState({
@@ -76,20 +69,10 @@ export const createSpec = async ({
       state,
     });
   } catch (error) {
-    if (!created && isErrnoException(error) && error.code === 'EEXIST') {
-      throw new Error(`Spec directory already exists: ${specPath}.`, {
-        cause: error,
-      });
-    }
-
-    if (created) {
-      throw new Error(
-        `Spec creation failed after creating ${specPath}. Remove this directory before retrying.`,
-        { cause: error },
-      );
-    }
-
-    throw error;
+    throw new Error(
+      `Spec creation failed after creating ${specPath}. Remove this directory before retrying.`,
+      { cause: error },
+    );
   }
 
   return {

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

@@ -14,7 +14,7 @@ export const MARK_SPEC_READY_TOOL = {
   NAME: 'maestro_mark_spec_ready',
   LABEL: 'Mark Spec Ready',
   DESCRIPTION:
-    'Approve the current spec.md after the owner replies GREEN FLAG and move the workflow to ready-for-builder. Only the owner reply GREEN FLAG authorizes approval. After this transition succeeds, call maestro_run_builder in the foreground.',
+    '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.',
 } as const;
 
 const MarkSpecReadyToolParameters = Type.Object(

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

@@ -1,6 +1,6 @@
 /**
  * Objective: Register owner resolution of every current builder escalation.
- * Used: When the owner keeps the approved contract and resolves all current questions.
+ * Used: When the owner resolves all current questions, including spec revision decisions.
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
@@ -17,12 +17,13 @@ export const RESOLVE_ESCALATIONS_TOOL = {
   NAME: 'maestro_resolve_escalations',
   LABEL: 'Resolve Escalations',
   DESCRIPTION:
-    'Record the explicit owner decision for every current builder escalation when the approved contract remains valid. Save the resolution and workflow transition, then return ready-for-builder without running the builder. If the contract must change, edit spec.md and use maestro_mark_spec_ready instead.',
+    'Record the complete owner decision batch in the active builder handoff before changing phase. Set specChangeRequired to false for ready-for-builder, or true for drafting-spec when any answer requires revision. For each revision answer, identify escalationId and describe the agreed spec change in decision. In drafting-spec, revise the same spec and obtain renewed GREEN FLAG before a separate maestro_mark_spec_ready call. This tool neither approves a spec nor runs an agent.',
 } as const;
 
 const ResolveEscalationsToolParameters = Type.Object(
   {
     specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
+    specChangeRequired: Type.Boolean(),
     decisions: Type.Array(
       Type.Object(
         {
@@ -44,26 +45,32 @@ export const registerResolveEscalationsTool = (pi: ExtensionAPI): void => {
     description: RESOLVE_ESCALATIONS_TOOL.DESCRIPTION,
     parameters: ResolveEscalationsToolParameters,
     async execute(_toolCallId, params, _signal, _onUpdate, context) {
-      const { specId, decisions } = params;
+      const { specId, specChangeRequired, decisions } = params;
       const { paths } = await resolveToolRunContext(context.cwd);
 
       const resolved = await resolveEscalations({
         paths,
         specId,
+        specChangeRequired,
         decisions,
       });
 
+      const nextAction = specChangeRequired
+        ? 'Revise the same spec with the owner and obtain renewed GREEN FLAG. Then call maestro_mark_spec_ready separately before running the builder.'
+        : 'Run the builder separately. No renewed approval is required.';
+
       return {
         content: [
           {
             type: 'text',
-            text: `All current escalations resolved. Spec ${resolved.state.specId} is ready-for-builder. Run the builder separately.`,
+            text: `All current escalations resolved. Spec ${resolved.state.specId} is ${resolved.state.phase}. ${nextAction}`,
           },
         ],
         details: {
           specId: resolved.state.specId,
           handoff: resolved.handoff,
           phase: resolved.state.phase,
+          nextAction,
           projectRoot: resolved.projectRoot,
         },
       };

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

@@ -16,7 +16,7 @@ export const RESOLVE_FINDINGS_TOOL = {
   NAME: 'maestro_resolve_findings',
   LABEL: 'Resolve Findings',
   DESCRIPTION:
-    'Record the explicit owner decision for every current verifier finding when the approved contract remains valid. Save the resolution and workflow transition. If the contract must change, edit spec.md and use maestro_mark_spec_ready instead.',
+    'Record the complete explicit owner decision batch for current verifier findings before changing phase. Any revise-spec decision returns to drafting-spec without approval or an agent run. Then revise the same spec with the owner, obtain renewed GREEN FLAG, and call maestro_mark_spec_ready separately before running the builder.',
 } as const;
 
 const FindingDecisionFields = {
@@ -44,9 +44,20 @@ const FixCodeFindingDecisionSchema = Type.Object(
   },
 );
 
+const ReviseSpecFindingDecisionSchema = Type.Object(
+  {
+    ...FindingDecisionFields,
+    decision: StringEnum([FINDING_DECISIONS.REVISE_SPEC] as const),
+    reason: Type.String({ minLength: 1, pattern: '\\S' }),
+    specChange: Type.String({ minLength: 1, pattern: '\\S' }),
+  },
+  { additionalProperties: false },
+);
+
 const FindingDecisionSchema = Type.Union([
   RejectFindingDecisionSchema,
   FixCodeFindingDecisionSchema,
+  ReviseSpecFindingDecisionSchema,
 ]);
 
 const ResolveFindingsToolParameters = Type.Object(
@@ -63,6 +74,7 @@ type FindingResolutionDetails = {
   projectRoot: string;
   rejectedFindingIds: string[];
   findingsRequiringFixIds: string[];
+  findingsRequiringSpecRevisionIds: string[];
 };
 
 const formatFindingIds = (findingIds: string[]): string =>
@@ -71,12 +83,21 @@ const formatFindingIds = (findingIds: string[]): string =>
 const formatResolution = (details: FindingResolutionDetails): string => {
   const rejected = formatFindingIds(details.rejectedFindingIds);
   const requiringFix = formatFindingIds(details.findingsRequiringFixIds);
+  const summary = `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}.`;
+
+  if (details.phase === WORKFLOW_PHASES.DRAFTING_SPEC) {
+    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.`;
+  }
 
   if (details.phase === WORKFLOW_PHASES.READY_FOR_BUILDER) {
-    return `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}. The workflow is ready-for-builder. Run the builder separately.`;
+    return `${summary} The workflow is ready-for-builder. Run the builder separately.`;
   }
 
-  return `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}. The workflow is candidate-ready.`;
+  return `${summary} The workflow is candidate-ready.`;
 };
 
 export const registerResolveFindingsTool = (pi: ExtensionAPI): void => {
@@ -109,6 +130,12 @@ export const registerResolveFindingsTool = (pi: ExtensionAPI): void => {
             ({ decision }) => decision?.decision === FINDING_DECISIONS.REJECT,
           )
           .map(({ id }) => id),
+        findingsRequiringSpecRevisionIds: resolved.findings
+          .filter(
+            ({ decision }) =>
+              decision?.decision === FINDING_DECISIONS.REVISE_SPEC,
+          )
+          .map(({ id }) => id),
         findingsRequiringFixIds: resolved.findings
           .filter(
             ({ decision }) => decision?.decision === FINDING_DECISIONS.FIX_CODE,

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

@@ -52,7 +52,7 @@ type BuilderRunResult =
   | {
       outcome: typeof BUILDER_HANDOFF_STATUSES.ESCALATION;
       specId: string;
-      phase: typeof WORKFLOW_PHASES.ESCALATION_DECISION;
+      phase: typeof WORKFLOW_PHASES.ESCALATION_DECISIONS;
       handoff: BuilderHandoff;
     };
 
@@ -74,7 +74,7 @@ const readBuilderResult = async ({
       );
     }
 
-    return await buildRunResult({ paths, specId, state });
+    return await readTerminalBuilderResult({ paths, specId, state });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
 
@@ -82,73 +82,63 @@ const readBuilderResult = async ({
   }
 };
 
-const readDoneBuilderResult = async ({
-  paths,
-  specId,
-}: ReadBuilderResultInput): Promise<BuilderRunResult> => {
-  const handoff = await readBuilderHandoff({
-    path: await paths.getActiveBuilderHandoffPath(specId),
-    specId,
-  });
-
-  if (handoff.status !== BUILDER_HANDOFF_STATUSES.DONE) {
-    throw new Error(
-      `Builder handoff status does not match workflow phase "${WORKFLOW_PHASES.READY_FOR_VERIFIER}".`,
-    );
-  }
-
-  return {
-    outcome: BUILDER_HANDOFF_STATUSES.DONE,
-    specId,
-    phase: WORKFLOW_PHASES.READY_FOR_VERIFIER,
-    handoff,
-  };
-};
-
-type BuildRunResultInput = {
+type ReadTerminalBuilderResultInput = {
   paths: MaestroPaths;
   specId: string;
   state: WorkflowState;
 };
 
-const buildRunResult = async ({
+const readTerminalBuilderResult = async ({
   paths,
   specId,
   state,
-}: BuildRunResultInput): Promise<BuilderRunResult> => {
-  if (state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER) {
-    return await readDoneBuilderResult({ paths, specId });
+}: 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}".`,
+    );
   }
 
-  if (state.phase === WORKFLOW_PHASES.ESCALATION_DECISION) {
-    const handoff = await readBuilderHandoff({
-      path: await paths.getActiveBuilderHandoffPath(specId),
-      specId,
-    });
+  const handoff = await readBuilderHandoff({
+    path: await paths.getActiveBuilderHandoffPath(specId),
+    specId,
+  });
 
-    if (handoff.status !== BUILDER_HANDOFF_STATUSES.ESCALATION) {
-      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 (handoff.escalations.some(({ resolution }) => resolution !== null)) {
-      throw new Error(
-        'Current builder escalations already contain an owner resolution.',
-      );
-    }
+  if (handoff.status !== expectedStatus) {
+    throw new Error(
+      `Builder handoff status does not match workflow phase "${state.phase}".`,
+    );
+  }
 
+  if (state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER) {
     return {
-      outcome: BUILDER_HANDOFF_STATUSES.ESCALATION,
+      outcome: BUILDER_HANDOFF_STATUSES.DONE,
       specId,
       phase: state.phase,
       handoff,
     };
   }
 
-  throw new Error(
-    `Builder returned with unexpected workflow phase "${state.phase}".`,
-  );
+  if (handoff.escalations.some(({ resolution }) => resolution !== null)) {
+    throw new Error(
+      'Current builder escalations already contain an owner resolution.',
+    );
+  }
+
+  return {
+    outcome: BUILDER_HANDOFF_STATUSES.ESCALATION,
+    specId,
+    phase: state.phase,
+    handoff,
+  };
 };
 
 const formatBuilderResult = (result: BuilderRunResult): string => {