@emiliosp/pi-maestro 0.9.5 → 0.10.1

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 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. Added `success`, `failure`, and `unchanged` coverage labels to the `spec` template and `Maestro` guidance. Approval validation and `handoff` formats remain unchanged.
+2. Required `Maestro` to inspect existing tests before writing `acceptance criteria` and remove criteria whose exact scenarios already have coverage. Requirements remain documented in the `spec`.
+
+## 0.10.0
+
+1. Saved complete `owner` decision batches in their original `handoffs` before changing phase, including when the `spec` requires revision. See [PR #38](https://github.com/emilioSp/pi-maestro/pull/38).
+2. Added `revise-spec` decisions for `verifier` `findings`, with the owner's reason and agreed requirement change. Revision takes priority over code fixes and rejections.
+3. Unified both revision paths through `drafting-spec`, with renewed `GREEN FLAG` before separate approval and another `builder` `run`. Approval is allowed only from `drafting-spec`.
+4. Renamed workflow events to identify `builder` and `owner` actions. Both revision paths share `OWNER_REQUEST_SPEC_REVISION`.
+5. Breaking: supply the required boolean `specChangeRequired` when calling `maestro_resolve_escalations`.
+6. Breaking: saved decision phases are now `escalation-decisions` and `finding-decisions`. Existing workflows using older names require manual `owner` handling. No automatic migration is provided.
+
+## 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).

package/README.md

@@ -10,12 +10,13 @@ Pi extension for a spec-driven multiagent development workflow.
 
 A `specification` (`spec`) describes one reversible change. The `builder` implements it. An independent `verifier` checks every `acceptance criterion`. The `owner` performs the final review.
 
-Four principles hold the workflow together:
+Five principles hold the workflow together:
 
 1. The approved `spec` defines the required work for the `builder` and `verifier`.
 2. No agent approves its own work.
 3. Every `acceptance criterion` is checked independently.
 4. The `owner` decides requirements, scope, and unresolved questions.
+5. Each agent has one and only one role. Specific and with clear instruction.
 
 ## The roles
 
@@ -79,7 +80,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

@@ -6,6 +6,30 @@ This roadmap records planned outcomes, not permission to implement them. The `ow
 
 Item identifiers remain stable when priorities change. The `owner` approves changes to priorities and scope.
 
+## Overview
+
+| ID | Title | Status | Summary |
+|---|---|---|---|
+| R-01 | [Improve status presentation and activation feedback](#r-01-improve-status-presentation-and-activation-feedback) | Completed | Show clearer status and configured agent details without adding model context. |
+| R-02 | [Store escalations and owner decisions in builder handoffs](#r-02-store-escalations-and-owner-decisions-in-builder-handoffs) | Completed | Keep `escalation` questions and `owner` answers together in numbered `builder` `handoffs`. |
+| R-03 | [Route builder failures through owner escalations](#r-03-route-builder-failures-through-owner-escalations) | Completed | Route reportable `builder` problems through `owner` `escalations` instead of a terminal failure phase. |
+| R-12 | [Format glossary terms consistently](#r-12-format-glossary-terms-consistently) | Completed | Apply glossary formatting across documentation and record its exclusions. |
+| R-14 | [Introduce Maestro at activation](#r-14-introduce-maestro-at-activation) | Completed | Introduce `Maestro` at activation and load relevant documentation only when needed. |
+| R-15 | [Rename the test support directory](#r-15-rename-the-test-support-directory) | Completed | Rename `test/` to `tests/` and update affected references. |
+| R-16 | [Verify code quality against AGENTS.md instructions](#r-16-verify-code-quality-against-agentsmd-instructions) | Completed | Require the `verifier` to review affected code against applicable `AGENTS.md` code-quality directives. |
+| R-06 | [Check subagent extensions at activation](#r-06-check-subagent-extensions-at-activation) | Completed | Require a successful parent `pi-subagents` availability reply before activation. |
+| R-05 | [Keep acceptance criterion numbering continuous](#r-05-keep-acceptance-criterion-numbering-continuous) | Completed | Reject gaps in `acceptance criterion` numbering before approving a `spec`. |
+| R-10 | [Match handoff criteria to the approved spec](#r-10-match-handoff-criteria-to-the-approved-spec) | Completed | Require every approved `spec` criterion ID in each submitted `builder` and `verifier` `handoff`. |
+| R-17 | [Record escalation resolutions when the spec changes](#r-17-record-escalation-resolutions-when-the-spec-changes) | Completed | Save all current `escalation` answers before changing phase, including when the `spec` requires revision. |
+| R-20 | [Route finding-driven spec revisions through drafting-spec](#r-20-route-finding-driven-spec-revisions-through-drafting-spec) | Completed | Record `finding` decisions before `spec` revision and require renewed `GREEN FLAG` before another `builder` `run`. |
+| R-18 | [Label acceptance criterion coverage](#r-18-label-acceptance-criterion-coverage) | Completed | Label each `acceptance criterion` as success, failure, or unchanged behavior. |
+| R-19 | [Avoid acceptance criteria already covered by tests](#r-19-avoid-acceptance-criteria-already-covered-by-tests) | Completed | Omit `acceptance criteria` whose exact scenarios already have test coverage. |
+| R-04 | [Rename the npm package](#r-04-rename-the-npm-package) | Later | Rename `@emiliosp/pi-maestro` to `pi-maestro-sdd` with compatibility decisions defined in the `spec`. |
+| R-07 | [Guide initial configuration](#r-07-guide-initial-configuration) | Later | Help the `owner` create valid `Maestro` configuration through an interview. |
+| R-08 | [Change agent models before a builder run](#r-08-change-agent-models-before-a-builder-run) | Later | Let the `owner` change `builder` and `verifier` models before subsequent `runs`. |
+| R-09 | [Define workflow reconciliation](#r-09-define-workflow-reconciliation) | Later | Define how `Maestro` can reconcile saved `artifacts` and workflow state. |
+| R-21 | [Add a simplifier with one clear purpose per agent](#r-21-add-a-simplifier-with-one-clear-purpose-per-agent) | Later | Add a simplifier after successful verification to reduce complexity without changing behavior. |
+
 ## Completed
 
 ### R-01: Improve status presentation and activation feedback
@@ -60,7 +84,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
 
@@ -98,27 +122,102 @@ All 3 `acceptance criteria` passed with no `verifier` `findings`. The saved work
 
 [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).
 
-## Now
-
 ### 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
 
-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.
+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.
 
-The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
+| 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. |
+
+Direct `spec` approval from `escalation-decisions` is rejected. Recording answers does not move to `ready-for-verifier`; that phase requires a completed `builder` `pass`.
+
+#### 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
 
-Both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase.
+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).
+
+### R-18: Label acceptance criterion coverage
+
+Implemented with R-19 as one task, as selected by the `owner`.
+The `spec` template and `Maestro` guidance require one `Coverage` label per `acceptance criterion`:
 
-#### Implementation status
+| Label | Purpose |
+|---|---|
+| `success` | A valid action produces the required result. |
+| `failure` | An invalid action is correctly rejected. |
+| `unchanged` | The change preserves existing behavior. |
 
-The [approved specification](.specs/20261013-211629-match-handoff-criteria-to-the-approved-spec/spec.md) limits this change to missing IDs. The implementation rejects missing `spec` IDs before saving either `handoff` or changing phase. Extra report IDs remain allowed. No new check rejects duplicate IDs in the `spec`.
+Use `unchanged` when the criterion explicitly checks behavior that the change must preserve.
+Labels describe scenarios, not test outcomes. A `failure` scenario passes when the invalid action is correctly rejected.
+A `spec` does not need all three categories.
+`Maestro` includes labels when presenting criteria to the `owner` and checks them against scenarios and `expected results` during review.
+Approval validation and `handoff` formats remain unchanged.
 
-Both `acceptance criteria` passed independent verification with no `findings`. The saved workflow reached `candidate-ready`. The broader exact-match objective remains outside this approved scope.
+The existing creation integration test now checks that the generated `spec` includes the coverage field.
+The final `npm run check` passed all 238 tests and coverage thresholds. No model trials were performed.
 
-Later changes requested by the `owner` extract the shared presence check into one utility and cover extraction with unit tests. One missing-ID integration test remains per role to check rejection before saving. These changes are outside the completed independent verification.
+#### Evidence
+
+[Spec template](templates/spec.md), [Maestro guidance](src/maestro/instructions/getMaestroInstructions.ts), [creation integration test](src/specs/create.integration.test.ts), and [workflow documentation](docs/workflow.md#acceptance-criteria).
+
+### R-19: Avoid acceptance criteria already covered by tests
+
+Implemented with R-18. `Maestro` inspects existing tests before writing `acceptance criteria`.
+It omits a criterion only when a test covers the same starting conditions, action, and `expected result`.
+Partial or uncertain coverage does not justify omission. Similar tests do not count.
+
+During `spec` review, `Maestro` removes criteria whose exact scenarios already have test coverage.
+It keeps numbering continuous from `AC1` and updates affected references. Required behavior remains documented in the requirements and constraints.
+The same rules apply during `spec` revisions. No automatic approval check was added.
+
+Verification consisted of inspecting the written guidance and running `npm run check`. No model trials were performed.
+
+#### Evidence
+
+[Maestro guidance](src/maestro/instructions/getMaestroInstructions.ts), [spec template](templates/spec.md), and [workflow documentation](docs/workflow.md#acceptance-criteria).
+
+## Now
 
 ## Next
 
@@ -167,3 +266,25 @@ Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The re
 #### Completed when
 
 Not yet defined. The `owner` must define the intended outcome, recovery boundaries, and completion condition before this item can move forward.
+
+### R-21: Add a simplifier with one clear purpose per agent
+
+#### Objective
+
+Each agent has exactly one purpose. The `builder` implements the approved `spec`. The `verifier` independently checks its `acceptance criteria`. The simplifier refactors verified code.
+
+Add the simplifier after the `verifier`. It receives code built by the `builder` only after verification confirms that all checks defined in the `acceptance criteria` pass.
+
+The simplifier reduces complexity while preserving exact behavior. The goal is code that is easier to read, understand, modify, and debug, not fewer lines.
+Every simplification must pass this test: "Would a new team member understand this faster than the original?"
+
+#### Scope boundaries
+
+Remove the "Review code quality" section from `agents/verifier.md`. This replaces the additional review introduced in R-16, not independent verification of `acceptance criteria`.
+
+The simplifier's detailed instructions will be defined during `spec` preparation. This roadmap item does not define them.
+
+#### Completed when
+
+The workflow includes the simplifier after successful verification. Agent instructions keep implementation, verification, and simplification as separate responsibilities.
+The simplifier preserves exact behavior and follows the instructions agreed in the approved `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

@@ -4,7 +4,7 @@
 
 The approved `spec.md` defines behavior, scope, constraints, technical decisions, and `acceptance criteria` for the change.
 
-An `acceptance criterion` contains a `probe`, an `expected result`, and an example. A `probe` is a scenario used to test behavior.
+An `acceptance criterion` contains a coverage label, a `probe`, an `expected result`, and an example. A `probe` is a scenario used to test behavior.
 
 A `handoff` is a saved report from a `builder` or `verifier` `run`. It records the result, `probe` outcomes, and notes.
 
@@ -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
 
@@ -114,6 +114,7 @@ Each criterion contains these parts:
 
 | Part | Content |
 |---|---|
+| Coverage | One label that states the scenario's purpose: `success`, `failure`, or `unchanged`. |
 | `Probe` | Starting conditions and the action or observation that checks the behavior. |
 | `Expected result` | The measurable result the `probe` observes. |
 | Example | Concrete starting conditions, an input or action, and the exact `expected result`. |
@@ -125,14 +126,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 +151,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.5",
+  "version": "0.10.1",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",

package/src/MaestroPaths.ts

@@ -100,36 +100,15 @@ export class MaestroPaths {
   }
 
   public getSpecFilePath(specId: string): string {
-    assertSpecId(specId);
-
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.SPEC_FILE,
-    );
+    return resolve(this.getSpecPath(specId), PATHS.SPEC_FILE);
   }
 
   public getWorkflowPath(specId: string): string {
-    assertSpecId(specId);
-
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.WORKFLOW_FILE,
-    );
+    return resolve(this.getSpecPath(specId), PATHS.WORKFLOW_FILE);
   }
 
   public getHandoffsPath(specId: string): string {
-    assertSpecId(specId);
-
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.HANDOFFS_PATH,
-    );
+    return resolve(this.getSpecPath(specId), PATHS.HANDOFFS_PATH);
   }
 
   public getBuilderHandoffsPath(specId: string): string {
@@ -208,14 +187,7 @@ export class MaestroPaths {
   }
 
   public getPrototypesPath(specId: string): string {
-    assertSpecId(specId);
-
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.PROTOTYPES_PATH,
-    );
+    return resolve(this.getSpecPath(specId), PATHS.PROTOTYPES_PATH);
   }
 
   public getPrototypePath({

package/src/artifacts/builder-handoff/assertBuilderHandoff.ts

@@ -66,37 +66,31 @@ export function assertBuilderHandoff(
     throw new Error('Done builder handoff requires every probe to pass.');
   }
 
-  if (handoff.status === BUILDER_HANDOFF_STATUSES.ESCALATION) {
-    for (const [index, escalation] of handoff.escalations.entries()) {
-      if (escalation.id !== `E${index + 1}`) {
-        throw new Error('Escalation IDs must be sequential in array order.');
-      }
-
-      const optionIds = new Set(escalation.options.map(({ id }) => id));
-
-      if (optionIds.size !== escalation.options.length) {
-        throw new Error('Escalation option IDs must be unique.');
-      }
-
-      if (
-        escalation.recommendation !== null &&
-        !optionIds.has(escalation.recommendation.optionId)
-      ) {
-        throw new Error('Escalation recommendation references unknown option.');
-      }
-
-      if (
-        escalation.resolution !== null &&
-        escalation.resolution.selectedOptionId !== null &&
-        !optionIds.has(escalation.resolution.selectedOptionId)
-      ) {
-        throw new Error('Escalation resolution references unknown option.');
-      }
+  for (const [index, escalation] of handoff.escalations.entries()) {
+    if (escalation.id !== `E${index + 1}`) {
+      throw new Error('Escalation IDs must be sequential in array order.');
+    }
+
+    const optionIds = new Set(escalation.options.map(({ id }) => id));
+
+    if (optionIds.size !== escalation.options.length) {
+      throw new Error('Escalation option IDs must be unique.');
     }
-  }
 
-  if (!isValidSpecId(specId)) {
-    throw new Error(`Invalid expected builder handoff spec ID: "${specId}".`);
+    if (
+      escalation.recommendation !== null &&
+      !optionIds.has(escalation.recommendation.optionId)
+    ) {
+      throw new Error('Escalation recommendation references unknown option.');
+    }
+
+    if (
+      escalation.resolution !== null &&
+      escalation.resolution.selectedOptionId !== null &&
+      !optionIds.has(escalation.resolution.selectedOptionId)
+    ) {
+      throw new Error('Escalation resolution references unknown option.');
+    }
   }
 
   if (handoff.specId !== specId) {

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

@@ -40,18 +40,17 @@ export function assertVerifierHandoff(
     throw new Error(`Invalid verifier handoff spec ID: "${handoff.specId}".`);
   }
 
-  if (
-    new Set(handoff.acceptanceCriteria.map((criterion) => criterion.id))
-      .size !== handoff.acceptanceCriteria.length
-  ) {
+  const acceptanceCriterionIds = new Set(
+    handoff.acceptanceCriteria.map((criterion) => criterion.id),
+  );
+
+  if (acceptanceCriterionIds.size !== handoff.acceptanceCriteria.length) {
     throw new Error(
       'Verifier handoff acceptance criterion IDs must be unique.',
     );
   }
 
-  const acceptanceCriterionIds = new Set(
-    handoff.acceptanceCriteria.map((criterion) => criterion.id),
-  );
+  const criterionIdsWithFindings = new Set<string>();
 
   for (const [index, finding] of handoff.findings.entries()) {
     const expectedId = `F${index + 1}`;
@@ -62,26 +61,23 @@ export function assertVerifierHandoff(
       );
     }
 
-    if (
-      finding.acceptanceCriterion !== null &&
-      !acceptanceCriterionIds.has(finding.acceptanceCriterion)
-    ) {
+    if (finding.acceptanceCriterion === null) {
+      continue;
+    }
+
+    if (!acceptanceCriterionIds.has(finding.acceptanceCriterion)) {
       throw new Error(
         `Verifier handoff finding "${finding.id}" references unknown acceptance criterion "${finding.acceptanceCriterion}".`,
       );
     }
-  }
 
-  const findingCriteria = new Set(
-    handoff.findings.flatMap((finding) =>
-      finding.acceptanceCriterion === null ? [] : [finding.acceptanceCriterion],
-    ),
-  );
+    criterionIdsWithFindings.add(finding.acceptanceCriterion);
+  }
 
   for (const criterion of handoff.acceptanceCriteria) {
     if (
       criterion.probeStatus !== PROBE_STATUSES.PASSED &&
-      !findingCriteria.has(criterion.id)
+      !criterionIdsWithFindings.has(criterion.id)
     ) {
       throw new Error(
         `Verifier handoff incomplete acceptance criterion "${criterion.id}" requires a finding.`,

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),