@emiliosp/pi-maestro 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -2,12 +2,29 @@
 
 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.
 
-## Unreleased
+## 0.9.2
 
-1. Breaking: `builder` reports now support only `done` and `escalation`. Reportable technical problems use the existing `owner` `escalation` process.
+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).
+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).
 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`.
 
+## 0.8.0
+
+1. Updated the bundled `pi-subagents` dependency from `0.76.0` to `0.78.0`.
+2. Renamed `test/` to `tests/`. Updated imports, fixture paths, lint configuration, and project instructions. Source tests remain next to their source files.
+
 ## 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).

package/ROADMAP.md

@@ -24,6 +24,16 @@ Numbered `builder` `handoffs` contain multiple `escalation` questions and their
 
 [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-03: Route builder failures through owner escalations
+
+Released in `0.9.0`. The `builder` reports only `done` or `escalation`. Reportable technical problems use the existing `owner` `escalation` process. Individual `probe` results retain `failed`. Execution errors and missing or invalid saved results still stop the workflow without automatic recovery.
+
+All 8 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
+
+#### Evidence
+
+[Specification](.specs/20261013-101454-route-builder-failures-through-owner-escalations/spec.md), [verifier report](.specs/20261013-101454-route-builder-failures-through-owner-escalations/handoffs/verifier/V1.json), and [merged PR #32](https://github.com/emilioSp/pi-maestro/pull/32).
+
 ### 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.
@@ -32,6 +42,18 @@ Applied glossary formatting across the documentation and recorded its exclusions
 
 [Glossary](docs/glossary.md) and [workflow documentation](docs/workflow.md).
 
+### R-14: Introduce Maestro at activation
+
+Implemented in `0.9.1`. Successful activation introduces `Maestro` and invites the `owner` to ask how it works. The UI-only notice retains the configured agent details and does not add session history or start a model request.
+
+Active instructions identify absolute paths to the installed README and documentation directory. `Maestro` reads relevant documentation on demand without automatically loading its contents.
+
+All 6 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
+
+#### Evidence
+
+[Specification](.specs/20261013-171954-introduce-maestro-at-activation/spec.md), [verifier report](.specs/20261013-171954-introduce-maestro-at-activation/handoffs/verifier/V1.json), and [merged PR #33](https://github.com/emilioSp/pi-maestro/pull/33).
+
 ### R-15: Rename the test support directory
 
 Renamed `test/` to `tests/` at the owner's request. Updated imports, fixture paths, lint configuration, and project instructions. This follows the global instruction to keep fixtures under `tests/fixtures`. Source tests remain next to their source files. Historical `handoffs` retain their recorded paths.
@@ -40,24 +62,22 @@ Renamed `test/` to `tests/` at the owner's request. Updated imports, fixture pat
 
 [Test support](tests/support/), [fixtures](tests/fixtures/), [lint configuration](biome.json), and [project instructions](AGENTS.md#tests).
 
-## Now
+### R-16: Verify code quality against AGENTS.md instructions
 
-### R-03: Route builder failures through owner escalations
+Implemented in `0.9.2`. `Verifier` guidance now requires code-quality review only for code affected by the approved change when applicable `AGENTS.md` directives exist. All existing duties remain unchanged, including independent verification of every `acceptance criterion`.
 
-#### Objective
+Instruction-violation `findings` identify the instruction file, quote the rule, and explain the violating code through existing evidence fields. Missing files or code-quality directives cause only the added review to be skipped. Personal style preferences are not requirements.
 
-The `builder` reports technical problems that prevent completion through the existing `escalation` process. The `owner` decides how to proceed.
+All 5 `acceptance criteria` passed through independent inspection of the written guidance, with no `verifier` `findings`. No additional model trials were performed. The saved workflow reached `candidate-ready`.
 
-The approved [specification](.specs/20261013-101454-route-builder-failures-through-owner-escalations/spec.md) is implemented.
-Automatic recovery of interrupted `runs` remains outside this item.
+#### Evidence
 
-#### Completed when
+[Specification](.specs/20261013-185941-verify-code-quality-against-agents-md-instructions/spec.md), [verifier report](.specs/20261013-185941-verify-code-quality-against-agents-md-instructions/handoffs/verifier/V1.json), and [merged PR #34](https://github.com/emilioSp/pi-maestro/pull/34).
 
-`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 describe the same behavior.
+## Now
 
 ## Next
 
-
 ## 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.
@@ -159,25 +179,3 @@ Show an activity indicator in Pi's status bar while progress does not require an
 #### Completed when
 
 The status clearly distinguishes work in progress from a request for `owner` action.
-
-### R-14: Introduce Maestro at activation
-
-#### Objective
-
-When activated, `Maestro` gives a brief introduction and invites the `owner` to ask how it works, if interested. `Maestro` must have access to its own documentation to answer those questions.
-
-#### Completed when
-
-Activation includes this short introduction. `Maestro` can consult its documentation.
-
-### R-16: Verify code quality against AGENTS.md instructions
-
-#### Objective
-
-Add code-quality review against applicable `AGENTS.md` instructions as another `verifier` responsibility. Keep all existing responsibilities unchanged, including independent verification of every `acceptance criterion` in the approved `spec`. Code-quality review supplements that verification. It does not replace or reduce it.
-
-Existing `verifier` instructions already require reading applicable `AGENTS.md` files and following technical rules. Extend that guidance to require explicit code-quality review and reporting of instruction violations. Do not introduce personal style preferences as requirements.
-
-#### Completed when
-
-The `verifier` performs both its existing verification duties and the additional code-quality review. Every `acceptance criterion` is still independently verified. Each code-quality `finding` about an instruction violation identifies the `AGENTS.md` file, quotes the violated instruction, and explains how the code violates it.

package/agents/verifier.md

@@ -63,6 +63,21 @@ Use `probeStatus: passed` when the observed result matches the expected result.
 Use `failed` for an observed probe failure and `not-run` for an unexecuted probe.
 Include every spec criterion once. Never omit unrun criteria or fabricate evidence.
 
+## Review code quality
+
+If applicable `AGENTS.md` files contain code-quality directives, review affected code against those directives.
+Review only code affected by the approved change. Do not audit unrelated project code.
+This review supplements all existing duties. Independently verify every acceptance criterion even when this review finds instruction violations.
+Do not treat personal style preferences as requirements or report findings based only on those preferences.
+
+For each instruction violation, use the existing finding evidence fields:
+
+1. Identify the applicable `AGENTS.md` file in `evidence.source` and quote the violated instruction exactly in `evidence.observation`.
+2. Identify the violating code in `evidence.source` and explain how it violates that instruction in `evidence.observation`.
+
+If no applicable `AGENTS.md` files exist, or they contain no code-quality directives, skip only this added review.
+Missing files or directives are not errors or findings. Do not invent directives or require those files to be created.
+
 ## Record findings, not decisions
 
 Record technical issues supported by fresh evidence. Do not add requirements, style preferences, or unrelated improvements.

package/extensions/maestro.ts

@@ -90,10 +90,12 @@ export default (pi: ExtensionAPI): void => {
         syncMainTools();
         await refreshMaestroStatus(context);
 
-        // show builder/verifier model on activation
+        // Introduce Maestro and show configured agents only in the UI.
         context.ui.notify(
           [
             context.ui.theme.fg('muted', 'Maestro active'),
+            'Maestro helps the owner define a spec, then coordinates implementation and independent verification.',
+            'Ask how Maestro works for a short explanation.',
             context.ui.theme.fg(
               'accent',
               `Builder (${config.builder.model} ${config.builder.thinking})`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emiliosp/pi-maestro",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -3,6 +3,14 @@
  * Used: When Pi prepares a model request while Maestro is active.
  */
 
+import { fileURLToPath } from 'node:url';
+
+const README_PATH = fileURLToPath(
+  new URL('../../../README.md', import.meta.url),
+);
+
+const DOCS_PATH = fileURLToPath(new URL('../../../docs/', import.meta.url));
+
 const MAESTRO_INSTRUCTIONS = `## Maestro mode
 
 You are Maestro. Coordinate one sequential spec-driven workflow in the current session.
@@ -10,6 +18,14 @@ The owner decides requirements, scope, technical decisions in the spec, spec app
 The builder implements the approved spec. The verifier independently checks the candidate. Do not perform their work yourself.
 The approved spec.md is the contract for all three roles. Do not infer owner approval from an agent's recommendation.
 
+### Maestro documentation
+
+The loaded Maestro package's documentation is separate from the owner's project:
+README.md: ${README_PATH}
+docs/: ${DOCS_PATH}
+Before answering questions about Maestro, use the available file-reading tools to read the relevant documentation on demand.
+Do not automatically load all documentation.
+
 ### Tools and boundaries
 
 The project root is the canonical Pi working directory, resolved with realpath. Do not search ancestor directories.