agentxchain 2.16.0 → 2.17.0

package/package.json

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

package/scripts/release-preflight.sh

@@ -107,7 +107,7 @@ for example_dir in "${CLI_DIR}/../examples/mcp-echo-agent" "${CLI_DIR}/../exampl
     (cd "$example_dir" && env -u NODE_AUTH_TOKEN -u NPM_CONFIG_USERCONFIG npm install --ignore-scripts --userconfig /dev/null 2>&1) || true
   fi
 done
-if run_and_capture TEST_OUTPUT npm test; then
+if run_and_capture TEST_OUTPUT env AGENTXCHAIN_RELEASE_TARGET_VERSION="${TARGET_VERSION}" AGENTXCHAIN_RELEASE_PREFLIGHT=1 npm test; then
   TEST_STATUS=0
 else
   TEST_STATUS=$?

package/src/commands/multi.js

@@ -40,6 +40,7 @@ import {
   buildEscalationPayload,
 } from '../lib/coordinator-hooks.js';
 import { computeContextInvalidations } from '../lib/cross-repo-context.js';
+import { scaffoldRecoveryReport } from '../lib/workflow-gate-semantics.js';
 
 // ── multi init ─────────────────────────────────────────────────────────────
 
@@ -601,5 +602,6 @@ function blockCoordinator(workspacePath, state, blockedReason) {
     blocked_reason: blockedReason,
   };
   saveCoordinatorState(workspacePath, blockedState);
+  scaffoldRecoveryReport(workspacePath, blockedReason);
   return blockedState;
 }

package/src/lib/coordinator-recovery.js

@@ -21,6 +21,7 @@ import {
   readBarriers,
   recordCoordinatorDecision,
 } from './coordinator-state.js';
+import { evaluateRecoveryReport, scaffoldRecoveryReport } from './workflow-gate-semantics.js';
 import { safeWriteJson } from './safe-write.js';
 import {
   computeBarrierStatus as computeCoordinatorBarrierStatus,
@@ -416,6 +417,9 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
   }
 
   saveCoordinatorState(workspacePath, updatedState);
+  if (blockedReason) {
+    scaffoldRecoveryReport(workspacePath, blockedReason);
+  }
 
   // Step 6: Append resync event to history
   appendJsonl(historyPath(workspacePath), {
@@ -458,6 +462,22 @@ export function resumeCoordinatorFromBlockedState(workspacePath, state, config)
   }
 
   const previousBlockedReason = state.blocked_reason || 'unknown blocked reason';
+
+  // Require a recovery report before allowing resume
+  const reportResult = evaluateRecoveryReport(workspacePath);
+  if (reportResult === null) {
+    return {
+      ok: false,
+      error: 'Recovery report required before resume. Create .agentxchain/multirepo/RECOVERY_REPORT.md with ## Trigger, ## Impact, and ## Mitigation sections.',
+    };
+  }
+  if (!reportResult.ok) {
+    return {
+      ok: false,
+      error: reportResult.reason,
+    };
+  }
+
   const expectedSuperRunId = state.super_run_id;
   const resync = resyncFromRepoAuthority(workspacePath, state, config);
   const refreshedState = loadCoordinatorState(workspacePath);

package/src/lib/export.js

@@ -15,6 +15,7 @@ const COORDINATOR_INCLUDED_ROOTS = [
   '.agentxchain/multirepo/barriers.json',
   '.agentxchain/multirepo/decision-ledger.jsonl',
   '.agentxchain/multirepo/barrier-ledger.jsonl',
+  '.agentxchain/multirepo/RECOVERY_REPORT.md',
 ];
 
 const INCLUDED_ROOTS = [

package/src/lib/report.js

@@ -507,6 +507,36 @@ function buildRunSubject(artifact) {
   };
 }
 
+function extractRecoveryReportSection(content, heading) {
+  const pattern = new RegExp(`^${heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*$`, 'm');
+  const match = content.match(pattern);
+  if (!match) return null;
+  const start = match.index + match[0].length;
+  const nextHeading = content.slice(start).match(/^## /m);
+  const sectionText = nextHeading
+    ? content.slice(start, start + nextHeading.index).trim()
+    : content.slice(start).trim();
+  if (!sectionText || /^\(.*\)$/.test(sectionText)) return null;
+  return sectionText;
+}
+
+function extractRecoveryReportSummary(artifact) {
+  const entry = artifact.files?.['.agentxchain/multirepo/RECOVERY_REPORT.md'];
+  if (!entry) return null;
+  const content = typeof entry.data === 'string'
+    ? entry.data
+    : (entry.content_base64 ? Buffer.from(entry.content_base64, 'base64').toString('utf8') : null);
+  if (!content) return null;
+  return {
+    present: true,
+    trigger: extractRecoveryReportSection(content, '## Trigger'),
+    impact: extractRecoveryReportSection(content, '## Impact'),
+    mitigation: extractRecoveryReportSection(content, '## Mitigation'),
+    owner: extractRecoveryReportSection(content, '## Owner'),
+    exit_condition: extractRecoveryReportSection(content, '## Exit Condition'),
+  };
+}
+
 function buildCoordinatorSubject(artifact) {
   const coordinatorState = extractFileData(artifact, '.agentxchain/multirepo/state.json') || {};
   const repoStatuses = artifact.summary?.repo_run_statuses || {};
@@ -580,6 +610,7 @@ function buildCoordinatorSubject(artifact) {
     barrier_summary: barrierSummary,
     barrier_ledger_timeline: barrierLedgerTimeline,
     decision_digest: decisionDigest,
+    recovery_report: extractRecoveryReportSummary(artifact),
     repos,
     artifacts: {
       history_entries: artifact.summary?.history_entries || 0,
@@ -754,7 +785,7 @@ export function formatGovernanceReportText(report) {
     return lines.join('\n');
   }
 
-  const { coordinator, run, artifacts, repos, coordinator_timeline, barrier_summary, barrier_ledger_timeline, decision_digest } = report.subject;
+  const { coordinator, run, artifacts, repos, coordinator_timeline, barrier_summary, barrier_ledger_timeline, decision_digest, recovery_report } = report.subject;
   const lines = [
     'AgentXchain Governance Report',
     `Input: ${report.input}`,
@@ -827,6 +858,15 @@ export function formatGovernanceReportText(report) {
     }
   }
 
+  if (recovery_report) {
+    lines.push('', 'Recovery Report:');
+    lines.push(`  Trigger: ${recovery_report.trigger || 'n/a'}`);
+    lines.push(`  Impact: ${recovery_report.impact || 'n/a'}`);
+    lines.push(`  Mitigation: ${recovery_report.mitigation || 'n/a'}`);
+    lines.push(`  Owner: ${recovery_report.owner || 'n/a'}`);
+    lines.push(`  Exit Condition: ${recovery_report.exit_condition || 'n/a'}`);
+  }
+
   lines.push('Repo details:');
   lines.push(...repos.flatMap((repo) => {
       if (!repo.ok) {
@@ -991,7 +1031,7 @@ export function formatGovernanceReportMarkdown(report) {
     return lines.join('\n');
   }
 
-  const { coordinator, run, artifacts, repos, coordinator_timeline, barrier_summary, barrier_ledger_timeline, decision_digest } = report.subject;
+  const { coordinator, run, artifacts, repos, coordinator_timeline, barrier_summary, barrier_ledger_timeline, decision_digest, recovery_report: coordRecoveryReport } = report.subject;
   const mdLines = [
     '# AgentXchain Governance Report',
     '',
@@ -1065,6 +1105,15 @@ export function formatGovernanceReportMarkdown(report) {
     }
   }
 
+  if (coordRecoveryReport) {
+    mdLines.push('', '## Recovery Report', '');
+    mdLines.push(`- **Trigger:** ${coordRecoveryReport.trigger || 'n/a'}`);
+    mdLines.push(`- **Impact:** ${coordRecoveryReport.impact || 'n/a'}`);
+    mdLines.push(`- **Mitigation:** ${coordRecoveryReport.mitigation || 'n/a'}`);
+    mdLines.push(`- **Owner:** ${coordRecoveryReport.owner || 'n/a'}`);
+    mdLines.push(`- **Exit Condition:** ${coordRecoveryReport.exit_condition || 'n/a'}`);
+  }
+
   mdLines.push('', '## Repo Details', '');
   mdLines.push(...repos.flatMap((repo) => {
     if (!repo.ok) {

package/src/lib/workflow-gate-semantics.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
 export const PM_SIGNOFF_PATH = '.planning/PM_SIGNOFF.md';
@@ -7,6 +7,7 @@ export const IMPLEMENTATION_NOTES_PATH = '.planning/IMPLEMENTATION_NOTES.md';
 export const ACCEPTANCE_MATRIX_PATH = '.planning/acceptance-matrix.md';
 export const SHIP_VERDICT_PATH = '.planning/ship-verdict.md';
 export const RELEASE_NOTES_PATH = '.planning/RELEASE_NOTES.md';
+export const RECOVERY_REPORT_PATH = '.agentxchain/multirepo/RECOVERY_REPORT.md';
 
 const AFFIRMATIVE_SHIP_VERDICTS = new Set(['YES', 'SHIP', 'SHIP IT']);
 const AFFIRMATIVE_ACCEPTANCE_STATUSES = new Set(['PASS', 'PASSED', 'OK', 'YES']);
@@ -235,6 +236,105 @@ function evaluateReleaseNotes(content) {
   return { ok: true };
 }
 
+const RECOVERY_REPORT_PLACEHOLDER = /^\(Operator fills this before running multi resume\)$/i;
+
+function hasRecoveryReportSectionContent(content, sectionHeader) {
+  const lines = content.split(/\r?\n/);
+  const headerIndex = lines.findIndex((line) => line.trim().startsWith(sectionHeader));
+  if (headerIndex === -1) {
+    return { found: false, hasContent: false };
+  }
+
+  for (let i = headerIndex + 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (line.startsWith('## ')) break;
+    if (!line) continue;
+    if (RECOVERY_REPORT_PLACEHOLDER.test(line)) continue;
+    return { found: true, hasContent: true };
+  }
+
+  return { found: true, hasContent: false };
+}
+
+export function evaluateRecoveryReport(workspacePath) {
+  const content = readFile(workspacePath, RECOVERY_REPORT_PATH);
+  if (content === null) {
+    return null;
+  }
+
+  const trigger = hasRecoveryReportSectionContent(content, '## Trigger');
+  const impact = hasRecoveryReportSectionContent(content, '## Impact');
+  const mitigation = hasRecoveryReportSectionContent(content, '## Mitigation');
+
+  const missingSections = [];
+  if (!trigger.found) missingSections.push('## Trigger');
+  if (!impact.found) missingSections.push('## Impact');
+  if (!mitigation.found) missingSections.push('## Mitigation');
+
+  if (missingSections.length > 0) {
+    return {
+      ok: false,
+      reason: `Recovery report must define ${missingSections.join(' and ')} before resume.`,
+    };
+  }
+
+  const emptySections = [];
+  if (!trigger.hasContent) emptySections.push('## Trigger');
+  if (!impact.hasContent) emptySections.push('## Impact');
+  if (!mitigation.hasContent) emptySections.push('## Mitigation');
+
+  if (emptySections.length > 0) {
+    return {
+      ok: false,
+      reason: `Recovery report sections still contain placeholder text: ${emptySections.join(', ')}. Replace placeholder content before running multi resume.`,
+    };
+  }
+
+  return { ok: true };
+}
+
+export function scaffoldRecoveryReport(workspacePath, blockedReason) {
+  const absPath = join(workspacePath, RECOVERY_REPORT_PATH);
+  if (existsSync(absPath)) {
+    return false;
+  }
+
+  const reasonText = typeof blockedReason === 'string'
+    ? blockedReason
+    : JSON.stringify(blockedReason) || 'unknown';
+
+  const content = `# Recovery Report
+
+Coordinator entered blocked state. Fill in the sections below before running \`agentxchain multi resume\`.
+
+**Blocked reason:** ${reasonText}
+**Blocked at:** ${new Date().toISOString()}
+
+## Trigger
+
+(Operator fills this before running multi resume)
+
+## Impact
+
+(Operator fills this before running multi resume)
+
+## Mitigation
+
+(Operator fills this before running multi resume)
+
+## Owner
+
+(Optional: who performed the recovery)
+
+## Exit Condition
+
+(Optional: what must remain true after recovery)
+`;
+
+  writeFileSync(absPath, content);
+  return true;
+}
+
 function evaluateShipVerdict(content) {
   const verdict = parseLineValue(content, /^##\s+Verdict\s*:\s*(.+)$/im);
   if (!verdict) {