agentxchain 2.157.0 → 2.158.0

package/bin/agentxchain.js

@@ -124,6 +124,8 @@ import { benchmarkCommand } from '../src/commands/benchmark.js';
 import { benchmarkWorkloadsCommand } from '../src/commands/benchmark-workloads.js';
 import { historyCommand } from '../src/commands/history.js';
 import { decisionsCommand } from '../src/commands/decisions.js';
+import { shipStatusCommand } from '../src/commands/ship-status.js';
+import { attentionCommand } from '../src/commands/attention.js';
 import { diffCommand } from '../src/commands/diff.js';
 import { eventsCommand } from '../src/commands/events.js';
 import { connectorCapabilitiesCommand, connectorCheckCommand, connectorValidateCommand } from '../src/commands/connector.js';
@@ -420,6 +422,22 @@ program
   .option('-d, --dir <path>', 'Project directory')
   .action(decisionsCommand);
 
+program
+  .command('ship-status')
+  .description('Evaluate whether the current project is ready to ship')
+  .option('-j, --json', 'Machine-readable JSON output')
+  .option('-v, --verbose', 'Per-dimension detail breakdown')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(shipStatusCommand);
+
+program
+  .command('attention')
+  .description('Show the cross-run human-decision queue — what needs you, and nothing else (govern by exception)')
+  .option('-j, --json', 'Machine-readable JSON output (full HumanAttentionReport)')
+  .option('-a, --all', 'Include informational/non-blocking items (e.g. pending approved intents)')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(attentionCommand);
+
 program
   .command('diff <left_ref> <right_ref>')
   .description('Compare two recorded governed runs or two export artifacts')

package/package.json

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

package/src/commands/attention.js

@@ -0,0 +1,66 @@
+/**
+ * CLI command: agentxchain attention
+ *
+ * Answers "what needs MY attention right now — and nothing else?" by composing the
+ * cross-category human-decision queue into a single HumanAttentionReport. All evaluation
+ * logic lives in lib/human-attention.js — this command is presentation only
+ * (Architecture Invariant #6).
+ *
+ * It is a status surface, not a gate: it exits 0 in BOTH the clear and attention states.
+ * When the queue is empty it prints "Nothing needs your attention." — the operational
+ * proof that the human can step back and let governed autonomy run (VISION.md:51).
+ */
+
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import { evaluateHumanAttention } from '../lib/human-attention.js';
+
+export async function attentionCommand(opts) {
+  const dir = opts.dir ? resolve(opts.dir) : process.cwd();
+  const root = findProjectRoot(dir);
+  if (!root) {
+    console.error(chalk.red('No agentxchain project found. Run "agentxchain init" first.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const report = evaluateHumanAttention(root);
+
+  if (opts.json) {
+    // --json always emits the full, schema-valid HumanAttentionReport; exit 0 in both states.
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  if (report.overall === 'clear') {
+    console.log(chalk.green('Nothing needs your attention.'));
+    return;
+  }
+
+  // Default view surfaces blocking + escalation items first; informational pending-intent
+  // items are summarized as a count unless --all is passed.
+  const visible = opts.all ? report.items : report.items.filter((item) => item.blocking);
+  const hidden = report.items.length - visible.length;
+
+  console.log(
+    `\n${chalk.bold('Attention needed')}: ${report.items_count} `
+    + `item${report.items_count === 1 ? '' : 's'} (${report.blocking_count} blocking)`,
+  );
+
+  visible.forEach((item, idx) => {
+    const tag = chalk.cyan(String(item.category).padEnd(16));
+    const run = item.run_id ? `${chalk.dim(item.run_id)} ` : '';
+    console.log(`  [${idx + 1}] ${tag} ${run}${item.summary}`);
+    console.log(`      ${chalk.dim('→')} ${item.action_hint}`);
+  });
+
+  if (hidden > 0) {
+    console.log(
+      chalk.dim(`  (+${hidden} informational item${hidden === 1 ? '' : 's'} — run with --all to show)`),
+    );
+  }
+
+  console.log('');
+  // Status surface, not a gate — no non-zero exit even in the attention state.
+}

package/src/commands/ship-status.js

@@ -0,0 +1,104 @@
+/**
+ * CLI command: agentxchain ship-status
+ *
+ * Answers "is this ready to ship?" by composing five evidence dimensions into a
+ * single ShipStatusReport. All evaluation logic lives in lib/ship-status.js — this
+ * command is presentation only (Architecture Invariant #5).
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import { COORDINATOR_CONFIG_FILE } from '../lib/coordinator-config.js';
+import { evaluateShipStatus, evaluateCoordinatorShipStatus } from '../lib/ship-status.js';
+
+function statusIcon(status) {
+  if (status === 'pass') return chalk.green('✓');
+  if (status === 'fail') return chalk.red('✗');
+  return chalk.yellow('?');
+}
+
+function overallLabel(overall) {
+  if (overall === 'pass') return chalk.green.bold('YES');
+  if (overall === 'fail') return chalk.red.bold('NO');
+  return chalk.yellow.bold('PENDING');
+}
+
+function countPassed(report) {
+  return (report.dimensions || []).filter((d) => d.status === 'pass').length;
+}
+
+function printDimensions(dimensions, indent) {
+  for (const dim of dimensions || []) {
+    console.log(`${indent}${statusIcon(dim.status)}  ${dim.name}: ${dim.detail}`);
+  }
+}
+
+function printSingle(report, opts) {
+  const passed = countPassed(report);
+  const total = (report.dimensions || []).length;
+  const blocking = report.blocking_reasons || [];
+  const suffix = blocking.length ? `, ${blocking.length} blocking` : '';
+  console.log(`\nShip Status: ${overallLabel(report.overall)} (${passed}/${total} dimensions pass${suffix})`);
+
+  if (opts.verbose) {
+    console.log('');
+    printDimensions(report.dimensions, '  ');
+  } else {
+    for (const reason of blocking) {
+      console.log(`  ${chalk.dim('-')} ${reason}`);
+    }
+  }
+  console.log('');
+}
+
+export async function shipStatusCommand(opts) {
+  const dir = opts.dir ? resolve(opts.dir) : process.cwd();
+  const coordinatorConfigPath = join(dir, COORDINATOR_CONFIG_FILE);
+
+  let report;
+  let isCoordinator = false;
+
+  if (existsSync(coordinatorConfigPath)) {
+    isCoordinator = true;
+    report = evaluateCoordinatorShipStatus(dir);
+  } else {
+    const root = findProjectRoot(dir);
+    if (!root) {
+      console.error(chalk.red('No agentxchain project found. Run "agentxchain init" first.'));
+      process.exitCode = 1;
+      return;
+    }
+    report = evaluateShipStatus(root);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (isCoordinator) {
+    const blocking = report.blocking_repos || [];
+    const total = (report.repos || []).length;
+    const shippable = total - blocking.length;
+    console.log(`\nCoordinator Ship Status: ${overallLabel(report.overall)} (${shippable}/${total} repos shippable)`);
+    for (const entry of report.repos || []) {
+      const passed = countPassed(entry.ship_status);
+      const dimTotal = (entry.ship_status.dimensions || []).length;
+      console.log(`\n  ${chalk.bold(entry.repo_id)}: ${overallLabel(entry.ship_status.overall)} (${passed}/${dimTotal})`);
+      if (opts.verbose) {
+        printDimensions(entry.ship_status.dimensions, '    ');
+      } else {
+        for (const reason of entry.ship_status.blocking_reasons || []) {
+          console.log(`    ${chalk.dim('-')} ${reason}`);
+        }
+      }
+    }
+    console.log('');
+  } else {
+    printSingle(report, opts);
+  }
+
+  // Non-zero exit when not shippable (useful for CI gating).
+  if (report.overall === 'fail') {
+    process.exitCode = 1;
+  }
+}

package/src/lib/dispatch-bundle.js

@@ -471,6 +471,18 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('');
   }
 
+  // Single-shot execution model — prevents ghost turns from async / background-wait patterns.
+  lines.push('## Single-Shot Execution (read carefully)');
+  lines.push('');
+  lines.push('You run as a **single, non-interactive `--print` subprocess**. You get exactly ONE invocation with no "later": there is no async wake-up, no second message, and nothing will notify you after you stop responding. The moment you end your turn the subprocess exits — if you have not written your turn result by then, the entire turn is **discarded as a ghost** (no result, wasted run).');
+  lines.push('');
+  lines.push('Therefore:');
+  lines.push('- Do ALL work **synchronously** within this one turn. Run every command to completion in the foreground and read its output inline before continuing.');
+  lines.push('- **NEVER** start a background job and then wait for it. Do not use `ScheduleWakeup`; do not start a `Monitor` or `tail -f` and wait for events; do not background a process with `&` and poll for a notification; do not defer any conclusion to "after the suite/build finishes". You will not be re-invoked to finish.');
+  lines.push('- If you need a long command or test suite result, run it **blocking in the foreground** (e.g. `npm test`) and wait for it to return in-line — the per-turn timeout is generous, so budget your time for it.');
+  lines.push('- Writing the structured turn result below is your **final action**: gather every piece of evidence first, then write the result before you finish.');
+  lines.push('');
+
   // Output format with complete JSON template
   lines.push('## Required Output');
   lines.push('');

package/src/lib/human-attention.js

@@ -0,0 +1,381 @@
+/**
+ * M15: Govern Without Micromanaging — Human Attention Surface (VISION.md:51)
+ *
+ * Closes the final "Why This Must Exist" pain bullet: "humans lose the ability to
+ * govern without micromanaging." The triggers that legitimately require a human are
+ * real but scattered — pending phase/completion approvals live in `state.blocked_on`,
+ * open escalations in `human-escalations.jsonl`, approved-but-undispatched work in the
+ * intake system, credentialed gates in `approval-policy`, and budget/policy halts back
+ * in `state.blocked_on`. To govern today the operator must poll every surface
+ * (micromanage) or trust blindly (forbidden by VISION.md:220).
+ *
+ * This module is a govern-by-exception COMPOSITION layer (Architecture Invariant #1):
+ * it aggregates those already-existing signals into a single prioritized
+ * `HumanAttentionReport`, reaching each one through its public surface. It NEVER
+ * reimplements escalation, approval, or intake logic, and it is strictly READ-ONLY
+ * (Invariant #2) — it never mutates state, escalations, intents, artifacts, or config.
+ * Every category is evaluated independently; a failure or empty result in one never
+ * suppresses another (Invariant #4).
+ *
+ * The defining property: when no human decision is pending the queue is EMPTY and
+ * `overall === 'clear'` (Invariant #3). That empty state is the operational proof that
+ * the human can step back and let governed autonomy run.
+ *
+ * Public surface:
+ *   evaluateHumanAttention(repoDir)      — live single-repo cross-category queue
+ *   buildHumanAttentionSummary(artifact) — compact summary embedded in a governance report
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { loadProjectContext } from './config.js';
+import { readHumanEscalations } from './human-escalations.js';
+import { findPendingApprovedIntents } from './intake.js';
+import { isCredentialedExitGate } from './approval-policy.js';
+
+const DEFAULT_STATE_PATH = '.agentxchain/state.json';
+
+// Category ids surfaced by the attention queue.
+export const HUMAN_ATTENTION_CATEGORIES = {
+  CREDENTIALED_GATE: 'credentialed_gate',
+  ESCALATION: 'escalation',
+  APPROVAL: 'approval',
+  MANUAL_ACTION: 'manual_action',
+  BUDGET_POLICY: 'budget_policy',
+  PENDING_INTENT: 'pending_intent',
+};
+
+// Deterministic priority key (lower = more urgent). Blocking categories are all < 100
+// and informational categories >= 100, which — combined with the blocking-first sort —
+// guarantees every blocking item precedes every non-blocking item (Ordering contract).
+// Within the blocking tier: credentialed-gate and escalation outrank pending-approval,
+// which outranks budget/policy; manual_action (gate_action/human blocks) sits just below
+// approval. Pending-intent is the only informational tier.
+const CATEGORY_PRIORITY = {
+  credentialed_gate: 10,
+  escalation: 20,
+  approval: 30,
+  manual_action: 35,
+  budget_policy: 40,
+  pending_intent: 100,
+};
+
+/**
+ * Read the governed state file WITHOUT writeback (loadProjectState may normalize and
+ * persist, which would violate the read-only invariant). Mirrors ship-status.js.
+ */
+function readGovernedStateReadOnly(root, config) {
+  const rel = config?.files?.state || DEFAULT_STATE_PATH;
+  const filePath = join(root, rel);
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function blockedOnString(state) {
+  return typeof state?.blocked_on === 'string' ? state.blocked_on : null;
+}
+
+// ── category evaluators (pure; exported for focused unit testing) ─────────────
+
+/**
+ * Identify the gate (if any) currently awaiting human approval, from the blocked
+ * state or a recorded pending transition / completion.
+ */
+function pendingApprovalGate(state) {
+  if (!state) return null;
+  const blockedOn = blockedOnString(state);
+  if (blockedOn && blockedOn.startsWith('human_approval:')) {
+    return blockedOn.slice('human_approval:'.length) || null;
+  }
+  if (state.pending_run_completion?.gate) return state.pending_run_completion.gate;
+  if (state.pending_phase_transition?.gate) return state.pending_phase_transition.gate;
+  return null;
+}
+
+function approvalActionHint(state) {
+  if (state?.pending_run_completion) return 'agentxchain approve-completion';
+  return 'agentxchain approve-transition';
+}
+
+/**
+ * Categories 1 & 4 — Pending approvals (critical transitions / completion) and the
+ * credentialed-gate refinement. A pending human-approval gate is a single decision;
+ * it is classified as `credentialed_gate` when the current phase's exit gate is
+ * credentialed (VISION.md:36 — gates guarding irreversible or credentialed actions),
+ * otherwise as `approval`. Mutually exclusive, so the same decision is never
+ * double-counted while still honouring the ordering contract (credentialed outranks
+ * plain approval). Composes approval-policy.js `isCredentialedExitGate`.
+ */
+export function evaluatePendingApprovalCategory(state, config) {
+  const gate = pendingApprovalGate(state);
+  if (!gate) return [];
+
+  const runId = state?.run_id || null;
+  const phase = state?.phase || null;
+  const phaseSuffix = phase ? ` (phase "${phase}")` : '';
+  const hint = approvalActionHint(state);
+
+  let credentialed = false;
+  try {
+    credentialed = isCredentialedExitGate(config, phase);
+  } catch {
+    credentialed = false;
+  }
+
+  if (credentialed) {
+    return [{
+      category: HUMAN_ATTENTION_CATEGORIES.CREDENTIALED_GATE,
+      priority: CATEGORY_PRIORITY.credentialed_gate,
+      blocking: true,
+      run_id: runId,
+      summary: `Credentialed gate "${gate}" requires human approval${phaseSuffix}.`,
+      action_hint: hint,
+    }];
+  }
+
+  return [{
+    category: HUMAN_ATTENTION_CATEGORIES.APPROVAL,
+    priority: CATEGORY_PRIORITY.approval,
+    blocking: true,
+    run_id: runId,
+    summary: `Gate "${gate}" awaits human approval${phaseSuffix}.`,
+    action_hint: hint,
+  }];
+}
+
+/**
+ * Category 2 — Open human escalations (intervene during escalation). Composes
+ * human-escalations.js `readHumanEscalations`; surfaces every record whose status is
+ * `open`. Each carries its own `resolution_command` action hint.
+ */
+export function evaluateEscalationCategory(escalations) {
+  return (escalations || [])
+    .filter((record) => record && record.status === 'open')
+    .map((record) => {
+      const service = record.service ? ` (${record.service})` : '';
+      const what = record.detail || record.action || record.typed_reason || record.escalation_id;
+      return {
+        category: HUMAN_ATTENTION_CATEGORIES.ESCALATION,
+        priority: CATEGORY_PRIORITY.escalation,
+        blocking: true,
+        run_id: record.run_id || null,
+        summary: `${record.type || 'escalation'} escalated to human${service}: ${what}`,
+        action_hint: record.resolution_command || `agentxchain unblock ${record.escalation_id}`,
+      };
+    });
+}
+
+/**
+ * Category 5 — Budget / policy blockers. A run halted on budget or policy needs a human
+ * to raise the budget or override the policy. Composes `state.blocked_on`
+ * (`budget:exhausted`, `policy:<id>`).
+ */
+export function evaluateBudgetPolicyCategory(state) {
+  const blockedOn = blockedOnString(state);
+  if (!blockedOn) return [];
+  const runId = state?.run_id || null;
+
+  if (blockedOn === 'budget:exhausted') {
+    return [{
+      category: HUMAN_ATTENTION_CATEGORIES.BUDGET_POLICY,
+      priority: CATEGORY_PRIORITY.budget_policy,
+      blocking: true,
+      run_id: runId,
+      summary: 'Run halted: budget exhausted — raise the budget to continue.',
+      action_hint: 'agentxchain unblock',
+    }];
+  }
+
+  if (blockedOn.startsWith('policy:')) {
+    const policyId = blockedOn.slice('policy:'.length) || 'unknown';
+    return [{
+      category: HUMAN_ATTENTION_CATEGORIES.BUDGET_POLICY,
+      priority: CATEGORY_PRIORITY.budget_policy,
+      blocking: true,
+      run_id: runId,
+      summary: `Run halted by policy "${policyId}" — a human must override or adjust it.`,
+      action_hint: 'agentxchain unblock',
+    }];
+  }
+
+  return [];
+}
+
+/**
+ * Bonus category — Manual gate action / generic human block. Catches the remaining
+ * human-owned `state.blocked_on` encodings (`gate_action:<gate>`, `human:<detail>`) so a
+ * run blocked on operator intervention is never silently dropped from the queue. (The
+ * `escalation:<id>` encoding is already represented by its open escalation in Category 2.)
+ */
+export function evaluateManualActionCategory(state) {
+  const blockedOn = blockedOnString(state);
+  if (!blockedOn) return [];
+  const runId = state?.run_id || null;
+
+  if (blockedOn.startsWith('gate_action:')) {
+    const gate = blockedOn.slice('gate_action:'.length) || 'unknown';
+    return [{
+      category: HUMAN_ATTENTION_CATEGORIES.MANUAL_ACTION,
+      priority: CATEGORY_PRIORITY.manual_action,
+      blocking: true,
+      run_id: runId,
+      summary: `Run awaits a manual gate action on "${gate}".`,
+      action_hint: 'agentxchain gate',
+    }];
+  }
+
+  if (blockedOn.startsWith('human:')) {
+    const detail = blockedOn.slice('human:'.length) || 'operator intervention required';
+    return [{
+      category: HUMAN_ATTENTION_CATEGORIES.MANUAL_ACTION,
+      priority: CATEGORY_PRIORITY.manual_action,
+      blocking: true,
+      run_id: runId,
+      summary: `Run awaits operator intervention: ${detail}.`,
+      action_hint: 'agentxchain unblock',
+    }];
+  }
+
+  return [];
+}
+
+/**
+ * Category 3 — Pending approved intents awaiting dispatch (set direction). Informational:
+ * work approved but not yet dispatched. Composes intake.js `findPendingApprovedIntents`.
+ */
+export function evaluatePendingIntentCategory(intents) {
+  return (intents || []).map((intent) => {
+    const pri = intent.priority ? ` [${intent.priority}]` : '';
+    const charter = intent.charter ? `: ${intent.charter}` : '';
+    return {
+      category: HUMAN_ATTENTION_CATEGORIES.PENDING_INTENT,
+      priority: CATEGORY_PRIORITY.pending_intent,
+      blocking: false,
+      run_id: null,
+      summary: `Approved intent ${intent.intent_id}${pri} awaits dispatch${charter}.`,
+      action_hint: 'agentxchain start',
+    };
+  });
+}
+
+// ── ordering & assembly ──────────────────────────────────────────────────────
+
+/**
+ * Deterministic Ordering contract: blocking items before non-blocking; within a tier,
+ * ascending `priority`; ties broken by `run_id` then `summary` for stability.
+ */
+function sortItems(items) {
+  return [...items].sort((a, b) => {
+    if (a.blocking !== b.blocking) return a.blocking ? -1 : 1;
+    if (a.priority !== b.priority) return a.priority - b.priority;
+    const ra = a.run_id || '';
+    const rb = b.run_id || '';
+    if (ra !== rb) return ra < rb ? -1 : 1;
+    const sa = a.summary || '';
+    const sb = b.summary || '';
+    if (sa !== sb) return sa < sb ? -1 : 1;
+    return 0;
+  });
+}
+
+function assembleReport(items) {
+  const sorted = sortItems(items);
+  const blockingCount = sorted.filter((item) => item.blocking).length;
+  const categories = [...new Set(sorted.map((item) => item.category))];
+  const overall = sorted.length === 0 ? 'clear' : 'attention';
+
+  const evidence = overall === 'clear'
+    ? 'Nothing needs your attention; governed autonomy can run.'
+    : `${sorted.length} item${sorted.length === 1 ? '' : 's'} need human attention `
+      + `(${blockingCount} blocking) across ${categories.length} `
+      + `categor${categories.length === 1 ? 'y' : 'ies'}.`;
+
+  return {
+    overall,
+    items: sorted,
+    items_count: sorted.length,
+    blocking_count: blockingCount,
+    categories,
+    evidence_summary: evidence,
+  };
+}
+
+// Run each category in isolation so a throw or empty result in one never suppresses
+// another (Architecture Invariant #4).
+function collect(items, fn) {
+  try {
+    const result = fn();
+    if (Array.isArray(result)) items.push(...result);
+  } catch {
+    /* category isolated — a failure here must not blank the rest of the queue */
+  }
+}
+
+/**
+ * Compose the cross-category human-decision queue for a single governed repo into a
+ * prioritized `HumanAttentionReport`. Read-only.
+ *
+ * @param {string} repoDir
+ * @returns {{ overall, items, items_count, blocking_count, categories, evidence_summary }}
+ */
+export function evaluateHumanAttention(repoDir) {
+  const root = repoDir || process.cwd();
+
+  let config = null;
+  try {
+    const ctx = loadProjectContext(root);
+    config = ctx?.config || null;
+  } catch {
+    config = null;
+  }
+
+  const state = readGovernedStateReadOnly(root, config);
+
+  let escalations = [];
+  collect([], () => { escalations = readHumanEscalations(root) || []; return []; });
+
+  let intents = [];
+  collect([], () => { intents = findPendingApprovedIntents(root, { run_id: state?.run_id || null }) || []; return []; });
+
+  const items = [];
+  collect(items, () => evaluatePendingApprovalCategory(state, config));
+  collect(items, () => evaluateEscalationCategory(escalations));
+  collect(items, () => evaluateBudgetPolicyCategory(state));
+  collect(items, () => evaluateManualActionCategory(state));
+  collect(items, () => evaluatePendingIntentCategory(intents));
+
+  return assembleReport(items);
+}
+
+/**
+ * Build the compact human-attention summary embedded in a governance report. Operates on
+ * an export artifact (filesystem is not live), so only the state/config-derivable
+ * categories are evaluated — the live `agentxchain attention` command surfaces the full
+ * cross-category queue (escalations, pending intents).
+ *
+ * @param {object} artifact
+ * @returns {{ overall, items_count, blocking_count, categories } | null}
+ */
+export function buildHumanAttentionSummary(artifact) {
+  if (!artifact) return null;
+  const state = artifact.state || null;
+  const config = artifact.config || null;
+
+  const items = [];
+  collect(items, () => evaluatePendingApprovalCategory(state, config));
+  collect(items, () => evaluateBudgetPolicyCategory(state));
+  collect(items, () => evaluateManualActionCategory(state));
+
+  const report = assembleReport(items);
+  return {
+    overall: report.overall,
+    items_count: report.items_count,
+    blocking_count: report.blocking_count,
+    categories: report.categories,
+  };
+}

package/src/lib/report.js

@@ -13,6 +13,8 @@ import { buildCoordinatorRepoStatusEntries } from './coordinator-repo-status-pre
 import { summarizeCoordinatorEvent } from './coordinator-event-narrative.js';
 import { extractGateActionDigest } from './gate-actions.js';
 import { buildRecoveryClassificationReport } from './recovery-classification.js';
+import { buildShipStatusSummary } from './ship-status.js';
+import { buildHumanAttentionSummary } from './human-attention.js';
 
 export const GOVERNANCE_REPORT_VERSION = '0.1';
 
@@ -1077,6 +1079,8 @@ function buildRunSubject(artifact) {
       continuity,
       workflow_kit_artifacts: extractWorkflowKitArtifacts(artifact),
       repo_decisions: artifact.summary?.repo_decisions || null,
+      ship_status: buildShipStatusSummary(artifact),
+      human_attention: buildHumanAttentionSummary(artifact),
     },
     artifacts: {
       history_entries: artifact.summary?.history_entries || 0,
@@ -1425,6 +1429,17 @@ export function formatGovernanceReportText(report) {
       }
     }
 
+    if (run.ship_status) {
+      const ss = run.ship_status;
+      const label = ss.overall === 'pass' ? 'YES' : ss.overall === 'fail' ? 'NO' : 'PENDING';
+      lines.push('', `Ship Status: ${label} (${ss.dimensions_passed}/${ss.dimensions_total} dimensions pass)`);
+      if (ss.blocking_reasons.length > 0) {
+        for (const reason of ss.blocking_reasons) {
+          lines.push(`  - ${reason}`);
+        }
+      }
+    }
+
     if (run.turns && run.turns.length > 0) {
       const { items: boundedTurns, omitted: turnsOmitted } = boundedSlice(run.turns);
       lines.push('', 'Turn Timeline:');

package/src/lib/ship-status.js

@@ -0,0 +1,545 @@
+/**
+ * M14: Shippability Visibility — Vision Closure (VISION.md:50)
+ *
+ * Composes five independent evidence dimensions into a single, operator-queryable
+ * shippability assessment, answering "is this ready to ship?" without forcing the
+ * operator to inspect run state, QA verdicts, gates, release artifacts, and test
+ * evidence by hand.
+ *
+ * This module is a COMPOSITION layer (Architecture Invariant #1): it reaches the
+ * existing governance logic through its public surface and never reimplements gate
+ * evaluation, release alignment, or verification. It is strictly read-only
+ * (Invariant #2) — it never mutates run state, artifacts, or config. Every
+ * dimension is evaluated independently; a failure in one never short-circuits the
+ * others (Invariant #3). Coordinator aggregation uses worst-case semantics
+ * (Invariant #4).
+ *
+ * Public surface:
+ *   evaluateShipStatus(repoDir, options)            — single governed repo
+ *   evaluateCoordinatorShipStatus(coordDir, options) — multi-repo aggregation
+ *   buildShipStatusSummary(artifact)                 — export-artifact summary (report.js)
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { loadProjectContext } from './config.js';
+import { queryAcceptedTurnHistory } from './accepted-turn-history.js';
+import { evaluateWorkflowGateSemantics, SHIP_VERDICT_PATH } from './workflow-gate-semantics.js';
+import { validateReleaseAlignment } from './release-alignment.js';
+import { loadCoordinatorConfig, resolveRepoPaths } from './coordinator-config.js';
+
+export const SHIP_STATUS_DIMENSIONS = [
+  'run_completion',
+  'qa_ship_verdict',
+  'gate_clearance',
+  'release_alignment',
+  'test_verification',
+];
+
+const DEFAULT_STATE_PATH = '.agentxchain/state.json';
+const HISTORY_PATH = '.agentxchain/history.jsonl';
+
+const PASSING_VERIFICATION = new Set(['pass', 'attested_pass']);
+// Explicitly skipped verification (planning/review turns that run no test gate) is NEUTRAL:
+// it provides no test evidence but must not pin the shippability signal to "pending" forever.
+const NEUTRAL_VERIFICATION = new Set(['skipped']);
+const PASSING_RUN_STATUSES = new Set(['completed']);
+const FAILING_RUN_STATUSES = new Set(['failed', 'blocked', 'idle']);
+
+function dimension(name, status, detail, blockingReason) {
+  return {
+    name,
+    status,
+    detail,
+    blocking_reason: status === 'pass' ? null : (blockingReason || detail),
+  };
+}
+
+/**
+ * Read the governed state file WITHOUT writeback (loadProjectState may normalize
+ * and persist, which would violate the read-only invariant).
+ */
+function readGovernedStateReadOnly(root, config) {
+  const rel = config?.files?.state || DEFAULT_STATE_PATH;
+  const filePath = join(root, rel);
+  if (!existsSync(filePath)) return null;
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+// ── dimension evaluators (pure; exported for focused unit testing) ────────
+
+/**
+ * Dimension 1 — Run completion status. Source: governed run state `status`.
+ */
+export function evaluateRunCompletionDimension(state) {
+  const status = state?.status || null;
+  if (PASSING_RUN_STATUSES.has(status)) {
+    return dimension('run_completion', 'pass', `Run status is "${status}".`, null);
+  }
+  if (FAILING_RUN_STATUSES.has(status)) {
+    return dimension(
+      'run_completion',
+      'fail',
+      `Run status is "${status}".`,
+      `Run is not shippable: status "${status}".`,
+    );
+  }
+  const label = status || 'unknown';
+  return dimension(
+    'run_completion',
+    'pending',
+    `Run status is "${label}"; not yet completed.`,
+    `Run has not reached completion (status "${label}").`,
+  );
+}
+
+function phaseOrder(config) {
+  return Object.keys(config?.routing || {});
+}
+
+function finalPhaseReached(state, config) {
+  const phases = phaseOrder(config);
+  const finalPhase = phases.length ? phases[phases.length - 1] : 'qa';
+  const currentPhase = state?.phase || null;
+  if (state?.status === 'completed') return { reached: true, finalPhase };
+  if (currentPhase == null) return { reached: false, finalPhase };
+  const idx = phases.indexOf(currentPhase);
+  const finalIdx = phases.indexOf(finalPhase);
+  return { reached: idx >= 0 && idx >= finalIdx, finalPhase };
+}
+
+/**
+ * Dimension 2 — QA ship verdict. Source: workflow-gate-semantics public surface
+ * evaluated against .planning/ship-verdict.md (Architecture Invariant #1).
+ */
+export function evaluateShipVerdictDimension(root, state, config, semanticsEvaluator) {
+  const evaluate = semanticsEvaluator || evaluateWorkflowGateSemantics;
+  const result = evaluate(root, SHIP_VERDICT_PATH); // null when file missing, else { ok, reason? }
+  const { reached, finalPhase } = finalPhaseReached(state, config);
+
+  if (result == null) {
+    if (reached) {
+      return dimension(
+        'qa_ship_verdict',
+        'fail',
+        `Ship verdict file ${SHIP_VERDICT_PATH} is missing.`,
+        `QA ship verdict (${SHIP_VERDICT_PATH}) is missing after reaching the "${finalPhase}" phase.`,
+      );
+    }
+    return dimension(
+      'qa_ship_verdict',
+      'pending',
+      `QA ship verdict not yet produced (current phase "${state?.phase || 'unknown'}").`,
+      `QA phase ("${finalPhase}") not yet reached; ship verdict pending.`,
+    );
+  }
+
+  if (result.ok) {
+    return dimension('qa_ship_verdict', 'pass', 'QA ship verdict is affirmative (## Verdict: YES).', null);
+  }
+
+  const reason = result.reason || 'Ship verdict is not affirmative.';
+  return dimension('qa_ship_verdict', 'fail', reason, `QA did not approve shipping: ${reason}`);
+}
+
+/**
+ * Dimension 3 — Gate clearance. Source: recorded phase_gate_status (string values
+ * "passed"/"pending"/"failed") against the gates declared in config.
+ */
+export function evaluateGateClearanceDimension(state, config) {
+  const gateIds = Object.keys(config?.gates || {});
+  if (gateIds.length === 0) {
+    return dimension(
+      'gate_clearance',
+      'pending',
+      'No governance gates defined in config.',
+      'No governance gates defined to evaluate.',
+    );
+  }
+
+  const statusMap = state?.phase_gate_status || {};
+  const perGate = gateIds.map((id) => ({ id, status: normalizeGateStatus(statusMap[id]) }));
+  const failed = perGate.filter((g) => g.status === 'failed');
+  const pending = perGate.filter((g) => g.status !== 'passed' && g.status !== 'failed');
+  const detailParts = perGate.map((g) => `${g.id}=${g.status}`).join(', ');
+
+  if (failed.length > 0) {
+    return dimension(
+      'gate_clearance',
+      'fail',
+      `Gate status: ${detailParts}.`,
+      `Gate(s) failed: ${failed.map((g) => g.id).join(', ')}.`,
+    );
+  }
+  if (pending.length > 0) {
+    return dimension(
+      'gate_clearance',
+      'pending',
+      `Gate status: ${detailParts}.`,
+      `Gate(s) not yet satisfied: ${pending.map((g) => g.id).join(', ')}.`,
+    );
+  }
+  return dimension('gate_clearance', 'pass', `All ${gateIds.length} gates passed.`, null);
+}
+
+// phase_gate_status values are strings in governed state, but tolerate the
+// legacy { outcome | status } object shape defensively.
+function normalizeGateStatus(value) {
+  if (typeof value === 'string') return value;
+  if (value && typeof value === 'object') return value.outcome || value.status || 'pending';
+  return 'pending';
+}
+
+/**
+ * Dimension 4 — Release alignment. Source: release-alignment.validateReleaseAlignment.
+ * The evaluator is injectable so composition can be tested without reconstructing
+ * release-alignment's ~18 release surfaces (already covered by release-alignment.test.js).
+ * When the release context cannot be built (pre-release, no package/changelog) the
+ * dimension is pending rather than fail.
+ */
+export function evaluateReleaseAlignmentDimension(root, releaseEvaluator) {
+  const evaluate = releaseEvaluator || ((repoRoot) => validateReleaseAlignment(repoRoot, {}));
+  let result;
+  try {
+    result = evaluate(root);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return dimension(
+      'release_alignment',
+      'pending',
+      `Release alignment not yet evaluable: ${message}`,
+      `Release alignment not yet evaluated (pre-release): ${message}`,
+    );
+  }
+
+  if (!result) {
+    return dimension(
+      'release_alignment',
+      'pending',
+      'Release alignment produced no result.',
+      'Release alignment not yet evaluated.',
+    );
+  }
+
+  if (result.ok) {
+    const surfaces = result.checkedSurfaceCount ?? (result.checkedSurfaceIds?.length || 0);
+    return dimension('release_alignment', 'pass', `Release alignment OK (${surfaces} surfaces checked).`, null);
+  }
+
+  const reasons = (result.errors || []).map((e) => e?.message || String(e));
+  const preview = reasons.slice(0, 3).join('; ');
+  const more = reasons.length > 3 ? ` (+${reasons.length - 3} more)` : '';
+  return dimension(
+    'release_alignment',
+    'fail',
+    `Release alignment failed: ${reasons.length} issue(s).`,
+    `Release artifacts not aligned: ${preview}${more}.`,
+  );
+}
+
+/**
+ * Dimension 5 — Test verification. Source: verification.status across accepted turns.
+ */
+export function evaluateTestVerificationDimension(history) {
+  if (!Array.isArray(history) || history.length === 0) {
+    return dimension(
+      'test_verification',
+      'pending',
+      'No accepted turns with verification evidence yet.',
+      'No accepted turns with verification evidence yet.',
+    );
+  }
+
+  const failed = history.filter((h) => normalizeVerificationStatus(h) === 'fail');
+  if (failed.length > 0) {
+    const ids = failed.map((h) => h.turn_id).filter(Boolean).slice(0, 3).join(', ');
+    return dimension(
+      'test_verification',
+      'fail',
+      `${failed.length} accepted turn(s) failed verification.`,
+      `Verification failed on turn(s): ${ids || '(unknown)'}.`,
+    );
+  }
+
+  // Turns that explicitly SKIPPED verification (e.g. planning/review turns with no test gate)
+  // are neutral — they neither contribute nor withhold test evidence. Excluding them prevents a
+  // shippable run from being pinned to "pending" forever just because one planning turn skipped.
+  const evidenceBearing = history.filter(
+    (h) => !NEUTRAL_VERIFICATION.has(normalizeVerificationStatus(h)),
+  );
+  if (evidenceBearing.length === 0) {
+    return dimension(
+      'test_verification',
+      'pending',
+      `No accepted turns with passing verification evidence yet (all ${history.length} skipped).`,
+      'No accepted turns have produced passing verification evidence yet.',
+    );
+  }
+
+  const nonPass = evidenceBearing.filter((h) => !PASSING_VERIFICATION.has(normalizeVerificationStatus(h)));
+  if (nonPass.length > 0) {
+    return dimension(
+      'test_verification',
+      'pending',
+      `${nonPass.length} accepted turn(s) without a passing verification.`,
+      `Verification not yet passing on ${nonPass.length} accepted turn(s).`,
+    );
+  }
+
+  return dimension(
+    'test_verification',
+    'pass',
+    `All ${evidenceBearing.length} verification-bearing accepted turns passed.`,
+    null,
+  );
+}
+
+function normalizeVerificationStatus(entry) {
+  const status = entry?.verification?.status;
+  return typeof status === 'string' ? status.toLowerCase() : null;
+}
+
+/**
+ * Aggregate dimension verdicts with worst-case semantics:
+ * any fail → fail; else any pending → pending; else pass.
+ */
+export function aggregateShipStatus(dimensions) {
+  const hasFail = dimensions.some((d) => d.status === 'fail');
+  const hasPending = dimensions.some((d) => d.status === 'pending');
+  const overall = hasFail ? 'fail' : hasPending ? 'pending' : 'pass';
+  const passed = dimensions.filter((d) => d.status === 'pass').length;
+  const blocking_reasons = dimensions
+    .filter((d) => d.status !== 'pass')
+    .map((d) => d.blocking_reason)
+    .filter(Boolean);
+
+  const blockingTag = blocking_reasons.length ? `, ${blocking_reasons.length} blocking` : '';
+  const evidence_summary = `Ship status: ${overall.toUpperCase()} — ${passed}/${dimensions.length} dimensions pass${blockingTag}.`;
+
+  return { overall, dimensions, blocking_reasons, evidence_summary };
+}
+
+// ── public API ────────────────────────────────────────────────────────────
+
+/**
+ * Compose the five evidence dimensions into a single ShipStatusReport.
+ *
+ * @param {string} repoDir
+ * @param {object} [options]
+ * @param {object} [options.context] - preloaded { root, config }
+ * @param {object} [options.state] - preloaded run state
+ * @param {Array}  [options.history] - preloaded accepted-turn history
+ * @param {Function} [options.releaseAlignmentEvaluator] - (root) => { ok, errors }
+ * @param {Function} [options.semanticsEvaluator] - (root, relPath) => { ok, reason? } | null
+ * @returns {{ overall: string, dimensions: object[], blocking_reasons: string[], evidence_summary: string }}
+ */
+export function evaluateShipStatus(repoDir, options = {}) {
+  const context = options.context || loadProjectContext(repoDir);
+  if (!context) {
+    const reason = `Not a governed AgentXchain project: no agentxchain.json found at ${repoDir}.`;
+    return {
+      overall: 'fail',
+      dimensions: [],
+      blocking_reasons: [reason],
+      evidence_summary: `Ship status: FAIL — ${reason}`,
+    };
+  }
+
+  const { root, config } = context;
+  const state = options.state || readGovernedStateReadOnly(root, config) || {};
+  const history = options.history || queryAcceptedTurnHistory(root);
+
+  const dimensions = [
+    evaluateRunCompletionDimension(state),
+    evaluateShipVerdictDimension(root, state, config, options.semanticsEvaluator),
+    evaluateGateClearanceDimension(state, config),
+    evaluateReleaseAlignmentDimension(root, options.releaseAlignmentEvaluator),
+    evaluateTestVerificationDimension(history),
+  ];
+
+  return aggregateShipStatus(dimensions);
+}
+
+/**
+ * Aggregate per-repo shippability for a multi-repo coordinator run.
+ *
+ * @param {string} coordinatorDir
+ * @param {object} [options] - dimension-evaluator overrides forwarded to each repo
+ * @returns {{ overall: string, repos: object[], blocking_repos: string[], evidence_summary: string }}
+ */
+export function evaluateCoordinatorShipStatus(coordinatorDir, options = {}) {
+  const loaded = options.coordinatorConfig
+    ? { ok: true, config: options.coordinatorConfig, errors: [] }
+    : loadCoordinatorConfig(coordinatorDir);
+
+  if (!loaded.ok || !loaded.config) {
+    const reason = `Cannot load coordinator config: ${(loaded.errors || []).join('; ') || 'unknown error'}`;
+    return {
+      overall: 'fail',
+      repos: [],
+      blocking_repos: [],
+      evidence_summary: `Coordinator ship status: FAIL — ${reason}`,
+    };
+  }
+
+  const { resolved } = resolveRepoPaths(loaded.config, coordinatorDir);
+  const repoIds = loaded.config.repo_order || Object.keys(loaded.config.repos || {});
+
+  // Only dimension-evaluator overrides are forwarded; per-repo state/context/history
+  // must be loaded fresh for each repo.
+  const forwarded = {
+    releaseAlignmentEvaluator: options.releaseAlignmentEvaluator,
+    semanticsEvaluator: options.semanticsEvaluator,
+  };
+
+  const repos = repoIds.map((repo_id) => {
+    const repoPath = resolved[repo_id];
+    if (!repoPath) {
+      const reason = `repo "${repo_id}" path could not be resolved.`;
+      return {
+        repo_id,
+        ship_status: {
+          overall: 'fail',
+          dimensions: [],
+          blocking_reasons: [reason],
+          evidence_summary: `Ship status: FAIL — ${reason}`,
+        },
+      };
+    }
+    return { repo_id, ship_status: evaluateShipStatus(repoPath, forwarded) };
+  });
+
+  const hasFail = repos.some((r) => r.ship_status.overall === 'fail');
+  const hasPending = repos.some((r) => r.ship_status.overall === 'pending');
+  const overall = hasFail ? 'fail' : hasPending ? 'pending' : 'pass';
+  const blocking_repos = repos
+    .filter((r) => r.ship_status.overall !== 'pass')
+    .map((r) => r.repo_id);
+  const passed = repos.filter((r) => r.ship_status.overall === 'pass').length;
+  const blockingTag = blocking_repos.length ? `, blocking: ${blocking_repos.join(', ')}` : '';
+  const evidence_summary = `Coordinator ship status: ${overall.toUpperCase()} — ${passed}/${repos.length} repos shippable${blockingTag}.`;
+
+  return { overall, repos, blocking_repos, evidence_summary };
+}
+
+// ── governance-report integration (export-artifact based) ───────────────────
+
+function readArtifactFileContent(artifact, relPath) {
+  const entry = artifact?.files?.[relPath];
+  if (!entry) return null;
+  if (typeof entry === 'string') return entry;
+  if (typeof entry.data === 'string') return entry.data;
+  if (typeof entry.content_base64 === 'string') {
+    try {
+      return Buffer.from(entry.content_base64, 'base64').toString('utf8');
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function parseHistoryJsonl(content) {
+  if (typeof content !== 'string' || !content.trim()) return [];
+  return content
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+// Affirmative ship-verdict tokens, mirroring workflow-gate-semantics
+// (evaluateShipVerdict is not exported, so the artifact path checks the recorded
+// gate outcome first and only falls back to a minimal verdict-line parse).
+const AFFIRMATIVE_VERDICTS = new Set(['yes', 'ship', 'ship it']);
+
+function evaluateShipVerdictFromArtifact(state, verdictContent, config) {
+  const gateStatus = normalizeGateStatus(state?.phase_gate_status?.qa_ship_verdict);
+  if (gateStatus === 'passed') {
+    return dimension('qa_ship_verdict', 'pass', 'QA ship verdict gate passed.', null);
+  }
+  if (gateStatus === 'failed') {
+    return dimension('qa_ship_verdict', 'fail', 'QA ship verdict gate failed.', 'QA did not approve shipping.');
+  }
+
+  if (typeof verdictContent === 'string' && verdictContent.trim()) {
+    const match = verdictContent.match(/^##\s+Verdict\s*:\s*(.+)$/im);
+    if (match) {
+      const token = match[1].trim().toLowerCase().replace(/[.!]+$/, '');
+      if (AFFIRMATIVE_VERDICTS.has(token)) {
+        return dimension('qa_ship_verdict', 'pass', 'QA ship verdict is affirmative.', null);
+      }
+      return dimension(
+        'qa_ship_verdict',
+        'fail',
+        `QA ship verdict is "${match[1].trim()}".`,
+        `QA did not approve shipping: verdict "${match[1].trim()}".`,
+      );
+    }
+  }
+
+  const { reached, finalPhase } = finalPhaseReached(state, config);
+  if (reached) {
+    return dimension(
+      'qa_ship_verdict',
+      'fail',
+      'QA ship verdict missing after QA phase.',
+      `QA ship verdict missing after reaching the "${finalPhase}" phase.`,
+    );
+  }
+  return dimension(
+    'qa_ship_verdict',
+    'pending',
+    'QA ship verdict not yet produced.',
+    `QA phase ("${finalPhase}") not yet reached; ship verdict pending.`,
+  );
+}
+
+/**
+ * Build the compact ship-status summary embedded in a governance report.
+ * Operates on an export artifact (filesystem is not live), so release_alignment
+ * is reported as pending — the live `agentxchain ship-status` command surfaces it.
+ *
+ * @param {object} artifact
+ * @returns {{ overall, dimensions_passed, dimensions_total, blocking_reasons } | null}
+ */
+export function buildShipStatusSummary(artifact) {
+  if (!artifact) return null;
+
+  const state = artifact.state || null;
+  const config = artifact.config || null;
+  const history = parseHistoryJsonl(readArtifactFileContent(artifact, HISTORY_PATH));
+  const verdictContent = readArtifactFileContent(artifact, SHIP_VERDICT_PATH);
+
+  const dimensions = [
+    evaluateRunCompletionDimension(state),
+    evaluateShipVerdictFromArtifact(state, verdictContent, config),
+    evaluateGateClearanceDimension(state, config),
+    dimension(
+      'release_alignment',
+      'pending',
+      'Release alignment is not evaluable from an export artifact.',
+      'Release alignment not evaluated (run `agentxchain ship-status` for live evaluation).',
+    ),
+    evaluateTestVerificationDimension(history),
+  ];
+
+  const result = aggregateShipStatus(dimensions);
+  return {
+    overall: result.overall,
+    dimensions_passed: result.dimensions.filter((d) => d.status === 'pass').length,
+    dimensions_total: result.dimensions.length,
+    blocking_reasons: result.blocking_reasons,
+  };
+}

package/src/lib/turn-result-validator.js

@@ -138,7 +138,7 @@ export function validateStagedTurnResult(root, state, config, opts = {}) {
   }
 
   // ── Stage C: Artifact Validation ───────────────────────────────────────
-  const artifactResult = validateArtifact(turnResult, config, state);
+  const artifactResult = validateArtifact(turnResult, config, state, root);
   if (artifactResult.errors.length > 0) {
     return result('artifact', 'artifact_error', artifactResult.errors, artifactResult.warnings);
   }
@@ -670,7 +670,7 @@ function validateAssignment(tr, state) {
 
 // ── Stage C: Artifact Validation ─────────────────────────────────────────────
 
-function validateArtifact(tr, config, state = null) {
+function validateArtifact(tr, config, state = null, root = null) {
   const errors = [];
   const warnings = [];
 
@@ -733,10 +733,18 @@ function validateArtifact(tr, config, state = null) {
   if (writeAuthority === 'authoritative' && state?.phase === 'implementation' && tr.status === 'completed') {
     const productFiles = (tr.files_changed || []).filter(f => isProductChangePath(f));
     if (productFiles.length === 0) {
-      errors.push(
-        `Role "${tr.role}" completed an implementation turn without product code changes in files_changed. ` +
-        'Implementation-phase completion requires at least one non-planning, non-review repo path; planning artifacts alone are not sufficient.'
-      );
+      // A planning/review-only completion is legitimate ONLY as a follow-on once the
+      // objective's product code has already been delivered in a prior accepted turn of this
+      // run (e.g. QA, or a Dev re-run, finalizing the gate-required IMPLEMENTATION_NOTES
+      // ## Changes / ## Verification sections after the implementation itself was committed).
+      // If no product code has been committed for the run yet, planning artifacts alone still
+      // do not satisfy the implementation_complete gate.
+      if (!runHasCommittedProductCode(root, state?.run_id)) {
+        errors.push(
+          `Role "${tr.role}" completed an implementation turn without product code changes in files_changed. ` +
+          'Implementation-phase completion requires at least one non-planning, non-review repo path; planning artifacts alone are not sufficient.'
+        );
+      }
     } else if (productFiles.every(f => isTestPath(f))) {
       // Work-substance signal: an implementation turn that changed ONLY test files produced
       // no implementation source. That is legitimate for acceptance/verification objectives,
@@ -802,6 +810,34 @@ function isProductChangePath(filePath) {
     && !filePath.startsWith('.agentxchain/staging/');
 }
 
+// Whether any prior accepted turn in this run already committed product code. A follow-on
+// implementation-phase turn that only finalizes planning artifacts (e.g. the gate-required
+// IMPLEMENTATION_NOTES ## Changes / ## Verification sections) is legitimate once the
+// objective's implementation is delivered; a run that has produced no product code at all is
+// still held to the "code, not just docs" requirement. Reads the governed accepted-turn log.
+function runHasCommittedProductCode(root, runId) {
+  if (!root || !runId) return false;
+  try {
+    const histPath = join(root, '.agentxchain', 'history.jsonl');
+    if (!existsSync(histPath)) return false;
+    for (const line of readFileSync(histPath, 'utf8').split('\n')) {
+      if (!line.trim()) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      if (entry.run_id !== runId) continue;
+      // Only a COMPLETED IMPLEMENTATION turn counts as "the objective's code was delivered" — a
+      // planning-phase or non-completed turn that incidentally touched a file must not disarm the
+      // guard (adversarial-review hardening).
+      if (entry.status !== 'completed' || entry.phase !== 'implementation') continue;
+      const files = Array.isArray(entry.files_changed) ? entry.files_changed : [];
+      if (files.some((f) => isProductChangePath(f))) return true;
+    }
+  } catch {
+    // History unreadable — fall back to the strict requirement (treat as no prior product code).
+  }
+  return false;
+}
+
 // A test/spec file path — used to flag implementation turns that produced only tests
 // (no implementation source) so test-only work is reviewed rather than silently accepted.
 function isTestPath(filePath) {