@emiliosp/pi-maestro 0.10.0 → 0.11.0

package/ADR.md

@@ -1,7 +1,7 @@
 # Architecture decision records
 
-An Architecture Decision Record (ADR) explains an important architectural choice, its context, and its consequences. 
-This file contains one numbered record per decision. 
+An Architecture Decision Record (ADR) explains an important architectural choice, its context, and its consequences.
+This file contains one numbered record per decision.
 
 Requirements and routine project rules belong in the [roadmap](ROADMAP.md) or other relevant documentation.
 
@@ -11,11 +11,12 @@ When a new decision replaces an accepted decision, add a new record, mark the ea
 
 ### Status
 
-Accepted. Recorded date: 2026-10-07. Implemented in `0.6.0`.
+Superseded by [ADR-004](#adr-004-require-git-only-for-the-simplifier). Recorded date: 2026-10-07. Implemented in `0.6.0`.
 
 ### Context
 
-The previous workflow required Git and used checkpoints and automatic commits. The recorded reason for removing that approach was to simplify the project. Other evaluated alternatives were not recorded.
+The previous workflow required Git and used checkpoints and automatic commits. The recorded reason for removing that approach was to simplify the project. Other evaluated
+alternatives were not recorded.
 
 ### Decision
 
@@ -25,11 +26,13 @@ The `verifier` checks live project files. The `owner` controls later Git use, pu
 
 ### Consequences
 
-Workflow execution no longer depends on Git. Revision and commit fields were removed without migration or compatibility readers. Interrupted and older workflows require manual `owner` handling.
+Workflow execution no longer depends on Git. Revision and commit fields were removed without migration or compatibility readers. Interrupted and older workflows require
+manual `owner` handling.
 
 ### Evidence
 
-[Commit deae41c](https://github.com/emilioSp/pi-maestro/commit/deae41ce66a3f2c76859209c44165e7ddd0f3a72), [Changelog 0.6.0](CHANGELOG.md#060), and [workflow completion](docs/workflow.md#workflow-completion).
+[Commit deae41c](https://github.com/emilioSp/pi-maestro/commit/deae41ce66a3f2c76859209c44165e7ddd0f3a72), [Changelog 0.6.0](CHANGELOG.md#060),
+and [workflow completion](docs/workflow.md#workflow-completion).
 
 ## ADR-002: Store escalation decisions in builder handoffs
 
@@ -39,7 +42,8 @@ Accepted. Recorded date: 2026-10-08. Implemented in `0.7.0`.
 
 ### Context
 
-The previous approach stored `escalations` in standalone files and used singular resolution tools. The recorded reason for replacing it was to use the same storage, local ID, and batch decision model as `verifier` `findings`. Other evaluated alternatives were not recorded.
+The previous approach stored `escalations` in standalone files and used singular resolution tools. The recorded reason for replacing it was to use the same storage, local
+ID, and batch decision model as `verifier` `findings`. Other evaluated alternatives were not recorded.
 
 ### Decision
 
@@ -55,7 +59,8 @@ 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).
+[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
 
@@ -86,4 +91,43 @@ This breaking MVP change has no migrations, compatibility readers, deprecated al
 
 ### 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).
+[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).
+
+## ADR-004: Require Git only for the simplifier
+
+### Status
+
+Accepted. Implemented through R-21.
+Supersedes [ADR-001](#adr-001-keep-the-workflow-independent-of-git).
+
+### Context
+
+The `simplifier` needs a list of changed code files. Git can supply that list without adding file tracking to `builder` `handoffs`.
+
+### Decision
+
+Only the `simplifier` requires Git and a Git repository to discover changed files. It has no non-Git fallback.
+
+The Git readiness decision belongs only inside `maestro_run_simplifier`, before delegation. The tool checks readiness with `git rev-parse --is-inside-work-tree` in the
+project directory. Only a successful result of `true` enables simplification.
+
+Activation, `spec` preparation, `builder` execution, `verifier` completion, and `finding` resolution do not check Git readiness. Both `simplifier` entry routes save
+`simplifier-running` before `Maestro` calls `maestro_run_simplifier`.
+
+`Maestro` does not create automatic commits or Git checkpoints. The `owner` retains control of commits, pull requests, and merging.
+
+### Consequences
+
+If Git readiness cannot be confirmed, `maestro_run_simplifier` reports a warning and skips delegation. The workflow moves from `simplifier-running` to `candidate-ready`
+without an error. The skip transition is defined in `src/workflow/transitions.ts` and applied through `transitionWorkflow`.
+
+Activation does not predict whether simplification will be skipped. The same readiness decision applies after successful verification and after the `owner` rejects all
+current `findings`. Rejected `findings` retain their reasons and do not become passed verification.
+
+The `simplifier` uses Git to select all staged, unstaged, and untracked code changes, including pre-existing changes.
+There is no spec-specific starting commit or `builder` file list. Required caller updates can include initially unchanged files.
+
+### Evidence
+
+[R-21](ROADMAP.md#r-21-add-a-simplifier-with-one-clear-purpose-per-agent) and the [specification](.specs/20261016-090319-add-a-dedicated-simplifier-after-verification/spec.md).

package/CHANGELOG.md

@@ -1,52 +1,77 @@
 # Changelog
 
-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.
+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.
 
-## Unreleased
+## 0.11.0
 
-1. Add `revise-spec` decisions for `verifier` `findings`, with the owner's reason and agreed requirement change saved in the active `handoff`.
-2. Route any revision batch to `drafting-spec` before revision, with priority over code fixes and rejections.
-3. Require separate renewed approval from `drafting-spec` and reject direct approval from `finding-decisions`.
+1. Added the `simplifier` after successful verification or rejection of all current `findings`, without another approval or verification cycle.
+2. Added Git-only readiness and file discovery for simplification. If Git is unavailable, the workflow warns and completes without delegation.
+3. Added independent `simplifier` configuration, activation checks and presentation, running status, and the fixed `handoffs/simplifier/S.json` result.
+4. Removed the extra code-quality review from the verifier's instructions. The `simplifier` preserves accepted behavior without introducing check failures.
 
-4. Require the boolean `specChangeRequired` in `maestro_resolve_escalations`. Save every current answer in the active `builder` `handoff` before changing phase.
-5. Route revision decisions to `drafting-spec`. Revise the same `spec` and obtain renewed `GREEN FLAG` before a separate approval and `builder` `run`.
-6. Reject direct `spec` approval from `escalation-decisions`. Decisions without revision still return to `ready-for-builder` without renewed approval.
-7. Breaking: rename the saved decision phases to `escalation-decisions` and `finding-decisions`. Existing workflows using the previous names require manual `owner` handling.
+## 0.10.1
+
+1. Added `success`, `failure`, and `unchanged` coverage labels to the `spec` template and `Maestro` guidance. Approval validation and `handoff` formats remain unchanged.
+2. Required `Maestro` to inspect existing tests before writing `acceptance criteria` and remove criteria whose exact scenarios already have coverage. Requirements remain
+   documented in the `spec`.
+
+## 0.10.0
+
+1. Saved complete `owner` decision batches in their original `handoffs` before changing phase, including when the `spec` requires revision.
+   See [PR #38](https://github.com/emilioSp/pi-maestro/pull/38).
+2. Added `revise-spec` decisions for `verifier` `findings`, with the owner's reason and agreed requirement change. Revision takes priority over code fixes and rejections.
+3. Unified both revision paths through `drafting-spec`, with renewed `GREEN FLAG` before separate approval and another `builder` `run`. Approval is allowed only from
+   `drafting-spec`.
+4. Renamed workflow events to identify `builder` and `owner` actions. Both revision paths share `OWNER_REQUEST_SPEC_REVISION`.
+5. Breaking: supply the required boolean `specChangeRequired` when calling `maestro_resolve_escalations`.
+6. Breaking: saved decision phases are now `escalation-decisions` and `finding-decisions`. Existing workflows using older names require manual `owner` handling. No
+   automatic migration is provided.
 
 ## 0.9.5
 
-1. Added a shared check that requires every approved `spec` criterion ID in `builder` and `verifier` `handoffs`. See [PR #37](https://github.com/emilioSp/pi-maestro/pull/37).
+1. Added a shared check that requires every approved `spec` criterion ID in `builder` and `verifier` `handoffs`.
+   See [PR #37](https://github.com/emilioSp/pi-maestro/pull/37).
 2. Missing IDs reject submission before saving a report or changing phase. Extra report IDs remain allowed, and existing report validation is unchanged.
 3. Reused the raw heading rule `^### AC(\d+):`, including leading zeros and matching lines inside code blocks. No matching headings impose no new restriction.
 4. Added unit tests for extraction and one missing-ID integration test per role.
 
 ## 0.9.4
 
-1. Added numbering validation to `spec` approval. Matched `acceptance criterion` headings must start at `AC1` and continue without gaps. See [PR #36](https://github.com/emilioSp/pi-maestro/pull/36).
+1. Added numbering validation to `spec` approval. Matched `acceptance criterion` headings must start at `AC1` and continue without gaps.
+   See [PR #36](https://github.com/emilioSp/pi-maestro/pull/36).
 2. Invalid numbering rejects approval before saving the workflow and leaves all saved files unchanged. No matching headings still permits approval.
-3. Added `Maestro` guidance to correct only numbering and affected references, then retry with the existing `GREEN FLAG`. No additional `owner` approval is required before starting the `builder`.
+3. Added `Maestro` guidance to correct only numbering and affected references, then retry with the existing `GREEN FLAG`. No additional `owner` approval is required
+   before starting the `builder`.
 
 ## 0.9.3
 
-1. Added a parent `pi-subagents` availability check during activation. A matching successful version 1 `ping` reply is required within 2000 ms. See [PR #35](https://github.com/emilioSp/pi-maestro/pull/35).
-2. Failed or invalid replies, emission errors, and timeouts prevent activation. The error includes "Maestro flow requires pi-subagents installed in the Pi environment." The check makes no automatic retry.
-3. Preserved existing activation checks, UI-only notices, and unchanged session history. The availability check starts no agent, makes no model request, and does not run when turning `Maestro` off.
+1. Added a parent `pi-subagents` availability check during activation. A matching successful version 1 `ping` reply is required within 2000 ms.
+   See [PR #35](https://github.com/emilioSp/pi-maestro/pull/35).
+2. Failed or invalid replies, emission errors, and timeouts prevent activation. The error includes "Maestro flow requires pi-subagents installed in the Pi environment."
+   The check makes no automatic retry.
+3. Preserved existing activation checks, UI-only notices, and unchanged session history. The availability check starts no agent, makes no model request, and does not run
+   when turning `Maestro` off.
 
 ## 0.9.2
 
-1. Added code-quality review to `verifier` guidance for code affected by the approved change when applicable `AGENTS.md` directives exist. See [PR #34](https://github.com/emilioSp/pi-maestro/pull/34). All existing verification duties remain unchanged.
+1. Added code-quality review to `verifier` guidance for code affected by the approved change when applicable `AGENTS.md` directives exist.
+   See [PR #34](https://github.com/emilioSp/pi-maestro/pull/34). All existing verification duties remain unchanged.
 2. Required instruction-violation `findings` to identify the instruction file, quote the rule, and explain the violating code through existing evidence fields.
 3. Skip only the added review when files or code-quality directives are absent. Missing directives and personal style preferences do not produce `findings`.
 
 ## 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).
+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.
+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).
+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`.
 
@@ -57,39 +82,47 @@ This file summarizes meaningful changes to the codebase, including behavior, dat
 
 ## 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).
+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).
 2. Updated `oxlint-anti-slop` from `0.3.3` to `0.3.6`.
 3. Updated 106 test titles to match the naming rule without changing test logic.
 
 ## 0.7.2
 
 1. Renamed the constitution files to `MISSION.md`, `TECH_STACK.md`, `ROADMAP.md`, and `CHANGELOG.md`. Updated their links, package file list, and audit references.
-2. Applied consistent inline code formatting to glossary terms across the documentation. Recorded the formatting rule and its exclusions in `AGENTS.md` and the documentation audit skill.
+2. Applied consistent inline code formatting to glossary terms across the documentation. Recorded the formatting rule and its exclusions in `AGENTS.md` and the
+   documentation audit skill.
 3. Used `spec` consistently for the approved change document and removed the redundant glossary entry.
 
 ## 0.7.1
 
-1. Documented the project mission, current tech stack, `owner` responsibilities, roadmap, and codebase change history. See [PR #30](https://github.com/emilioSp/pi-maestro/pull/30).
+1. Documented the project mission, current tech stack, `owner` responsibilities, roadmap, and codebase change history.
+   See [PR #30](https://github.com/emilioSp/pi-maestro/pull/30).
 2. Replaced `TODO.md` with the roadmap and included the four project constitution documents in the npm package.
 3. Updated documentation audits to compare all current documentation and the project constitution with the working tree without requesting a comparison baseline.
 
 ## 0.7.0
 
-1. Stored multiple `escalation` questions and `owner` resolutions inside numbered `builder` `handoffs`. Earlier `handoffs` remain available as history. See [PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
-2. Breaking: replaced `maestro_open_escalation` and `maestro_resolve_escalation` with `maestro_record_builder_handoff` and `maestro_resolve_escalations`. Done `handoffs` require `escalations: []`. Standalone `escalation` storage was removed without migration or compatibility readers. `Artifact` versions remain `1.0.0`.
+1. Stored multiple `escalation` questions and `owner` resolutions inside numbered `builder` `handoffs`. Earlier `handoffs` remain available as history.
+   See [PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
+2. Breaking: replaced `maestro_open_escalation` and `maestro_resolve_escalation` with `maestro_record_builder_handoff` and `maestro_resolve_escalations`. Done `handoffs`
+   require `escalations: []`. Standalone `escalation` storage was removed without migration or compatibility readers. `Artifact` versions remain `1.0.0`.
 3. Added LCOV coverage reports and Codecov uploads from CI. See [PR #28](https://github.com/emilioSp/pi-maestro/pull/28).
 
 Reload `Maestro` extensions before starting new workflows so sessions use the updated tools.
 
 ## 0.6.2
 
-Added phase icons, theme colors, and display-only shortening of long `spec` IDs. Successful activation shows the configured agent settings in a UI-only notice, outside session history and model context. See [PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
+Added phase icons, theme colors, and display-only shortening of long `spec` IDs. Successful activation shows the configured agent settings in a UI-only notice, outside
+session history and model context. See [PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
 
 ## 0.6.0
 
-1. Removed Git requirements, checkpoints, and automatic commits from the workflow. `Maestro` uses Pi's project directory and saved workflow phase. See [PR #25](https://github.com/emilioSp/pi-maestro/pull/25).
+1. Removed Git requirements, checkpoints, and automatic commits from the workflow. `Maestro` uses Pi's project directory and saved workflow phase.
+   See [PR #25](https://github.com/emilioSp/pi-maestro/pull/25).
 2. Retained numbered `builder` and `verifier` `handoffs` and explicit `owner` `finding` decisions. Removed workflow revision counters and writer locks.
-3. Breaking: changed `artifact` formats, `handoff` paths, and tool results without migration or compatibility readers. Removed revision and commit fields. `Artifact` versions remain `1.0.0`. Interrupted and older workflows require manual `owner` handling.
+3. Breaking: changed `artifact` formats, `handoff` paths, and tool results without migration or compatibility readers. Removed revision and commit fields. `Artifact`
+   versions remain `1.0.0`. Interrupted and older workflows require manual `owner` handling.
 
 ## 0.5.2
 
@@ -97,21 +130,25 @@ Reverted the `spec` question-dependency instructions introduced in `0.5.1`. See
 
 ## 0.5.1
 
-Added instructions to resolve prerequisite decisions before asking dependent `spec` questions and to review unresolved decisions before approval. These instructions were reverted in `0.5.2`.
+Added instructions to resolve prerequisite decisions before asking dependent `spec` questions and to review unresolved decisions before approval. These instructions were
+reverted in `0.5.2`.
 
 ## 0.5.0
 
-Removed breakage checks from `specs`, `handoffs`, validation, and agent instructions. Breakage checks temporarily introduced faults to test error detection. `Acceptance criteria` retain `probes`, `expected results`, and concrete examples. See [PR #24](https://github.com/emilioSp/pi-maestro/pull/24).
+Removed breakage checks from `specs`, `handoffs`, validation, and agent instructions. Breakage checks temporarily introduced faults to test error detection.
+`Acceptance criteria` retain `probes`, `expected results`, and concrete examples. See [PR #24](https://github.com/emilioSp/pi-maestro/pull/24).
 
 Breaking: `handoffs` no longer accept `breakageStatus`. Older `handoffs` containing that field must be regenerated. `Artifact` versions remain `1.0.0`.
 
 ## 0.4.5
 
-Required a concrete example in every `acceptance criterion`, both in the `spec` and when presenting it to the `owner`. Examples identify starting conditions, an action, and the expected observable result.
+Required a concrete example in every `acceptance criterion`, both in the `spec` and when presenting it to the `owner`. Examples identify starting conditions, an action,
+and the expected observable result.
 
 ## 0.4.4
 
-Expanded Maestro's explanations of `findings` and `escalations` with code evidence, concrete examples, available choices, and their consequences. The `owner` retains control of each decision.
+Expanded Maestro's explanations of `findings` and `escalations` with code evidence, concrete examples, available choices, and their consequences. The `owner` retains
+control of each decision.
 
 ## 0.4.3
 
@@ -119,7 +156,8 @@ Removed explicit `builder` and `verifier` tool allowlists and enabled inherited
 
 ## 0.4.2
 
-Made breakage checks optional when the approved `spec` did not require them. Required acceptance `probes` remained mandatory. Breakage checks were later removed in `0.5.0`. See [PR #23](https://github.com/emilioSp/pi-maestro/pull/23).
+Made breakage checks optional when the approved `spec` did not require them. Required acceptance `probes` remained mandatory. Breakage checks were later removed in
+`0.5.0`. See [PR #23](https://github.com/emilioSp/pi-maestro/pull/23).
 
 ## 0.4.1
 
@@ -133,7 +171,8 @@ Enabled inheritance of global instructions for `builder` and `verifier` agents,
 
 ## 0.3.0
 
-Clarified `Maestro`, `builder`, and `verifier` responsibilities, `spec` and prototype revisions, permitted experiments, evidence requirements, and cleanup. See [PR #21](https://github.com/emilioSp/pi-maestro/pull/21).
+Clarified `Maestro`, `builder`, and `verifier` responsibilities, `spec` and prototype revisions, permitted experiments, evidence requirements, and cleanup.
+See [PR #21](https://github.com/emilioSp/pi-maestro/pull/21).
 
 ## 0.2.0
 
@@ -141,10 +180,14 @@ Moved TypeBox to peer dependencies and loosened Pi peer dependency version const
 
 ## 0.1.2
 
-Pinned `verifier` comparisons to a fixed `candidate` checkpoint rather than the current HEAD's parent. This checkpoint mechanism was later removed in `0.4.0`. See [PR #20](https://github.com/emilioSp/pi-maestro/pull/20).
+Pinned `verifier` comparisons to a fixed `candidate` checkpoint rather than the current HEAD's parent. This checkpoint mechanism was later removed in `0.4.0`.
+See [PR #20](https://github.com/emilioSp/pi-maestro/pull/20).
 
-Breaking: renamed `maestro_launch_builder` and `maestro_launch_verifier` to `maestro_run_builder` and `maestro_run_verifier`. Renamed the corresponding workflow events from `launch-*` to `run-*`.
+Breaking: renamed `maestro_launch_builder` and `maestro_launch_verifier` to `maestro_run_builder` and `maestro_run_verifier`. Renamed the corresponding workflow events
+from `launch-*` to `run-*`.
 
 ## 0.1.1
 
-First tagged baseline with `/maestro`, `spec` creation and approval, and foreground `builder` and `verifier` `runs`. The `owner` decides `escalation` questions and `verifier` `findings`. The workflow ends at `candidate-ready`, leaving final review to the `owner`. See [PR #14](https://github.com/emilioSp/pi-maestro/pull/14) and [PR #13](https://github.com/emilioSp/pi-maestro/pull/13).
+First tagged baseline with `/maestro`, `spec` creation and approval, and foreground `builder` and `verifier` `runs`. The `owner` decides `escalation` questions and
+`verifier` `findings`. The workflow ends at `candidate-ready`, leaving final review to the `owner`. See [PR #14](https://github.com/emilioSp/pi-maestro/pull/14)
+and [PR #13](https://github.com/emilioSp/pi-maestro/pull/13).

package/MISSION.md

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

package/README.md

@@ -8,25 +8,32 @@ Pi extension for a spec-driven multiagent development workflow.
 
 ## The idea
 
-A `specification` (`spec`) describes one reversible change. The `builder` implements it. An independent `verifier` checks every `acceptance criterion`. The `owner` performs the final review.
+A `specification` (`spec`) describes one reversible change.
+The `builder` implements it.
+An independent `verifier` checks every `acceptance criterion`.
+A `simplifier` then refactors accepted code without changing behavior.
+The `owner` performs the final review.
 
-Four principles hold the workflow together:
+Five principles hold the workflow together:
 
 1. The approved `spec` defines the required work for the `builder` and `verifier`.
 2. No agent approves its own work.
 3. Every `acceptance criterion` is checked independently.
 4. The `owner` decides requirements, scope, and unresolved questions.
+5. Each agent has one and only one role. Specific and with clear instruction.
 
 ## The roles
 
-| Role | Responsibility |
-|---|---|
-| `Owner` | Brings the problem, approves the `spec`, decides questions and `findings`, and reviews the final code. |
-| `Maestro` | Works directly with the `owner`, prepares the `spec`, runs the other agents, records decisions, and summarizes results. |
-| `Builder` | Implements the approved `spec` and checks each `acceptance criterion`. |
-| `Verifier` | Independently checks the project files against the `spec` and reports technical issues. |
+| Role         | Responsibility                                                                                                          |
+|--------------|-------------------------------------------------------------------------------------------------------------------------|
+| `Owner`      | Brings the problem, approves the `spec`, decides questions and `findings`, and reviews the final code.                  |
+| `Maestro`    | Works directly with the `owner`, prepares the `spec`, runs the other agents, records decisions, and summarizes results. |
+| `Builder`    | Implements the approved `spec` and checks each `acceptance criterion`.                                                  |
+| `Verifier`   | Independently checks the project files against the `spec` and reports technical issues.                                 |
+| `Simplifier` | Refactors accepted code for clarity without changing behavior or introducing check failures.                            |
 
-An `escalation` asks the `owner` to decide an implementation question. A `finding` records a technical issue reported by the `verifier`. The `owner` discusses both with `Maestro`, not directly with the `builder` or `verifier`.
+An `escalation` asks the `owner` to decide an implementation question. A `finding` records a technical issue reported by the `verifier`. The `owner` discusses both with
+`Maestro`, not directly with the `builder` or `verifier`.
 
 ## Prerequisites
 
@@ -34,7 +41,7 @@ An `escalation` asks the `owner` to decide an implementation question. A `findin
 2. Node.js 26 or later.
 3. Pi 1.0.0 or later.
 4. `pi-subagents` installed and enabled in Pi.
-5. Access to the configured `builder` and `verifier` models.
+5. Access to the configured `builder`, `verifier`, and `simplifier` models.
 6. A project directory that Pi trusts.
 
 ## Installation
@@ -73,26 +80,35 @@ The `owner` follows this workflow:
 6. Reads Maestro's summary at `candidate-ready` and performs the final review.
 
 `Maestro` starts the `verifier` after a successful `builder` `run`.
-Both agents run in the foreground: Pi waits for each `run` to finish and `Maestro` shows the current phase in Pi's status, while `pi-subagents` FleetView and `/subagents-fleet` show agent activity and transcripts.
+All three agents run in the foreground: Pi waits for each `run` to finish and `Maestro` shows the current phase in Pi's status, while `pi-subagents` FleetView and
+`/subagents-fleet` show agent activity and transcripts.
 
 The `owner` must not edit product files while the workflow runs.
 `Maestro` can perform temporary experiments with `owner` agreement during `spec` preparation and permitted revisions. See [Workflow](docs/workflow.md#spec-approval).
 
-An `escalation` asks the `owner` to decide an implementation question, and a `finding` records a technical issue reported by the `verifier`. The `owner` discusses both with `Maestro`, never directly with the `builder` or `verifier`.
+An `escalation` asks the `owner` to decide an implementation question, and a `finding` records a technical issue reported by the `verifier`. The `owner` discusses both
+with `Maestro`, never directly with the `builder` or `verifier`.
 `Maestro` records all current `escalation` answers or `finding` decisions in the active `handoff` before changing phase.
 
 If any decision requires a `spec` change, the workflow returns to `drafting-spec` before the `owner` and `Maestro` revise the same `spec`.
 The `owner` reviews the revised `spec` and replies `GREEN FLAG` again.
 `Maestro` records renewed approval separately before another `builder` `run`.
 
-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.
+After successful verification or rejection of all `findings`, `Maestro` starts the `simplifier`.
+Only this step requires Git. If Git readiness cannot be confirmed, `Maestro` warns and skips simplification.
+The `simplifier` selects all uncommitted code changes, including pre-existing staged, unstaged, and untracked files.
 
-The same `/maestro` command disables `Maestro` and leaves project files unchanged. Disabling `Maestro`, restarting Pi, or using `/resume` clears live session state. 
+The workflow ends at `candidate-ready`. Rejected `findings` retain their reasons and accepted failures can remain.
+Maestro's summary separates independent verification from the later simplifier's report.
+The `owner` controls later review, commits, pull requests, and merging.
+
+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
 
-`Maestro` uses default values when `.pi/maestro.json` is absent from the project root. The `owner` can add this file to change the `spec` directory, models, thinking levels, or timeouts. See [Configuration](docs/configuration.md).
+`Maestro` uses default values when `.pi/maestro.json` is absent from the project root. The `owner` can add this file to change the `spec` directory, models, thinking
+levels, or timeouts. See [Configuration](docs/configuration.md).
 
 ## Documentation