@emiliosp/pi-maestro 0.9.1 → 0.9.3

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.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.
+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).

package/ROADMAP.md

@@ -44,7 +44,7 @@ Applied glossary formatting across the documentation and recorded its exclusions
 
 ### R-14: Introduce Maestro at activation
 
-Implemented in `0.9.1`. npm publication is pending. 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.
+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.
 
@@ -62,8 +62,39 @@ 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).
 
+### R-16: Verify code quality against AGENTS.md instructions
+
+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`.
+
+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.
+
+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`.
+
+#### Evidence
+
+[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
 
+### R-06: Check subagent extensions at activation
+
+#### Objective
+
+Make `pi-subagents` availability problems visible before a `builder` or `verifier` `run` starts.
+
+#### Implementation status
+
+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`.
+
+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.
+
+[Specification](.specs/20261013-194407-check-pi-subagents-availability-with-ping-at-activation/spec.md).
+
+#### Completed when
+
+Unavailable `pi-subagents` prevents activation. The error identifies the problem.
+
+
 ## Next
 
 ## Later
@@ -92,16 +123,6 @@ When criteria are removed during `spec` preparation or revision, renumber the re
 
 The `spec` and its current references use consistent numbering.
 
-### R-06: Check subagent extensions at activation
-
-#### 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.
-
-#### Completed when
-
-Unavailable required subagent extensions prevent activation. The error identifies the problem.
-
 ### R-07: Guide initial configuration
 
 #### Objective
@@ -167,15 +188,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-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

@@ -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.1",
+  "version": "0.9.3",
   "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 },
+    );
+  }
 }