@emiliosp/pi-maestro 0.3.0 → 0.4.0

package/README.md

@@ -77,7 +77,7 @@ Do not change product code yourself while the workflow runs. Maestro can run tem
 
 The workflow is complete when it reaches `candidate-ready`. No final tool call is needed. Changes after completion are outside the Maestro review.
 
-If an escalation or finding requires a contract change, edit and approve `spec.md`, then call `maestro_mark_spec_ready`. The workflow returns to `ready-for-builder` on the same branch. A technical builder failure stops the workflow and requires owner follow-up.
+If an escalation or finding requires a contract change, edit and approve `spec.md`, then call `maestro_mark_spec_ready`. The workflow returns to `ready-for-builder` on the same branch. Commit the revised `spec.md`, its prototypes, and `workflow.json` before asking Maestro to run the builder again. The checkout must be clean. A technical builder failure stops the workflow and requires owner follow-up.
 
 Builder and verifier runs stay in the foreground. Pi waits for each run before you continue the conversation. Maestro shows the current phase in Pi's status. Use pi-subagents FleetView or `/subagents-fleet` to inspect live activity and the transcript.
 

package/agents/verifier.md

@@ -106,8 +106,7 @@ All files outside the tool-owned `workflow.json` and `handoffs/verifier.json` mu
 This includes the spec, prototypes, builder handoff, and escalation files. Findings do not relax this requirement.
 
 Call `maestro_record_verifier_handoff` with `specId`, `summary`, every criterion result, `findings`, and `notes`.
-The tool checks product restoration, writes the handoff, changes the phase, and commits only its two protocol files.
-If it returns `PRODUCT_FILES_MODIFIED`, inspect the remaining differences, restore your changes, and retry. The tool does not restore files.
+The tool writes the handoff, changes the phase, and commits only its two protocol files.
 If validation rejects the payload without writing it, correct the payload without changing the facts.
 If the tool already wrote an artifact or changed phase before an error, do not resubmit or commit manually.
 Do not delete artifacts, change workflow state, or bypass the tool to force completion.

package/docs/workflow.md

@@ -64,7 +64,7 @@ It reads the active spec and available artifacts. Historical artifacts provide c
 
 Before the verifier starts, Maestro commits a `verifier-running` checkpoint. That checkpoint is the candidate commit.
 
-The verifier never changes product code, it independently regenerates every probe and breakage from the candidate.
+The verifier does not repair product code. It independently regenerates every probe and breakage from the candidate and restores all temporary changes before its handoff. Maestro relies on verifier instructions for restoration, not a comparison with the candidate commit.
 
 ## Main flow
 
@@ -146,7 +146,7 @@ For the initial spec:
 
 During `drafting-spec`, Maestro can use any available tool to edit the active `spec.md` with the owner. Maestro can also create and update visual prototypes in that spec's `prototypes/` directory with any available tool. During `escalation-decision` or `findings-decision`, the same permission applies to owner-directed contract revisions of the spec and its prototypes. This permission does not apply to other workflow artifacts or product files. Maestro cannot edit the spec or its prototypes in other phases.
 
-The committed `spec.md` represents the approved contract for the builder and verifier. The spec and its prototypes are immutable during a builder or verifier pass.
+The committed `spec.md` represents the approved contract for the builder and verifier. Agents must not change the spec or its prototypes during a builder or verifier pass.
 
 During spec preparation, Maestro can run tests and checks to understand the repository. This also applies when you request a spec revision in `escalation-decision` or `findings-decision`, but not in other phases.
 
@@ -217,7 +217,7 @@ A spec revision is allowed only from these blocked phases:
 - `escalation-decision`
 - `findings-decision`
 
-The owner edits and approves the spec, then Maestro changes the phase to `ready-for-builder`.
+The owner edits and approves the spec, then Maestro calls `maestro_mark_spec_ready` to change the phase to `ready-for-builder`. The owner must commit the revised `spec.md`, its prototypes, and `workflow.json` before Maestro starts the builder again. The checkout must be clean.
 
 The previous escalation or finding becomes inactive. Its artifact remains in the branch as historical context. Builder and verifier decide whether historical artifacts apply to the current spec.
 

package/extensions/maestro-subagent.ts

@@ -3,75 +3,10 @@
  * Used: When Pi starts a Maestro subagent session.
  */
 
-import type {
-  ExtensionAPI,
-  ToolCallEvent,
-  ToolCallEventResult,
-} from '@earendil-works/pi-coding-agent';
-import { isToolCallEventType } from '@earendil-works/pi-coding-agent';
-import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { registerOpenEscalationTool } from '#tools/child/open-escalation.ts';
 import { registerRecordBuilderHandoffTool } from '#tools/child/record-builder-handoff.ts';
 import { registerRecordVerifierHandoffTool } from '#tools/child/record-verifier-handoff.ts';
-import { isProtectedSpecPath } from '#tools/child/utils/isProtectedSpecPath.ts';
-import { resolveWorkflowContext } from '#tools/child/utils/resolveWorkflowContext.ts';
-
-const getWriteOrEditPath = (event: ToolCallEvent): string | undefined => {
-  if (isToolCallEventType('write', event)) {
-    return event.input.path;
-  }
-
-  if (isToolCallEventType('edit', event)) {
-    return event.input.path;
-  }
-
-  return undefined;
-};
-
-type ProtectSpecPathInput = {
-  cwd: string;
-  event: ToolCallEvent;
-};
-
-const protectSpecPath = async ({
-  cwd,
-  event,
-}: ProtectSpecPathInput): Promise<ToolCallEventResult | undefined> => {
-  const targetPath = getWriteOrEditPath(event);
-
-  if (targetPath === undefined) {
-    return undefined;
-  }
-
-  const specId = maestroSessionState.getActiveSpecId();
-
-  if (specId === null) {
-    return undefined;
-  }
-
-  const { paths, repositoryRoot } = await resolveWorkflowContext({
-    cwd,
-    specId,
-  });
-
-  const specPath = paths.getSpecFilePath(specId);
-
-  if (
-    await isProtectedSpecPath({
-      repositoryRoot,
-      specPath,
-      targetPath,
-    })
-  ) {
-    return {
-      block: true,
-      reason:
-        'The owner-approved spec.md cannot be changed directly during a subagent session.',
-    };
-  }
-
-  return undefined;
-};
 
 export default (pi: ExtensionAPI): void => {
   // pi-subagents selects active tools from each agent's tools allowlist after registration.
@@ -79,10 +14,4 @@ export default (pi: ExtensionAPI): void => {
   registerOpenEscalationTool(pi);
   registerRecordBuilderHandoffTool(pi);
   registerRecordVerifierHandoffTool(pi);
-
-  // Pi fires this before a tool runs. A handler can block the call.
-  // Block direct child writes and edits to the owner-approved spec.md.
-  pi.on('tool_call', (event, context) =>
-    protectSpecPath({ cwd: context.cwd, event }),
-  );
 };

package/package.json

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

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -26,7 +26,7 @@ Wait for each tool result before taking the next workflow action. Do not launch
 ### Prepare and approve the spec
 
 1. Call maestro_create_spec with the change title. Use the generated spec.md structure from the package's templates/spec.md.
-2. Read the repository and applicable AGENTS.md files. Use existing facts before asking the owner for missing information.
+2. Read the repository and applicable AGENTS.md files. Investigate the affected behavior before asking the owner for missing information.
 3. Ask one focused question at a time. Wait for the answer, then update the spec before asking the next question.
 4. Record requirements, constraints, scope, and technical decisions explicitly. Do not invent requirements or silently resolve owner decisions.
 5. Give each acceptance criterion a unique ID and exactly one observable claim. Specify its probe, expected result, and safe temporary breakage.
@@ -35,6 +35,13 @@ Wait for each tool result before taking the next workflow action. Do not launch
 8. Request explicit approval. Only after approval, call maestro_mark_spec_ready with the active specId.
 9. Ask the owner to commit spec.md, its prototypes, and workflow.json. Do not start the builder until the checkout is clean.
 
+During spec preparation and revisions, investigate each technical decision before presenting options or recommending an answer. Do not wait for the owner to request code analysis.
+Trace the relevant code and data flow across affected components, including transformations that limit the available data.
+Use repository evidence to explain each option's feasibility, required changes, scope, and effects on existing behavior.
+Cite the relevant files. Distinguish confirmed facts from assumptions and state what you could not verify, including deployed state.
+Do not ask the owner questions that repository inspection can answer. Keep requirement choices and technical decisions with the owner.
+Record the supporting evidence and unresolved limits with the decision in spec.md. Follow the check and experiment permissions below.
+
 ### 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.

package/src/maestro/session/MaestroSessionState.ts

@@ -1,15 +1,11 @@
 /**
- * Objective: Manage the shared in-memory activation state for one Maestro session.
- * Used: By the main and subagent extensions in the foreground Pi runtime.
+ * Objective: Manage activation and spec selection for one Maestro owner session.
+ * Used: By the main extension and owner tools, never by child sessions.
  */
 
-import { getFileSha256 } from '#utils/getFileSha256.ts';
-
 class MaestroSessionState {
   private active = false;
   private activeSpecId: string | null = null;
-  private specSha256: string | null = null;
-  private verifierCheckpointCommit: string | null = null;
 
   public isActive = (): boolean => this.active;
 
@@ -25,35 +21,12 @@ class MaestroSessionState {
     this.activeSpecId = specId;
   };
 
-  public getSpecSha256 = (): string | null => this.specSha256;
-
-  public setSpecSha256 = async (specPath: string): Promise<void> => {
-    if (this.activeSpecId === null) {
-      throw new Error('Cannot set spec SHA-256 without an active spec.');
-    }
-
-    this.specSha256 = await getFileSha256(specPath);
-  };
-
-  public getVerifierCheckpointCommit = (): string | null =>
-    this.verifierCheckpointCommit;
-
-  public setVerifierCheckpointCommit = (commit: string): void => {
-    this.verifierCheckpointCommit = commit;
-  };
-
-  public clearVerifierCheckpointCommit = (): void => {
-    this.verifierCheckpointCommit = null;
-  };
-
   public activate = (): void => {
     this.active = true;
   };
 
   public clearActiveSpecId = (): void => {
     this.activeSpecId = null;
-    this.specSha256 = null;
-    this.clearVerifierCheckpointCommit();
   };
 
   public deactivate = (): void => {

package/src/maestro/status/refreshMaestroStatus.ts

@@ -1,6 +1,6 @@
 /**
  * Objective: Refresh Pi status from the live Maestro session and its current workflow.
- * Used: After activation or a main tool result, and before an owner turn.
+ * Used: After activation, before child delegation, after main tool results, and before owner turns.
  */
 
 import type { ExtensionContext } from '@earendil-works/pi-coding-agent';

package/src/tools/child/record-verifier-handoff.ts

@@ -13,14 +13,9 @@ import {
 import { createWorkflowCheckpointCommit } from '#git/commits/createWorkflowCheckpointCommit.ts';
 import { getRepositoryStatus } from '#git/repository/getRepositoryStatus.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
 import { resolveWorkflowContext } from '#tools/child/utils/resolveWorkflowContext.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import {
-  type CompletedVerifierPass,
-  completeVerifierPass,
-  type VerifierPassRejection,
-} from '#workflow/verifier/completeVerifierPass.ts';
+import { completeVerifierPass } from '#workflow/verifier/completeVerifierPass.ts';
 
 export const VERIFIER_HANDOFF_TOOL = {
   NAME: 'maestro_record_verifier_handoff',
@@ -48,20 +43,6 @@ const VerifierHandoffToolParameters = Type.Object(
   { additionalProperties: false },
 );
 
-type VerifierPassResult = CompletedVerifierPass | VerifierPassRejection;
-
-const isVerifierPassRejection = (
-  result: VerifierPassResult,
-): result is VerifierPassRejection => 'error' in result;
-
-function assertVerifierCheckpointCommit(
-  commit: string | null,
-): asserts commit is string {
-  if (commit === null) {
-    throw new Error('Verifier handoff requires a live verifier checkpoint.');
-  }
-}
-
 export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
   pi.registerTool({
     name: VERIFIER_HANDOFF_TOOL.NAME,
@@ -80,10 +61,6 @@ export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
         paths.getWorkflowPath(specId),
       );
 
-      const candidateCommit = maestroSessionState.getVerifierCheckpointCommit();
-
-      assertVerifierCheckpointCommit(candidateCommit);
-
       const handoff = {
         version: VERIFIER_HANDOFF_VERSION,
         specId: currentState.specId,
@@ -94,21 +71,9 @@ export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
       const completed = await completeVerifierPass({
         paths,
         specId,
-        candidateCommit,
         handoff,
       });
 
-      if (isVerifierPassRejection(completed)) {
-        return {
-          content: [{ type: 'text', text: completed.message }],
-          details: {
-            error: completed.error,
-            message: completed.message,
-            specId,
-          },
-        };
-      }
-
       const workflowCheckpointCommit = await createWorkflowCheckpointCommit({
         repositoryRoot,
         expectedPaths: [
@@ -131,7 +96,6 @@ export const registerRecordVerifierHandoffTool = (pi: ExtensionAPI): void => {
           },
         ],
         details: {
-          candidateCommit,
           phase: completed.state.phase,
           workflowCheckpointCommit,
           revision: completed.state.revision,

package/src/tools/main/run-builder.ts

@@ -18,6 +18,7 @@ import { AGENTS } from '#config/schema.ts';
 import { getRepositoryStatus } from '#git/repository/getRepositoryStatus.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
+import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
 import {
   assertDelegationResponse,
   waitForDelegationResponse,
@@ -232,6 +233,7 @@ export const registerRunBuilderTool = (pi: ExtensionAPI): void => {
       const { paths, config } = await resolveToolRunContext(context.cwd);
 
       const run = await prepareBuilderRun({ paths, specId });
+      await refreshMaestroStatus(context);
 
       const request: SubagentDelegationRequest = {
         requestId: randomUUID(),

package/src/tools/main/run-verifier.ts

@@ -13,7 +13,7 @@ import { AGENTS } from '#config/schema.ts';
 import { getRepositoryStatus } from '#git/repository/getRepositoryStatus.ts';
 import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
-import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
+import { refreshMaestroStatus } from '#maestro/status/refreshMaestroStatus.ts';
 import {
   assertDelegationResponse,
   waitForDelegationResponse,
@@ -22,11 +22,6 @@ import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
 import { WORKFLOW_ROLES } from '#workflow/roles.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import { WORKFLOW_PHASES, type WorkflowState } from '#workflow/state/schema.ts';
-import {
-  VERIFIER_PASS_ERRORS,
-  VERIFIER_PASS_MESSAGES,
-} from '#workflow/verifier/completeVerifierPass.ts';
-import { hasProductChanges } from '#workflow/verifier/hasProductChanges.ts';
 import {
   prepareVerifierRun,
   type VerifierRun,
@@ -68,28 +63,13 @@ type FindingsResult = {
   handoff: VerifierHandoff;
 };
 
-type ProductChangesResult = {
-  outcome: typeof VERIFIER_PASS_ERRORS.PRODUCT_FILES_MODIFIED;
-  error: typeof VERIFIER_PASS_ERRORS.PRODUCT_FILES_MODIFIED;
-  message: typeof VERIFIER_PASS_MESSAGES.PRODUCT_FILES_MODIFIED;
-  specId: string;
-  revision: number;
-  phase: typeof WORKFLOW_PHASES.VERIFIER_RUNNING;
-  candidateCommit: string;
-  checkpointCommit: string;
-};
-
-type VerifierRunResult =
-  | CandidateReadyResult
-  | FindingsResult
-  | ProductChangesResult;
+type VerifierRunResult = CandidateReadyResult | FindingsResult;
 
 type ReadTerminalVerifierResultInput = {
   paths: MaestroPaths;
   specId: string;
   run: VerifierRun;
   state: WorkflowState;
-  productChanges: boolean;
 };
 
 const readTerminalVerifierResult = async ({
@@ -97,7 +77,6 @@ const readTerminalVerifierResult = async ({
   specId,
   run,
   state,
-  productChanges,
 }: ReadTerminalVerifierResultInput): Promise<
   CandidateReadyResult | FindingsResult
 > => {
@@ -110,12 +89,6 @@ const readTerminalVerifierResult = async ({
     );
   }
 
-  if (productChanges) {
-    throw new Error(
-      'Product files differ from the candidate after the verifier handoff.',
-    );
-  }
-
   const repositoryStatus = await getRepositoryStatus(run.repositoryRoot);
 
   if (!repositoryStatus.clean) {
@@ -176,27 +149,7 @@ const readVerifierResult = async ({
       );
     }
 
-    const productChanges = await hasProductChanges({
-      repositoryRoot: run.repositoryRoot,
-      candidateCommit: run.candidateCommit,
-      workflowPath: paths.getWorkflowPath(specId),
-      handoffPath: paths.getVerifierHandoffPath(specId),
-    });
-
     if (state.phase === WORKFLOW_PHASES.VERIFIER_RUNNING) {
-      if (productChanges) {
-        return {
-          outcome: VERIFIER_PASS_ERRORS.PRODUCT_FILES_MODIFIED,
-          error: VERIFIER_PASS_ERRORS.PRODUCT_FILES_MODIFIED,
-          message: VERIFIER_PASS_MESSAGES.PRODUCT_FILES_MODIFIED,
-          specId,
-          revision: state.revision,
-          phase: state.phase,
-          candidateCommit: run.candidateCommit,
-          checkpointCommit: run.checkpointCommit,
-        };
-      }
-
       throw new Error(
         'The verifier returned without recording a valid terminal handoff.',
       );
@@ -207,7 +160,6 @@ const readVerifierResult = async ({
       specId,
       run,
       state,
-      productChanges,
     });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
@@ -221,11 +173,7 @@ const formatVerifierResult = (result: VerifierRunResult): string => {
     return `Verifier completed spec ${result.specId}. The workflow is candidate-ready.`;
   }
 
-  if (result.outcome === WORKFLOW_PHASES.FINDINGS_DECISION) {
-    return `Verifier found ${result.handoff.findings.length} finding(s) for spec ${result.specId}. The workflow is waiting for owner decisions.`;
-  }
-
-  return `${result.message} The workflow remains verifier-running.`;
+  return `Verifier found ${result.handoff.findings.length} finding(s) for spec ${result.specId}. The workflow is waiting for owner decisions.`;
 };
 
 export const registerRunVerifierTool = (pi: ExtensionAPI): void => {
@@ -238,38 +186,35 @@ export const registerRunVerifierTool = (pi: ExtensionAPI): void => {
       const { paths, config } = await resolveToolRunContext(context.cwd);
 
       const run = await prepareVerifierRun({ paths, specId });
-
-      try {
-        const request: SubagentDelegationRequest = {
-          requestId: randomUUID(),
-          ownerRunId: toolCallId,
-          nodeId: WORKFLOW_ROLES.VERIFIER,
-          // pi-subagents loads this name from agents/verifier.md through package.json.
-          agent: AGENTS.VERIFIER,
-          task: `Verify specId "${specId}" at candidate checkpoint "${run.candidateCommit}" in the current checkout "${run.repositoryRoot}". Read all applicable AGENTS.md files before working.`,
-          context: 'fresh',
-          cwd: run.repositoryRoot,
-          model: config.verifier.model,
-          thinking: config.verifier.thinking,
-          timeoutMs: config.verifier.timeoutMinutes * MILLISECONDS_PER_MINUTE,
-          result: { kind: 'text' },
-        };
-
-        const response = await waitForDelegationResponse({
-          piEventsBus: pi.events,
-          request,
-        });
-
-        assertDelegationResponse(response);
-        const result = await readVerifierResult({ paths, specId, run });
-
-        return {
-          content: [{ type: 'text', text: formatVerifierResult(result) }],
-          details: result,
-        };
-      } finally {
-        maestroSessionState.clearVerifierCheckpointCommit();
-      }
+      await refreshMaestroStatus(context);
+
+      const request: SubagentDelegationRequest = {
+        requestId: randomUUID(),
+        ownerRunId: toolCallId,
+        nodeId: WORKFLOW_ROLES.VERIFIER,
+        // pi-subagents loads this name from agents/verifier.md through package.json.
+        agent: AGENTS.VERIFIER,
+        task: `Verify specId "${specId}" at candidate checkpoint "${run.candidateCommit}" in the current checkout "${run.repositoryRoot}". Read all applicable AGENTS.md files before working.`,
+        context: 'fresh',
+        cwd: run.repositoryRoot,
+        model: config.verifier.model,
+        thinking: config.verifier.thinking,
+        timeoutMs: config.verifier.timeoutMinutes * MILLISECONDS_PER_MINUTE,
+        result: { kind: 'text' },
+      };
+
+      const response = await waitForDelegationResponse({
+        piEventsBus: pi.events,
+        request,
+      });
+
+      assertDelegationResponse(response);
+      const result = await readVerifierResult({ paths, specId, run });
+
+      return {
+        content: [{ type: 'text', text: formatVerifierResult(result) }],
+        details: result,
+      };
     },
   });
 };

package/src/workflow/builder/completeBuilderPass.ts

@@ -15,7 +15,6 @@ import {
 import { writeBuilderHandoff } from '#artifacts/builder-handoff/writeBuilderHandoff.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { pathExists } from '#utils/path-exists.ts';
-import { assertBuilderProtocolUnchanged } from '#workflow/builder/assertBuilderProtocolUnchanged.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import {
   WORKFLOW_EVENTS,
@@ -75,8 +74,6 @@ export const completeBuilderPass = async ({
   specId,
   handoff: draftHandoff,
 }: CompleteBuilderPassInput): Promise<CompletedBuilderPass> => {
-  await assertBuilderProtocolUnchanged({ paths, specId });
-
   const workflowPath = paths.getWorkflowPath(specId);
   const handoffPath = paths.getBuilderHandoffPath(specId);
   const currentState = await readWorkflowState(workflowPath);

package/src/workflow/builder/prepareBuilderRun.ts

@@ -103,8 +103,6 @@ export const prepareBuilderRun = async ({
     expectedPaths,
   });
 
-  await maestroSessionState.setSpecSha256(paths.getSpecFilePath(specId));
-
   return {
     specId,
     revision: nextState.revision,

package/src/workflow/escalation/openBuilderEscalation.ts

@@ -11,7 +11,6 @@ import type {
 } from '#artifacts/escalation/schema.ts';
 import type { MaestroPaths } from '#MaestroPaths.ts';
 import { pathExists } from '#utils/path-exists.ts';
-import { assertBuilderProtocolUnchanged } from '#workflow/builder/assertBuilderProtocolUnchanged.ts';
 import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
 import {
   WORKFLOW_EVENTS,
@@ -40,8 +39,6 @@ export const openBuilderEscalation = async ({
   specId,
   escalation,
 }: OpenBuilderEscalationInput): Promise<OpenedBuilderEscalation> => {
-  await assertBuilderProtocolUnchanged({ paths, specId });
-
   const workflowPath = paths.getWorkflowPath(specId);
   const handoffPath = paths.getBuilderHandoffPath(specId);
   const escalationsPath = paths.getEscalationsPath(specId);

package/src/workflow/findings/resolveFindings.ts

@@ -3,12 +3,14 @@
  * 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';
@@ -22,7 +24,6 @@ import {
 } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
-import { hasProductChanges } from '#workflow/verifier/hasProductChanges.ts';
 
 export const FINDING_DECISIONS = {
   REJECT: 'reject',
@@ -182,6 +183,67 @@ const buildFindingWorkflow = ({
   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;
@@ -199,18 +261,11 @@ const commitFindingWorkflow = async ({
   const workflowPath = paths.getWorkflowPath(specId);
   const handoffPath = paths.getVerifierHandoffPath(specId);
 
-  if (
-    await hasProductChanges({
-      repositoryRoot,
-      candidateCommit: await getHeadCommit(repositoryRoot),
-      workflowPath,
-      handoffPath,
-    })
-  ) {
-    throw new Error(
-      'Finding resolution requires no changes outside its protocol files.',
-    );
-  }
+  await assertNoChangesOutsideFindingArtifacts({
+    repositoryRoot,
+    workflowPath,
+    handoffPath,
+  });
 
   await writeJsonAtomically({ path: handoffPath, data: workflow.handoff });
   await writeWorkflowState({

package/src/workflow/verifier/completeVerifierPass.ts

@@ -1,5 +1,5 @@
 /**
- * Objective: Complete a verifier pass without allowing candidate changes.
+ * Objective: Complete a verifier pass with a validated handoff.
  * Used: When the verifier submits its terminal handoff.
  */
 
@@ -18,16 +18,6 @@ import {
 } from '#workflow/state/schema.ts';
 import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
 import { transitionWorkflow } from '#workflow/transitions.ts';
-import { hasProductChanges } from '#workflow/verifier/hasProductChanges.ts';
-
-export const VERIFIER_PASS_ERRORS = {
-  PRODUCT_FILES_MODIFIED: 'PRODUCT_FILES_MODIFIED',
-} as const;
-
-export const VERIFIER_PASS_MESSAGES = {
-  PRODUCT_FILES_MODIFIED:
-    'Product files differ from the candidate commit. Restore the candidate before submitting the verifier handoff.',
-} as const;
 
 export type CompletedVerifierPass = {
   handoff: VerifierHandoff;
@@ -35,26 +25,17 @@ export type CompletedVerifierPass = {
   repositoryRoot: string;
 };
 
-export type VerifierPassRejection = {
-  error: (typeof VERIFIER_PASS_ERRORS)[keyof typeof VERIFIER_PASS_ERRORS];
-  message: string;
-};
-
 type CompleteVerifierPassInput = {
   paths: MaestroPaths;
   specId: string;
-  candidateCommit: string;
   handoff: unknown;
 };
 
 export const completeVerifierPass = async ({
   paths,
   specId,
-  candidateCommit,
   handoff: draftHandoff,
-}: CompleteVerifierPassInput): Promise<
-  CompletedVerifierPass | VerifierPassRejection
-> => {
+}: CompleteVerifierPassInput): Promise<CompletedVerifierPass> => {
   const repositoryRoot = paths.getRepositoryRoot();
   const workflowPath = paths.getWorkflowPath(specId);
   const handoffPath = paths.getVerifierHandoffPath(specId);
@@ -76,20 +57,6 @@ export const completeVerifierPass = async ({
     throw new Error('Verifier terminal handoff already exists.');
   }
 
-  if (
-    await hasProductChanges({
-      repositoryRoot,
-      candidateCommit,
-      workflowPath,
-      handoffPath,
-    })
-  ) {
-    return {
-      error: VERIFIER_PASS_ERRORS.PRODUCT_FILES_MODIFIED,
-      message: VERIFIER_PASS_MESSAGES.PRODUCT_FILES_MODIFIED,
-    };
-  }
-
   const handoffInput = {
     handoff: draftHandoff,
     specId,

package/src/workflow/verifier/prepareVerifierRun.ts

@@ -7,7 +7,6 @@ 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 maestroSessionState from '#maestro/session/MaestroSessionState.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';
@@ -84,8 +83,6 @@ export const prepareVerifierRun = async ({
     expectedPaths,
   });
 
-  maestroSessionState.setVerifierCheckpointCommit(checkpointCommit);
-
   return {
     specId,
     repositoryRoot,

package/src/tools/child/utils/isProtectedSpecPath.ts

@@ -1,61 +0,0 @@
-/**
- * Objective: Identify paths that resolve to the protected workflow spec.
- * Used: Before child write and edit tools run.
- */
-
-import { lstat, realpath } from 'node:fs/promises';
-import { basename, dirname, resolve } from 'node:path';
-import { isErrnoException } from '#utils/is-errno-exception.ts';
-
-const resolveThroughExistingParent = async (path: string): Promise<string> => {
-  const unresolvedParts: string[] = [];
-  let currentPath = path;
-
-  while (true) {
-    try {
-      await lstat(currentPath);
-
-      const existingPath = await realpath(currentPath);
-
-      return resolve(existingPath, ...unresolvedParts);
-    } catch (error) {
-      if (!isErrnoException(error) || error.code !== 'ENOENT') {
-        throw error;
-      }
-
-      const parentPath = dirname(currentPath);
-
-      if (parentPath === currentPath) {
-        throw new Error(`Cannot resolve path "${path}".`);
-      }
-
-      unresolvedParts.unshift(basename(currentPath));
-      currentPath = parentPath;
-    }
-  }
-};
-
-type IsProtectedSpecPathInput = {
-  repositoryRoot: string;
-  specPath: string;
-  targetPath: string;
-};
-
-export const isProtectedSpecPath = async ({
-  repositoryRoot,
-  specPath,
-  targetPath,
-}: IsProtectedSpecPathInput): Promise<boolean> => {
-  const pathWithoutPrefix = targetPath.startsWith('@')
-    ? targetPath.slice(1)
-    : targetPath;
-
-  const resolvedTargetPath = resolve(repositoryRoot, pathWithoutPrefix);
-
-  const [resolvedSpecPath, resolvedTarget] = await Promise.all([
-    resolveThroughExistingParent(specPath),
-    resolveThroughExistingParent(resolvedTargetPath),
-  ]);
-
-  return resolvedTarget === resolvedSpecPath;
-};

package/src/utils/getFileSha256.ts

@@ -1,13 +0,0 @@
-/**
- * Objective: Calculate the SHA-256 digest of a file.
- * Used: When a workflow needs to compare a file with an in-memory baseline.
- */
-
-import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-
-export const getFileSha256 = async (path: string): Promise<string> => {
-  const contents = await readFile(path);
-
-  return createHash('sha256').update(contents).digest('hex');
-};

package/src/workflow/builder/assertBuilderProtocolUnchanged.ts

@@ -1,33 +0,0 @@
-/**
- * Objective: Reject changes to spec.md after a builder session starts.
- * Used: Before a builder tool writes a terminal workflow artifact.
- */
-
-import type { MaestroPaths } from '#MaestroPaths.ts';
-import maestroSessionState from '#maestro/session/MaestroSessionState.ts';
-import { getFileSha256 } from '#utils/getFileSha256.ts';
-
-type AssertBuilderProtocolUnchangedInput = {
-  paths: MaestroPaths;
-  specId: string;
-};
-
-export async function assertBuilderProtocolUnchanged({
-  paths,
-  specId,
-}: AssertBuilderProtocolUnchangedInput): Promise<void> {
-  const expectedSpecSha256 = maestroSessionState.getSpecSha256();
-
-  if (expectedSpecSha256 === null) {
-    throw new Error('Builder spec SHA-256 baseline is not initialized.');
-  }
-
-  const specPath = paths.getSpecFilePath(specId);
-  const actualSpecSha256 = await getFileSha256(specPath);
-
-  if (actualSpecSha256 !== expectedSpecSha256) {
-    throw new Error(
-      `Builder changed spec.md after the run starts: "${specPath}".`,
-    );
-  }
-}

package/src/workflow/verifier/hasProductChanges.ts

@@ -1,68 +0,0 @@
-/**
- * Objective: Check whether product files differ from a commit.
- * Used: Before verifier handoffs and owner finding resolutions.
- */
-
-import { relative } from 'node:path';
-import { runGitCommand } from '#git/command.ts';
-import { getRepositoryStatus } from '#git/repository/getRepositoryStatus.ts';
-
-type HasProductChangesInput = {
-  repositoryRoot: string;
-  candidateCommit: string;
-  workflowPath: string;
-  handoffPath: string;
-};
-
-export const hasProductChanges = async ({
-  repositoryRoot,
-  candidateCommit,
-  workflowPath,
-  handoffPath,
-}: HasProductChangesInput): Promise<boolean> => {
-  /*
-   * Compare both the checkout and index with the candidate. The second diff
-   * catches a product file that the verifier staged and then restored only on
-   * disk.
-   */
-  const [diff, stagedDiff, status] = await Promise.all([
-    runGitCommand({
-      arguments: [
-        'diff',
-        '--no-renames',
-        '--name-only',
-        '-z',
-        candidateCommit,
-        '--',
-      ],
-      cwd: repositoryRoot,
-    }),
-    runGitCommand({
-      arguments: [
-        'diff',
-        '--cached',
-        '--no-renames',
-        '--name-only',
-        '-z',
-        candidateCommit,
-        '--',
-      ],
-      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);
-
-  return (
-    changedTrackedPaths.some((path) => !allowedPaths.has(path)) ||
-    status.untracked.some((path) => !allowedPaths.has(path))
-  );
-};