@emiliosp/pi-maestro 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emilio Spatola
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# pi-maestro
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pi extension for a spec-driven multiagent development workflow.
+
+![Maestro workflow](docs/maestro.png)
+
+## The idea
+
+One spec describes one small reversible change. An agent builds it. A second, independent agent regenerates each acceptance criterion from scratch. The owner performs the final review and controls the Git flow after the candidate is ready.
+
+Four principles hold the workflow together:
+
+- The approved spec is the contract for the builder and verifier.
+- No agent approves its own work.
+- A check that passes must be able to fail. Each acceptance criterion states the breakage that must break it.
+- An agent never decides for the owner, and never guesses.
+
+## The roles
+
+- **Owner** — You. You bring the problem, decide every escalation and every finding, review the final code, and control the Git flow after the candidate is ready. You never talk to a builder or a verifier.
+- **Maestro** — The agent you talk to. It writes the spec with you, spawns and supervises the other agents, records your decisions, and summarizes the results.
+- **Builder** — The agent that implements one spec. It never verifies its own work.
+- **Verifier** — The agent that verifies if the builder implementation is technically compliant to the spec.
+
+## Prerequisites
+
+- macOS
+- Node.js 26 or later
+- Git
+- Pi 1.0.0 or later
+- `pi-subagents` 0.68.0 or later, installed and enabled in Pi
+- Access to the configured builder and verifier models
+- A trusted Git repository
+
+## Installation
+
+Install `pi-subagents` and Maestro:
+
+```bash
+pi install npm:pi-subagents
+pi install npm:@emiliosp/pi-maestro
+```
+
+## Usage
+
+Maestro uses the current Git checkout and branch. It does not create, switch, name, or validate branches. It does not create worktrees. If you want to work on a feature branch, create and check out that branch before you start.
+
+Start Pi from the repository:
+
+```bash
+cd /path/to/project
+pi
+```
+
+Activate Maestro:
+
+```text
+/maestro
+```
+
+The same command disables Maestro. Disabling Maestro leaves the current branch, workflow files, and artifacts unchanged. During activation, Maestro makes sure that the repository, configuration, models, and agents are ready. If an item fails, Maestro stays disabled and reports the problem.
+
+Follow this workflow:
+
+1. Activate Maestro with `/maestro`.
+2. Describe the change.
+3. Review the spec with Maestro.
+4. Approve the spec.
+5. Commit the approved `spec.md` and `workflow.json` on the current branch.
+6. Ask Maestro to launch the builder.
+7. Review builder escalations and answer them.
+8. Review verifier findings and choose an action for each finding.
+9. When the workflow reaches `candidate-ready`, read Maestro's summary of the results and Pull Request facts.
+10. Review or change the candidate as needed, then open a Pull Request from the current branch and choose the merge method.
+
+Do not change product code while the workflow runs. The workflow is complete when it reaches `candidate-ready`. No final tool call is needed. Changes after completion are outside the Maestro review.
+
+If an escalation or finding requires a contract change, edit and approve `spec.md`, then call `maestro_mark_spec_ready`. The workflow returns to `ready-for-builder` on the same branch. A technical builder failure stops the workflow and requires owner follow-up.
+
+Builder and verifier runs stay in the foreground. Pi waits for each run before you continue the conversation. Maestro shows the current phase in Pi's status. Use pi-subagents FleetView or `/subagents-fleet` to inspect live activity and the transcript.
+
+Restarting Pi, disabling Maestro, or using `/resume` clears live session state. Maestro does not recover an incomplete workflow from `workflow.json`.
+
+## Configuration
+
+Maestro uses default values when `.pi/maestro.json` is absent. Add this file when you need to change the spec directory, models, thinking levels, or timeouts. See [Configuration](docs/configuration.md).
+
+## Documentation
+
+- [Workflow](docs/workflow.md)
+- [Configuration](docs/configuration.md)
+- [Subagent integration](docs/subagent-integration.md)

package/agents/builder.md

@@ -0,0 +1,40 @@
+---
+name: builder
+package: maestro
+description: Implements an owner-approved Maestro specification.
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - bash
+  - edit
+  - write
+  - maestro_record_builder_handoff
+  - maestro_open_escalation
+systemPromptMode: replace
+inheritProjectContext: true
+inheritGlobalContext: false
+inheritSkills: false
+completionGuard: false
+allowNestedSubagents: false
+subagentOnlyExtensions: ../extensions/maestro-subagent.ts
+---
+
+You are the builder. Work only in the current Git checkout and branch selected by the owner. Use the explicit spec ID supplied by Maestro. Start from the owner-committed `ready-for-builder` workflow state. The owner approves the spec and decides requirements, scope, escalations, and findings. Maestro coordinates the workflow. Do not delegate work to another agent or approve your own work.
+
+Read the approved spec, its relevant prototypes, the current workflow state, applicable `AGENTS.md` files, and any resolved escalations or findings supplied for this pass. On a repair pass, fix every finding with `rejection: null`. Leave rejected findings alone. Follow repository commands and technical rules in the applicable `AGENTS.md` files; do not invent required commands.
+
+The approved `spec.md` is the contract between the owner, Maestro, the builder, and the verifier. Follow its constraints, out-of-scope items, technical decisions, requirements, and acceptance criteria. Do not silently change the contract. You may choose implementation details that the contract leaves open, and you may change any product file within the Git root needed to meet the contract, but do not add unrelated work. Do not edit the spec, prototypes, workflow state, or handoff files directly. Use only the Maestro subagent tools for protocol artifacts.
+
+A discovery that is worth preserving but does not require an owner decision belongs in the builder handoff `notes`. Notes are a deliberate record of significant information, not a log of every observation. A significant discovery that requires the owner's attention and a choice belongs in an escalation, even when it is not a technical failure or an implementation blocker. If there are no meaningful options or no owner decision, do not open an escalation or block the workflow; continue the work and use `notes` only when the discovery is worth preserving. Do not open an escalation for routine implementation details already covered by the contract. An escalation must explain the discovery, the question, the available options, their consequences, the next step, and a recommendation when justified. After opening an escalation, commit the current work and protocol artifacts, then stop.
+
+Implement every acceptance criterion. For each one, run its probe and observe the expected result. Apply its specified safe, temporary breakage in the current checkout, run the *same* probe and observe failure, restore the breakage fully, then run the same probe again and observe success. Never apply breakage to production data or services. Do not change a probe, expected result, breakage, or the approved design to make a test pass. For visual claims, produce reproducible evidence using the spec and repository instructions: compare with a prototype when required, or probe the existing surface. Run applicable repository checks. Record the actual probe command or procedure and a concise status for every criterion, including any not run. Do not put full logs or secrets in the handoff.
+
+Finish in exactly one of these ways:
+
+1. When the implementation and every probe, breakage, and restored probe succeed, call `maestro_record_builder_handoff` with `status: done`, a summary, every criterion with `probeStatus: passed` and `breakageStatus: confirmed`, and any useful notes. Commit the implementation, generated workflow state, and terminal handoff together. Stop.
+2. If an owner decision is needed, including a significant discovery that requires the owner's attention and presents meaningful options, call `maestro_open_escalation`. State the question, context and evidence, concrete options with consequences and next steps, and a recommendation when justified. This is not limited to technical failures or blockers. Commit the generated escalation and workflow state with the current work, then stop. Do not wait for a reply in this pass.
+3. If you cannot finish for a technical reason that does not require an owner decision, call `maestro_record_builder_handoff` with `status: failed`. Include a specific failure reason and honest per-criterion statuses; mark unrun work `not-run`. Commit the current work, generated workflow state, and terminal handoff together, then stop. Do not claim `done` with missing evidence.
+
+Do not write more than one terminal handoff in this pass. If a child tool rejects the artifact or a commit fails, address the error without bypassing the tool or claiming completion.

package/agents/verifier.md

@@ -0,0 +1,31 @@
+---
+name: verifier
+package: maestro
+description: Independently verifies a Maestro candidate against its specification.
+tools:
+  - read
+  - grep
+  - find
+  - ls
+  - bash
+  - edit
+  - write
+  - maestro_record_verifier_handoff
+systemPromptMode: replace
+inheritProjectContext: true
+inheritGlobalContext: false
+inheritSkills: false
+completionGuard: false
+allowNestedSubagents: false
+subagentOnlyExtensions: ../extensions/maestro-subagent.ts
+---
+
+You are the independent verifier. Work only in the current Git checkout and branch selected by the owner. Use the explicit spec ID supplied by Maestro. The owner decides what to do with findings; Maestro coordinates. Do not delegate work, approve or reject findings, or issue a pass/fail verdict.
+
+Read the approved spec and relevant prototypes, the current workflow state, applicable `AGENTS.md` files, the builder handoff, and earlier verifier handoffs and owner decisions for this spec. The approved `spec.md` is the contract between the owner, Maestro, the builder, and you. Verify the candidate against that contract; do not silently reinterpret or expand it. Use the handoffs for context, not as proof. Follow repository commands and technical rules in the applicable `AGENTS.md` files; do not invent required commands. Do not modify the spec, prototypes, workflow state, or handoff files directly. Use the Maestro child tool for the terminal artifact.
+
+The candidate is the parent of the `verifier-running` checkpoint. Independently regenerate evidence for *every* acceptance criterion from that candidate commit. Run each probe and observe its expected result. Apply the specified safe, temporary breakage only in the current checkout, run the *same* probe and observe failure, restore every breakage fully, then rerun the same probe and observe success. Do not change approved probes, expected results, or breakages. Verify visual claims with reproducible evidence using the spec and repository instructions, including prototype comparisons when required. Run applicable repository checks. Record the actual command or procedure and honest probe and breakage statuses for every criterion, including `not-run` when necessary. Never treat the builder's results as evidence.
+
+Do not repair product code, even if a probe fails. Use `edit` and `write` only to apply and restore temporary breakages. Record technical observations as findings with evidence, not questions or decisions. Give each finding a unique `F1`, `F2`, etc. ID, an acceptance criterion ID when relevant (otherwise `null`), severity, confidence, concise summary, and source plus observation. Every criterion with a probe other than `passed` or breakage other than `confirmed` needs a related finding. A finding always starts with `rejection: null`; only Maestro can record an owner rejection. Use `findings: []` only if every probe passes and every breakage is confirmed. Do not include full logs or secrets.
+
+Before handoff, restore all temporary changes and check staged, unstaged, and untracked product files against the candidate commit in the current checkout. Product files must match it exactly, whether findings are empty or not. Call `maestro_record_verifier_handoff` with a summary, evidence for every criterion, findings, and notes. If it reports `PRODUCT_FILES_MODIFIED`, inspect and restore the remaining changes yourself and retry; the tool will not restore them. Do not overwrite unrelated changes you cannot safely restore. Never bypass the tool or commit a modified product file. Do not run `git commit`; the handoff tool commits only `workflow.json` and `handoffs/verifier.json` after a successful product check. Stop after a successful handoff. If you cannot restore the candidate or record the handoff, stop and report the blocker to Maestro without claiming verification is complete.

package/docs/configuration.md

@@ -0,0 +1,109 @@
+# Configuration
+
+Maestro reads project configuration from:
+
+```text
+.pi/maestro.json
+```
+
+The file is optional. Maestro uses all default values when the file is absent.
+
+## Default configuration
+
+```json
+{
+  "version": "1.0.0",
+  "specDirectory": ".specs",
+  "builder": {
+    "model": "openai-codex/gpt-5.6-luna",
+    "thinking": "max",
+    "timeoutMinutes": 60
+  },
+  "verifier": {
+    "model": "openai-codex/gpt-6.1-sol",
+    "thinking": "high",
+    "timeoutMinutes": 60
+  }
+}
+```
+
+Maestro does not configure a branch, a target branch, or a worktree directory. It uses the current Git checkout and branch.
+
+## Fields
+
+| Field | Required | Default | Rules |
+|---|---:|---|---|
+| `version` | Yes, when the file exists | `1.0.0` | Semantic version of the configuration schema. Must be supported by the installed Maestro release. |
+| `specDirectory` | No | `.specs` | Relative path inside the Git repository. |
+| `builder` | No | Builder defaults | May contain supported builder overrides. |
+| `builder.model` | No | `openai-codex/gpt-5.6-luna` | Full `provider/model` identifier. |
+| `builder.thinking` | No | `max` | One supported thinking level. |
+| `builder.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each builder run. |
+| `verifier` | No | Verifier defaults | May contain supported verifier overrides. |
+| `verifier.model` | No | `openai-codex/gpt-6.1-sol` | Full `provider/model` identifier. |
+| `verifier.thinking` | No | `high` | One supported thinking level. |
+| `verifier.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each verifier run. |
+
+Supported thinking levels:
+
+```text
+off
+minimal
+low
+medium
+high
+xhigh
+max
+```
+
+Each object accepts only the documented fields. Unknown fields stop activation and produce an error.
+
+When a run reaches its timeout, Maestro reports it and does not treat the run as complete.
+
+## Partial configuration
+
+Only `version` is required when the file exists. Each other field overrides its matching default.
+
+```json
+{
+  "version": "1.0.0",
+  "builder": {
+    "timeoutMinutes": 90
+  }
+}
+```
+
+This example keeps every default except the builder timeout.
+
+## Schema version
+
+`version` identifies the configuration schema. It is separate from the npm package version.
+
+The current schema version is `1.0.0`. An unsupported major version stops Maestro activation. Minor and patch versions represent compatible schema changes supported by the installed Maestro release.
+
+## Path rules
+
+`specDirectory` must meet these rules:
+
+- The path is relative to the Git repository root.
+- The path points below the repository root.
+- The resolved path stays inside the repository, including through symlinks.
+
+An invalid path stops Maestro activation. Maestro validates the path while it loads configuration, but does not create the directory then. Workflow actions create a spec directory and its artifacts only when they need them.
+
+## Model access
+
+Maestro checks both configured models during activation. Each model must exist and have valid authentication.
+
+A model error stops activation and identifies the affected model. Update the configuration or authenticate the provider, then run `/maestro` again.
+
+## Fixed values
+
+Agent names:
+
+```text
+maestro.builder
+maestro.verifier
+```
+
+Maestro does not require a branch naming pattern. The owner selects the current branch before using the workflow.

package/docs/subagent-integration.md

@@ -0,0 +1,53 @@
+# Subagent integration
+
+Maestro uses `pi-subagents` to run the builder and verifier as child sessions. A child session is a separate Pi session that receives one role and one task. An agent definition is a Markdown file that gives the child its role, tools, and system prompt. A system prompt is the instruction text that the child follows.
+
+## Agent definitions
+
+The package contains two agent definitions:
+
+1. [`agents/builder.md`](../agents/builder.md) defines the builder role.
+2. [`agents/verifier.md`](../agents/verifier.md) defines the verifier role.
+
+Each file has YAML frontmatter at the top. Frontmatter is the YAML block between the two `---` lines. The text after the frontmatter is the system prompt.
+
+The frontmatter defines the agent name, tools, context rules, and child-only extensions. The system prompt defines the role rules and the work procedure.
+
+## Package registration
+
+`package.json` registers the agent directory with Pi:
+
+```json
+{
+  "pi": {
+    "subagents": {
+      "agents": [
+        "./agents"
+      ]
+    }
+  }
+}
+```
+
+The `pi.subagents.agents` field tells `pi-subagents` to scan `./agents` for agent definitions. Pi scans nested directories as well.
+
+The `package` and `name` fields in each file form the runtime name that delegation uses. The builder file has `package: maestro` and `name: builder`, so its runtime name is `maestro.builder`. The verifier runtime name is `maestro.verifier`.
+
+## Launch flow
+
+When the owner launches the builder, the integration follows these steps:
+
+1. The owner calls `maestro_launch_builder`.
+2. `src/tools/main/launch-builder.ts` prepares the workflow and emits a delegation request.
+3. The request sets `agent: AGENTS.BUILDER`.
+4. `AGENTS.BUILDER` has the value `maestro.builder` in `src/config/schema.ts`.
+5. `pi-subagents` resolves `maestro.builder` to `agents/builder.md`.
+6. The child receives the system prompt and the tools from that agent definition.
+
+Maestro also passes the explicit spec ID, the current repository root, the configured model, the thinking level, the timeout, and a fresh context. The task text tells the builder to read the applicable `AGENTS.md` files.
+
+The verifier uses the same name mapping with `AGENTS.VERIFIER` and `maestro.verifier`.
+
+## Subagent extension
+
+Both agent files set `subagentOnlyExtensions` to `../extensions/maestro-subagent.ts`. This field tells `pi-subagents` to load the extension only in the child session for that agent.

package/docs/workflow.md

@@ -0,0 +1,260 @@
+# Workflow
+
+Maestro manages one spec-driven development workflow in the current session.
+
+The approved `spec.md` is the contract between the owner, Maestro, the builder, and the verifier. It defines the intended behavior, constraints, technical decisions, and acceptance criteria. Implementation details that the contract leaves open are decided during the work. Changes to the contract's behavior, scope, or approved decisions require an owner-approved revision.
+
+The owner works with Maestro. Builder and verifier communicate with Maestro through repository handoffs. Maestro prepares the spec, updates workflow state, starts the builder and verifier, and records owner decisions.
+
+Maestro uses the current Git checkout and branch. It does not create, switch, name, or validate a branch. It does not create worktrees. If the owner starts on `main`, `master`, or another branch, all workflow commits use that branch.
+
+## Roles
+
+### Owner
+
+The owner is the human in the loop. Every decision that needs human judgment returns to the owner.
+
+The owner has final authority over:
+
+- Requirements
+- Scope
+- Technical decisions recorded in the spec
+- Escalation answers
+- Finding decisions
+- Spec approval
+- Git flow after the candidate is ready
+- Final Pull Request and merge
+
+The owner does not change product code while the workflow is running. The owner may revise `spec.md` while the workflow is blocked, as described below.
+
+### Maestro
+
+Maestro:
+
+- Discusses the change with the owner
+- Writes and reviews the spec with the owner
+- Creates workflow artifacts on the current branch
+- Starts the builder and verifier
+- Reads their handoffs
+- Presents escalations and findings to the owner
+- Records explicit owner decisions
+- Summarizes the results and facts for a Pull Request when the candidate is ready
+
+Maestro does not know or manage a target branch.
+
+### Builder
+
+The builder works on the current branch with a fresh context. It reads the active spec, implements the approved change, and runs every acceptance criterion.
+
+For each criterion, the builder runs the probe, applies the approved temporary breakage, confirms that the same probe fails, restores the implementation, and confirms that the probe passes again.
+
+The builder ends a run with one of these outcomes:
+
+- `done`
+- `failed`
+- An escalation
+
+The builder uses `maestro_record_builder_handoff` or `maestro_open_escalation`, then commits the implementation, generated workflow state, and handoff together.
+
+### Verifier
+
+The verifier works on the current branch with a fresh context. It reads the active spec and available artifacts. Historical artifacts provide context, not proof; the verifier decides which information is still applicable to the active spec.
+
+The verifier independently regenerates every probe and breakage from the candidate. It does not repair product code and does not commit through Bash.
+
+Before the verifier starts, Maestro commits a `verifier-running` checkpoint. The candidate is the parent of that checkpoint's `HEAD`.
+
+The verifier applies and restores temporary breakages. `maestro_record_verifier_handoff` compares product files with that parent commit. If the product is unchanged, the tool writes `verifier.json` and `workflow.json` and commits only those protocol files. If product changes remain, the tool returns `PRODUCT_FILES_MODIFIED` and does not write or commit the handoff.
+
+There is no numbered verifier pass and no separate verifier branch. The current artifact is always:
+
+```text
+.specs/<spec-id>/handoffs/verifier.json
+```
+
+Git preserves earlier verifier handoffs.
+
+Builder and verifier runs are foreground operations. Pi waits for each run before the owner continues. Maestro's Pi status shows the current phase, and pi-subagents FleetView shows the live activity and transcript.
+
+## Main flow
+
+Happy path is highlighted in green.
+
+```mermaid
+flowchart TD
+    spec[Owner and Maestro write one spec]
+    ready[Maestro marks the spec ready]
+    approval[Owner commits spec and workflow state on the current branch]
+    build[Builder works on the current branch]
+    buildOutcome{How does the builder run end?}
+
+    spec --> ready
+    ready --> approval
+    approval --> build
+    build --> buildOutcome
+
+    buildOutcome -->|Escalation| escalation[Builder records an escalation and stops]
+    escalation --> ownerAnswer[Owner decides]
+    ownerAnswer --> escalationOutcome{Does the contract change?}
+    escalationOutcome -->|No| recordContinue[Maestro records the resolution]
+    recordContinue --> build
+    escalationOutcome -->|Yes| reviseSpec[Owner revises and approves spec.md]
+    reviseSpec --> approval
+
+    buildOutcome -->|Failed| builderFailed[Maestro reports the error and stops]
+    builderFailed --> abandoned[Owner handles the failed workflow manually]
+
+    buildOutcome -->|Done| verify[Verifier regenerates every proof]
+    verify --> findings{Findings?}
+
+    findings -->|None| candidate[Candidate ready]
+    findings -->|One or more| ownerFindings[Owner reviews every finding]
+
+    ownerFindings -->|Reject all with reasons| candidate
+    ownerFindings -->|Code must change| returnBuilder[Maestro records the decision]
+    returnBuilder --> build
+    ownerFindings -->|Spec must change| reviseSpec
+
+    candidate --> summary[Maestro summarizes results and Pull Request facts]
+    summary --> ownerReview[Owner reviews the candidate]
+    ownerReview -->|Changes needed| adjust[Owner changes code, spec, or acceptance criteria]
+    adjust --> ownerReview
+    ownerReview -->|Satisfied| pullRequest[Owner opens a Pull Request]
+    pullRequest --> merge[Owner merges the Pull Request]
+
+    linkStyle 0,1,2,3,13,14,15,21,22,23,24,25,26 stroke:#2e7d32,stroke-width:3px
+```
+
+## Workflow phases
+
+Maestro stores the current phase in `.specs/<spec-id>/workflow.json` by default.
+
+| Phase | Meaning |
+|---|---|
+| `drafting-spec` | Owner and Maestro are preparing the initial spec. |
+| `ready-for-builder` | The owner approved the spec and it awaits a builder run. |
+| `builder-running` | A builder run is active. |
+| `escalation-decision` | The owner must decide how to resolve the active escalation. |
+| `builder-failed` | The builder ended the run with a failure. |
+| `ready-for-verifier` | Builder work is ready for independent verification. |
+| `verifier-running` | A verifier run is active. |
+| `findings-decision` | The owner must decide how to handle verifier findings. |
+| `candidate-ready` | The candidate passed verification or all findings were rejected with reasons. This is the last persisted Maestro phase. |
+
+A session can have one active Maestro workflow. A workflow in `candidate-ready` is complete from Maestro's point of view. Completed or abandoned workflows can remain under the spec directory.
+
+Disabling Maestro, restarting Pi, or using `/resume` clears live session state. Maestro does not resume an incomplete workflow from `workflow.json`; the owner must clean it up manually.
+
+## Spec approval and revision
+
+Maestro treats `spec.md` as opaque Markdown. It checks the workflow phase and file existence, but does not parse the spec or compare its content with an earlier version.
+
+For the initial spec:
+
+1. Maestro creates `spec.md` and `workflow.json` in `drafting-spec`.
+2. The owner reviews and approves the spec.
+3. `maestro_mark_spec_ready` changes the phase to `ready-for-builder`.
+4. The owner commits `spec.md` and `workflow.json` on the current branch.
+
+The committed `spec.md` and `workflow.json` are the approved contract for the builder and verifier. The contract is immutable during a builder or verifier pass. When a discovery shows that the contract must change, the owner makes an explicit revision and approval before the next pass.
+
+A contract revision is allowed only from these blocked phases:
+
+- `escalation-decision`
+- `findings-decision`
+
+`builder-failed` is a sink state. Maestro reports the technical error and stops the workflow; it does not retry the builder or revise the spec from that state.
+
+The owner edits and approves `spec.md`, then calls `maestro_mark_spec_ready` directly from the blocked phase. The tool changes the phase to `ready-for-builder`. There is no separate revision phase and no new `specId`.
+
+The previous escalation or finding becomes inactive. Its artifact remains in the branch as historical context. Builder and verifier decide whether historical artifacts apply to the current spec.
+
+The workflow does not store a separate spec version. The active contract is the current `spec.md`; Git preserves earlier versions and approvals.
+
+Immediately before each builder launch, Maestro calculates the SHA-256 of the current `spec.md` and stores it only in live session state. Builder handoff and escalation tools compare the current file with that baseline. A spec revision receives its new baseline only after the owner approves it. Restart, `/resume`, and deactivation discard the live baseline.
+
+## Acceptance criterion simplicity principle
+
+Each acceptance criterion must prove exactly one thing.
+
+```text
+Probe
+  How the behavior is verified.
+
+Expected result
+  What the probe must observe.
+
+Breakage
+  How to prove that the probe detects a broken behavior.
+```
+
+Each distinct error behavior required by the spec must have its own acceptance criterion. Equivalent inputs that produce the same behavior can share one criterion.
+
+Builder and verifier both run the probe, apply the specified safe breakage, run the same probe again, restore the breakage, and run the probe again. They must restore every temporary change before the handoff.
+
+## Escalations
+
+An escalation is the way Maestro brings a significant implementation discovery to the owner's attention and asks for a decision. It is not necessarily a technical failure, an error, or a blocker.
+
+An escalation is relevant when the work presents meaningful alternatives with different consequences. Examples include a conflict between the approved contract and the repository, behavior that the contract does not define, a material architectural alternative, a possible scope change, or a decision that affects verification or reversibility.
+
+Each escalation presents a question, context and evidence, available options, consequences, next steps, and an optional recommendation. While an escalation is unresolved, the workflow is paused in `escalation-decision` and the owner must decide how to proceed.
+
+The owner can choose one of two paths:
+
+- Continue with the current contract. Maestro records the decision and returns the workflow to `ready-for-builder` for another builder run.
+- Change the approved contract. The owner revises and approves `spec.md`, then calls `maestro_mark_spec_ready`. The workflow returns to `ready-for-builder` on the same branch and with the same `specId`.
+
+Each escalation remains in the workflow history as references.
+
+## Findings
+
+A finding records a technical issue found by the verifier. Every finding blocks progress until the owner makes a decision.
+
+| Decision | Result |
+|---|---|
+| `reject` | Requires and records the owner’s reason. When every finding is rejected, the candidate becomes ready. |
+| `fix-code` | Keeps the current spec and starts another builder run. |
+| Spec must change | The owner revises `spec.md` from `findings-decision`; previous findings become historical. |
+
+When decisions are mixed, any `fix-code` decision starts another builder run. If the approved contract must change, the owner uses the same spec revision flow instead of resolving obsolete findings.
+
+## Completion and Pull Request
+
+The workflow ends at `candidate-ready` after a verifier run with no findings, or after the owner rejects every finding with a reason.
+
+The operations that produce this phase, `maestro_record_verifier_handoff` and `maestro_resolve_findings`, own the required checks:
+
+1. Before writing the transition, they make sure that the resulting handoff matches the spec identity and workflow revision, with no active findings.
+2. They reject changes outside the expected protocol files. The verifier must also restore the product to the verified candidate.
+3. They commit only the expected protocol files and return success only when the checkout is clean.
+
+No final tool call or checkpoint is needed. `candidate-ready` is the last persisted Maestro phase.
+
+Maestro reads the artifacts and Git information to summarize the changes, verification results, rejected findings and reasons, and applicable builder notes. The summary includes the current branch and final `HEAD`. Rejected findings are owner decisions, not proof that verification passed.
+
+The summary does not change files or workflow state, create commits, or run verification again. The owner controls the Git flow, review, Pull Request, and merge. Maestro does not squash, stage, merge, create, or remove branches. It does not create worktrees.
+
+## Stored artifacts
+
+When the owner creates a spec, Maestro creates the spec directory with `spec.md` and `workflow.json`. It also creates the empty `handoffs/escalations/` and `prototypes/` directories. Later workflow actions create the artifact files.
+
+The default spec directory contains:
+
+```text
+.specs/<spec-id>/
+├── spec.md
+├── workflow.json
+├── handoffs/
+│   ├── builder.json
+│   ├── verifier.json
+│   └── escalations/
+│       ├── E1.json
+│       └── ...
+└── prototypes/
+```
+
+- `builder.json` and `verifier.json` represent the current handoffs and can be overwritten by later runs. 
+- Builder handoff `notes` contain curated significant discoveries that did not require an owner decision; Maestro surfaces the applicable notes in the final workflow summary. 
+- Escalations remain in the history directory. 
+- Earlier versions of all artifacts remain in Git commits.