@emiliosp/pi-maestro 0.6.3 → 0.7.0

package/README.md

@@ -1,5 +1,7 @@
 # pi-maestro
 
+[![Coverage](https://img.shields.io/codecov/c/github/emiliosp/pi-maestro?logo=codecov)](https://codecov.io/gh/emiliosp/pi-maestro)
+
 Pi extension for a spec-driven multiagent development workflow.
 
 ![Maestro workflow](docs/maestro.png)
@@ -66,11 +68,11 @@ The owner follows this workflow:
 1. Describes one change to Maestro.
 2. Reviews the spec, including its acceptance criteria and concrete examples.
 3. Replies `GREEN FLAG` when Maestro asks for approval. Maestro records the approval and starts the builder.
-4. Reviews builder escalations and decides how to proceed.
+4. Reviews every current builder escalation and gives Maestro an answer and reason for each question.
 5. Reviews verifier findings and chooses an action for every finding.
 6. Reads Maestro's summary at `candidate-ready` and performs the final review.
 
-Maestro starts the verifier after a successful builder run. 
+Maestro starts the verifier after a successful builder run.
 Both agents run in the foreground: Pi waits for each run to finish and Maestro shows the current phase in Pi's status, while `pi-subagents` FleetView and `/subagents-fleet` show agent activity and transcripts.
 
 The owner must not edit product files while the workflow runs. 
@@ -89,6 +91,9 @@ Maestro uses default values when `.pi/maestro.json` is absent from the project r
 
 ## Documentation
 
-1. [Workflow](docs/workflow.md).
-2. [Configuration](docs/configuration.md).
-3. [Subagent integration](docs/subagent-integration.md).
+The reading order is:
+
+1. [Glossary](docs/glossary.md): terms and identifiers used in specs, reports, and Maestro messages. Read this before the first workflow.
+2. [Workflow](docs/workflow.md): approvals, decisions, and how each run produces artifacts.
+3. [Configuration](docs/configuration.md): project paths, models, and timeouts.
+4. [Subagent integration](docs/subagent-integration.md): agent context, execution, and activity tracking.

package/agents/builder.md

@@ -6,7 +6,6 @@ systemPromptMode: replace
 inheritProjectContext: true
 inheritGlobalContext: true
 inheritSkills: true
-completionGuard: false
 subagentOnlyExtensions: ../extensions/maestro-subagent.ts
 ---
 
@@ -22,7 +21,7 @@ Do not delegate, contact the owner directly, or approve your own work.
 1. Use the exact `specId` supplied by Maestro. Do not select another spec.
 2. Locate `<specDirectory>/<specId>/` relative to the canonical Pi working directory supplied by Maestro. Use `specDirectory` from `.pi/maestro.json`, or `.specs` when unset.
 3. Read `spec.md`, relevant `prototypes/`, `workflow.json`, and applicable `AGENTS.md` files.
-4. Read available handoffs and escalation resolutions for this spec. Earlier numbered artifacts remain on the file system.
+4. Read available handoffs and their embedded escalation resolutions for this spec. Earlier numbered artifacts remain on the file system.
 5. Confirm that the workflow identifies this spec and is in `builder-running`. Maestro already saved that phase.
 
 If the supplied spec is missing or the phase is wrong, report the mismatch to Maestro and stop. Do not repair workflow state.
@@ -32,7 +31,7 @@ The highest numeric sequence is the active handoff for each role. Earlier record
 
 Do not edit the frozen spec during builder or verifier execution.
 The approved spec defines the required behavior, constraints, technical decisions, scope, and acceptance criteria.
-If this pass follows an escalation resolution, follow the recorded owner decision without changing the contract.
+If this pass follows escalation resolutions, read them from the active builder handoff and follow each owner decision.
 If this pass follows `fix-code`, fix all current findings assigned for repair. These contain an explicit `decision: { decision: "fix-code" }` from the owner.
 Do not fix rejected findings merely because they appear in the handoff.
 After a spec revision, earlier escalations and findings are historical context, not active repair instructions.
@@ -43,8 +42,8 @@ Use the active spec and the active handoff to assess repair instructions. A find
 Change only product files needed to meet the approved contract, within the project root.
 Use existing repository patterns for routine implementation details that the spec leaves open. Do not add unrelated improvements.
 Follow applicable repository commands and technical rules. Inspect scripts before running them. Do not invent required commands.
-Do not edit `spec.md`, prototypes, `workflow.json`, handoffs, or escalation files directly through any tool.
-Use `maestro_record_builder_handoff` or `maestro_open_escalation` for protocol changes. The tools supply artifact paths and versions.
+Do not edit `spec.md`, prototypes, `workflow.json`, or handoffs directly through any tool.
+Use `maestro_record_builder_handoff` for protocol changes. The tool supplies artifact paths and versions.
 
 If a significant discovery requires an owner choice, stop implementation and use the escalation outcome below.
 Examples include a spec conflict, undefined behavior, a material architectural alternative, scope changes, or verification and reversibility decisions.
@@ -75,8 +74,8 @@ Include every spec criterion once. Do not omit unrun criteria, fabricate evidenc
 Before any terminal tool call, restore temporary verification changes and remove temporary verification files. Keep the implementation work.
 Choose the outcome from the actual result:
 
-1. `done`: Implementation and required checks are complete. Every criterion has `probeStatus: passed`. Call `maestro_record_builder_handoff` with `specId`, `status: done`, `summary`, `acceptanceCriteria`, and `notes`.
-2. Escalation: An owner decision is required. Call `maestro_open_escalation` with `specId`, `question`, `context`, `options`, `recommendation`, and `notes`. Include evidence in the context. Give each option an ID, description, consequences, and next step. Use `recommendation: null` unless evidence supports a specific option. Do not also submit a builder handoff.
+1. `done`: Implementation and required checks are complete. Every criterion has `probeStatus: passed`. Call `maestro_record_builder_handoff` with `specId`, `status: done`, `summary`, `acceptanceCriteria`, `notes`, and `escalations: []`.
+2. `escalation`: An owner decision is required. Call `maestro_record_builder_handoff` with `specId`, `status: escalation`, `summary`, every criterion result, `notes`, and all `escalations`. Assign sequential IDs in array order: `E1`, `E2`, and so on. Restart at `E1` for each handoff. Each entry contains `id`, `question`, `context`, `options`, `recommendation`, `notes`, and `resolution: null`. Include evidence in the context. Give each option an ID, description, consequences, and next step. Use `recommendation: null` unless evidence supports an option. Refer to questions with both IDs, such as `B1/E1`. Record actual probe results, including incomplete probes. All probes can pass when an owner decision remains necessary. Save one handoff and stop.
 3. `failed`: You cannot complete the work for a technical reason that needs no owner decision. Call `maestro_record_builder_handoff` with `specId`, `status: failed`, `summary`, all criterion results, `failure.reason`, and `notes`. Report actual statuses, including `not-run` where applicable.
 
 After a successful terminal call, return the saved outcome and artifact path to Maestro. Stop the pass.

package/agents/verifier.md

@@ -6,7 +6,6 @@ systemPromptMode: replace
 inheritProjectContext: true
 inheritGlobalContext: true
 inheritSkills: true
-completionGuard: false
 subagentOnlyExtensions: ../extensions/maestro-subagent.ts
 ---
 
@@ -22,7 +21,7 @@ Do not delegate, contact the owner directly, repair the implementation, or issue
 1. Use the exact `specId` and project directory supplied by Maestro. Do not select another spec or project.
 2. Locate `<specDirectory>/<specId>/` relative to the canonical Pi working directory supplied by Maestro. Use `specDirectory` from `.pi/maestro.json`, or `.specs` when unset.
 3. Read `spec.md`, relevant `prototypes/`, `workflow.json`, and applicable `AGENTS.md` files.
-4. Read the builder handoff and available earlier handoffs, escalation resolutions, and finding decisions. Earlier numbered artifacts remain on the file system.
+4. Read the builder handoff and available earlier handoffs, embedded escalation resolutions in builder handoffs, and finding decisions. Earlier numbered artifacts remain on the file system.
 5. Confirm that the workflow identifies this spec and is in `verifier-running`.
 
 If the required inputs or phase do not match, report the mismatch to Maestro and stop. Do not reset unrelated changes.
@@ -30,6 +29,7 @@ The candidate is the live project. Maestro creates no product snapshot or file-h
 This workflow assumes no external product edits during verification.
 Handoffs use `handoffs/builder/B1.json`, `B2.json` and `handoffs/verifier/V1.json`, `V2.json`.
 The highest numeric sequence is the active handoff for each role. Earlier handoffs and their owner decisions remain references.
+Escalation questions and owner resolutions are inside builder handoffs. Use handoff-qualified references, such as `B1/E1` and `B2/E1`.
 You start with a fresh context. Use artifacts as context, never as proof or as a replacement for the active spec.
 After a spec revision, assess historical observations against the revised contract. Do not carry forward old findings without fresh evidence.
 
@@ -89,7 +89,7 @@ Before each temporary change, retain the exact original file contents and note w
 Before handoff, restore only your temporary changes from probes and repository checks to those exact contents.
 Remove only temporary files created during this pass. Preserve all pre-existing files and content. Do not use blanket cleanup commands.
 For example, restore `src/total.ts` from `return 0` to its original `return 42`, remove your `probe.txt`, and leave pre-existing `notes.txt` unchanged.
-The spec, prototypes, earlier handoffs, and escalation files must remain unchanged. Findings do not relax this requirement.
+The spec, prototypes, and earlier handoffs must remain unchanged. Findings do not relax this requirement.
 If cleanup cannot finish safely, stop and report the remaining changes. Maestro validates the protocol, not product restoration.
 
 Call `maestro_record_verifier_handoff` with `specId`, `summary`, every criterion result, `findings`, and `notes`.

package/docs/glossary.md

@@ -0,0 +1,69 @@
+# Glossary
+
+## Terms
+
+| Term | Meaning |
+|---|---|
+| Owner | The person who approves the spec, decides questions and findings, and performs the final review. |
+| Maestro | The coordinator that prepares the spec, runs the agents, and records owner decisions. |
+| Builder | The agent that implements the approved spec and runs its probes. |
+| Verifier | The independent agent that checks the implementation and reports technical issues. |
+| Spec | A specification that describes one change and its acceptance criteria. It is saved as `spec.md`. |
+| Contract | The approved spec that defines the required behavior and scope. |
+| Acceptance criterion (AC) | One required, observable result defined in the spec. |
+| Probe | A scenario used to test an acceptance criterion. Reports record the actual command or procedure and its outcome. |
+| Expected result | The observable result that a probe must produce. |
+| Artifact | A saved workflow file, such as a spec, or a handoff between agents. |
+| Handoff | A saved builder or verifier report with results, probe outcomes, and notes. |
+| Run or pass | One execution of the builder or verifier with a fresh conversation. |
+| Candidate | The project files created by agents after a workflow run |
+| Finding | A technical issue that the verifier records for an owner decision. |
+| Escalation | An implementation question 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. |
+| `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. |
+
+## Identifiers and file names
+
+An ID is an identifier that names one record. These labels refer to records within one spec, not across all workflows.
+
+| Label | Meaning | Location or scope |
+|---|---|---|
+| `<spec-id>` | The identifier shared by the spec and its workflow artifacts. | The directory name under `<project-root>/.specs/` by default. |
+| `B1`, `B2` | Builder handoff 1, builder handoff 2. | `handoffs/builder/B1.json`, `handoffs/builder/B2.json`. |
+| `V1`, `V2` | Verifier handoff 1, verifier handoff 2. | `handoffs/verifier/V1.json`, `handoffs/verifier/V2.json`. |
+| `E1`, `E2` | Escalation 1, escalation 2 within one builder report. | Entries in that report's `escalations` list. |
+| `F1`, `F2` | Finding 1, finding 2 within one verifier report. | Entries in that report's `findings` list. |
+| `AC1`, `AC2` | Acceptance criterion 1, acceptance criterion 2. | Criteria in `spec.md` and the matching `acceptanceCriteria` entries in reports. |
+| `B1/E1` | Escalation 1 in builder handoff 1. | The question with `id: "E1"` inside `handoffs/builder/B1.json`. |
+| `V1/F2` | Finding 2 in verifier handoff 1. | The finding with `id: "F2"` inside `handoffs/verifier/V1.json`. |
+
+All paths in this table are relative to the spec directory unless stated otherwise. The [configuration](configuration.md#path-rules) can change the directory that contains specs.
+
+The `AC` prefix is the template's naming convention. Criterion IDs must be unique within the spec. Reports use the exact IDs from the spec.
+
+Builder and verifier numbers count saved handoffs in separate sequences.
+
+## Escalation references
+
+Read `B1/E1` as "escalation 1 in builder report 1". `B1` selects `handoffs/builder/B1.json`. `E1` selects the entry with `id: "E1"` in its `escalations` list.
+
+Escalation numbers restart at `E1` in each builder report. `B1/E1` and `B2/E1` identify different questions, even if they concern the same topic.
+
+The owner discusses every current question with Maestro. Maestro records all answers and reasons together in that same builder report. See [Escalations](workflow.md#escalations) for the available choices and their effects.
+
+## Finding references
+
+Read `V1/F2` as "finding 2 in verifier report 1". `V1` selects `handoffs/verifier/V1.json`. `F2` selects the entry with `id: "F2"` in its `findings` list.
+
+Finding numbers restart at `F1` in each verifier report. `V1/F2` and `V2/F2` identify different records, even if they describe a similar issue.
+
+For example, a finding about a saved title can appear in a Maestro message like this:
+
+> Verifier report 1, finding 2 (`V1/F2`): the title returns to "Draft" after saving "Ready" and reopening the item.
+> Acceptance criterion 1 (`AC1`) requires the saved title to remain "Ready".
+
+In this example, the finding's `acceptanceCriterion: "AC1"` connects the issue to criterion `AC1` in `spec.md`.
+
+The owner discusses the issue with Maestro. Maestro records the decision in the same verifier report. See [Findings](workflow.md#findings) for the available choices and their effects.

package/docs/subagent-integration.md

@@ -23,7 +23,7 @@ Runs stay in the foreground and occur one at a time. Pi waits for each run to fi
 
 Maestro's Pi status shows the workflow phase. `pi-subagents` FleetView shows agent activity, and `/subagents-fleet` opens its inspector for details and transcripts.
 
-Each child saves its result through Maestro tools before returning.
+Each child saves its result through Maestro tools before returning. Builder results produce `B1.json`, `B2.json`, and so on. Verifier results produce `V1.json`, `V2.json`, and so on. See [Stored artifacts](workflow.md#stored-artifacts) for the creation sequence.
 
 If a run fails or returns without a valid saved result, Maestro reports the error and stops. Manual follow-up is described in [Limitations](workflow.md#limitations).
 

package/docs/workflow.md

@@ -4,15 +4,12 @@ Maestro manages one spec-driven workflow in the current Pi session. The owner wo
 
 The approved `spec.md` is the contract for the change. It defines behavior, scope, constraints, technical decisions, and acceptance criteria.
 
-An acceptance criterion contains a probe, an expected result and an example. The probe checks an acceptance criterion against its expected result. 
+An acceptance criterion contains a probe, an expected result, and an example. A probe is a scenario used to test behavior.
 
-An agent run result is a handoff.
-The handoff can contain:
-- Escalations: the owner have to decide implementation questions.
-- Findings: technical issues on the implementation
-- Evidences: work executed by agents
+A handoff is a saved report from a builder or verifier run. It records the result, probe outcomes, and notes.
 
-The workflow uses files in the [project root](configuration.md#project-root).
+A builder handoff can contain escalations, which are questions that need owner decisions. 
+A verifier handoff can contain findings, which are technical issues.
 
 ## Roles
 
@@ -50,8 +47,8 @@ flowchart TD
     verify --> findings
     findings -->|None| candidate
 
-    buildOutcome -->|Escalation| ownerEscalation{Owner decides}
-    ownerEscalation -->|Contract unchanged| recordEscalation[Maestro records the answer]
+    buildOutcome -->|Escalation| ownerEscalation{Owner decides every question}
+    ownerEscalation -->|Contract unchanged| recordEscalation[Maestro records all answers]
     recordEscalation --> build
     ownerEscalation -->|Contract changes| reviseSpec[Owner and Maestro revise the spec]
     reviseSpec --> approval
@@ -81,7 +78,7 @@ The default path is `.specs/<spec-id>/workflow.json`. The spec directory is [con
 | `drafting-spec` | The owner and Maestro are preparing the initial spec. |
 | `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 the current escalation. |
+| `escalation-decision` | The owner must decide how to handle every escalation question. |
 | `builder-failed` | The builder recorded a technical failure. The workflow stops. |
 | `ready-for-verifier` | The builder completed the work and the verifier can start. |
 | `verifier-running` | A verifier run is active. |
@@ -101,7 +98,9 @@ Approval freezes the spec as the contract. The spec and its visual prototypes re
 
 ## Acceptance criteria
 
-Each acceptance criterion has a unique ID and describes one observable result. It contains these parts:
+Each acceptance criterion has a unique ID and describes one observable result.
+
+Each criterion contains these parts:
 
 | Part | Content |
 |---|---|
@@ -113,19 +112,27 @@ Each acceptance criterion has a unique ID and describes one observable result. I
 
 An escalation returns an implementation decision to the owner. It does not necessarily mean that a technical failure occurred. Examples include undefined behavior, a conflict with the spec, or a possible scope change.
 
-Maestro presents the question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decision` until the owner decides.
+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.
+
+If the contract 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.
 
 | Owner choice | Result |
 |---|---|
-| Keep the current contract | Maestro records the answer and reason, returns to `ready-for-builder`, and starts another builder run. |
+| Keep the current contract | Maestro saves all answers and reasons together in the active builder handoff, returns to `ready-for-builder`, and starts another builder run. |
 | Change the contract | The owner and Maestro revise the same spec and obtain renewed approval before another builder run. |
 
-The escalation file remains available as history.
+Owner decisions update only the questions' `resolution` fields. The handoff's other content and earlier handoffs remain unchanged.
 
 ## Findings
 
 Every current finding requires an owner decision, regardless of severity. Maestro explains the issue, evidence, practical effect, and available choices.
 
+Maestro identifies each finding with its report and finding IDs. For example, `V1/F2` means finding 2 in verifier report `V1.json`. The finding is an entry in that file's `findings` list, not a separate `F2.json` file. Finding numbers restart at `F1` in each verifier report. See [Finding references](glossary.md#finding-references) for a worked example.
+
+Maestro records owner decisions in the same verifier report, e.g. decisions about `V1/F2` update `V1.json`, not a new `V2.json`. A new verifier result creates the next report (`V2.json`).
+
 | Decision | Result |
 |---|---|
 | `reject` | Records the owner's reason. If every finding is rejected, the workflow reaches `candidate-ready`. |
@@ -141,7 +148,7 @@ Contract revisions are allowed only in `escalation-decision` or `findings-decisi
 
 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.
 
-Previous escalations, findings, and handoffs remain as historical context. The revised spec is the contract for subsequent work.
+Previous escalations, findings, and handoffs remain as historical context. The new (revised) spec is the contract for subsequent work.
 
 ## Verification boundary
 
@@ -157,7 +164,27 @@ The owner performs the final review and controls any later Git use, pull request
 
 ## Stored artifacts
 
-Maestro creates the spec directory with `spec.md`, `workflow.json`, and empty `handoffs/escalations/` and `prototypes/` directories. Builder and verifier handoff directories appear when those results are saved.
+An artifact is a saved workflow file. Maestro creates the spec directory with `spec.md`, `workflow.json`, and an empty `prototypes/` directory. Builder and verifier handoff directories appear when those results are saved.
+
+The agents submit results through Maestro tools instead of writing the reports directly. A successful submission saves the result and updates the phase in `workflow.json` before the agent returns.
+
+Builder (`B`) and verifier (`V`) numbers count saved handoffs within one spec. Each sequence starts at 1 and advances independently. Every saved builder outcome, including escalation, creates the next `B` report. Revising the same spec keeps these sequences. A new spec starts new sequences.
+
+Escalation (`E`) numbers identify questions within a builder handoff. They restart at `E1` in each handoff.
+
+For example, a repair cycle with successful builder results produces these files:
+
+| Step | Action | Report saved or updated |
+|---|---|---|
+| 1 | The builder completes the implementation. | Creates `handoffs/builder/B1.json`. |
+| 2 | The verifier checks it and reports findings. | Creates `handoffs/verifier/V1.json`. |
+| 3 | The owner decides every finding and requests a code fix. | Updates decisions in the existing `V1.json`. |
+| 4 | A new builder run completes the fixes. | Creates `handoffs/builder/B2.json`. |
+| 5 | A new verifier run checks the work again and reports no findings. | Creates `handoffs/verifier/V2.json`. The workflow reaches `candidate-ready`. |
+
+If the first builder run escalates, it creates `B1.json` with its questions. Owner answers update `B1.json`. The next saved builder result creates `B2.json`.
+
+A builder report with `status: failed` stops the workflow without a verifier run. If an agent returns without a valid saved result, Maestro stops and reports the error. See [Limitations](#limitations).
 
 The default layout after multiple runs is:
 
@@ -169,19 +196,24 @@ The default layout after multiple runs is:
 │   ├── builder/
 │   │   ├── B1.json
 │   │   └── B2.json
-│   ├── verifier/
-│   │   ├── V1.json
-│   │   └── V2.json
-│   └── escalations/
-│       ├── E1.json
-│       └── ...
+│   └── verifier/
+│       ├── V1.json
+│       └── V2.json
 └── prototypes/
 ```
 
-Each new handoff gets the next number in its role's sequence. Maestro uses the latest handoff in each sequence as the active result, and earlier handoffs remain on the file system as references.
+Maestro uses the latest saved handoff in each role's sequence as the active result. New results do not replace earlier numbered reports. Earlier reports remain available as context, not as proof for the current run. Owner decisions update the active builder or verifier handoff without creating another numbered report.
 
 ## Limitations
 
+### No small models
+The owner must not use small models with a `low` thinking level for this workflow. These combinations cannot reliably follow the workflow rules. 
+One example is `gpt-luna-6` with `thinking: "low"`.
+
+Moreover, the workflow works well with a defined harness: tests, lint for code rules, anti-slop checks for unwanted patterns, and `AGENTS.md`. Maestro does not supply these project-specific checks.
+
+### No automatic rollback
 Maestro provides no automatic rollback, repair, or recovery for failed or interrupted workflows. The files that remain are available for owner inspection. The owner handles the workflow manually.
 
+### No reconciliation
 Disabling Maestro, restarting Pi, or using `/resume` clears live Maestro session state and leaves project files unchanged. Maestro starts disabled in a new or resumed session. Reactivating it does not reconstruct or resume a saved workflow.

package/extensions/maestro-subagent.ts

@@ -4,12 +4,10 @@
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { registerOpenEscalationTool } from '#tools/child/open-escalation.ts';
 import { registerRecordBuilderHandoffTool } from '#tools/child/record-builder-handoff.ts';
 import { registerRecordVerifierHandoffTool } from '#tools/child/record-verifier-handoff.ts';
 
 export default (pi: ExtensionAPI): void => {
-  registerOpenEscalationTool(pi);
   registerRecordBuilderHandoffTool(pi);
   registerRecordVerifierHandoffTool(pi);
 };

package/extensions/maestro.ts

@@ -18,9 +18,9 @@ import {
   registerMarkSpecReadyTool,
 } from '#tools/main/mark-spec-ready.ts';
 import {
-  RESOLVE_ESCALATION_TOOL,
-  registerResolveEscalationTool,
-} from '#tools/main/resolve-escalation.ts';
+  RESOLVE_ESCALATIONS_TOOL,
+  registerResolveEscalationsTool,
+} from '#tools/main/resolve-escalations.ts';
 import {
   RESOLVE_FINDINGS_TOOL,
   registerResolveFindingsTool,
@@ -38,7 +38,7 @@ const MAIN_TOOL_NAMES: readonly string[] = [
   CREATE_SPEC_TOOL.NAME,
   MARK_SPEC_READY_TOOL.NAME,
   RUN_BUILDER_TOOL.NAME,
-  RESOLVE_ESCALATION_TOOL.NAME,
+  RESOLVE_ESCALATIONS_TOOL.NAME,
   RUN_VERIFIER_TOOL.NAME,
   RESOLVE_FINDINGS_TOOL.NAME,
 ];
@@ -47,7 +47,7 @@ export default (pi: ExtensionAPI): void => {
   registerCreateSpecTool(pi);
   registerMarkSpecReadyTool(pi);
   registerRunBuilderTool(pi);
-  registerResolveEscalationTool(pi);
+  registerResolveEscalationsTool(pi);
   registerRunVerifierTool(pi);
   registerResolveFindingsTool(pi);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",
@@ -50,9 +50,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "npm run test:unit && npm run test:integration",
-    "test:unit": "vitest run --exclude \"**/*.integration.test.ts\"",
-    "test:integration": "vitest run --exclude \"**/*.unit.test.ts\"",
+    "test": "vitest run --coverage --config vitest.config.ts",
     "check": "npm run lint:fix && npm run typecheck && npm test",
     "prepublishOnly": "npm run check",
     "publish:npm": "npm publish --access public",
@@ -75,6 +73,7 @@
     "@biomejs/biome": "2.5.15",
     "@earendil-works/pi-agent-core": "1.0.3",
     "@earendil-works/pi-tui": "1.0.3",
+    "@vitest/coverage-v8": "5.0.3",
     "@types/node": "26.6.4",
     "oxlint": "1.87.0",
     "oxlint-anti-slop": "0.3.3",

package/src/MaestroPaths.ts

@@ -15,7 +15,6 @@ const PATHS = {
   HANDOFFS_PATH: 'handoffs',
   BUILDER_HANDOFFS_PATH: 'handoffs/builder',
   VERIFIER_HANDOFFS_PATH: 'handoffs/verifier',
-  ESCALATIONS_PATH: 'handoffs/escalations',
   PROTOTYPES_PATH: 'prototypes',
 } as const;
 
@@ -55,11 +54,6 @@ export type MaestroPathsInput = {
   config: MaestroConfig;
 };
 
-type EscalationPathInput = {
-  specId: string;
-  escalationNumber: number;
-};
-
 type HandoffPathInput = {
   specId: string;
   handoffPassNumber: number;
@@ -213,32 +207,6 @@ export class MaestroPaths {
     });
   }
 
-  public getEscalationsPath(specId: string): string {
-    assertSpecId(specId);
-
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.ESCALATIONS_PATH,
-    );
-  }
-
-  public getEscalationPath({
-    specId,
-    escalationNumber,
-  }: EscalationPathInput): string {
-    assertArtifactNumber(escalationNumber);
-    assertSpecId(specId);
-
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      `${PATHS.ESCALATIONS_PATH}/E${escalationNumber}.json`,
-    );
-  }
-
   public getPrototypesPath(specId: string): string {
     assertSpecId(specId);
 

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

@@ -80,6 +80,35 @@ export function assertBuilderHandoff(
     );
   }
 
+  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.');
+      }
+    }
+  }
+
   if (!isValidSpecId(specId)) {
     throw new Error(`Invalid expected builder handoff spec ID: "${specId}".`);
   }