@emiliosp/pi-maestro 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -0,0 +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.
+
+## 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.
+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).
+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`.
+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).
+
+## 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).
+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.
+
+## 0.5.2
+
+Reverted the `spec` question-dependency instructions introduced in `0.5.1`. See [commit 13cad11](https://github.com/emilioSp/pi-maestro/commit/13cad11).
+
+## 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`.
+
+## 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).
+
+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.
+
+## 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.
+
+## 0.4.3
+
+Removed explicit `builder` and `verifier` tool allowlists and enabled inherited skills. Workflow boundaries remain defined by agent instructions.
+
+## 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).
+
+## 0.4.1
+
+Enabled inheritance of global instructions for `builder` and `verifier` agents, alongside project context.
+
+## 0.4.0
+
+1. Fixed delegated `handoffs` that depended on unavailable parent session memory. See [PR #22](https://github.com/emilioSp/pi-maestro/pull/22).
+2. Removed hash-based `spec` guards and checkpoint-based `verifier` comparisons. `Spec` preservation and restoration rely on agent instructions.
+3. Refreshed the running status before delegation and required repository investigation before presenting technical decisions during `spec` preparation.
+
+## 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).
+
+## 0.2.0
+
+Moved TypeBox to peer dependencies and loosened Pi peer dependency version constraints. Kept `pi-subagents` bundled with the package.
+
+## 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).
+
+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).

package/MISSION.md

@@ -0,0 +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`.
+
+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,25 @@ 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`. The `owner` performs the final review.
 
 Four principles hold the workflow together:
 
-1. The approved spec is the contract for the builder and verifier.
+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.
+3. Every `acceptance criterion` is checked independently.
+4. The `owner` decides requirements, scope, and unresolved questions.
 
 ## 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. |
+| `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. |
 
-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,12 +34,12 @@ An escalation asks the owner to decide an implementation question. A finding rec
 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` and `verifier` models.
 6. A project directory that Pi trusts.
 
 ## Installation
 
-The owner installs `pi-subagents` and Maestro with these commands:
+The `owner` installs `pi-subagents` and `Maestro` with these commands:
 
 ```bash
 pi install npm:pi-subagents
@@ -48,52 +48,59 @@ pi install npm:@emiliosp/pi-maestro
 
 ## Usage
 
-The owner starts Pi from the project directory:
+The `owner` starts Pi from the project directory:
 
 ```bash
 cd /path/to/project
 pi
 ```
 
-Activate Maestro:
+Activate `Maestro`:
 
 ```text
 /maestro
 ```
 
-During activation, Maestro checks project trust, configuration, models, and agent availability. If a check fails, Maestro stays disabled and reports the problem.
+During activation, `Maestro` checks project trust, configuration, models, and agent availability. If a check fails, `Maestro` stays disabled and reports the problem.
 
-The owner follows this workflow:
+The `owner` follows this workflow:
 
-1. Describes one change to Maestro.
-2. Reviews the spec, including its acceptance criteria and concrete examples.
-3. Replies `GREEN FLAG` when Maestro asks for approval. Maestro records the approval and starts the builder.
-4. Reviews every current builder escalation and gives Maestro an answer and reason for each question.
-5. Reviews verifier findings and chooses an action for every finding.
+1. Describes one change to `Maestro`.
+2. Reviews the `spec`, including its `acceptance criteria` and concrete examples.
+3. Replies `GREEN FLAG` when `Maestro` asks for approval. `Maestro` records the approval and starts the `builder`.
+4. Reviews every current `builder` `escalation` and gives `Maestro` an answer and reason for each question.
+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`.
+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.
 
-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.
-If a contract change is needed during an escalation or finding decision, the owner reviews the revised spec and replies `GREEN FLAG` again. Maestro then starts another builder run.
+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`.
+If a `spec` change is needed during an `escalation` or `finding` decision, the `owner` reviews the revised `spec` and replies `GREEN FLAG` again. `Maestro` then starts 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.
+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 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
 
 The reading order is:
 
-1. [Glossary](docs/glossary.md): terms and identifiers used in specs, reports, and Maestro messages. Read this before the first workflow.
-2. [Workflow](docs/workflow.md): approvals, decisions, and how each run produces artifacts.
+1. [Glossary](docs/glossary.md): terms and identifiers used in `specs`, reports, and `Maestro` messages. Read this before the first workflow.
+2. [Workflow](docs/workflow.md): approvals, decisions, and how each `run` produces `artifacts`.
 3. [Configuration](docs/configuration.md): project paths, models, and timeouts.
 4. [Subagent integration](docs/subagent-integration.md): agent context, execution, and activity tracking.
+
+## Project constitution
+
+1. [Mission](MISSION.md): purpose, scope, and `owner` responsibilities.
+2. [Tech stack](TECH_STACK.md): runtime technologies and development tools.
+3. [Roadmap](ROADMAP.md): completed outcomes and planned priorities.
+4. [Changelog](CHANGELOG.md): meaningful codebase changes and breaking changes.

package/ROADMAP.md

@@ -0,0 +1,89 @@
+# Roadmap
+
+This roadmap records planned outcomes, not permission to implement them. The `owner` selects work and approves its `specification` before implementation starts. Detailed requirements, technical decisions, and `acceptance criteria` belong in that `specification`.
+
+"Now" is the current priority. "Next" follows it. “Later” contains uncommitted ideas with no promised order or date.
+
+Item identifiers remain stable when priorities change. The `owner` approves changes to priorities and scope.
+
+## Completed
+
+### R-01: Improve status presentation and activation feedback
+
+The status bar uses phase icons, theme colors, and shortened `spec` IDs. Successful activation shows the configured `builder` and `verifier` settings without adding the notice to session history or model context. All 12 `acceptance criteria` passed with no `verifier` `findings`; the saved workflow reached `candidate-ready`.
+
+Evidence: [Specification](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/spec.md), [verifier report](.specs/20261007-170438-update-maestro-status-bar-with-agent-models-theme-colors-and-phase-icons/handoffs/verifier/V1.json), and [merged PR #26](https://github.com/emilioSp/pi-maestro/pull/26).
+
+### R-02: Store escalations and owner decisions in builder handoffs
+
+Numbered `builder` `handoffs` contain multiple `escalation` questions and their `owner` resolutions. The `owner` resolves all current questions in one batch, while earlier `handoffs` remain available as history. All 10 `acceptance criteria` passed with no `verifier` `findings`; the saved workflow reached `candidate-ready`.
+
+Evidence: [Specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md), [verifier report](.specs/20261008-132344-store-escalations-in-builder-handoffs/handoffs/verifier/V1.json), and [merged PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
+
+### R-12: Format glossary terms consistently
+
+Applied glossary formatting across the documentation and recorded its exclusions in `AGENTS.md` and the documentation audit skill. The approved change document uses the term `spec`. The `owner` confirmed completion.
+
+Evidence: [Glossary](docs/glossary.md) and [workflow documentation](docs/workflow.md).
+
+## Now
+
+No current priority is selected.
+
+## Next
+
+### R-03: Route builder failures through owner escalations
+
+A technical `builder` failure currently ends the workflow in `builder-failed`. Replace the builder's `failed` `handoff` status and the `builder-failed` workflow phase with an `escalation`. The `owner` decides how to proceed through the existing `escalation` process.
+
+Complete when `builder` failures produce `owner` `escalations` instead of a terminal failure state. Individual checks retain `failed` as a valid result. Agent instructions, tools, workflow transitions, tests, and documentation must describe the same behavior.
+
+Automatic recovery of interrupted `runs` is outside this item. No `specification` is approved yet.
+
+## Later
+
+These items need scope review before `specification` approval. Existing behavior must be checked before adding new code. Dependencies between these items are not yet agreed.
+
+### R-04: Rename the npm package
+
+Rename `@emiliosp/pi-maestro` to `pi-maestro-sdd`. The `owner` installs the package under the new name. This item changes the package identity, not the development workflow.
+
+Complete when package metadata and installation documentation use the new name and the package is available under it. Compatibility with installations under the old name must be decided in the `specification`. No `specification` is approved yet.
+
+### R-05: Keep acceptance criterion numbering continuous
+
+When criteria are removed during `spec` preparation or revision, renumber the remaining criteria without gaps. Numbering starts at `AC1` and continues through the final criterion. Complete when the `spec` and its current references use consistent numbering.
+
+### R-06: Check subagent extensions at activation
+
+Make extension availability problems visible before a `builder` or `verifier` `run` starts. Activation already checks agent launch requirements, so first identify any missing extension checks. Complete when unavailable required subagent extensions prevent activation and the error identifies the problem.
+
+### R-07: Guide initial configuration
+
+Help the `owner` create `Maestro` configuration through an interview. `Maestro` asks questions and writes the agreed configuration. Complete when the `owner` can create a valid project configuration without writing the file manually.
+
+### R-08: Change agent models before a builder run
+
+Let the `owner` change the `builder` and `verifier` models during `spec` preparation and the `ready-for-builder` phase. The selected models apply to subsequent `runs`. Complete when the `owner` can select available models in those phases and `Maestro` uses the selections.
+
+### R-09: Define workflow reconciliation
+
+Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The recovery scope is not yet defined. The `owner` must define the intended outcome, recovery boundaries, and completion condition before this item can move forward.
+
+### R-10: Match handoff criteria to the approved spec
+
+Prevent `builder` and `verifier` reports from omitting or adding `acceptance criteria`. Each report must contain exactly the criterion IDs in the approved `spec`, with no duplicates in either place. Existing duplicate checks in reports do not establish this match.
+
+Complete when both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase. The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
+
+### R-11: Reduce temporary verifier changes
+
+Reduce the risk that verification changes the `candidate`. Existing instructions already require exact restoration, cleanup, and reporting of unresolved restoration problems. Refine the remaining guidance rather than duplicate those rules.
+
+Prefer checks that leave existing files unchanged and use separate temporary files when possible. Change an existing file only when a criterion requires it, retain its exact contents, and restore it immediately after each `probe`, including failed `probes`. Prefer check-only commands over commands that apply automatic fixes.
+
+Complete when `verifier` instructions cover these limits and require restoration and temporary-file cleanup before `handoff`. If restoration fails, the `verifier` must stop and report affected paths and remaining changes. `Maestro` currently has no file-hash restoration check; adding one requires a separate scope decision.
+
+### R-13: Show when Maestro is working
+
+Show an activity indicator in Pi's status bar while progress does not require an `owner` decision. A spinner is one option, not an agreed implementation. Complete when the status clearly distinguishes work in progress from a request for `owner` action.

package/TECH_STACK.md

@@ -0,0 +1,14 @@
+# Tech stack
+
+`Maestro` is a source-only TypeScript package that uses ECMAScript modules (ESM). Pi loads the TypeScript source directly. The package has no build step or compiled `dist/` directory.
+
+| Technology | Use |
+|---|---|
+| TypeScript | Application code and static type checks with `tsc --noEmit`. |
+| Node.js | Runtime. |
+| Pi | Extension host, agent APIs, and terminal interface. |
+| `pi-subagents` | `Builder` and `verifier` execution and activity tracking. |
+| TypeBox | Schemas and runtime validation for configuration, workflow state, tool inputs, and agent reports. |
+| Vitest with coverage | Unit tests, integration tests, and code coverage. |
+| Biome | Formatting and lint checks. |
+| Oxlint with `oxlint-anti-slop` | Additional lint and anti-slop checks. |

package/docs/configuration.md

@@ -1,12 +1,12 @@
 # Configuration
 
-Maestro reads `.pi/maestro.json` from the project root. The file is optional. Maestro uses all default values when it is absent.
+`Maestro` reads `.pi/maestro.json` from the project root. The file is optional. `Maestro` uses all default values when it is absent.
 
 ## Project root
 
-The project root is the current Pi working directory. Builder and verifier runs use this same directory.
+The project root is the current Pi working directory. `Builder` and `verifier` `runs` use this same directory.
 
-For example, if Pi starts in `/work/app/src`, Maestro reads `/work/app/src/.pi/maestro.json`. A configuration file in `/work/app/.pi/maestro.json` does not apply.
+For example, if Pi starts in `/work/app/src`, `Maestro` reads `/work/app/src/.pi/maestro.json`. A configuration file in `/work/app/.pi/maestro.json` does not apply.
 
 ## Default configuration
 
@@ -33,16 +33,16 @@ For example, if Pi starts in `/work/app/src`, Maestro reads `/work/app/src/.pi/m
 |---|---:|---|---|
 | `version` | Yes, when the file exists | `1.0.0` | Configuration format version. Only `1.0.0` is supported. |
 | `specDirectory` | No | `.specs` | Relative path below the project root. |
-| `builder` | No | Builder defaults | Overrides supported builder fields. |
+| `builder` | No | `Builder` defaults | Overrides supported `builder` fields. |
 | `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 | Overrides supported verifier fields. |
+| `builder.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each `builder` `run`. |
+| `verifier` | No | `Verifier` defaults | Overrides supported `verifier` fields. |
 | `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. |
+| `verifier.timeoutMinutes` | No | `60` | Integer from `1` to `1440`. Applies to each `verifier` `run`. |
 
-Model identifiers use the full `provider/model` form shown in the defaults. Maestro accepts these thinking levels:
+Model identifiers use the full `provider/model` form shown in the defaults. `Maestro` accepts these thinking levels:
 
 ```text
 off
@@ -67,7 +67,7 @@ Only `version` is required when the file exists. Each other field overrides its
 }
 ```
 
-This example keeps every default except the builder timeout.
+This example keeps every default except the `builder` timeout.
 
 ## Schema version
 
@@ -81,10 +81,10 @@ This example keeps every default except the builder timeout.
 2. The path stays below that root after `.` and `..` are resolved.
 3. The path is not the project root itself.
 
-For example, `specDirectory: "planning/specs"` places specs in `<project-root>/planning/specs/`. Absolute paths and paths outside the project root are rejected. The owner is responsible for directory permissions that allow Maestro to save artifacts.
+For example, `specDirectory: "planning/specs"` places `specs` in `<project-root>/planning/specs/`. Absolute paths and paths outside the project root are rejected. The `owner` is responsible for directory permissions that allow `Maestro` to save `artifacts`.
 
 ## Model access
 
-Maestro checks both configured models during activation. Each model must exist and have valid authentication.
+`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. The owner can correct the model identifier or authenticate the provider, then run `/maestro` again. Agent names and context are described in [Subagent integration](subagent-integration.md#roles-and-context).
+A model error stops activation and identifies the affected model. The `owner` can correct the model identifier or authenticate the provider, then run `/maestro` again. Agent names and context are described in [Subagent integration](subagent-integration.md#roles-and-context).

package/docs/glossary.md

@@ -4,66 +4,65 @@
 
 | Term | Meaning |
 |---|---|
-| Owner | The person who approves the spec, decides questions and findings, and performs the final review. |
-| Maestro | The coordinator that prepares the spec, runs the agents, and records owner decisions. |
-| Builder | The agent that implements the approved spec and runs its probes. |
-| Verifier | The independent agent that checks the implementation and reports technical issues. |
-| Spec | A specification that describes one change and its acceptance criteria. It is saved as `spec.md`. |
-| Contract | The approved spec that defines the required behavior and scope. |
-| Acceptance criterion (AC) | One required, observable result defined in the spec. |
-| Probe | A scenario used to test an acceptance criterion. Reports record the actual command or procedure and its outcome. |
-| Expected result | The observable result that a probe must produce. |
-| Artifact | A saved workflow file, such as a spec, or a handoff between agents. |
-| Handoff | A saved builder or verifier report with results, probe outcomes, and notes. |
-| Run or pass | One execution of the builder or verifier with a fresh conversation. |
-| Candidate | The project files created by agents after a workflow run |
-| Finding | A technical issue that the verifier records for an owner decision. |
-| Escalation | An implementation question that the builder records in its handoff for an owner decision. |
-| `GREEN FLAG` | The owner's explicit reply that approves the current spec and starts the builder. |
-| `fix-code` | An owner decision that requests code fixes without changing the approved spec. |
-| `reject` | An owner decision that declines a finding and records a reason. It does not mean that verification passed. |
-| `candidate-ready` | The completed workflow phase. The verifier reported no findings, or the owner rejected every finding with a reason. Final review remains with the owner. |
+| `Owner` | The person who approves the `spec`, decides questions and `findings`, and performs the final review. |
+| `Maestro` | The coordinator that prepares the `spec`, runs the agents, and records `owner` decisions. |
+| `Builder` | The agent that implements the approved `spec` and runs its `probes`. |
+| `Verifier` | The independent agent that checks the implementation and reports technical issues. |
+| `Spec` | A `specification` that describes one change, its scope, and its `acceptance criteria`. The approved `spec` defines the required behavior. It is saved as `spec.md`. |
+| `Acceptance criterion` (`AC`) | One required, observable result defined in the `spec`. |
+| `Probe` | A scenario used to test an `acceptance criterion`. Reports record the actual command or procedure and its outcome. |
+| `Expected result` | The observable result that a `probe` must produce. |
+| `Artifact` | A saved workflow file, such as a `spec`, or a `handoff` between agents. |
+| `Handoff` | A saved `builder` or `verifier` report with results, `probe` outcomes, and notes. |
+| `Run` or `pass` | One execution of the `builder` or `verifier` with a fresh conversation. |
+| `Candidate` | The project files created by agents after a workflow `run` |
+| `Finding` | A technical issue that the `verifier` records for an `owner` decision. |
+| `Escalation` | An implementation question that the `builder` records in its `handoff` for an `owner` decision. |
+| `GREEN FLAG` | The owner's explicit reply that approves the current `spec` and starts the `builder`. |
+| `fix-code` | An `owner` decision that requests code fixes without changing the approved `spec`. |
+| `reject` | An `owner` decision that declines a `finding` and records a reason. It does not mean that verification passed. |
+| `candidate-ready` | The completed workflow phase. The `verifier` reported no `findings`, or the `owner` rejected every `finding` with a reason. Final review remains with the `owner`. |
 
 ## Identifiers and file names
 
-An ID is an identifier that names one record. These labels refer to records within one spec, not across all workflows.
+An ID is an identifier that names one record. These labels refer to records within one `spec`, not across all workflows.
 
 | Label | Meaning | Location or scope |
 |---|---|---|
-| `<spec-id>` | The identifier shared by the spec and its workflow artifacts. | The directory name under `<project-root>/.specs/` by default. |
-| `B1`, `B2` | Builder handoff 1, builder handoff 2. | `handoffs/builder/B1.json`, `handoffs/builder/B2.json`. |
-| `V1`, `V2` | Verifier handoff 1, verifier handoff 2. | `handoffs/verifier/V1.json`, `handoffs/verifier/V2.json`. |
-| `E1`, `E2` | Escalation 1, escalation 2 within one builder report. | Entries in that report's `escalations` list. |
-| `F1`, `F2` | Finding 1, finding 2 within one verifier report. | Entries in that report's `findings` list. |
-| `AC1`, `AC2` | Acceptance criterion 1, acceptance criterion 2. | Criteria in `spec.md` and the matching `acceptanceCriteria` entries in reports. |
-| `B1/E1` | Escalation 1 in builder handoff 1. | The question with `id: "E1"` inside `handoffs/builder/B1.json`. |
-| `V1/F2` | Finding 2 in verifier handoff 1. | The finding with `id: "F2"` inside `handoffs/verifier/V1.json`. |
+| `<spec-id>` | The identifier shared by the `spec` and its workflow `artifacts`. | The directory name under `<project-root>/.specs/` by default. |
+| `B1`, `B2` | `Builder` `handoff` 1, `builder` `handoff` 2. | `handoffs/builder/B1.json`, `handoffs/builder/B2.json`. |
+| `V1`, `V2` | `Verifier` `handoff` 1, `verifier` `handoff` 2. | `handoffs/verifier/V1.json`, `handoffs/verifier/V2.json`. |
+| `E1`, `E2` | `Escalation` 1, `escalation` 2 within one `builder` report. | Entries in that report's `escalations` list. |
+| `F1`, `F2` | `Finding` 1, `finding` 2 within one `verifier` report. | Entries in that report's `findings` list. |
+| `AC1`, `AC2` | `Acceptance criterion` 1, `acceptance criterion` 2. | Criteria in `spec.md` and the matching `acceptanceCriteria` entries in reports. |
+| `B1/E1` | `Escalation` 1 in `builder` `handoff` 1. | The question with `id: "E1"` inside `handoffs/builder/B1.json`. |
+| `V1/F2` | `Finding` 2 in `verifier` `handoff` 1. | The `finding` with `id: "F2"` inside `handoffs/verifier/V1.json`. |
 
-All paths in this table are relative to the spec directory unless stated otherwise. The [configuration](configuration.md#path-rules) can change the directory that contains specs.
+All paths in this table are relative to the `spec` directory unless stated otherwise. The [configuration](configuration.md#path-rules) can change the directory that contains `specs`.
 
-The `AC` prefix is the template's naming convention. Criterion IDs must be unique within the spec. Reports use the exact IDs from the spec.
+The `AC` prefix is the template's naming convention. Criterion IDs must be unique within the `spec`. Reports use the exact IDs from the `spec`.
 
-Builder and verifier numbers count saved handoffs in separate sequences.
+`Builder` and `verifier` numbers count saved `handoffs` in separate sequences.
 
 ## Escalation references
 
 Read `B1/E1` as "escalation 1 in builder report 1". `B1` selects `handoffs/builder/B1.json`. `E1` selects the entry with `id: "E1"` in its `escalations` list.
 
-Escalation numbers restart at `E1` in each builder report. `B1/E1` and `B2/E1` identify different questions, even if they concern the same topic.
+`Escalation` numbers restart at `E1` in each `builder` report. `B1/E1` and `B2/E1` identify different questions, even if they concern the same topic.
 
-The owner discusses every current question with Maestro. Maestro records all answers and reasons together in that same builder report. See [Escalations](workflow.md#escalations) for the available choices and their effects.
+The `owner` discusses every current question with `Maestro`. `Maestro` records all answers and reasons together in that same `builder` report. See [Escalations](workflow.md#escalations) for the available choices and their effects.
 
 ## Finding references
 
 Read `V1/F2` as "finding 2 in verifier report 1". `V1` selects `handoffs/verifier/V1.json`. `F2` selects the entry with `id: "F2"` in its `findings` list.
 
-Finding numbers restart at `F1` in each verifier report. `V1/F2` and `V2/F2` identify different records, even if they describe a similar issue.
+`Finding` numbers restart at `F1` in each `verifier` report. `V1/F2` and `V2/F2` identify different records, even if they describe a similar issue.
 
-For example, a finding about a saved title can appear in a Maestro message like this:
+For example, a `finding` about a saved title can appear in a `Maestro` message like this:
 
 > Verifier report 1, finding 2 (`V1/F2`): the title returns to "Draft" after saving "Ready" and reopening the item.
 > Acceptance criterion 1 (`AC1`) requires the saved title to remain "Ready".
 
 In this example, the finding's `acceptanceCriterion: "AC1"` connects the issue to criterion `AC1` in `spec.md`.
 
-The owner discusses the issue with Maestro. Maestro records the decision in the same verifier report. See [Findings](workflow.md#findings) for the available choices and their effects.
+The `owner` discusses the issue with `Maestro`. `Maestro` records the decision in the same `verifier` report. See [Findings](workflow.md#findings) for the available choices and their effects.

package/docs/subagent-integration.md

@@ -1,6 +1,6 @@
 # Subagent integration
 
-Maestro uses `pi-subagents` to run the builder and verifier as child sessions. A child session is a separate Pi session for one role. The owner stays in the main Maestro conversation.
+`Maestro` uses `pi-subagents` to run the `builder` and `verifier` as child sessions. A child session is a separate Pi session for one role. The `owner` stays in the main `Maestro` conversation.
 
 ## Roles and context
 
@@ -8,27 +8,27 @@ The package supplies both roles and the tools that save their results:
 
 | Role | Agent name | Definition |
 |---|---|---|
-| Builder | `maestro.builder` | [`agents/builder.md`](../agents/builder.md) |
-| Verifier | `maestro.verifier` | [`agents/verifier.md`](../agents/verifier.md) |
+| `Builder` | `maestro.builder` | [`agents/builder.md`](../agents/builder.md) |
+| `Verifier` | `maestro.verifier` | [`agents/verifier.md`](../agents/verifier.md) |
 
-Each run starts with a fresh conversation, not the main session's conversation history. Both agents inherit project instructions, the owner's global `AGENTS.md`, and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
+Each `run` starts with a fresh conversation, not the main session's conversation history. Both agents inherit project instructions, the owner's global `AGENTS.md`, and available skills. The global file normally lives at `~/.pi/agent/AGENTS.md`.
 
-Maestro supplies the spec ID, project directory, model, thinking level, and timeout. The agents read the approved spec and saved artifacts to understand the work. Earlier artifacts provide context, not proof.
+`Maestro` supplies the `spec` ID, project directory, model, thinking level, and timeout. The agents read the approved `spec` and saved `artifacts` to understand the work. Earlier `artifacts` provide context, not proof.
 
-The owner does not call builder or verifier tools directly. Maestro starts the builder after `GREEN FLAG` approval and the verifier after successful builder completion.
+The `owner` does not call `builder` or `verifier` tools directly. `Maestro` starts the `builder` after `GREEN FLAG` approval and the `verifier` after successful `builder` completion.
 
 ## Following a run
 
-Runs stay in the foreground and occur one at a time. Pi waits for each run to finish before Maestro continues. Maestro does not run the builder and verifier in parallel or in the background.
+`Runs` stay in the foreground and occur one at a time. Pi waits for each `run` to finish before `Maestro` continues. `Maestro` does not run the `builder` and `verifier` in parallel or in the background.
 
 Maestro's Pi status shows the workflow phase. `pi-subagents` FleetView shows agent activity, and `/subagents-fleet` opens its inspector for details and transcripts.
 
-Each child saves its result through Maestro tools before returning. Builder results produce `B1.json`, `B2.json`, and so on. Verifier results produce `V1.json`, `V2.json`, and so on. See [Stored artifacts](workflow.md#stored-artifacts) for the creation sequence.
+Each child saves its result through `Maestro` tools before returning. `Builder` results produce `B1.json`, `B2.json`, and so on. `Verifier` results produce `V1.json`, `V2.json`, and so on. See [Stored artifacts](workflow.md#stored-artifacts) for the creation sequence.
 
-If a run fails or returns without a valid saved result, Maestro reports the error and stops. Manual follow-up is described in [Limitations](workflow.md#limitations).
+If a `run` fails or returns without a valid saved result, `Maestro` reports the error and stops. Manual follow-up is described in [Limitations](workflow.md#limitations).
 
 ## External configuration
 
-The `pi-subagents` extension must be installed and enabled in Pi. Builder and verifier model choices, thinking levels, and timeouts come from [Maestro configuration](configuration.md). Other `pi-subagents` configuration remains the owner's responsibility.
+The `pi-subagents` extension must be installed and enabled in Pi. `Builder` and `verifier` model choices, thinking levels, and timeouts come from [Maestro configuration](configuration.md). Other `pi-subagents` configuration remains the owner's responsibility.
 
-Maestro does not invoke Git to manage its workflow. `pi-subagents` can use Git internally.
+`Maestro` does not invoke Git to manage its workflow. `pi-subagents` can use Git internally.

package/docs/workflow.md

@@ -1,32 +1,32 @@
 # Workflow
 
-Maestro manages one spec-driven workflow in the current Pi session. The owner works directly with Maestro.
+`Maestro` manages one spec-driven workflow in the current Pi session. The `owner` works directly with `Maestro`.
 
-The approved `spec.md` is the contract for the change. It defines behavior, scope, constraints, technical decisions, and acceptance criteria.
+The approved `spec.md` defines behavior, scope, constraints, technical decisions, and `acceptance criteria` for the change.
 
-An acceptance criterion contains a probe, an expected result, and an example. A probe is a scenario used to test behavior.
+An `acceptance criterion` contains a `probe`, an `expected result`, and an example. A `probe` is a scenario used to test behavior.
 
-A handoff is a saved report from a builder or verifier run. It records the result, probe outcomes, and notes.
+A `handoff` is a saved report from a `builder` or `verifier` `run`. It records the result, `probe` outcomes, and notes.
 
-A builder handoff can contain escalations, which are questions that need owner decisions. 
-A verifier handoff can contain findings, which are technical issues.
+A `builder` `handoff` can contain `escalations`, which are questions that need `owner` decisions.
+A `verifier` `handoff` can contain `findings`, which are technical issues.
 
 ## Roles
 
 | Role | Responsibility |
 |---|---|
-| Owner | Decides requirements, scope, technical decisions, spec approval, escalation answers, and finding decisions. Performs the final review. |
-| Maestro | Prepares the spec with the owner, records workflow progress, runs agents, presents issues, and saves owner decisions. |
-| Builder | Implements the approved spec and runs every probe. Reports completion, an escalation, or a technical failure. |
-| Verifier | Independently runs every probe against the live project files. Reports findings without repairing product code. |
+| `Owner` | Decides requirements, scope, technical decisions, `spec` approval, `escalation` answers, and `finding` decisions. Performs the final review. |
+| `Maestro` | Prepares the `spec` with the `owner`, records workflow progress, runs agents, presents issues, and saves `owner` decisions. |
+| `Builder` | Implements the approved `spec` and runs every `probe`. Reports completion, an `escalation`, or a technical failure. |
+| `Verifier` | Independently runs every `probe` against the live project files. Reports `findings` without repairing product code. |
 
-Builder and verifier runs are sequential foreground operations. Each starts with a fresh conversation and reads the spec and saved artifacts.
+`Builder` and `verifier` `runs` are sequential foreground operations. Each starts with a fresh conversation and reads the `spec` and saved `artifacts`.
 
 Maestro's Pi status shows the current phase. `pi-subagents` FleetView and `/subagents-fleet` show live agent activity and transcripts.
 
 ## Main flow
 
-The green arrows and lines show the path without escalations or findings.
+The green arrows and lines show the path without `escalations` or `findings`.
 
 ```mermaid
 flowchart TD
@@ -48,9 +48,9 @@ flowchart TD
     findings -->|None| candidate
 
     buildOutcome -->|Escalation| ownerEscalation{Owner decides every question}
-    ownerEscalation -->|Contract unchanged| recordEscalation[Maestro records all answers]
+    ownerEscalation -->|Spec unchanged| recordEscalation[Maestro records all answers]
     recordEscalation --> build
-    ownerEscalation -->|Contract changes| reviseSpec[Owner and Maestro revise the spec]
+    ownerEscalation -->|Spec changes| reviseSpec[Owner and Maestro revise the spec]
     reviseSpec --> approval
 
     buildOutcome -->|Failed| stopped[Workflow stops for manual owner follow-up]
@@ -69,124 +69,124 @@ flowchart TD
 
 ## Workflow phases
 
-Each spec has a `workflow.json` file that records its identity and current phase. The saved phase controls the next permitted workflow action. An agent's final message alone does not establish a completed action.
+Each `spec` has a `workflow.json` file that records its identity and current phase. The saved phase controls the next permitted workflow action. An agent's final message alone does not establish a completed action.
 
-The default path is `.specs/<spec-id>/workflow.json`. The spec directory is [configurable](configuration.md).
+The default path is `.specs/<spec-id>/workflow.json`. The `spec` directory is [configurable](configuration.md).
 
 | Phase | Meaning |
 |---|---|
-| `drafting-spec` | The owner and Maestro are preparing the initial spec. |
-| `ready-for-builder` | The approved spec or recorded owner decisions permit a builder run. |
-| `builder-running` | A builder run is active. |
-| `escalation-decision` | The owner must decide how to handle every escalation question. |
-| `builder-failed` | The builder recorded a technical failure. The workflow stops. |
-| `ready-for-verifier` | The builder completed the work and the verifier can start. |
-| `verifier-running` | A verifier run is active. |
-| `findings-decision` | The owner must decide how to handle every current finding. |
-| `candidate-ready` | The verifier reported no findings, or the owner rejected every finding with a reason. The workflow is complete. |
+| `drafting-spec` | The `owner` and `Maestro` are preparing the initial `spec`. |
+| `ready-for-builder` | The approved `spec` or recorded `owner` decisions permit a `builder` `run`. |
+| `builder-running` | A `builder` `run` is active. |
+| `escalation-decision` | The `owner` must decide how to handle every `escalation` question. |
+| `builder-failed` | The `builder` recorded a technical failure. The workflow stops. |
+| `ready-for-verifier` | The `builder` completed the work and the `verifier` can start. |
+| `verifier-running` | A `verifier` `run` is active. |
+| `findings-decision` | The `owner` must decide how to handle every current `finding`. |
+| `candidate-ready` | The `verifier` reported no `findings`, or the `owner` rejected every `finding` with a reason. The workflow is complete. |
 
 ## Spec approval
 
-For the initial spec:
+For the initial `spec`:
 
-1. Maestro creates `spec.md` and `workflow.json` in `drafting-spec` and prepares the spec with the owner.
-2. The owner reviews the requirements, scope, technical decisions, and acceptance criteria.
-3. Maestro asks the owner to inspect the current `spec.md` and reply `GREEN FLAG` to approve it and start the builder.
-4. After that reply, Maestro saves `ready-for-builder` and starts the builder in the foreground.
+1. `Maestro` creates `spec.md` and `workflow.json` in `drafting-spec` and prepares the `spec` with the `owner`.
+2. The `owner` reviews the requirements, scope, technical decisions, and `acceptance criteria`.
+3. `Maestro` asks the `owner` to inspect the current `spec.md` and reply `GREEN FLAG` to approve it and start the `builder`.
+4. After that reply, `Maestro` saves `ready-for-builder` and starts the `builder` in the foreground.
 
-Approval freezes the spec as the contract. The spec and its visual prototypes remain unchanged during builder and verifier execution. Contract revisions are limited to the decision phases described in [Spec revision](#spec-revision).
+Approval freezes the `spec`. The `spec` and its visual prototypes remain unchanged during `builder` and `verifier` execution. `Spec` revisions are limited to the decision phases described in [Spec revision](#spec-revision).
 
 ## Acceptance criteria
 
-Each acceptance criterion has a unique ID and describes one observable result.
+Each `acceptance criterion` has a unique ID and describes one observable result.
 
 Each criterion contains these parts:
 
 | Part | Content |
 |---|---|
-| Probe | Starting conditions and the action or observation that checks the behavior. |
-| Expected result | The measurable result the probe observes. |
-| Example | Concrete starting conditions, an input or action, and the exact expected result. |
+| `Probe` | Starting conditions and the action or observation that checks the behavior. |
+| `Expected result` | The measurable result the `probe` observes. |
+| Example | Concrete starting conditions, an input or action, and the exact `expected result`. |
 
 ## Escalations
 
-An escalation returns an implementation decision to the owner. It does not necessarily mean that a technical failure occurred. Examples include undefined behavior, a conflict with the spec, or a possible scope change.
+An `escalation` returns an implementation decision to the `owner`. It does not necessarily mean that a technical failure occurred. Examples include undefined behavior, a conflict with the `spec`, or a possible scope change.
 
-The builder saves all questions from one pass in the `escalations` list of its numbered handoff. Maestro identifies each question with both report and escalation IDs, such as `B1/E1`. See [Escalation references](glossary.md#escalation-references) for their scope.
+The `builder` saves all questions from one `pass` in the `escalations` list of its numbered `handoff`. `Maestro` identifies each question with both report and `escalation` IDs, such as `B1/E1`. See [Escalation references](glossary.md#escalation-references) for their scope.
 
-Maestro presents each question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decision` while the owner decides how to proceed.
+`Maestro` presents each question, evidence, options, consequences, and next steps. The workflow pauses in `escalation-decision` while the `owner` decides how to proceed.
 
-If the contract stays unchanged, the owner gives Maestro an answer and reason for every current question. The owner can select a listed option or give a different decision.
+If the `spec` stays unchanged, the `owner` gives `Maestro` an answer and reason for every current question. The `owner` can select a listed option or give a different decision.
 
-| Owner choice | Result |
+| `Owner` choice | Result |
 |---|---|
-| Keep the current contract | Maestro saves all answers and reasons together in the active builder handoff, returns to `ready-for-builder`, and starts another builder run. |
-| Change the contract | The owner and Maestro revise the same spec and obtain renewed approval before another builder run. |
+| Keep the current `spec` | `Maestro` saves all answers and reasons together in the active `builder` `handoff`, returns to `ready-for-builder`, and starts another `builder` `run`. |
+| Change the `spec` | The `owner` and `Maestro` revise the same `spec` and obtain renewed approval before another `builder` `run`. |
 
-Owner decisions update only the questions' `resolution` fields. The handoff's other content and earlier handoffs remain unchanged.
+`Owner` decisions update only the questions' `resolution` fields. The handoff's other content and earlier `handoffs` remain unchanged.
 
 ## Findings
 
-Every current finding requires an owner decision, regardless of severity. Maestro explains the issue, evidence, practical effect, and available choices.
+Every current `finding` requires an `owner` decision, regardless of severity. `Maestro` explains the issue, evidence, practical effect, and available choices.
 
-Maestro identifies each finding with its report and finding IDs. For example, `V1/F2` means finding 2 in verifier report `V1.json`. The finding is an entry in that file's `findings` list, not a separate `F2.json` file. Finding numbers restart at `F1` in each verifier report. See [Finding references](glossary.md#finding-references) for a worked example.
+`Maestro` identifies each `finding` with its report and `finding` IDs. For example, `V1/F2` means `finding` 2 in `verifier` report `V1.json`. The `finding` is an entry in that file's `findings` list, not a separate `F2.json` file. `Finding` numbers restart at `F1` in each `verifier` report. See [Finding references](glossary.md#finding-references) for a worked example.
 
-Maestro records owner decisions in the same verifier report, e.g. decisions about `V1/F2` update `V1.json`, not a new `V2.json`. A new verifier result creates the next report (`V2.json`).
+`Maestro` records `owner` decisions in the same `verifier` report, e.g. decisions about `V1/F2` update `V1.json`, not a new `V2.json`. A new `verifier` result creates the next report (`V2.json`).
 
 | Decision | Result |
 |---|---|
-| `reject` | Records the owner's reason. If every finding is rejected, the workflow reaches `candidate-ready`. |
-| `fix-code` | Keeps the current spec and returns to `ready-for-builder` for code fixes. |
+| `reject` | Records the owner's reason. If every `finding` is rejected, the workflow reaches `candidate-ready`. |
+| `fix-code` | Keeps the current `spec` and returns to `ready-for-builder` for code fixes. |
 
-Any `fix-code` decision requires another builder run, including when other findings are rejected. After the builder completes the fixes, the verifier checks the work again.
+Any `fix-code` decision requires another `builder` `run`, including when other `findings` are rejected. After the `builder` completes the fixes, the `verifier` checks the work again.
 
-If the contract must change, the owner and Maestro use [Spec revision](#spec-revision) instead. Earlier findings then become historical context.
+If the `spec` must change, the `owner` and `Maestro` use [Spec revision](#spec-revision) instead. Earlier `findings` then become historical context.
 
 ## Spec revision
 
-Contract revisions are allowed only in `escalation-decision` or `findings-decision`. Maestro revises the same spec with the owner, including its prototypes when needed.
+`Spec` revisions are allowed only in `escalation-decision` or `findings-decision`. `Maestro` revises the same `spec` with the `owner`, including its prototypes when needed.
 
-After review and cleanup, Maestro asks the owner to inspect the revised spec and reply `GREEN FLAG` again. Maestro then records `ready-for-builder` and starts another builder run.
+After review and cleanup, `Maestro` asks the `owner` to inspect the revised `spec` and reply `GREEN FLAG` again. `Maestro` then records `ready-for-builder` and starts another `builder` `run`.
 
-Previous escalations, findings, and handoffs remain as historical context. The new (revised) spec is the contract for subsequent work.
+Previous `escalations`, `findings`, and `handoffs` remain as historical context. The revised `spec` defines the requirements for subsequent work.
 
 ## Verification boundary
 
-The verifier can make temporary changes for probes. Before submitting its handoff, it restores the exact original contents of affected files and removes only files it created.
+The `verifier` can make temporary changes for `probes`. Before submitting its `handoff`, it restores the exact original contents of affected files and removes only files it created.
 
-Cleanup relies on the verifier. If cleanup cannot finish safely, the verifier stops and reports the remaining changes.
+Cleanup relies on the `verifier`. If cleanup cannot finish safely, the `verifier` stops and reports the remaining changes.
 
 ## Workflow completion
 
-The workflow ends at `candidate-ready`. Maestro summarizes the changes, verification results, rejected findings and reasons, and relevant builder notes from the saved artifacts.
+The workflow ends at `candidate-ready`. `Maestro` summarizes the changes, verification results, rejected `findings` and reasons, and relevant `builder` notes from the saved `artifacts`.
 
-The owner performs the final review and controls any later Git use, pull request, or merge. Changes after completion are outside the completed verification.
+The `owner` performs the final review and controls any later Git use, pull request, or merge. Changes after completion are outside the completed verification.
 
 ## Stored artifacts
 
-An artifact is a saved workflow file. Maestro creates the spec directory with `spec.md`, `workflow.json`, and an empty `prototypes/` directory. Builder and verifier handoff directories appear when those results are saved.
+An `artifact` is a saved workflow file. `Maestro` creates the `spec` directory with `spec.md`, `workflow.json`, and an empty `prototypes/` directory. `Builder` and `verifier` `handoff` directories appear when those results are saved.
 
-The agents submit results through Maestro tools instead of writing the reports directly. A successful submission saves the result and updates the phase in `workflow.json` before the agent returns.
+The agents submit results through `Maestro` tools instead of writing the reports directly. A successful submission saves the result and updates the phase in `workflow.json` before the agent returns.
 
-Builder (`B`) and verifier (`V`) numbers count saved handoffs within one spec. Each sequence starts at 1 and advances independently. Every saved builder outcome, including escalation, creates the next `B` report. Revising the same spec keeps these sequences. A new spec starts new sequences.
+`Builder` (`B`) and `verifier` (`V`) numbers count saved `handoffs` within one `spec`. Each sequence starts at 1 and advances independently. Every saved `builder` outcome, including `escalation`, creates the next `B` report. Revising the same `spec` keeps these sequences. A new `spec` starts new sequences.
 
-Escalation (`E`) numbers identify questions within a builder handoff. They restart at `E1` in each handoff.
+`Escalation` (`E`) numbers identify questions within a `builder` `handoff`. They restart at `E1` in each `handoff`.
 
-For example, a repair cycle with successful builder results produces these files:
+For example, a repair cycle with successful `builder` results produces these files:
 
 | Step | Action | Report saved or updated |
 |---|---|---|
-| 1 | The builder completes the implementation. | Creates `handoffs/builder/B1.json`. |
-| 2 | The verifier checks it and reports findings. | Creates `handoffs/verifier/V1.json`. |
-| 3 | The owner decides every finding and requests a code fix. | Updates decisions in the existing `V1.json`. |
-| 4 | A new builder run completes the fixes. | Creates `handoffs/builder/B2.json`. |
-| 5 | A new verifier run checks the work again and reports no findings. | Creates `handoffs/verifier/V2.json`. The workflow reaches `candidate-ready`. |
+| 1 | The `builder` completes the implementation. | Creates `handoffs/builder/B1.json`. |
+| 2 | The `verifier` checks it and reports `findings`. | Creates `handoffs/verifier/V1.json`. |
+| 3 | The `owner` decides every `finding` and requests a code fix. | Updates decisions in the existing `V1.json`. |
+| 4 | A new `builder` `run` completes the fixes. | Creates `handoffs/builder/B2.json`. |
+| 5 | A new `verifier` `run` checks the work again and reports no `findings`. | Creates `handoffs/verifier/V2.json`. The workflow reaches `candidate-ready`. |
 
-If the first builder run escalates, it creates `B1.json` with its questions. Owner answers update `B1.json`. The next saved builder result creates `B2.json`.
+If the first `builder` `run` escalates, it creates `B1.json` with its questions. `Owner` answers update `B1.json`. The next saved `builder` result creates `B2.json`.
 
-A builder report with `status: failed` stops the workflow without a verifier run. If an agent returns without a valid saved result, Maestro stops and reports the error. See [Limitations](#limitations).
+A `builder` report with `status: failed` stops the workflow without a `verifier` `run`. If an agent returns without a valid saved result, `Maestro` stops and reports the error. See [Limitations](#limitations).
 
-The default layout after multiple runs is:
+The default layout after multiple `runs` is:
 
 ```text
 .specs/<spec-id>/
@@ -202,18 +202,18 @@ The default layout after multiple runs is:
 └── prototypes/
 ```
 
-Maestro uses the latest saved handoff in each role's sequence as the active result. New results do not replace earlier numbered reports. Earlier reports remain available as context, not as proof for the current run. Owner decisions update the active builder or verifier handoff without creating another numbered report.
+`Maestro` uses the latest saved `handoff` in each role's sequence as the active result. New results do not replace earlier numbered reports. Earlier reports remain available as context, not as proof for the current `run`. `Owner` decisions update the active `builder` or `verifier` `handoff` without creating another numbered report.
 
 ## Limitations
 
 ### No small models
-The owner must not use small models with a `low` thinking level for this workflow. These combinations cannot reliably follow the workflow rules. 
+The `owner` must not use small models with a `low` thinking level for this workflow. These combinations cannot reliably follow the workflow rules.
 One example is `gpt-luna-6` with `thinking: "low"`.
 
-Moreover, the workflow works well with a defined harness: tests, lint for code rules, anti-slop checks for unwanted patterns, and `AGENTS.md`. Maestro does not supply these project-specific checks.
+Moreover, the workflow works well with a defined harness: tests, lint for code rules, anti-slop checks for unwanted patterns, and `AGENTS.md`. `Maestro` does not supply these project-specific checks.
 
 ### No automatic rollback
-Maestro provides no automatic rollback, repair, or recovery for failed or interrupted workflows. The files that remain are available for owner inspection. The owner handles the workflow manually.
+`Maestro` provides no automatic rollback, repair, or recovery for failed or interrupted workflows. The files that remain are available for `owner` inspection. The `owner` handles the workflow manually.
 
 ### No reconciliation
-Disabling Maestro, restarting Pi, or using `/resume` clears live Maestro session state and leaves project files unchanged. Maestro starts disabled in a new or resumed session. Reactivating it does not reconstruct or resume a saved workflow.
+Disabling `Maestro`, restarting Pi, or using `/resume` clears live `Maestro` session state and leaves project files unchanged. `Maestro` starts disabled in a new or resumed session. Reactivating it does not reconstruct or resume a saved workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",
@@ -33,6 +33,10 @@
     "src/",
     "!**/*.test.ts",
     "docs/",
+    "MISSION.md",
+    "TECH_STACK.md",
+    "ROADMAP.md",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],