@emiliosp/pi-maestro 0.5.1 → 0.6.0

package/src/MaestroPaths.ts

@@ -1,8 +1,9 @@
 /**
- * Objective: Build validated paths for one Maestro workflow in the current checkout.
- * Used: Whenever Maestro reads or writes repository workflow artifacts.
+ * Objective: Build validated paths for one Maestro workflow in the current project.
+ * Used: Whenever Maestro reads or writes project workflow artifacts.
  */
 
+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';
@@ -10,12 +11,17 @@ import { isPathStrictlyWithin } from '#utils/path-strictly-within.ts';
 
 const PATHS = {
   SPEC_FILE: 'spec.md',
-  WORKFLOW: 'workflow.json',
-  HANDOFFS: 'handoffs',
-  BUILDER_HANDOFF: 'handoffs/builder.json',
-  VERIFIER_HANDOFF: 'handoffs/verifier.json',
-  ESCALATIONS: 'handoffs/escalations',
-  PROTOTYPES: 'prototypes',
+  WORKFLOW_FILE: 'workflow.json',
+  HANDOFFS_PATH: 'handoffs',
+  BUILDER_HANDOFFS_PATH: 'handoffs/builder',
+  VERIFIER_HANDOFFS_PATH: 'handoffs/verifier',
+  ESCALATIONS_PATH: 'handoffs/escalations',
+  PROTOTYPES_PATH: 'prototypes',
+} as const;
+
+const AGENTS_PREFIX = {
+  BUILDER: 'B',
+  VERIFIER: 'V',
 } as const;
 
 function assertSpecId(specId: string): void {
@@ -26,9 +32,9 @@ function assertSpecId(specId: string): void {
   }
 }
 
-function assertEscalationNumber(escalationNumber: number): void {
-  if (!Number.isSafeInteger(escalationNumber) || escalationNumber < 1) {
-    throw new Error('Escalation number must be a positive integer.');
+function assertArtifactNumber(artifactNumber: number): void {
+  if (!Number.isSafeInteger(artifactNumber) || artifactNumber < 1) {
+    throw new Error('Artifact number must be a positive integer.');
   }
 }
 
@@ -45,7 +51,7 @@ function assertSafeRelativePrototypePath(value: string): void {
 }
 
 export type MaestroPathsInput = {
-  repositoryRoot: string;
+  projectRoot: string;
   config: MaestroConfig;
 };
 
@@ -54,34 +60,39 @@ type EscalationPathInput = {
   escalationNumber: number;
 };
 
+type HandoffPathInput = {
+  specId: string;
+  handoffPassNumber: number;
+};
+
 type PrototypePathInput = {
   specId: string;
   relativePath: string;
 };
 
 export class MaestroPaths {
-  private readonly repositoryRoot: string;
+  private readonly projectRoot: string;
   private readonly specDirectory: string;
 
   private readonly specDirectoryFromRoot: string;
 
-  public constructor({ repositoryRoot, config }: MaestroPathsInput) {
+  public constructor({ projectRoot, config }: MaestroPathsInput) {
     if (
       !isPathStrictlyWithin({
-        parent: repositoryRoot,
-        candidate: config.specDirectory,
+        parent: projectRoot,
+        path: config.specDirectory,
       })
     ) {
-      throw new Error('Generated Maestro path leaves the Git root.');
+      throw new Error('Generated Maestro path leaves the project root.');
     }
 
-    this.repositoryRoot = repositoryRoot;
+    this.projectRoot = projectRoot;
     this.specDirectory = config.specDirectory;
-    this.specDirectoryFromRoot = relative(repositoryRoot, config.specDirectory);
+    this.specDirectoryFromRoot = relative(projectRoot, config.specDirectory);
   }
 
-  public getRepositoryRoot(): string {
-    return this.repositoryRoot;
+  public getProjectRoot(): string {
+    return this.projectRoot;
   }
 
   public getSpecDirectory(): string {
@@ -91,14 +102,14 @@ export class MaestroPaths {
   public getSpecPath(specId: string): string {
     assertSpecId(specId);
 
-    return resolve(this.repositoryRoot, this.specDirectoryFromRoot, specId);
+    return resolve(this.projectRoot, this.specDirectoryFromRoot, specId);
   }
 
   public getSpecFilePath(specId: string): string {
     assertSpecId(specId);
 
     return resolve(
-      this.repositoryRoot,
+      this.projectRoot,
       this.specDirectoryFromRoot,
       specId,
       PATHS.SPEC_FILE,
@@ -109,10 +120,10 @@ export class MaestroPaths {
     assertSpecId(specId);
 
     return resolve(
-      this.repositoryRoot,
+      this.projectRoot,
       this.specDirectoryFromRoot,
       specId,
-      PATHS.WORKFLOW,
+      PATHS.WORKFLOW_FILE,
     );
   }
 
@@ -120,43 +131,96 @@ export class MaestroPaths {
     assertSpecId(specId);
 
     return resolve(
-      this.repositoryRoot,
+      this.projectRoot,
       this.specDirectoryFromRoot,
       specId,
-      PATHS.HANDOFFS,
+      PATHS.HANDOFFS_PATH,
     );
   }
 
-  public getBuilderHandoffPath(specId: string): string {
-    assertSpecId(specId);
+  public getBuilderHandoffsPath(specId: string): string {
+    return resolve(this.getSpecPath(specId), PATHS.BUILDER_HANDOFFS_PATH);
+  }
+
+  public getVerifierHandoffsPath(specId: string): string {
+    return resolve(this.getSpecPath(specId), PATHS.VERIFIER_HANDOFFS_PATH);
+  }
+
+  public getBuilderHandoffPath({
+    specId,
+    handoffPassNumber,
+  }: HandoffPathInput): string {
+    assertArtifactNumber(handoffPassNumber);
 
     return resolve(
-      this.repositoryRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.BUILDER_HANDOFF,
+      this.getBuilderHandoffsPath(specId),
+      `${AGENTS_PREFIX.BUILDER}${handoffPassNumber}.json`,
     );
   }
 
-  public getVerifierHandoffPath(specId: string): string {
-    assertSpecId(specId);
+  public getVerifierHandoffPath({
+    specId,
+    handoffPassNumber,
+  }: HandoffPathInput): string {
+    assertArtifactNumber(handoffPassNumber);
 
     return resolve(
-      this.repositoryRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.VERIFIER_HANDOFF,
+      this.getVerifierHandoffsPath(specId),
+      `${AGENTS_PREFIX.VERIFIER}${handoffPassNumber}.json`,
     );
   }
 
+  public async getActiveBuilderHandoffPath(specId: string): Promise<string> {
+    const handoffPassNumber = (
+      await readdir(this.getBuilderHandoffsPath(specId))
+    ).length;
+
+    if (handoffPassNumber === 0) throw new Error('Builder handoff is missing.');
+
+    return this.getBuilderHandoffPath({ specId, handoffPassNumber });
+  }
+
+  public async getActiveVerifierHandoffPath(specId: string): Promise<string> {
+    const handoffPassNumber = (
+      await readdir(this.getVerifierHandoffsPath(specId))
+    ).length;
+
+    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;
+
+    return this.getBuilderHandoffPath({
+      specId,
+      handoffPassNumber: handoffPassNumber + 1,
+    });
+  }
+
+  public async getNextVerifierHandoffPath(specId: string): Promise<string> {
+    const handoffPassNumber = (
+      await readdir(this.getVerifierHandoffsPath(specId))
+    ).length;
+
+    return this.getVerifierHandoffPath({
+      specId,
+      handoffPassNumber: handoffPassNumber + 1,
+    });
+  }
+
   public getEscalationsPath(specId: string): string {
     assertSpecId(specId);
 
     return resolve(
-      this.repositoryRoot,
+      this.projectRoot,
       this.specDirectoryFromRoot,
       specId,
-      PATHS.ESCALATIONS,
+      PATHS.ESCALATIONS_PATH,
     );
   }
 
@@ -164,14 +228,14 @@ export class MaestroPaths {
     specId,
     escalationNumber,
   }: EscalationPathInput): string {
-    assertEscalationNumber(escalationNumber);
+    assertArtifactNumber(escalationNumber);
     assertSpecId(specId);
 
     return resolve(
-      this.repositoryRoot,
+      this.projectRoot,
       this.specDirectoryFromRoot,
       specId,
-      `${PATHS.ESCALATIONS}/E${escalationNumber}.json`,
+      `${PATHS.ESCALATIONS_PATH}/E${escalationNumber}.json`,
     );
   }
 
@@ -179,10 +243,10 @@ export class MaestroPaths {
     assertSpecId(specId);
 
     return resolve(
-      this.repositoryRoot,
+      this.projectRoot,
       this.specDirectoryFromRoot,
       specId,
-      PATHS.PROTOTYPES,
+      PATHS.PROTOTYPES_PATH,
     );
   }
 
@@ -195,7 +259,7 @@ export class MaestroPaths {
     const prototypesPath = this.getPrototypesPath(specId);
     const target = resolve(prototypesPath, relativePath);
 
-    if (!isPathStrictlyWithin({ parent: prototypesPath, candidate: target })) {
+    if (!isPathStrictlyWithin({ parent: prototypesPath, path: target })) {
       throw new Error(
         'Prototype path must stay inside the prototypes directory.',
       );

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

@@ -1,5 +1,5 @@
 /**
- * Objective: Check builder handoff content, spec ID, and revision.
+ * Objective: Check builder handoff content and spec ID.
  * Used: When Maestro handles builder handoff artifacts.
  */
 
@@ -48,14 +48,13 @@ function assertBuilderHandoffSchema(
 type AssertBuilderHandoffInput<Handoff = unknown> = {
   handoff: Handoff;
   specId: string;
-  revision: number;
 };
 
 export function assertBuilderHandoff(
   input: AssertBuilderHandoffInput,
 ): asserts input is AssertBuilderHandoffInput<BuilderHandoff> {
   assertBuilderHandoffSchema(input.handoff);
-  const { handoff, specId, revision } = input;
+  const { handoff, specId } = input;
 
   if (!isValidSpecId(handoff.specId)) {
     throw new Error(`Invalid builder handoff spec ID: "${handoff.specId}".`);
@@ -85,21 +84,9 @@ export function assertBuilderHandoff(
     throw new Error(`Invalid expected builder handoff spec ID: "${specId}".`);
   }
 
-  if (!Number.isSafeInteger(revision) || revision < 1) {
-    throw new Error(
-      'Expected builder handoff revision must be a positive integer.',
-    );
-  }
-
   if (handoff.specId !== specId) {
     throw new Error(
       `Builder handoff spec ID mismatch: expected "${specId}", found "${handoff.specId}".`,
     );
   }
-
-  if (handoff.revision !== revision) {
-    throw new Error(
-      `Builder handoff revision mismatch: expected ${revision}, found ${handoff.revision}.`,
-    );
-  }
 }

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

@@ -10,18 +10,15 @@ import { readJsonFile } from '#utils/read-json.ts';
 type ReadBuilderHandoffInput = {
   path: string;
   specId: string;
-  revision: number;
 };
 
 export const readBuilderHandoff = async ({
   path,
   specId,
-  revision,
 }: ReadBuilderHandoffInput): Promise<BuilderHandoff> => {
   const input = {
     handoff: await readJsonFile({ path, description: 'Builder handoff' }),
     specId,
-    revision,
   };
 
   assertBuilderHandoff(input);

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

@@ -51,7 +51,7 @@ const BuilderHandoffContentFields = {
 const BuilderHandoffFields = {
   version: Type.Literal(BUILDER_HANDOFF_VERSION),
   specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-  revision: Type.Integer({ minimum: 1 }),
+
   ...BuilderHandoffContentFields,
 };
 

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

@@ -4,21 +4,19 @@
  */
 
 import { assertBuilderHandoff } from '#artifacts/builder-handoff/assertBuilderHandoff.ts';
-import { writeJsonAtomically } from '#utils/write-json-atomically.ts';
+import { writeJson } from '#utils/write-json.ts';
 
 type WriteBuilderHandoffInput = {
   path: string;
   handoff: unknown;
   specId: string;
-  revision: number;
 };
 
 export const writeBuilderHandoff = async ({
   path,
   handoff,
   specId,
-  revision,
 }: WriteBuilderHandoffInput): Promise<void> => {
-  assertBuilderHandoff({ handoff, specId, revision });
-  await writeJsonAtomically({ path, data: handoff });
+  assertBuilderHandoff({ handoff, specId });
+  await writeJson({ path, data: handoff });
 };

package/src/artifacts/escalation/createEscalation.ts

@@ -11,19 +11,17 @@ import {
   type Escalation,
   type NewEscalation,
 } from '#artifacts/escalation/schema.ts';
-import { writeJsonAtomically } from '#utils/write-json-atomically.ts';
+import { writeJson } from '#utils/write-json.ts';
 
 type CreateEscalationInput = {
   directory: string;
   specId: string;
-  revision: number;
   escalation: NewEscalation;
 };
 
 export const createEscalation = async ({
   directory,
   specId,
-  revision,
   escalation,
 }: CreateEscalationInput): Promise<{
   path: string;
@@ -32,21 +30,23 @@ export const createEscalation = async ({
   const id = await getNextEscalationId({
     directory,
     specId,
-    currentRevision: revision,
   });
 
   const newEscalation = {
-    ...escalation,
+    question: escalation.question,
+    context: escalation.context,
+    options: escalation.options,
+    recommendation: escalation.recommendation,
+    notes: escalation.notes,
     version: ESCALATION_VERSION,
     specId,
-    revision,
     id,
     resolution: null,
   };
 
   assertEscalation(newEscalation);
   const path = join(directory, `${id}.json`);
-  await writeJsonAtomically({ path, data: newEscalation });
+  await writeJson({ path, data: newEscalation });
 
   return { path, escalation: newEscalation };
 };

package/src/artifacts/escalation/getNextEscalationId.ts

@@ -8,18 +8,15 @@ import { readEscalationHistory } from '#artifacts/escalation/readEscalationHisto
 type GetNextEscalationIdInput = {
   directory: string;
   specId: string;
-  currentRevision: number;
 };
 
 export const getNextEscalationId = async ({
   directory,
   specId,
-  currentRevision,
 }: GetNextEscalationIdInput): Promise<string> => {
   const history = await readEscalationHistory({
     directory,
     specId,
-    currentRevision,
   });
 
   return `E${history.length + 1}`;

package/src/artifacts/escalation/readEscalation.ts

@@ -10,41 +10,31 @@ import { readJsonFile } from '#utils/read-json.ts';
 type AssertWorkflowEscalationInput = {
   escalation: Escalation;
   specId: string;
-  currentRevision: number;
 };
 
 function assertWorkflowEscalation({
   escalation,
   specId,
-  currentRevision,
 }: AssertWorkflowEscalationInput): void {
   if (escalation.specId !== specId) {
     throw new Error(
       `Escalation spec ID mismatch: expected "${specId}", found "${escalation.specId}".`,
     );
   }
-
-  if (escalation.revision > currentRevision) {
-    throw new Error(
-      `Escalation revision ${escalation.revision} is newer than workflow revision ${currentRevision}.`,
-    );
-  }
 }
 
 type ReadEscalationInput = {
   path: string;
   specId: string;
-  currentRevision: number;
 };
 
 export const readEscalation = async ({
   path,
   specId,
-  currentRevision,
 }: ReadEscalationInput): Promise<Escalation> => {
   const escalation = await readJsonFile({ path, description: 'Escalation' });
   assertEscalation(escalation);
-  assertWorkflowEscalation({ escalation, specId, currentRevision });
+  assertWorkflowEscalation({ escalation, specId });
 
   return escalation;
 };

package/src/artifacts/escalation/readEscalationHistory.ts

@@ -13,13 +13,11 @@ const ESCALATION_FILE_PATTERN = /^E([1-9]\d*)\.json$/;
 type ReadEscalationHistoryInput = {
   directory: string;
   specId: string;
-  currentRevision: number;
 };
 
 export const readEscalationHistory = async ({
   directory,
   specId,
-  currentRevision,
 }: ReadEscalationHistoryInput): Promise<Escalation[]> => {
   const files = await readdir(directory);
 
@@ -37,7 +35,6 @@ export const readEscalationHistory = async ({
     const escalation = await readEscalation({
       path: join(directory, file),
       specId,
-      currentRevision,
     });
 
     escalations.push(escalation);

package/src/artifacts/escalation/resolveEscalation.ts

@@ -9,45 +9,35 @@ import type {
   Escalation,
   EscalationResolution,
 } from '#artifacts/escalation/schema.ts';
-import { writeJsonAtomically } from '#utils/write-json-atomically.ts';
+import { writeJson } from '#utils/write-json.ts';
 
 type ResolveEscalationInput = {
   path: string;
   specId: string;
-  revision: number;
   resolution: EscalationResolution;
 };
 
 export const resolveEscalation = async ({
   path,
   specId,
-  revision,
   resolution,
 }: ResolveEscalationInput): Promise<Escalation> => {
   const current = await readEscalation({
     path,
     specId,
-    currentRevision: revision,
   });
 
   if (current.resolution !== null) {
     throw new Error(`Escalation "${current.id}" is already resolved.`);
   }
 
-  if (revision <= current.revision) {
-    throw new Error(
-      `Escalation resolution revision must be greater than ${current.revision}.`,
-    );
-  }
-
   const resolvedEscalation = {
     ...current,
-    revision,
     resolution,
   };
 
   assertEscalation(resolvedEscalation);
-  await writeJsonAtomically({ path, data: resolvedEscalation });
+  await writeJson({ path, data: resolvedEscalation });
 
   return resolvedEscalation;
 };

package/src/artifacts/escalation/schema.ts

@@ -56,7 +56,6 @@ export const EscalationSchema = Type.Object(
   {
     version: Type.Literal(ESCALATION_VERSION),
     specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-    revision: Type.Integer({ minimum: 1 }),
     id: Type.String({ pattern: ESCALATION_ID_PATTERN.source }),
     ...NewEscalationFields,
     recommendation: Type.Union([EscalationRecommendationSchema, Type.Null()]),

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

@@ -1,5 +1,5 @@
 /**
- * Objective: Check verifier handoff content, spec ID, and revision.
+ * Objective: Check verifier handoff content and spec ID.
  * Used: When Maestro handles verifier handoff artifacts.
  */
 
@@ -28,14 +28,13 @@ function assertVerifierHandoffSchema(
 type AssertVerifierHandoffInput<Handoff = unknown> = {
   handoff: Handoff;
   specId: string;
-  revision: number;
 };
 
 export function assertVerifierHandoff(
   input: AssertVerifierHandoffInput,
 ): asserts input is AssertVerifierHandoffInput<VerifierHandoff> {
   assertVerifierHandoffSchema(input.handoff);
-  const { handoff, specId, revision } = input;
+  const { handoff, specId } = input;
 
   if (!isValidSpecId(handoff.specId)) {
     throw new Error(`Invalid verifier handoff spec ID: "${handoff.specId}".`);
@@ -95,10 +94,4 @@ export function assertVerifierHandoff(
       `Verifier handoff spec ID mismatch: expected "${specId}", found "${handoff.specId}".`,
     );
   }
-
-  if (handoff.revision !== revision) {
-    throw new Error(
-      `Verifier handoff revision mismatch: expected ${revision}, found ${handoff.revision}.`,
-    );
-  }
 }

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

@@ -10,18 +10,15 @@ import { readJsonFile } from '#utils/read-json.ts';
 type ReadVerifierHandoffInput = {
   path: string;
   specId: string;
-  revision: number;
 };
 
 export const readVerifierHandoff = async ({
   path,
   specId,
-  revision,
 }: ReadVerifierHandoffInput): Promise<VerifierHandoff> => {
   const input = {
     handoff: await readJsonFile({ path, description: 'Verifier handoff' }),
     specId,
-    revision,
   };
 
   assertVerifierHandoff(input);

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

@@ -32,10 +32,25 @@ const FindingEvidenceSchema = Type.Object(
   { additionalProperties: false },
 );
 
-const FindingRejectionSchema = Type.Object(
-  { reason: Type.String({ minLength: 1 }) },
-  { additionalProperties: false },
-);
+export const FINDING_DECISIONS = {
+  REJECT: 'reject',
+  FIX_CODE: 'fix-code',
+} as const;
+
+const FindingDecisionSchema = Type.Union([
+  Type.Null(),
+  Type.Object(
+    {
+      decision: Type.Literal(FINDING_DECISIONS.REJECT),
+      reason: Type.String({ minLength: 1 }),
+    },
+    { additionalProperties: false },
+  ),
+  Type.Object(
+    { decision: Type.Literal(FINDING_DECISIONS.FIX_CODE) },
+    { additionalProperties: false },
+  ),
+]);
 
 export const VerifierFindingSchema = Type.Object(
   {
@@ -48,7 +63,7 @@ export const VerifierFindingSchema = Type.Object(
     confidence: Type.Number({ minimum: 0, maximum: 1 }),
     summary: Type.String({ minLength: 1 }),
     evidence: Type.Array(FindingEvidenceSchema, { minItems: 1 }),
-    rejection: Type.Union([FindingRejectionSchema, Type.Null()]),
+    decision: FindingDecisionSchema,
   },
   { additionalProperties: false },
 );
@@ -57,7 +72,6 @@ export const VerifierHandoffSchema = Type.Object(
   {
     version: Type.Literal(VERIFIER_HANDOFF_VERSION),
     specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-    revision: Type.Integer({ minimum: 1 }),
     summary: Type.String({ minLength: 1 }),
     acceptanceCriteria: Type.Array(BuilderAcceptanceCriterionSchema),
     findings: Type.Array(VerifierFindingSchema),