@emiliosp/pi-maestro 0.9.4 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 This file summarizes meaningful changes to the codebase, including behavior, data formats, architecture, and development tools. Git tags identify version boundaries; GitHub Releases are not required. Version-only changes and routine maintenance are omitted.
 
+## Unreleased
+
+1. Add `revise-spec` decisions for `verifier` `findings`, with the owner's reason and agreed requirement change saved in the active `handoff`.
+2. Route any revision batch to `drafting-spec` before revision, with priority over code fixes and rejections.
+3. Require separate renewed approval from `drafting-spec` and reject direct approval from `finding-decisions`.
+
+4. Require the boolean `specChangeRequired` in `maestro_resolve_escalations`. Save every current answer in the active `builder` `handoff` before changing phase.
+5. Route revision decisions to `drafting-spec`. Revise the same `spec` and obtain renewed `GREEN FLAG` before a separate approval and `builder` `run`.
+6. Reject direct `spec` approval from `escalation-decisions`. Decisions without revision still return to `ready-for-builder` without renewed approval.
+7. Breaking: rename the saved decision phases to `escalation-decisions` and `finding-decisions`. Existing workflows using the previous names require manual `owner` handling.
+
+## 0.9.5
+
+1. Added a shared check that requires every approved `spec` criterion ID in `builder` and `verifier` `handoffs`. See [PR #37](https://github.com/emilioSp/pi-maestro/pull/37).
+2. Missing IDs reject submission before saving a report or changing phase. Extra report IDs remain allowed, and existing report validation is unchanged.
+3. Reused the raw heading rule `^### AC(\d+):`, including leading zeros and matching lines inside code blocks. No matching headings impose no new restriction.
+4. Added unit tests for extraction and one missing-ID integration test per role.
+
+## 0.9.4
+
+1. Added numbering validation to `spec` approval. Matched `acceptance criterion` headings must start at `AC1` and continue without gaps. See [PR #36](https://github.com/emilioSp/pi-maestro/pull/36).
+2. Invalid numbering rejects approval before saving the workflow and leaves all saved files unchanged. No matching headings still permits approval.
+3. Added `Maestro` guidance to correct only numbering and affected references, then retry with the existing `GREEN FLAG`. No additional `owner` approval is required before starting the `builder`.
+
 ## 0.9.3
 
 1. Added a parent `pi-subagents` availability check during activation. A matching successful version 1 `ping` reply is required within 2000 ms. See [PR #35](https://github.com/emilioSp/pi-maestro/pull/35).

package/README.md

@@ -79,7 +79,11 @@ The `owner` must not edit product files while the workflow runs.
 `Maestro` can perform temporary experiments with `owner` agreement during `spec` preparation and permitted revisions. See [Workflow](docs/workflow.md#spec-approval).
 
 An `escalation` asks the `owner` to decide an implementation question, and a `finding` records a technical issue reported by the `verifier`. The `owner` discusses both with `Maestro`, never directly with the `builder` or `verifier`.
-If a `spec` change is needed during an `escalation` or `finding` decision, the `owner` reviews the revised `spec` and replies `GREEN FLAG` again. `Maestro` then starts another `builder` `run`.
+`Maestro` records all current `escalation` answers or `finding` decisions in the active `handoff` before changing phase.
+
+If any decision requires a `spec` change, the workflow returns to `drafting-spec` before the `owner` and `Maestro` revise the same `spec`.
+The `owner` reviews the revised `spec` and replies `GREEN FLAG` again.
+`Maestro` records renewed approval separately before another `builder` `run`.
 
 The workflow ends at `candidate-ready`. Rejected `findings` retain their reasons. Later changes are outside the completed verification. The `owner` controls any later Git use, pull request, and merge.
 

package/ROADMAP.md

@@ -60,7 +60,7 @@ Renamed `test/` to `tests/` at the owner's request. Updated imports, fixture pat
 
 #### Evidence
 
-[Test support](tests/support/), [fixtures](tests/fixtures/), [lint configuration](biome.json), and [project instructions](AGENTS.md#tests).
+[Test support](tests/support/), [fixtures](tests/fixtures/), and [lint configuration](biome.json).
 
 ### R-16: Verify code quality against AGENTS.md instructions
 
@@ -86,23 +86,74 @@ A later integration test requested by the `owner` directly checks the environmen
 
 [Specification](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/spec.md), [verifier report](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/handoffs/verifier/V1.json), and [merged PR #35](https://github.com/emilioSp/pi-maestro/pull/35).
 
-## Now
-
 ### R-05: Keep acceptance criterion numbering continuous
 
+Implemented in `0.9.4`. `Spec` approval rejects numbered `acceptance criterion` headings that do not start at `AC1` and continue without gaps. Rejection leaves saved files unchanged.
+
+`Maestro` corrects numbering and affected references without changing criterion order or requirements, then retries with the existing `GREEN FLAG`. No additional `owner` approval is required.
+
+All 3 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
+
+#### Evidence
+
+[Specification](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/spec.md), [verifier report](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/handoffs/verifier/V1.json), and [merged PR #36](https://github.com/emilioSp/pi-maestro/pull/36).
+
+### R-10: Match handoff criteria to the approved spec
+
+Implemented in `0.9.5` with the narrower scope approved by the `owner`. Both `handoff` submissions require every `acceptance criterion` ID from the approved `spec` before saving a report or changing phase. Extra report IDs remain allowed. Existing report validation is unchanged, and no new check rejects duplicate `spec` IDs.
+
+Both `acceptance criteria` passed independent verification with no `findings`. The saved workflow reached `candidate-ready`.
+
+Later changes requested by the `owner` extracted the shared check and replaced repeated integration scenarios with unit tests. One missing-ID integration test remains per role. These changes are outside the completed independent verification. The final `npm run check` passed all 227 tests and coverage thresholds.
+
+#### Evidence
+
+[Specification](.specs/20261013-211629-match-handoff-criteria-to-the-approved-spec/spec.md), [verifier report](.specs/20261013-211629-match-handoff-criteria-to-the-approved-spec/handoffs/verifier/V1.json), and [merged PR #37](https://github.com/emilioSp/pi-maestro/pull/37).
+
+### R-17: Record escalation resolutions when the spec changes
+
 #### Objective
 
-When criteria are removed during `spec` preparation or revision, renumber the remaining criteria without gaps. Numbering starts at `AC1` and continues through the final criterion.
+Save every current `escalation` answer in the original `builder` `handoff`, whether the `spec` stays unchanged or requires revision.
+Each `resolution` records the owner's chosen solution and reason. A decision requiring revision also identifies the `escalation` and describes the agreed `spec` change.
+
+#### Agreed flow
+
+`Maestro` records the complete decision batch through `maestro_resolve_escalations` before changing phase.
 
-#### Current state
+| Decision | Next phase and action |
+|---|---|
+| No `spec` change | `escalation-decisions` → `ready-for-builder`. The `builder` continues under the approved `spec`, without renewed approval. |
+| `Spec` change required | `escalation-decisions` → `drafting-spec`. The `owner` and `Maestro` revise and review the same `spec`. |
+| Revised `spec` receives renewed `GREEN FLAG` | `drafting-spec` → `ready-for-builder` through separate `maestro_mark_spec_ready` approval. |
 
-Implemented approval-time numbering validation and `Maestro` guidance for numbering-only recovery using the existing GREEN FLAG. Rejected numbering leaves saved files unchanged. Independent verification is pending.
+Direct `spec` approval from `escalation-decisions` is rejected. Recording answers does not move to `ready-for-verifier`; that phase requires a completed `builder` `pass`.
 
-[Specification](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/spec.md).
+#### Implementation boundaries
+
+Reuse the existing resolution operation and `handoff` fields. Do not add a parallel decision store, tool, or workflow phase.
+Define both resolution transitions explicitly in `src/workflow/transitions.ts` and apply them through `transitionWorkflow`. Direct phase assignment elsewhere is banned.
+Preserve initial `spec` approval, `verifier` `finding` decisions, existing batch validation, and historical `handoffs`.
 
 #### Completed when
 
-The `spec` and its current references use consistent numbering.
+Saved `resolutions`, workflow phases, tool results, agent instructions, and human documentation follow the agreed flow.
+Verification checks both observable behavior and use of the central transition definitions for each resolution branch. Passing behavior tests alone is not enough.
+The new `spec` includes coverage labels and omits `acceptance criteria` already covered by tests of the same scenario.
+
+### R-20: Route finding-driven spec revisions through drafting-spec
+
+Implemented the approved revision route. `Maestro` records every current `finding` decision before returning to `drafting-spec` when revision is required.
+The `owner` reviews the same revised `spec` and gives renewed `GREEN FLAG` before separate approval and another `builder` `run`.
+Revision takes priority in mixed batches. Direct approval from `finding-decisions` is rejected.
+
+Later event naming cleanup identifies `builder` and `owner` actions explicitly. Both revision routes use `OWNER_REQUEST_SPEC_REVISION` without changing the phase flow. Batch resolution uses `RESOLVE_ESCALATIONS`, and the status label refers to `escalations` in the plural. The saved decision phases are named `escalation-decisions` and `finding-decisions`.
+
+#### Evidence
+
+[Specification](.specs/20261015-154812-route-finding-driven-spec-revisions-through-drafting-spec/spec.md) and [resolution integration tests](src/tools/main/resolve-findings.integration.test.ts).
+
+## Now
 
 ## Next
 
@@ -152,38 +203,28 @@ Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The re
 
 Not yet defined. The `owner` must define the intended outcome, recovery boundaries, and completion condition before this item can move forward.
 
-### R-10: Match handoff criteria to the approved spec
+### R-18: Label acceptance criterion coverage
 
 #### Objective
 
-Prevent `builder` and `verifier` reports from omitting or adding `acceptance criteria`. Each report must contain exactly the criterion IDs in the approved `spec`, with no duplicates in either place. Existing duplicate checks in reports do not establish this match.
-
-The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
+Label each `acceptance criterion` in a `spec` as success, failure, or keep current behavior unchanged.
+The label makes the purpose of its `probe` clear. Failure means an invalid action is correctly rejected.
 
 #### Completed when
 
-Both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase.
+The `spec` template and `Maestro` guidance require a coverage label for every `acceptance criterion`. 
+Each label matches the scenario and `expected result`. A `spec` does not need all three categories when they do not apply.
 
-### R-11: Reduce temporary verifier changes
+### R-19: Avoid acceptance criteria already covered by tests
 
 #### Objective
 
-Reduce the risk that verification changes the `candidate`. Existing instructions already require exact restoration, cleanup, and reporting of unresolved restoration problems. Refine the remaining guidance rather than duplicate those rules.
-
-Prefer checks that leave existing files unchanged and use separate temporary files when possible. Change an existing file only when a criterion requires it. Retain its exact contents and restore it immediately after each `probe`, including failed `probes`. Prefer check-only commands over commands that apply automatic fixes.
-
-`Maestro` currently has no file-hash restoration check. Adding one requires a separate scope decision.
-
-#### Completed when
-
-`Verifier` instructions cover these limits and require restoration and temporary-file cleanup before `handoff`. If restoration fails, the `verifier` must stop and report affected paths and remaining changes.
-
-### R-13: Show when Maestro is working
-
-#### Objective
+Do not add an `acceptance criterion` when an existing test already covers the same starting conditions, action, and `expected result`.
 
-Show an activity indicator in Pi's status bar while progress does not require an `owner` decision. A spinner is one option, not an agreed implementation.
+Similar tests do not count if they miss the proposed scenario.
 
 #### Completed when
 
-The status clearly distinguishes work in progress from a request for `owner` action.
+`Maestro` guidance requires inspection of existing tests before adding `acceptance criteria`. 
+During `spec` review, `Maestro` removes criteria already covered by tests and keeps numbering continuous. 
+Required behavior remains documented in the `spec`.

package/agents/verifier.md

@@ -115,5 +115,5 @@ Do not delete artifacts, change workflow state, or bypass the tool to force comp
 If restoration or submission cannot be completed safely, report the exact blocker and remaining changes to Maestro and stop.
 
 After a successful handoff, return a concise summary and the saved artifact path to Maestro and stop. Do not run more checks.
-The handoff produces `findings-decision` when findings exist and `candidate-ready` when none exist.
+The handoff produces `finding-decisions` when findings exist and `candidate-ready` when none exist.
 Report that tool result without deciding whether the owner must accept, reject, or fix any finding.

package/docs/glossary.md

@@ -21,6 +21,7 @@
 | `Escalation` | An implementation question or reportable technical problem that the `builder` records in its `handoff` for an `owner` decision. |
 | `GREEN FLAG` | The owner's explicit reply that approves the current `spec` and starts the `builder`. |
 | `fix-code` | An `owner` decision that requests code fixes without changing the approved `spec`. |
+| `revise-spec` | An `owner` decision that records a reason and agreed requirement change, then returns to `drafting-spec` for revision and renewed approval. |
 | `reject` | An `owner` decision that declines a `finding` and records a reason. It does not mean that verification passed. |
 | `candidate-ready` | The completed workflow phase. The `verifier` reported no `findings`, or the `owner` rejected every `finding` with a reason. Final review remains with the `owner`. |
 

package/docs/workflow.md

@@ -61,16 +61,16 @@ flowchart TD
     findings -->|None| candidate
 
     buildOutcome -->|Escalation| ownerEscalation{Owner decides every question}
-    ownerEscalation -->|Spec unchanged| recordEscalation[Maestro records all answers]
-    recordEscalation --> build
-    ownerEscalation -->|Spec changes| reviseSpec[Owner and Maestro revise the spec]
+    ownerEscalation --> recordEscalation[Maestro records all answers]
+    recordEscalation -->|Spec unchanged| build
+    recordEscalation -->|Spec changes| reviseSpec[Owner and Maestro revise the spec]
     reviseSpec --> approval
 
     findings -->|One or more| ownerFindings[Owner decides every finding]
-    ownerFindings -->|Reject all with reasons| candidate
-    ownerFindings -->|Fix code| recordFixes[Maestro records the decisions]
-    recordFixes --> build
-    ownerFindings -->|Revise spec| reviseSpec
+    ownerFindings --> recordFindings[Maestro records all decisions]
+    recordFindings -->|Reject all with reasons| candidate
+    recordFindings -->|Fix code without spec changes| build
+    recordFindings -->|Spec changes| reviseSpec
 
     candidate --> summary
     summary --> review
@@ -86,13 +86,13 @@ The default path is `.specs/<spec-id>/workflow.json`. The `spec` directory is [c
 
 | Phase | Meaning |
 |---|---|
-| `drafting-spec` | The `owner` and `Maestro` are preparing the initial `spec`. |
+| `drafting-spec` | The `owner` and `Maestro` prepare the initial `spec` or revise it after recorded `escalation` answers or `finding` decisions. |
 | `ready-for-builder` | The approved `spec` or recorded `owner` decisions permit a `builder` `run`. |
 | `builder-running` | A `builder` `run` is active. |
-| `escalation-decision` | The `owner` must decide how to handle every `escalation` question. |
+| `escalation-decisions` | The `owner` must decide how to handle every `escalation` question. |
 | `ready-for-verifier` | The `builder` completed the work and the `verifier` can start. |
 | `verifier-running` | A `verifier` `run` is active. |
-| `findings-decision` | The `owner` must decide how to handle every current `finding`. |
+| `finding-decisions` | The `owner` must decide how to handle every current `finding`. |
 | `candidate-ready` | The `verifier` reported no `findings`, or the `owner` rejected every `finding` with a reason. The workflow is complete. |
 
 ## Spec approval
@@ -104,7 +104,7 @@ For the initial `spec`:
 3. `Maestro` asks the `owner` to inspect the current `spec.md` and reply `GREEN FLAG` to approve it and start the `builder`.
 4. After that reply, `Maestro` saves `ready-for-builder` and starts the `builder` in the foreground.
 
-Approval freezes the `spec`. The `spec` and its visual prototypes remain unchanged during `builder` and `verifier` execution. `Spec` revisions are limited to the decision phases described in [Spec revision](#spec-revision).
+Approval freezes the `spec`. The `spec` and its visual prototypes remain unchanged during `builder` and `verifier` execution. See [Spec revision](#spec-revision) for permitted revisions.
 
 ## Acceptance criteria
 
@@ -125,14 +125,17 @@ For instance a technical failure, an undefined behavior, a conflict with the `sp
 
 The `builder` saves all questions from one `pass` in the `escalations` list of its numbered `handoff`. `Maestro` identifies each question with both report and `escalation` IDs, such as `B1/E1`. See [Escalation references](glossary.md#escalation-references) for their scope.
 
-`Maestro` presents each question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decision` while the `owner` decides how to proceed.
+`Maestro` presents each question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decisions` while the `owner` decides how to proceed.
 
-If the `spec` stays unchanged, the `owner` gives `Maestro` an answer and reason for every current question. The `owner` can select a listed option or give a different decision.
+The `owner` gives `Maestro` an answer and reason for every current question, whether or not the `spec` must change.
+The `owner` can select a listed option or give a different decision.
+
+`Maestro` saves all answers in the current `builder` `handoff` before the workflow continues.
 
 | `Owner` choice | Result |
 |---|---|
-| Keep the current `spec` | `Maestro` saves all answers and reasons together in the active `builder` `handoff`, returns to `ready-for-builder`, and starts another `builder` `run`. |
-| Change the `spec` | The `owner` and `Maestro` revise the same `spec` and obtain renewed approval before another `builder` `run`. |
+| Keep the current `spec` | `Maestro` starts another `builder` `run` without renewed approval. |
+| Change the `spec` | The `owner` and `Maestro` revise the same `spec`. The `owner` reviews it and replies `GREEN FLAG` before another `builder` `run`. |
 
 `Owner` decisions update only the questions' `resolution` fields. The handoff's other content and earlier `handoffs` remain unchanged.
 
@@ -147,19 +150,27 @@ Every current `finding` requires an `owner` decision, regardless of severity. `M
 | Decision | Result |
 |---|---|
 | `reject` | Records the owner's reason. If every `finding` is rejected, the workflow reaches `candidate-ready`. |
-| `fix-code` | Keeps the current `spec` and returns to `ready-for-builder` for code fixes. |
+| `fix-code` | Keeps the current `spec` and returns to `ready-for-builder` for code fixes when no decision requires revision. |
+| `revise-spec` | Records the owner's reason and agreed requirement change, then returns to `drafting-spec`. |
 
-Any `fix-code` decision requires another `builder` `run`, including when other `findings` are rejected. After the `builder` completes the fixes, the `verifier` checks the work again.
+`Maestro` saves every current decision together before the phase changes.
+If any `finding` requires revision, revision takes priority over code fixes and rejections. See [Spec revision](#spec-revision).
 
-If the `spec` must change, the `owner` and `Maestro` use [Spec revision](#spec-revision) instead. Earlier `findings` then become historical context.
+Without revision, any `fix-code` decision requires another `builder` `run`, including when other `findings` are rejected.
+After the `builder` completes the fixes, the `verifier` checks the work again.
 
 ## Spec revision
 
-`Spec` revisions are allowed only in `escalation-decision` or `findings-decision`. `Maestro` revises the same `spec` with the `owner`, including its prototypes when needed.
+For either `escalation` answers or `finding` decisions, `Maestro` records the complete batch before the workflow returns to `drafting-spec`.
+This decision does not approve the `spec` or start an agent.
+The `owner` and `Maestro` then revise the same `spec` together in `drafting-spec`.
 
-After review and cleanup, `Maestro` asks the `owner` to inspect the revised `spec` and reply `GREEN FLAG` again. `Maestro` then records `ready-for-builder` and starts another `builder` `run`.
+The `owner` reviews the changes and replies `GREEN FLAG` again.
+`Maestro` records that renewed approval separately, moves to `ready-for-builder`, and starts another `builder` `run`.
+Approval is permitted only in `drafting-spec`, not directly from either decision phase.
 
-Previous `escalations`, `findings`, and `handoffs` remain as historical context. The revised `spec` defines the requirements for subsequent work.
+The revised `spec` controls subsequent work.
+Earlier `escalations`, `findings`, and their decisions remain historical context.
 
 ## Verification boundary
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.9.4",
+  "version": "0.10.0",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",

package/src/artifacts/verifier-handoff/schema.ts

@@ -35,10 +35,19 @@ const FindingEvidenceSchema = Type.Object(
 export const FINDING_DECISIONS = {
   REJECT: 'reject',
   FIX_CODE: 'fix-code',
+  REVISE_SPEC: 'revise-spec',
 } as const;
 
 const FindingDecisionSchema = Type.Union([
   Type.Null(),
+  Type.Object(
+    {
+      decision: Type.Literal(FINDING_DECISIONS.REVISE_SPEC),
+      reason: Type.String({ minLength: 1, pattern: '\\S' }),
+      specChange: Type.String({ minLength: 1, pattern: '\\S' }),
+    },
+    { additionalProperties: false },
+  ),
   Type.Object(
     {
       decision: Type.Literal(FINDING_DECISIONS.REJECT),

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -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.
@@ -81,9 +81,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 +108,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 +120,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 +143,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/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 =>
@@ -72,6 +84,14 @@ const formatResolution = (details: FindingResolutionDetails): string => {
   const rejected = formatFindingIds(details.rejectedFindingIds);
   const requiringFix = formatFindingIds(details.findingsRequiringFixIds);
 
+  if (details.phase === WORKFLOW_PHASES.DRAFTING_SPEC) {
+    const requiringRevision = formatFindingIds(
+      details.findingsRequiringSpecRevisionIds,
+    );
+
+    return `Recorded rejections for ${rejected}. Findings requiring code fixes: ${requiringFix}. 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.`;
   }
@@ -109,6 +129,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;
     };
 
@@ -120,7 +120,7 @@ const buildRunResult = async ({
     return await readDoneBuilderResult({ paths, specId });
   }
 
-  if (state.phase === WORKFLOW_PHASES.ESCALATION_DECISION) {
+  if (state.phase === WORKFLOW_PHASES.ESCALATION_DECISIONS) {
     const handoff = await readBuilderHandoff({
       path: await paths.getActiveBuilderHandoffPath(specId),
       specId,

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

@@ -47,9 +47,9 @@ type CandidateReadyResult = {
 };
 
 type FindingsResult = {
-  outcome: typeof WORKFLOW_PHASES.FINDINGS_DECISION;
+  outcome: typeof WORKFLOW_PHASES.FINDING_DECISIONS;
   specId: string;
-  phase: typeof WORKFLOW_PHASES.FINDINGS_DECISION;
+  phase: typeof WORKFLOW_PHASES.FINDING_DECISIONS;
   handoff: VerifierHandoff;
 };
 
@@ -70,7 +70,7 @@ const readTerminalVerifierResult = async ({
 > => {
   if (
     state.phase !== WORKFLOW_PHASES.CANDIDATE_READY &&
-    state.phase !== WORKFLOW_PHASES.FINDINGS_DECISION
+    state.phase !== WORKFLOW_PHASES.FINDING_DECISIONS
   ) {
     throw new Error(
       `Verifier returned with unexpected workflow phase "${state.phase}".`,
@@ -84,7 +84,7 @@ const readTerminalVerifierResult = async ({
 
   const expectedPhase =
     handoff.findings.length > 0
-      ? WORKFLOW_PHASES.FINDINGS_DECISION
+      ? WORKFLOW_PHASES.FINDING_DECISIONS
       : WORKFLOW_PHASES.CANDIDATE_READY;
 
   if (state.phase !== expectedPhase) {

package/src/workflow/builder/completeBuilderPass.ts

@@ -3,7 +3,7 @@
  * Used: When the builder reports done or escalation through the child tool.
  */
 
-import { mkdir } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { Value } from 'typebox/value';
 import { assertBuilderHandoff } from '#artifacts/builder-handoff/assertBuilderHandoff.ts';
 import {
@@ -19,6 +19,7 @@ import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
+import { assertSpecAcceptanceCriteria } from '#workflow/utils/assertSpecAcceptanceCriteria.ts';
 
 export type CompletedBuilderPass = {
   handoff: BuilderHandoff;
@@ -76,6 +77,11 @@ export const completeBuilderPass = async ({
   assertBuilderHandoff(handoffInput);
   const { handoff } = handoffInput;
 
+  assertSpecAcceptanceCriteria({
+    markdown: await readFile(paths.getSpecFilePath(specId), 'utf8'),
+    criterionIds: new Set(handoff.acceptanceCriteria.map(({ id }) => id)),
+  });
+
   const nextState = transitionWorkflow({
     state: currentState,
     event: getWorkflowEventByBuilderHandoff(handoff),

package/src/workflow/builder/resolveEscalations.ts

@@ -1,6 +1,6 @@
 /**
  * Objective: Save all owner resolutions in the active builder handoff.
- * Used: When the owner keeps the contract and resolves current questions together.
+ * Used: When the owner resolves current questions, with or without spec revision.
  */
 
 import { readBuilderHandoff } from '#artifacts/builder-handoff/readBuilderHandoff.ts';
@@ -10,8 +10,9 @@ import {
 } from '#artifacts/builder-handoff/schema.ts';
 import { writeBuilderHandoff } from '#artifacts/builder-handoff/writeBuilderHandoff.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
+import { getWorkflowEventBySpecChangeRequired } from '#workflow/builder/utils/getWorkflowEventBySpecChangeRequired.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import { WORKFLOW_EVENTS, WORKFLOW_PHASES } from '#workflow/state/schema.ts';
+import { WORKFLOW_PHASES } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
 
@@ -22,12 +23,14 @@ export type EscalationDecision = EscalationResolution & {
 type ResolveEscalationsInput = {
   paths: MaestroPaths;
   specId: string;
+  specChangeRequired: boolean;
   decisions: EscalationDecision[];
 };
 
 export const resolveEscalations = async ({
   paths,
   specId,
+  specChangeRequired,
   decisions,
 }: ResolveEscalationsInput) => {
   const workflowPath = paths.getWorkflowPath(specId);
@@ -35,9 +38,9 @@ export const resolveEscalations = async ({
 
   if (state.specId !== specId) throw new Error('Workflow spec ID mismatch.');
 
-  if (state.phase !== WORKFLOW_PHASES.ESCALATION_DECISION) {
+  if (state.phase !== WORKFLOW_PHASES.ESCALATION_DECISIONS) {
     throw new Error(
-      `Escalation resolution requires escalation-decision state, found "${state.phase}".`,
+      `Escalation resolution requires escalation-decisions state, found "${state.phase}".`,
     );
   }
 
@@ -81,7 +84,7 @@ export const resolveEscalations = async ({
 
   const nextState = transitionWorkflow({
     state,
-    event: WORKFLOW_EVENTS.RESOLVE_ESCALATION,
+    event: getWorkflowEventBySpecChangeRequired(specChangeRequired),
   });
 
   // The artifact writer validates every resolution before the first protocol write.

package/src/workflow/builder/utils/getWorkflowEventByBuilderHandoff.ts

@@ -17,7 +17,7 @@ export const getWorkflowEventByBuilderHandoff = ({
   }
 
   if (status === BUILDER_HANDOFF_STATUSES.ESCALATION) {
-    return WORKFLOW_EVENTS.OPEN_ESCALATION;
+    return WORKFLOW_EVENTS.BUILDER_OPEN_ESCALATIONS;
   }
 
   throw new Error(`Unexpected builder handoff status: "${status}".`);

package/src/workflow/builder/utils/getWorkflowEventBySpecChangeRequired.ts

@@ -0,0 +1,16 @@
+/**
+ * Objective: Select the workflow event for resolving escalations.
+ * Used: When owner answers determine whether the spec must change.
+ */
+
+import { WORKFLOW_EVENTS, type WorkflowEvent } from '#workflow/state/schema.ts';
+
+export const getWorkflowEventBySpecChangeRequired = (
+  specChangeRequired: boolean,
+): WorkflowEvent => {
+  if (specChangeRequired) {
+    return WORKFLOW_EVENTS.OWNER_REQUEST_SPEC_REVISION;
+  }
+
+  return WORKFLOW_EVENTS.RESOLVE_ESCALATIONS;
+};

package/src/workflow/state/schema.ts

@@ -13,34 +13,35 @@ export const WORKFLOW_PHASES = {
   DRAFTING_SPEC: 'drafting-spec',
   READY_FOR_BUILDER: 'ready-for-builder',
   BUILDER_RUNNING: 'builder-running',
-  ESCALATION_DECISION: 'escalation-decision',
+  ESCALATION_DECISIONS: 'escalation-decisions',
   READY_FOR_VERIFIER: 'ready-for-verifier',
   VERIFIER_RUNNING: 'verifier-running',
-  FINDINGS_DECISION: 'findings-decision',
+  FINDING_DECISIONS: 'finding-decisions',
   CANDIDATE_READY: 'candidate-ready',
 } as const;
 
 export const WORKFLOW_EVENTS = {
   MARK_SPEC_READY: 'mark-spec-ready',
   RUN_BUILDER: 'run-builder',
-  OPEN_ESCALATION: 'open-escalation',
-  RESOLVE_ESCALATION: 'resolve-escalation',
+  BUILDER_OPEN_ESCALATIONS: 'builder-open-escalations',
+  RESOLVE_ESCALATIONS: 'resolve-escalations',
+  OWNER_REQUEST_SPEC_REVISION: 'owner-request-spec-revision',
   BUILDER_DONE: 'builder-done',
   RUN_VERIFIER: 'run-verifier',
   VERIFIER_FOUND_FINDINGS: 'verifier-found-findings',
-  VERIFIER_APPROVED: 'verifier-approved',
-  REJECT_FINDINGS: 'reject-findings',
-  REQUEST_FIXES: 'request-fixes',
+  VERIFIER_DONE: 'verifier-done',
+  OWNER_REJECT_FINDINGS: 'owner-reject-findings',
+  OWNER_REQUEST_FIXES: 'owner-request-fixes',
 } as const;
 
 export const WorkflowPhaseSchema = Type.Union([
   Type.Literal(WORKFLOW_PHASES.DRAFTING_SPEC),
   Type.Literal(WORKFLOW_PHASES.READY_FOR_BUILDER),
   Type.Literal(WORKFLOW_PHASES.BUILDER_RUNNING),
-  Type.Literal(WORKFLOW_PHASES.ESCALATION_DECISION),
+  Type.Literal(WORKFLOW_PHASES.ESCALATION_DECISIONS),
   Type.Literal(WORKFLOW_PHASES.READY_FOR_VERIFIER),
   Type.Literal(WORKFLOW_PHASES.VERIFIER_RUNNING),
-  Type.Literal(WORKFLOW_PHASES.FINDINGS_DECISION),
+  Type.Literal(WORKFLOW_PHASES.FINDING_DECISIONS),
   Type.Literal(WORKFLOW_PHASES.CANDIDATE_READY),
 ]);
 

package/src/workflow/transitions.ts

@@ -19,25 +19,28 @@ type WorkflowTransition = {
 
 export const WORKFLOW_TRANSITIONS: Record<WorkflowEvent, WorkflowTransition> = {
   [WORKFLOW_EVENTS.MARK_SPEC_READY]: {
-    from: [
-      WORKFLOW_PHASES.DRAFTING_SPEC,
-      WORKFLOW_PHASES.ESCALATION_DECISION,
-      WORKFLOW_PHASES.FINDINGS_DECISION,
-    ],
+    from: [WORKFLOW_PHASES.DRAFTING_SPEC],
     to: WORKFLOW_PHASES.READY_FOR_BUILDER,
   },
   [WORKFLOW_EVENTS.RUN_BUILDER]: {
     from: [WORKFLOW_PHASES.READY_FOR_BUILDER],
     to: WORKFLOW_PHASES.BUILDER_RUNNING,
   },
-  [WORKFLOW_EVENTS.OPEN_ESCALATION]: {
+  [WORKFLOW_EVENTS.BUILDER_OPEN_ESCALATIONS]: {
     from: [WORKFLOW_PHASES.BUILDER_RUNNING],
-    to: WORKFLOW_PHASES.ESCALATION_DECISION,
+    to: WORKFLOW_PHASES.ESCALATION_DECISIONS,
   },
-  [WORKFLOW_EVENTS.RESOLVE_ESCALATION]: {
-    from: [WORKFLOW_PHASES.ESCALATION_DECISION],
+  [WORKFLOW_EVENTS.RESOLVE_ESCALATIONS]: {
+    from: [WORKFLOW_PHASES.ESCALATION_DECISIONS],
     to: WORKFLOW_PHASES.READY_FOR_BUILDER,
   },
+  [WORKFLOW_EVENTS.OWNER_REQUEST_SPEC_REVISION]: {
+    from: [
+      WORKFLOW_PHASES.ESCALATION_DECISIONS,
+      WORKFLOW_PHASES.FINDING_DECISIONS,
+    ],
+    to: WORKFLOW_PHASES.DRAFTING_SPEC,
+  },
   [WORKFLOW_EVENTS.BUILDER_DONE]: {
     from: [WORKFLOW_PHASES.BUILDER_RUNNING],
     to: WORKFLOW_PHASES.READY_FOR_VERIFIER,
@@ -48,18 +51,18 @@ export const WORKFLOW_TRANSITIONS: Record<WorkflowEvent, WorkflowTransition> = {
   },
   [WORKFLOW_EVENTS.VERIFIER_FOUND_FINDINGS]: {
     from: [WORKFLOW_PHASES.VERIFIER_RUNNING],
-    to: WORKFLOW_PHASES.FINDINGS_DECISION,
+    to: WORKFLOW_PHASES.FINDING_DECISIONS,
   },
-  [WORKFLOW_EVENTS.VERIFIER_APPROVED]: {
+  [WORKFLOW_EVENTS.VERIFIER_DONE]: {
     from: [WORKFLOW_PHASES.VERIFIER_RUNNING],
     to: WORKFLOW_PHASES.CANDIDATE_READY,
   },
-  [WORKFLOW_EVENTS.REJECT_FINDINGS]: {
-    from: [WORKFLOW_PHASES.FINDINGS_DECISION],
+  [WORKFLOW_EVENTS.OWNER_REJECT_FINDINGS]: {
+    from: [WORKFLOW_PHASES.FINDING_DECISIONS],
     to: WORKFLOW_PHASES.CANDIDATE_READY,
   },
-  [WORKFLOW_EVENTS.REQUEST_FIXES]: {
-    from: [WORKFLOW_PHASES.FINDINGS_DECISION],
+  [WORKFLOW_EVENTS.OWNER_REQUEST_FIXES]: {
+    from: [WORKFLOW_PHASES.FINDING_DECISIONS],
     to: WORKFLOW_PHASES.READY_FOR_BUILDER,
   },
 };

package/src/workflow/utils/assertSpecAcceptanceCriteria.ts

@@ -0,0 +1,24 @@
+/**
+ * Objective: Require every spec criterion ID in a handoff.
+ * Used: Before builder and verifier submissions save their reports.
+ */
+
+type AssertSpecAcceptanceCriteriaInput = {
+  markdown: string;
+  criterionIds: Set<string>;
+};
+
+export function assertSpecAcceptanceCriteria({
+  markdown,
+  criterionIds,
+}: AssertSpecAcceptanceCriteriaInput): void {
+  const missingIds = [...markdown.matchAll(/^### AC(\d+):/gm)]
+    .map((match) => `AC${match[1]}`)
+    .filter((id) => !criterionIds.has(id));
+
+  if (missingIds.length > 0) {
+    throw new Error(
+      `Handoff is missing acceptance criterion IDs from spec.md: ${missingIds.join(', ')}.`,
+    );
+  }
+}

package/src/workflow/utils/getAgentRole.ts

@@ -9,13 +9,13 @@ import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
 
 const BUILDER_PHASES: readonly WorkflowState['phase'][] = [
   WORKFLOW_PHASES.BUILDER_RUNNING,
-  WORKFLOW_PHASES.ESCALATION_DECISION,
+  WORKFLOW_PHASES.ESCALATION_DECISIONS,
   WORKFLOW_PHASES.READY_FOR_VERIFIER,
 ];
 
 const VERIFIER_PHASES: readonly WorkflowState['phase'][] = [
   WORKFLOW_PHASES.VERIFIER_RUNNING,
-  WORKFLOW_PHASES.FINDINGS_DECISION,
+  WORKFLOW_PHASES.FINDING_DECISIONS,
 ];
 
 export const getAgentRole = (

package/src/workflow/verifier/completeVerifierPass.ts

@@ -3,7 +3,7 @@
  * Used: When the verifier submits its terminal handoff.
  */
 
-import { mkdir } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { assertVerifierHandoff } from '#artifacts/verifier-handoff/assertVerifierHandoff.ts';
 import type { VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
 import { writeVerifierHandoff } from '#artifacts/verifier-handoff/writeVerifierHandoff.ts';
@@ -12,6 +12,7 @@ import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
+import { assertSpecAcceptanceCriteria } from '#workflow/utils/assertSpecAcceptanceCriteria.ts';
 import { getWorkflowEventByVerifierHandoff } from '#workflow/verifier/utils/getWorkflowEventByVerifierHandoff.ts';
 
 export type CompletedVerifierPass = {
@@ -56,6 +57,11 @@ export const completeVerifierPass = async ({
   assertVerifierHandoff(handoffInput);
   const { handoff } = handoffInput;
 
+  assertSpecAcceptanceCriteria({
+    markdown: await readFile(paths.getSpecFilePath(specId), 'utf8'),
+    criterionIds: new Set(handoff.acceptanceCriteria.map(({ id }) => id)),
+  });
+
   const nextState = transitionWorkflow({
     state: currentState,
     event: getWorkflowEventByVerifierHandoff(handoff),

package/src/workflow/verifier/resolveFindings.ts

@@ -1,6 +1,6 @@
 /**
  * Objective: Record owner decisions for current verifier findings on the active handoff.
- * Used: When the owner resolves a findings-decision handoff.
+ * Used: When the owner resolves a finding-decisions handoff.
  */
 
 import { assertVerifierHandoff } from '#artifacts/verifier-handoff/assertVerifierHandoff.ts';
@@ -29,7 +29,17 @@ type FindingDecisionApproved = {
   decision: typeof FINDING_DECISIONS.FIX_CODE;
 };
 
-export type FindingDecision = FindingDecisionApproved | FindingDecisionRejected;
+type FindingDecisionRevision = {
+  findingId: string;
+  decision: typeof FINDING_DECISIONS.REVISE_SPEC;
+  reason: string;
+  specChange: string;
+};
+
+export type FindingDecision =
+  | FindingDecisionApproved
+  | FindingDecisionRejected
+  | FindingDecisionRevision;
 
 export type ResolvedFindings = {
   findings: VerifierFinding[];
@@ -98,9 +108,9 @@ const readFindingWorkflow = async ({
     );
   }
 
-  if (state.phase !== WORKFLOW_PHASES.FINDINGS_DECISION) {
+  if (state.phase !== WORKFLOW_PHASES.FINDING_DECISIONS) {
     throw new Error(
-      `Finding resolution requires findings-decision state, found "${state.phase}".`,
+      `Finding resolution requires finding-decisions state, found "${state.phase}".`,
     );
   }
 
@@ -143,6 +153,17 @@ const buildFindingWorkflow = ({
   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,

package/src/workflow/verifier/utils/getWorkflowEventByVerifierHandoff.ts

@@ -13,19 +13,27 @@ export const getWorkflowEventByVerifierHandoff = (
   handoff: VerifierHandoff,
 ): WorkflowEvent => {
   if (handoff.findings.length === 0) {
-    return WORKFLOW_EVENTS.VERIFIER_APPROVED;
+    return WORKFLOW_EVENTS.VERIFIER_DONE;
   }
 
   if (handoff.findings.every(({ decision }) => decision === null)) {
     return WORKFLOW_EVENTS.VERIFIER_FOUND_FINDINGS;
   }
 
+  if (
+    handoff.findings.some(
+      ({ decision }) => decision?.decision === FINDING_DECISIONS.REVISE_SPEC,
+    )
+  ) {
+    return WORKFLOW_EVENTS.OWNER_REQUEST_SPEC_REVISION;
+  }
+
   if (
     handoff.findings.some(
       ({ decision }) => decision?.decision === FINDING_DECISIONS.FIX_CODE,
     )
   ) {
-    return WORKFLOW_EVENTS.REQUEST_FIXES;
+    return WORKFLOW_EVENTS.OWNER_REQUEST_FIXES;
   }
 
   if (
@@ -33,7 +41,7 @@ export const getWorkflowEventByVerifierHandoff = (
       ({ decision }) => decision?.decision === FINDING_DECISIONS.REJECT,
     )
   ) {
-    return WORKFLOW_EVENTS.REJECT_FINDINGS;
+    return WORKFLOW_EVENTS.OWNER_REJECT_FINDINGS;
   }
 
   throw new Error('Unexpected verifier finding decisions.');