@emiliosp/pi-maestro 0.10.1 → 0.12.0

package/ADR.md

@@ -1,7 +1,6 @@
 # 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 +10,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 +25,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 +41,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 +58,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
 
@@ -65,25 +69,97 @@ Accepted. Implemented.
 
 ### Context
 
-The `owner` must decide how work continues after a reportable technical problem.
-The workflow also needs a simpler model with two `builder` outcomes.
+The `owner` must decide how work continues after a reportable technical problem. The workflow also needs a simpler model with two `builder` outcomes.
 
 ### Decision
 
-The `builder` reports only `done` or `escalation`.
-Reportable technical failures use the existing `escalation` process.
-The `owner` decides how to proceed instead of reaching a terminal failure phase.
+The `builder` reports only `done` or `escalation`. Reportable technical failures use the existing `escalation` process. The `owner` decides how to proceed instead of
+reaching a terminal failure phase.
 
 ### Consequences
 
-Reuse the existing tools, numbered `handoffs`, and batch decisions.
-Individual `probe` results retain `failed` as a valid value.
+Reuse the existing tools, numbered `handoffs`, and batch decisions. Individual `probe` results retain `failed` as a valid value.
 
-Execution and protocol errors without a valid saved result still stop the workflow.
-This decision adds no automatic recovery.
+Execution and protocol errors without a valid saved result still stop the workflow. This decision adds no automatic recovery.
 
 This breaking MVP change has no migrations, compatibility readers, deprecated aliases, or dedicated legacy-format tests.
 
 ### Evidence
 
-[Specification](.specs/20261013-101454-route-builder-failures-through-owner-escalations/spec.md) and [R-03](ROADMAP.md#r-03-route-builder-failures-through-owner-escalations).
+[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).
+
+## ADR-005: Approve a specification document set as one contract
+
+### Status
+
+Accepted. Implemented.
+
+### Context
+
+Combining motivation, behavior, and technical decisions in one `spec.md` made the document difficult to navigate. The `owner` selected separate documents by purpose, with
+`acceptance criteria` next to their requirements rather than collected at the end.
+
+### Decision
+
+Each new `spec` has required `proposal.md` for motivation and scope and `spec.md` for behavior and `acceptance criteria`. `Maestro` creates `design.md` only when
+significant approved technical decisions need recording. Routine implementation choices remain with the `builder`.
+
+One `GREEN FLAG` approves all present documents together. The entire set and its prototypes remain frozen during agent execution. Revision uses the existing
+`drafting-spec` flow and renewed approval of the complete set. No per-document approval or new workflow phase is introduced.
+
+Requirements keep level-three `REQ` headings. Their `acceptance criteria` use level-four AC headings. Relevant standalone regression criteria use level-three AC headings
+under an optional `Regression checks` section, without a requirement or `Delta` field. All criteria share continuous numbering across the document. Shared criteria are
+defined once and linked from other requirements.
+
+### Consequences
+
+Creation saves the proposal and behavioral `spec`, returns their paths and the optional design path, and leaves design creation to drafting. Approval requires the
+proposal. All three agent roles read every present document and must not create or modify a design after approval.
+
+Freezing continues to rely on agent instructions, without a file-hash manifest or file locks. Saved workflow and `handoff` formats are unchanged. Level-three standalone
+regression AC headings and nested level-four headings are both recognized. Historical `specs` are not migrated; older drafts need manual `owner` handling before new
+approval.
+
+### Evidence
+
+[Document workflow](docs/workflow.md#specification-documents), [creation](src/specs/create.ts), [approval](src/workflow/spec/markSpecReady.ts), and
+[templates](templates/).

package/CHANGELOG.md

@@ -1,55 +1,91 @@
 # 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.12.0
+
+1. Added stable `REQ` identifiers and a `Verified by` field to the `spec` template and `Maestro` guidance. Each requirement links to its `acceptance criteria` or exact
+   existing test scenarios. Review checks complete coverage and current links, including during revisions. Approval validation and `handoff` formats remain unchanged.
+2. Added per-requirement `Delta` labels: `added`, `modified`, and `removed`. Modified or removed behavior can include a brief, evidence-based `Before` description when
+   useful. Requirements state the complete required outcome; unchanged behavior remains implicit. Approval validation and `handoff` formats remain unchanged.
+3. Split new `specs` into required `proposal.md` and `spec.md`, with optional `design.md`. One `GREEN FLAG` approves and freezes the present document set; all agent roles
+   read it. Creation returns the new document paths; approval requires the proposal. Historical documents are not migrated.
+4. Placed requirement-associated `acceptance criteria` under their requirements as level-four headings. Relevant standalone regression criteria use level-three headings
+   under optional `Regression checks`, without inventing unchanged requirements. Both forms share global numbering and are required in `handoffs`. Workflow phases and
+   saved report formats remain unchanged.
+5. Removed the `Coverage` classification field from current `acceptance criteria`. Each criterion retains its `probe`, `expected result`, and example. Standalone
+   regression checks remain identified by their section; validation and report formats are unchanged.
+
+## 0.11.0
+
+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.
+
+## 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`.
+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).
+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`.
+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.
+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`.
 
@@ -60,39 +96,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
 
@@ -100,21 +144,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
 
@@ -122,7 +170,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
 
@@ -136,7 +185,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
 
@@ -144,10 +194,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,7 @@
 # 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.
-It provides a clear path from an approved `spec` to verified code and manages agent coordination for the `owner`.
+`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`.
-`Maestro` and its agents use these checks and instructions.
+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,7 +8,11 @@ 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.
 
 Five principles hold the workflow together:
 
@@ -18,16 +22,51 @@ Five principles hold the workflow together:
 4. The `owner` decides requirements, scope, and unresolved questions.
 5. Each agent has one and only one role. Specific and with clear instruction.
 
+## Inspirations
+
+Pi Maestro is inspired by concepts from [OpenSpec](https://github.com/Fission-AI/OpenSpec) and [GitHub Spec Kit](https://github.com/github/spec-kit). It adapts those
+concepts to a sequential multiagent workflow in Pi.
+
+The following official sources document the conceptual references. The links point to fixed revisions so the cited content remains inspectable.
+
+1. **The `specification` drives the code.** [Spec Kit's philosophy][spec-kit-philosophy] treats the `specification` as the primary `artifact` and code as its expression.
+   In `Maestro`, the approved `spec` defines a working contract for the `builder` and `verifier`.
+2. **Describe behavior, not routine implementation choices.** [OpenSpec's schema][openspec-schema] defines a `specification` as a behavior contract, not an implementation
+   plan. `Maestro` records required behavior, constraints, and approved architectural decisions in the `spec`, leaving routine implementation choices to the `builder`.
+3. **Use concrete, testable scenarios.** [OpenSpec's schema][openspec-schema] pairs requirements with scenarios; [Spec Kit's template][spec-kit-template] uses
+   Given/When/Then acceptance scenarios. Each `Maestro` `acceptance criterion` includes a `probe`, an `expected result`, and a concrete example.
+4. **Clarify requirements progressively.** [Spec Kit's clarify command][spec-kit-clarify] asks one question at a time and integrates accepted answers into the
+   `specification`. `Maestro` likewise asks one focused question, waits for the owner's answer, and updates the `spec` before asking the next question.
+5. **Review requirements separately from testing code.** [Spec Kit's checklist command][spec-kit-checklist] evaluates requirements for completeness, clarity, consistency,
+   and measurability, not implementation correctness. Before approval, `Maestro` reviews the `spec` for consistency, missing decisions, measurable outcomes, and
+   reproducible scenarios. The later `verifier` checks the implementation independently.
+6. **Separate motivation, behavior, and design.** [OpenSpec's schema][openspec-schema] separates these concerns and calls for `design.md` only when significant technical
+   decisions need recording, including reasons, alternatives, and risks.
+7. **Make requirement changes explicit.** [OpenSpec's schema][openspec-schema] distinguishes added, modified, removed, and renamed requirements. `Maestro` adapts this
+   concept with one `Delta` field per requirement: `added`, `modified`, or `removed`. Each requirement states the complete required outcome.
+8. **Make requirement coverage traceable.** [Spec Kit's analyze command][spec-kit-analyze] maps requirements to implementation tasks and identifies coverage gaps.
+   `Maestro` applies a related principle to verification: each requirement has a `Verified by` field linking to its `acceptance criteria`, existing tests covering exact
+   scenarios, or both. The mapping connects requirements to verification.
+
+[openspec-schema]: https://github.com/Fission-AI/OpenSpec/blob/6d04a1b58dedc95729d34e4f223d9d483aae210a/schemas/spec-driven/schema.yaml
+[spec-kit-philosophy]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/spec-driven.md
+[spec-kit-template]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/spec-template.md
+[spec-kit-clarify]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/commands/clarify.md
+[spec-kit-checklist]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/commands/checklist.md
+[spec-kit-analyze]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/commands/analyze.md
+
 ## 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
 
@@ -35,7 +74,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,27 +112,32 @@ The `owner` follows this workflow:
 5. Reviews `verifier` `findings` and chooses an action for every `finding`.
 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.
+`Maestro` starts the `verifier` after a successful `builder` `run`. 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).
 
-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`. `Maestro` records all current `escalation` answers or `finding` decisions in the active `handoff` before
+changing phase.
 
-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`.
 
-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`.
+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 workflow ends at `candidate-ready`. Rejected `findings` retain their reasons. Later changes are outside the completed verification. The `owner` controls any later Git use, pull request, and merge.
+The 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.
+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