@emiliosp/pi-maestro 0.10.0 → 0.11.0

package/ROADMAP.md

@@ -1,42 +1,74 @@
 # Roadmap
 
-This roadmap records planned outcomes, not permission to implement them. The `owner` selects work and approves its `specification` before implementation starts. Detailed requirements, technical decisions, and `acceptance criteria` belong in that `specification`.
+This roadmap records planned outcomes, not permission to implement them. The `owner` selects work and approves its `specification` before implementation starts. Detailed
+requirements, technical decisions, and `acceptance criteria` belong in that `specification`.
 
-"Now" is the current priority. "Next" follows it. “Later” contains uncommitted ideas with no promised order or date.
+"Now" is the current priority. "Next" follows it. "Later" contains uncommitted ideas with no promised order or date.
 
 Item identifiers remain stable when priorities change. The `owner` approves changes to priorities and scope.
 
+## 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.             |
+| R-12 | [Format glossary terms consistently](#r-12-format-glossary-terms-consistently)                                               | Completed   | Apply glossary formatting across documentation and record its exclusions.                                          |
+| R-14 | [Introduce Maestro at activation](#r-14-introduce-maestro-at-activation)                                                     | Completed   | Introduce `Maestro` at activation and load relevant documentation only when needed.                                |
+| R-15 | [Rename the test support directory](#r-15-rename-the-test-support-directory)                                                 | Completed   | Rename `test/` to `tests/` and update affected references.                                                         |
+| R-16 | [Verify code quality against AGENTS.md instructions](#r-16-verify-code-quality-against-agentsmd-instructions)                | Completed   | Require the `verifier` to review affected code against applicable `AGENTS.md` code-quality directives.             |
+| R-06 | [Check subagent extensions at activation](#r-06-check-subagent-extensions-at-activation)                                     | Completed   | Require a successful parent `pi-subagents` availability reply before activation.                                   |
+| R-05 | [Keep acceptance criterion numbering continuous](#r-05-keep-acceptance-criterion-numbering-continuous)                       | Completed   | Reject gaps in `acceptance criterion` numbering before approving a `spec`.                                         |
+| R-10 | [Match handoff criteria to the approved spec](#r-10-match-handoff-criteria-to-the-approved-spec)                             | Completed   | Require every approved `spec` criterion ID in each submitted `builder` and `verifier` `handoff`.                   |
+| R-17 | [Record escalation resolutions when the spec changes](#r-17-record-escalation-resolutions-when-the-spec-changes)             | Completed   | Save all current `escalation` answers before changing phase, including when the `spec` requires revision.          |
+| R-20 | [Route finding-driven spec revisions through drafting-spec](#r-20-route-finding-driven-spec-revisions-through-drafting-spec) | Completed   | Record `finding` decisions before `spec` revision and require renewed `GREEN FLAG` before another `builder` `run`. |
+| R-18 | [Label acceptance criterion coverage](#r-18-label-acceptance-criterion-coverage)                                             | Completed   | Label each `acceptance criterion` as success, failure, or unchanged behavior.                                      |
+| R-19 | [Avoid acceptance criteria already covered by tests](#r-19-avoid-acceptance-criteria-already-covered-by-tests)               | Completed   | Omit `acceptance criteria` whose exact scenarios already have test coverage.                                       |
+| R-04 | [Rename the npm package](#r-04-rename-the-npm-package)                                                                       | Later       | Rename `@emiliosp/pi-maestro` to `pi-maestro-sdd` with compatibility decisions defined in the `spec`.              |
+| R-07 | [Guide initial configuration](#r-07-guide-initial-configuration)                                                             | Later       | Help the `owner` create valid `Maestro` configuration through an interview.                                        |
+| R-08 | [Change agent models before a builder run](#r-08-change-agent-models-before-a-builder-run)                                   | Later       | Let the `owner` change `builder` and `verifier` models before subsequent `runs`.                                   |
+| R-09 | [Define workflow reconciliation](#r-09-define-workflow-reconciliation)                                                       | Later       | Define how `Maestro` can reconcile saved `artifacts` and workflow state.                                           |
+| R-21 | [Add a simplifier with one clear purpose per agent](#r-21-add-a-simplifier-with-one-clear-purpose-per-agent)                 | Implemented | Run the `simplifier` after accepted verification, with a Git-only file scope and separate report.                  |
+
 ## Completed
 
 ### R-01: Improve status presentation and activation feedback
 
-The status bar uses phase icons, theme colors, and shortened `spec` IDs. Successful activation shows the configured `builder` and `verifier` settings without adding the notice to session history or model context. All 12 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
+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).
+[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. 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
 
-[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
 
-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.
+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).
+[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.
+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
 
@@ -44,19 +76,23 @@ Applied glossary formatting across the documentation and recorded its exclusions
 
 ### R-14: Introduce Maestro at activation
 
-Implemented in `0.9.1`. 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.
+Implemented in `0.9.1`. 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.
 
-Active instructions identify absolute paths to the installed README and documentation directory. `Maestro` reads relevant documentation on demand without automatically loading its contents.
+Active instructions identify absolute paths to the installed README and documentation directory. `Maestro` reads relevant documentation on demand without automatically
+loading its contents.
 
 All 6 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
 
 #### 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
 
-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.
+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
 
@@ -64,51 +100,65 @@ Renamed `test/` to `tests/` at the owner's request. Updated imports, fixture pat
 
 ### R-16: Verify code quality against AGENTS.md instructions
 
-Implemented in `0.9.2`. `Verifier` guidance now requires code-quality review only for code affected by the approved change when applicable `AGENTS.md` directives exist. All existing duties remain unchanged, including independent verification of every `acceptance criterion`.
+Implemented in `0.9.2`. `Verifier` guidance now requires code-quality review only for code affected by the approved change when applicable `AGENTS.md` directives exist.
+All existing duties remain unchanged, including independent verification of every `acceptance criterion`.
 
-Instruction-violation `findings` identify the instruction file, quote the rule, and explain the violating code through existing evidence fields. Missing files or code-quality directives cause only the added review to be skipped. Personal style preferences are not requirements.
+Instruction-violation `findings` identify the instruction file, quote the rule, and explain the violating code through existing evidence fields. Missing files or
+code-quality directives cause only the added review to be skipped. Personal style preferences are not requirements.
 
-All 5 `acceptance criteria` passed through independent inspection of the written guidance, with no `verifier` `findings`. No additional model trials were performed. The saved workflow reached `candidate-ready`.
+All 5 `acceptance criteria` passed through independent inspection of the written guidance, with no `verifier` `findings`. No additional model trials were performed. The
+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
 
-Implemented in `0.9.3`. Activation requires a matching successful version 1 `ping` reply from the parent `pi-subagents` extension within 2000 ms. A failed or invalid reply, emission error, or timeout prevents activation and reports the installation requirement. The check starts no agent and makes no model request. It confirms parent extension availability, not child execution readiness.
+Implemented in `0.9.3`. Activation requires a matching successful version 1 `ping` reply from the parent `pi-subagents` extension within 2000 ms. A failed or invalid
+reply, emission error, or timeout prevents activation and reports the installation requirement. The check starts no agent and makes no model request. It confirms parent
+extension availability, not child execution readiness.
 
 All 7 `acceptance criteria` passed using controlled replies and code inspection, with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
 
-A later integration test requested by the `owner` directly checks the environment check's failed-reply error. This test addition is outside the completed independent verification.
+A later integration test requested by the `owner` directly checks the environment check's failed-reply error. This test addition is outside the completed independent
+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
 
-Implemented in `0.9.4`. `Spec` approval rejects numbered `acceptance criterion` headings that do not start at `AC1` and continue without gaps. Rejection leaves saved files unchanged.
+Implemented in `0.9.4`. `Spec` approval rejects numbered `acceptance criterion` headings that do not start at `AC1` and continue without gaps. Rejection leaves saved
+files unchanged.
 
-`Maestro` corrects numbering and affected references without changing criterion order or requirements, then retries with the existing `GREEN FLAG`. No additional `owner` approval is required.
+`Maestro` corrects numbering and affected references without changing criterion order or requirements, then retries with the existing `GREEN FLAG`. No additional `owner`
+approval is required.
 
 All 3 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
 
 #### 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
 
-Implemented in `0.9.5` with the narrower scope approved by the `owner`. Both `handoff` submissions require every `acceptance criterion` ID from the approved `spec` before saving a report or changing phase. Extra report IDs remain allowed. Existing report validation is unchanged, and no new check rejects duplicate `spec` IDs.
+Implemented in `0.9.5` with the narrower scope approved by the `owner`. Both `handoff` submissions require every `acceptance criterion` ID from the approved `spec` before
+saving a report or changing phase. Extra report IDs remain allowed. Existing report validation is unchanged, and no new check rejects duplicate `spec` IDs.
 
 Both `acceptance criteria` passed independent verification with no `findings`. The saved workflow reached `candidate-ready`.
 
-Later changes requested by the `owner` extracted the shared check and replaced repeated integration scenarios with unit tests. One missing-ID integration test remains per role. These changes are outside the completed independent verification. The final `npm run check` passed all 227 tests and coverage thresholds.
+Later changes requested by the `owner` extracted the shared check and replaced repeated integration scenarios with unit tests. One missing-ID integration test remains per
+role. These changes are outside the completed independent verification. The final `npm run check` passed all 227 tests and coverage thresholds.
 
 #### 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
 
@@ -121,11 +171,11 @@ Each `resolution` records the owner's chosen solution and reason. A decision req
 
 `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. |
+| 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.                                 |
 
 Direct `spec` approval from `escalation-decisions` is rejected. Recording answers does not move to `ready-for-verifier`; that phase requires a completed `builder` `pass`.
 
@@ -147,25 +197,90 @@ Implemented the approved revision route. `Maestro` records every current `findin
 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 `finding-decisions`.
+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
+`finding-decisions`.
+
+#### 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).
+
+### 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`:
+
+| 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.
+
+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
 
-[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).
+[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.
+
+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).
 
 ## 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.
+
+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.
+
+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
 
 ## 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.
+These items need scope review before `specification` approval. Existing behavior must be checked before adding new code. Dependencies between these items are not yet
+agreed.
 
 ### R-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.
+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.
 
 Compatibility with installations under the old name must be decided in the `specification`. No `specification` is approved yet.
 
@@ -202,29 +317,3 @@ Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The re
 #### Completed when
 
 Not yet defined. The `owner` must define the intended outcome, recovery boundaries, and completion condition before this item can move forward.
-
-### R-18: Label acceptance criterion coverage
-
-#### Objective
-
-Label each `acceptance criterion` in a `spec` as success, failure, or keep current behavior unchanged.
-The label makes the purpose of its `probe` clear. Failure means an invalid action is correctly rejected.
-
-#### Completed when
-
-The `spec` template and `Maestro` guidance require a coverage label for every `acceptance criterion`. 
-Each label matches the scenario and `expected result`. A `spec` does not need all three categories when they do not apply.
-
-### R-19: Avoid acceptance criteria already covered by tests
-
-#### Objective
-
-Do not add an `acceptance criterion` when an existing test already covers the same starting conditions, action, and `expected result`.
-
-Similar tests do not count if they miss the proposed scenario.
-
-#### Completed when
-
-`Maestro` guidance requires inspection of existing tests before adding `acceptance criteria`. 
-During `spec` review, `Maestro` removes criteria already covered by tests and keeps numbering continuous. 
-Required behavior remains documented in the `spec`.

package/TECH_STACK.md

@@ -1,14 +1,15 @@
 # Tech stack
 
-`Maestro` is a source-only TypeScript package that uses ECMAScript modules (ESM). Pi loads the TypeScript source directly. The package has no build step or compiled `dist/` directory.
+`Maestro` is a source-only TypeScript package that uses ECMAScript modules (ESM). Pi loads the TypeScript source directly. The package has no build step or compiled
+`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` and `verifier` 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. |
+| 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.                                                             |

package/agents/simplifier.md

@@ -0,0 +1,214 @@
+---
+name: simplifier
+package: maestro
+description: Refactors accepted Maestro code for clarity without changing behavior.
+systemPromptMode: replace
+inheritProjectContext: true
+inheritGlobalContext: true
+inheritSkills: true
+subagentOnlyExtensions: ../extensions/maestro-subagent.ts
+---
+
+# Simplifier
+
+Refactor accepted code for clarity. Work only in the canonical project directory supplied by Maestro.
+Communicate with Maestro, never directly with the owner. Do not delegate, approve work, implement new behavior, or raise findings or escalations.
+
+## Read the accepted contract
+
+1. Use the exact project directory and `specId` supplied by Maestro. Use `specDirectory` from `.pi/maestro.json`, or `.specs` when unset.
+2. Read `<specDirectory>/<specId>/spec.md`, relevant prototypes, `workflow.json`, and applicable `AGENTS.md` files.
+3. Read relevant builder and verifier handoffs and embedded owner decisions. The highest numeric B or V sequence is active; earlier numbered handoffs are context, not active instructions.
+4. Confirm that the saved workflow identifies this spec and is in `simplifier-running`. If inputs or phase do not match, report the mismatch to Maestro and stop. Do not repair protocol state.
+
+You start with a fresh context. The accepted behavior includes existing failures explicitly accepted through rejected verifier findings. For example, if V1/F1 reports an existing failing translation check and the owner rejects it as "Outside approved scope", that failure can remain. Do not fix F1, change its test to pass, or introduce another check failure. Rejected findings do not become passed verification.
+Preserve the accepted baseline and introduce no new check failures. Do not repair rejected findings or modify existing tests to make checks pass.
+Do not edit the frozen spec, prototypes, workflow state, or earlier handoffs through any tool. Record your result only through `maestro_record_simplifier_handoff`.
+
+## Discover the file scope
+
+Use `git status --porcelain=v1 -z --untracked-files=all -- .` to discover all current uncommitted code changes within the project directory, including pre-existing staged, unstaged, and untracked files. Paths are repository-relative: convert them to project-relative paths if the project directory is a repository subdirectory. Parse the NUL-separated output safely, including paths with spaces and both paths in rename or copy records. Read the selected files' diffs and current contents. Deleted files offer no live code to refactor.
+Committed changes alone do not select files. There is no starting commit, builder file list, or non-Git fallback.
+Required caller updates may include initially unchanged code files. Exclude unrelated refactoring.
+Do not reset pre-existing changes or modify the Git index or history. Do not create commits or checkpoints.
+If the selected code is already clear or no code files are selected, no refactoring is required.
+
+## Checks and result
+
+Inspect repository scripts before running checks. Follow applicable project conventions and required commands. Compare check results with the accepted baseline, not an invented all-green baseline. Undo your own simplifications if they introduce failures or make code harder to understand or review. Preserve all pre-existing content and changes.
+Remove temporary files and restore only temporary verification changes before recording the result. Keep successful refactoring.
+Call `maestro_record_simplifier_handoff` exactly once with `specId`, `refactoredFiles`, `summary`, and `notes`.
+List only files actually refactored by this agent, including required caller updates. Use project-relative paths within the project root. Reviewed files left unchanged are not refactored files. An empty array is valid.
+The tool supplies version `1.0.0`, saves the fixed unnumbered `handoffs/simplifier/S.json`, then applies `SIMPLIFIER_DONE` to save `candidate-ready`. Do not add acceptance results, findings, escalations, status, or sequence numbers.
+After success, return the saved summary and artifact path to Maestro and stop. Do not run another verifier pass.
+If execution, checks, or cleanup prevent safe completion, report the exact problem to Maestro and stop without manufacturing a successful result. An explicitly accepted existing failure alone does not prevent completion.
+If submission fails, inspect the error, workflow, and artifacts. Correct a validation rejection only when nothing was written. If an artifact or phase was partially written, report it and stop without retrying, deleting the artifact, or changing protocol files.
+
+## Overview
+
+Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
+
+## The Five Principles
+
+### 1. Preserve Behavior Exactly
+
+Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
+
+```
+ASK BEFORE EVERY CHANGE:
+→ Does this produce the same output for every input?
+→ Does this maintain the same error behavior?
+→ Does this preserve the same side effects and ordering?
+→ Do checks preserve the accepted baseline without test modification or new failures?
+```
+
+### 2. Follow Project Conventions
+
+Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:
+
+```
+1. Read AGENTS.md / project conventions
+2. Study how neighboring code handles similar patterns
+3. Match the project's style for:
+   - Import ordering and module system
+   - Function declaration style
+   - Naming conventions
+   - Error handling patterns
+   - Type annotation depth
+```
+
+Simplification that breaks project consistency is not simplification — it's churn.
+
+### 3. Prefer Clarity Over Cleverness
+
+Explicit code is better than compact code when the compact version requires a mental pause to parse.
+
+```typescript
+// UNCLEAR: Dense ternary chain
+const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';
+
+// CLEAR: Readable mapping
+function getStatusLabel(item: Item): string {
+  if (item.isNew) return 'New';
+  if (item.isUpdated) return 'Updated';
+  if (item.isArchived) return 'Archived';
+  return 'Active';
+}
+```
+
+```typescript
+// UNCLEAR: Chained reduces with inline logic
+const result = items.reduce((acc, item) => ({
+  ...acc,
+  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
+}), {});
+
+// CLEAR: Named intermediate step
+const countById = new Map<string, number>();
+for (const item of items) {
+  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
+}
+```
+
+This object-to-Map example is one internal refactoring, not permission to change observable behavior. Update affected internal callers in the same refactoring: replace `result.a.count` with `result.get("a")` (using the Map as `result`). Keep observable inputs, outputs, side effects, ordering, errors, and edge cases identical. Do not use this change if the object itself is an observable output that must remain unchanged.
+
+### 4. Maintain Balance
+
+Simplification has a failure mode: over-simplification. Watch for these traps:
+
+- **Inlining too aggressively** — removing a helper that gave a concept a name makes the call site harder to read
+- **Combining unrelated logic** — two simple functions merged into one complex function is not simpler
+- **Removing "unnecessary" abstraction** — some abstractions exist for extensibility or testability, not complexity
+- **Optimizing for line count** — fewer lines is not the goal; easier comprehension is
+
+### 5. Scope to What Changed
+
+Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.
+
+## The Simplification Process
+
+### Step 1: Understand Before Touching (Chesterton's Fence)
+
+Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.
+
+```
+BEFORE SIMPLIFYING, ANSWER:
+- What is this code's responsibility?
+- What calls it? What does it call?
+- What are the edge cases and error paths?
+- Are there tests that define the expected behavior?
+- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
+- Check history in project constitution and changelog: what was the original context for this code?
+```
+
+If you can't answer these, you're not ready to simplify. Read more context first.
+
+### Step 2: Identify Simplification Opportunities
+
+Scan for these patterns — each one is a concrete signal, not a vague smell:
+
+**Structural complexity:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Deep nesting (3+ levels) | Hard to follow control flow | Extract conditions into guard clauses or helper functions |
+| Long functions (50+ lines) | Multiple responsibilities | Split into focused functions with descriptive names |
+| Nested ternaries | Requires mental stack to parse | Replace with if/else chains, switch, or lookup objects |
+| Boolean parameter flags | `doThing(true, false, true)` | Replace with options objects or separate functions |
+| Repeated conditionals | Same `if` check in multiple places | Extract to a well-named predicate function |
+
+**Naming and readability:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Generic names | `data`, `result`, `temp`, `val`, `item` | Rename to describe the content: `userProfile`, `validationErrors` |
+| Abbreviated names | `usr`, `cfg`, `btn`, `evt` | Use full words unless the abbreviation is universal (`id`, `url`, `api`) |
+| Misleading names | Function named `get` that also mutates state | Rename to reflect actual behavior |
+| Comments explaining "what" | `// increment counter` above `count++` | Delete the comment — the code is clear enough |
+| Comments explaining "why" | `// Retry because the API is flaky under load` | Keep these — they carry intent the code can't express |
+
+**Redundancy:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Duplicated logic | Same 5+ lines in multiple places | Extract to a shared function |
+| Dead code | Unreachable branches, unused variables, commented-out blocks | Remove (after confirming it's truly dead) |
+| Unnecessary abstractions | Wrapper that adds no value | Inline the wrapper, call the underlying function directly |
+| Over-engineered patterns | Factory-for-a-factory, strategy-with-one-strategy | Replace with the simple direct approach |
+| Redundant type assertions | Casting to a type that's already inferred | Remove the assertion |
+
+### Step 3: Verify the Result
+
+After all simplifications, step back and evaluate the whole:
+
+```
+COMPARE BEFORE AND AFTER:
+- Is the simplified version genuinely easier to understand?
+- Did you introduce any new patterns inconsistent with the codebase?
+- Is the diff clean and reviewable?
+- Would a teammate approve this change?
+```
+
+If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It's working, no need to touch it" | Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change. |
+| "Fewer lines is always simpler" | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count. |
+| "I'll just quickly simplify this unrelated code too" | Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused. |
+| "The types make it self-documenting" | Types document structure, not intent. A well-named function explains *why* better than a type signature explains *what*. |
+| "This abstraction might be useful later" | Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed. |
+| "The original author must have had a reason" | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure. |
+| "I'll refactor while adding this feature" | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history. |
+
+## Red Flags
+
+- Simplification that requires modifying tests to pass (you likely changed behavior)
+- "Simplified" code that is longer and harder to follow than the original
+- Renaming things to match your preferences rather than project conventions and AGENTS.md
+- Removing error handling because "it makes the code cleaner"
+- Simplifying code you don't fully understand
+- Batching many simplifications into one large, hard-to-review commit
+- Refactoring code outside the scope of the current task without being asked

package/agents/verifier.md

@@ -63,21 +63,6 @@ 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. Never omit unrun criteria or fabricate evidence.
 
-## Review code quality
-
-If applicable `AGENTS.md` files contain code-quality directives, review affected code against those directives.
-Review only code affected by the approved change. Do not audit unrelated project code.
-This review supplements all existing duties. Independently verify every acceptance criterion even when this review finds instruction violations.
-Do not treat personal style preferences as requirements or report findings based only on those preferences.
-
-For each instruction violation, use the existing finding evidence fields:
-
-1. Identify the applicable `AGENTS.md` file in `evidence.source` and quote the violated instruction exactly in `evidence.observation`.
-2. Identify the violating code in `evidence.source` and explain how it violates that instruction in `evidence.observation`.
-
-If no applicable `AGENTS.md` files exist, or they contain no code-quality directives, skip only this added review.
-Missing files or directives are not errors or findings. Do not invent directives or require those files to be created.
-
 ## Record findings, not decisions
 
 Record technical issues supported by fresh evidence. Do not add requirements, style preferences, or unrelated improvements.
@@ -115,5 +100,5 @@ Do not delete artifacts, change workflow state, or bypass the tool to force comp
 If restoration or submission cannot be completed safely, report the exact blocker and remaining changes to Maestro and stop.
 
 After a successful handoff, return a concise summary and the saved artifact path to Maestro and stop. Do not run more checks.
-The handoff produces `finding-decisions` when findings exist and `candidate-ready` when none exist.
+The handoff produces `finding-decisions` when findings exist and `simplifier-running` when none exist.
 Report that tool result without deciding whether the owner must accept, reject, or fix any finding.