@emiliosp/pi-maestro 0.6.3 → 0.7.1

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,16 @@ 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.
+
+## Project constitution
+
+1. [Mission](mission.md): purpose, scope, and owner responsibilities.
+2. [Tech stack](tech-stack.md): runtime technologies and development tools.
+3. [Roadmap](roadmap.md): completed outcomes and planned priorities.
+4. [Changelog](changelog.md): meaningful codebase changes and breaking contracts.

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/changelog.md

@@ -0,0 +1,85 @@
+# Changelog
+
+This file summarizes meaningful changes to the codebase, including behavior, contracts, architecture, and development tools. Git tags identify version boundaries; GitHub Releases are not required. Version-only changes and routine maintenance are omitted.
+
+## 0.7.1
+
+1. Documented the project mission, current tech stack, owner responsibilities, roadmap, and codebase change history. See [PR #30](https://github.com/emilioSp/pi-maestro/pull/30).
+2. Replaced `TODO.md` with the roadmap and included the four project constitution documents in the npm package.
+3. Updated documentation audits to compare all current documentation and the project constitution with the working tree without requesting a comparison baseline.
+
+## 0.7.0
+
+1. Stored multiple escalation questions and owner resolutions inside numbered builder handoffs. Earlier handoffs remain available as history. See [PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
+2. Breaking: replaced `maestro_open_escalation` and `maestro_resolve_escalation` with `maestro_record_builder_handoff` and `maestro_resolve_escalations`. Done handoffs require `escalations: []`. Standalone escalation storage was removed without migration or compatibility readers. Artifact versions remain `1.0.0`.
+3. Added LCOV coverage reports and Codecov uploads from CI. See [PR #28](https://github.com/emilioSp/pi-maestro/pull/28).
+
+Reload Maestro extensions before starting new workflows so sessions use the new tool contracts.
+
+## 0.6.2
+
+Added phase icons, theme colors, and display-only shortening of long spec IDs. Successful activation shows the configured agent settings in a UI-only notice, outside session history and model context. See [PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
+
+## 0.6.0
+
+1. Removed Git requirements, checkpoints, and automatic commits from the workflow. Maestro uses Pi's project directory and saved workflow phase. See [PR #25](https://github.com/emilioSp/pi-maestro/pull/25).
+2. Retained numbered builder and verifier handoffs and explicit owner finding decisions. Removed workflow revision counters and writer locks.
+3. Breaking: changed artifact contracts, handoff paths, and tool results without migration or compatibility readers. Removed revision and commit fields. Artifact versions remain `1.0.0`. Interrupted and older workflows require manual owner handling.
+
+## 0.5.2
+
+Reverted the spec question-dependency instructions introduced in `0.5.1`. See [commit 13cad11](https://github.com/emilioSp/pi-maestro/commit/13cad11).
+
+## 0.5.1
+
+Added instructions to resolve prerequisite decisions before asking dependent spec questions and to review unresolved decisions before approval. These instructions were reverted in `0.5.2`.
+
+## 0.5.0
+
+Removed breakage checks from specs, handoffs, validation, and agent instructions. Breakage checks temporarily introduced faults to test error detection. Acceptance criteria retain probes, expected results, and concrete examples. See [PR #24](https://github.com/emilioSp/pi-maestro/pull/24).
+
+Breaking: handoffs no longer accept `breakageStatus`. Older handoffs containing that field must be regenerated. Artifact versions remain `1.0.0`.
+
+## 0.4.5
+
+Required a concrete example in every acceptance criterion, both in the spec and when presenting it to the owner. Examples identify starting conditions, an action, and the expected observable result.
+
+## 0.4.4
+
+Expanded Maestro's explanations of findings and escalations with code evidence, concrete examples, available choices, and their consequences. The owner retains control of each decision.
+
+## 0.4.3
+
+Removed explicit builder and verifier tool allowlists and enabled inherited skills. Workflow boundaries remain defined by agent instructions.
+
+## 0.4.2
+
+Made breakage checks optional when the approved spec did not require them. Required acceptance probes remained mandatory. Breakage checks were later removed in `0.5.0`. See [PR #23](https://github.com/emilioSp/pi-maestro/pull/23).
+
+## 0.4.1
+
+Enabled inheritance of global instructions for builder and verifier agents, alongside project context.
+
+## 0.4.0
+
+1. Fixed delegated handoffs that depended on unavailable parent session memory. See [PR #22](https://github.com/emilioSp/pi-maestro/pull/22).
+2. Removed hash-based spec guards and checkpoint-based verifier comparisons. Spec preservation and restoration rely on agent instructions.
+3. Refreshed the running status before delegation and required repository investigation before presenting technical decisions during spec preparation.
+
+## 0.3.0
+
+Clarified Maestro, builder, and verifier responsibilities, spec and prototype revisions, permitted experiments, evidence requirements, and cleanup. See [PR #21](https://github.com/emilioSp/pi-maestro/pull/21).
+
+## 0.2.0
+
+Moved TypeBox to peer dependencies and loosened Pi peer dependency version constraints. Kept `pi-subagents` bundled with the package.
+
+## 0.1.2
+
+Pinned verifier comparisons to a fixed candidate checkpoint rather than the current HEAD's parent. This checkpoint mechanism was later removed in `0.4.0`. See [PR #20](https://github.com/emilioSp/pi-maestro/pull/20).
+
+Breaking: renamed `maestro_launch_builder` and `maestro_launch_verifier` to `maestro_run_builder` and `maestro_run_verifier`. Renamed the corresponding workflow events from `launch-*` to `run-*`.
+
+## 0.1.1
+
+First tagged baseline with `/maestro`, spec creation and approval, and foreground builder and verifier runs. The owner decides escalation questions and verifier findings. The workflow ends at `candidate-ready`, leaving final review to the owner. See [PR #14](https://github.com/emilioSp/pi-maestro/pull/14) and [PR #13](https://github.com/emilioSp/pi-maestro/pull/13).

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/mission.md

@@ -0,0 +1,7 @@
+# Mission
+
+Maestro uses spec-driven development to improve quality when coding with agents. It guides the owner to define requirements and think through a feature before writing code.
+It provides a clear path from an approved spec to verified code and manages agent coordination for the owner.
+
+The owner remains responsible for final code review, pull requests, and merging. The owner also provides and maintains the project's development checks and instructions, including linters, tests, anti-slop checks, and `AGENTS.md`.
+Maestro and its agents use these checks and instructions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",
@@ -33,6 +33,10 @@
     "src/",
     "!**/*.test.ts",
     "docs/",
+    "mission.md",
+    "tech-stack.md",
+    "roadmap.md",
+    "changelog.md",
     "README.md",
     "LICENSE"
   ],
@@ -50,9 +54,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 +77,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/roadmap.md

@@ -0,0 +1,85 @@
+# Roadmap
+
+This roadmap records planned outcomes, not permission to implement them. The owner selects work and approves its specification before implementation starts. Detailed requirements, technical decisions, and acceptance criteria belong in that specification.
+
+"Now" is the current priority. "Next" follows it. “Later” contains uncommitted ideas with no promised order or date.
+
+Item identifiers remain stable when priorities change. The owner approves changes to priorities and scope.
+
+## Completed
+
+### R-01: Improve status presentation and activation feedback
+
+The status bar uses phase icons, theme colors, and shortened spec IDs. Successful activation shows the configured builder and verifier settings without adding the notice to session history or model context. All 12 acceptance criteria passed with no verifier findings; the saved workflow reached `candidate-ready`.
+
+Evidence: [Specification](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/spec.md), [verifier report](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/handoffs/verifier/V1.json), and [merged PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
+
+### R-02: Store escalations and owner decisions in builder handoffs
+
+Numbered builder handoffs contain multiple escalation questions and their owner resolutions. The owner resolves all current questions in one batch, while earlier handoffs remain available as history. All 10 acceptance criteria passed with no verifier findings; the saved workflow reached `candidate-ready`.
+
+Evidence: [Specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md), [verifier report](.specs/20261008-132344-store-escalations-in-builder-handoffs/handoffs/verifier/V1.json), and [merged PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
+
+## Now
+
+### R-03: Route builder failures through owner escalations
+
+A technical builder failure currently ends the workflow in `builder-failed`. Replace the builder's `failed` handoff status and the `builder-failed` workflow phase with an escalation. The owner decides how to proceed through the existing escalation process.
+
+Complete when builder failures produce owner escalations instead of a terminal failure state. Individual checks retain `failed` as a valid result. Agent instructions, tools, workflow transitions, tests, and documentation must describe the same behavior.
+
+Automatic recovery of interrupted runs is outside this item. No specification is approved yet.
+
+## Next
+
+### R-04: Rename the npm package
+
+Rename `@emiliosp/pi-maestro` to `pi-maestro-sdd`. The owner installs the package under the new name. This item changes the package identity, not the development workflow.
+
+Complete when package metadata and installation documentation use the new name and the package is available under it. Compatibility with installations under the old name must be decided in the specification. No specification is approved yet.
+
+## Later
+
+These items need scope review before specification approval. Existing behavior must be checked before adding new code. Dependencies between these items are not yet agreed.
+
+### R-05: Keep acceptance criterion numbering continuous
+
+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. Complete when the spec and its current references use consistent numbering.
+
+### R-06: Check subagent extensions at activation
+
+Make extension availability problems visible before a builder or verifier run starts. Activation already checks agent launch contracts, so first identify any missing extension checks. Complete when unavailable required subagent extensions prevent activation and the error identifies the problem.
+
+### R-07: Guide initial configuration
+
+Help the owner create Maestro configuration through an interview. Maestro asks questions and writes the agreed configuration. Complete when the owner can create a valid project configuration without writing the file manually.
+
+### R-08: Change agent models before a builder run
+
+Let the owner change the builder and verifier models during spec preparation and the `ready-for-builder` phase. The selected models apply to subsequent runs. Complete when the owner can select available models in those phases and Maestro uses the selections.
+
+### R-09: Define workflow reconciliation
+
+Explore how Maestro can reconcile saved artifacts and workflow state. The recovery scope is 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
+
+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.
+
+Complete when both handoff submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase. The specification must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
+
+### R-11: Reduce temporary verifier changes
+
+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.
+
+Complete 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. Maestro currently has no file-hash restoration check; adding one requires a separate scope decision.
+
+### R-12: Format glossary terms consistently
+
+Use inline code formatting for glossary terms throughout the documentation. This lets the owner recognize the same term across documents. Complete when occurrences of glossary terms consistently use formatting such as `candidate-ready`.
+
+### R-13: Show when Maestro is working
+
+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. Complete when the status clearly distinguishes work in progress from a request for owner action.