fix(matrix): route phase placement by command (Automattic#844)

Route planning, execution, and finalization through the Homeboy placement contracts intended for each command so fixture-matrix orchestration remains deterministic.

Closes Automattic#843.

AI assistance: OpenAI openai/gpt-5.6-sol and openai/gpt-5.6-terra via OpenCode diagnosed the wrapper/control-plane contract, implemented the command-specific routing and regression coverage, and verified the published parser repair across PHP 8.1-8.4. Chris Huber remains responsible for every line.

Author: chubes4

tools/fixture-matrix.test.mjs

@@ -33,6 +33,8 @@ import runFixtureMatrixBench, {
 import {
   buildCodeFreshness,
   buildFixtureMatrixRunPlan,
+  FIXTURE_MATRIX_PHASE_PLAN_SCHEMA,
+  phaseFailureDiagnostic,
   SOLVED_ONLY_LANE_ID,
   resolvePathFreshness,
   summarizeBenchRun,
@@ -3892,7 +3894,7 @@ test('--solved-only selects exactly the valid solved fixture corpus', () => {
   assert.ok(matrix.fixtures.every((fixture) => fixture.fixture_corpus === 'solved'));
 });
 
-test('fixture matrix operator composes typed placement only for the bench step', () => {
+test('fixture matrix deterministic dry-run phase plans route setup locally and workload by mode', () => {
   const root = mkdtempSync(path.join(tmpdir(), 'ssi-routing-plan-'));
   const staticSiteImporter = path.join(root, 'static-site-importer');
   const fixtureRoot = path.join(root, 'fixtures');
@@ -3908,6 +3910,19 @@ test('fixture matrix operator composes typed placement only for the bench step',
     ['rig', 'install', path.dirname(path.dirname(fileURLToPath(import.meta.url))), '--id', 'static-site-importer-fixture-matrix', '--reinstall'],
     ['rig', 'sync', 'static-site-importer-fixture-matrix'],
   ]);
+  assert.deepEqual(setupPlan.phase_plan, {
+    schema: FIXTURE_MATRIX_PHASE_PLAN_SCHEMA,
+    phases: setupPlan.steps.map(({ phase, placement, resolved_placement, reason, retry_command }) => ({
+      phase,
+      placement,
+      resolved_placement,
+      reason,
+      retry_command,
+    })),
+  });
+  assert.ok(setupPlan.steps.slice(0, -1).every((step) => step.phase === 'controller-setup' && step.placement === 'auto' && step.resolved_placement === 'controller-local'));
+  assert.equal(setupPlan.steps.at(-1).phase, 'fixture-workload');
+  assert.equal(setupPlan.steps.at(-1).resolved_placement, 'lab:homeboy-lab');
 
   const labPlan = buildFixtureMatrixRunPlan({
     runner: 'homeboy-lab',
@@ -3998,6 +4013,20 @@ test('fixture matrix operator composes typed placement only for the bench step',
   });
   assert.equal(autoPlan.execution_target, 'auto');
   assert.deepEqual(autoPlan.steps.at(-1).args.slice(-2), ['--placement', 'auto']);
+  assert.equal(autoPlan.steps.at(-1).resolved_placement, 'auto');
+});
+
+test('fixture matrix phase retries identify setup ownership and the exact command', () => {
+  const setup = {
+    phase: 'controller-setup',
+    label: 'Sync/materialize rig components (lab:homeboy-lab)',
+    command: 'homeboy',
+    args: ['rig', 'sync', 'static-site-importer-fixture-matrix'],
+  };
+  assert.equal(
+    phaseFailureDiagnostic(setup, 17),
+    'Sync/materialize rig components (lab:homeboy-lab) failed with exit 17 during controller-setup. Retry: homeboy rig sync static-site-importer-fixture-matrix',
+  );
 });
 
 test('fixture matrix operator projects exact Homeboy arguments for every routing mode', () => {
@@ -4802,11 +4831,21 @@ test('summarizeBenchRun still throws when a non-zero bench produced no parseable
   // No output file at all -> genuine crash, keep throwing.
   assert.throws(
     () => summarizeBenchRun({
-      plan: { mode: 'development-override', run_id: 'planned-run', output_file: missingOutput },
+      plan: {
+        mode: 'development-override',
+        run_id: 'planned-run',
+        output_file: missingOutput,
+        steps: [{
+          phase: 'fixture-workload',
+          label: 'Run SSI fixture matrix bench',
+          command: 'homeboy',
+          args: ['bench', '--rig', 'static-site-importer-fixture-matrix'],
+        }],
+      },
       benchStatus: 1,
       benchLabel: 'Run SSI fixture matrix bench',
     }),
-    /Run SSI fixture matrix bench failed with exit 1/,
+    /Run SSI fixture matrix bench failed with exit 1 during fixture-workload\. Retry: homeboy bench --rig static-site-importer-fixture-matrix/,
   );
 
   // Output exists but is unparseable / carries no result payload -> still a crash.

tools/run-fixture-matrix.mjs

@@ -15,6 +15,7 @@ import { FIXTURE_MATRIX_RUN_FIELDS, MAX_EXTRA_SURFACE_COUNT, createFixtureMatrix
 
 export const RIG_ID = 'static-site-importer-fixture-matrix';
 export const SOLVED_ONLY_LANE_ID = 'fixtures-solved-only/v1';
+export const FIXTURE_MATRIX_PHASE_PLAN_SCHEMA = 'static-site-importer/fixture-matrix-phase-plan/v1';
 
 const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 
@@ -122,6 +123,7 @@ export function buildFixtureMatrixRunPlan(input) {
     ...buildFreshnessWarnings(codeFreshness, options),
   ];
 
+  const steps = buildSteps(options, settings);
   return {
     schema: 'static-site-importer/fixture-matrix-operator-run/v1',
     mode: options.mode,
@@ -195,7 +197,17 @@ export function buildFixtureMatrixRunPlan(input) {
         },
       }
       : {},
-    steps: buildSteps(options, settings),
+    phase_plan: {
+      schema: FIXTURE_MATRIX_PHASE_PLAN_SCHEMA,
+      phases: steps.map(({ phase, placement, resolved_placement, reason, retry_command }) => ({
+        phase,
+        placement,
+        resolved_placement,
+        reason,
+        retry_command,
+      })),
+    },
+    steps,
   };
 }
 
@@ -680,18 +692,26 @@ function gitText(cwd, args, gitRunner) {
 function buildSteps(options, settings) {
   const steps = [];
   if (!options.skipInstall) {
-    steps.push({
+    steps.push(createPhaseStep({
+      phase: 'controller-setup',
+      placement: 'auto',
+      resolvedPlacement: 'controller-local',
+      reason: 'Rig source installation remains on the controller and does not inherit fixture workload routing.',
       label: `Refresh installed SSI fixture matrix rig (${options.executionTarget})`,
       command: options.homeboyBin,
       args: ['rig', 'install', packageRoot, '--id', RIG_ID, '--reinstall'],
-    });
+    }));
   }
   if (!options.skipSync) {
-    steps.push({
+    steps.push(createPhaseStep({
+      phase: 'controller-setup',
+      placement: 'auto',
+      resolvedPlacement: 'controller-local',
+      reason: 'Rig component synchronization remains on the controller and does not inherit fixture workload routing.',
       label: `Sync/materialize rig components (${options.executionTarget})`,
       command: options.homeboyBin,
       args: ['rig', 'sync', RIG_ID],
-    });
+    }));
   }
 
   const benchArgs = [
@@ -716,15 +736,39 @@ function buildSteps(options, settings) {
   if (options.passthrough.length > 0) {
     routedBenchArgs.push('--', ...options.passthrough);
   }
-  steps.push({
+  steps.push(createPhaseStep({
+    phase: 'fixture-workload',
+    placement: options.placement,
+    resolvedPlacement: workloadResolvedPlacement(options),
+    reason: 'Fixture execution owns the requested Homeboy placement and runner.',
     label: `Run SSI fixture matrix bench through Homeboy/Lab/WP Codebox (${options.executionTarget})`,
     command: options.homeboyBin,
     args: routedBenchArgs,
-  });
+  }));
 
   return steps;
 }
 
+function createPhaseStep({ phase, placement, resolvedPlacement, reason, label, command, args }) {
+  const step = {
+    phase,
+    placement,
+    resolved_placement: resolvedPlacement,
+    reason,
+    label,
+    command,
+    args,
+  };
+  return { ...step, retry_command: shellCommand(step) };
+}
+
+function workloadResolvedPlacement(options) {
+  if (options.runner) {
+    return `lab:${options.runner}`;
+  }
+  return options.placement;
+}
+
 function withBenchRouting(args, options) {
   const routed = [...args];
   if (!(options.runner && options.placement === 'lab')) {
@@ -745,10 +789,16 @@ function withBenchRouting(args, options) {
 function runCommand(step) {
   const status = runStep(step);
   if (status !== 0) {
-    throw new Error(`${step.label} failed with exit ${status}`);
+    throw new Error(phaseFailureDiagnostic(step, status));
   }
 }
 
+export function phaseFailureDiagnostic(step, status) {
+  const phase = step.phase || 'unknown';
+  const retry = step.retry_command || shellCommand(step);
+  return `${step.label} failed with exit ${status} during ${phase}. Retry: ${retry}`;
+}
+
 // Run a step and return its exit status without throwing, so callers can decide
 // whether a non-zero exit is fatal (setup) or an expected outcome (bench gate).
 function runStep(step) {
@@ -763,7 +813,10 @@ function runStep(step) {
 // On crash, preserve the historical throw/error behavior.
 export function summarizeBenchRun({ plan, benchStatus, benchLabel = 'bench step' }) {
   if (benchStatus !== 0 && !benchProducedResult(plan.output_file)) {
-    throw new Error(`${benchLabel} failed with exit ${benchStatus}`);
+    const benchStep = plan.steps?.at(-1);
+    throw new Error(benchStep
+      ? phaseFailureDiagnostic(benchStep, benchStatus)
+      : `${benchLabel} failed with exit ${benchStatus}`);
   }
   const gateFailed = benchStatus !== 0;
   return {