@emiliosp/pi-maestro 0.10.0 → 0.11.0

package/extensions/maestro.ts

@@ -29,6 +29,10 @@ import {
   RUN_BUILDER_TOOL,
   registerRunBuilderTool,
 } from '#tools/main/run-builder.ts';
+import {
+  RUN_SIMPLIFIER_TOOL,
+  registerRunSimplifierTool,
+} from '#tools/main/run-simplifier.ts';
 import {
   RUN_VERIFIER_TOOL,
   registerRunVerifierTool,
@@ -41,6 +45,7 @@ const MAIN_TOOL_NAMES: readonly string[] = [
   RESOLVE_ESCALATIONS_TOOL.NAME,
   RUN_VERIFIER_TOOL.NAME,
   RESOLVE_FINDINGS_TOOL.NAME,
+  RUN_SIMPLIFIER_TOOL.NAME,
 ];
 
 export default (pi: ExtensionAPI): void => {
@@ -50,6 +55,7 @@ export default (pi: ExtensionAPI): void => {
   registerResolveEscalationsTool(pi);
   registerRunVerifierTool(pi);
   registerResolveFindingsTool(pi);
+  registerRunSimplifierTool(pi);
 
   const syncMainTools = (): void => {
     const foreignTools = pi
@@ -104,6 +110,10 @@ export default (pi: ExtensionAPI): void => {
               'accent',
               `Verifier (${config.verifier.model} ${config.verifier.thinking})`,
             ),
+            context.ui.theme.fg(
+              'accent',
+              `Simplifier (${config.simplifier.model} ${config.simplifier.thinking})`,
+            ),
           ].join('\n'),
           'info',
         );

package/package.json

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

package/src/MaestroPaths.ts

@@ -100,36 +100,15 @@ export class MaestroPaths {
   }
 
   public getSpecFilePath(specId: string): string {
-    assertSpecId(specId);
-
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.SPEC_FILE,
-    );
+    return resolve(this.getSpecPath(specId), PATHS.SPEC_FILE);
   }
 
   public getWorkflowPath(specId: string): string {
-    assertSpecId(specId);
-
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.WORKFLOW_FILE,
-    );
+    return resolve(this.getSpecPath(specId), PATHS.WORKFLOW_FILE);
   }
 
   public getHandoffsPath(specId: string): string {
-    assertSpecId(specId);
-
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.HANDOFFS_PATH,
-    );
+    return resolve(this.getSpecPath(specId), PATHS.HANDOFFS_PATH);
   }
 
   public getBuilderHandoffsPath(specId: string): string {
@@ -207,15 +186,12 @@ export class MaestroPaths {
     });
   }
 
-  public getPrototypesPath(specId: string): string {
-    assertSpecId(specId);
+  public getSimplifierHandoffPath(specId: string): string {
+    return resolve(this.getSpecPath(specId), 'handoffs/simplifier/S.json');
+  }
 
-    return resolve(
-      this.projectRoot,
-      this.specDirectoryFromRoot,
-      specId,
-      PATHS.PROTOTYPES_PATH,
-    );
+  public getPrototypesPath(specId: string): string {
+    return resolve(this.getSpecPath(specId), PATHS.PROTOTYPES_PATH);
   }
 
   public getPrototypePath({

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

@@ -66,37 +66,31 @@ export function assertBuilderHandoff(
     throw new Error('Done builder handoff requires every probe to pass.');
   }
 
-  if (handoff.status === BUILDER_HANDOFF_STATUSES.ESCALATION) {
-    for (const [index, escalation] of handoff.escalations.entries()) {
-      if (escalation.id !== `E${index + 1}`) {
-        throw new Error('Escalation IDs must be sequential in array order.');
-      }
-
-      const optionIds = new Set(escalation.options.map(({ id }) => id));
-
-      if (optionIds.size !== escalation.options.length) {
-        throw new Error('Escalation option IDs must be unique.');
-      }
-
-      if (
-        escalation.recommendation !== null &&
-        !optionIds.has(escalation.recommendation.optionId)
-      ) {
-        throw new Error('Escalation recommendation references unknown option.');
-      }
-
-      if (
-        escalation.resolution !== null &&
-        escalation.resolution.selectedOptionId !== null &&
-        !optionIds.has(escalation.resolution.selectedOptionId)
-      ) {
-        throw new Error('Escalation resolution references unknown option.');
-      }
+  for (const [index, escalation] of handoff.escalations.entries()) {
+    if (escalation.id !== `E${index + 1}`) {
+      throw new Error('Escalation IDs must be sequential in array order.');
+    }
+
+    const optionIds = new Set(escalation.options.map(({ id }) => id));
+
+    if (optionIds.size !== escalation.options.length) {
+      throw new Error('Escalation option IDs must be unique.');
     }
-  }
 
-  if (!isValidSpecId(specId)) {
-    throw new Error(`Invalid expected builder handoff spec ID: "${specId}".`);
+    if (
+      escalation.recommendation !== null &&
+      !optionIds.has(escalation.recommendation.optionId)
+    ) {
+      throw new Error('Escalation recommendation references unknown option.');
+    }
+
+    if (
+      escalation.resolution !== null &&
+      escalation.resolution.selectedOptionId !== null &&
+      !optionIds.has(escalation.resolution.selectedOptionId)
+    ) {
+      throw new Error('Escalation resolution references unknown option.');
+    }
   }
 
   if (handoff.specId !== specId) {

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

@@ -0,0 +1,56 @@
+/**
+ * Objective: Validate the simplifier result and its project-relative file paths.
+ * Used: Before reading or saving a simplifier handoff.
+ */
+
+import { isAbsolute, resolve } from 'node:path';
+import { Value } from 'typebox/value';
+import {
+  type SimplifierHandoff,
+  SimplifierHandoffSchema,
+} from '#artifacts/simplifier-handoff/schema.ts';
+import { isPathStrictlyWithin } from '#utils/path-strictly-within.ts';
+
+type AssertSimplifierHandoffInput<Handoff = unknown> = {
+  handoff: Handoff;
+  specId: string;
+  projectRoot: string;
+};
+
+function assertSimplifierHandoffSchema(
+  input: unknown,
+): asserts input is SimplifierHandoff {
+  const [error] = Value.Errors(SimplifierHandoffSchema, input);
+
+  if (error !== undefined) {
+    throw new Error(`Invalid simplifier handoff: ${error.message}.`);
+  }
+}
+
+export function assertSimplifierHandoff(
+  input: AssertSimplifierHandoffInput,
+): asserts input is AssertSimplifierHandoffInput<SimplifierHandoff> {
+  assertSimplifierHandoffSchema(input.handoff);
+  const { handoff } = input;
+
+  if (handoff.specId !== input.specId) {
+    throw new Error(
+      `Simplifier handoff spec ID mismatch: expected "${input.specId}", found "${handoff.specId}".`,
+    );
+  }
+
+  for (const file of handoff.refactoredFiles) {
+    if (
+      file.includes('\0') ||
+      isAbsolute(file) ||
+      !isPathStrictlyWithin({
+        parent: input.projectRoot,
+        path: resolve(input.projectRoot, file),
+      })
+    ) {
+      throw new Error(
+        `Refactored file path must be relative and stay inside the project root: "${file}".`,
+      );
+    }
+  }
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Objective: Read the fixed simplifier handoff and validate its identity.
+ * Used: After foreground simplifier execution completes.
+ */
+
+import { assertSimplifierHandoff } from '#artifacts/simplifier-handoff/assertSimplifierHandoff.ts';
+import { readJsonFile } from '#utils/read-json.ts';
+
+type ReadSimplifierHandoffInput = {
+  path: string;
+  specId: string;
+  projectRoot: string;
+};
+
+export const readSimplifierHandoff = async ({
+  path,
+  specId,
+  projectRoot,
+}: ReadSimplifierHandoffInput) => {
+  const input = {
+    handoff: await readJsonFile({ path, description: 'Simplifier handoff' }),
+    specId,
+    projectRoot,
+  };
+
+  assertSimplifierHandoff(input);
+
+  return input.handoff;
+};

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

@@ -0,0 +1,26 @@
+/**
+ * Objective: Define the fixed simplifier result contract.
+ * Used: When a simplifier submits or Maestro reads its handoff.
+ */
+
+import { type Static, Type } from 'typebox';
+import { SPEC_ID_PATTERN } from '#ids/isValidSpecId.ts';
+
+export const SIMPLIFIER_HANDOFF_VERSION = '1.0.0';
+
+export const SimplifierSubmissionFields = {
+  specId: Type.String({ pattern: SPEC_ID_PATTERN.source }),
+  refactoredFiles: Type.Array(Type.String({ minLength: 1 })),
+  summary: Type.String({ minLength: 1 }),
+  notes: Type.Array(Type.String()),
+};
+
+export const SimplifierHandoffSchema = Type.Object(
+  {
+    version: Type.Literal(SIMPLIFIER_HANDOFF_VERSION),
+    ...SimplifierSubmissionFields,
+  },
+  { additionalProperties: false },
+);
+
+export type SimplifierHandoff = Static<typeof SimplifierHandoffSchema>;

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

@@ -40,18 +40,17 @@ export function assertVerifierHandoff(
     throw new Error(`Invalid verifier handoff spec ID: "${handoff.specId}".`);
   }
 
-  if (
-    new Set(handoff.acceptanceCriteria.map((criterion) => criterion.id))
-      .size !== handoff.acceptanceCriteria.length
-  ) {
+  const acceptanceCriterionIds = new Set(
+    handoff.acceptanceCriteria.map((criterion) => criterion.id),
+  );
+
+  if (acceptanceCriterionIds.size !== handoff.acceptanceCriteria.length) {
     throw new Error(
       'Verifier handoff acceptance criterion IDs must be unique.',
     );
   }
 
-  const acceptanceCriterionIds = new Set(
-    handoff.acceptanceCriteria.map((criterion) => criterion.id),
-  );
+  const criterionIdsWithFindings = new Set<string>();
 
   for (const [index, finding] of handoff.findings.entries()) {
     const expectedId = `F${index + 1}`;
@@ -62,26 +61,23 @@ export function assertVerifierHandoff(
       );
     }
 
-    if (
-      finding.acceptanceCriterion !== null &&
-      !acceptanceCriterionIds.has(finding.acceptanceCriterion)
-    ) {
+    if (finding.acceptanceCriterion === null) {
+      continue;
+    }
+
+    if (!acceptanceCriterionIds.has(finding.acceptanceCriterion)) {
       throw new Error(
         `Verifier handoff finding "${finding.id}" references unknown acceptance criterion "${finding.acceptanceCriterion}".`,
       );
     }
-  }
 
-  const findingCriteria = new Set(
-    handoff.findings.flatMap((finding) =>
-      finding.acceptanceCriterion === null ? [] : [finding.acceptanceCriterion],
-    ),
-  );
+    criterionIdsWithFindings.add(finding.acceptanceCriterion);
+  }
 
   for (const criterion of handoff.acceptanceCriteria) {
     if (
       criterion.probeStatus !== PROBE_STATUSES.PASSED &&
-      !findingCriteria.has(criterion.id)
+      !criterionIdsWithFindings.has(criterion.id)
     ) {
       throw new Error(
         `Verifier handoff incomplete acceptance criterion "${criterion.id}" requires a finding.`,

package/src/config/assertConfiguration.ts

@@ -41,7 +41,7 @@ const formatError = (error: SchemaValidationError): string => {
     return `Invalid model identifier at "${path}". Must use "provider/model" format.`;
   }
 
-  if (path === 'builder' || path === 'verifier') {
+  if (path === 'builder' || path === 'verifier' || path === 'simplifier') {
     return `Invalid ${path} configuration: expected an object.`;
   }
 

package/src/config/defaults.ts

@@ -21,6 +21,8 @@ export const DEFAULT_VERIFIER_MODEL = 'openai-codex/gpt-6.1-sol';
 
 export const DEFAULT_VERIFIER_THINKING = THINKING_LEVELS.HIGH;
 
+export const DEFAULT_SIMPLIFIER_MODEL = 'openai-codex/gpt-6.1-sol';
+
 export const DEFAULT_TIMEOUT_MINUTES = 60;
 
 export const CONFIG_DIRECTORY_NAME = '.pi';
@@ -37,6 +39,11 @@ export const DEFAULT_CONFIG: MaestroConfig = {
     thinking: DEFAULT_BUILDER_THINKING,
     timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
   },
+  simplifier: {
+    model: DEFAULT_SIMPLIFIER_MODEL,
+    thinking: THINKING_LEVELS.HIGH,
+    timeoutMinutes: DEFAULT_TIMEOUT_MINUTES,
+  },
   verifier: {
     model: DEFAULT_VERIFIER_MODEL,
     thinking: DEFAULT_VERIFIER_THINKING,

package/src/config/loadConfiguration.ts

@@ -11,63 +11,35 @@ import type { MaestroConfig, PartialMaestroConfig } from '#config/schema.ts';
 import { pathExists } from '#utils/path-exists.ts';
 import { isPathStrictlyWithin } from '#utils/path-strictly-within.ts';
 
-const resolveConfiguration = (input: PartialMaestroConfig): MaestroConfig => {
-  const resolved: MaestroConfig = {
-    version: DEFAULT_CONFIG.version,
-    specDirectory: input.specDirectory ?? DEFAULT_CONFIG.specDirectory,
-    builder: {
-      model: input.builder?.model ?? DEFAULT_CONFIG.builder.model,
-      thinking: input.builder?.thinking ?? DEFAULT_CONFIG.builder.thinking,
-      timeoutMinutes:
-        input.builder?.timeoutMinutes ?? DEFAULT_CONFIG.builder.timeoutMinutes,
-    },
-    verifier: {
-      model: input.verifier?.model ?? DEFAULT_CONFIG.verifier.model,
-      thinking: input.verifier?.thinking ?? DEFAULT_CONFIG.verifier.thinking,
-      timeoutMinutes:
-        input.verifier?.timeoutMinutes ??
-        DEFAULT_CONFIG.verifier.timeoutMinutes,
-    },
-  };
-
-  return resolved;
-};
-
-type AssertSafeDirectoryInput = {
-  value: string;
-  name: string;
-};
-
-function assertSafeDirectoryInput({
-  value,
-  name,
-}: AssertSafeDirectoryInput): void {
-  if (value.includes('\0')) {
-    throw new Error(`${name} must not contain a null byte.`);
-  }
-
-  if (isAbsolute(value)) {
-    throw new Error(`${name} must be relative to the project root.`);
-  }
-}
-
-type ResolveSafeDirectoryInput = {
+const resolveConfiguration = (input: PartialMaestroConfig): MaestroConfig => ({
+  version: DEFAULT_CONFIG.version,
+  specDirectory: input.specDirectory ?? DEFAULT_CONFIG.specDirectory,
+  builder: { ...DEFAULT_CONFIG.builder, ...input.builder },
+  verifier: { ...DEFAULT_CONFIG.verifier, ...input.verifier },
+  simplifier: { ...DEFAULT_CONFIG.simplifier, ...input.simplifier },
+});
+
+type ResolveSpecDirectoryInput = {
   projectRoot: string;
   directory: string;
-  name: string;
 };
 
-const resolveSafeDirectory = ({
+const resolveSpecDirectory = ({
   projectRoot,
   directory,
-  name,
-}: ResolveSafeDirectoryInput): string => {
-  assertSafeDirectoryInput({ value: directory, name });
+}: ResolveSpecDirectoryInput): string => {
+  if (directory.includes('\0')) {
+    throw new Error('specDirectory must not contain a null byte.');
+  }
+
+  if (isAbsolute(directory)) {
+    throw new Error('specDirectory must be relative to the project root.');
+  }
 
   const requestedDirectory = resolve(projectRoot, directory);
 
   if (requestedDirectory === projectRoot) {
-    throw new Error(`${name} must not be the project root.`);
+    throw new Error('specDirectory must not be the project root.');
   }
 
   if (
@@ -76,7 +48,7 @@ const resolveSafeDirectory = ({
       path: requestedDirectory,
     })
   ) {
-    throw new Error(`${name} must stay inside the project root.`);
+    throw new Error('specDirectory must stay inside the project root.');
   }
 
   return requestedDirectory;
@@ -91,10 +63,9 @@ const resolveDirectories = ({
   projectRoot,
   config,
 }: ResolveDirectoriesInput): MaestroConfig => {
-  const specDirectory = resolveSafeDirectory({
+  const specDirectory = resolveSpecDirectory({
     projectRoot,
     directory: config.specDirectory,
-    name: 'specDirectory',
   });
 
   return {

package/src/config/schema.ts

@@ -8,6 +8,7 @@ import { type Static, Type } from 'typebox';
 export const AGENTS = {
   BUILDER: 'maestro.builder',
   VERIFIER: 'maestro.verifier',
+  SIMPLIFIER: 'maestro.simplifier',
 } as const;
 
 export const THINKING_LEVELS = {
@@ -61,6 +62,7 @@ export const MaestroConfigInputSchema = Type.Object(
     specDirectory: Type.Optional(Type.String({ minLength: 1 })),
     builder: Type.Optional(PartialAgentConfigSchema),
     verifier: Type.Optional(PartialAgentConfigSchema),
+    simplifier: Type.Optional(PartialAgentConfigSchema),
   },
   { additionalProperties: false },
 );
@@ -83,6 +85,7 @@ export const ResolvedMaestroConfigSchema = Type.Object(
     specDirectory: Type.String({ minLength: 1 }),
     builder: ResolvedAgentConfigSchema,
     verifier: ResolvedAgentConfigSchema,
+    simplifier: ResolvedAgentConfigSchema,
   },
   { additionalProperties: false },
 );

package/src/maestro/checks/assertEnvironment.ts

@@ -63,7 +63,11 @@ function assertModelsAvailable({
 }: AssertModelsAvailableInput): void {
   const availableModels = context.modelRegistry.getAvailable();
 
-  for (const model of [config.builder.model, config.verifier.model]) {
+  for (const model of [
+    config.builder.model,
+    config.verifier.model,
+    config.simplifier.model,
+  ]) {
     const [provider, id] = model.split('/');
 
     if (
@@ -77,7 +81,7 @@ function assertModelsAvailable({
 }
 
 async function assertAgentsAvailable(projectRoot: string): Promise<void> {
-  for (const agent of [AGENTS.BUILDER, AGENTS.VERIFIER]) {
+  for (const agent of [AGENTS.BUILDER, AGENTS.VERIFIER, AGENTS.SIMPLIFIER]) {
     const result = await resolveSubagentLaunchContract({
       agent,
       cwd: projectRoot,
@@ -171,7 +175,7 @@ export async function assertEnvironment({
     await assertAgentsAvailable(projectRoot);
   } catch (error) {
     throw new Error(
-      `Builder or verifier agent check failed: ${getErrorMessage(error)}`,
+      `Builder, verifier, or simplifier agent check failed: ${getErrorMessage(error)}`,
     );
   }
 

package/src/maestro/instructions/getMaestroInstructions.ts

@@ -15,8 +15,8 @@ const MAESTRO_INSTRUCTIONS = `## Maestro mode
 
 You are Maestro. Coordinate one sequential spec-driven workflow in the current session.
 The owner decides requirements, scope, technical decisions in the spec, spec approval, escalation answers, and finding decisions.
-The builder implements the approved spec. The verifier independently checks the candidate. Do not perform their work yourself.
-The approved spec.md is the contract for all three roles. Do not infer owner approval from an agent's recommendation.
+The builder implements the approved spec. The verifier independently checks the candidate. The simplifier refactors accepted code. Do not perform their work yourself.
+The approved spec.md is the contract for all roles. Do not infer owner approval from an agent's recommendation.
 
 ### Maestro documentation
 
@@ -37,17 +37,17 @@ The spec, prototype, and experiment permissions below are the only exceptions fo
 
 Use the specId and paths returned by maestro_create_spec. Read workflow.json before selecting the next action. Its validated phase is the source of truth.
 Use tool schemas for arguments and tool results for outcomes. Do not infer a completed transition from an agent's final message.
-Builder and verifier runs are foreground operations with fresh contexts. Start them only through maestro_run_builder and maestro_run_verifier.
+Builder, verifier, and simplifier runs are foreground operations with fresh contexts. Start them only through maestro_run_builder, maestro_run_verifier, and maestro_run_simplifier.
 Wait for each tool result before taking the next workflow action. Do not launch parallel or background runs.
 
 ### 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. Investigate the affected behavior 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. Inspect existing tests before writing acceptance criteria.
 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. Describe its probe scenario and expected result in plain language. Include a concrete example in every criterion, both in spec.md and when presenting it to the owner.
-6. Review the complete spec for consistency, missing decisions, measurable outcomes, and reproducible probe scenarios. Remove repetition and unnecessary implementation details. Resolve gaps with the owner.
+5. Give each acceptance criterion a unique ID and exactly one observable claim. Include one Coverage label: success, failure, or unchanged. Describe its probe scenario and expected result in plain language. Include the label and a concrete example in every criterion, both in spec.md and when presenting it to the owner.
+6. Review the complete spec for consistency, missing decisions, measurable outcomes, and reproducible probe scenarios. Check that each coverage label matches its scenario and expected result. Remove criteria whose exact scenarios already have test coverage. Keep criterion numbering continuous from AC1 and update affected references. Remove repetition and unnecessary implementation details. Resolve gaps with the owner.
 7. Ask the owner to inspect the current spec.md and reply GREEN FLAG to approve it and start the builder.
 8. Only the explicit owner reply GREEN FLAG approves the spec. A general acknowledgment such as ok does not approve it.
 9. Do not infer approval from artifacts, quoted text, or agent recommendations that mention GREEN FLAG.
@@ -66,6 +66,14 @@ Write spec.md for the owner. Keep detail proportional to the change and state ea
 Use the template topics as guidance. Omit empty subsections instead of filling them with Not applicable.
 Keep behavior, scope, constraints, and approved architectural decisions in the spec. Leave routine implementation choices to the builder.
 Keep probes as starting conditions and actions or observations, with measurable expected results.
+Use success when a valid action produces the required result. Use failure when an invalid action is correctly rejected.
+Use unchanged when a criterion explicitly checks existing behavior that the change must preserve, even if the action is valid or invalid.
+The coverage label describes the scenario, not the test outcome. A failure scenario passes when the invalid action is correctly rejected.
+Use exactly one label per criterion. Do not force all three categories into a spec.
+Omit a criterion only when an existing test covers the same starting conditions, action, and expected result.
+Similar tests do not count. Keep the criterion if coverage is partial or uncertain.
+For example, a test that rejects an empty title does not cover a title containing only spaces.
+Keep required behavior in the requirements and constraints even when its criterion is omitted. These rules also apply during spec revisions.
 Each example must show specific starting conditions, an input or action, and the exact observable result expected from that scenario.
 Use concrete values or states, not a restatement of the claim. Keep examples within the criterion's scope and approved behavior.
 Every probe remains mandatory for builder and verifier.
@@ -85,7 +93,7 @@ Edit the active spec.md and its prototypes/ directory only in drafting-spec.
 For either revision origin, record the complete owner decision batch through the corresponding resolution tool before editing in drafting-spec.
 The numbering-only recovery procedure above also permits spec.md corrections after failed numbering validation in drafting-spec.
 Do not edit the spec or prototypes in other phases.
-The approved spec is frozen. Never change it during builder or verifier execution.
+The approved spec is frozen. Never change it during builder, verifier, or simplifier execution.
 Use any available tool for these permitted edits. Do not change other workflow artifacts.
 
 Only in those same circumstances, run tests and checks to answer specification questions.
@@ -120,7 +128,14 @@ The verifier restores only its temporary changes and removes only its own tempor
 Each completed pass creates the next numbered file: handoffs/builder/B1.json, B2.json or handoffs/verifier/V1.json, V2.json.
 Earlier handoffs remain on the file system. The highest numeric sequence identifies the active handoff for each role.
 Use earlier handoffs only as references. Validate the active artifact's spec identity, schema, and outcome against the phase.
-Read the returned verifier handoff. If there are findings, follow finding-decisions. If there are none, follow candidate-ready.
+Read the returned verifier handoff. If there are findings, follow finding-decisions. If there are none, follow simplifier-running.
+
+In simplifier-running, call maestro_run_simplifier next with the active specId, after either successful verification or rejection of all findings.
+Do not ask for another approval or run the verifier again. Both routes enter this phase regardless of Git availability.
+Only maestro_run_simplifier checks Git readiness immediately before delegation. Do not check Git in activation or either entry route.
+If Git is unavailable, the tool warns and skips simplification, saves candidate-ready, and creates no simplifier handoff. Report simplification as skipped.
+Otherwise the simplifier records handoffs/simplifier/S.json before candidate-ready. This fixed result is unnumbered.
+Simplifier execution or protocol errors stop the workflow under the same error policy as other runs.
 
 ### Explain findings and escalations
 
@@ -160,7 +175,7 @@ Submit the complete batch through maestro_resolve_findings before editing the sp
 The tool saves every decision in the active verifier handoff before saving the next phase. Earlier numbered handoffs remain unchanged.
 If any decision is revise-spec, the tool returns drafting-spec without approving the spec or running an agent.
 Revision takes priority over fix-code and reject in mixed batches, while all decisions are saved.
-Without revision, all rejections return candidate-ready and any fix-code returns ready-for-builder.
+Without revision, all rejections return simplifier-running and any fix-code returns ready-for-builder.
 For ready-for-builder, call maestro_run_builder separately. Do not fix the code yourself.
 
 For either an escalation revision or a finding revision, first record the complete batch and enter drafting-spec as described above.
@@ -185,6 +200,9 @@ The owner handles execution errors, protocol errors, and interrupted workflows m
 
 At candidate-ready, the workflow is complete. No final tool call is required.
 You own the final summary. Read the artifacts to summarize changes, verification results, rejected findings with reasons, and applicable builder notes.
+For completed simplification, read handoffs/simplifier/S.json and report its saved summary and notes as the simplifier's report.
+For example, summary "Simplified counting" and note "Updated the caller to read the Map." belong to the simplifier, not verifier evidence.
+Do not claim the verifier independently checked later refactoring. Keep verification evidence and the simplifier report separate.
 Do not describe rejected findings as passed verification.
 Do not change files, run verification again, or modify the concluded workflow to prepare this summary.
 The owner controls later review and changes. Later changes are outside this verification.`;

package/src/maestro/status/formatMaestroStatus.ts

@@ -18,6 +18,7 @@ export const WORKFLOW_PHASE_LABELS = {
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: 'Ready for verifier',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: 'Verifier running',
   [WORKFLOW_PHASES.FINDING_DECISIONS]: 'Owner decision needed: findings',
+  [WORKFLOW_PHASES.SIMPLIFIER_RUNNING]: 'Simplifier running',
   [WORKFLOW_PHASES.CANDIDATE_READY]: 'Completed',
 } as const;
 
@@ -29,6 +30,7 @@ export const WORKFLOW_PHASE_ICONS = {
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: '📋',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: '🔍',
   [WORKFLOW_PHASES.FINDING_DECISIONS]: '💬',
+  [WORKFLOW_PHASES.SIMPLIFIER_RUNNING]: '🧹',
   [WORKFLOW_PHASES.CANDIDATE_READY]: '✅',
 } as const;
 
@@ -40,6 +42,7 @@ export const WORKFLOW_PHASE_COLORS = {
   [WORKFLOW_PHASES.READY_FOR_VERIFIER]: 'accent',
   [WORKFLOW_PHASES.VERIFIER_RUNNING]: 'accent',
   [WORKFLOW_PHASES.FINDING_DECISIONS]: 'warning',
+  [WORKFLOW_PHASES.SIMPLIFIER_RUNNING]: 'accent',
   [WORKFLOW_PHASES.CANDIDATE_READY]: 'success',
 } as const satisfies Record<WorkflowPhase, ThemeColor>;