agentxchain 2.111.0 → 2.113.0

package/bin/agentxchain.js

@@ -122,6 +122,7 @@ import { eventsCommand } from '../src/commands/events.js';
 import { connectorCheckCommand } from '../src/commands/connector.js';
 import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand, scheduleStatusCommand } from '../src/commands/schedule.js';
 import { chainLatestCommand, chainListCommand, chainShowCommand } from '../src/commands/chain.js';
+import { missionAttachChainCommand, missionListCommand, missionPlanApproveCommand, missionPlanCommand, missionPlanLaunchCommand, missionPlanListCommand, missionPlanShowCommand, missionShowCommand, missionStartCommand } from '../src/commands/mission.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -419,6 +420,90 @@ chainCmd
   .option('-d, --dir <path>', 'Project directory')
   .action(chainShowCommand);
 
+const missionCmd = program
+  .command('mission')
+  .description('Group chained runs under a single-repo long-horizon mission');
+
+missionCmd
+  .command('start')
+  .description('Create a durable mission artifact for a single repo')
+  .requiredOption('--title <text>', 'Mission title')
+  .requiredOption('--goal <text>', 'Mission goal')
+  .option('--id <mission_id>', 'Override the derived mission ID')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionStartCommand);
+
+missionCmd
+  .command('list')
+  .description('List mission artifacts newest first')
+  .option('-l, --limit <n>', 'Max missions to show (default: 20)')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionListCommand);
+
+missionCmd
+  .command('show [mission_id]')
+  .description('Show one mission, or the latest mission when no ID is provided')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionShowCommand);
+
+missionCmd
+  .command('attach-chain [chain_id]')
+  .description('Attach a chain report to a mission (default: latest chain on latest mission)')
+  .option('-m, --mission <mission_id>', 'Explicit mission ID (defaults to latest mission)')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionAttachChainCommand);
+
+const missionPlanCmd = missionCmd
+  .command('plan [mission_id]')
+  .description('Generate a decomposition plan for a mission (default: latest mission)')
+  .option('--constraint <text>', 'Add a constraint to the planner (repeatable)', collectOption, [])
+  .option('--role-hint <role>', 'Hint available roles to the planner (repeatable)', collectOption, [])
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionPlanCommand);
+
+missionPlanCmd
+  .command('show [plan_id]')
+  .description('Show a decomposition plan (default: latest plan)')
+  .option('-m, --mission <mission_id>', 'Explicit mission ID')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionPlanShowCommand);
+
+missionPlanCmd
+  .command('approve [plan_id]')
+  .description('Approve a decomposition plan (default: latest plan)')
+  .option('-m, --mission <mission_id>', 'Explicit mission ID')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionPlanApproveCommand);
+
+missionPlanCmd
+  .command('launch [plan_id]')
+  .description('Launch a workstream from an approved plan (default: latest plan)')
+  .requiredOption('-w, --workstream <id>', 'Workstream ID to launch')
+  .option('-m, --mission <mission_id>', 'Explicit mission ID')
+  .option('--auto-approve', 'Auto-approve run gates while executing the launched workstream')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionPlanLaunchCommand);
+
+missionPlanCmd
+  .command('list')
+  .description('List all plans for a mission')
+  .option('-m, --mission <mission_id>', 'Explicit mission ID')
+  .option('-l, --limit <n>', 'Max plans to show (default: 20)')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionPlanListCommand);
+
+function collectOption(value, previous) {
+  return previous.concat([value]);
+}
+
 program
   .command('validate')
   .description('Validate project protocol artifacts')
@@ -547,6 +632,7 @@ program
   .option('--max-chains <n>', 'Maximum continuation runs in chain mode (default: 5)', parseInt)
   .option('--chain-on <statuses>', 'Comma-separated terminal statuses that trigger chaining (default: completed)')
   .option('--chain-cooldown <seconds>', 'Seconds to wait between chained runs (default: 5)', parseInt)
+  .option('--mission <mission_id>', 'Bind chained runs to a mission (use "latest" for most recent mission)')
   .action(runCommand);
 
 program

package/dashboard/app.js

@@ -15,6 +15,7 @@ import { render as renderCrossRepo } from './components/cross-repo.js';
 import { render as renderDelegations } from './components/delegations.js';
 import { render as renderBlockers } from './components/blockers.js';
 import { render as renderArtifacts } from './components/artifacts.js';
+import { render as renderMission } from './components/mission.js';
 import { render as renderChain } from './components/chain.js';
 import { render as renderRunHistory } from './components/run-history.js';
 import { render as renderTimeouts } from './components/timeouts.js';
@@ -36,6 +37,7 @@ const VIEWS = {
   'cross-repo': { fetch: ['coordinatorState', 'coordinatorHistory'], render: renderCrossRepo },
   blockers: { fetch: ['coordinatorBlockers'], render: renderBlockers },
   artifacts: { fetch: ['workflowKitArtifacts'], render: renderArtifacts },
+  mission: { fetch: ['missions', 'plans'], render: renderMission },
   chain: { fetch: ['chainReports'], render: renderChain },
   'run-history': { fetch: ['runHistory'], render: renderRunHistory },
   timeouts: { fetch: ['timeouts'], render: renderTimeouts },
@@ -60,6 +62,8 @@ const API_MAP = {
   coordinatorBlockers: '/api/coordinator/blockers',
   coordinatorRepoStatusRows: '/api/coordinator/repo-status',
   workflowKitArtifacts: '/api/workflow-kit-artifacts',
+  missions: '/api/missions',
+  plans: '/api/plans',
   chainReports: '/api/chain-reports',
   connectors: '/api/connectors',
   runHistory: '/api/run-history',

package/dashboard/components/mission.js

@@ -0,0 +1,356 @@
+function esc(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function badge(label, color = 'var(--text-dim)') {
+  return `<span class="badge" style="color:${color};border-color:${color}">${esc(label)}</span>`;
+}
+
+function formatMissionStatus(status) {
+  switch (status) {
+    case 'progressing':
+      return badge('progressing', 'var(--green)');
+    case 'planned':
+      return badge('planned', '#38bdf8');
+    case 'needs_attention':
+      return badge('needs attention', 'var(--yellow)');
+    case 'degraded':
+      return badge('degraded', 'var(--red)');
+    default:
+      return badge(status || 'unknown', 'var(--text-dim)');
+  }
+}
+
+function formatTerminalReason(reason) {
+  switch (reason) {
+    case 'chain_limit_reached':
+      return badge('chain limit reached', '#38bdf8');
+    case 'non_chainable_status':
+      return badge('non-chainable status', 'var(--yellow)');
+    case 'operator_abort':
+      return badge('operator abort', 'var(--red)');
+    case 'parent_validation_failed':
+      return badge('parent validation failed', 'var(--red)');
+    case 'completed':
+      return badge('completed', 'var(--green)');
+    default:
+      return badge(reason || 'none', 'var(--text-dim)');
+  }
+}
+
+function formatDate(iso) {
+  if (!iso) return '—';
+  try {
+    const date = new Date(iso);
+    return date.toLocaleDateString(undefined, { month: 'short', day: 'numeric' })
+      + ' ' + date.toLocaleTimeString(undefined, { hour: '2-digit', minute: '2-digit' });
+  } catch {
+    return esc(iso);
+  }
+}
+
+function truncateId(value, len = 14) {
+  if (!value) return '—';
+  return value.length > len ? `${value.slice(0, len)}…` : value;
+}
+
+function renderAttachedChains(latest) {
+  if (!Array.isArray(latest?.chains) || latest.chains.length === 0) {
+    return `<div class="section"><h3>Attached Chains</h3><p class="section-subtitle">No chain reports are attached to this mission yet.</p></div>`;
+  }
+
+  let html = `<div class="section"><h3>Attached Chains</h3>
+    <table class="data-table">
+      <thead>
+        <tr>
+          <th>#</th>
+          <th>Chain ID</th>
+          <th>Runs</th>
+          <th>Turns</th>
+          <th>Terminal</th>
+          <th>Started</th>
+        </tr>
+      </thead>
+      <tbody>`;
+
+  latest.chains.forEach((chain, index) => {
+    html += `<tr>
+      <td style="color:var(--text-dim)">${index + 1}</td>
+      <td class="mono" title="${esc(chain.chain_id || '')}">${esc(truncateId(chain.chain_id))}</td>
+      <td>${chain.runs?.length || 0}</td>
+      <td>${chain.total_turns ?? '—'}</td>
+      <td>${formatTerminalReason(chain.terminal_reason)}</td>
+      <td>${formatDate(chain.started_at)}</td>
+    </tr>`;
+  });
+
+  html += '</tbody></table></div>';
+  return html;
+}
+
+function renderRecentMissions(missions) {
+  let html = `<div class="section"><h3>Recent Missions</h3>
+    <table class="data-table">
+      <thead>
+        <tr>
+          <th>#</th>
+          <th>Mission ID</th>
+          <th>Status</th>
+          <th>Chains</th>
+          <th>Runs</th>
+          <th>Turns</th>
+          <th>Repo Decisions</th>
+          <th>Latest Terminal</th>
+          <th>Updated</th>
+          <th>Title</th>
+        </tr>
+      </thead>
+      <tbody>`;
+
+  missions.forEach((mission, index) => {
+    html += `<tr>
+      <td style="color:var(--text-dim)">${index + 1}</td>
+      <td class="mono" title="${esc(mission.mission_id || '')}">${esc(truncateId(mission.mission_id, 18))}</td>
+      <td>${formatMissionStatus(mission.derived_status)}</td>
+      <td>${mission.chain_count ?? 0}</td>
+      <td>${mission.total_runs ?? 0}</td>
+      <td>${mission.total_turns ?? 0}</td>
+      <td>${mission.active_repo_decisions_count ?? 0}</td>
+      <td>${formatTerminalReason(mission.latest_terminal_reason)}</td>
+      <td>${formatDate(mission.updated_at || mission.created_at)}</td>
+      <td>${esc(mission.title || '—')}</td>
+    </tr>`;
+  });
+
+  html += '</tbody></table></div>';
+  return html;
+}
+
+function formatPlanStatus(status) {
+  switch (status) {
+    case 'proposed':
+      return badge('proposed', '#38bdf8');
+    case 'approved':
+      return badge('approved', 'var(--green)');
+    case 'superseded':
+      return badge('superseded', 'var(--text-dim)');
+    case 'needs_attention':
+      return badge('needs attention', 'var(--yellow)');
+    default:
+      return badge(status || 'unknown', 'var(--text-dim)');
+  }
+}
+
+function formatLaunchStatus(status) {
+  switch (status) {
+    case 'ready':
+      return badge('ready', 'var(--green)');
+    case 'blocked':
+      return badge('blocked', 'var(--red)');
+    case 'launched':
+      return badge('launched', '#38bdf8');
+    case 'completed':
+      return badge('completed', 'var(--green)');
+    case 'needs_attention':
+      return badge('needs attention', 'var(--yellow)');
+    default:
+      return badge(status || 'unknown', 'var(--text-dim)');
+  }
+}
+
+function renderLatestPlan(plan) {
+  if (!plan) {
+    return `<div class="section"><h3>Latest Plan</h3><p class="section-subtitle">No decomposition plan found. Run <code>agentxchain mission plan &lt;mission_id&gt;</code> to generate one.</p></div>`;
+  }
+
+  const workstreams = Array.isArray(plan.workstreams) ? plan.workstreams : [];
+  const launchRecords = Array.isArray(plan.launch_records) ? plan.launch_records : [];
+  const statusCounts = plan.workstream_status_counts || {};
+
+  let html = `<div class="section"><h3>Latest Plan</h3><dl class="detail-list">`;
+  html += `<dt>Plan ID</dt><dd class="mono" title="${esc(plan.plan_id || '')}">${esc(truncateId(plan.plan_id, 30))}</dd>`;
+  html += `<dt>Status</dt><dd>${formatPlanStatus(plan.status)}</dd>`;
+  html += `<dt>Mission</dt><dd class="mono">${esc(plan.mission_id || '—')}</dd>`;
+  html += `<dt>Created</dt><dd>${formatDate(plan.created_at)}</dd>`;
+  if (plan.approved_at) {
+    html += `<dt>Approved</dt><dd>${formatDate(plan.approved_at)}</dd>`;
+  }
+  html += `<dt>Workstreams</dt><dd>${plan.workstream_count || 0}</dd>`;
+  html += `<dt>Launched</dt><dd>${plan.launch_record_count || 0}</dd>`;
+  if (Object.keys(statusCounts).length > 0) {
+    const countsStr = Object.entries(statusCounts).map(([k, v]) => `${k}: ${v}`).join(', ');
+    html += `<dt>Status Breakdown</dt><dd>${esc(countsStr)}</dd>`;
+  }
+  if (plan.supersedes_plan_id) {
+    html += `<dt>Supersedes</dt><dd class="mono">${esc(truncateId(plan.supersedes_plan_id, 30))}</dd>`;
+  }
+  html += `</dl></div>`;
+
+  // Workstreams table
+  if (workstreams.length > 0) {
+    html += `<div class="section"><h3>Workstreams</h3>
+      <table class="data-table">
+        <thead>
+          <tr>
+            <th>#</th>
+            <th>ID</th>
+            <th>Title</th>
+            <th>Status</th>
+            <th>Roles</th>
+            <th>Phases</th>
+            <th>Dependencies</th>
+          </tr>
+        </thead>
+        <tbody>`;
+
+    workstreams.forEach((ws, index) => {
+      const roles = Array.isArray(ws.roles) ? ws.roles.join(', ') : '—';
+      const phases = Array.isArray(ws.phases) ? ws.phases.join(', ') : '—';
+      const deps = Array.isArray(ws.depends_on) && ws.depends_on.length > 0 ? ws.depends_on.join(', ') : 'none';
+
+      html += `<tr>
+        <td style="color:var(--text-dim)">${index + 1}</td>
+        <td class="mono">${esc(ws.workstream_id || '—')}</td>
+        <td>${esc(ws.title || '—')}</td>
+        <td>${formatLaunchStatus(ws.launch_status)}</td>
+        <td>${esc(roles)}</td>
+        <td>${esc(phases)}</td>
+        <td class="mono">${esc(deps)}</td>
+      </tr>`;
+    });
+
+    html += '</tbody></table></div>';
+  }
+
+  // Launch records table
+  if (launchRecords.length > 0) {
+    html += `<div class="section"><h3>Launch Records</h3>
+      <table class="data-table">
+        <thead>
+          <tr>
+            <th>#</th>
+            <th>Workstream</th>
+            <th>Chain ID</th>
+            <th>Status</th>
+            <th>Terminal</th>
+            <th>Launched</th>
+            <th>Completed</th>
+          </tr>
+        </thead>
+        <tbody>`;
+
+    launchRecords.forEach((lr, index) => {
+      html += `<tr>
+        <td style="color:var(--text-dim)">${index + 1}</td>
+        <td class="mono">${esc(lr.workstream_id || '—')}</td>
+        <td class="mono" title="${esc(lr.chain_id || '')}">${esc(truncateId(lr.chain_id))}</td>
+        <td>${formatLaunchStatus(lr.status)}</td>
+        <td>${esc(lr.terminal_reason || '—')}</td>
+        <td>${formatDate(lr.launched_at)}</td>
+        <td>${formatDate(lr.completed_at)}</td>
+      </tr>`;
+    });
+
+    html += '</tbody></table></div>';
+  }
+
+  return html;
+}
+
+function renderRecentPlans(plans) {
+  if (!Array.isArray(plans) || plans.length <= 1) {
+    return '';
+  }
+
+  // Skip the first (latest) since it's rendered in detail above
+  const olderPlans = plans.slice(1);
+  if (olderPlans.length === 0) return '';
+
+  let html = `<div class="section"><h3>Previous Plans</h3>
+    <table class="data-table">
+      <thead>
+        <tr>
+          <th>#</th>
+          <th>Plan ID</th>
+          <th>Mission</th>
+          <th>Status</th>
+          <th>Workstreams</th>
+          <th>Launched</th>
+          <th>Created</th>
+        </tr>
+      </thead>
+      <tbody>`;
+
+  olderPlans.forEach((plan, index) => {
+    html += `<tr>
+      <td style="color:var(--text-dim)">${index + 1}</td>
+      <td class="mono" title="${esc(plan.plan_id || '')}">${esc(truncateId(plan.plan_id, 20))}</td>
+      <td class="mono">${esc(truncateId(plan.mission_id, 18))}</td>
+      <td>${formatPlanStatus(plan.status)}</td>
+      <td>${plan.workstream_count || 0}</td>
+      <td>${plan.launch_record_count || 0}</td>
+      <td>${formatDate(plan.created_at)}</td>
+    </tr>`;
+  });
+
+  html += '</tbody></table></div>';
+  return html;
+}
+
+export function render({ missions, plans }) {
+  if (!missions || typeof missions !== 'object') {
+    return `<div class="placeholder"><h2>Mission</h2><p>No mission data available. Create a mission and bind a chain to populate this view.</p></div>`;
+  }
+
+  const missionList = Array.isArray(missions.missions) ? missions.missions : [];
+  const latest = missions.latest || missionList[0] || null;
+
+  if (!latest || missionList.length === 0) {
+    return `<div class="placeholder"><h2>Mission</h2><p>No missions found. Run <code>agentxchain mission start --title "..." --goal "..."</code> and then <code>agentxchain run --chain --mission latest</code> to track long-horizon work here.</p></div>`;
+  }
+
+  const missingChains = Array.isArray(latest.missing_chain_ids) ? latest.missing_chain_ids : [];
+
+  let html = `<div class="mission-view"><div class="run-header"><div class="run-meta">`;
+  html += `<span class="turn-count">latest mission ${esc(latest.mission_id || '—')}</span>`;
+  html += formatMissionStatus(latest.derived_status);
+  html += badge(`${latest.chain_count || 0} chains`, '#38bdf8');
+  html += badge(`${latest.total_turns || 0} turns`, 'var(--green)');
+  html += badge(`${latest.active_repo_decisions_count || 0} repo decisions`, 'var(--yellow)');
+  html += `</div></div>`;
+
+  html += `<div class="section"><h3>Latest Mission Summary</h3><dl class="detail-list">`;
+  html += `<dt>Title</dt><dd>${esc(latest.title || '—')}</dd>`;
+  html += `<dt>Goal</dt><dd>${esc(latest.goal || '—')}</dd>`;
+  html += `<dt>Updated</dt><dd>${esc(latest.updated_at || latest.created_at || '—')}</dd>`;
+  html += `<dt>Latest Chain</dt><dd class="mono">${esc(latest.latest_chain_id || '—')}</dd>`;
+  html += `<dt>Latest Terminal</dt><dd>${esc(latest.latest_terminal_reason || '—')}</dd>`;
+  html += `<dt>Total Runs</dt><dd>${latest.total_runs ?? 0}</dd>`;
+  html += `<dt>Attached Chains</dt><dd>${latest.attached_chain_count ?? 0}</dd>`;
+  html += `<dt>Missing Chains</dt><dd>${missingChains.length}</dd>`;
+  html += `<dt>Active Repo Decisions</dt><dd>${latest.active_repo_decisions_count ?? 0}</dd>`;
+  html += `</dl></div>`;
+
+  if (missingChains.length > 0) {
+    html += `<div class="section"><h3>Missing Chain References</h3><p class="section-subtitle">This mission is degraded until the missing chain reports are restored.</p><p class="mono">${esc(missingChains.join(', '))}</p></div>`;
+  }
+
+  html += renderAttachedChains(latest);
+
+  // Plan visibility
+  const planData = plans && typeof plans === 'object' ? plans : null;
+  const latestPlan = planData?.latest || null;
+  const allPlans = Array.isArray(planData?.plans) ? planData.plans : [];
+  html += renderLatestPlan(latestPlan);
+  html += renderRecentPlans(allPlans);
+
+  html += renderRecentMissions(missionList);
+  html += '</div>';
+  return html;
+}

package/dashboard/index.html

@@ -405,6 +405,7 @@
     <a href="#gate">Gates</a>
     <a href="#blockers">Blockers</a>
     <a href="#artifacts">Artifacts</a>
+    <a href="#mission">Mission</a>
     <a href="#chain">Chain</a>
     <a href="#run-history">Run History</a>
     <a href="#timeouts">Timeouts</a>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.111.0",
+  "version": "2.113.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
     "test:node": "node --test test/*.test.js",
     "preflight:release": "bash scripts/release-preflight.sh",
     "preflight:release:strict": "bash scripts/release-preflight.sh --strict",
+    "check:release-alignment": "node scripts/check-release-alignment.mjs",
     "postflight:release": "bash scripts/release-postflight.sh",
     "postflight:downstream": "bash scripts/release-downstream-truth.sh",
     "bump:release": "bash scripts/release-bump.sh",

package/scripts/check-release-alignment.mjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+import process from 'node:process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  RELEASE_ALIGNMENT_SCOPES,
+  validateReleaseAlignment,
+} from '../src/lib/release-alignment.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, '..', '..');
+
+function usage() {
+  console.error('Usage: node cli/scripts/check-release-alignment.mjs [--target-version <semver>] [--scope prebump|current] [--json]');
+}
+
+let targetVersion = null;
+let scope = RELEASE_ALIGNMENT_SCOPES.CURRENT;
+let json = false;
+
+for (let index = 2; index < process.argv.length; index += 1) {
+  const arg = process.argv[index];
+  if (arg === '--target-version') {
+    targetVersion = process.argv[index + 1] || null;
+    if (!targetVersion) {
+      console.error('Error: --target-version requires a semver argument');
+      usage();
+      process.exit(1);
+    }
+    index += 1;
+    continue;
+  }
+  if (arg === '--scope') {
+    scope = process.argv[index + 1] || '';
+    if (!Object.values(RELEASE_ALIGNMENT_SCOPES).includes(scope)) {
+      console.error(`Error: invalid --scope "${scope}"`);
+      usage();
+      process.exit(1);
+    }
+    index += 1;
+    continue;
+  }
+  if (arg === '--json') {
+    json = true;
+    continue;
+  }
+  console.error(`Error: unknown argument "${arg}"`);
+  usage();
+  process.exit(1);
+}
+
+const result = validateReleaseAlignment(REPO_ROOT, { targetVersion, scope });
+
+if (json) {
+  console.log(JSON.stringify(result, null, 2));
+} else if (result.ok) {
+  console.log(`Release alignment OK for ${result.targetVersion} (${result.scope}, ${result.checkedSurfaceCount} surfaces).`);
+} else {
+  console.error(`Release alignment FAILED for ${result.targetVersion} (${result.scope}, ${result.errors.length} issue(s)).`);
+  for (const error of result.errors) {
+    console.error(`- [${error.surface_id}] ${error.message}`);
+  }
+}
+
+process.exit(result.ok ? 0 : 1);

package/scripts/release-bump.sh

@@ -143,74 +143,23 @@ if git rev-parse "v${TARGET_VERSION}" >/dev/null 2>&1; then
 fi
 echo "  OK: tag v${TARGET_VERSION} does not exist"
 
-# 4. Pre-bump version-surface alignment guard
-# Ensures all governed version surfaces already reference the target version
+# 4. Pre-bump release-alignment guard
+# Ensures all manual target-version surfaces already reference the target version
 # BEFORE the bump commit is created. This catches stale drift that would
 # otherwise only be discovered after minting local release identities.
 #
 # NOTE: Homebrew mirror formula and README are NOT checked here. They are
-# auto-aligned in step 5 because the registry SHA256 is inherently a
-# post-publish artifact. See DEC-HOMEBREW-SHA-SPLIT-001.
-echo "[4/9] Verifying version-surface alignment for ${TARGET_VERSION}..."
-SURFACE_ERRORS=()
-
-# 4a. CHANGELOG top heading
-CHANGELOG_TOP=$(grep -m1 -E '^## [0-9]+\.[0-9]+\.[0-9]+$' "${REPO_ROOT}/cli/CHANGELOG.md" 2>/dev/null | sed 's/^## //' || true)
-if [[ "$CHANGELOG_TOP" != "$TARGET_VERSION" ]]; then
-  SURFACE_ERRORS+=("CHANGELOG.md top heading is '${CHANGELOG_TOP:-missing}', expected '${TARGET_VERSION}'")
-fi
-
-# 4b. Release notes page exists
-RELEASE_DOC_ID="v${TARGET_VERSION//./-}"
-RELEASE_DOC_PATH="website-v2/docs/releases/${RELEASE_DOC_ID}.mdx"
-if [[ ! -f "${REPO_ROOT}/${RELEASE_DOC_PATH}" ]]; then
-  SURFACE_ERRORS+=("release notes page missing: ${RELEASE_DOC_PATH}")
-fi
-
-# 4c. Docs sidebar auto-generates releases from dirName (release doc existence is sufficient)
-if ! grep -q "dirName.*releases" "${REPO_ROOT}/website-v2/sidebars.ts" 2>/dev/null; then
-  SURFACE_ERRORS+=("sidebars.ts does not auto-generate releases (missing dirName: 'releases')")
-fi
-
-# 4d. Homepage hero badge shows target version
-if ! grep -q "v${TARGET_VERSION}" "${REPO_ROOT}/website-v2/src/pages/index.tsx" 2>/dev/null; then
-  SURFACE_ERRORS+=("homepage index.tsx does not contain 'v${TARGET_VERSION}'")
-fi
-
-# 4e. Conformance capabilities version
-CAPS_VERSION=$(node -e "try{console.log(JSON.parse(require('fs').readFileSync('${REPO_ROOT}/.agentxchain-conformance/capabilities.json','utf8')).version)}catch{console.log('missing')}" 2>/dev/null || echo "missing")
-if [[ "$CAPS_VERSION" != "$TARGET_VERSION" ]]; then
-  SURFACE_ERRORS+=("capabilities.json version is '${CAPS_VERSION}', expected '${TARGET_VERSION}'")
-fi
-
-# 4f. Protocol implementor guide example
-if ! grep -q "\"version\": \"${TARGET_VERSION}\"" "${REPO_ROOT}/website-v2/docs/protocol-implementor-guide.mdx" 2>/dev/null; then
-  SURFACE_ERRORS+=("protocol-implementor-guide.mdx does not contain '\"version\": \"${TARGET_VERSION}\"'")
-fi
-
-# 4g. Launch evidence report title
-ESCAPED_VERSION="${TARGET_VERSION//./\\.}"
-if ! grep -qE "^# Launch Evidence Report — AgentXchain v${ESCAPED_VERSION}" "${REPO_ROOT}/.planning/LAUNCH_EVIDENCE_REPORT.md" 2>/dev/null; then
-  SURFACE_ERRORS+=("LAUNCH_EVIDENCE_REPORT.md title does not carry v${TARGET_VERSION}")
-fi
-
-# 4h. llms.txt must list the current release notes route
-CURRENT_RELEASE_ROUTE="/docs/releases/${RELEASE_DOC_ID}"
-if ! grep -q "${CURRENT_RELEASE_ROUTE}" "${REPO_ROOT}/website-v2/static/llms.txt" 2>/dev/null; then
-  SURFACE_ERRORS+=("website-v2/static/llms.txt does not list '${CURRENT_RELEASE_ROUTE}'")
-fi
-
-# 4i. sitemap.xml is now auto-generated by Docusaurus at build time — no static file check needed
-
-if [[ "${#SURFACE_ERRORS[@]}" -gt 0 ]]; then
-  echo "FAIL: ${#SURFACE_ERRORS[@]} version-surface(s) not aligned to ${TARGET_VERSION}:" >&2
-  printf '  - %s\n' "${SURFACE_ERRORS[@]}" >&2
+# auto-aligned in step 6 because the registry tarball URL is deterministic but
+# the registry SHA256 is inherently post-publish truth.
+echo "[4/10] Verifying release alignment for ${TARGET_VERSION}..."
+if node "${CLI_DIR}/scripts/check-release-alignment.mjs" --target-version "${TARGET_VERSION}" --scope prebump; then
+  :
+else
   echo "" >&2
   echo "Fix these surfaces before running release-bump. The bump script refuses to" >&2
   echo "create release identity when governed surfaces are stale." >&2
   exit 1
 fi
-echo "  OK: all 8 governed version surfaces reference ${TARGET_VERSION}"
 
 # 5. Normalize release-note sidebar ordering
 echo "[5/10] Normalizing release-note sidebar positions..."