@emiliosp/pi-maestro 0.5.2 → 0.6.1

package/src/workflow/escalation/resolveBuilderEscalation.ts

@@ -1,5 +1,5 @@
 /**
- * Objective: Resolve the current builder escalation and checkpoint the decision.
+ * Objective: Resolve the current builder escalation and save the decision.
  * Used: When the owner keeps the approved contract and makes a decision.
  */
 
@@ -9,7 +9,6 @@ import type {
   Escalation,
   EscalationResolution,
 } from '#artifacts/escalation/schema.ts';
-import { createWorkflowCheckpointCommit } from '#git/commits/createWorkflowCheckpointCommit.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import {
@@ -23,8 +22,7 @@ import { transitionWorkflow } from '#workflow/transitions.ts';
 export type ResolvedBuilderEscalation = {
   escalation: Escalation;
   state: WorkflowState;
-  repositoryRoot: string;
-  checkpointCommit: string;
+  projectRoot: string;
 };
 
 type AssertCurrentEscalationInput<CurrentEscalation = Escalation | undefined> =
@@ -70,6 +68,12 @@ export const resolveBuilderEscalation = async ({
   const escalationsPath = paths.getEscalationsPath(specId);
   const currentState = await readWorkflowState(workflowPath);
 
+  if (currentState.specId !== specId) {
+    throw new Error(
+      `Workflow spec ID mismatch: expected "${specId}", found "${currentState.specId}".`,
+    );
+  }
+
   if (currentState.phase !== WORKFLOW_PHASES.ESCALATION_DECISION) {
     throw new Error(
       `Escalation resolution requires escalation-decision state, found "${currentState.phase}".`,
@@ -79,7 +83,6 @@ export const resolveBuilderEscalation = async ({
   const history = await readEscalationHistory({
     directory: escalationsPath,
     specId,
-    currentRevision: currentState.revision,
   });
 
   const escalationInput = { currentEscalation: history.at(-1), escalationId };
@@ -99,25 +102,17 @@ export const resolveBuilderEscalation = async ({
   const resolvedEscalation = await resolveEscalation({
     path: escalationPath,
     specId,
-    revision: nextState.revision,
     resolution,
   });
 
   await writeWorkflowState({
     path: workflowPath,
     state: nextState,
-    currentRevision: currentState.revision,
-  });
-
-  const checkpointCommit = await createWorkflowCheckpointCommit({
-    repositoryRoot: paths.getRepositoryRoot(),
-    expectedPaths: [workflowPath, escalationPath],
   });
 
   return {
     escalation: resolvedEscalation,
     state: nextState,
-    repositoryRoot: paths.getRepositoryRoot(),
-    checkpointCommit,
+    projectRoot: paths.getProjectRoot(),
   };
 };

package/src/workflow/findings/resolveFindings.ts

@@ -1,21 +1,17 @@
 /**
- * Objective: Record owner decisions for current verifier findings on the current branch.
+ * Objective: Record owner decisions for current verifier findings on the active handoff.
  * Used: When the owner resolves a findings-decision handoff.
  */
 
-import { relative } from 'node:path';
 import { assertVerifierHandoff } from '#artifacts/verifier-handoff/assertVerifierHandoff.ts';
 import { readVerifierHandoff } from '#artifacts/verifier-handoff/readVerifierHandoff.ts';
 import type {
   VerifierFinding,
   VerifierHandoff,
 } from '#artifacts/verifier-handoff/schema.ts';
-import { runGitCommand } from '#git/command.ts';
-import { createWorkflowCheckpointCommit } from '#git/commits/createWorkflowCheckpointCommit.ts';
-import { getHeadCommit } from '#git/repository/getHeadCommit.ts';
-import { getRepositoryStatus } from '#git/repository/getRepositoryStatus.ts';
+import { FINDING_DECISIONS } from '#artifacts/verifier-handoff/schema.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
-import { writeJsonAtomically } from '#utils/write-json-atomically.ts';
+import { writeJson } from '#utils/write-json.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import {
   WORKFLOW_EVENTS,
@@ -25,11 +21,6 @@ import {
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
 
-export const FINDING_DECISIONS = {
-  REJECT: 'reject',
-  FIX_CODE: 'fix-code',
-} as const;
-
 type FindingDecisionRejected = {
   findingId: string;
   decision: typeof FINDING_DECISIONS.REJECT;
@@ -46,8 +37,7 @@ export type FindingDecision = FindingDecisionApproved | FindingDecisionRejected;
 export type ResolvedFindings = {
   findings: VerifierFinding[];
   state: WorkflowState;
-  repositoryRoot: string;
-  checkpointCommit: string;
+  projectRoot: string;
 };
 
 type AssertDecisionsInput = {
@@ -118,9 +108,8 @@ const readFindingWorkflow = async ({
   }
 
   const handoff = await readVerifierHandoff({
-    path: paths.getVerifierHandoffPath(specId),
+    path: await paths.getActiveVerifierHandoffPath(specId),
     specId,
-    revision: state.revision,
   });
 
   if (handoff.findings.length === 0) {
@@ -129,8 +118,10 @@ const readFindingWorkflow = async ({
     );
   }
 
-  if (handoff.findings.some(({ rejection }) => rejection !== null)) {
-    throw new Error('Current verifier findings already contain a rejection.');
+  if (handoff.findings.some(({ decision }) => decision !== null)) {
+    throw new Error(
+      'Current verifier findings already contain an owner decision.',
+    );
   }
 
   return { state, handoff };
@@ -155,11 +146,17 @@ const buildFindingWorkflow = ({
   const findings = handoff.findings.map((finding) => {
     const decision = decisionsById.get(finding.id);
 
-    if (decision?.decision !== FINDING_DECISIONS.REJECT) {
-      return finding;
+    if (decision?.decision === FINDING_DECISIONS.REJECT) {
+      return {
+        ...finding,
+        decision: {
+          decision: FINDING_DECISIONS.REJECT,
+          reason: decision.reason.trim(),
+        },
+      };
     }
 
-    return { ...finding, rejection: { reason: decision.reason.trim() } };
+    return { ...finding, decision: { decision: FINDING_DECISIONS.FIX_CODE } };
   });
 
   const isFixCodeRequested = decisions.some(
@@ -173,121 +170,15 @@ const buildFindingWorkflow = ({
       : WORKFLOW_EVENTS.REJECT_FINDINGS,
   });
 
-  const nextHandoff = { ...handoff, revision: nextState.revision, findings };
+  const nextHandoff = { ...handoff, findings };
   assertVerifierHandoff({
     handoff: nextHandoff,
     specId: state.specId,
-    revision: nextState.revision,
   });
 
   return { state: nextState, handoff: nextHandoff };
 };
 
-type AssertNoChangesOutsideFindingArtifactsInput = {
-  repositoryRoot: string;
-  workflowPath: string;
-  handoffPath: string;
-};
-
-async function assertNoChangesOutsideFindingArtifacts({
-  repositoryRoot,
-  workflowPath,
-  handoffPath,
-}: AssertNoChangesOutsideFindingArtifactsInput): Promise<void> {
-  const headCommit = await getHeadCommit(repositoryRoot);
-
-  // Compare both the checkout and index with HEAD. The index comparison also
-  // catches staged changes when the working file was restored on disk.
-  const [diff, stagedDiff, status] = await Promise.all([
-    runGitCommand({
-      arguments: [
-        'diff',
-        '--no-renames',
-        '--name-only',
-        '-z',
-        headCommit,
-        '--',
-      ],
-      cwd: repositoryRoot,
-    }),
-    runGitCommand({
-      arguments: [
-        'diff',
-        '--cached',
-        '--no-renames',
-        '--name-only',
-        '-z',
-        headCommit,
-        '--',
-      ],
-      cwd: repositoryRoot,
-    }),
-    getRepositoryStatus(repositoryRoot),
-  ]);
-
-  const allowedPaths = new Set([
-    relative(repositoryRoot, workflowPath),
-    relative(repositoryRoot, handoffPath),
-  ]);
-
-  const changedTrackedPaths = [diff.stdout, stagedDiff.stdout]
-    .flatMap((output) => output.split('\0'))
-    .filter((path) => path.length > 0);
-
-  if (
-    changedTrackedPaths.some((path) => !allowedPaths.has(path)) ||
-    status.untracked.some((path) => !allowedPaths.has(path))
-  ) {
-    throw new Error(
-      'Finding resolution requires no changes outside its protocol files.',
-    );
-  }
-}
-
-type CommitFindingWorkflowInput = {
-  paths: MaestroPaths;
-  specId: string;
-  currentRevision: number;
-  workflow: FindingWorkflow;
-};
-
-const commitFindingWorkflow = async ({
-  paths,
-  specId,
-  currentRevision,
-  workflow,
-}: CommitFindingWorkflowInput): Promise<string> => {
-  const repositoryRoot = paths.getRepositoryRoot();
-  const workflowPath = paths.getWorkflowPath(specId);
-  const handoffPath = paths.getVerifierHandoffPath(specId);
-
-  await assertNoChangesOutsideFindingArtifacts({
-    repositoryRoot,
-    workflowPath,
-    handoffPath,
-  });
-
-  await writeJsonAtomically({ path: handoffPath, data: workflow.handoff });
-  await writeWorkflowState({
-    path: workflowPath,
-    state: workflow.state,
-    currentRevision,
-  });
-
-  const checkpointCommit = await createWorkflowCheckpointCommit({
-    repositoryRoot,
-    expectedPaths: [handoffPath, workflowPath],
-  });
-
-  if (!(await getRepositoryStatus(repositoryRoot)).clean) {
-    throw new Error(
-      'Finding resolution requires a clean checkout after its commit.',
-    );
-  }
-
-  return checkpointCommit;
-};
-
 type ResolveFindingsInput = {
   paths: MaestroPaths;
   specId: string;
@@ -306,17 +197,16 @@ export const resolveFindings = async ({
     decisions,
   });
 
-  const checkpointCommit = await commitFindingWorkflow({
-    paths,
-    specId,
-    currentRevision: currentWorkflow.state.revision,
-    workflow,
+  const handoffPath = await paths.getActiveVerifierHandoffPath(specId);
+  await writeJson({ path: handoffPath, data: workflow.handoff });
+  await writeWorkflowState({
+    path: paths.getWorkflowPath(specId),
+    state: workflow.state,
   });
 
   return {
     findings: workflow.handoff.findings,
     state: workflow.state,
-    repositoryRoot: paths.getRepositoryRoot(),
-    checkpointCommit,
+    projectRoot: paths.getProjectRoot(),
   };
 };

package/src/workflow/spec/markSpecReady.ts

@@ -54,7 +54,6 @@ export const markSpecReady = async ({
   await writeWorkflowState({
     path: workflowPath,
     state,
-    currentRevision: current.revision,
   });
 
   return state;

package/src/workflow/state/readWorkflowState.ts

@@ -1,6 +1,6 @@
 /**
  * Objective: Read and validate a workflow state file.
- * Used: When Maestro loads a workflow phase or revision.
+ * Used: When Maestro loads a workflow phase.
  */
 
 import { readJsonFile } from '#utils/read-json.ts';
@@ -15,5 +15,5 @@ export const readWorkflowState = async (
   const state = await readJsonFile({ path, description: 'Workflow state' });
   assertWorkflowState(state);
 
-  return state;
+  return { version: state.version, specId: state.specId, phase: state.phase };
 };

package/src/workflow/state/schema.ts

@@ -51,7 +51,6 @@ export const WorkflowStateSchema = Type.Object(
   {
     version: Type.Literal(WORKFLOW_STATE_VERSION),
     specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-    revision: Type.Integer({ minimum: 1 }),
     phase: WorkflowPhaseSchema,
   },
   { additionalProperties: false },

package/src/workflow/state/writeWorkflowState.ts

@@ -1,82 +1,26 @@
 /**
- * Objective: Atomically write a validated workflow state at a new revision.
- * Used: When Maestro persists a workflow transition.
+ * Objective: Write a validated workflow state.
+ * Used: When Maestro persists a sequential workflow transition.
  */
 
-import { type FileHandle, open, rm } from 'node:fs/promises';
-import { isErrnoException } from '#utils/is-errno-exception.ts';
-import { pathExists } from '#utils/path-exists.ts';
-import { writeJsonAtomically } from '#utils/write-json-atomically.ts';
-import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
+import { writeJson } from '#utils/write-json.ts';
 import {
   assertWorkflowState,
   type WorkflowState,
 } from '#workflow/state/schema.ts';
 
-const acquireWorkflowLock = async (path: string): Promise<FileHandle> => {
-  try {
-    return await open(path, 'wx', 0o600);
-  } catch (error) {
-    if (isErrnoException(error) && error.code === 'EEXIST') {
-      throw new Error('Another workflow state update is in progress.', {
-        cause: error,
-      });
-    }
-
-    throw error;
-  }
-};
-
 type WriteWorkflowStateInput = {
   path: string;
   state: WorkflowState;
-  currentRevision: number;
 };
 
 export const writeWorkflowState = async ({
   path,
   state,
-  currentRevision,
 }: WriteWorkflowStateInput): Promise<void> => {
   assertWorkflowState(state);
-
-  if (!Number.isSafeInteger(currentRevision) || currentRevision < 0) {
-    throw new Error(
-      'Expected workflow revision must be a non-negative integer.',
-    );
-  }
-
-  if (state.revision <= currentRevision) {
-    throw new Error(
-      `Workflow revision must be higher than expected revision ${currentRevision}.`,
-    );
-  }
-
-  const lockPath = `${path}.lock`;
-  const lock = await acquireWorkflowLock(lockPath);
-
-  try {
-    const exists = await pathExists(path);
-
-    if (!exists && currentRevision !== 0) {
-      throw new Error(
-        `Stale workflow revision: expected ${currentRevision}, but no state exists.`,
-      );
-    }
-
-    if (exists) {
-      const current = await readWorkflowState(path);
-
-      if (current.revision !== currentRevision) {
-        throw new Error(
-          `Stale workflow revision: expected ${currentRevision}, found ${current.revision}.`,
-        );
-      }
-    }
-
-    await writeJsonAtomically({ path, data: state });
-  } finally {
-    await lock.close();
-    await rm(lockPath, { force: true });
-  }
+  await writeJson({
+    path,
+    data: { version: state.version, specId: state.specId, phase: state.phase },
+  });
 };

package/src/workflow/transitions.ts

@@ -92,8 +92,8 @@ export const transitionWorkflow = ({
   }
 
   return {
-    ...current,
-    revision: current.revision + 1,
+    version: current.version,
+    specId: current.specId,
     phase: transition.to,
   };
 };

package/src/workflow/verifier/completeVerifierPass.ts

@@ -4,12 +4,10 @@
  */
 
 import { mkdir } from 'node:fs/promises';
-import { dirname } from 'node:path';
 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';
 import type { MaestroPaths } from '#MaestroPaths.ts';
-import { pathExists } from '#utils/path-exists.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import {
   WORKFLOW_EVENTS,
@@ -22,7 +20,8 @@ import { transitionWorkflow } from '#workflow/transitions.ts';
 export type CompletedVerifierPass = {
   handoff: VerifierHandoff;
   state: WorkflowState;
-  repositoryRoot: string;
+  projectRoot: string;
+  handoffPath: string;
 };
 
 type CompleteVerifierPassInput = {
@@ -36,9 +35,8 @@ export const completeVerifierPass = async ({
   specId,
   handoff: draftHandoff,
 }: CompleteVerifierPassInput): Promise<CompletedVerifierPass> => {
-  const repositoryRoot = paths.getRepositoryRoot();
+  const projectRoot = paths.getProjectRoot();
   const workflowPath = paths.getWorkflowPath(specId);
-  const handoffPath = paths.getVerifierHandoffPath(specId);
   const currentState = await readWorkflowState(workflowPath);
 
   if (currentState.specId !== specId) {
@@ -53,14 +51,9 @@ export const completeVerifierPass = async ({
     );
   }
 
-  if (await pathExists(handoffPath)) {
-    throw new Error('Verifier terminal handoff already exists.');
-  }
-
   const handoffInput = {
     handoff: draftHandoff,
     specId,
-    revision: currentState.revision + 1,
   };
 
   assertVerifierHandoff(handoffInput);
@@ -74,22 +67,23 @@ export const completeVerifierPass = async ({
         : WORKFLOW_EVENTS.VERIFIER_APPROVED,
   });
 
-  await mkdir(dirname(handoffPath), { recursive: true });
+  await mkdir(paths.getVerifierHandoffsPath(specId), { recursive: true });
+  const handoffPath = await paths.getNextVerifierHandoffPath(specId);
+
   await writeVerifierHandoff({
     path: handoffPath,
     handoff,
     specId,
-    revision: nextState.revision,
   });
   await writeWorkflowState({
     path: workflowPath,
     state: nextState,
-    currentRevision: currentState.revision,
   });
 
   return {
     handoff,
+    handoffPath,
     state: nextState,
-    repositoryRoot,
+    projectRoot,
   };
 };

package/src/workflow/verifier/prepareVerifierRun.ts

@@ -1,13 +1,9 @@
 /**
- * Objective: Prepare a committed verifier run checkpoint in the current checkout.
+ * Objective: Prepare a verifier run transition in the project directory.
  * Used: When Maestro starts a verifier pass.
  */
 
-import { rm } from 'node:fs/promises';
-import { createWorkflowCheckpointCommit } from '#git/commits/createWorkflowCheckpointCommit.ts';
-import { getRepositoryStatus } from '#git/repository/getRepositoryStatus.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
-import { pathExists } from '#utils/path-exists.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import { WORKFLOW_EVENTS, WORKFLOW_PHASES } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
@@ -15,10 +11,7 @@ import { transitionWorkflow } from '#workflow/transitions.ts';
 
 export type VerifierRun = {
   specId: string;
-  repositoryRoot: string;
-  candidateCommit: string;
-  checkpointCommit: string;
-  revision: number;
+  projectRoot: string;
 };
 
 type PrepareVerifierRunInput = {
@@ -30,9 +23,8 @@ export const prepareVerifierRun = async ({
   paths,
   specId,
 }: PrepareVerifierRunInput): Promise<VerifierRun> => {
-  const repositoryRoot = paths.getRepositoryRoot();
+  const projectRoot = paths.getProjectRoot();
   const workflowPath = paths.getWorkflowPath(specId);
-  const handoffPath = paths.getVerifierHandoffPath(specId);
   const currentState = await readWorkflowState(workflowPath);
 
   if (currentState.specId !== specId) {
@@ -47,47 +39,18 @@ export const prepareVerifierRun = async ({
     );
   }
 
-  const status = await getRepositoryStatus(repositoryRoot);
-
-  if (!status.clean) {
-    throw new Error(
-      'Verifier run requires a committed ready-for-verifier candidate.',
-    );
-  }
-
   const nextState = transitionWorkflow({
     state: currentState,
     event: WORKFLOW_EVENTS.RUN_VERIFIER,
   });
 
-  const handoffExists = await pathExists(handoffPath);
-
-  if (handoffExists) {
-    await rm(handoffPath);
-  }
-
   await writeWorkflowState({
     path: workflowPath,
     state: nextState,
-    currentRevision: currentState.revision,
-  });
-
-  const expectedPaths = [workflowPath];
-
-  if (handoffExists) {
-    expectedPaths.push(handoffPath);
-  }
-
-  const checkpointCommit = await createWorkflowCheckpointCommit({
-    repositoryRoot,
-    expectedPaths,
   });
 
   return {
     specId,
-    repositoryRoot,
-    candidateCommit: checkpointCommit,
-    checkpointCommit,
-    revision: nextState.revision,
+    projectRoot,
   };
 };

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

@@ -1,54 +0,0 @@
-/**
- * Objective: Record an owner rejection on one verifier finding.
- * Used: When Maestro handles verifier handoff artifacts.
- */
-
-import { assertVerifierHandoff } from '#artifacts/verifier-handoff/assertVerifierHandoff.ts';
-import { readVerifierHandoff } from '#artifacts/verifier-handoff/readVerifierHandoff.ts';
-import type { VerifierHandoff } from '#artifacts/verifier-handoff/schema.ts';
-import { writeJsonAtomically } from '#utils/write-json-atomically.ts';
-
-type RejectVerifierFindingInput = {
-  path: string;
-  specId: string;
-  revision: number;
-  findingId: string;
-  reason: string;
-};
-
-export const rejectVerifierFinding = async ({
-  path,
-  specId,
-  revision,
-  findingId,
-  reason,
-}: RejectVerifierFindingInput): Promise<VerifierHandoff> => {
-  const handoff = await readVerifierHandoff({ path, specId, revision });
-  const finding = handoff.findings.find(({ id }) => id === findingId);
-
-  if (finding === undefined) {
-    throw new Error(`Verifier finding "${findingId}" does not exist.`);
-  }
-
-  if (finding.rejection !== null) {
-    throw new Error(`Verifier finding "${findingId}" is already rejected.`);
-  }
-
-  if (reason.length === 0) {
-    throw new Error('Verifier finding rejection reason must be non-empty.');
-  }
-
-  const rejectedHandoff = {
-    ...handoff,
-    findings: handoff.findings.map((currentFinding) =>
-      currentFinding.id === findingId
-        ? { ...currentFinding, rejection: { reason } }
-        : currentFinding,
-    ),
-  };
-
-  assertVerifierHandoff({ handoff: rejectedHandoff, specId, revision });
-  await writeJsonAtomically({ path, data: rejectedHandoff });
-
-  return rejectedHandoff;
-};