@emiliosp/pi-maestro 0.11.0 → 0.13.0

package/ADR.md

@@ -1,9 +1,8 @@
 # Architecture decision records
 
-An Architecture Decision Record (ADR) explains an important architectural choice, its context, and its consequences.
-This file contains one numbered record per decision.
+An Architecture Decision Record (ADR) explains an important architectural choice, its context, and its consequences. This file contains one numbered record per decision.
 
-Requirements and routine project rules belong in the [roadmap](ROADMAP.md) or other relevant documentation.
+Requirements and routine project rules belong in the [roadmap](https://linear.app/emilio-spatola/team/MAESTRO/overview) or other relevant documentation.
 
 When a new decision replaces an accepted decision, add a new record, mark the earlier record as superseded, and link both records.
 
@@ -31,8 +30,8 @@ manual `owner` handling.
 
 ### Evidence
 
-[Commit deae41c](https://github.com/emilioSp/pi-maestro/commit/deae41ce66a3f2c76859209c44165e7ddd0f3a72), [Changelog 0.6.0](CHANGELOG.md#060),
-and [workflow completion](docs/workflow.md#workflow-completion).
+[Commit deae41c](https://github.com/emilioSp/pi-maestro/commit/deae41ce66a3f2c76859209c44165e7ddd0f3a72), [Changelog 0.6.0](CHANGELOG.md#060), and
+[workflow completion](docs/workflow.md#workflow-completion).
 
 ## ADR-002: Store escalation decisions in builder handoffs
 
@@ -59,8 +58,8 @@ There are no migration procedures, fallback readers, or deprecated aliases. `Art
 
 ### Evidence
 
-[Repository-only specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md), [Commit dda6eb5](https://github.com/emilioSp/pi-maestro/commit/dda6eb5b3ab76ba175112c3c565c70be747d7344),
-and [escalation workflow](docs/workflow.md#escalations).
+[Repository-only specification](.specs/20261008-132344-store-escalations-in-builder-handoffs/spec.md),
+[Commit dda6eb5](https://github.com/emilioSp/pi-maestro/commit/dda6eb5b3ab76ba175112c3c565c70be747d7344), and [escalation workflow](docs/workflow.md#escalations).
 
 ## ADR-003: Route builder failures through owner escalations
 
@@ -70,36 +69,31 @@ Accepted. Implemented.
 
 ### Context
 
-The `owner` must decide how work continues after a reportable technical problem.
-The workflow also needs a simpler model with two `builder` outcomes.
+The `owner` must decide how work continues after a reportable technical problem. The workflow also needs a simpler model with two `builder` outcomes.
 
 ### Decision
 
-The `builder` reports only `done` or `escalation`.
-Reportable technical failures use the existing `escalation` process.
-The `owner` decides how to proceed instead of reaching a terminal failure phase.
+The `builder` reports only `done` or `escalation`. Reportable technical failures use the existing `escalation` process. The `owner` decides how to proceed instead of
+reaching a terminal failure phase.
 
 ### Consequences
 
-Reuse the existing tools, numbered `handoffs`, and batch decisions.
-Individual `probe` results retain `failed` as a valid value.
+Reuse the existing tools, numbered `handoffs`, and batch decisions. Individual `probe` results retain `failed` as a valid value.
 
-Execution and protocol errors without a valid saved result still stop the workflow.
-This decision adds no automatic recovery.
+Execution and protocol errors without a valid saved result still stop the workflow. This decision adds no automatic recovery.
 
 This breaking MVP change has no migrations, compatibility readers, deprecated aliases, or dedicated legacy-format tests.
 
 ### Evidence
 
-[Specification](.specs/20261013-101454-route-builder-failures-through-owner-escalations/spec.md)
-and [R-03](ROADMAP.md#r-03-route-builder-failures-through-owner-escalations).
+[Specification](.specs/20261013-101454-route-builder-failures-through-owner-escalations/spec.md) and
+[MAESTRO-7](https://linear.app/emilio-spatola/issue/MAESTRO-7/route-builder-failures-through-owner-escalations).
 
 ## ADR-004: Require Git only for the simplifier
 
 ### Status
 
-Accepted. Implemented through R-21.
-Supersedes [ADR-001](#adr-001-keep-the-workflow-independent-of-git).
+Accepted. Implemented through MAESTRO-24. Supersedes [ADR-001](#adr-001-keep-the-workflow-independent-of-git).
 
 ### Context
 
@@ -125,9 +119,74 @@ without an error. The skip transition is defined in `src/workflow/transitions.ts
 Activation does not predict whether simplification will be skipped. The same readiness decision applies after successful verification and after the `owner` rejects all
 current `findings`. Rejected `findings` retain their reasons and do not become passed verification.
 
-The `simplifier` uses Git to select all staged, unstaged, and untracked code changes, including pre-existing changes.
-There is no spec-specific starting commit or `builder` file list. Required caller updates can include initially unchanged files.
+The `simplifier` uses Git to select all staged, unstaged, and untracked code changes, including pre-existing changes. There is no spec-specific starting commit or
+`builder` file list. Required caller updates can include initially unchanged files.
 
 ### Evidence
 
-[R-21](ROADMAP.md#r-21-add-a-simplifier-with-one-clear-purpose-per-agent) and the [specification](.specs/20261016-090319-add-a-dedicated-simplifier-after-verification/spec.md).
+[MAESTRO-24](https://linear.app/emilio-spatola/issue/MAESTRO-24/add-a-simplifier-with-one-clear-purpose-per-agent) and the
+[specification](.specs/20261016-090319-add-a-dedicated-simplifier-after-verification/spec.md).
+
+## ADR-005: Approve a specification document set as one contract
+
+### Status
+
+Accepted. Implemented.
+
+### Context
+
+Combining motivation, behavior, and technical decisions in one `spec.md` made the document difficult to navigate. The `owner` selected separate documents by purpose, with
+`acceptance criteria` next to their requirements rather than collected at the end.
+
+### Decision
+
+Each new `spec` has required `proposal.md` for motivation and scope and `spec.md` for behavior and `acceptance criteria`. `Maestro` creates `design.md` only when
+significant approved technical decisions need recording. Routine implementation choices remain with the `builder`.
+
+One `GREEN FLAG` approves all present documents together. The entire set and its prototypes remain frozen during agent execution. Revision uses the existing
+`drafting-spec` flow and renewed approval of the complete set. No per-document approval or new workflow phase is introduced.
+
+Requirements keep level-three `REQ` headings. Their `acceptance criteria` use level-four AC headings. Relevant standalone regression criteria use level-three AC headings
+under an optional `Regression checks` section, without a requirement or `Delta` field. All criteria share continuous numbering across the document. Shared criteria are
+defined once and linked from other requirements.
+
+### Consequences
+
+Creation saves the proposal and behavioral `spec`, returns their paths and the optional design path, and leaves design creation to drafting. Approval requires the
+proposal. All three agent roles read every present document and must not create or modify a design after approval.
+
+Freezing continues to rely on agent instructions, without a file-hash manifest or file locks. Saved workflow and `handoff` formats are unchanged. Level-three standalone
+regression AC headings and nested level-four headings are both recognized. Historical `specs` are not migrated; older drafts need manual `owner` handling before new
+approval.
+
+### Evidence
+
+[Document workflow](docs/workflow.md#specification-documents), [creation](src/specs/create.ts), [approval](src/workflow/spec/markSpecReady.ts), and
+[templates](templates/).
+
+## ADR-006: Maintain the roadmap in Linear
+
+### Status
+
+Accepted. Implemented.
+
+### Context
+
+The `owner` moved roadmap items from the repository to Linear, selected the dedicated `MAESTRO` team, and requested removal of the local roadmap file and redundant
+identifiers. This moves the source of truth for planning outside Git.
+
+### Decision
+
+Maintain the roadmap only in [Linear](https://linear.app/emilio-spatola/team/MAESTRO/overview), using Linear issue identifiers. Keep the roadmap location and maintenance
+instructions in `AGENTS.md`, without a local copy of the issue list.
+
+Approved `specifications`, verification evidence, the changelog, and architectural decisions remain in the repository.
+
+### Consequences
+
+Reading or updating current roadmap state requires Linear access. Git history remains evidence of earlier plans, not the current roadmap. Imported issues retain
+commit-pinned links to repository evidence. Removing the local roadmap also removes it from the published package.
+
+### Evidence
+
+[Linear roadmap](https://linear.app/emilio-spatola/team/MAESTRO/overview) and [repository instructions](AGENTS.md).

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 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.
 
+## 0.13.0
+
+1. Automatically turn off `Maestro` after successfully delivering the final summary of a completed workflow, including when Git is unavailable and simplification is
+   skipped. Clear live tools, status, instructions, and active `spec` selection while preserving saved workflow files and other extensions. See
+   [MAESTRO-26](https://linear.app/emilio-spatola/issue/MAESTRO-26).
+
+## 0.12.0
+
+1. Added stable `REQ` identifiers and a `Verified by` field to the `spec` template and `Maestro` guidance. Each requirement links to its `acceptance criteria` or exact
+   existing test scenarios. Review checks complete coverage and current links, including during revisions. Approval validation and `handoff` formats remain unchanged.
+2. Added per-requirement `Delta` labels: `added`, `modified`, and `removed`. Modified or removed behavior can include a brief, evidence-based `Before` description when
+   useful. Requirements state the complete required outcome; unchanged behavior remains implicit. Approval validation and `handoff` formats remain unchanged.
+3. Split new `specs` into required `proposal.md` and `spec.md`, with optional `design.md`. One `GREEN FLAG` approves and freezes the present document set; all agent roles
+   read it. Creation returns the new document paths; approval requires the proposal. Historical documents are not migrated.
+4. Placed requirement-associated `acceptance criteria` under their requirements as level-four headings. Relevant standalone regression criteria use level-three headings
+   under optional `Regression checks`, without inventing unchanged requirements. Both forms share global numbering and are required in `handoffs`. Workflow phases and
+   saved report formats remain unchanged.
+5. Removed the `Coverage` classification field from current `acceptance criteria`. Each criterion retains its `probe`, `expected result`, and example. Standalone
+   regression checks remain identified by their section; validation and report formats are unchanged.
+
 ## 0.11.0
 
 1. Added the `simplifier` after successful verification or rejection of all current `findings`, without another approval or verification cycle.
@@ -18,8 +38,8 @@ GitHub Releases are not required.
 
 ## 0.10.0
 
-1. Saved complete `owner` decision batches in their original `handoffs` before changing phase, including when the `spec` requires revision.
-   See [PR #38](https://github.com/emilioSp/pi-maestro/pull/38).
+1. Saved complete `owner` decision batches in their original `handoffs` before changing phase, including when the `spec` requires revision. See
+   [PR #38](https://github.com/emilioSp/pi-maestro/pull/38).
 2. Added `revise-spec` decisions for `verifier` `findings`, with the owner's reason and agreed requirement change. Revision takes priority over code fixes and rejections.
 3. Unified both revision paths through `drafting-spec`, with renewed `GREEN FLAG` before separate approval and another `builder` `run`. Approval is allowed only from
    `drafting-spec`.
@@ -30,24 +50,24 @@ GitHub Releases are not required.
 
 ## 0.9.5
 
-1. Added a shared check that requires every approved `spec` criterion ID in `builder` and `verifier` `handoffs`.
-   See [PR #37](https://github.com/emilioSp/pi-maestro/pull/37).
+1. Added a shared check that requires every approved `spec` criterion ID in `builder` and `verifier` `handoffs`. See
+   [PR #37](https://github.com/emilioSp/pi-maestro/pull/37).
 2. Missing IDs reject submission before saving a report or changing phase. Extra report IDs remain allowed, and existing report validation is unchanged.
 3. Reused the raw heading rule `^### AC(\d+):`, including leading zeros and matching lines inside code blocks. No matching headings impose no new restriction.
 4. Added unit tests for extraction and one missing-ID integration test per role.
 
 ## 0.9.4
 
-1. Added numbering validation to `spec` approval. Matched `acceptance criterion` headings must start at `AC1` and continue without gaps.
-   See [PR #36](https://github.com/emilioSp/pi-maestro/pull/36).
+1. Added numbering validation to `spec` approval. Matched `acceptance criterion` headings must start at `AC1` and continue without gaps. See
+   [PR #36](https://github.com/emilioSp/pi-maestro/pull/36).
 2. Invalid numbering rejects approval before saving the workflow and leaves all saved files unchanged. No matching headings still permits approval.
 3. Added `Maestro` guidance to correct only numbering and affected references, then retry with the existing `GREEN FLAG`. No additional `owner` approval is required
    before starting the `builder`.
 
 ## 0.9.3
 
-1. Added a parent `pi-subagents` availability check during activation. A matching successful version 1 `ping` reply is required within 2000 ms.
-   See [PR #35](https://github.com/emilioSp/pi-maestro/pull/35).
+1. Added a parent `pi-subagents` availability check during activation. A matching successful version 1 `ping` reply is required within 2000 ms. See
+   [PR #35](https://github.com/emilioSp/pi-maestro/pull/35).
 2. Failed or invalid replies, emission errors, and timeouts prevent activation. The error includes "Maestro flow requires pi-subagents installed in the Pi environment."
    The check makes no automatic retry.
 3. Preserved existing activation checks, UI-only notices, and unchanged session history. The availability check starts no agent, makes no model request, and does not run
@@ -55,23 +75,23 @@ GitHub Releases are not required.
 
 ## 0.9.2
 
-1. Added code-quality review to `verifier` guidance for code affected by the approved change when applicable `AGENTS.md` directives exist.
-   See [PR #34](https://github.com/emilioSp/pi-maestro/pull/34). All existing verification duties remain unchanged.
+1. Added code-quality review to `verifier` guidance for code affected by the approved change when applicable `AGENTS.md` directives exist. See
+   [PR #34](https://github.com/emilioSp/pi-maestro/pull/34). All existing verification duties remain unchanged.
 2. Required instruction-violation `findings` to identify the instruction file, quote the rule, and explain the violating code through existing evidence fields.
 3. Skip only the added review when files or code-quality directives are absent. Missing directives and personal style preferences do not produce `findings`.
 
 ## 0.9.1
 
-1. Added a brief introduction and an invitation to ask how `Maestro` works to the successful activation notice.
-   See [PR #33](https://github.com/emilioSp/pi-maestro/pull/33).
+1. Added a brief introduction and an invitation to ask how `Maestro` works to the successful activation notice. See
+   [PR #33](https://github.com/emilioSp/pi-maestro/pull/33).
 2. Preserved the configured agent details and UI-only activation. Activation does not add session history or start a model request.
 3. Added absolute paths to the installed README and documentation directory in active instructions. `Maestro` reads relevant documentation on demand without automatically
    loading its contents.
 
 ## 0.9.0
 
-1. Breaking: `builder` reports now support only `done` and `escalation`. Reportable technical problems use the existing `owner` `escalation` process.
-   See [PR #32](https://github.com/emilioSp/pi-maestro/pull/32).
+1. Breaking: `builder` reports now support only `done` and `escalation`. Reportable technical problems use the existing `owner` `escalation` process. See
+   [PR #32](https://github.com/emilioSp/pi-maestro/pull/32).
 2. Removed the terminal `builder` failure phase and event. Execution errors and missing or invalid saved results still stop the workflow without automatic recovery.
 3. No migrations, compatibility readers, or deprecated aliases are provided. `Artifact` versions remain `1.0.0`.
 
@@ -82,8 +102,8 @@ GitHub Releases are not required.
 
 ## 0.7.3
 
-1. Added Oxlint rules for `given ... when ... then ...` test titles, `const` usage, unnecessary `else` branches, type aliases, and ESM imports.
-   See [PR #31](https://github.com/emilioSp/pi-maestro/pull/31).
+1. Added Oxlint rules for `given ... when ... then ...` test titles, `const` usage, unnecessary `else` branches, type aliases, and ESM imports. See
+   [PR #31](https://github.com/emilioSp/pi-maestro/pull/31).
 2. Updated `oxlint-anti-slop` from `0.3.3` to `0.3.6`.
 3. Updated 106 test titles to match the naming rule without changing test logic.
 
@@ -96,15 +116,15 @@ GitHub Releases are not required.
 
 ## 0.7.1
 
-1. Documented the project mission, current tech stack, `owner` responsibilities, roadmap, and codebase change history.
-   See [PR #30](https://github.com/emilioSp/pi-maestro/pull/30).
+1. Documented the project mission, current tech stack, `owner` responsibilities, roadmap, and codebase change history. See
+   [PR #30](https://github.com/emilioSp/pi-maestro/pull/30).
 2. Replaced `TODO.md` with the roadmap and included the four project constitution documents in the npm package.
 3. Updated documentation audits to compare all current documentation and the project constitution with the working tree without requesting a comparison baseline.
 
 ## 0.7.0
 
-1. Stored multiple `escalation` questions and `owner` resolutions inside numbered `builder` `handoffs`. Earlier `handoffs` remain available as history.
-   See [PR #27](https://github.com/emilioSp/pi-maestro/pull/27).
+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).
@@ -118,8 +138,8 @@ session history and model context. See [PR #26](https://github.com/emilioSp/pi-m
 
 ## 0.6.0
 
-1. Removed Git requirements, checkpoints, and automatic commits from the workflow. `Maestro` uses Pi's project directory and saved workflow phase.
-   See [PR #25](https://github.com/emilioSp/pi-maestro/pull/25).
+1. Removed Git requirements, checkpoints, and automatic commits from the workflow. `Maestro` uses Pi's project directory and saved workflow phase. See
+   [PR #25](https://github.com/emilioSp/pi-maestro/pull/25).
 2. Retained numbered `builder` and `verifier` `handoffs` and explicit `owner` `finding` decisions. Removed workflow revision counters and writer locks.
 3. Breaking: changed `artifact` formats, `handoff` paths, and tool results without migration or compatibility readers. Removed revision and commit fields. `Artifact`
    versions remain `1.0.0`. Interrupted and older workflows require manual `owner` handling.
@@ -171,8 +191,8 @@ Enabled inheritance of global instructions for `builder` and `verifier` agents,
 
 ## 0.3.0
 
-Clarified `Maestro`, `builder`, and `verifier` responsibilities, `spec` and prototype revisions, permitted experiments, evidence requirements, and cleanup.
-See [PR #21](https://github.com/emilioSp/pi-maestro/pull/21).
+Clarified `Maestro`, `builder`, and `verifier` responsibilities, `spec` and prototype revisions, permitted experiments, evidence requirements, and cleanup. See
+[PR #21](https://github.com/emilioSp/pi-maestro/pull/21).
 
 ## 0.2.0
 
@@ -180,8 +200,8 @@ Moved TypeBox to peer dependencies and loosened Pi peer dependency version const
 
 ## 0.1.2
 
-Pinned `verifier` comparisons to a fixed `candidate` checkpoint rather than the current HEAD's parent. This checkpoint mechanism was later removed in `0.4.0`.
-See [PR #20](https://github.com/emilioSp/pi-maestro/pull/20).
+Pinned `verifier` comparisons to a fixed `candidate` checkpoint rather than the current HEAD's parent. This checkpoint mechanism was later removed in `0.4.0`. See
+[PR #20](https://github.com/emilioSp/pi-maestro/pull/20).
 
 Breaking: renamed `maestro_launch_builder` and `maestro_launch_verifier` to `maestro_run_builder` and `maestro_run_verifier`. Renamed the corresponding workflow events
 from `launch-*` to `run-*`.
@@ -189,5 +209,5 @@ 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).
+`verifier` `findings`. The workflow ends at `candidate-ready`, leaving final review to the `owner`. See [PR #14](https://github.com/emilioSp/pi-maestro/pull/14) and
+[PR #13](https://github.com/emilioSp/pi-maestro/pull/13).

package/MISSION.md

@@ -1,9 +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`.
+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.
+instructions, including linters, tests, anti-slop checks, and `AGENTS.md`. `Maestro` and its agents use these checks and instructions.

package/README.md

@@ -8,11 +8,11 @@ Pi extension for a spec-driven multiagent development workflow.
 
 ## The idea
 
-A `specification` (`spec`) describes one reversible change.
-The `builder` implements it.
-An independent `verifier` checks every `acceptance criterion`.
-A `simplifier` then refactors accepted code without changing behavior.
-The `owner` performs the final review.
+- A `specification` (`spec`) describes one reversible change.
+- The `builder` implements it.
+- An independent `verifier` checks every `acceptance criterion`.
+- A `simplifier` then refactors accepted code without changing behavior.
+- The `owner` performs the final review.
 
 Five principles hold the workflow together:
 
@@ -22,10 +22,43 @@ Five principles hold the workflow together:
 4. The `owner` decides requirements, scope, and unresolved questions.
 5. Each agent has one and only one role. Specific and with clear instruction.
 
+## Inspirations
+
+Pi Maestro is inspired by concepts from [OpenSpec](https://github.com/Fission-AI/OpenSpec) and [GitHub Spec Kit](https://github.com/github/spec-kit). It adapts those
+concepts to a sequential multiagent workflow in Pi.
+
+The following official sources document the conceptual references. The links point to fixed revisions so the cited content remains inspectable.
+
+1. **The `specification` drives the code.** [Spec Kit's philosophy][spec-kit-philosophy] treats the `specification` as the primary `artifact` and code as its expression.
+   In `Maestro`, the approved `spec` defines a working contract for the `builder` and `verifier`.
+2. **Describe behavior, not routine implementation choices.** [OpenSpec's schema][openspec-schema] defines a `specification` as a behavior contract, not an implementation
+   plan. `Maestro` records required behavior, constraints, and approved architectural decisions in the `spec`, leaving routine implementation choices to the `builder`.
+3. **Use concrete, testable scenarios.** [OpenSpec's schema][openspec-schema] pairs requirements with scenarios; [Spec Kit's template][spec-kit-template] uses
+   Given/When/Then acceptance scenarios. Each `Maestro` `acceptance criterion` includes a `probe`, an `expected result`, and a concrete example.
+4. **Clarify requirements progressively.** [Spec Kit's clarify command][spec-kit-clarify] asks one question at a time and integrates accepted answers into the
+   `specification`. `Maestro` likewise asks one focused question, waits for the owner's answer, and updates the `spec` before asking the next question.
+5. **Review requirements separately from testing code.** [Spec Kit's checklist command][spec-kit-checklist] evaluates requirements for completeness, clarity, consistency,
+   and measurability, not implementation correctness. Before approval, `Maestro` reviews the `spec` for consistency, missing decisions, measurable outcomes, and
+   reproducible scenarios. The later `verifier` checks the implementation independently.
+6. **Separate motivation, behavior, and design.** [OpenSpec's schema][openspec-schema] separates these concerns and calls for `design.md` only when significant technical
+   decisions need recording, including reasons, alternatives, and risks.
+7. **Make requirement changes explicit.** [OpenSpec's schema][openspec-schema] distinguishes added, modified, removed, and renamed requirements. `Maestro` adapts this
+   concept with one `Delta` field per requirement: `added`, `modified`, or `removed`. Each requirement states the complete required outcome.
+8. **Make requirement coverage traceable.** [Spec Kit's analyze command][spec-kit-analyze] maps requirements to implementation tasks and identifies coverage gaps.
+   `Maestro` applies a related principle to verification: each requirement has a `Verified by` field linking to its `acceptance criteria`, existing tests covering exact
+   scenarios, or both. The mapping connects requirements to verification.
+
+[openspec-schema]: https://github.com/Fission-AI/OpenSpec/blob/6d04a1b58dedc95729d34e4f223d9d483aae210a/schemas/spec-driven/schema.yaml
+[spec-kit-philosophy]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/spec-driven.md
+[spec-kit-template]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/spec-template.md
+[spec-kit-clarify]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/commands/clarify.md
+[spec-kit-checklist]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/commands/checklist.md
+[spec-kit-analyze]: https://github.com/github/spec-kit/blob/222a973f8b8794366680c043fb935a31f71902af/templates/commands/analyze.md
+
 ## The roles
 
 | Role         | Responsibility                                                                                                          |
-|--------------|-------------------------------------------------------------------------------------------------------------------------|
+| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
 | `Owner`      | Brings the problem, approves the `spec`, decides questions and `findings`, and reviews the final code.                  |
 | `Maestro`    | Works directly with the `owner`, prepares the `spec`, runs the other agents, records decisions, and summarizes results. |
 | `Builder`    | Implements the approved `spec` and checks each `acceptance criterion`.                                                  |
@@ -79,31 +112,28 @@ The `owner` follows this workflow:
 5. Reviews `verifier` `findings` and chooses an action for every `finding`.
 6. Reads Maestro's summary at `candidate-ready` and performs the final review.
 
-`Maestro` starts the `verifier` after a successful `builder` `run`.
-All three agents run in the foreground: Pi waits for each `run` to finish and `Maestro` shows the current phase in Pi's status, while `pi-subagents` FleetView and
-`/subagents-fleet` show agent activity and transcripts.
+`Maestro` starts the `verifier` after a successful `builder` `run`. All three agents run in the foreground: Pi waits for each `run` to finish and `Maestro` shows the
+current phase in Pi's status, while `pi-subagents` FleetView and `/subagents-fleet` show agent activity and transcripts.
 
-The `owner` must not edit product files while the workflow runs.
-`Maestro` can perform temporary experiments with `owner` agreement during `spec` preparation and permitted revisions. See [Workflow](docs/workflow.md#spec-approval).
+The `owner` must not edit product files while the workflow runs. `Maestro` can perform temporary experiments with `owner` agreement during `spec` preparation and
+permitted revisions. See [Workflow](docs/workflow.md#spec-approval).
 
 An `escalation` asks the `owner` to decide an implementation question, and a `finding` records a technical issue reported by the `verifier`. The `owner` discusses both
-with `Maestro`, never directly with the `builder` or `verifier`.
-`Maestro` records all current `escalation` answers or `finding` decisions in the active `handoff` before changing phase.
+with `Maestro`, never directly with the `builder` or `verifier`. `Maestro` records all current `escalation` answers or `finding` decisions in the active `handoff` before
+changing phase.
 
-If any decision requires a `spec` change, the workflow returns to `drafting-spec` before the `owner` and `Maestro` revise the same `spec`.
-The `owner` reviews the revised `spec` and replies `GREEN FLAG` again.
-`Maestro` records renewed approval separately before another `builder` `run`.
+If any decision requires a `spec` change, the workflow returns to `drafting-spec` before the `owner` and `Maestro` revise the same `spec`. The `owner` reviews the revised
+`spec` and replies `GREEN FLAG` again. `Maestro` records renewed approval separately before another `builder` `run`.
 
-After successful verification or rejection of all `findings`, `Maestro` starts the `simplifier`.
-Only this step requires Git. If Git readiness cannot be confirmed, `Maestro` warns and skips simplification.
-The `simplifier` selects all uncommitted code changes, including pre-existing staged, unstaged, and untracked files.
+After successful verification or rejection of all `findings`, `Maestro` starts the `simplifier`. Only this step requires Git. If Git readiness cannot be confirmed,
+`Maestro` warns and skips simplification. The `simplifier` selects all uncommitted code changes, including pre-existing staged, unstaged, and untracked files.
 
-The workflow ends at `candidate-ready`. Rejected `findings` retain their reasons and accepted failures can remain.
-Maestro's summary separates independent verification from the later simplifier's report.
-The `owner` controls later review, commits, pull requests, and merging.
+The workflow ends at `candidate-ready`. Rejected `findings` retain their reasons and accepted failures can remain. Maestro's summary separates independent verification
+from the later simplifier's report. After the final summary finishes successfully, `Maestro` automatically turns off. The `owner` controls later review, commits, pull
+requests, and merging.
 
-The same `/maestro` command disables `Maestro` and leaves project files unchanged. Disabling `Maestro`, restarting Pi, or using `/resume` clears live session state.
-Saved files do not automatically restore or resume an incomplete workflow. The `owner` handles it manually.
+The same `/maestro` command disables `Maestro` and leaves project files unchanged. Disabling `Maestro`, restarting Pi, or using `/resume` clears live session state. Saved
+files do not automatically restore or resume an incomplete workflow. The `owner` handles it manually.
 
 ## Configuration
 
@@ -123,6 +153,6 @@ The reading order is:
 
 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.
+3. [Roadmap](https://linear.app/emilio-spatola/team/MAESTRO/overview): completed outcomes and planned priorities maintained in Linear.
 4. [Changelog](CHANGELOG.md): meaningful codebase changes and breaking changes.
 5. [Architecture decision records](ADR.md): architectural choices, context, consequences, and evidence.

package/TECH_STACK.md

@@ -4,12 +4,12 @@
 `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`, `verifier`, and `simplifier` execution and activity tracking.                          |
 | TypeBox                        | Schemas and runtime validation for configuration, workflow state, tool inputs, and agent reports. |
 | Vitest with coverage           | Unit tests, integration tests, and code coverage.                                                 |
-| Biome                          | Formatting and lint checks.                                                                       |
-| Oxlint with `oxlint-anti-slop` | Additional lint and anti-slop checks.                                                             |
+| Oxfmt                          | Formatting                                                                                        |
+| Oxlint with `oxlint-anti-slop` | Linting and additional anti-slop checks.                                                          |