@emiliosp/pi-maestro 0.9.2 → 0.9.4

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.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,25 +74,19 @@ 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).
 
-## 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.
+### R-06: Check subagent extensions at activation
 
-### R-04: Rename the npm package
+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.
 
-#### Objective
+All 7 `acceptance criteria` passed using controlled replies and code inspection, with no `verifier` `findings`. The saved workflow reached `candidate-ready`.
 
-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.
+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.
 
-Compatibility with installations under the old name must be decided in the `specification`. No `specification` is approved yet.
+#### Evidence
 
-#### Completed when
+[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).
 
-Package metadata and installation documentation use the new name. The package is available under that name.
+## Now
 
 ### R-05: Keep acceptance criterion numbering continuous
 
@@ -100,19 +94,33 @@ Package metadata and installation documentation use the new name. The package is
 
 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.
 
+#### Current state
+
+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.
+
+[Specification](.specs/20261013-202811-check-acceptance-criterion-numbering-before-builder-execution/spec.md).
+
 #### Completed when
 
 The `spec` and its current references use consistent numbering.
 
-### R-06: Check subagent extensions at activation
+## 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.
+
+### R-04: Rename the npm package
 
 #### Objective
 
-Make extension availability problems visible before a `builder` or `verifier` `run` starts. Activation already checks agent launch requirements, so first identify any missing extension checks.
+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.
+
+Compatibility with installations under the old name must be decided in the `specification`. No `specification` is approved yet.
 
 #### Completed when
 
-Unavailable required subagent extensions prevent activation. The error identifies the problem.
+Package metadata and installation documentation use the new name. The package is available under that name.
 
 ### R-07: Guide initial configuration
 

package/extensions/maestro.ts

@@ -83,7 +83,7 @@ export default (pi: ExtensionAPI): void => {
       }
 
       try {
-        await assertEnvironment(context);
+        await assertEnvironment({ context, piEventsBus: pi.events });
         const config = await loadConfiguration(context.cwd);
 
         maestroSessionState.activate();

package/package.json

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

package/src/maestro/checks/assertEnvironment.ts

@@ -3,12 +3,26 @@
  * Used: When the owner activates Maestro mode.
  */
 
+import { randomUUID } from 'node:crypto';
 import { realpath } from 'node:fs/promises';
-import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from '@earendil-works/pi-coding-agent';
 import { resolveSubagentLaunchContract } from 'pi-subagents/preflight';
 import { loadConfiguration } from '#config/loadConfiguration.ts';
 import { AGENTS } from '#config/schema.ts';
 
+export const SUBAGENT_PING = {
+  REQUEST_EVENT: 'subagents:rpc:v1:request',
+  REPLY_EVENT_PREFIX: 'subagents:rpc:v1:reply:',
+  VERSION: 1,
+  METHOD: 'ping',
+  TIMEOUT_MS: 2000,
+  INSTALLATION_ERROR:
+    'Maestro flow requires pi-subagents installed in the Pi environment.',
+} as const;
+
 const getErrorMessage = (error: unknown): string =>
   error instanceof Error ? error.message : String(error);
 
@@ -76,9 +90,81 @@ async function assertAgentsAvailable(projectRoot: string): Promise<void> {
   }
 }
 
-export async function assertEnvironment(
-  context: ExtensionContext,
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isReplyWithRequestId = (
+  reply: unknown,
+): reply is Record<string, unknown> & { requestId: string } =>
+  isRecord(reply) && typeof reply.requestId === 'string';
+
+type SuccessfulPingReply = {
+  version: typeof SUBAGENT_PING.VERSION;
+  requestId: string;
+  method: typeof SUBAGENT_PING.METHOD;
+  success: true;
+  data: { version: typeof SUBAGENT_PING.VERSION };
+};
+
+function assertSuccessfulPingReply(
+  reply: unknown,
+): asserts reply is SuccessfulPingReply {
+  if (
+    !isReplyWithRequestId(reply) ||
+    reply.version !== SUBAGENT_PING.VERSION ||
+    reply.method !== SUBAGENT_PING.METHOD ||
+    reply.success !== true ||
+    !isRecord(reply.data) ||
+    reply.data.version !== SUBAGENT_PING.VERSION
+  ) {
+    throw new Error('Unsuccessful or invalid pi-subagents ping reply.');
+  }
+}
+
+async function assertSubagentsRespond(
+  piEventsBus: ExtensionAPI['events'],
 ): Promise<void> {
+  const requestId = randomUUID();
+  const { promise, resolve, reject } = Promise.withResolvers<unknown>();
+
+  const unsubscribe = piEventsBus.on(
+    `${SUBAGENT_PING.REPLY_EVENT_PREFIX}${requestId}`,
+    (reply) => {
+      if (isReplyWithRequestId(reply) && reply.requestId !== requestId) {
+        return;
+      }
+
+      resolve(reply);
+    },
+  );
+
+  const timeout = setTimeout(
+    () => reject(new Error('Pi-subagents ping timed out after 2000 ms.')),
+    SUBAGENT_PING.TIMEOUT_MS,
+  );
+
+  try {
+    piEventsBus.emit(SUBAGENT_PING.REQUEST_EVENT, {
+      version: SUBAGENT_PING.VERSION,
+      requestId,
+      method: SUBAGENT_PING.METHOD,
+    });
+    assertSuccessfulPingReply(await promise);
+  } finally {
+    clearTimeout(timeout);
+    unsubscribe();
+  }
+}
+
+type AssertEnvironmentInput = {
+  context: ExtensionContext;
+  piEventsBus: ExtensionAPI['events'];
+};
+
+export async function assertEnvironment({
+  context,
+  piEventsBus,
+}: AssertEnvironmentInput): Promise<void> {
   const projectRoot = await getProjectRoot(context);
 
   try {
@@ -92,4 +178,13 @@ export async function assertEnvironment(
   const config = await getActivationConfiguration(projectRoot);
 
   assertModelsAvailable({ context, config });
+
+  try {
+    await assertSubagentsRespond(piEventsBus);
+  } catch (error) {
+    throw new Error(
+      `${SUBAGENT_PING.INSTALLATION_ERROR} ${getErrorMessage(error)}`,
+      { cause: error },
+    );
+  }
 }

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