@emiliosp/pi-maestro 0.6.2 → 0.7.0

package/src/artifacts/escalation/createEscalation.ts

@@ -1,52 +0,0 @@
-/**
- * Objective: Create an unresolved escalation.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { join } from 'node:path';
-import { assertEscalation } from '#artifacts/escalation/assertEscalation.ts';
-import { getNextEscalationId } from '#artifacts/escalation/getNextEscalationId.ts';
-import {
-  ESCALATION_VERSION,
-  type Escalation,
-  type NewEscalation,
-} from '#artifacts/escalation/schema.ts';
-import { writeJson } from '#utils/write-json.ts';
-
-type CreateEscalationInput = {
-  directory: string;
-  specId: string;
-  escalation: NewEscalation;
-};
-
-export const createEscalation = async ({
-  directory,
-  specId,
-  escalation,
-}: CreateEscalationInput): Promise<{
-  path: string;
-  escalation: Escalation;
-}> => {
-  const id = await getNextEscalationId({
-    directory,
-    specId,
-  });
-
-  const newEscalation = {
-    question: escalation.question,
-    context: escalation.context,
-    options: escalation.options,
-    recommendation: escalation.recommendation,
-    notes: escalation.notes,
-    version: ESCALATION_VERSION,
-    specId,
-    id,
-    resolution: null,
-  };
-
-  assertEscalation(newEscalation);
-  const path = join(directory, `${id}.json`);
-  await writeJson({ path, data: newEscalation });
-
-  return { path, escalation: newEscalation };
-};

package/src/artifacts/escalation/getNextEscalationId.ts

@@ -1,23 +0,0 @@
-/**
- * Objective: Allocate the next escalation ID from history.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { readEscalationHistory } from '#artifacts/escalation/readEscalationHistory.ts';
-
-type GetNextEscalationIdInput = {
-  directory: string;
-  specId: string;
-};
-
-export const getNextEscalationId = async ({
-  directory,
-  specId,
-}: GetNextEscalationIdInput): Promise<string> => {
-  const history = await readEscalationHistory({
-    directory,
-    specId,
-  });
-
-  return `E${history.length + 1}`;
-};

package/src/artifacts/escalation/readEscalation.ts

@@ -1,40 +0,0 @@
-/**
- * Objective: Read an escalation for its workflow.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { assertEscalation } from '#artifacts/escalation/assertEscalation.ts';
-import type { Escalation } from '#artifacts/escalation/schema.ts';
-import { readJsonFile } from '#utils/read-json.ts';
-
-type AssertWorkflowEscalationInput = {
-  escalation: Escalation;
-  specId: string;
-};
-
-function assertWorkflowEscalation({
-  escalation,
-  specId,
-}: AssertWorkflowEscalationInput): void {
-  if (escalation.specId !== specId) {
-    throw new Error(
-      `Escalation spec ID mismatch: expected "${specId}", found "${escalation.specId}".`,
-    );
-  }
-}
-
-type ReadEscalationInput = {
-  path: string;
-  specId: string;
-};
-
-export const readEscalation = async ({
-  path,
-  specId,
-}: ReadEscalationInput): Promise<Escalation> => {
-  const escalation = await readJsonFile({ path, description: 'Escalation' });
-  assertEscalation(escalation);
-  assertWorkflowEscalation({ escalation, specId });
-
-  return escalation;
-};

package/src/artifacts/escalation/readEscalationHistory.ts

@@ -1,44 +0,0 @@
-/**
- * Objective: Read and order validated escalation history.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { readEscalation } from '#artifacts/escalation/readEscalation.ts';
-import type { Escalation } from '#artifacts/escalation/schema.ts';
-
-const ESCALATION_FILE_PATTERN = /^E([1-9]\d*)\.json$/;
-
-type ReadEscalationHistoryInput = {
-  directory: string;
-  specId: string;
-};
-
-export const readEscalationHistory = async ({
-  directory,
-  specId,
-}: ReadEscalationHistoryInput): Promise<Escalation[]> => {
-  const files = await readdir(directory);
-
-  if (!files.every((file) => ESCALATION_FILE_PATTERN.test(file))) {
-    throw new Error('Escalation history contains an invalid entry.');
-  }
-
-  const orderedFiles = files.sort(
-    (left, right) => Number(left.slice(1, -5)) - Number(right.slice(1, -5)),
-  );
-
-  const escalations: Escalation[] = [];
-
-  for (const file of orderedFiles.values()) {
-    const escalation = await readEscalation({
-      path: join(directory, file),
-      specId,
-    });
-
-    escalations.push(escalation);
-  }
-
-  return escalations;
-};

package/src/artifacts/escalation/resolveEscalation.ts

@@ -1,43 +0,0 @@
-/**
- * Objective: Record an owner escalation resolution.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { assertEscalation } from '#artifacts/escalation/assertEscalation.ts';
-import { readEscalation } from '#artifacts/escalation/readEscalation.ts';
-import type {
-  Escalation,
-  EscalationResolution,
-} from '#artifacts/escalation/schema.ts';
-import { writeJson } from '#utils/write-json.ts';
-
-type ResolveEscalationInput = {
-  path: string;
-  specId: string;
-  resolution: EscalationResolution;
-};
-
-export const resolveEscalation = async ({
-  path,
-  specId,
-  resolution,
-}: ResolveEscalationInput): Promise<Escalation> => {
-  const current = await readEscalation({
-    path,
-    specId,
-  });
-
-  if (current.resolution !== null) {
-    throw new Error(`Escalation "${current.id}" is already resolved.`);
-  }
-
-  const resolvedEscalation = {
-    ...current,
-    resolution,
-  };
-
-  assertEscalation(resolvedEscalation);
-  await writeJson({ path, data: resolvedEscalation });
-
-  return resolvedEscalation;
-};

package/src/artifacts/escalation/schema.ts

@@ -1,73 +0,0 @@
-/**
- * Objective: Define escalation options and resolution contracts.
- * Used: When Maestro handles escalation artifacts.
- */
-
-import { type Static, Type } from 'typebox';
-import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-
-export const ESCALATION_VERSION = '1.0.0';
-
-export const ESCALATION_ID_PATTERN = /^E([1-9]\d*)$/;
-
-export const EscalationOptionSchema = Type.Object(
-  {
-    id: Type.String({ minLength: 1 }),
-    description: Type.String({ minLength: 1 }),
-    consequences: Type.String({ minLength: 1 }),
-    nextStep: Type.String({ minLength: 1 }),
-  },
-  { additionalProperties: false },
-);
-
-export const EscalationRecommendationSchema = Type.Object(
-  {
-    optionId: Type.String({ minLength: 1 }),
-    reason: Type.String({ minLength: 1 }),
-  },
-  { additionalProperties: false },
-);
-
-export const EscalationResolutionSchema = Type.Object(
-  {
-    selectedOptionId: Type.Union([Type.String({ minLength: 1 }), Type.Null()]),
-    decision: Type.String({ minLength: 1 }),
-    reason: Type.String({ minLength: 1 }),
-  },
-  { additionalProperties: false },
-);
-
-const NewEscalationFields = {
-  question: Type.String({ minLength: 1 }),
-  context: Type.String({ minLength: 1 }),
-  options: Type.Array(EscalationOptionSchema, { minItems: 1 }),
-  notes: Type.Array(Type.String()),
-};
-
-export const NewEscalationSchema = Type.Object(
-  {
-    ...NewEscalationFields,
-    recommendation: Type.Union([EscalationRecommendationSchema, Type.Null()]),
-  },
-  { additionalProperties: false },
-);
-
-export const EscalationSchema = Type.Object(
-  {
-    version: Type.Literal(ESCALATION_VERSION),
-    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-    id: Type.String({ pattern: ESCALATION_ID_PATTERN.source }),
-    ...NewEscalationFields,
-    recommendation: Type.Union([EscalationRecommendationSchema, Type.Null()]),
-    resolution: Type.Union([EscalationResolutionSchema, Type.Null()]),
-  },
-  { additionalProperties: false },
-);
-
-export type EscalationOption = Static<typeof EscalationOptionSchema>;
-
-export type EscalationResolution = Static<typeof EscalationResolutionSchema>;
-
-export type Escalation = Static<typeof EscalationSchema>;
-
-export type NewEscalation = Static<typeof NewEscalationSchema>;

package/src/tools/child/open-escalation.ts

@@ -1,71 +0,0 @@
-/**
- * Objective: Register the builder escalation tool for the current project.
- * Used: When the builder finds a significant discovery that requires an owner decision.
- */
-
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { Type } from 'typebox';
-import {
-  EscalationOptionSchema,
-  EscalationRecommendationSchema,
-} from '#artifacts/escalation/schema.ts';
-import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-import { resolveWorkflowContext } from '#tools/child/utils/resolveWorkflowContext.ts';
-import { openBuilderEscalation } from '#workflow/escalation/openBuilderEscalation.ts';
-
-export const BUILDER_ESCALATION_TOOL = {
-  NAME: 'maestro_open_escalation',
-  LABEL: 'Open Builder Escalation',
-  DESCRIPTION:
-    'Ask the owner to choose between options for a significant discovery or unresolved decision. An escalation is not limited to a technical failure or blocker. After success, stop. The tool saves the escalation and workflow phase. Do not wait for the owner.',
-} as const;
-
-const BuilderEscalationToolParameters = Type.Object(
-  {
-    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-    question: Type.String({ minLength: 1 }),
-    context: Type.String({ minLength: 1 }),
-    options: Type.Array(EscalationOptionSchema, { minItems: 1 }),
-    recommendation: Type.Union([EscalationRecommendationSchema, Type.Null()]),
-    notes: Type.Array(Type.String()),
-  },
-  { additionalProperties: false },
-);
-
-export const registerOpenEscalationTool = (pi: ExtensionAPI): void => {
-  pi.registerTool({
-    name: BUILDER_ESCALATION_TOOL.NAME,
-    label: BUILDER_ESCALATION_TOOL.LABEL,
-    description: BUILDER_ESCALATION_TOOL.DESCRIPTION,
-    parameters: BuilderEscalationToolParameters,
-    async execute(_toolCallId, params, _signal, _onUpdate, context) {
-      const { specId, ...escalation } = params;
-
-      const { paths } = await resolveWorkflowContext({
-        cwd: context.cwd,
-        specId,
-      });
-
-      const opened = await openBuilderEscalation({
-        paths,
-        specId,
-        escalation,
-      });
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Escalation ${opened.escalation.id} recorded. The escalation and workflow phase are saved. Stop now. Do not wait for the owner.`,
-          },
-        ],
-        details: {
-          specId: opened.escalation.specId,
-          escalationId: opened.escalation.id,
-          escalationPath: opened.escalationPath,
-          phase: opened.state.phase,
-        },
-      };
-    },
-  });
-};

package/src/tools/main/resolve-escalation.ts

@@ -1,65 +0,0 @@
-/**
- * Objective: Register owner resolution of the current builder escalation.
- * Used: When the owner keeps the approved contract and chooses an escalation resolution.
- */
-
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { Type } from 'typebox';
-import {
-  ESCALATION_ID_PATTERN,
-  EscalationResolutionSchema,
-} from '#artifacts/escalation/schema.ts';
-import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
-import { resolveToolRunContext } from '#tools/utils/resolveToolRunContext.ts';
-import { resolveBuilderEscalation } from '#workflow/escalation/resolveBuilderEscalation.ts';
-
-export const RESOLVE_ESCALATION_TOOL = {
-  NAME: 'maestro_resolve_escalation',
-  LABEL: 'Resolve Escalation',
-  DESCRIPTION:
-    'Record the explicit owner decision for the current builder escalation when the approved contract remains valid. Save the resolution and workflow transition, then return ready-for-builder without running the builder. If the contract must change, edit spec.md and use maestro_mark_spec_ready instead.',
-} as const;
-
-const ResolveEscalationToolParameters = Type.Object(
-  {
-    specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
-    escalationId: Type.String({ pattern: ESCALATION_ID_PATTERN.source }),
-    ...EscalationResolutionSchema.properties,
-  },
-  { additionalProperties: false },
-);
-
-export const registerResolveEscalationTool = (pi: ExtensionAPI): void => {
-  pi.registerTool({
-    name: RESOLVE_ESCALATION_TOOL.NAME,
-    label: RESOLVE_ESCALATION_TOOL.LABEL,
-    description: RESOLVE_ESCALATION_TOOL.DESCRIPTION,
-    parameters: ResolveEscalationToolParameters,
-    async execute(_toolCallId, params, _signal, _onUpdate, context) {
-      const { specId, escalationId, ...resolution } = params;
-      const { paths } = await resolveToolRunContext(context.cwd);
-
-      const resolved = await resolveBuilderEscalation({
-        paths,
-        specId,
-        escalationId,
-        resolution,
-      });
-
-      return {
-        content: [
-          {
-            type: 'text',
-            text: `Escalation ${resolved.escalation.id} resolved. Spec ${resolved.state.specId} is ready-for-builder. Run the builder separately.`,
-          },
-        ],
-        details: {
-          specId: resolved.state.specId,
-          escalationId: resolved.escalation.id,
-          phase: resolved.state.phase,
-          projectRoot: resolved.projectRoot,
-        },
-      };
-    },
-  });
-};

package/src/workflow/escalation/openBuilderEscalation.ts

@@ -1,82 +0,0 @@
-/**
- * Objective: Open a builder escalation and move the workflow to an owner decision.
- * Used: When a builder identifies a significant discovery that requires owner attention.
- */
-
-import { mkdir } from 'node:fs/promises';
-import { createEscalation } from '#artifacts/escalation/createEscalation.ts';
-import type {
-  Escalation,
-  NewEscalation,
-} from '#artifacts/escalation/schema.ts';
-import type { MaestroPaths } from '#MaestroPaths.ts';
-import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import {
-  WORKFLOW_EVENTS,
-  WORKFLOW_PHASES,
-  type WorkflowState,
-} from '#workflow/state/schema.ts';
-import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
-import { transitionWorkflow } from '#workflow/transitions.ts';
-
-export type OpenedBuilderEscalation = {
-  escalation: Escalation;
-  state: WorkflowState;
-  projectRoot: string;
-  workflowPath: string;
-  escalationPath: string;
-};
-
-type OpenBuilderEscalationInput = {
-  paths: MaestroPaths;
-  specId: string;
-  escalation: NewEscalation;
-};
-
-export const openBuilderEscalation = async ({
-  paths,
-  specId,
-  escalation,
-}: OpenBuilderEscalationInput): Promise<OpenedBuilderEscalation> => {
-  const workflowPath = paths.getWorkflowPath(specId);
-  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.BUILDER_RUNNING) {
-    throw new Error(
-      `Builder escalation requires builder-running state, found "${currentState.phase}".`,
-    );
-  }
-
-  const nextState = transitionWorkflow({
-    state: currentState,
-    event: WORKFLOW_EVENTS.OPEN_ESCALATION,
-  });
-
-  await mkdir(escalationsPath, { recursive: true });
-
-  const created = await createEscalation({
-    directory: escalationsPath,
-    specId: currentState.specId,
-    escalation,
-  });
-
-  await writeWorkflowState({
-    path: workflowPath,
-    state: nextState,
-  });
-
-  return {
-    escalation: created.escalation,
-    state: nextState,
-    projectRoot: paths.getProjectRoot(),
-    workflowPath,
-    escalationPath: created.path,
-  };
-};

package/src/workflow/escalation/resolveBuilderEscalation.ts

@@ -1,118 +0,0 @@
-/**
- * Objective: Resolve the current builder escalation and save the decision.
- * Used: When the owner keeps the approved contract and makes a decision.
- */
-
-import { readEscalationHistory } from '#artifacts/escalation/readEscalationHistory.ts';
-import { resolveEscalation } from '#artifacts/escalation/resolveEscalation.ts';
-import type {
-  Escalation,
-  EscalationResolution,
-} from '#artifacts/escalation/schema.ts';
-import type { MaestroPaths } from '#MaestroPaths.ts';
-import { readWorkflowState } from '#workflow/state/readWorkflowState.ts';
-import {
-  WORKFLOW_EVENTS,
-  WORKFLOW_PHASES,
-  type WorkflowState,
-} from '#workflow/state/schema.ts';
-import { writeWorkflowState } from '#workflow/state/writeWorkflowState.ts';
-import { transitionWorkflow } from '#workflow/transitions.ts';
-
-export type ResolvedBuilderEscalation = {
-  escalation: Escalation;
-  state: WorkflowState;
-  projectRoot: string;
-};
-
-type AssertCurrentEscalationInput<CurrentEscalation = Escalation | undefined> =
-  {
-    currentEscalation: CurrentEscalation;
-    escalationId: string;
-  };
-
-function assertCurrentEscalation(
-  input: AssertCurrentEscalationInput,
-): asserts input is AssertCurrentEscalationInput<Escalation> {
-  const { currentEscalation, escalationId } = input;
-
-  if (currentEscalation === undefined) {
-    throw new Error('There is no escalation to solve.');
-  }
-
-  if (currentEscalation.id !== escalationId) {
-    throw new Error(
-      `Only the current escalation can be resolved: expected "${currentEscalation.id}", found "${escalationId}".`,
-    );
-  }
-
-  if (currentEscalation.resolution !== null) {
-    throw new Error(`Escalation "${escalationId}" is already resolved.`);
-  }
-}
-
-type ResolveBuilderEscalationInput = {
-  paths: MaestroPaths;
-  specId: string;
-  escalationId: string;
-  resolution: EscalationResolution;
-};
-
-export const resolveBuilderEscalation = async ({
-  paths,
-  specId,
-  escalationId,
-  resolution,
-}: ResolveBuilderEscalationInput): Promise<ResolvedBuilderEscalation> => {
-  const workflowPath = paths.getWorkflowPath(specId);
-  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}".`,
-    );
-  }
-
-  const history = await readEscalationHistory({
-    directory: escalationsPath,
-    specId,
-  });
-
-  const escalationInput = { currentEscalation: history.at(-1), escalationId };
-  assertCurrentEscalation(escalationInput);
-  const { currentEscalation } = escalationInput;
-
-  const nextState = transitionWorkflow({
-    state: currentState,
-    event: WORKFLOW_EVENTS.RESOLVE_ESCALATION,
-  });
-
-  const escalationPath = paths.getEscalationPath({
-    specId,
-    escalationNumber: Number(currentEscalation.id.slice(1)),
-  });
-
-  const resolvedEscalation = await resolveEscalation({
-    path: escalationPath,
-    specId,
-    resolution,
-  });
-
-  await writeWorkflowState({
-    path: workflowPath,
-    state: nextState,
-  });
-
-  return {
-    escalation: resolvedEscalation,
-    state: nextState,
-    projectRoot: paths.getProjectRoot(),
-  };
-};