@emiliosp/pi-maestro 0.7.4 → 0.9.0

package/ADR.md

@@ -0,0 +1,89 @@
+# Architecture decision records
+
+An Architecture Decision Record (ADR) explains an important architectural choice, its context, and its consequences. 
+This file contains one numbered record per decision. 
+
+Requirements and routine project rules belong in the [roadmap](ROADMAP.md) or other relevant documentation.
+
+When a new decision replaces an accepted decision, add a new record, mark the earlier record as superseded, and link both records.
+
+## ADR-001: Keep the workflow independent of Git
+
+### Status
+
+Accepted. Recorded date: 2026-10-07. Implemented in `0.6.0`.
+
+### Context
+
+The previous workflow required Git and used checkpoints and automatic commits. The recorded reason for removing that approach was to simplify the project. Other evaluated alternatives were not recorded.
+
+### Decision
+
+`Maestro` uses the Pi project directory and saved workflow phase. It does not require Git or create automatic commits.
+
+The `verifier` checks live project files. The `owner` controls later Git use, pull requests, and merging.
+
+### Consequences
+
+Workflow execution no longer depends on Git. Revision and commit fields were removed without migration or compatibility readers. Interrupted and older workflows require manual `owner` handling.
+
+### Evidence
+
+[Commit deae41c](https://github.com/emilioSp/pi-maestro/commit/deae41ce66a3f2c76859209c44165e7ddd0f3a72), [Changelog 0.6.0](CHANGELOG.md#060), and [workflow completion](docs/workflow.md#workflow-completion).
+
+## ADR-002: Store escalation decisions in builder handoffs
+
+### Status
+
+Accepted. Recorded date: 2026-10-08. Implemented in `0.7.0`.
+
+### Context
+
+The previous approach stored `escalations` in standalone files and used singular resolution tools. The recorded reason for replacing it was to use the same storage, local ID, and batch decision model as `verifier` `findings`. Other evaluated alternatives were not recorded.
+
+### Decision
+
+Numbered `builder` `handoffs` contain `escalation` questions and their `owner` resolutions. One call records all current answers. No parallel storage model is needed.
+
+IDs restart at `E1` in each `handoff`. References include both IDs, such as `B1/E1`. Answers update only the active handoff's resolution fields.
+
+### Consequences
+
+Standalone `escalation` storage and singular resolution tools were removed. Questions and decisions remain together in each numbered `builder` `handoff`.
+
+There are no migration procedures, fallback readers, or deprecated aliases. `Artifact` versions remain `1.0.0` despite the breaking change.
+
+### Evidence
+
+[Repository-only specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md), [Commit dda6eb5](https://github.com/emilioSp/pi-maestro/commit/dda6eb5b3ab76ba175112c3c565c70be747d7344), and [escalation workflow](docs/workflow.md#escalations).
+
+## ADR-003: Route builder failures through owner escalations
+
+### Status
+
+Accepted. Implemented.
+
+### Context
+
+The `owner` must decide how work continues after a reportable technical problem.
+The workflow also needs a simpler model with two `builder` outcomes.
+
+### Decision
+
+The `builder` reports only `done` or `escalation`.
+Reportable technical failures use the existing `escalation` process.
+The `owner` decides how to proceed instead of reaching a terminal failure phase.
+
+### Consequences
+
+Reuse the existing tools, numbered `handoffs`, and batch decisions.
+Individual `probe` results retain `failed` as a valid value.
+
+Execution and protocol errors without a valid saved result still stop the workflow.
+This decision adds no automatic recovery.
+
+This breaking MVP change has no migrations, compatibility readers, deprecated aliases, or dedicated legacy-format tests.
+
+### Evidence
+
+[Specification](.specs/20261013-101454-route-builder-failures-through-owner-escalations/spec.md) and [R-03](ROADMAP.md#r-03-route-builder-failures-through-owner-escalations).

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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. Breaking: `builder` reports now support only `done` and `escalation`. Reportable technical problems use the existing `owner` `escalation` process.
+2. Removed the terminal `builder` failure phase and event. Execution errors and missing or invalid saved results still stop the workflow without automatic recovery.
+3. No migrations, compatibility readers, or deprecated aliases are provided. `Artifact` versions remain `1.0.0`.
+
 ## 0.7.3
 
 1. Added Oxlint rules for `given ... when ... then ...` test titles, `const` usage, unnecessary `else` branches, type aliases, and ESM imports. See [PR #31](https://github.com/emilioSp/pi-maestro/pull/31).

package/README.md

@@ -83,7 +83,8 @@ If a `spec` change is needed during an `escalation` or `finding` decision, the `
 
 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.
 
-The same `/maestro` command disables `Maestro` and leaves project files unchanged. Disabling `Maestro`, restarting Pi, or using `/resume` clears live session state. Saved files do not automatically restore or resume an incomplete workflow. The `owner` handles it manually.
+The same `/maestro` command disables `Maestro` and leaves project files unchanged. Disabling `Maestro`, restarting Pi, or using `/resume` clears live session state. 
+Saved files do not automatically restore or resume an incomplete workflow. The `owner` handles it manually.
 
 ## Configuration
 
@@ -104,4 +105,4 @@ The reading order is:
 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 changes.
-5. [Design decisions](DESIGN_DECISIONS.md): recorded choices, reasons, alternatives, and constraints.
+5. [Architecture decision records](ADR.md): architectural choices, context, consequences, and evidence.

package/ROADMAP.md

@@ -10,35 +10,53 @@ Item identifiers remain stable when priorities change. The `owner` approves chan
 
 ### 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`.
+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).
+#### 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`.
+Numbered `builder` `handoffs` contain multiple `escalation` questions and their `owner` resolutions. The `owner` resolves all current questions in one batch. Earlier `handoffs` remain available as history. All 10 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
+
+#### Evidence
 
-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).
+[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).
 
 ### R-12: Format glossary terms consistently
 
 Applied glossary formatting across the documentation and recorded its exclusions in `AGENTS.md` and the documentation audit skill. The approved change document uses the term `spec`. The `owner` confirmed completion.
 
-Evidence: [Glossary](docs/glossary.md) and [workflow documentation](docs/workflow.md).
+#### Evidence
 
-## Now
+[Glossary](docs/glossary.md) and [workflow documentation](docs/workflow.md).
 
-No current priority is selected.
+### R-15: Rename the test support directory
 
-## Next
+Renamed `test/` to `tests/` at the owner's request. Updated imports, fixture paths, lint configuration, and project instructions. This follows the global instruction to keep fixtures under `tests/fixtures`. Source tests remain next to their source files. Historical `handoffs` retain their recorded paths.
+
+#### Evidence
+
+[Test support](tests/support/), [fixtures](tests/fixtures/), [lint configuration](biome.json), and [project instructions](AGENTS.md#tests).
+
+## 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.
+#### Objective
+
+The `builder` reports technical problems that prevent completion through the existing `escalation` process. The `owner` decides how to proceed.
+
+The approved [specification](.specs/20261013-101454-route-builder-failures-through-owner-escalations/spec.md) is implemented.
+Automatic recovery of interrupted `runs` remains outside this item.
 
-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.
+#### Completed 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 describe the same behavior.
+
+## Next
 
-Automatic recovery of interrupted `runs` is outside this item. No `specification` is approved yet.
 
 ## Later
 
@@ -46,44 +64,120 @@ These items need scope review before `specification` approval. Existing behavior
 
 ### R-04: Rename the npm package
 
+#### Objective
+
 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.
+Compatibility with installations under the old name must be decided in the `specification`. No `specification` is approved yet.
+
+#### Completed when
+
+Package metadata and installation documentation use the new name. The package is available under that name.
 
 ### 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.
+#### Objective
+
+When criteria are removed during `spec` preparation or revision, renumber the remaining criteria without gaps. Numbering starts at `AC1` and continues through the final criterion.
+
+#### Completed 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 requirements, so first identify any missing extension checks. Complete when unavailable required subagent extensions prevent activation and the error identifies the problem.
+#### Objective
+
+Make extension availability problems visible before a `builder` or `verifier` `run` starts. Activation already checks agent launch requirements, so first identify any missing extension checks.
+
+#### Completed when
+
+Unavailable required subagent extensions prevent activation. 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.
+#### Objective
+
+Help the `owner` create `Maestro` configuration through an interview. `Maestro` asks questions and writes the agreed configuration.
+
+#### Completed 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.
+#### Objective
+
+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`.
+
+#### Completed when
+
+The `owner` can select available models in those phases. `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.
+#### Objective
+
+Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The recovery scope is not yet defined.
+
+#### Completed when
+
+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
 
+#### 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.
 
-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: ...`.
+The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
+
+#### Completed when
+
+Both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase.
 
 ### R-11: Reduce temporary verifier changes
 
+#### Objective
+
 Reduce the risk that verification changes the `candidate`. Existing instructions already require exact restoration, cleanup, and reporting of unresolved restoration problems. Refine the remaining guidance rather than duplicate those rules.
 
-Prefer checks that leave existing files unchanged and use separate temporary files when possible. Change an existing file only when a criterion requires it, retain its exact contents, and restore it immediately after each `probe`, including failed `probes`. Prefer check-only commands over commands that apply automatic fixes.
+Prefer checks that leave existing files unchanged and use separate temporary files when possible. Change an existing file only when a criterion requires it. Retain its exact contents and restore it immediately after each `probe`, including failed `probes`. Prefer check-only commands over commands that apply automatic fixes.
+
+`Maestro` currently has no file-hash restoration check. Adding one requires a separate scope decision.
 
-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.
+#### Completed when
+
+`Verifier` instructions cover these limits and require restoration and temporary-file cleanup before `handoff`. If restoration fails, the `verifier` must stop and report affected paths and remaining changes.
 
 ### R-13: Show when Maestro is working
 
-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.
+#### Objective
+
+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.
+
+#### Completed when
+
+The status clearly distinguishes work in progress from a request for `owner` action.
+
+### R-14: Introduce Maestro at activation
+
+#### Objective
+
+When activated, `Maestro` gives a brief introduction and invites the `owner` to ask how it works, if interested. `Maestro` must have access to its own documentation to answer those questions.
+
+#### Completed when
+
+Activation includes this short introduction. `Maestro` can consult its documentation.
+
+### R-16: Verify code quality against AGENTS.md instructions
+
+#### Objective
+
+Add code-quality review against applicable `AGENTS.md` instructions as another `verifier` responsibility. Keep all existing responsibilities unchanged, including independent verification of every `acceptance criterion` in the approved `spec`. Code-quality review supplements that verification. It does not replace or reduce it.
+
+Existing `verifier` instructions already require reading applicable `AGENTS.md` files and following technical rules. Extend that guidance to require explicit code-quality review and reporting of instruction violations. Do not introduce personal style preferences as requirements.
+
+#### Completed when
+
+The `verifier` performs both its existing verification duties and the additional code-quality review. Every `acceptance criterion` is still independently verified. Each code-quality `finding` about an instruction violation identifies the `AGENTS.md` file, quotes the violated instruction, and explains how the code violates it.

package/agents/builder.md

@@ -45,6 +45,7 @@ Follow applicable repository commands and technical rules. Inspect scripts befor
 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 technical problem prevents completion and you can safely report it, stop implementation and submit an escalation. Use its fields for the reason, evidence, owner question, options, consequences, and next steps. The owner decides how work continues.
 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.
 An escalation does not require a technical failure or blocker.
@@ -75,8 +76,7 @@ Before any terminal tool call, restore temporary verification changes and remove
 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`, `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.
+2. `escalation`: An owner decision is required, including when a reportable technical problem prevents completion. 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 or another required repository check prevents completion. Save one handoff and stop.
 
 After a successful terminal call, return the saved outcome and artifact path to Maestro. Stop the pass.
 Do not delete or replace earlier handoffs. Do not continue implementation after saving the result.
@@ -88,8 +88,6 @@ If a terminal call fails, inspect the error, current phase, and artifacts before
 If validation rejected the submission without writing it, correct the payload to match the tool schema and actual evidence.
 If the tool partially wrote an artifact or changed phase before an error, report it and stop. Do not resubmit.
 Never change honest statuses or omit criteria merely to make a payload pass validation.
-The tool rejects `failed` when a nonempty criterion list contains only `passed` probes.
-If another technical failure prevents completion in that case, report this protocol limitation to Maestro instead of falsifying criterion results.
 Do not delete a terminal artifact, edit workflow state, or use a different outcome to bypass an error.
 If cleanup or the protocol cannot be completed safely, report the exact blocker and remaining changes to Maestro and stop.
 Do not claim a saved result when the terminal call did not succeed.

package/docs/glossary.md

@@ -14,10 +14,11 @@
 | `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. |
+| `Observability` | The owner's ability to inspect workflow progress and reported results. |
 | `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. |
+| `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`. |
 | `reject` | An `owner` decision that declines a `finding` and records a reason. It does not mean that verification passed. |

package/docs/workflow.md

@@ -17,12 +17,25 @@ A `verifier` `handoff` can contain `findings`, which are technical issues.
 |---|---|
 | `Owner` | Decides requirements, scope, technical decisions, `spec` approval, `escalation` answers, and `finding` decisions. Performs the final review. |
 | `Maestro` | Prepares the `spec` with the `owner`, records workflow progress, runs agents, presents issues, and saves `owner` decisions. |
-| `Builder` | Implements the approved `spec` and runs every `probe`. Reports completion, an `escalation`, or a technical failure. |
+| `Builder` | Implements the approved `spec` and runs every `probe`. Reports completion or an `escalation`, including technical problems that prevent completion. |
 | `Verifier` | Independently runs every `probe` against the live project files. Reports `findings` without repairing product code. |
 
 `Builder` and `verifier` `runs` are sequential foreground operations. Each starts with a fresh conversation and reads the `spec` and saved `artifacts`.
 
-Maestro's Pi status shows the current phase. `pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
+## Observability
+
+`Observability` is the owner's ability to inspect workflow progress and reported results. 
+
+Maestro's Pi status shows the current phase. 
+
+`pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
+
+Saved `handoffs` provide a structured account of each reported `run`.
+The `builder` reports its outcome, `probe` results, notes, and any `escalation` questions. 
+The `verifier` reports its independent checks, results, and `findings`. 
+Recorded `owner` decisions explain how questions and issues were resolved. Earlier numbered reports remain available for inspection.
+
+For example, the `owner` can read `B1.json` to see what the `builder` reports implementing and which `probes` it ran. `V1.json` shows what the `verifier` reports checking independently and which issues it found.
 
 ## Main flow
 
@@ -53,8 +66,6 @@ flowchart TD
     ownerEscalation -->|Spec changes| reviseSpec[Owner and Maestro revise the spec]
     reviseSpec --> approval
 
-    buildOutcome -->|Failed| stopped[Workflow stops for manual owner follow-up]
-
     findings -->|One or more| ownerFindings[Owner decides every finding]
     ownerFindings -->|Reject all with reasons| candidate
     ownerFindings -->|Fix code| recordFixes[Maestro records the decisions]
@@ -64,7 +75,7 @@ flowchart TD
     candidate --> summary
     summary --> review
 
-    linkStyle 0,1,2,3,4,5,17,18 stroke:#2e7d32,stroke-width:3px
+    linkStyle 0,1,2,3,4,5,16,17 stroke:#2e7d32,stroke-width:3px
 ```
 
 ## Workflow phases
@@ -79,7 +90,6 @@ The default path is `.specs/<spec-id>/workflow.json`. The `spec` directory is [c
 | `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. |
-| `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. |
 | `findings-decision` | The `owner` must decide how to handle every current `finding`. |
@@ -110,7 +120,8 @@ Each criterion contains these parts:
 
 ## Escalations
 
-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.
+An `escalation` returns an implementation decision or a technical problem to the `owner`. 
+For instance a technical failure, an undefined behavior, a conflict with the `spec`, or a possible scope change.
 
 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.
 
@@ -184,7 +195,10 @@ For example, a repair cycle with successful `builder` results produces these fil
 
 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).
+A `builder` report has `status: done` or `status: escalation`. A `done` report requires every recorded `probe` to pass and an empty `escalations` list.
+An `escalation` retains actual `probe` results: `passed`, `failed`, or `not-run`. 
+
+Execution errors or missing or invalid saved results stop the workflow. See [Limitations](#limitations).
 
 The default layout after multiple `runs` is:
 
@@ -213,7 +227,9 @@ 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.
+Launch errors, delegation failures, timeouts, interruptions, cancellations, and missing or invalid `handoffs` stop the workflow without a recovery transition.
+If a `run` saves no completed transition, its saved running phase remains unchanged. Partial protocol writes require manual `owner` follow-up.
+`Maestro` provides no automatic rollback, repair, or recovery for these errors. The files that remain are available for `owner` inspection.
 
 ### 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.