@emiliosp/pi-maestro 0.9.4 → 0.9.5

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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).

package/ROADMAP.md

@@ -86,23 +86,39 @@ A later integration test requested by the `owner` directly checks the environmen
 
 [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-05: Keep acceptance criterion numbering continuous
+### R-10: Match handoff criteria to the approved spec
 
 #### 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.
+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.
 
-#### Current state
+The `specification` must define the criterion heading format used to extract IDs. For example, a heading can use `### AC1: ...`.
 
-Implemented approval-time numbering validation and `Maestro` guidance for numbering-only recovery using the existing GREEN FLAG. Rejected numbering leaves saved files unchanged. Independent verification is pending.
+#### Completed when
 
-[Specification](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/spec.md).
+Both `handoff` submissions reject missing, extra, or duplicate criterion IDs before saving a report or changing phase.
 
-#### Completed when
+#### Implementation status
 
-The `spec` and its current references use consistent numbering.
+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`.
+
+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
 
@@ -151,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.4",
+  "version": "0.9.5",
   "description": "A spec-driven multiagent development workflow for Pi.",
   "license": "MIT",
   "type": "module",

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/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),