@emiliosp/pi-maestro 0.7.0 → 0.7.1

package/README.md

@@ -97,3 +97,10 @@ The reading order is:
 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 contracts.

package/changelog.md

@@ -0,0 +1,85 @@
+# Changelog
+
+This file summarizes meaningful changes to the codebase, including behavior, contracts, architecture, and development tools. Git tags identify version boundaries; GitHub Releases are not required. Version-only changes and routine maintenance are omitted.
+
+## 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 new tool contracts.
+
+## 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 contracts, 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "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"
   ],

package/roadmap.md

@@ -0,0 +1,85 @@
+# 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).
+
+## Now
+
+### 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.
+
+## Next
+
+### 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.
+
+## 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-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 contracts, 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-12: Format glossary terms consistently
+
+Use inline code formatting for glossary terms throughout the documentation. This lets the owner recognize the same term across documents. Complete when occurrences of glossary terms consistently use formatting such as `candidate-ready`.
+
+### 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 V8 coverage | Unit tests, integration tests, and code coverage. |
+| Biome | Formatting and lint checks. |
+| Oxlint with `oxlint-anti-slop` | Additional lint and anti-slop checks. |