agentxchain 2.63.0 → 2.64.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 } from '../src/commands/verify.js';
+import { verifyExportCommand, verifyProtocolCommand, verifyTurnCommand } from '../src/commands/verify.js';
 import { kickoffCommand } from '../src/commands/kickoff.js';
 import { rebindCommand } from '../src/commands/rebind.js';
 import { branchCommand } from '../src/commands/branch.js';
@@ -86,6 +86,8 @@ import {
 } from '../src/commands/plugin.js';
 import { templateSetCommand } from '../src/commands/template-set.js';
 import { templateListCommand } from '../src/commands/template-list.js';
+import { phaseCommand } from '../src/commands/phase.js';
+import { gateCommand } from '../src/commands/gate.js';
 import { roleCommand } from '../src/commands/role.js';
 import { turnShowCommand } from '../src/commands/turn.js';
 import { templateValidateCommand } from '../src/commands/template-validate.js';
@@ -330,7 +332,14 @@ program
 
 const verifyCmd = program
   .command('verify')
-  .description('Verify protocol conformance targets');
+  .description('Verify governed turns, export artifacts, and protocol conformance targets');
+
+verifyCmd
+  .command('turn [turn_id]')
+  .description('Replay a staged turn\'s declared machine-evidence commands and compare exit codes')
+  .option('-j, --json', 'Output as JSON')
+  .option('--timeout <ms>', 'Per-command replay timeout in milliseconds', '30000')
+  .action(verifyTurnCommand);
 
 verifyCmd
   .command('protocol')
@@ -487,6 +496,39 @@ templateCmd
   .option('-j, --json', 'Output as JSON')
   .action(templateValidateCommand);
 
+const phaseCmd = program
+  .command('phase')
+  .description('Inspect governed workflow phases');
+
+phaseCmd
+  .command('list')
+  .description('List governed phases in routing order')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => phaseCommand('list', null, opts));
+
+phaseCmd
+  .command('show [phase]')
+  .description('Show one governed phase in detail')
+  .option('-j, --json', 'Output as JSON')
+  .action((phaseId, opts) => phaseCommand('show', phaseId, opts));
+
+const gateCmd = program
+  .command('gate')
+  .description('Inspect governed gate definitions');
+
+gateCmd
+  .command('list')
+  .description('List all defined gates with phase linkage and predicate summary')
+  .option('-j, --json', 'Output as JSON')
+  .action((opts) => gateCommand('list', null, opts));
+
+gateCmd
+  .command('show <gate_id>')
+  .description('Show a single gate contract, predicates, and status')
+  .option('-j, --json', 'Output as JSON')
+  .option('--evaluate', 'Live-evaluate gate predicates against current filesystem')
+  .action((gateId, opts) => gateCommand('show', gateId, opts));
+
 const roleCmd = program
   .command('role')
   .description('Inspect governed role definitions');

package/package.json

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

package/src/commands/gate.js

@@ -0,0 +1,315 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import {
+  evaluateArtifactSemantics,
+  evaluateWorkflowGateSemantics,
+  getSemanticIdForPath,
+} from '../lib/workflow-gate-semantics.js';
+import { getEffectiveGateArtifacts, hasRoleParticipationInPhase } from '../lib/gate-evaluator.js';
+
+export function gateCommand(subcommand, gateId, opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config, version } = context;
+  if (version !== 4 || config.protocol_mode !== 'governed') {
+    console.log(chalk.red('  Not a governed AgentXchain project (requires v4 config).'));
+    process.exit(1);
+  }
+
+  const gateIds = Object.keys(config.gates || {});
+  if (gateIds.length === 0) {
+    console.log(chalk.red('  No gates defined in config.'));
+    process.exit(1);
+  }
+
+  const state = loadProjectState(root, config);
+
+  if (subcommand === 'show') {
+    return showGate(gateId, { root, config, state, gateIds, opts });
+  }
+
+  return listGates({ root, config, state, gateIds, opts });
+}
+
+function findLinkedPhase(gateId, routing) {
+  for (const [phaseId, route] of Object.entries(routing || {})) {
+    if (route.exit_gate === gateId) return phaseId;
+  }
+  return null;
+}
+
+function buildGateRecord(root, config, state, gateId, evaluate) {
+  const gateDef = config.gates[gateId] || {};
+  const linkedPhase = findLinkedPhase(gateId, config.routing);
+  const effectiveArtifacts = getEffectiveGateArtifacts(config, gateDef, linkedPhase);
+  const requiresFiles = Array.isArray(gateDef.requires_files) ? gateDef.requires_files : [];
+  const requiresVerification = gateDef.requires_verification_pass === true;
+  const requiresHumanApproval = gateDef.requires_human_approval === true;
+  const status = state?.phase_gate_status?.[gateId] || null;
+
+  const lastFailure = state?.last_gate_failure?.gate_id === gateId
+    ? state.last_gate_failure
+    : null;
+
+  const record = {
+    id: gateId,
+    linked_phase: linkedPhase,
+    requires_files: requiresFiles,
+    effective_artifacts: effectiveArtifacts.map(normalizeEffectiveArtifact),
+    requires_verification_pass: requiresVerification,
+    requires_human_approval: requiresHumanApproval,
+    status,
+    last_failure: lastFailure
+      ? {
+        gate_type: lastFailure.gate_type,
+        phase: lastFailure.phase,
+        failed_at: lastFailure.failed_at,
+        reasons: lastFailure.reasons || [],
+        missing_files: lastFailure.missing_files || [],
+      }
+      : null,
+  };
+
+  if (evaluate) {
+    record.evaluation = evaluateGateSnapshot({
+      root,
+      state,
+      linkedPhase,
+      requiresVerification,
+      effectiveArtifacts,
+    });
+  }
+
+  return record;
+}
+
+function normalizeEffectiveArtifact(artifact) {
+  return {
+    path: artifact.path,
+    required: artifact.required !== false,
+    owned_by: artifact.owned_by || null,
+    legacy_semantics: artifact.useLegacySemantics ? getSemanticIdForPath(artifact.path) : null,
+    semantic_checks: Array.isArray(artifact.semanticChecks) ? artifact.semanticChecks : [],
+  };
+}
+
+function getLatestAcceptedTurnForPhase(state, phase) {
+  if (!phase || !Array.isArray(state?.history)) {
+    return null;
+  }
+
+  for (let index = state.history.length - 1; index >= 0; index--) {
+    const entry = state.history[index];
+    if (entry?.phase === phase) {
+      return entry;
+    }
+  }
+
+  return null;
+}
+
+function buildOwnershipFailure(artifact, linkedPhase) {
+  if (!artifact.owned_by) {
+    return null;
+  }
+
+  if (!linkedPhase) {
+    return `Gate is not linked to a routing phase, so ownership for "${artifact.path}" cannot be evaluated.`;
+  }
+
+  return `"${artifact.path}" requires participation from role "${artifact.owned_by}" in phase "${linkedPhase}", but no accepted turn from that role was found`;
+}
+
+function evaluateGateSnapshot({ root, state, linkedPhase, requiresVerification, effectiveArtifacts }) {
+  const missingFiles = [];
+  const semanticFailures = [];
+  const ownershipFailures = [];
+
+  const artifacts = effectiveArtifacts.map((artifact) => {
+    const exists = existsSync(join(root, artifact.path));
+    const failures = [];
+
+    if (!exists && artifact.required) {
+      const reason = `Required file missing: ${artifact.path}`;
+      missingFiles.push(artifact.path);
+      failures.push(reason);
+    }
+
+    if (exists && artifact.useLegacySemantics) {
+      const semanticCheck = evaluateWorkflowGateSemantics(root, artifact.path);
+      if (semanticCheck && !semanticCheck.ok) {
+        semanticFailures.push(semanticCheck.reason);
+        failures.push(semanticCheck.reason);
+      }
+    }
+
+    if (exists) {
+      for (const semantic of artifact.semanticChecks || []) {
+        const semanticCheck = evaluateArtifactSemantics(root, {
+          path: artifact.path,
+          semantics: semantic.semantics,
+          semantics_config: semantic.semantics_config,
+        });
+        if (semanticCheck && !semanticCheck.ok) {
+          semanticFailures.push(semanticCheck.reason);
+          failures.push(semanticCheck.reason);
+        }
+      }
+    }
+
+    const ownershipSatisfied = artifact.owned_by && linkedPhase
+      ? hasRoleParticipationInPhase(state, linkedPhase, artifact.owned_by)
+      : null;
+    if (artifact.owned_by && linkedPhase && ownershipSatisfied === false) {
+      const reason = buildOwnershipFailure(artifact, linkedPhase);
+      ownershipFailures.push(reason);
+      failures.push(reason);
+    }
+
+    return {
+      ...normalizeEffectiveArtifact(artifact),
+      exists,
+      ownership_satisfied: ownershipSatisfied,
+      failures,
+    };
+  });
+
+  const latestAcceptedTurn = getLatestAcceptedTurnForPhase(state, linkedPhase);
+  const verificationStatus = latestAcceptedTurn?.verification?.status || null;
+  const verificationPassed = verificationStatus === 'pass' || verificationStatus === 'attested_pass';
+  const reasons = [
+    ...artifacts.flatMap((artifact) => artifact.failures),
+  ];
+
+  if (requiresVerification && !verificationPassed) {
+    reasons.push(`Verification status is "${verificationStatus || 'missing'}", requires "pass" or "attested_pass"`);
+  }
+
+  return {
+    phase: linkedPhase,
+    passed: reasons.length === 0,
+    reasons,
+    missing_files: missingFiles,
+    semantic_failures: semanticFailures,
+    ownership_failures: ownershipFailures,
+    artifacts,
+    verification: {
+      required: requiresVerification,
+      source_turn_id: latestAcceptedTurn?.turn_id || null,
+      status: verificationStatus,
+      passed: requiresVerification ? verificationPassed : null,
+    },
+  };
+}
+
+function listGates({ root, config, state, gateIds, opts }) {
+  const gates = gateIds.map((id) => buildGateRecord(root, config, state, id, false));
+
+  if (opts.json) {
+    console.log(JSON.stringify({ gates }, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Gates (${gates.length}):\n`));
+  for (const gate of gates) {
+    const phase = gate.linked_phase || chalk.dim('orphaned');
+    const approval = gate.requires_human_approval ? chalk.yellow('human-approval') : 'auto';
+    const predicates = [];
+    if (gate.effective_artifacts.length > 0) predicates.push(`${gate.effective_artifacts.length} artifact${gate.effective_artifacts.length > 1 ? 's' : ''}`);
+    if (gate.requires_verification_pass) predicates.push('verification');
+    const predicateStr = predicates.length > 0 ? predicates.join(' + ') : 'none';
+    const statusStr = gate.status ? ` [${gate.status}]` : '';
+    console.log(`  ${chalk.cyan(gate.id)}${statusStr} — phase ${chalk.bold(phase)}, ${approval}, requires ${predicateStr}`);
+  }
+  console.log('');
+  console.log(chalk.dim('  Usage: agentxchain gate show <gate_id>\n'));
+}
+
+function showGate(requestedGateId, { root, config, state, gateIds, opts }) {
+  if (!requestedGateId) {
+    console.log(chalk.red('  Gate ID is required.'));
+    console.log(chalk.dim(`  Available: ${gateIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  if (!config.gates[requestedGateId]) {
+    console.log(chalk.red(`  Unknown gate: ${requestedGateId}`));
+    console.log(chalk.dim(`  Available: ${gateIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  const gate = buildGateRecord(root, config, state, requestedGateId, opts.evaluate);
+
+  if (opts.json) {
+    console.log(JSON.stringify(gate, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Gate: ${chalk.cyan(gate.id)}\n`));
+  console.log(`  Linked phase:       ${gate.linked_phase || chalk.dim('none (orphaned)')}`);
+  console.log(`  Human approval:     ${gate.requires_human_approval ? chalk.yellow('yes') : 'no'}`);
+  console.log(`  Verification:       ${gate.requires_verification_pass ? 'required' : 'not required'}`);
+  if (gate.status) {
+    const statusColor = gate.status === 'passed' ? chalk.green : gate.status === 'failed' ? chalk.red : chalk.yellow;
+    console.log(`  Status:             ${statusColor(gate.status)}`);
+  }
+  if (gate.evaluation) {
+    console.log(`  Evaluation:         ${gate.evaluation.passed ? chalk.green('pass') : chalk.red('fail')}`);
+  }
+  console.log('');
+
+  if (gate.effective_artifacts.length === 0) {
+    console.log(`  ${chalk.dim('Effective artifacts:')} none\n`);
+  } else {
+    console.log(`  ${chalk.dim('Effective artifacts:')}`);
+    const evaluatedArtifacts = gate.evaluation?.artifacts || [];
+    for (const artifact of gate.effective_artifacts) {
+      const artifactEval = evaluatedArtifacts.find((entry) => entry.path === artifact.path);
+      const icon = artifactEval
+        ? artifactEval.failures.length === 0
+          ? chalk.green('\u2713')
+          : chalk.red('\u2717')
+        : chalk.dim('-');
+      const owner = artifact.owned_by || 'none';
+      const semantics = [
+        artifact.legacy_semantics,
+        ...artifact.semantic_checks.map((entry) => entry.semantics),
+      ].filter(Boolean);
+      console.log(`    ${icon} ${artifact.path} [${artifact.required ? 'required' : 'optional'}] [owner: ${owner}] [semantics: ${semantics.length > 0 ? semantics.join(', ') : 'none'}]`);
+      if (artifactEval?.failures.length) {
+        for (const failure of artifactEval.failures) {
+          console.log(`      ${chalk.dim(`- ${failure}`)}`);
+        }
+      }
+    }
+    console.log('');
+  }
+
+  if (gate.evaluation && gate.requires_verification_pass) {
+    const vpIcon = gate.evaluation.verification.passed ? chalk.green('\u2713') : chalk.red('\u2717');
+    const source = gate.evaluation.verification.source_turn_id
+      ? ` (${gate.evaluation.verification.source_turn_id})`
+      : '';
+    console.log(`  Verification pass: ${vpIcon} ${gate.evaluation.verification.passed ? 'yes' : 'no'}${source}\n`);
+  }
+
+  if (gate.last_failure) {
+    console.log(chalk.dim('  Last failure:'));
+    console.log(`    Type:    ${gate.last_failure.gate_type}`);
+    console.log(`    Phase:   ${gate.last_failure.phase}`);
+    console.log(`    At:      ${gate.last_failure.failed_at}`);
+    if (gate.last_failure.reasons.length > 0) {
+      console.log(`    Reasons: ${gate.last_failure.reasons.join('; ')}`);
+    }
+    if (gate.last_failure.missing_files.length > 0) {
+      console.log(`    Missing: ${gate.last_failure.missing_files.join(', ')}`);
+    }
+    console.log('');
+  }
+}

package/src/commands/phase.js

@@ -0,0 +1,159 @@
+import { existsSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { getNextPhase } from '../lib/gate-evaluator.js';
+import { getMaxConcurrentTurns } from '../lib/normalized-config.js';
+
+export function phaseCommand(subcommand, phaseId, opts) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('  No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(1);
+  }
+
+  const { root, config, rawConfig, version } = context;
+  if (version !== 4 || config.protocol_mode !== 'governed') {
+    console.log(chalk.red('  Not a governed AgentXchain project (requires v4 config).'));
+    process.exit(1);
+  }
+
+  const phaseIds = Object.keys(config.routing || {});
+  if (phaseIds.length === 0) {
+    console.log(chalk.red('  No governed phases are defined in routing.'));
+    process.exit(1);
+  }
+
+  const state = loadProjectState(root, config);
+
+  if (subcommand === 'show') {
+    return showPhase(phaseId, { root, config, rawConfig, state, phaseIds, opts });
+  }
+
+  return listPhases({ root, config, rawConfig, state, phaseIds, opts });
+}
+
+function listPhases({ root, config, rawConfig, state, phaseIds, opts }) {
+  const phases = phaseIds.map((phaseId) => buildPhaseRecord(root, config, rawConfig, state, phaseId));
+
+  if (opts.json) {
+    console.log(JSON.stringify({
+      current_phase: state?.phase || null,
+      phases,
+    }, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Phases (${phases.length}):\n`));
+  for (const phase of phases) {
+    const current = phase.is_current ? chalk.green(' [current]') : '';
+    const entry = phase.entry_role || 'none';
+    const gate = phase.exit_gate || 'open';
+    const next = phase.next_phase || 'final';
+    console.log(`  ${chalk.cyan(phase.id)}${current} — entry ${chalk.bold(entry)}, gate ${gate}, next ${next}, artifacts ${phase.workflow_kit.artifacts.length}`);
+  }
+  console.log('');
+  console.log(chalk.dim('  Usage: agentxchain phase show <phase>\n'));
+}
+
+function showPhase(requestedPhaseId, { root, config, rawConfig, state, phaseIds, opts }) {
+  const phaseId = requestedPhaseId || state?.phase || phaseIds[0];
+  if (!config.routing?.[phaseId]) {
+    console.log(chalk.red(`  Unknown phase: ${phaseId}`));
+    console.log(chalk.dim(`  Available: ${phaseIds.join(', ')}`));
+    process.exit(1);
+  }
+
+  const phase = buildPhaseRecord(root, config, rawConfig, state, phaseId);
+
+  if (opts.json) {
+    console.log(JSON.stringify(phase, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold(`\n  Phase: ${chalk.cyan(phase.id)}${phase.is_current ? chalk.green(' [current]') : ''}\n`));
+  console.log(`  Entry role:        ${phase.entry_role || chalk.dim('none')}`);
+  console.log(`  Exit gate:         ${phase.exit_gate || chalk.dim('open')}`);
+  if (phase.exit_gate_status) {
+    console.log(`  Gate status:       ${phase.exit_gate_status}`);
+  }
+  console.log(`  Next phase:        ${phase.next_phase || chalk.dim('final')}`);
+  console.log(`  Next roles:        ${phase.allowed_next_roles.length > 0 ? phase.allowed_next_roles.join(', ') : chalk.dim('none')}`);
+  console.log(`  Max turns:         ${phase.max_concurrent_turns}`);
+  if (phase.timeout_minutes != null || phase.timeout_action) {
+    console.log(`  Timeout override:  ${phase.timeout_minutes != null ? `${phase.timeout_minutes}m` : chalk.dim('default')} / ${phase.timeout_action || chalk.dim('default')}`);
+  }
+  console.log(`  Workflow source:   ${phase.workflow_kit.source}`);
+  if (phase.workflow_kit.template) {
+    console.log(`  Workflow template: ${phase.workflow_kit.template}`);
+  }
+  console.log('');
+
+  if (phase.workflow_kit.artifacts.length === 0) {
+    console.log(`  ${chalk.dim('Artifacts:')} none declared\n`);
+    return;
+  }
+
+  console.log(`  ${chalk.dim('Artifacts:')}`);
+  for (const artifact of phase.workflow_kit.artifacts) {
+    const icon = artifact.exists ? chalk.green('✓') : (artifact.required ? chalk.red('✗') : chalk.yellow('○'));
+    const ownerLabel = artifact.owner_resolution === 'explicit'
+      ? artifact.owned_by
+      : artifact.owner_resolution === 'entry_role'
+        ? `${chalk.dim(artifact.owned_by + ' (hint, not enforced)')}`
+        : 'none';
+    const semantics = artifact.semantics || 'none';
+    const required = artifact.required ? 'required' : 'optional';
+    console.log(`    ${icon} ${artifact.path} [${required}] [owner: ${ownerLabel}] [semantics: ${semantics}]`);
+  }
+  if (phase.workflow_kit.artifacts.some((artifact) => artifact.owner_resolution === 'entry_role')) {
+    console.log(`    ${chalk.dim('Hint: inferred ownership from entry_role is display-only. Only explicit owned_by is enforced at gate evaluation.')}`);
+  }
+  console.log('');
+}
+
+function buildPhaseRecord(root, config, rawConfig, state, phaseId) {
+  const route = config.routing?.[phaseId] || {};
+  const normalizedPhaseKit = config.workflow_kit?.phases?.[phaseId] || null;
+  const rawWorkflowKit = rawConfig.workflow_kit;
+  const rawPhaseKit = rawWorkflowKit?.phases?.[phaseId] || null;
+  const hasExplicitWorkflowKit = rawWorkflowKit !== undefined && rawWorkflowKit !== null;
+
+  const workflowSource = !hasExplicitWorkflowKit
+    ? 'default'
+    : rawPhaseKit
+      ? 'explicit'
+      : 'not_declared';
+
+  const artifacts = (normalizedPhaseKit?.artifacts || []).map((artifact) => {
+    const hasExplicitOwner = typeof artifact.owned_by === 'string' && artifact.owned_by.length > 0;
+    const ownedBy = hasExplicitOwner ? artifact.owned_by : (route.entry_role || null);
+    return {
+      path: artifact.path,
+      required: artifact.required !== false,
+      semantics: artifact.semantics || null,
+      owned_by: ownedBy,
+      owner_resolution: hasExplicitOwner ? 'explicit' : (ownedBy ? 'entry_role' : 'unowned'),
+      ownership_enforced: hasExplicitOwner,
+      exists: existsSync(join(root, artifact.path)),
+    };
+  });
+
+  return {
+    id: phaseId,
+    is_current: state?.phase === phaseId,
+    entry_role: route.entry_role || null,
+    exit_gate: route.exit_gate || null,
+    exit_gate_status: route.exit_gate ? (state?.phase_gate_status?.[route.exit_gate] || null) : null,
+    next_phase: getNextPhase(phaseId, config.routing || {}),
+    allowed_next_roles: Array.isArray(route.allowed_next_roles) ? route.allowed_next_roles : [],
+    timeout_minutes: typeof route.timeout_minutes === 'number' ? route.timeout_minutes : null,
+    timeout_action: typeof route.timeout_action === 'string' ? route.timeout_action : null,
+    max_concurrent_turns: getMaxConcurrentTurns(config, phaseId),
+    workflow_kit: {
+      source: workflowSource,
+      template: typeof rawPhaseKit?.template === 'string' ? rawPhaseKit.template : null,
+      artifacts,
+    },
+  };
+}

package/src/commands/verify.js

@@ -1,4 +1,10 @@
 import chalk from 'chalk';
+import { spawnSync } from 'node:child_process';
+import { loadProjectContext, loadProjectState } from '../lib/config.js';
+import { getActiveTurns } from '../lib/governed-state.js';
+import { normalizeVerification } from '../lib/repo-observer.js';
+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 { verifyProtocolConformance } from '../lib/protocol-conformance.js';
@@ -95,6 +101,85 @@ export async function verifyExportCommand(opts) {
   process.exit(result.ok ? 0 : 1);
 }
 
+export async function verifyTurnCommand(turnId, opts = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
+    process.exit(2);
+  }
+
+  if (context.config.protocol_mode !== 'governed' || context.version !== 4) {
+    console.log(chalk.red('verify turn is only available in governed v4 projects.'));
+    process.exit(2);
+  }
+
+  const timeoutMs = Number.parseInt(String(opts.timeout || '30000'), 10);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) {
+    console.log(chalk.red('verify turn requires a positive integer --timeout in milliseconds.'));
+    process.exit(2);
+  }
+
+  const { root, config } = context;
+  const state = loadProjectState(root, config);
+  const activeTurns = getActiveTurns(state);
+  const selectedTurnId = resolveTargetTurnId(turnId, activeTurns);
+  const selectedTurn = activeTurns[selectedTurnId];
+  const stagingPath = getTurnStagingResultPath(selectedTurnId);
+  const validationState = {
+    ...state,
+    active_turns: {
+      [selectedTurnId]: selectedTurn,
+    },
+  };
+  const validation = validateStagedTurnResult(root, validationState, config, { stagingPath });
+
+  if (!validation.ok) {
+    emitTurnValidationFailure(validation, opts.json);
+    process.exit(1);
+  }
+
+  const turnResult = validation.turnResult;
+  const runtimeType = config.runtimes?.[selectedTurn.runtime_id]?.type || 'manual';
+  const declaredStatus = turnResult.verification?.status || 'skipped';
+  const normalizedStatus = normalizeVerification(turnResult.verification, runtimeType).status;
+  const machineEvidence = Array.isArray(turnResult.verification?.machine_evidence)
+    ? turnResult.verification.machine_evidence
+    : [];
+
+  const payload = {
+    turn_id: selectedTurnId,
+    role: selectedTurn.assigned_role,
+    runtime_id: selectedTurn.runtime_id,
+    runtime_type: runtimeType,
+    staging_path: stagingPath,
+    declared_status: declaredStatus,
+    normalized_status: normalizedStatus,
+    validation: {
+      ok: true,
+      warnings: validation.warnings || [],
+    },
+    timeout_ms: timeoutMs,
+    overall: 'not_reproducible',
+    replayed_commands: 0,
+    matched_commands: 0,
+    commands: [],
+  };
+
+  if (machineEvidence.length === 0) {
+    payload.reason = 'No verification.machine_evidence commands were declared. commands/evidence_summary are not executable proof.';
+    emitTurnVerification(payload, opts.json);
+    process.exit(1);
+  }
+
+  payload.commands = machineEvidence.map((entry, index) => replayEvidenceCommand(root, entry, index, timeoutMs));
+  payload.replayed_commands = payload.commands.length;
+  payload.matched_commands = payload.commands.filter((entry) => entry.matched).length;
+  payload.overall = payload.commands.every((entry) => entry.matched) ? 'match' : 'mismatch';
+
+  emitTurnVerification(payload, opts.json);
+  process.exit(payload.overall === 'match' ? 0 : 1);
+}
+
 function printProtocolReport(report) {
   console.log('');
   console.log(chalk.bold('  AgentXchain Protocol Conformance'));
@@ -162,3 +247,143 @@ function printExportReport(report) {
 
   console.log('');
 }
+
+function resolveTargetTurnId(requestedTurnId, activeTurns) {
+  const turnIds = Object.keys(activeTurns);
+
+  if (requestedTurnId) {
+    if (!activeTurns[requestedTurnId]) {
+      console.log(chalk.red(`Unknown active turn: ${requestedTurnId}`));
+      if (turnIds.length > 0) {
+        console.log(chalk.dim(`  Available: ${turnIds.join(', ')}`));
+      }
+      process.exit(2);
+    }
+    return requestedTurnId;
+  }
+
+  if (turnIds.length === 0) {
+    console.log(chalk.red('No active turn found.'));
+    process.exit(2);
+  }
+
+  if (turnIds.length > 1) {
+    console.log(chalk.red('Multiple active turns are present. Re-run with `agentxchain verify turn <turn_id>`.'));
+    console.log(chalk.dim(`  Available: ${turnIds.join(', ')}`));
+    process.exit(2);
+  }
+
+  return turnIds[0];
+}
+
+function emitTurnValidationFailure(validation, jsonMode) {
+  const payload = {
+    overall: 'validation_failed',
+    validation: {
+      ok: false,
+      stage: validation.stage,
+      error_class: validation.error_class,
+      errors: validation.errors || [],
+      warnings: validation.warnings || [],
+    },
+  };
+
+  if (jsonMode) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.red('  Turn Verification Blocked By Validation'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Stage:')}    ${validation.stage || 'unknown'}`);
+  console.log(`  ${chalk.dim('Reason:')}   ${validation.error_class || 'validation_error'}`);
+  for (const error of validation.errors || []) {
+    console.log(`  ${chalk.dim('Error:')}    ${error}`);
+  }
+  if ((validation.warnings || []).length > 0) {
+    console.log('');
+    for (const warning of validation.warnings || []) {
+      console.log(`  ${chalk.dim('Warning:')}  ${warning}`);
+    }
+  }
+  console.log('');
+}
+
+function replayEvidenceCommand(root, entry, index, timeoutMs) {
+  const result = spawnSync(entry.command, {
+    cwd: root,
+    encoding: 'utf8',
+    shell: true,
+    timeout: timeoutMs,
+    maxBuffer: 1024 * 1024,
+  });
+
+  const timedOut = result.error?.code === 'ETIMEDOUT';
+  const actualExitCode = Number.isInteger(result.status) ? result.status : null;
+  const errorMessage = result.error?.message || null;
+
+  return {
+    index,
+    command: entry.command,
+    declared_exit_code: entry.exit_code,
+    actual_exit_code: actualExitCode,
+    matched: actualExitCode === entry.exit_code,
+    timed_out: timedOut,
+    signal: result.signal || null,
+    error: errorMessage,
+  };
+}
+
+function emitTurnVerification(payload, jsonMode) {
+  if (jsonMode) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold(`  Verify Turn: ${chalk.cyan(payload.turn_id)}`));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(`  ${chalk.dim('Role:')}       ${payload.role}`);
+  console.log(`  ${chalk.dim('Runtime:')}    ${payload.runtime_id} (${payload.runtime_type})`);
+  console.log(`  ${chalk.dim('Staging:')}    ${payload.staging_path}`);
+  console.log(`  ${chalk.dim('Declared:')}   ${payload.declared_status}`);
+  console.log(`  ${chalk.dim('Normalized:')} ${payload.normalized_status}`);
+  console.log(`  ${chalk.dim('Outcome:')}    ${formatOutcome(payload.overall)}`);
+
+  for (const warning of payload.validation?.warnings || []) {
+    console.log(`  ${chalk.dim('Warning:')}    ${warning}`);
+  }
+
+  if (payload.reason) {
+    console.log(`  ${chalk.dim('Reason:')}     ${payload.reason}`);
+    console.log('');
+    return;
+  }
+
+  console.log('');
+  for (const command of payload.commands || []) {
+    const marker = command.matched ? chalk.green('match') : chalk.red('mismatch');
+    console.log(`  [${marker}] ${command.command}`);
+    console.log(`    declared=${command.declared_exit_code} actual=${command.actual_exit_code == null ? 'null' : command.actual_exit_code}`);
+    if (command.signal) {
+      console.log(`    signal=${command.signal}`);
+    }
+    if (command.timed_out) {
+      console.log('    timed_out=true');
+    }
+    if (command.error) {
+      console.log(`    error=${command.error}`);
+    }
+  }
+
+  console.log('');
+  console.log(chalk.dim('  Replay uses the current workspace and shell environment. It verifies declared exit-code reproducibility, not historical stdout/stderr identity.'));
+  console.log('');
+}
+
+function formatOutcome(outcome) {
+  if (outcome === 'match') return chalk.green('match');
+  if (outcome === 'mismatch') return chalk.red('mismatch');
+  return chalk.yellow('not_reproducible');
+}

package/src/lib/gate-evaluator.js

@@ -30,7 +30,7 @@ function getWorkflowArtifactsForPhase(config, phase) {
   return Array.isArray(artifacts) ? artifacts : [];
 }
 
-function buildEffectiveGateArtifacts(config, gateDef, phase) {
+export function getEffectiveGateArtifacts(config, gateDef, phase) {
   const byPath = new Map();
 
   if (Array.isArray(gateDef?.requires_files)) {
@@ -92,7 +92,7 @@ function prefixSemanticReason(filePath, reason) {
   return `${filePath}: ${reason}`;
 }
 
-function hasRoleParticipationInPhase(state, phase, roleId) {
+export function hasRoleParticipationInPhase(state, phase, roleId) {
   const history = state?.history;
   if (!Array.isArray(history)) {
     return false;
@@ -104,7 +104,7 @@ function hasRoleParticipationInPhase(state, phase, roleId) {
 
 function evaluateGateArtifacts({ root, config, gateDef, phase, result, state }) {
   const failures = [];
-  const artifacts = buildEffectiveGateArtifacts(config, gateDef, phase);
+  const artifacts = getEffectiveGateArtifacts(config, gateDef, phase);
 
   for (const artifact of artifacts) {
     const absPath = join(root, artifact.path);