@emiliosp/pi-maestro 0.11.0 → 0.12.0

package/ROADMAP.md

@@ -10,7 +10,7 @@ Item identifiers remain stable when priorities change. The `owner` approves chan
 ## Overview
 
 | ID   | Title                                                                                                                        | Status      | Summary                                                                                                            |
-|------|------------------------------------------------------------------------------------------------------------------------------|-------------|--------------------------------------------------------------------------------------------------------------------|
+| ---- | ---------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
 | R-01 | [Improve status presentation and activation feedback](#r-01-improve-status-presentation-and-activation-feedback)             | Completed   | Show clearer status and configured agent details without adding model context.                                     |
 | R-02 | [Store escalations and owner decisions in builder handoffs](#r-02-store-escalations-and-owner-decisions-in-builder-handoffs) | Completed   | Keep `escalation` questions and `owner` answers together in numbered `builder` `handoffs`.                         |
 | R-03 | [Route builder failures through owner escalations](#r-03-route-builder-failures-through-owner-escalations)                   | Completed   | Route reportable `builder` problems through `owner` `escalations` instead of a terminal failure phase.             |
@@ -40,8 +40,9 @@ notice to session history or model context. All 12 `acceptance criteria` passed
 
 #### 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).
+[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
 
@@ -50,8 +51,9 @@ Numbered `builder` `handoffs` contain multiple `escalation` questions and their
 
 #### 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-03: Route builder failures through owner escalations
 
@@ -62,8 +64,9 @@ All 8 `acceptance criteria` passed with no `verifier` `findings`. The saved work
 
 #### 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).
+[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
 
@@ -86,8 +89,8 @@ All 6 `acceptance criteria` passed with no `verifier` `findings`. The saved work
 
 #### Evidence
 
-[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).
+[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).
 
 ### R-15: Rename the test support directory
 
@@ -96,7 +99,7 @@ keep fixtures under `tests/fixtures`. Source tests remain next to their source f
 
 #### Evidence
 
-[Test support](tests/support/), [fixtures](tests/fixtures/), and [lint configuration](biome.json).
+[Test support](tests/support/), [fixtures](tests/fixtures/), and [lint configuration](.oxlintrc.json).
 
 ### R-16: Verify code quality against AGENTS.md instructions
 
@@ -111,8 +114,9 @@ saved workflow reached `candidate-ready`.
 
 #### Evidence
 
-[Specification](.specs/20261013-185941-verify-code-quality-against-agents-md-instructions/spec.md), [verifier report](.specs/20261013-185941-verify-code-quality-against-agents-md-instructions/handoffs/verifier/V1.json),
-and [merged PR #34](https://github.com/emilioSp/pi-maestro/pull/34).
+[Specification](.specs/20261013-185941-verify-code-quality-against-agents-md-instructions/spec.md),
+[verifier report](.specs/20261013-185941-verify-code-quality-against-agents-md-instructions/handoffs/verifier/V1.json), and
+[merged PR #34](https://github.com/emilioSp/pi-maestro/pull/34).
 
 ### R-06: Check subagent extensions at activation
 
@@ -127,8 +131,9 @@ verification.
 
 #### Evidence
 
-[Specification](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/spec.md), [verifier report](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/handoffs/verifier/V1.json),
-and [merged PR #35](https://github.com/emilioSp/pi-maestro/pull/35).
+[Specification](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/spec.md),
+[verifier report](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/handoffs/verifier/V1.json), and
+[merged PR #35](https://github.com/emilioSp/pi-maestro/pull/35).
 
 ### R-05: Keep acceptance criterion numbering continuous
 
@@ -142,8 +147,9 @@ All 3 `acceptance criteria` passed with no `verifier` `findings`. The saved work
 
 #### Evidence
 
-[Specification](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/spec.md), [verifier report](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/handoffs/verifier/V1.json),
-and [merged PR #36](https://github.com/emilioSp/pi-maestro/pull/36).
+[Specification](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/spec.md),
+[verifier report](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/handoffs/verifier/V1.json), and
+[merged PR #36](https://github.com/emilioSp/pi-maestro/pull/36).
 
 ### R-10: Match handoff criteria to the approved spec
 
@@ -157,22 +163,23 @@ role. These changes are outside the completed independent verification. The fina
 
 #### Evidence
 
-[Specification](.specs/20261013-211629-match-handoff-criteria-to-the-approved-spec/spec.md), [verifier report](.specs/20261013-211629-match-handoff-criteria-to-the-approved-spec/handoffs/verifier/V1.json),
-and [merged PR #37](https://github.com/emilioSp/pi-maestro/pull/37).
+[Specification](.specs/20261013-211629-match-handoff-criteria-to-the-approved-spec/spec.md),
+[verifier report](.specs/20261013-211629-match-handoff-criteria-to-the-approved-spec/handoffs/verifier/V1.json), and
+[merged PR #37](https://github.com/emilioSp/pi-maestro/pull/37).
 
 ### R-17: Record escalation resolutions when the spec changes
 
 #### Objective
 
-Save every current `escalation` answer in the original `builder` `handoff`, whether the `spec` stays unchanged or requires revision.
-Each `resolution` records the owner's chosen solution and reason. A decision requiring revision also identifies the `escalation` and describes the agreed `spec` change.
+Save every current `escalation` answer in the original `builder` `handoff`, whether the `spec` stays unchanged or requires revision. Each `resolution` records the owner's
+chosen solution and reason. A decision requiring revision also identifies the `escalation` and describes the agreed `spec` change.
 
 #### Agreed flow
 
 `Maestro` records the complete decision batch through `maestro_resolve_escalations` before changing phase.
 
 | Decision                                     | Next phase and action                                                                                                      |
-|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------|
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
 | No `spec` change                             | `escalation-decisions` → `ready-for-builder`. The `builder` continues under the approved `spec`, without renewed approval. |
 | `Spec` change required                       | `escalation-decisions` → `drafting-spec`. The `owner` and `Maestro` revise and review the same `spec`.                     |
 | Revised `spec` receives renewed `GREEN FLAG` | `drafting-spec` → `ready-for-builder` through separate `maestro_mark_spec_ready` approval.                                 |
@@ -181,21 +188,21 @@ Direct `spec` approval from `escalation-decisions` is rejected. Recording answer
 
 #### Implementation boundaries
 
-Reuse the existing resolution operation and `handoff` fields. Do not add a parallel decision store, tool, or workflow phase.
-Define both resolution transitions explicitly in `src/workflow/transitions.ts` and apply them through `transitionWorkflow`. Direct phase assignment elsewhere is banned.
-Preserve initial `spec` approval, `verifier` `finding` decisions, existing batch validation, and historical `handoffs`.
+Reuse the existing resolution operation and `handoff` fields. Do not add a parallel decision store, tool, or workflow phase. Define both resolution transitions explicitly
+in `src/workflow/transitions.ts` and apply them through `transitionWorkflow`. Direct phase assignment elsewhere is banned. Preserve initial `spec` approval, `verifier`
+`finding` decisions, existing batch validation, and historical `handoffs`.
 
 #### Completed when
 
-Saved `resolutions`, workflow phases, tool results, agent instructions, and human documentation follow the agreed flow.
-Verification checks both observable behavior and use of the central transition definitions for each resolution branch. Passing behavior tests alone is not enough.
-The new `spec` includes coverage labels and omits `acceptance criteria` already covered by tests of the same scenario.
+Saved `resolutions`, workflow phases, tool results, agent instructions, and human documentation follow the agreed flow. Verification checks both observable behavior and
+use of the central transition definitions for each resolution branch. Passing behavior tests alone is not enough. The new `spec` includes coverage labels and omits
+`acceptance criteria` already covered by tests of the same scenario.
 
 ### R-20: Route finding-driven spec revisions through drafting-spec
 
-Implemented the approved revision route. `Maestro` records every current `finding` decision before returning to `drafting-spec` when revision is required.
-The `owner` reviews the same revised `spec` and gives renewed `GREEN FLAG` before separate approval and another `builder` `run`.
-Revision takes priority in mixed batches. Direct approval from `finding-decisions` is rejected.
+Implemented the approved revision route. `Maestro` records every current `finding` decision before returning to `drafting-spec` when revision is required. The `owner`
+reviews the same revised `spec` and gives renewed `GREEN FLAG` before separate approval and another `builder` `run`. Revision takes priority in mixed batches. Direct
+approval from `finding-decisions` is rejected.
 
 Later event naming cleanup identifies `builder` and `owner` actions explicitly. Both revision routes use `OWNER_REQUEST_SPEC_REVISION` without changing the phase flow.
 Batch resolution uses `RESOLVE_ESCALATIONS`, and the status label refers to `escalations` in the plural. The saved decision phases are named `escalation-decisions` and
@@ -203,70 +210,63 @@ Batch resolution uses `RESOLVE_ESCALATIONS`, and the status label refers to `esc
 
 #### Evidence
 
-[Specification](.specs/20261015-154812-route-finding-driven-spec-revisions-through-drafting-spec/spec.md)
-and [resolution integration tests](src/tools/main/resolve-findings.integration.test.ts).
+[Specification](.specs/20261015-154812-route-finding-driven-spec-revisions-through-drafting-spec/spec.md) and
+[resolution integration tests](src/tools/main/resolve-findings.integration.test.ts).
 
 ### R-18: Label acceptance criterion coverage
 
-Implemented with R-19 as one task, as selected by the `owner`.
-The `spec` template and `Maestro` guidance require one `Coverage` label per `acceptance criterion`:
+Implemented with R-19 as one task, as selected by the `owner`. The `spec` template and `Maestro` guidance require one `Coverage` label per `acceptance criterion`:
 
 | Label       | Purpose                                      |
-|-------------|----------------------------------------------|
+| ----------- | -------------------------------------------- |
 | `success`   | A valid action produces the required result. |
 | `failure`   | An invalid action is correctly rejected.     |
 | `unchanged` | The change preserves existing behavior.      |
 
-Use `unchanged` when the criterion explicitly checks behavior that the change must preserve.
-Labels describe scenarios, not test outcomes. A `failure` scenario passes when the invalid action is correctly rejected.
-A `spec` does not need all three categories.
-`Maestro` includes labels when presenting criteria to the `owner` and checks them against scenarios and `expected results` during review.
-Approval validation and `handoff` formats remain unchanged.
+Use `unchanged` when the criterion explicitly checks behavior that the change must preserve. Labels describe scenarios, not test outcomes. A `failure` scenario passes
+when the invalid action is correctly rejected. A `spec` does not need all three categories. `Maestro` includes labels when presenting criteria to the `owner` and checks
+them against scenarios and `expected results` during review. Approval validation and `handoff` formats remain unchanged.
 
-The existing creation integration test now checks that the generated `spec` includes the coverage field.
-The final `npm run check` passed all 238 tests and coverage thresholds. No model trials were performed.
+The existing creation integration test now checks that the generated `spec` includes the coverage field. The final `npm run check` passed all 238 tests and coverage
+thresholds. No model trials were performed.
 
 #### Evidence
 
-[Spec template](templates/spec.md), [Maestro guidance](src/maestro/instructions/getMaestroInstructions.ts), [creation integration test](src/specs/create.integration.test.ts),
-and [workflow documentation](docs/workflow.md#acceptance-criteria).
+[Spec template](templates/spec.md), [Maestro guidance](src/maestro/instructions/getMaestroInstructions.ts),
+[creation integration test](src/specs/create.integration.test.ts), and [workflow documentation](docs/workflow.md#acceptance-criteria).
 
 ### R-19: Avoid acceptance criteria already covered by tests
 
-Implemented with R-18. `Maestro` inspects existing tests before writing `acceptance criteria`.
-It omits a criterion only when a test covers the same starting conditions, action, and `expected result`.
-Partial or uncertain coverage does not justify omission. Similar tests do not count.
+Implemented with R-18. `Maestro` inspects existing tests before writing `acceptance criteria`. It omits a criterion only when a test covers the same starting conditions,
+action, and `expected result`. Partial or uncertain coverage does not justify omission. Similar tests do not count.
 
-During `spec` review, `Maestro` removes criteria whose exact scenarios already have test coverage.
-It keeps numbering continuous from `AC1` and updates affected references. Required behavior remains documented in the requirements and constraints.
-The same rules apply during `spec` revisions. No automatic approval check was added.
+During `spec` review, `Maestro` removes criteria whose exact scenarios already have test coverage. It keeps numbering continuous from `AC1` and updates affected
+references. Required behavior remains documented in the requirements and constraints. The same rules apply during `spec` revisions. No automatic approval check was added.
 
 Verification consisted of inspecting the written guidance and running `npm run check`. No model trials were performed.
 
 #### Evidence
 
-[Maestro guidance](src/maestro/instructions/getMaestroInstructions.ts), [spec template](templates/spec.md),
-and [workflow documentation](docs/workflow.md#acceptance-criteria).
+[Maestro guidance](src/maestro/instructions/getMaestroInstructions.ts), [spec template](templates/spec.md), and
+[workflow documentation](docs/workflow.md#acceptance-criteria).
 
 ## Now
 
 ### R-21: Add a simplifier with one clear purpose per agent
 
-Implemented under the [specification](.specs/20261016-090319-add-a-dedicated-simplifier-after-verification/spec.md). Independent review is pending.
-The `builder` implements the approved `spec`. The `verifier` checks its `acceptance criteria`. The `simplifier` refactors accepted code for clarity.
-The extra code-quality review introduced in R-16 is removed from the verifier's instructions.
+Implemented under the [specification](.specs/20261016-090319-add-a-dedicated-simplifier-after-verification/spec.md). Independent review is pending. The `builder`
+implements the approved `spec`. The `verifier` checks its `acceptance criteria`. The `simplifier` refactors accepted code for clarity. The extra code-quality review
+introduced in R-16 is removed from the verifier's instructions.
 
-Successful verification and rejection of all current `findings` save `simplifier-running`.
-`Maestro` calls `maestro_run_simplifier` without another approval or verification cycle.
-Only that tool checks Git readiness. If Git is unavailable, it warns and saves `candidate-ready` without delegation or a `simplifier` `handoff`.
+Successful verification and rejection of all current `findings` save `simplifier-running`. `Maestro` calls `maestro_run_simplifier` without another approval or
+verification cycle. Only that tool checks Git readiness. If Git is unavailable, it warns and saves `candidate-ready` without delegation or a `simplifier` `handoff`.
 
-The `simplifier` selects all uncommitted code changes, including pre-existing staged, unstaged, and untracked files.
-It preserves observable behavior and the accepted check baseline. Rejected `findings` remain rejected, not passed.
-Required caller updates can include initially unchanged files. Unrelated refactoring, index changes, and automatic commits are excluded.
+The `simplifier` selects all uncommitted code changes, including pre-existing staged, unstaged, and untracked files. It preserves observable behavior and the accepted
+check baseline. Rejected `findings` remain rejected, not passed. Required caller updates can include initially unchanged files. Unrelated refactoring, index changes, and
+automatic commits are excluded.
 
-A completed `pass` saves the fixed, unnumbered `handoffs/simplifier/S.json`, then saves `candidate-ready`.
-The report contains refactored files, a summary, and notes. No refactoring is required when selected code is already clear.
-Maestro's final summary separates this report from independent `verifier` evidence.
+A completed `pass` saves the fixed, unnumbered `handoffs/simplifier/S.json`, then saves `candidate-ready`. The report contains refactored files, a summary, and notes. No
+refactoring is required when selected code is already clear. Maestro's final summary separates this report from independent `verifier` evidence.
 
 ## Next
 

package/TECH_STACK.md

@@ -4,12 +4,12 @@
 `dist/` directory.
 
 | Technology                     | Use                                                                                               |
-|--------------------------------|---------------------------------------------------------------------------------------------------|
+| ------------------------------ | ------------------------------------------------------------------------------------------------- |
 | TypeScript                     | Application code and static type checks with `tsc --noEmit`.                                      |
 | Node.js                        | Runtime.                                                                                          |
 | Pi                             | Extension host, agent APIs, and terminal interface.                                               |
 | `pi-subagents`                 | `Builder`, `verifier`, and `simplifier` execution and activity tracking.                          |
 | TypeBox                        | Schemas and runtime validation for configuration, workflow state, tool inputs, and agent reports. |
 | Vitest with coverage           | Unit tests, integration tests, and code coverage.                                                 |
-| Biome                          | Formatting and lint checks.                                                                       |
-| Oxlint with `oxlint-anti-slop` | Additional lint and anti-slop checks.                                                             |
+| Oxfmt                          | Formatting                                                                                        |
+| Oxlint with `oxlint-anti-slop` | Linting and additional anti-slop checks.                                                          |

package/agents/builder.md

@@ -11,83 +11,79 @@ subagentOnlyExtensions: ../extensions/maestro-subagent.ts
 
 # Builder
 
-Implement the approved spec and produce one saved result for this pass.
-Work in the project directory supplied by Maestro.
-The owner decides requirements, scope, spec changes, escalations, and findings. Maestro coordinates those decisions.
-Do not delegate, contact the owner directly, or approve your own work.
+Implement the approved spec and produce one saved result for this pass. Work in the project directory supplied by Maestro. The owner decides requirements, scope, spec
+changes, escalations, and findings. Maestro coordinates those decisions. Do not delegate, contact the owner directly, or approve your own work.
 
 ## Read the contract and current state
 
 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.
+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 `proposal.md` for motivation and scope, `spec.md` for behavior and all acceptance criteria, including standalone regression checks, and `design.md` when present
+   for approved technical decisions. Read relevant `prototypes/`, `workflow.json`, and applicable `AGENTS.md` files. The present documents form one approved contract.
 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.
-You start with a fresh context. Do not assume prior conversation or owner decisions that are not recorded.
-Builder handoffs use `handoffs/builder/B1.json`, `B2.json`, and so on. Verifier handoffs use `handoffs/verifier/V1.json`, `V2.json`, and so on.
-The highest numeric sequence is the active handoff for each role. Earlier records are references, not active instructions.
+If the supplied spec is missing or the phase is wrong, report the mismatch to Maestro and stop. Do not repair workflow state. You start with a fresh context. Do not
+assume prior conversation or owner decisions that are not recorded. Builder handoffs use `handoffs/builder/B1.json`, `B2.json`, and so on. Verifier handoffs use
+`handoffs/verifier/V1.json`, `V2.json`, and so on. The highest numeric sequence is the active handoff for each role. Earlier records are references, not active
+instructions.
 
-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 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.
-Use the active spec and the active handoff to assess repair instructions. A finding with `decision: null` has no owner decision.
+Do not edit the frozen proposal, spec, design, or prototypes during any agent execution. Do not create a design document after approval. The approved spec defines the
+required behavior, constraints, technical decisions, scope, and acceptance criteria. 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. Use the active spec and the active handoff to assess repair instructions. A finding with
+`decision: null` has no owner decision.
 
 ## Implement within the contract
 
-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`, or handoffs directly through any tool.
-Use `maestro_record_builder_handoff` for protocol changes. The tool supplies artifact paths and versions.
+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 `proposal.md`, `spec.md`, `design.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.
-Do not escalate routine implementation choices that stay within the contract.
-Record significant discoveries without an owner decision in handoff `notes`. Do not turn notes into an activity log.
+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. Do not escalate routine implementation choices that stay within the contract. Record significant
+discoveries without an owner decision in handoff `notes`. Do not turn notes into an activity log.
 
 ## Prove every acceptance criterion
 
-Run every probe, including on repair passes. Previous evidence does not replace this pass's results.
-The spec defines probe scenarios, expected results, and concrete examples.
-Choose test code, fixtures, mocks, and commands that cover each approved scenario.
-These execution details are your responsibility, not missing owner decisions. Follow any explicit execution constraints in the approved spec.
-Run each executable probe against the implementation and compare the observed result with the expected result.
-Do not change approved probe scenarios, expected results, examples, or design decisions to obtain passing results.
-If the implementation fails, repair it within the contract and repeat the proof for affected criteria.
-If the contract needs clarification or revision, escalate instead of inventing a replacement probe.
-For visual claims, use the specified reproducible procedure and compare with prototypes when required.
-Run applicable repository checks. If subsequent changes invalidate earlier evidence, rerun the affected checks and proofs.
-
-For each criterion, record its exact `id`, actual command or procedure in `probe`, and `probeStatus`.
-Use `probeStatus: passed` when the observed result matches the expected result.
-Use `failed` for an observed probe failure and `not-run` for an unexecuted probe.
-Include every spec criterion once. Do not omit unrun criteria, fabricate evidence, or include secrets or full logs.
+Run every probe, including on repair passes. Previous evidence does not replace this pass's results. The spec defines probe scenarios, expected results, and concrete
+examples. Choose test code, fixtures, mocks, and commands that cover each approved scenario. These execution details are your responsibility, not missing owner decisions.
+Follow any explicit execution constraints in the approved spec. Run each executable probe against the implementation and compare the observed result with the expected
+result. Do not change approved probe scenarios, expected results, examples, or design decisions to obtain passing results. If the implementation fails, repair it within
+the contract and repeat the proof for affected criteria. If the contract needs clarification or revision, escalate instead of inventing a replacement probe. For visual
+claims, use the specified reproducible procedure and compare with prototypes when required. Run applicable repository checks. If subsequent changes invalidate earlier
+evidence, rerun the affected checks and proofs.
+
+For each criterion, record its exact `id`, actual command or procedure in `probe`, and `probeStatus`. Use `probeStatus: passed` when the observed result matches the
+expected result. Use `failed` for an observed probe failure and `not-run` for an unexecuted probe. Include every spec criterion once. Do not omit unrun criteria,
+fabricate evidence, or include secrets or full logs.
 
 ## Record exactly one outcome
 
-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:
+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`, `notes`, and `escalations: []`.
-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.
+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, 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.
-Do not wait for an escalation answer, run the verifier, or continue implementation after the terminal call.
+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. Do not wait for an escalation answer, run the verifier, or continue implementation after the terminal call.
 
 ## Handle protocol errors without bypasses
 
-If a terminal call fails, inspect the error, current phase, and artifacts before retrying.
-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.
-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.
+If a terminal call fails, inspect the error, current phase, and artifacts before retrying. 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. 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.