agentxchain 2.99.0 → 2.101.0

package/bin/agentxchain.js

@@ -59,7 +59,7 @@ import { generateCommand } from '../src/commands/generate.js';
 import { doctorCommand } from '../src/commands/doctor.js';
 import { superviseCommand } from '../src/commands/supervise.js';
 import { validateCommand } from '../src/commands/validate.js';
-import { verifyExportCommand, verifyProtocolCommand, verifyTurnCommand } from '../src/commands/verify.js';
+import { verifyDiffCommand, verifyExportCommand, verifyProtocolCommand, verifyTurnCommand } from '../src/commands/verify.js';
 import { replayTurnCommand } from '../src/commands/replay.js';
 import { replayExportCommand } from '../src/commands/replay-export.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
@@ -401,6 +401,12 @@ verifyCmd
   .option('--format <format>', 'Output format: text or json', 'text')
   .action(verifyExportCommand);
 
+verifyCmd
+  .command('diff <left_export> <right_export>')
+  .description('Verify two export artifacts, then detect governance regressions between them')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .action(verifyDiffCommand);
+
 const replayCmd = program
   .command('replay')
   .description('Replay accepted governed evidence against the current workspace');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.99.0",
+  "version": "2.101.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/scripts/normalize-release-note-sidebar-positions.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '..', '..');
+const releasesDir = join(repoRoot, 'website-v2', 'docs', 'releases');
+
+function parseReleaseFile(file) {
+  const match = /^v(\d+)-(\d+)-(\d+)\.mdx$/.exec(file);
+  if (!match) {
+    throw new Error(`Unparseable release note filename: ${file}`);
+  }
+  return {
+    file,
+    version: match.slice(1).map(Number),
+  };
+}
+
+function compareDesc(left, right) {
+  for (let i = 0; i < 3; i += 1) {
+    if (left.version[i] !== right.version[i]) {
+      return right.version[i] - left.version[i];
+    }
+  }
+  return 0;
+}
+
+function updateSidebarPosition(content, nextPosition) {
+  if (!content.startsWith('---\n')) {
+    throw new Error('Release note is missing YAML frontmatter opening delimiter');
+  }
+
+  const frontmatterEnd = content.indexOf('\n---\n', 4);
+  if (frontmatterEnd === -1) {
+    throw new Error('Release note is missing YAML frontmatter closing delimiter');
+  }
+
+  const frontmatter = content.slice(0, frontmatterEnd + 5);
+  const body = content.slice(frontmatterEnd + 5);
+  const expectedLine = `sidebar_position: ${nextPosition}`;
+
+  let updatedFrontmatter;
+  if (/^sidebar_position:\s*\d+\s*$/m.test(frontmatter)) {
+    updatedFrontmatter = frontmatter.replace(/^sidebar_position:\s*\d+\s*$/m, expectedLine);
+  } else {
+    updatedFrontmatter = frontmatter.replace(/^---\n/, `---\n${expectedLine}\n`);
+  }
+
+  const updated = updatedFrontmatter + body;
+  return {
+    updated,
+    changed: updated !== content,
+  };
+}
+
+const releaseFiles = readdirSync(releasesDir)
+  .filter((file) => /^v\d+-\d+-\d+\.mdx$/.test(file))
+  .map(parseReleaseFile)
+  .sort(compareDesc);
+
+if (releaseFiles.length === 0) {
+  throw new Error(`No release notes found in ${releasesDir}`);
+}
+
+let changedCount = 0;
+for (const [index, release] of releaseFiles.entries()) {
+  const filePath = join(releasesDir, release.file);
+  const content = readFileSync(filePath, 'utf8');
+  const { updated, changed } = updateSidebarPosition(content, index);
+  if (changed) {
+    writeFileSync(filePath, updated);
+    changedCount += 1;
+  }
+}
+
+console.log(
+  `Normalized release note sidebar positions across ${releaseFiles.length} files (${changedCount} updated).`,
+);

package/scripts/release-bump.sh

@@ -192,13 +192,18 @@ if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
 fi
 echo "  OK: all 8 governed version surfaces reference ${TARGET_VERSION}"
 
-# 5. Auto-align Homebrew mirror to target version
+# 5. Normalize release-note sidebar ordering
+echo "[5/10] Normalizing release-note sidebar positions..."
+node "${CLI_DIR}/scripts/normalize-release-note-sidebar-positions.mjs"
+echo "  OK: release-note sidebar positions normalized newest-first"
+
+# 6. Auto-align Homebrew mirror to target version
 # The formula URL and README version/tarball are updated automatically.
 # The SHA256 is carried from the previous committed formula — it is inherently a
 # post-publish artifact (npm registry tarballs are not byte-identical to
 # local npm-pack output). Any working-tree SHA edit is overwritten here.
 # sync-homebrew.sh corrects the SHA after publish.
-echo "[5/9] Auto-aligning Homebrew mirror to ${TARGET_VERSION}..."
+echo "[6/10] Auto-aligning Homebrew mirror to ${TARGET_VERSION}..."
 HOMEBREW_MIRROR="${REPO_ROOT}/cli/homebrew/agentxchain.rb"
 HOMEBREW_MIRROR_README="${REPO_ROOT}/cli/homebrew/README.md"
 TARBALL_URL="https://registry.npmjs.org/agentxchain/-/agentxchain-${TARGET_VERSION}.tgz"
@@ -256,13 +261,13 @@ else
   echo "  Skipped: no Homebrew mirror files found"
 fi
 
-# 6. Update version files (no git operations)
-echo "[6/9] Updating version files..."
+# 7. Update version files (no git operations)
+echo "[7/10] Updating version files..."
 npm version "$TARGET_VERSION" --no-git-tag-version
 echo "  OK: package.json updated to ${TARGET_VERSION}"
 
-# 7. Stage version files
-echo "[7/9] Staging version files..."
+# 8. Stage version files
+echo "[8/10] Staging version files..."
 git add -- package.json
 if [[ -f package-lock.json ]]; then
   git add -- package-lock.json
@@ -270,10 +275,11 @@ fi
 for rel_path in "${ALLOWED_RELEASE_PATHS[@]}"; do
   stage_if_present "$rel_path"
 done
+git -C "$REPO_ROOT" add -- website-v2/docs/releases
 echo "  OK: version files and allowed release surfaces staged"
 
-# 8. Create release commit
-echo "[8/9] Creating release commit..."
+# 9. Create release commit
+echo "[9/10] Creating release commit..."
 git commit -m "${TARGET_VERSION}"
 RELEASE_SHA=$(git rev-parse HEAD)
 COMMIT_MSG=$(git log -1 --format=%s)
@@ -283,13 +289,13 @@ if [[ "$COMMIT_MSG" != "$TARGET_VERSION" ]]; then
 fi
 echo "  OK: commit ${RELEASE_SHA:0:7} with message '${TARGET_VERSION}'"
 
-# 8.5. Inline preflight gate — tests, pack, and docs build must pass before tag
+# 9.5. Inline preflight gate — tests, pack, and docs build must pass before tag
 if [[ "$SKIP_PREFLIGHT" -eq 1 ]]; then
   echo ""
-  echo "[8.5/10] Inline preflight gate SKIPPED (--skip-preflight)"
+  echo "[9.5/11] Inline preflight gate SKIPPED (--skip-preflight)"
 else
   echo ""
-  echo "[8.5/10] Running inline preflight gate..."
+  echo "[9.5/11] Running inline preflight gate..."
   echo "  Running test suite..."
 
   # Install MCP example deps if needed (same as release-preflight.sh)
@@ -342,8 +348,8 @@ else
   echo "  Inline preflight gate passed — proceeding to tag"
 fi
 
-# 9. Create annotated tag
-echo "[9/10] Creating annotated tag..."
+# 10. Create annotated tag
+echo "[10/11] Creating annotated tag..."
 git tag -a "v${TARGET_VERSION}" -m "v${TARGET_VERSION}"
 TAG_SHA=$(git rev-parse "v${TARGET_VERSION}")
 if [[ -z "$TAG_SHA" ]]; then

package/src/commands/diff.js

@@ -132,6 +132,8 @@ function formatExportDiffText(diff) {
       .map((entry) => `${entry.key}: ${formatValue(entry.left)} -> ${formatValue(entry.right)}${formatDelta(entry.delta, entry.label)}`));
   }
 
+  appendRegressionSection(lines, diff.regressions);
+
   return lines.join('\n');
 }
 
@@ -144,6 +146,18 @@ function appendChangedSection(lines, heading, items) {
   }
 }
 
+function appendRegressionSection(lines, regressions) {
+  if (!regressions || regressions.length === 0) return;
+  lines.push('');
+  lines.push(chalk.bold.red('Governance Regressions:'));
+  for (const reg of regressions) {
+    const severityTag = reg.severity === 'error'
+      ? chalk.red(`[${reg.severity}]`)
+      : chalk.yellow(`[${reg.severity}]`);
+    lines.push(`${severityTag} ${reg.id}: ${reg.message}`);
+  }
+}
+
 function listChangeItems(entry) {
   const items = [];
   if (entry.added.length > 0) {

package/src/commands/verify.js

@@ -6,6 +6,7 @@ import { validateStagedTurnResult } from '../lib/turn-result-validator.js';
 import { getTurnStagingResultPath } from '../lib/turn-paths.js';
 import { resolve } from 'node:path';
 import { loadExportArtifact, verifyExportArtifact } from '../lib/export-verifier.js';
+import { buildExportDiff, resolveExportArtifact } from '../lib/export-diff.js';
 import { verifyProtocolConformance } from '../lib/protocol-conformance.js';
 import {
   DEFAULT_VERIFICATION_REPLAY_TIMEOUT_MS,
@@ -72,6 +73,18 @@ function emitProtocolVerifyError(format, message) {
   console.log(chalk.red(`Protocol verification failed: ${message}`));
 }
 
+function emitVerifyDiffError(format, message) {
+  if (format === 'json') {
+    console.log(JSON.stringify({
+      overall: 'error',
+      message,
+    }, null, 2));
+    return;
+  }
+
+  console.log(chalk.red(`Diff verification failed: ${message}`));
+}
+
 export async function verifyExportCommand(opts) {
   const format = opts.format || 'text';
   const loaded = loadExportArtifact(opts.input || '-', process.cwd());
@@ -104,6 +117,75 @@ export async function verifyExportCommand(opts) {
   process.exit(result.ok ? 0 : 1);
 }
 
+export async function verifyDiffCommand(leftRef, rightRef, opts = {}) {
+  const format = opts.format || 'text';
+  const leftLoaded = resolveExportArtifact(leftRef);
+  if (!leftLoaded.ok) {
+    emitVerifyDiffError(format, leftLoaded.error);
+    process.exit(2);
+  }
+
+  const rightLoaded = resolveExportArtifact(rightRef);
+  if (!rightLoaded.ok) {
+    emitVerifyDiffError(format, rightLoaded.error);
+    process.exit(2);
+  }
+
+  if (leftLoaded.artifact.export_kind !== rightLoaded.artifact.export_kind) {
+    emitVerifyDiffError(
+      format,
+      `Export kinds do not match: ${leftLoaded.artifact.export_kind} vs ${rightLoaded.artifact.export_kind}`,
+    );
+    process.exit(2);
+  }
+
+  const leftVerification = verifyExportArtifact(leftLoaded.artifact);
+  const rightVerification = verifyExportArtifact(rightLoaded.artifact);
+  const leftReport = { ...leftVerification.report, input: leftLoaded.resolved_ref };
+  const rightReport = { ...rightVerification.report, input: rightLoaded.resolved_ref };
+
+  let diff = null;
+  let overall = 'pass';
+  let exitCode = 0;
+  let message = null;
+
+  if (!leftVerification.ok || !rightVerification.ok) {
+    overall = 'fail';
+    exitCode = 1;
+    message = 'Diff skipped because one or both exports failed verification.';
+  } else {
+    const diffResult = buildExportDiff(leftLoaded.artifact, rightLoaded.artifact, {
+      left_ref: leftLoaded.resolved_ref,
+      right_ref: rightLoaded.resolved_ref,
+    });
+    if (!diffResult.ok) {
+      emitVerifyDiffError(format, diffResult.error);
+      process.exit(2);
+    }
+    diff = diffResult.diff;
+    if (diff.has_regressions) {
+      overall = 'fail';
+      exitCode = 1;
+    }
+  }
+
+  const report = {
+    overall,
+    left: leftReport,
+    right: rightReport,
+    diff,
+    message,
+  };
+
+  if (format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printVerifyDiffReport(report);
+  }
+
+  process.exit(exitCode);
+}
+
 export async function verifyTurnCommand(turnId, opts = {}) {
   const context = loadProjectContext();
   if (!context) {
@@ -237,6 +319,54 @@ function printExportReport(report) {
   console.log('');
 }
 
+function printVerifyDiffReport(report) {
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Diff Verification'));
+  console.log(chalk.dim('  ' + '─'.repeat(41)));
+  console.log(chalk.dim(`  Left: ${report.left.input}`));
+  console.log(chalk.dim(`  Right: ${report.right.input}`));
+  console.log('');
+
+  const overallLabel = report.overall === 'pass'
+    ? chalk.green('PASS')
+    : report.overall === 'fail'
+      ? chalk.red('FAIL')
+      : chalk.red('ERROR');
+  console.log(`  Overall: ${overallLabel}`);
+  console.log(`  Left export: ${formatVerifyStatus(report.left.overall)}`);
+  console.log(`  Right export: ${formatVerifyStatus(report.right.overall)}`);
+
+  if (report.diff) {
+    console.log(chalk.dim(`  Diff subject: ${report.diff.subject_kind}`));
+    console.log(chalk.dim(`  Changed: ${report.diff.changed ? 'yes' : 'no'}`));
+    console.log(chalk.dim(`  Governance regressions: ${report.diff.regression_count}`));
+  }
+
+  if (report.message) {
+    console.log(chalk.yellow(`  ${report.message}`));
+  }
+
+  for (const error of report.left.errors || []) {
+    console.log(chalk.red(`    left ✗ ${error}`));
+  }
+  for (const error of report.right.errors || []) {
+    console.log(chalk.red(`    right ✗ ${error}`));
+  }
+
+  if (report.diff?.regressions?.length > 0) {
+    console.log('');
+    console.log(chalk.bold.red('  Governance Regressions'));
+    for (const regression of report.diff.regressions) {
+      const severity = regression.severity === 'error'
+        ? chalk.red(`[${regression.severity}]`)
+        : chalk.yellow(`[${regression.severity}]`);
+      console.log(`    ${severity} ${regression.id}: ${regression.message}`);
+    }
+  }
+
+  console.log('');
+}
+
 function resolveTargetTurnId(requestedTurnId, activeTurns) {
   const turnIds = Object.keys(activeTurns);
 
@@ -351,3 +481,9 @@ function formatOutcome(outcome) {
   if (outcome === 'mismatch') return chalk.red('mismatch');
   return chalk.yellow('not_reproducible');
 }
+
+function formatVerifyStatus(status) {
+  if (status === 'pass') return chalk.green('PASS');
+  if (status === 'fail') return chalk.red('FAIL');
+  return chalk.red(String(status || 'error').toUpperCase());
+}

package/src/lib/export-diff.js

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from 'fs';
 import { resolve } from 'path';
 
+const FAILED_STATUSES = new Set(['failed', 'error', 'crashed']);
+
 const RUN_EXPORT_SCALAR_FIELDS = [
   ['run_id', 'Run ID'],
   ['status', 'Status'],
@@ -119,6 +121,7 @@ function buildRunExportDiff(leftArtifact, rightArtifact, refs) {
   };
 
   const changed = hasChanged(scalar_changes, numeric_changes, list_changes);
+  const regressions = detectRunRegressions(left, right);
 
   return {
     comparison_mode: 'export',
@@ -132,6 +135,9 @@ function buildRunExportDiff(leftArtifact, rightArtifact, refs) {
     scalar_changes,
     numeric_changes,
     list_changes,
+    regressions,
+    regression_count: regressions.length,
+    has_regressions: regressions.length > 0,
   };
 }
 
@@ -153,6 +159,7 @@ function buildCoordinatorExportDiff(leftArtifact, rightArtifact, refs) {
     || repo_status_changes.some((entry) => entry.changed)
     || repo_export_changes.some((entry) => entry.changed)
     || event_type_changes.some((entry) => entry.changed);
+  const regressions = detectCoordinatorRegressions(left, right);
 
   return {
     comparison_mode: 'export',
@@ -169,17 +176,24 @@ function buildCoordinatorExportDiff(leftArtifact, rightArtifact, refs) {
     repo_status_changes,
     repo_export_changes,
     event_type_changes,
+    regressions,
+    regression_count: regressions.length,
+    has_regressions: regressions.length > 0,
   };
 }
 
 function normalizeRunExport(artifact) {
   const summary = artifact.summary || {};
   const repoDecisions = summary.repo_decisions || {};
+  const state = artifact.state || {};
+  const budgetStatus = state.budget_status || {};
+  const phaseGateStatus = state.phase_gate_status || {};
   return {
     export_kind: artifact.export_kind,
     run_id: summary.run_id || null,
     status: summary.status || null,
     phase: summary.phase || null,
+    workflow_phase_order: Array.isArray(summary.workflow_phase_order) ? summary.workflow_phase_order : null,
     project_name: artifact.project?.name || null,
     project_goal: summary.project_goal || artifact.project?.goal || null,
     provenance_trigger: summary.provenance?.trigger || null,
@@ -197,6 +211,10 @@ function normalizeRunExport(artifact) {
     retained_turn_ids: normalizeStringArray(summary.retained_turn_ids),
     active_repo_decision_ids: normalizeStringArray((repoDecisions.active || []).map((entry) => entry?.id)),
     overridden_repo_decision_ids: normalizeStringArray((repoDecisions.overridden || []).map((entry) => entry?.id)),
+    budget_warn_mode: budgetStatus.warn_mode === true,
+    budget_exhausted: budgetStatus.exhausted === true,
+    phase_gate_status: normalizeGateStatusMap(phaseGateStatus),
+    delegation_missing_decisions: normalizeDelegationMissingMap(summary.delegation_summary),
   };
 }
 
@@ -211,6 +229,7 @@ function normalizeCoordinatorExport(artifact) {
     super_run_id: summary.super_run_id || null,
     status: summary.status || null,
     phase: summary.phase || null,
+    workflow_phase_order: Array.isArray(summary.workflow_phase_order) ? summary.workflow_phase_order : null,
     project_name: artifact.coordinator?.project_name || null,
     barrier_count: toNumber(summary.barrier_count),
     history_entries: toNumber(summary.history_entries),
@@ -338,6 +357,27 @@ function normalizeNumericMap(value) {
   );
 }
 
+function normalizeDelegationMissingMap(summary) {
+  if (!summary || typeof summary !== 'object' || Array.isArray(summary)) return {};
+  const chains = Array.isArray(summary.delegation_chains) ? summary.delegation_chains : [];
+  const entries = [];
+  for (const chain of chains) {
+    const delegations = Array.isArray(chain?.delegations) ? chain.delegations : [];
+    for (const delegation of delegations) {
+      if (!delegation || typeof delegation !== 'object' || Array.isArray(delegation)) continue;
+      const delegationId = typeof delegation.delegation_id === 'string' && delegation.delegation_id.trim()
+        ? delegation.delegation_id.trim()
+        : null;
+      if (!delegationId) continue;
+      entries.push([
+        delegationId,
+        normalizeStringArray(delegation.missing_decision_ids),
+      ]);
+    }
+  }
+  return Object.fromEntries(entries.sort(([left], [right]) => left.localeCompare(right, 'en')));
+}
+
 function toNumber(value) {
   return typeof value === 'number' ? value : null;
 }
@@ -345,3 +385,224 @@ function toNumber(value) {
 function isEqual(left, right) {
   return JSON.stringify(left) === JSON.stringify(right);
 }
+
+function normalizeGateStatusMap(gateStatus) {
+  if (!gateStatus || typeof gateStatus !== 'object' || Array.isArray(gateStatus)) return {};
+  return Object.fromEntries(
+    Object.entries(gateStatus)
+      .filter(([key]) => typeof key === 'string' && key.trim().length > 0)
+      .map(([key, value]) => [key.trim(), typeof value === 'string' ? value.trim() : String(value)]),
+  );
+}
+
+const GATE_PASSED_STATES = new Set(['passed', 'approved', 'satisfied']);
+const GATE_FAILED_STATES = new Set(['failed', 'blocked', 'rejected']);
+
+function detectRunRegressions(left, right) {
+  const regressions = [];
+  let counter = 0;
+
+  // Status regression: completed/active -> failed/error/crashed
+  if (left.status && right.status && !FAILED_STATUSES.has(left.status) && FAILED_STATUSES.has(right.status)) {
+    regressions.push({
+      id: `REG-STATUS-${String(++counter).padStart(3, '0')}`,
+      category: 'status',
+      severity: 'error',
+      message: `Run status regressed from ${left.status} to ${right.status}`,
+      field: 'status',
+      left: left.status,
+      right: right.status,
+    });
+  }
+
+  // Phase regression: backward movement in workflow phase order
+  if (left.phase && right.phase === null) {
+    // Phase disappeared — information loss
+    regressions.push({
+      id: `REG-PHASE-${String(++counter).padStart(3, '0')}`,
+      category: 'phase',
+      severity: 'warning',
+      message: `Phase regressed from "${left.phase}" to null (phase information lost)`,
+      field: 'phase',
+      left: left.phase,
+      right: null,
+    });
+  } else if (left.phase && right.phase && left.phase !== right.phase) {
+    // Use right export's phase order as canonical (or left if right doesn't have one)
+    const phaseOrder = right.workflow_phase_order || left.workflow_phase_order;
+    if (Array.isArray(phaseOrder) && phaseOrder.length > 0) {
+      const leftIndex = phaseOrder.indexOf(left.phase);
+      const rightIndex = phaseOrder.indexOf(right.phase);
+      // Only flag when both phases are known and right is earlier than left
+      if (leftIndex !== -1 && rightIndex !== -1 && rightIndex < leftIndex) {
+        regressions.push({
+          id: `REG-PHASE-${String(++counter).padStart(3, '0')}`,
+          category: 'phase',
+          severity: 'warning',
+          message: `Phase moved backward from "${left.phase}" (position ${leftIndex}) to "${right.phase}" (position ${rightIndex})`,
+          field: 'phase',
+          left: left.phase,
+          right: right.phase,
+        });
+      }
+    }
+  }
+
+  // Budget warn_mode regression
+  if (left.budget_warn_mode === false && right.budget_warn_mode === true) {
+    regressions.push({
+      id: `REG-BUDGET-WARN-${String(++counter).padStart(3, '0')}`,
+      category: 'budget',
+      severity: 'warning',
+      message: 'Budget entered warn mode (over budget)',
+      field: 'budget_warn_mode',
+      left: false,
+      right: true,
+    });
+  }
+
+  // Budget exhausted regression
+  if (left.budget_exhausted === false && right.budget_exhausted === true) {
+    regressions.push({
+      id: `REG-BUDGET-EXHAUST-${String(++counter).padStart(3, '0')}`,
+      category: 'budget',
+      severity: 'error',
+      message: 'Budget exhausted',
+      field: 'budget_exhausted',
+      left: false,
+      right: true,
+    });
+  }
+
+  // Decision override count increase
+  const leftOverrides = typeof left.overridden_repo_decision_count === 'number' ? left.overridden_repo_decision_count : 0;
+  const rightOverrides = typeof right.overridden_repo_decision_count === 'number' ? right.overridden_repo_decision_count : 0;
+  if (rightOverrides > leftOverrides) {
+    regressions.push({
+      id: `REG-DECISION-OVERRIDE-${String(++counter).padStart(3, '0')}`,
+      category: 'decisions',
+      severity: 'warning',
+      message: `Repo decision overrides increased from ${leftOverrides} to ${rightOverrides}`,
+      field: 'overridden_repo_decision_count',
+      left: leftOverrides,
+      right: rightOverrides,
+    });
+  }
+
+  // Delegation contract regressions: newly missing required decisions.
+  const allDelegationIds = new Set([
+    ...Object.keys(left.delegation_missing_decisions || {}),
+    ...Object.keys(right.delegation_missing_decisions || {}),
+  ]);
+  for (const delegationId of allDelegationIds) {
+    const leftMissing = normalizeStringArray((left.delegation_missing_decisions || {})[delegationId]);
+    const rightMissing = normalizeStringArray((right.delegation_missing_decisions || {})[delegationId]);
+    const leftSet = new Set(leftMissing);
+    const newlyMissing = rightMissing.filter((decisionId) => !leftSet.has(decisionId));
+    if (newlyMissing.length > 0) {
+      regressions.push({
+        id: `REG-DELEGATION-MISSING-${String(++counter).padStart(3, '0')}`,
+        category: 'delegation',
+        severity: 'error',
+        message: `Delegation "${delegationId}" is now missing required decisions: ${newlyMissing.join(', ')}`,
+        field: `delegation_summary.${delegationId}.missing_decision_ids`,
+        left: leftMissing,
+        right: rightMissing,
+      });
+    }
+  }
+
+  // Gate regressions: passed/approved -> failed/blocked
+  const allGateIds = new Set([...Object.keys(left.phase_gate_status || {}), ...Object.keys(right.phase_gate_status || {})]);
+  for (const gateId of allGateIds) {
+    const leftGate = (left.phase_gate_status || {})[gateId] || null;
+    const rightGate = (right.phase_gate_status || {})[gateId] || null;
+    if (leftGate && rightGate && GATE_PASSED_STATES.has(leftGate) && GATE_FAILED_STATES.has(rightGate)) {
+      regressions.push({
+        id: `REG-GATE-${String(++counter).padStart(3, '0')}`,
+        category: 'gate',
+        severity: 'error',
+        message: `Gate "${gateId}" regressed from ${leftGate} to ${rightGate}`,
+        field: `phase_gate_status.${gateId}`,
+        left: leftGate,
+        right: rightGate,
+      });
+    }
+  }
+
+  return regressions;
+}
+
+function detectCoordinatorRegressions(left, right) {
+  // Start with the run-level regressions that apply to coordinator summaries
+  const regressions = detectRunRegressions(left, right);
+  let counter = regressions.length;
+
+  // Repo status regressions: child repo completed -> failed
+  const allRepoIds = new Set([...Object.keys(left.repo_run_statuses || {}), ...Object.keys(right.repo_run_statuses || {})]);
+  for (const repoId of allRepoIds) {
+    const leftStatus = (left.repo_run_statuses || {})[repoId] || null;
+    const rightStatus = (right.repo_run_statuses || {})[repoId] || null;
+    if (leftStatus && rightStatus && !FAILED_STATUSES.has(leftStatus) && FAILED_STATUSES.has(rightStatus)) {
+      regressions.push({
+        id: `REG-REPO-STATUS-${String(++counter).padStart(3, '0')}`,
+        category: 'repo_status',
+        severity: 'error',
+        message: `Child repo "${repoId}" status regressed from ${leftStatus} to ${rightStatus}`,
+        field: `repo_run_statuses.${repoId}`,
+        left: leftStatus,
+        right: rightStatus,
+      });
+    }
+  }
+
+  // Repo export regressions: ok true -> false
+  const allExportRepoIds = new Set([...Object.keys(left.repo_export_status || {}), ...Object.keys(right.repo_export_status || {})]);
+  for (const repoId of allExportRepoIds) {
+    const leftOk = (left.repo_export_status || {})[repoId];
+    const rightOk = (right.repo_export_status || {})[repoId];
+    if (leftOk === true && rightOk === false) {
+      regressions.push({
+        id: `REG-REPO-EXPORT-${String(++counter).padStart(3, '0')}`,
+        category: 'repo_export',
+        severity: 'error',
+        message: `Child repo "${repoId}" export regressed from ok to failed`,
+        field: `repo_export_status.${repoId}`,
+        left: true,
+        right: false,
+      });
+    }
+  }
+
+  // Barrier count decrease
+  const leftBarriers = typeof left.barrier_count === 'number' ? left.barrier_count : 0;
+  const rightBarriers = typeof right.barrier_count === 'number' ? right.barrier_count : 0;
+  if (leftBarriers > 0 && rightBarriers < leftBarriers) {
+    regressions.push({
+      id: `REG-BARRIER-${String(++counter).padStart(3, '0')}`,
+      category: 'barrier',
+      severity: 'warning',
+      message: `Barrier count decreased from ${leftBarriers} to ${rightBarriers}`,
+      field: 'barrier_count',
+      left: leftBarriers,
+      right: rightBarriers,
+    });
+  }
+
+  // Event loss: total_events decreased
+  const leftEvents = typeof left.total_events === 'number' ? left.total_events : 0;
+  const rightEvents = typeof right.total_events === 'number' ? right.total_events : 0;
+  if (leftEvents > 0 && rightEvents < leftEvents) {
+    regressions.push({
+      id: `REG-EVENT-LOSS-${String(++counter).padStart(3, '0')}`,
+      category: 'events',
+      severity: 'warning',
+      message: `Aggregated event count decreased from ${leftEvents} to ${rightEvents}`,
+      field: 'total_events',
+      left: leftEvents,
+      right: rightEvents,
+    });
+  }
+
+  return regressions;
+}

package/src/lib/export.js

@@ -454,6 +454,9 @@ export function buildRunExport(startDir = process.cwd()) {
         run_id: state?.run_id || null,
         status: state?.status || null,
         phase: state?.phase || null,
+        workflow_phase_order: config.routing && Object.keys(config.routing).length > 0
+          ? Object.keys(config.routing)
+          : null,
         provenance: normalizeRunProvenance(state?.provenance),
         inherited_context: state?.inherited_context || null,
         active_turn_ids: activeTurns,
@@ -640,6 +643,10 @@ export function buildCoordinatorExport(startDir = process.cwd()) {
         super_run_id: coordState?.super_run_id || null,
         status: coordState?.status || null,
         phase: coordState?.phase || null,
+        workflow_phase_order: rawConfig.routing && typeof rawConfig.routing === 'object'
+            && Object.keys(rawConfig.routing).length > 0
+          ? Object.keys(rawConfig.routing)
+          : null,
         repo_run_statuses: repoRunStatuses,
         barrier_count: barrierCount,
         history_entries: countJsonl(files, '.agentxchain/multirepo/history.jsonl'),