@emiliosp/pi-maestro 0.9.3 → 0.9.5

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 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.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).
+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).
+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 when turning `Maestro` off.
+
 ## 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.

package/ROADMAP.md

@@ -74,26 +74,51 @@ All 5 `acceptance criteria` passed through independent inspection of the written
 
 [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).
 
+### R-06: Check subagent extensions at activation
+
+Implemented in `0.9.3`. Activation requires a matching successful version 1 `ping` reply from the parent `pi-subagents` extension within 2000 ms. A failed or invalid reply, emission error, or timeout prevents activation and reports the installation requirement. The check starts no agent and makes no model request. It confirms parent extension availability, not child execution readiness.
+
+All 7 `acceptance criteria` passed using controlled replies and code inspection, with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
+
+A later integration test requested by the `owner` directly checks the environment check's failed-reply error. This test addition is outside the completed independent verification.
+
+#### Evidence
+
+[Specification](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/spec.md), [verifier report](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/handoffs/verifier/V1.json), and [merged PR #35](https://github.com/emilioSp/pi-maestro/pull/35).
+
+### R-05: Keep acceptance criterion numbering continuous
+
+Implemented in `0.9.4`. `Spec` approval rejects numbered `acceptance criterion` headings that do not start at `AC1` and continue without gaps. Rejection leaves saved files unchanged.
+
+`Maestro` corrects numbering and affected references without changing criterion order or requirements, then retries with the existing `GREEN FLAG`. No additional `owner` approval is required.
+
+All 3 `acceptance criteria` passed with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
+
+#### Evidence
+
+[Specification](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/spec.md), [verifier report](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/handoffs/verifier/V1.json), and [merged PR #36](https://github.com/emilioSp/pi-maestro/pull/36).
+
 ## Now
 
-### R-06: Check subagent extensions at activation
+### R-10: Match handoff criteria to the approved spec
 
 #### Objective
 
-Make `pi-subagents` availability problems visible before a `builder` or `verifier` `run` starts.
+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.
 
-#### Implementation status
+The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
 
-Activation now requires a successful version 1 `ping` reply from the parent `pi-subagents` extension within 2000 ms. The check does not start an agent. All 7 `acceptance criteria` passed with no `verifier` `findings`; the workflow reached `candidate-ready`.
+#### Completed when
 
-A later integration test requested by the `owner` directly checks the environment check's failed-reply error. This test addition is outside the completed independent verification.
+Both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase.
 
-[Specification](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/spec.md).
+#### Implementation status
 
-#### Completed when
+The [approved specification](.specs/20261013-211629-match-handoff-criteria-to-the-approved-spec/spec.md) limits this change to missing IDs. The implementation rejects missing `spec` IDs before saving either `handoff` or changing phase. Extra report IDs remain allowed. No new check rejects duplicate IDs in the `spec`.
 
-Unavailable `pi-subagents` prevents activation. The error identifies the problem.
+Both `acceptance criteria` passed independent verification with no `findings`. The saved workflow reached `candidate-ready`. The broader exact-match objective remains outside this approved scope.
 
+Later changes requested by the `owner` extract the shared presence check into one utility and cover extraction with unit tests. One missing-ID integration test remains per role to check rejection before saving. These changes are outside the completed independent verification.
 
 ## Next
 
@@ -113,16 +138,6 @@ Compatibility with installations under the old name must be decided in the `spec
 
 Package metadata and installation documentation use the new name. The package is available under that name.
 
-### R-05: Keep acceptance criterion numbering continuous
-
-#### Objective
-
-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.
-
-#### Completed when
-
-The `spec` and its current references use consistent numbering.
-
 ### R-07: Guide initial configuration
 
 #### Objective
@@ -152,39 +167,3 @@ Explore how `Maestro` can reconcile saved `artifacts` and workflow state. The re
 #### Completed when
 
 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
-
-#### Objective
-
-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.
-
-The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
-
-#### Completed when
-
-Both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase.
-
-### R-11: Reduce temporary verifier changes
-
-#### Objective
-
-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.
-
-`Maestro` currently has no file-hash restoration check. Adding one requires a separate scope decision.
-
-#### Completed 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.
-
-### R-13: Show when Maestro is working
-
-#### Objective
-
-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.
-
-#### Completed when
-
-The status clearly distinguishes work in progress from a request for `owner` action.

package/package.json

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

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -54,6 +54,14 @@ Wait for each tool result before taking the next workflow action. Do not launch
 10. On approval, freeze the spec as the contract. Call maestro_mark_spec_ready with the active specId.
 11. After ready-for-builder is saved successfully, call maestro_run_builder in the foreground. Do not request a separate start approval.
 
+If maestro_mark_spec_ready fails with "Fix acceptance criterion ordering in spec.md." after GREEN FLAG, keep the current phase unchanged.
+In drafting-spec, escalation-decision, or findings-decision, correct only numbering and affected references in the current spec.md.
+Do not change criterion order or requirements.
+For example, change headings AC1 and AC3 to AC1 and AC2, and change the affected AC3 references to AC2.
+Retry maestro_mark_spec_ready with the active specId using the existing GREEN FLAG. Do not request another approval.
+After the transition succeeds, call maestro_run_builder in the foreground.
+This edit exception applies only to failed numbering validation. It does not apply after successful approval or during agent runs.
+
 Write spec.md for the owner. Keep detail proportional to the change and state each requirement once.
 Use the template topics as guidance. Omit empty subsections instead of filling them with Not applicable.
 Keep behavior, scope, constraints, and approved architectural decisions in the spec. Leave routine implementation choices to the builder.
@@ -74,6 +82,7 @@ In spec.md, keep only a brief reason, essential references, and unresolved limit
 ### Spec edits, checks, and experiments
 
 Edit the active spec.md and its prototypes/ directory only in drafting-spec or during owner-directed contract revisions in decision phases.
+The numbering-only recovery procedure above also permits spec.md corrections after failed numbering validation in those phases.
 The decision phases are escalation-decision and findings-decision. Do not edit the spec or prototypes in other phases.
 The approved spec is frozen. Never change it during builder or verifier execution.
 Use any available tool for these permitted edits. Do not change other workflow artifacts.

package/src/workflow/builder/completeBuilderPass.ts

@@ -3,7 +3,7 @@
  * Used: When the builder reports done or escalation through the child tool.
  */
 
-import { mkdir } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { Value } from 'typebox/value';
 import { assertBuilderHandoff } from '#artifacts/builder-handoff/assertBuilderHandoff.ts';
 import {
@@ -19,6 +19,7 @@ import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
+import { assertSpecAcceptanceCriteria } from '#workflow/utils/assertSpecAcceptanceCriteria.ts';
 
 export type CompletedBuilderPass = {
   handoff: BuilderHandoff;
@@ -76,6 +77,11 @@ export const completeBuilderPass = async ({
   assertBuilderHandoff(handoffInput);
   const { handoff } = handoffInput;
 
+  assertSpecAcceptanceCriteria({
+    markdown: await readFile(paths.getSpecFilePath(specId), 'utf8'),
+    criterionIds: new Set(handoff.acceptanceCriteria.map(({ id }) => id)),
+  });
+
   const nextState = transitionWorkflow({
     state: currentState,
     event: getWorkflowEventByBuilderHandoff(handoff),

package/src/workflow/spec/markSpecReady.ts

@@ -3,6 +3,7 @@
  * Used: When the owner approves the spec content.
  */
 
+import { readFile } from 'node:fs/promises';
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { pathExists } from '#utils/path-exists.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
@@ -10,6 +11,14 @@ import { WORKFLOW_EVENTS, type WorkflowState } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
 
+function assertAcceptanceCriterionOrdering(markdown: string): void {
+  const criteria = [...markdown.matchAll(/^### AC(\d+):/gm)];
+
+  if (criteria.some((match, index) => Number(match[1]) !== index + 1)) {
+    throw new Error('Fix acceptance criterion ordering in spec.md.');
+  }
+}
+
 type MarkSpecReadyInput = {
   paths: MaestroPaths;
   specId: string;
@@ -51,6 +60,8 @@ export const markSpecReady = async ({
     event: WORKFLOW_EVENTS.MARK_SPEC_READY,
   });
 
+  assertAcceptanceCriterionOrdering(await readFile(specFilePath, 'utf8'));
+
   await writeWorkflowState({
     path: workflowPath,
     state,

package/src/workflow/utils/assertSpecAcceptanceCriteria.ts

@@ -0,0 +1,24 @@
+/**
+ * Objective: Require every spec criterion ID in a handoff.
+ * Used: Before builder and verifier submissions save their reports.
+ */
+
+type AssertSpecAcceptanceCriteriaInput = {
+  markdown: string;
+  criterionIds: Set<string>;
+};
+
+export function assertSpecAcceptanceCriteria({
+  markdown,
+  criterionIds,
+}: AssertSpecAcceptanceCriteriaInput): void {
+  const missingIds = [...markdown.matchAll(/^### AC(\d+):/gm)]
+    .map((match) => `AC${match[1]}`)
+    .filter((id) => !criterionIds.has(id));
+
+  if (missingIds.length > 0) {
+    throw new Error(
+      `Handoff is missing acceptance criterion IDs from spec.md: ${missingIds.join(', ')}.`,
+    );
+  }
+}

package/src/workflow/verifier/completeVerifierPass.ts

@@ -3,7 +3,7 @@
  * Used: When the verifier submits its terminal handoff.
  */
 
-import { mkdir } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { assertVerifierHandoff } from '#artifacts/verifier-handoff/assertVerifierHandoff.ts';
 import type { VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
 import { writeVerifierHandoff } from '#artifacts/verifier-handoff/writeVerifierHandoff.ts';
@@ -12,6 +12,7 @@ import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
+import { assertSpecAcceptanceCriteria } from '#workflow/utils/assertSpecAcceptanceCriteria.ts';
 import { getWorkflowEventByVerifierHandoff } from '#workflow/verifier/utils/getWorkflowEventByVerifierHandoff.ts';
 
 export type CompletedVerifierPass = {
@@ -56,6 +57,11 @@ export const completeVerifierPass = async ({
   assertVerifierHandoff(handoffInput);
   const { handoff } = handoffInput;
 
+  assertSpecAcceptanceCriteria({
+    markdown: await readFile(paths.getSpecFilePath(specId), 'utf8'),
+    criterionIds: new Set(handoff.acceptanceCriteria.map(({ id }) => id)),
+  });
+
   const nextState = transitionWorkflow({
     state: currentState,
     event: getWorkflowEventByVerifierHandoff(handoff),