@emiliosp/pi-maestro 0.8.0 → 0.9.1

package/ADR.md

@@ -56,3 +56,34 @@ There are no migration procedures, fallback readers, or deprecated aliases. `Art
 ### 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,23 @@
 
 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.
 
+## 0.9.1
+
+1. Added a brief introduction and an invitation to ask how `Maestro` works to the successful activation notice. See [PR #33](https://github.com/emilioSp/pi-maestro/pull/33).
+2. Preserved the configured agent details and UI-only activation. Activation does not add session history or start a model request.
+3. Added absolute paths to the installed README and documentation directory in active instructions. `Maestro` reads relevant documentation on demand without automatically loading its contents.
+
+## 0.9.0
+
+1. Breaking: `builder` reports now support only `done` and `escalation`. Reportable technical problems use the existing `owner` `escalation` process. See [PR #32](https://github.com/emilioSp/pi-maestro/pull/32).
+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.8.0
+
+1. Updated the bundled `pi-subagents` dependency from `0.76.0` to `0.78.0`.
+2. Renamed `test/` to `tests/`. Updated imports, fixture paths, lint configuration, and project instructions. Source tests remain next to their source files.
+
 ## 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
 

package/ROADMAP.md

@@ -24,6 +24,16 @@ Numbered `builder` `handoffs` contain multiple `escalation` questions and their
 
 [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-03: Route builder failures through owner escalations
+
+Released in `0.9.0`. The `builder` reports only `done` or `escalation`. Reportable technical problems use the existing `owner` `escalation` process. Individual `probe` results retain `failed`. Execution errors and missing or invalid saved results still stop the workflow without automatic recovery.
+
+All 8 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
+
+#### Evidence
+
+[Specification](.specs/20261013-101454-route-builder-failures-through-owner-escalations/spec.md), [verifier report](.specs/20261013-101454-route-builder-failures-through-owner-escalations/handoffs/verifier/V1.json), and [merged PR #32](https://github.com/emilioSp/pi-maestro/pull/32).
+
 ### 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.
@@ -32,31 +42,30 @@ Applied glossary formatting across the documentation and recorded its exclusions
 
 [Glossary](docs/glossary.md) and [workflow documentation](docs/workflow.md).
 
-### R-15: Rename the test support directory
+### R-14: Introduce Maestro at activation
 
-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.
+Implemented in `0.9.1`. npm publication is pending. Successful activation introduces `Maestro` and invites the `owner` to ask how it works. The UI-only notice retains the configured agent details and does not add session history or start a model request.
 
-#### Evidence
+Active instructions identify absolute paths to the installed README and documentation directory. `Maestro` reads relevant documentation on demand without automatically loading its contents.
 
-[Test support](tests/support/), [fixtures](tests/fixtures/), [lint configuration](biome.json), and [project instructions](AGENTS.md#tests).
+All 6 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
 
-## Now
+#### Evidence
 
-### R-03: Route builder failures through owner escalations
+[Specification](.specs/20261013-171954-introduce-maestro-at-activation/spec.md), [verifier report](.specs/20261013-171954-introduce-maestro-at-activation/handoffs/verifier/V1.json), and [merged PR #33](https://github.com/emilioSp/pi-maestro/pull/33).
 
-#### Objective
+### R-15: Rename the test support directory
 
-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.
+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.
 
-Automatic recovery of interrupted `runs` is outside this item. No `specification` is approved yet.
+#### Evidence
 
-#### Completed when
+[Test support](tests/support/), [fixtures](tests/fixtures/), [lint configuration](biome.json), and [project instructions](AGENTS.md#tests).
 
-`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.
+## Now
 
 ## Next
 
-
 ## 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.
@@ -159,16 +168,6 @@ Show an activity indicator in Pi's status bar while progress does not require an
 
 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

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

@@ -18,7 +18,7 @@
 | `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,7 +17,7 @@ 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`.
@@ -66,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]
@@ -77,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
@@ -92,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`. |
@@ -123,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.
 
@@ -197,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:
 
@@ -226,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.

package/extensions/maestro.ts

@@ -90,10 +90,12 @@ export default (pi: ExtensionAPI): void => {
         syncMainTools();
         await refreshMaestroStatus(context);
 
-        // show builder/verifier model on activation
+        // Introduce Maestro and show configured agents only in the UI.
         context.ui.notify(
           [
             context.ui.theme.fg('muted', 'Maestro active'),
+            'Maestro helps the owner define a spec, then coordinates implementation and independent verification.',
+            'Ask how Maestro works for a short explanation.',
             context.ui.theme.fg(
               'accent',
               `Builder (${config.builder.model} ${config.builder.thinking})`,

package/package.json

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

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

@@ -26,11 +26,6 @@ const hasOnlyPassedProbes = (
     (criterion) => criterion.probeStatus === PROBE_STATUSES.PASSED,
   );
 
-const hasValidFailedChecks = (
-  acceptanceCriteria: BuilderAcceptanceCriterion[],
-): boolean =>
-  acceptanceCriteria.length === 0 || !hasOnlyPassedProbes(acceptanceCriteria);
-
 function assertBuilderHandoffSchema(
   input: unknown,
 ): asserts input is BuilderHandoff {
@@ -71,15 +66,6 @@ export function assertBuilderHandoff(
     throw new Error('Done builder handoff requires every probe to pass.');
   }
 
-  if (
-    handoff.status === BUILDER_HANDOFF_STATUSES.FAILED &&
-    !hasValidFailedChecks(handoff.acceptanceCriteria)
-  ) {
-    throw new Error(
-      'Failed builder handoff cannot mark every acceptance check as completed.',
-    );
-  }
-
   if (handoff.status === BUILDER_HANDOFF_STATUSES.ESCALATION) {
     for (const [index, escalation] of handoff.escalations.entries()) {
       if (escalation.id !== `E${index + 1}`) {

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

@@ -11,7 +11,6 @@ export const BUILDER_HANDOFF_VERSION = '1.0.0';
 
 export const BUILDER_HANDOFF_STATUSES = {
   DONE: 'done',
-  FAILED: 'failed',
   ESCALATION: 'escalation',
 } as const;
 
@@ -41,11 +40,6 @@ export type BuilderAcceptanceCriterion = Static<
   typeof BuilderAcceptanceCriterionSchema
 >;
 
-export const BuilderHandoffFailureSchema = Type.Object(
-  { reason: Type.String({ minLength: 1 }) },
-  { additionalProperties: false },
-);
-
 const BuilderHandoffContentFields = {
   summary: Type.String({ minLength: 1 }),
   acceptanceCriteria: Type.Array(BuilderAcceptanceCriterionSchema),
@@ -134,19 +128,9 @@ export const BuilderEscalationHandoffSchema = Type.Object(
   { additionalProperties: false },
 );
 
-export const BuilderFailedHandoffSchema = Type.Object(
-  {
-    ...BuilderHandoffFields,
-    status: Type.Literal(BUILDER_HANDOFF_STATUSES.FAILED),
-    failure: BuilderHandoffFailureSchema,
-  },
-  { additionalProperties: false },
-);
-
 export const BuilderHandoffSchema = Type.Union([
   BuilderDoneHandoffSchema,
   BuilderEscalationHandoffSchema,
-  BuilderFailedHandoffSchema,
 ]);
 
 export type BuilderHandoff = Static<typeof BuilderHandoffSchema>;
@@ -169,19 +153,9 @@ export const BuilderEscalationHandoffSubmissionSchema = Type.Object(
   { additionalProperties: false },
 );
 
-export const BuilderFailedHandoffSubmissionSchema = Type.Object(
-  {
-    status: Type.Literal(BUILDER_HANDOFF_STATUSES.FAILED),
-    ...BuilderHandoffContentFields,
-    failure: BuilderHandoffFailureSchema,
-  },
-  { additionalProperties: false },
-);
-
 export const BuilderHandoffSubmissionSchema = Type.Union([
   BuilderDoneHandoffSubmissionSchema,
   BuilderEscalationHandoffSubmissionSchema,
-  BuilderFailedHandoffSubmissionSchema,
 ]);
 
 export type BuilderHandoffSubmissionInput = Static<

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -3,6 +3,14 @@
  * Used: When Pi prepares a model request while Maestro is active.
  */
 
+import { fileURLToPath } from 'node:url';
+
+const README_PATH = fileURLToPath(
+  new URL('../../../README.md', import.meta.url),
+);
+
+const DOCS_PATH = fileURLToPath(new URL('../../../docs/', import.meta.url));
+
 const MAESTRO_INSTRUCTIONS = `## Maestro mode
 
 You are Maestro. Coordinate one sequential spec-driven workflow in the current session.
@@ -10,6 +18,14 @@ The owner decides requirements, scope, technical decisions in the spec, spec app
 The builder implements the approved spec. The verifier independently checks the candidate. Do not perform their work yourself.
 The approved spec.md is the contract for all three roles. Do not infer owner approval from an agent's recommendation.
 
+### Maestro documentation
+
+The loaded Maestro package's documentation is separate from the owner's project:
+README.md: ${README_PATH}
+docs/: ${DOCS_PATH}
+Before answering questions about Maestro, use the available file-reading tools to read the relevant documentation on demand.
+Do not automatically load all documentation.
+
 ### Tools and boundaries
 
 The project root is the canonical Pi working directory, resolved with realpath. Do not search ancestor directories.
@@ -83,8 +99,8 @@ Read the returned artifact and follow its outcome:
 
 1. done: The phase is ready-for-verifier. Call maestro_run_verifier with the active specId.
 2. escalation: The phase is escalation-decision. Present all questions from the active builder handoff, with evidence, options, consequences, and next steps.
-3. failed: The phase is builder-failed. Report the failure and stop. There is no builder retry or spec revision from this phase.
 
+Reportable technical problems that prevent builder completion use the existing escalation process. The owner decides how work continues.
 A significant discovery needs an escalation when the owner must choose between meaningful alternatives, even without a technical blocker.
 Do not invent an escalation for routine implementation details. Read significant discoveries without owner decisions from the builder handoff notes.
 
@@ -142,9 +158,11 @@ If a tool fails, inspect its error, workflow.json, and artifacts before taking a
 If the tool wrote no artifacts or transition, correct recoverable errors within your permissions before retrying.
 If it partially updated artifacts or workflow state, report that state and stop. Do not retry a partially completed transition.
 Do not repeat an unchanged failing call, edit protocol files, or fabricate evidence to bypass an error.
+Launch errors, delegation failures, timeouts, interruptions, cancellations, and missing or invalid handoffs stop the workflow. Do not create synthetic escalations or recovery transitions.
 If a run ends without a valid saved result, report the error and stop. Do not repair product files or force a transition.
+If a run saves no completed transition, its saved running phase remains unchanged.
 Disabling Maestro, restarting Pi, or using /resume clears live state. Do not reconstruct or resume an incomplete workflow.
-The owner handles failed or interrupted workflows manually.
+The owner handles execution errors, protocol errors, and interrupted workflows manually.
 
 At candidate-ready, the workflow is complete. No final tool call is required.
 You own the final summary. Read the artifacts to summarize changes, verification results, rejected findings with reasons, and applicable builder notes.

package/src/maestro/status/formatMaestroStatus.ts

@@ -15,7 +15,6 @@ export const WORKFLOW_PHASE_LABELS = {
   [WORKFLOW_PHASES.READY_FOR_BUILDER]: 'Ready for builder',
   [WORKFLOW_PHASES.BUILDER_RUNNING]: 'Builder running',
   [WORKFLOW_PHASES.ESCALATION_DECISION]: 'Owner decision needed: escalation',
-  [WORKFLOW_PHASES.BUILDER_FAILED]: 'Builder failed',
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: 'Ready for verifier',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: 'Verifier running',
   [WORKFLOW_PHASES.FINDINGS_DECISION]: 'Owner decision needed: findings',
@@ -27,7 +26,6 @@ export const WORKFLOW_PHASE_ICONS = {
   [WORKFLOW_PHASES.READY_FOR_BUILDER]: '🚧',
   [WORKFLOW_PHASES.BUILDER_RUNNING]: '🛠️',
   [WORKFLOW_PHASES.ESCALATION_DECISION]: '✋',
-  [WORKFLOW_PHASES.BUILDER_FAILED]: '❌',
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: '📋',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: '🔍',
   [WORKFLOW_PHASES.FINDINGS_DECISION]: '💬',
@@ -39,7 +37,6 @@ export const WORKFLOW_PHASE_COLORS = {
   [WORKFLOW_PHASES.READY_FOR_BUILDER]: 'accent',
   [WORKFLOW_PHASES.BUILDER_RUNNING]: 'accent',
   [WORKFLOW_PHASES.ESCALATION_DECISION]: 'warning',
-  [WORKFLOW_PHASES.BUILDER_FAILED]: 'error',
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: 'accent',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: 'accent',
   [WORKFLOW_PHASES.FINDINGS_DECISION]: 'warning',

package/src/tools/child/record-builder-handoff.ts

@@ -1,6 +1,6 @@
 /**
  * Objective: Register the builder handoff tool for the current project.
- * Used: When the builder reports a done, escalation, or failed result.
+ * Used: When the builder reports a done or escalation result.
  */
 
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
@@ -8,7 +8,6 @@ import { Type } from 'typebox';
 import {
   BuilderDoneHandoffSubmissionSchema,
   BuilderEscalationHandoffSubmissionSchema,
-  BuilderFailedHandoffSubmissionSchema,
 } from '#artifacts/builder-handoff/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import { resolveWorkflowContext } from '#tools/child/utils/resolveWorkflowContext.ts';
@@ -18,7 +17,7 @@ export const BUILDER_HANDOFF_TOOL = {
   NAME: 'maestro_record_builder_handoff',
   LABEL: 'Record Builder Handoff',
   DESCRIPTION:
-    'Record the builder pass as done, escalation, or failed. Put significant discoveries that do not require an owner decision in notes. After success, stop. The tool saves a numbered builder handoff and the workflow phase.',
+    'Record the builder pass as done or escalation. Report technical problems that prevent completion as escalations for owner decisions. Put significant discoveries that do not require an owner decision in notes. After success, stop. The tool saves a numbered builder handoff and the workflow phase.',
 } as const;
 
 const BuilderHandoffToolParameters = Type.Union([
@@ -36,13 +35,6 @@ const BuilderHandoffToolParameters = Type.Union([
     },
     { additionalProperties: false },
   ),
-  Type.Object(
-    {
-      specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-      ...BuilderFailedHandoffSubmissionSchema.properties,
-    },
-    { additionalProperties: false },
-  ),
 ]);
 
 export const registerRecordBuilderHandoffTool = (pi: ExtensionAPI): void => {

package/src/tools/main/resolve-escalations.ts

@@ -11,7 +11,7 @@ import {
 } from '#artifacts/builder-handoff/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
-import { resolveEscalations } from '#workflow/escalation/resolveEscalations.ts';
+import { resolveEscalations } from '#workflow/builder/resolveEscalations.ts';
 
 export const RESOLVE_ESCALATIONS_TOOL = {
   NAME: 'maestro_resolve_escalations',

package/src/tools/main/resolve-findings.ts

@@ -9,8 +9,8 @@ import { Type } from 'typebox';
 import { FINDING_DECISIONS } from '#artifacts/verifier-handoff/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
-import { resolveFindings } from '#workflow/findings/resolveFindings.ts';
 import { WORKFLOW_PHASES } from '#workflow/state/schema.ts';
+import { resolveFindings } from '#workflow/verifier/resolveFindings.ts';
 
 export const RESOLVE_FINDINGS_TOOL = {
   NAME: 'maestro_resolve_findings',

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

@@ -30,7 +30,7 @@ export const RUN_BUILDER_TOOL = {
   NAME: 'maestro_run_builder',
   LABEL: 'Run Builder',
   DESCRIPTION:
-    'Run the builder in the project directory for an owner-approved spec. The builder runs in the foreground and cannot be retried after a recorded failure.',
+    'Run the builder in the project directory for an owner-approved spec. The builder runs in the foreground and returns done or escalation. Owner decisions or renewed spec approval permit another pass after an escalation.',
 } as const;
 
 const RunBuilderToolParameters = Type.Object(
@@ -49,12 +49,6 @@ type BuilderRunResult =
       phase: typeof WORKFLOW_PHASES.READY_FOR_VERIFIER;
       handoff: BuilderHandoff;
     }
-  | {
-      outcome: typeof BUILDER_HANDOFF_STATUSES.FAILED;
-      specId: string;
-      phase: typeof WORKFLOW_PHASES.BUILDER_FAILED;
-      handoff: BuilderHandoff;
-    }
   | {
       outcome: typeof BUILDER_HANDOFF_STATUSES.ESCALATION;
       specId: string;
@@ -88,48 +82,25 @@ const readBuilderResult = async ({
   }
 };
 
-type ReadTerminalBuilderResultInput = {
-  paths: MaestroPaths;
-  specId: string;
-  phase:
-    | typeof WORKFLOW_PHASES.READY_FOR_VERIFIER
-    | typeof WORKFLOW_PHASES.BUILDER_FAILED;
-};
-
-const readTerminalBuilderResult = async ({
+const readDoneBuilderResult = async ({
   paths,
   specId,
-  phase,
-}: ReadTerminalBuilderResultInput): Promise<BuilderRunResult> => {
+}: ReadBuilderResultInput): Promise<BuilderRunResult> => {
   const handoff = await readBuilderHandoff({
     path: await paths.getActiveBuilderHandoffPath(specId),
     specId,
   });
 
-  const expectedStatus =
-    phase === WORKFLOW_PHASES.READY_FOR_VERIFIER
-      ? BUILDER_HANDOFF_STATUSES.DONE
-      : BUILDER_HANDOFF_STATUSES.FAILED;
-
-  if (handoff.status !== expectedStatus) {
+  if (handoff.status !== BUILDER_HANDOFF_STATUSES.DONE) {
     throw new Error(
-      `Builder handoff status does not match workflow phase "${phase}".`,
+      `Builder handoff status does not match workflow phase "${WORKFLOW_PHASES.READY_FOR_VERIFIER}".`,
     );
   }
 
-  if (phase === WORKFLOW_PHASES.READY_FOR_VERIFIER) {
-    return {
-      outcome: BUILDER_HANDOFF_STATUSES.DONE,
-      specId,
-      phase,
-      handoff,
-    };
-  }
-
   return {
-    outcome: BUILDER_HANDOFF_STATUSES.FAILED,
+    outcome: BUILDER_HANDOFF_STATUSES.DONE,
     specId,
-    phase,
+    phase: WORKFLOW_PHASES.READY_FOR_VERIFIER,
     handoff,
   };
 };
@@ -145,15 +116,8 @@ const buildRunResult = async ({
   specId,
   state,
 }: BuildRunResultInput): Promise<BuilderRunResult> => {
-  if (
-    state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER ||
-    state.phase === WORKFLOW_PHASES.BUILDER_FAILED
-  ) {
-    return await readTerminalBuilderResult({
-      paths,
-      specId,
-      phase: state.phase,
-    });
+  if (state.phase === WORKFLOW_PHASES.READY_FOR_VERIFIER) {
+    return await readDoneBuilderResult({ paths, specId });
   }
 
   if (state.phase === WORKFLOW_PHASES.ESCALATION_DECISION) {
@@ -192,10 +156,6 @@ const formatBuilderResult = (result: BuilderRunResult): string => {
     return `Builder completed spec ${result.specId}. The workflow is ready-for-verifier.`;
   }
 
-  if (result.outcome === BUILDER_HANDOFF_STATUSES.FAILED) {
-    return `Builder failed for spec ${result.specId}. The workflow is builder-failed and cannot be retried.`;
-  }
-
   return `Builder submitted escalation questions for spec ${result.specId}. The workflow is waiting for an owner decision.`;
 };
 

package/src/workflow/builder/completeBuilderPass.ts

@@ -1,13 +1,12 @@
 /**
  * Objective: Complete a builder pass with a validated terminal handoff.
- * Used: When the builder reports done, escalation, or failed through the child tool.
+ * Used: When the builder reports done or escalation through the child tool.
  */
 
 import { mkdir } from 'node:fs/promises';
 import { Value } from 'typebox/value';
 import { assertBuilderHandoff } from '#artifacts/builder-handoff/assertBuilderHandoff.ts';
 import {
-  BUILDER_HANDOFF_STATUSES,
   BUILDER_HANDOFF_VERSION,
   type BuilderHandoff,
   type BuilderHandoffSubmissionInput,
@@ -15,12 +14,9 @@ import {
 } from '#artifacts/builder-handoff/schema.ts';
 import { writeBuilderHandoff } from '#artifacts/builder-handoff/writeBuilderHandoff.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
+import { getWorkflowEventByBuilderHandoff } from '#workflow/builder/utils/getWorkflowEventByBuilderHandoff.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import {
-  WORKFLOW_EVENTS,
-  WORKFLOW_PHASES,
-  type WorkflowState,
-} from '#workflow/state/schema.ts';
+import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
 
@@ -82,12 +78,7 @@ export const completeBuilderPass = async ({
 
   const nextState = transitionWorkflow({
     state: currentState,
-    event:
-      draftHandoff.status === BUILDER_HANDOFF_STATUSES.DONE
-        ? WORKFLOW_EVENTS.BUILDER_DONE
-        : draftHandoff.status === BUILDER_HANDOFF_STATUSES.ESCALATION
-          ? WORKFLOW_EVENTS.OPEN_ESCALATION
-          : WORKFLOW_EVENTS.BUILDER_FAILED,
+    event: getWorkflowEventByBuilderHandoff(handoff),
   });
 
   await mkdir(paths.getBuilderHandoffsPath(specId), { recursive: true });

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

@@ -0,0 +1,24 @@
+/**
+ * Objective: Select the workflow event from a builder handoff.
+ * Used: When a builder completes a pass with done or escalation.
+ */
+
+import {
+  BUILDER_HANDOFF_STATUSES,
+  type BuilderHandoff,
+} from '#artifacts/builder-handoff/schema.ts';
+import { WORKFLOW_EVENTS, type WorkflowEvent } from '#workflow/state/schema.ts';
+
+export const getWorkflowEventByBuilderHandoff = ({
+  status,
+}: BuilderHandoff): WorkflowEvent => {
+  if (status === BUILDER_HANDOFF_STATUSES.DONE) {
+    return WORKFLOW_EVENTS.BUILDER_DONE;
+  }
+
+  if (status === BUILDER_HANDOFF_STATUSES.ESCALATION) {
+    return WORKFLOW_EVENTS.OPEN_ESCALATION;
+  }
+
+  throw new Error(`Unexpected builder handoff status: "${status}".`);
+};

package/src/workflow/state/schema.ts

@@ -14,7 +14,6 @@ export const WORKFLOW_PHASES = {
   READY_FOR_BUILDER: 'ready-for-builder',
   BUILDER_RUNNING: 'builder-running',
   ESCALATION_DECISION: 'escalation-decision',
-  BUILDER_FAILED: 'builder-failed',
   READY_FOR_VERIFIER: 'ready-for-verifier',
   VERIFIER_RUNNING: 'verifier-running',
   FINDINGS_DECISION: 'findings-decision',
@@ -26,7 +25,6 @@ export const WORKFLOW_EVENTS = {
   RUN_BUILDER: 'run-builder',
   OPEN_ESCALATION: 'open-escalation',
   RESOLVE_ESCALATION: 'resolve-escalation',
-  BUILDER_FAILED: 'builder-failed',
   BUILDER_DONE: 'builder-done',
   RUN_VERIFIER: 'run-verifier',
   VERIFIER_FOUND_FINDINGS: 'verifier-found-findings',
@@ -40,7 +38,6 @@ export const WorkflowPhaseSchema = Type.Union([
   Type.Literal(WORKFLOW_PHASES.READY_FOR_BUILDER),
   Type.Literal(WORKFLOW_PHASES.BUILDER_RUNNING),
   Type.Literal(WORKFLOW_PHASES.ESCALATION_DECISION),
-  Type.Literal(WORKFLOW_PHASES.BUILDER_FAILED),
   Type.Literal(WORKFLOW_PHASES.READY_FOR_VERIFIER),
   Type.Literal(WORKFLOW_PHASES.VERIFIER_RUNNING),
   Type.Literal(WORKFLOW_PHASES.FINDINGS_DECISION),

package/src/workflow/transitions.ts

@@ -38,10 +38,6 @@ export const WORKFLOW_TRANSITIONS: Record<WorkflowEvent, WorkflowTransition> = {
     from: [WORKFLOW_PHASES.ESCALATION_DECISION],
     to: WORKFLOW_PHASES.READY_FOR_BUILDER,
   },
-  [WORKFLOW_EVENTS.BUILDER_FAILED]: {
-    from: [WORKFLOW_PHASES.BUILDER_RUNNING],
-    to: WORKFLOW_PHASES.BUILDER_FAILED,
-  },
   [WORKFLOW_EVENTS.BUILDER_DONE]: {
     from: [WORKFLOW_PHASES.BUILDER_RUNNING],
     to: WORKFLOW_PHASES.READY_FOR_VERIFIER,

package/src/workflow/verifier/completeVerifierPass.ts

@@ -9,13 +9,10 @@ import type { VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
 import { writeVerifierHandoff } from '#artifacts/verifier-handoff/writeVerifierHandoff.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import {
-  WORKFLOW_EVENTS,
-  WORKFLOW_PHASES,
-  type WorkflowState,
-} from '#workflow/state/schema.ts';
+import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
+import { getWorkflowEventByVerifierHandoff } from '#workflow/verifier/utils/getWorkflowEventByVerifierHandoff.ts';
 
 export type CompletedVerifierPass = {
   handoff: VerifierHandoff;
@@ -61,10 +58,7 @@ export const completeVerifierPass = async ({
 
   const nextState = transitionWorkflow({
     state: currentState,
-    event:
-      handoff.findings.length > 0
-        ? WORKFLOW_EVENTS.VERIFIER_FOUND_FINDINGS
-        : WORKFLOW_EVENTS.VERIFIER_APPROVED,
+    event: getWorkflowEventByVerifierHandoff(handoff),
   });
 
   await mkdir(paths.getVerifierHandoffsPath(specId), { recursive: true });

package/src/workflow/{findings → verifier}/resolveFindings.ts

@@ -13,13 +13,10 @@ import { FINDING_DECISIONS } from '#artifacts/verifier-handoff/schema.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { writeJson } from '#utils/write-json.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import {
-  WORKFLOW_EVENTS,
-  WORKFLOW_PHASES,
-  type WorkflowState,
-} from '#workflow/state/schema.ts';
+import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
+import { getWorkflowEventByVerifierHandoff } from '#workflow/verifier/utils/getWorkflowEventByVerifierHandoff.ts';
 
 type FindingDecisionRejected = {
   findingId: string;
@@ -159,18 +156,13 @@ const buildFindingWorkflow = ({
     return { ...finding, decision: { decision: FINDING_DECISIONS.FIX_CODE } };
   });
 
-  const isFixCodeRequested = decisions.some(
-    (decision) => decision.decision === FINDING_DECISIONS.FIX_CODE,
-  );
+  const nextHandoff = { ...handoff, findings };
 
   const nextState = transitionWorkflow({
     state,
-    event: isFixCodeRequested
-      ? WORKFLOW_EVENTS.REQUEST_FIXES
-      : WORKFLOW_EVENTS.REJECT_FINDINGS,
+    event: getWorkflowEventByVerifierHandoff(nextHandoff),
   });
 
-  const nextHandoff = { ...handoff, findings };
   assertVerifierHandoff({
     handoff: nextHandoff,
     specId: state.specId,

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

@@ -0,0 +1,40 @@
+/**
+ * Objective: Select the workflow event from a verifier handoff.
+ * Used: When a verifier completes a pass or the owner resolves its findings.
+ */
+
+import {
+  FINDING_DECISIONS,
+  type VerifierHandoff,
+} from '#artifacts/verifier-handoff/schema.ts';
+import { WORKFLOW_EVENTS, type WorkflowEvent } from '#workflow/state/schema.ts';
+
+export const getWorkflowEventByVerifierHandoff = (
+  handoff: VerifierHandoff,
+): WorkflowEvent => {
+  if (handoff.findings.length === 0) {
+    return WORKFLOW_EVENTS.VERIFIER_APPROVED;
+  }
+
+  if (handoff.findings.every(({ decision }) => decision === null)) {
+    return WORKFLOW_EVENTS.VERIFIER_FOUND_FINDINGS;
+  }
+
+  if (
+    handoff.findings.some(
+      ({ decision }) => decision?.decision === FINDING_DECISIONS.FIX_CODE,
+    )
+  ) {
+    return WORKFLOW_EVENTS.REQUEST_FIXES;
+  }
+
+  if (
+    handoff.findings.every(
+      ({ decision }) => decision?.decision === FINDING_DECISIONS.REJECT,
+    )
+  ) {
+    return WORKFLOW_EVENTS.REJECT_FINDINGS;
+  }
+
+  throw new Error('Unexpected verifier finding decisions.');
+};