@emiliosp/pi-maestro 0.11.0 → 0.12.0

package/src/MaestroPaths.ts

@@ -5,12 +5,15 @@
 
 import { readdir } from 'node:fs/promises';
 import { isAbsolute, relative, resolve } from 'node:path';
+
 import type { MaestroConfig } from '#config/schema.ts';
 import { isValidSpecId } from '#ids/isValidSpecId.ts';
 import { isPathStrictlyWithin } from '#utils/path-strictly-within.ts';
 
 const PATHS = {
+  PROPOSAL_FILE: 'proposal.md',
   SPEC_FILE: 'spec.md',
+  DESIGN_FILE: 'design.md',
   WORKFLOW_FILE: 'workflow.json',
   HANDOFFS_PATH: 'handoffs',
   BUILDER_HANDOFFS_PATH: 'handoffs/builder',
@@ -25,9 +28,7 @@ const AGENTS_PREFIX = {
 
 function assertSpecId(specId: string): void {
   if (!isValidSpecId(specId)) {
-    throw new Error(
-      `Invalid spec ID: "${specId}". Expected YYYYMMDD-HHmmss-<slug>.`,
-    );
+    throw new Error(`Invalid spec ID: "${specId}". Expected YYYYMMDD-HHmmss-<slug>.`);
   }
 }
 
@@ -43,9 +44,7 @@ function assertSafeRelativePrototypePath(value: string): void {
   }
 
   if (isAbsolute(value)) {
-    throw new Error(
-      'Prototype path must be relative to the prototypes directory.',
-    );
+    throw new Error('Prototype path must be relative to the prototypes directory.');
   }
 }
 
@@ -99,10 +98,18 @@ export class MaestroPaths {
     return resolve(this.projectRoot, this.specDirectoryFromRoot, specId);
   }
 
+  public getProposalFilePath(specId: string): string {
+    return resolve(this.getSpecPath(specId), PATHS.PROPOSAL_FILE);
+  }
+
   public getSpecFilePath(specId: string): string {
     return resolve(this.getSpecPath(specId), PATHS.SPEC_FILE);
   }
 
+  public getDesignFilePath(specId: string): string {
+    return resolve(this.getSpecPath(specId), PATHS.DESIGN_FILE);
+  }
+
   public getWorkflowPath(specId: string): string {
     return resolve(this.getSpecPath(specId), PATHS.WORKFLOW_FILE);
   }
@@ -119,10 +126,7 @@ export class MaestroPaths {
     return resolve(this.getSpecPath(specId), PATHS.VERIFIER_HANDOFFS_PATH);
   }
 
-  public getBuilderHandoffPath({
-    specId,
-    handoffPassNumber,
-  }: HandoffPathInput): string {
+  public getBuilderHandoffPath({ specId, handoffPassNumber }: HandoffPathInput): string {
     assertArtifactNumber(handoffPassNumber);
 
     return resolve(
@@ -131,10 +135,7 @@ export class MaestroPaths {
     );
   }
 
-  public getVerifierHandoffPath({
-    specId,
-    handoffPassNumber,
-  }: HandoffPathInput): string {
+  public getVerifierHandoffPath({ specId, handoffPassNumber }: HandoffPathInput): string {
     assertArtifactNumber(handoffPassNumber);
 
     return resolve(
@@ -144,9 +145,7 @@ export class MaestroPaths {
   }
 
   public async getActiveBuilderHandoffPath(specId: string): Promise<string> {
-    const handoffPassNumber = (
-      await readdir(this.getBuilderHandoffsPath(specId))
-    ).length;
+    const handoffPassNumber = (await readdir(this.getBuilderHandoffsPath(specId))).length;
 
     if (handoffPassNumber === 0) throw new Error('Builder handoff is missing.');
 
@@ -154,20 +153,15 @@ export class MaestroPaths {
   }
 
   public async getActiveVerifierHandoffPath(specId: string): Promise<string> {
-    const handoffPassNumber = (
-      await readdir(this.getVerifierHandoffsPath(specId))
-    ).length;
+    const handoffPassNumber = (await readdir(this.getVerifierHandoffsPath(specId))).length;
 
-    if (handoffPassNumber === 0)
-      throw new Error('Verifier handoff is missing.');
+    if (handoffPassNumber === 0) throw new Error('Verifier handoff is missing.');
 
     return this.getVerifierHandoffPath({ specId, handoffPassNumber });
   }
 
   public async getNextBuilderHandoffPath(specId: string): Promise<string> {
-    const handoffPassNumber = (
-      await readdir(this.getBuilderHandoffsPath(specId))
-    ).length;
+    const handoffPassNumber = (await readdir(this.getBuilderHandoffsPath(specId))).length;
 
     return this.getBuilderHandoffPath({
       specId,
@@ -176,9 +170,7 @@ export class MaestroPaths {
   }
 
   public async getNextVerifierHandoffPath(specId: string): Promise<string> {
-    const handoffPassNumber = (
-      await readdir(this.getVerifierHandoffsPath(specId))
-    ).length;
+    const handoffPassNumber = (await readdir(this.getVerifierHandoffsPath(specId))).length;
 
     return this.getVerifierHandoffPath({
       specId,
@@ -194,19 +186,14 @@ export class MaestroPaths {
     return resolve(this.getSpecPath(specId), PATHS.PROTOTYPES_PATH);
   }
 
-  public getPrototypePath({
-    specId,
-    relativePath,
-  }: PrototypePathInput): string {
+  public getPrototypePath({ specId, relativePath }: PrototypePathInput): string {
     assertSafeRelativePrototypePath(relativePath);
 
     const prototypesPath = this.getPrototypesPath(specId);
     const target = resolve(prototypesPath, relativePath);
 
     if (!isPathStrictlyWithin({ parent: prototypesPath, path: target })) {
-      throw new Error(
-        'Prototype path must stay inside the prototypes directory.',
-      );
+      throw new Error('Prototype path must stay inside the prototypes directory.');
     }
 
     return target;

package/src/artifacts/builder-handoff/assertBuilderHandoff.ts

@@ -4,6 +4,7 @@
  */
 
 import { Value } from 'typebox/value';
+
 import {
   BUILDER_HANDOFF_STATUSES,
   type BuilderAcceptanceCriterion,
@@ -16,19 +17,12 @@ import { isValidSpecId } from '#ids/isValidSpecId.ts';
 const hasUniqueAcceptanceCriterionIds = (
   acceptanceCriteria: BuilderAcceptanceCriterion[],
 ): boolean =>
-  new Set(acceptanceCriteria.map((criterion) => criterion.id)).size ===
-  acceptanceCriteria.length;
+  new Set(acceptanceCriteria.map((criterion) => criterion.id)).size === acceptanceCriteria.length;
 
-const hasOnlyPassedProbes = (
-  acceptanceCriteria: BuilderAcceptanceCriterion[],
-): boolean =>
-  acceptanceCriteria.every(
-    (criterion) => criterion.probeStatus === PROBE_STATUSES.PASSED,
-  );
+const hasOnlyPassedProbes = (acceptanceCriteria: BuilderAcceptanceCriterion[]): boolean =>
+  acceptanceCriteria.every((criterion) => criterion.probeStatus === PROBE_STATUSES.PASSED);
 
-function assertBuilderHandoffSchema(
-  input: unknown,
-): asserts input is BuilderHandoff {
+function assertBuilderHandoffSchema(input: unknown): asserts input is BuilderHandoff {
   if (typeof input !== 'object' || input === null || Array.isArray(input)) {
     throw new Error('Builder handoff must be a JSON object.');
   }
@@ -77,10 +71,7 @@ export function assertBuilderHandoff(
       throw new Error('Escalation option IDs must be unique.');
     }
 
-    if (
-      escalation.recommendation !== null &&
-      !optionIds.has(escalation.recommendation.optionId)
-    ) {
+    if (escalation.recommendation !== null && !optionIds.has(escalation.recommendation.optionId)) {
       throw new Error('Escalation recommendation references unknown option.');
     }
 

package/src/artifacts/builder-handoff/schema.ts

@@ -5,6 +5,7 @@
 
 import { StringEnum } from '@earendil-works/pi-ai';
 import { type Static, Type } from 'typebox';
+
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 
 export const BUILDER_HANDOFF_VERSION = '1.0.0';
@@ -36,9 +37,7 @@ export const BuilderAcceptanceCriterionSchema = Type.Object(
   { additionalProperties: false },
 );
 
-export type BuilderAcceptanceCriterion = Static<
-  typeof BuilderAcceptanceCriterionSchema
->;
+export type BuilderAcceptanceCriterion = Static<typeof BuilderAcceptanceCriterionSchema>;
 
 const BuilderHandoffContentFields = {
   summary: Type.String({ minLength: 1 }),
@@ -158,6 +157,4 @@ export const BuilderHandoffSubmissionSchema = Type.Union([
   BuilderEscalationHandoffSubmissionSchema,
 ]);
 
-export type BuilderHandoffSubmissionInput = Static<
-  typeof BuilderHandoffSubmissionSchema
->;
+export type BuilderHandoffSubmissionInput = Static<typeof BuilderHandoffSubmissionSchema>;

package/src/artifacts/simplifier-handoff/assertSimplifierHandoff.ts

@@ -4,7 +4,9 @@
  */
 
 import { isAbsolute, resolve } from 'node:path';
+
 import { Value } from 'typebox/value';
+
 import {
   type SimplifierHandoff,
   SimplifierHandoffSchema,
@@ -17,9 +19,7 @@ type AssertSimplifierHandoffInput<Handoff = unknown> = {
   projectRoot: string;
 };
 
-function assertSimplifierHandoffSchema(
-  input: unknown,
-): asserts input is SimplifierHandoff {
+function assertSimplifierHandoffSchema(input: unknown): asserts input is SimplifierHandoff {
   const [error] = Value.Errors(SimplifierHandoffSchema, input);
 
   if (error !== undefined) {

package/src/artifacts/simplifier-handoff/schema.ts

@@ -4,6 +4,7 @@
  */
 
 import { type Static, Type } from 'typebox';
+
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 
 export const SIMPLIFIER_HANDOFF_VERSION = '1.0.0';

package/src/artifacts/verifier-handoff/assertVerifierHandoff.ts

@@ -4,16 +4,12 @@
  */
 
 import { Value } from 'typebox/value';
+
 import { PROBE_STATUSES } from '#artifacts/builder-handoff/schema.ts';
-import {
-  type VerifierHandoff,
-  VerifierHandoffSchema,
-} from '#artifacts/verifier-handoff/schema.ts';
+import { type VerifierHandoff, VerifierHandoffSchema } from '#artifacts/verifier-handoff/schema.ts';
 import { isValidSpecId } from '#ids/isValidSpecId.ts';
 
-function assertVerifierHandoffSchema(
-  input: unknown,
-): asserts input is VerifierHandoff {
+function assertVerifierHandoffSchema(input: unknown): asserts input is VerifierHandoff {
   if (typeof input !== 'object' || input === null || Array.isArray(input)) {
     throw new Error('Verifier handoff must be a JSON object.');
   }
@@ -45,9 +41,7 @@ export function assertVerifierHandoff(
   );
 
   if (acceptanceCriterionIds.size !== handoff.acceptanceCriteria.length) {
-    throw new Error(
-      'Verifier handoff acceptance criterion IDs must be unique.',
-    );
+    throw new Error('Verifier handoff acceptance criterion IDs must be unique.');
   }
 
   const criterionIdsWithFindings = new Set<string>();

package/src/artifacts/verifier-handoff/schema.ts

@@ -4,6 +4,7 @@
  */
 
 import { type Static, Type } from 'typebox';
+
 import { BuilderAcceptanceCriterionSchema } from '#artifacts/builder-handoff/schema.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 
@@ -15,8 +16,7 @@ export const FINDING_SEVERITIES = {
   LOW: 'low',
 } as const;
 
-export type FindingSeverity =
-  (typeof FINDING_SEVERITIES)[keyof typeof FINDING_SEVERITIES];
+export type FindingSeverity = (typeof FINDING_SEVERITIES)[keyof typeof FINDING_SEVERITIES];
 
 const FindingSeveritySchema = Type.Union([
   Type.Literal(FINDING_SEVERITIES.HIGH),
@@ -64,10 +64,7 @@ const FindingDecisionSchema = Type.Union([
 export const VerifierFindingSchema = Type.Object(
   {
     id: Type.String({ pattern: '^F[1-9]\\d*$' }),
-    acceptanceCriterion: Type.Union([
-      Type.String({ minLength: 1 }),
-      Type.Null(),
-    ]),
+    acceptanceCriterion: Type.Union([Type.String({ minLength: 1 }), Type.Null()]),
     severity: FindingSeveritySchema,
     confidence: Type.Number({ minimum: 0, maximum: 1 }),
     summary: Type.String({ minLength: 1 }),

package/src/artifacts/verifier-handoff/writeVerifierHandoff.ts

@@ -22,9 +22,7 @@ export const writeVerifierHandoff = async ({
   const { handoff } = input;
 
   if (handoff.findings.some((finding) => finding.decision !== null)) {
-    throw new Error(
-      'New verifier handoff findings must have no owner decision.',
-    );
+    throw new Error('New verifier handoff findings must have no owner decision.');
   }
 
   await writeJson({ path, data: handoff });

package/src/config/assertConfiguration.ts

@@ -4,6 +4,7 @@
  */
 
 import { Value } from 'typebox/value';
+
 import {
   MAX_TIMEOUT_MINUTES,
   MaestroConfigInputSchema,
@@ -52,9 +53,7 @@ const formatError = (error: SchemaValidationError): string => {
   return `Invalid configuration at "${path}": ${error.message}.`;
 };
 
-export function assertConfiguration(
-  input: unknown,
-): asserts input is PartialMaestroConfig {
+export function assertConfiguration(input: unknown): asserts input is PartialMaestroConfig {
   if (typeof input !== 'object' || input === null || Array.isArray(input)) {
     throw new Error('Configuration must be a JSON object.');
   }
@@ -62,9 +61,7 @@ export function assertConfiguration(
   const raw = input;
 
   if (!('version' in raw) || raw.version === undefined) {
-    throw new Error(
-      "Missing configuration version. The 'version' field is required.",
-    );
+    throw new Error("Missing configuration version. The 'version' field is required.");
   }
 
   if (typeof raw.version !== 'string') {

package/src/config/defaults.ts

@@ -3,11 +3,7 @@
  * Used: When configuration is resolved from missing or partial input.
  */
 
-import {
-  type MaestroConfig,
-  SUPPORTED_CONFIG_VERSION,
-  THINKING_LEVELS,
-} from '#config/schema.ts';
+import { type MaestroConfig, SUPPORTED_CONFIG_VERSION, THINKING_LEVELS } from '#config/schema.ts';
 
 export const DEFAULT_CONFIG_VERSION = SUPPORTED_CONFIG_VERSION;
 

package/src/config/loadConfiguration.ts

@@ -5,6 +5,7 @@
 
 import { readFile, realpath } from 'node:fs/promises';
 import { isAbsolute, join, resolve } from 'node:path';
+
 import { assertConfiguration } from '#config/assertConfiguration.ts';
 import { CONFIG_FILE_PATH, DEFAULT_CONFIG } from '#config/defaults.ts';
 import type { MaestroConfig, PartialMaestroConfig } from '#config/schema.ts';
@@ -24,10 +25,7 @@ type ResolveSpecDirectoryInput = {
   directory: string;
 };
 
-const resolveSpecDirectory = ({
-  projectRoot,
-  directory,
-}: ResolveSpecDirectoryInput): string => {
+const resolveSpecDirectory = ({ projectRoot, directory }: ResolveSpecDirectoryInput): string => {
   if (directory.includes('\0')) {
     throw new Error('specDirectory must not contain a null byte.');
   }
@@ -59,10 +57,7 @@ type ResolveDirectoriesInput = {
   config: MaestroConfig;
 };
 
-const resolveDirectories = ({
-  projectRoot,
-  config,
-}: ResolveDirectoriesInput): MaestroConfig => {
+const resolveDirectories = ({ projectRoot, config }: ResolveDirectoriesInput): MaestroConfig => {
   const specDirectory = resolveSpecDirectory({
     projectRoot,
     directory: config.specDirectory,
@@ -85,9 +80,7 @@ const readConfigurationFile = async (path: string): Promise<unknown> => {
   }
 };
 
-export const loadConfiguration = async (
-  cwd: string = process.cwd(),
-): Promise<MaestroConfig> => {
+export const loadConfiguration = async (cwd: string = process.cwd()): Promise<MaestroConfig> => {
   const projectRoot = await realpath(cwd);
   const targetPath = join(projectRoot, CONFIG_FILE_PATH);
 

package/src/config/schema.ts

@@ -21,8 +21,7 @@ export const THINKING_LEVELS = {
   MAX: 'max',
 } as const;
 
-export type ThinkingLevel =
-  (typeof THINKING_LEVELS)[keyof typeof THINKING_LEVELS];
+export type ThinkingLevel = (typeof THINKING_LEVELS)[keyof typeof THINKING_LEVELS];
 
 export const MODEL_PATTERN = '^[^/\\s]+/[^/\\s]+$';
 

package/src/ids/createSpecId.ts

@@ -41,5 +41,4 @@ type CreateSpecIdInput = {
 export const createSpecId = ({
   title,
   instant = Temporal.Now.instant(),
-}: CreateSpecIdInput): string =>
-  `${formatUtcTimestamp(instant)}-${normalizeSlug(title)}`;
+}: CreateSpecIdInput): string => `${formatUtcTimestamp(instant)}-${normalizeSlug(title)}`;

package/src/ids/isValidSpecId.ts

@@ -12,8 +12,7 @@ const isValidUtcTimestamp = (value: string): boolean => {
     return false;
   }
 
-  const [, yearText, monthText, dayText, hourText, minuteText, secondText] =
-    match;
+  const [, yearText, monthText, dayText, hourText, minuteText, secondText] = match;
 
   try {
     Temporal.PlainDateTime.from(

package/src/maestro/checks/assertEnvironment.ts

@@ -5,11 +5,10 @@
 
 import { randomUUID } from 'node:crypto';
 import { realpath } from 'node:fs/promises';
-import type {
-  ExtensionAPI,
-  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';
 
@@ -19,8 +18,7 @@ export const SUBAGENT_PING = {
   VERSION: 1,
   METHOD: 'ping',
   TIMEOUT_MS: 2000,
-  INSTALLATION_ERROR:
-    'Maestro flow requires pi-subagents installed in the Pi environment.',
+  INSTALLATION_ERROR: 'Maestro flow requires pi-subagents installed in the Pi environment.',
 } as const;
 
 const getErrorMessage = (error: unknown): string =>
@@ -46,9 +44,7 @@ const getActivationConfiguration = async (
   try {
     return await loadConfiguration(projectRoot);
   } catch (error) {
-    throw new Error(
-      `Maestro configuration check failed: ${getErrorMessage(error)}`,
-    );
+    throw new Error(`Maestro configuration check failed: ${getErrorMessage(error)}`);
   }
 };
 
@@ -57,24 +53,13 @@ type AssertModelsAvailableInput = {
   config: Awaited<ReturnType<typeof loadConfiguration>>;
 };
 
-function assertModelsAvailable({
-  context,
-  config,
-}: AssertModelsAvailableInput): void {
+function assertModelsAvailable({ context, config }: AssertModelsAvailableInput): void {
   const availableModels = context.modelRegistry.getAvailable();
 
-  for (const model of [
-    config.builder.model,
-    config.verifier.model,
-    config.simplifier.model,
-  ]) {
+  for (const model of [config.builder.model, config.verifier.model, config.simplifier.model]) {
     const [provider, id] = model.split('/');
 
-    if (
-      !availableModels.some(
-        (entry) => entry.provider === provider && entry.id === id,
-      )
-    ) {
+    if (!availableModels.some((entry) => entry.provider === provider && entry.id === id)) {
       throw new Error(`Configured model is not available: "${model}".`);
     }
   }
@@ -102,17 +87,7 @@ const isReplyWithRequestId = (
 ): 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 {
+function assertSuccessfulPingReply(reply: unknown): void {
   if (
     !isReplyWithRequestId(reply) ||
     reply.version !== SUBAGENT_PING.VERSION ||
@@ -125,22 +100,17 @@ function assertSuccessfulPingReply(
   }
 }
 
-async function assertSubagentsRespond(
-  piEventsBus: ExtensionAPI['events'],
-): Promise<void> {
+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;
-      }
+  const unsubscribe = piEventsBus.on(`${SUBAGENT_PING.REPLY_EVENT_PREFIX}${requestId}`, (reply) => {
+    if (isReplyWithRequestId(reply) && reply.requestId !== requestId) {
+      return;
+    }
 
-      resolve(reply);
-    },
-  );
+    resolve(reply);
+  });
 
   const timeout = setTimeout(
     () => reject(new Error('Pi-subagents ping timed out after 2000 ms.')),
@@ -186,9 +156,8 @@ export async function assertEnvironment({
   try {
     await assertSubagentsRespond(piEventsBus);
   } catch (error) {
-    throw new Error(
-      `${SUBAGENT_PING.INSTALLATION_ERROR} ${getErrorMessage(error)}`,
-      { cause: error },
-    );
+    throw new Error(`${SUBAGENT_PING.INSTALLATION_ERROR} ${getErrorMessage(error)}`, {
+      cause: error,
+    });
   }
 }