agentxchain 2.14.0 → 2.16.0

package/src/lib/coordinator-recovery.js

@@ -19,8 +19,14 @@ import {
   saveCoordinatorState,
   readCoordinatorHistory,
   readBarriers,
+  recordCoordinatorDecision,
 } from './coordinator-state.js';
 import { safeWriteJson } from './safe-write.js';
+import {
+  computeBarrierStatus as computeCoordinatorBarrierStatus,
+  getAcceptedReposForWorkstream,
+  getAlignedReposForBarrier,
+} from './coordinator-barriers.js';
 
 // ── Paths ───────────────────────────────────────────────────────────────────
 
@@ -335,6 +341,23 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
     if (barrier.type === 'shared_human_gate') continue; // Never auto-transition
 
     const newStatus = recomputeBarrierStatus(barrier, fullHistory, config);
+    if (barrier.type === 'all_repos_accepted') {
+      const satisfiedRepos = getAcceptedReposForWorkstream(
+        fullHistory, barrier.workstream_id, barrier.required_repos
+      );
+      if (JSON.stringify(barrier.satisfied_repos || []) !== JSON.stringify(satisfiedRepos)) {
+        barrier.satisfied_repos = satisfiedRepos;
+        barriersChanged = true;
+      }
+    }
+    if (barrier.type === 'interface_alignment') {
+      const satisfiedRepos = getAlignedReposForBarrier(barrier, fullHistory);
+      if (JSON.stringify(barrier.satisfied_repos || []) !== JSON.stringify(satisfiedRepos)) {
+        barrier.satisfied_repos = satisfiedRepos;
+        barriersChanged = true;
+      }
+    }
+
     if (newStatus !== barrier.status) {
       const previousStatus = barrier.status;
       barrierChanges.push({
@@ -347,13 +370,6 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
 
       barrier.status = newStatus;
 
-      // Update satisfied_repos for tracking
-      if (barrier.type === 'all_repos_accepted') {
-        barrier.satisfied_repos = getAcceptedReposForWorkstream(
-          fullHistory, barrier.workstream_id, barrier.required_repos
-        );
-      }
-
       barriersChanged = true;
 
       appendJsonl(barrierLedgerPath(workspacePath), {
@@ -421,75 +437,124 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
   };
 }
 
-// ── Internal helpers ────────────────────────────────────────────────────────
+/**
+ * Clear a coordinator blocked state after the operator resolves the cause.
+ *
+ * Recovery always begins with repo-authority resync, then restores the
+ * coordinator to `active` or `paused` based on whether a pending gate still
+ * exists. It never mutates repo-local governed state.
+ *
+ * @param {string} workspacePath
+ * @param {object} state
+ * @param {object} config
+ * @returns {{ ok: boolean, state?: object, resumed_status?: string, blocked_reason?: string, blocked_repos?: string[], resync?: object, error?: string }}
+ */
+export function resumeCoordinatorFromBlockedState(workspacePath, state, config) {
+  if (!state || state.status !== 'blocked') {
+    return {
+      ok: false,
+      error: `Cannot resume coordinator: status is "${state?.status || 'missing'}", expected "blocked"`,
+    };
+  }
 
-function getAcceptedReposForWorkstream(history, workstreamId, requiredRepos) {
-  const accepted = new Set();
-  for (const entry of history) {
-    if (entry?.type === 'acceptance_projection' && entry.workstream_id === workstreamId) {
-      if (requiredRepos.includes(entry.repo_id)) {
-        accepted.add(entry.repo_id);
-      }
-    }
+  const previousBlockedReason = state.blocked_reason || 'unknown blocked reason';
+  const expectedSuperRunId = state.super_run_id;
+  const resync = resyncFromRepoAuthority(workspacePath, state, config);
+  const refreshedState = loadCoordinatorState(workspacePath);
+
+  if (!refreshedState) {
+    return {
+      ok: false,
+      error: 'Coordinator state could not be reloaded after resync',
+      blocked_reason: previousBlockedReason,
+      resync,
+    };
   }
-  return [...accepted];
-}
 
-function recomputeBarrierStatus(barrier, history, config) {
-  switch (barrier.type) {
-    case 'all_repos_accepted': {
-      const required = new Set(barrier.required_repos);
-      const satisfied = new Set();
-      for (const entry of history) {
-        if (entry?.type === 'acceptance_projection' && entry.workstream_id === barrier.workstream_id) {
-          if (required.has(entry.repo_id)) {
-            satisfied.add(entry.repo_id);
-          }
-        }
-      }
-      if (satisfied.size === required.size) return 'satisfied';
-      if (satisfied.size > 0) return 'partially_satisfied';
-      return 'pending';
-    }
+  if (refreshedState.super_run_id !== expectedSuperRunId) {
+    return {
+      ok: false,
+      error: `Cannot resume coordinator: super_run_id changed from "${expectedSuperRunId}" to "${refreshedState.super_run_id}"`,
+      blocked_reason: previousBlockedReason,
+      resync,
+    };
+  }
 
-    case 'ordered_repo_sequence': {
-      const workstream = config.workstreams?.[barrier.workstream_id];
-      if (!workstream) return barrier.status;
-      const entryRepo = workstream.entry_repo;
-      const hasUpstream = history.some(
-        e => e?.type === 'acceptance_projection'
-          && e.workstream_id === barrier.workstream_id
-          && e.repo_id === entryRepo
-      );
-      if (hasUpstream) return 'satisfied';
-      const anyDownstream = history.some(
-        e => e?.type === 'acceptance_projection'
-          && e.workstream_id === barrier.workstream_id
-          && e.repo_id !== entryRepo
-      );
-      if (anyDownstream) return 'partially_satisfied';
-      return 'pending';
-    }
+  if (!resync.ok) {
+    return {
+      ok: false,
+      error: `Coordinator remains blocked: ${resync.blocked_reason || refreshedState.blocked_reason || previousBlockedReason}`,
+      blocked_reason: resync.blocked_reason || refreshedState.blocked_reason || previousBlockedReason,
+      resync,
+      state: refreshedState,
+    };
+  }
+
+  const blockedRepos = Object.entries(refreshedState.repo_runs || {})
+    .filter(([, repoRun]) => repoRun?.status === 'blocked')
+    .map(([repoId]) => repoId);
+
+  if (blockedRepos.length > 0) {
+    const blockedReason = `child repos remain blocked: ${blockedRepos.join(', ')}`;
+    const blockedState = {
+      ...refreshedState,
+      status: 'blocked',
+      blocked_reason: blockedReason,
+    };
+    saveCoordinatorState(workspacePath, blockedState);
+    return {
+      ok: false,
+      error: `Cannot resume coordinator: ${blockedReason}`,
+      blocked_reason: blockedReason,
+      blocked_repos: blockedRepos,
+      resync,
+      state: blockedState,
+    };
+  }
+
+  const resumedStatus = refreshedState.pending_gate ? 'paused' : 'active';
+  const resumedState = {
+    ...refreshedState,
+    status: resumedStatus,
+  };
+  delete resumedState.blocked_reason;
 
-    case 'interface_alignment': {
-      const required = new Set(barrier.required_repos);
-      const acceptedRepos = new Set();
-      for (const entry of history) {
-        if (entry?.type === 'acceptance_projection' && entry.workstream_id === barrier.workstream_id) {
-          if (required.has(entry.repo_id)) acceptedRepos.add(entry.repo_id);
-        }
+  saveCoordinatorState(workspacePath, resumedState);
+  appendJsonl(historyPath(workspacePath), {
+    type: 'blocked_resolved',
+    timestamp: new Date().toISOString(),
+    super_run_id: refreshedState.super_run_id,
+    from: 'blocked',
+    to: resumedStatus,
+    blocked_reason: previousBlockedReason,
+    pending_gate: refreshedState.pending_gate
+      ? {
+        gate: refreshedState.pending_gate.gate,
+        gate_type: refreshedState.pending_gate.gate_type,
       }
-      if (acceptedRepos.size === 0) return 'pending';
-      if (acceptedRepos.size < required.size) return 'partially_satisfied';
-      return 'satisfied';
-    }
+      : null,
+  });
+  recordCoordinatorDecision(workspacePath, resumedState, {
+    category: 'recovery',
+    from: 'blocked',
+    to: resumedStatus,
+    reason: typeof previousBlockedReason === 'string'
+      ? previousBlockedReason
+      : JSON.stringify(previousBlockedReason),
+    statement: `Resumed coordinator from blocked to ${resumedStatus}`,
+  });
 
-    case 'shared_human_gate':
-      return barrier.status; // Never auto-transition
+  return {
+    ok: true,
+    state: resumedState,
+    resumed_status: resumedStatus,
+    blocked_reason: previousBlockedReason,
+    resync,
+  };
+}
 
-    default:
-      return barrier.status;
-  }
+function recomputeBarrierStatus(barrier, history, config) {
+  return computeCoordinatorBarrierStatus(barrier, history, config);
 }
 
 /**

package/src/lib/coordinator-state.js

@@ -64,6 +64,21 @@ function appendJsonl(filePath, entry) {
   writeFileSync(filePath, JSON.stringify(entry) + '\n', { flag: 'a' });
 }
 
+function nextCoordinatorDecisionId(entries) {
+  let max = 0;
+  for (const entry of entries) {
+    const match = typeof entry?.id === 'string'
+      ? entry.id.match(/^DEC-COORD-(\d+)$/)
+      : null;
+    if (!match) continue;
+    const current = Number.parseInt(match[1], 10);
+    if (Number.isFinite(current) && current > max) {
+      max = current;
+    }
+  }
+  return `DEC-COORD-${String(max + 1).padStart(3, '0')}`;
+}
+
 function readRepoLocalState(repoPath) {
   const stateFile = join(repoPath, '.agentxchain/state.json');
   if (!existsSync(stateFile)) return null;
@@ -97,6 +112,7 @@ function bootstrapBarriers(config) {
       status: 'pending',
       required_repos: [...workstream.repos],
       satisfied_repos: [],
+      alignment_decision_ids: workstream.interface_alignment?.decision_ids_by_repo || null,
       created_at: new Date().toISOString(),
     };
   }
@@ -251,6 +267,11 @@ export function initializeCoordinatorRun(workspacePath, preloadedConfig) {
       ),
       timestamp: now,
     });
+    recordCoordinatorDecision(workspacePath, state, {
+      timestamp: now,
+      category: 'initialization',
+      statement: `Initialized coordinator run for ${config.project.id} with ${Object.keys(repoRuns).length} repo${Object.keys(repoRuns).length === 1 ? '' : 's'}`,
+    });
   } catch (err) {
     // Atomic failure: clean up partial state
     try {
@@ -297,6 +318,59 @@ export function saveCoordinatorState(workspacePath, state) {
   safeWriteJson(statePath(workspacePath), updated);
 }
 
+export function readCoordinatorDecisionLedger(workspacePath) {
+  const file = ledgerPath(workspacePath);
+  if (!existsSync(file)) return [];
+  try {
+    const content = readFileSync(file, 'utf8').trim();
+    if (!content) return [];
+    return content.split('\n').map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+export function recordCoordinatorDecision(workspacePath, state, decision) {
+  const statement = typeof decision?.statement === 'string' ? decision.statement.trim() : '';
+  if (statement.length === 0) {
+    throw new Error('Coordinator decision statement is required');
+  }
+
+  const existingEntries = readCoordinatorDecisionLedger(workspacePath);
+  const entry = {
+    id: typeof decision?.id === 'string' && decision.id.length > 0
+      ? decision.id
+      : nextCoordinatorDecisionId(existingEntries),
+    timestamp: decision?.timestamp || new Date().toISOString(),
+    super_run_id: decision?.super_run_id || state?.super_run_id || null,
+    role: decision?.role || 'coordinator',
+    phase: decision?.phase || state?.phase || null,
+    category: decision?.category || 'governance',
+    statement,
+  };
+
+  for (const key of [
+    'repo_id',
+    'repo_run_id',
+    'repo_turn_id',
+    'workstream_id',
+    'gate',
+    'from',
+    'to',
+    'reason',
+    'context_ref',
+    'projection_ref',
+  ]) {
+    const value = decision?.[key];
+    if (value != null) {
+      entry[key] = value;
+    }
+  }
+
+  appendJsonl(ledgerPath(workspacePath), entry);
+  return entry;
+}
+
 /**
  * Get a full coordinator status snapshot.
  *

package/src/lib/cross-repo-context.js

@@ -2,6 +2,7 @@ import { mkdirSync, writeFileSync, appendFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { readCoordinatorHistory, readBarriers } from './coordinator-state.js';
+import { listWorkstreamHandoffs } from './intake-handoff.js';
 
 const CONTEXT_ROOT = '.agentxchain/multirepo/context';
 
@@ -60,6 +61,7 @@ function collectActiveBarriers(barriers, workstreamIds, targetRepoId) {
       type: barrier.type || 'unknown',
       status: barrier.status,
       notes: barrier.notes || null,
+      alignment_decision_ids: barrier.alignment_decision_ids || null,
     }));
 }
 
@@ -75,6 +77,17 @@ function buildRequiredFollowups(workstreamId, dependencyIds, upstreamAcceptances
   }
 
   for (const barrier of activeBarriers) {
+    if (
+      barrier.type === 'interface_alignment'
+      && barrier.alignment_decision_ids
+      && Array.isArray(barrier.alignment_decision_ids[targetRepoId])
+      && barrier.alignment_decision_ids[targetRepoId].length > 0
+    ) {
+      followups.push(
+        `Accept declared interface-alignment decisions for ${targetRepoId}: ${barrier.alignment_decision_ids[targetRepoId].join(', ')}.`,
+      );
+    }
+
     if (barrier.notes) {
       followups.push(barrier.notes);
     } else {
@@ -85,6 +98,21 @@ function buildRequiredFollowups(workstreamId, dependencyIds, upstreamAcceptances
   return [...new Set(followups)];
 }
 
+function collectIntakeHandoffs(workspacePath, state, workstreamId) {
+  return listWorkstreamHandoffs(workspacePath, workstreamId, state.super_run_id).map((handoff) => ({
+    intent_id: handoff.intent_id,
+    source_repo: handoff.source_repo,
+    source_event_id: handoff.source_event_id,
+    source_signal_source: handoff.source_signal_source || null,
+    source_signal_category: handoff.source_signal_category || null,
+    charter: handoff.charter || '',
+    acceptance_contract: Array.isArray(handoff.acceptance_contract) ? handoff.acceptance_contract : [],
+    source_event_ref: handoff.source_event_ref || null,
+    evidence_refs: Array.isArray(handoff.evidence_refs) ? handoff.evidence_refs : [],
+    handed_off_at: handoff.handed_off_at || null,
+  }));
+}
+
 function renderContextMarkdown(snapshot) {
   const lines = [
     '# Coordinator Context',
@@ -116,7 +144,16 @@ function renderContextMarkdown(snapshot) {
     lines.push('- None');
   } else {
     for (const barrier of snapshot.active_barriers) {
-      lines.push(`- ${barrier.barrier_id}: ${barrier.type} (${barrier.status})`);
+      let suffix = '';
+      if (
+        barrier.type === 'interface_alignment'
+        && barrier.alignment_decision_ids
+        && Array.isArray(barrier.alignment_decision_ids[snapshot.target_repo_id])
+        && barrier.alignment_decision_ids[snapshot.target_repo_id].length > 0
+      ) {
+        suffix = ` Required decision IDs for ${snapshot.target_repo_id}: ${barrier.alignment_decision_ids[snapshot.target_repo_id].join(', ')}.`;
+      }
+      lines.push(`- ${barrier.barrier_id}: ${barrier.type} (${barrier.status})${suffix}`);
     }
   }
 
@@ -132,6 +169,34 @@ function renderContextMarkdown(snapshot) {
     }
   }
 
+  if (snapshot.intake_handoffs.length > 0) {
+    lines.push('');
+    lines.push('## Intake Handoff');
+    lines.push('');
+
+    for (const handoff of snapshot.intake_handoffs) {
+      lines.push(`### ${handoff.intent_id}`);
+      lines.push('');
+      lines.push(`- Source Repo: ${handoff.source_repo}`);
+      if (handoff.source_signal_source || handoff.source_signal_category) {
+        lines.push(`- Original Signal: ${handoff.source_signal_source || 'unknown'} — ${handoff.source_signal_category || 'unknown'}`);
+      }
+      if (handoff.charter) {
+        lines.push(`- Charter: ${handoff.charter}`);
+      }
+      if (handoff.source_event_ref) {
+        lines.push(`- Evidence: ${handoff.source_repo}/${handoff.source_event_ref}`);
+      }
+      if (handoff.acceptance_contract.length > 0) {
+        lines.push('- Acceptance Contract:');
+        for (const requirement of handoff.acceptance_contract) {
+          lines.push(`  - ${requirement}`);
+        }
+      }
+      lines.push('');
+    }
+  }
+
   lines.push('');
   return lines.join('\n');
 }
@@ -197,6 +262,7 @@ export function generateCrossRepoContext(workspacePath, state, config, targetRep
   const relevantWorkstreamIds = [workstreamId, ...(Array.isArray(workstream.depends_on) ? workstream.depends_on : [])];
   const upstreamAcceptances = collectUpstreamAcceptances(history, targetRepoId, relevantWorkstreamIds);
   const activeBarriers = collectActiveBarriers(barriers, relevantWorkstreamIds, targetRepoId);
+  const intakeHandoffs = collectIntakeHandoffs(workspacePath, state, workstreamId);
   const snapshot = {
     schema_version: '0.1',
     super_run_id: state.super_run_id,
@@ -213,6 +279,7 @@ export function generateCrossRepoContext(workspacePath, state, config, targetRep
       activeBarriers,
       targetRepoId,
     ),
+    intake_handoffs: intakeHandoffs,
   };
 
   const contextDir = getContextDir(workspacePath, contextRef);

package/src/lib/governed-templates.js

@@ -73,6 +73,32 @@ function validateAcceptanceHints(acceptanceHints, errors) {
   }
 }
 
+const VALID_SPEC_OVERLAY_KEYS = new Set([
+  'purpose_guidance',
+  'interface_guidance',
+  'behavior_guidance',
+  'error_cases_guidance',
+  'acceptance_tests_guidance',
+  'extra_sections',
+]);
+
+function validateSystemSpecOverlay(overlay, errors) {
+  if (overlay === undefined) return;
+  if (!overlay || typeof overlay !== 'object' || Array.isArray(overlay)) {
+    errors.push('system_spec_overlay must be an object when provided');
+    return;
+  }
+
+  for (const [key, value] of Object.entries(overlay)) {
+    if (!VALID_SPEC_OVERLAY_KEYS.has(key)) {
+      errors.push(`system_spec_overlay contains unknown key "${key}"`);
+    }
+    if (typeof value !== 'string' || !value.trim()) {
+      errors.push(`system_spec_overlay["${key}"] must be a non-empty string`);
+    }
+  }
+}
+
 export function validateGovernedTemplateManifest(manifest, expectedId = null) {
   const errors = [];
 
@@ -111,6 +137,7 @@ export function validateGovernedTemplateManifest(manifest, expectedId = null) {
   validatePlanningArtifacts(manifest.planning_artifacts, errors);
   validatePromptOverrides(manifest.prompt_overrides, errors);
   validateAcceptanceHints(manifest.acceptance_hints, errors);
+  validateSystemSpecOverlay(manifest.system_spec_overlay, errors);
 
   return { ok: errors.length === 0, errors };
 }
@@ -251,6 +278,7 @@ const TEMPLATE_GUIDANCE_HEADER = '## Template Guidance';
 const GOVERNED_WORKFLOW_KIT_BASE_FILES = Object.freeze([
   '.planning/PM_SIGNOFF.md',
   '.planning/ROADMAP.md',
+  '.planning/SYSTEM_SPEC.md',
   '.planning/acceptance-matrix.md',
   '.planning/ship-verdict.md',
 ]);
@@ -267,6 +295,24 @@ const GOVERNED_WORKFLOW_KIT_STRUCTURAL_CHECKS = Object.freeze([
     pattern: /^##\s+Phases\b/im,
     description: 'Roadmap defines a ## Phases section',
   },
+  {
+    id: 'system_spec_purpose_section',
+    file: '.planning/SYSTEM_SPEC.md',
+    pattern: /^##\s+Purpose\b/im,
+    description: 'System spec defines a ## Purpose section',
+  },
+  {
+    id: 'system_spec_interface_section',
+    file: '.planning/SYSTEM_SPEC.md',
+    pattern: /^##\s+Interface\b/im,
+    description: 'System spec defines a ## Interface section',
+  },
+  {
+    id: 'system_spec_acceptance_tests_section',
+    file: '.planning/SYSTEM_SPEC.md',
+    pattern: /^##\s+Acceptance Tests\b/im,
+    description: 'System spec defines a ## Acceptance Tests section',
+  },
   {
     id: 'acceptance_matrix_table_header',
     file: '.planning/acceptance-matrix.md',
@@ -452,6 +498,20 @@ export function validateGovernedWorkflowKit(root, config = {}) {
   };
 }
 
+export const SYSTEM_SPEC_OVERLAY_SEPARATOR = '## Template-Specific Guidance';
+
+export function buildSystemSpecContent(projectName, overlay) {
+  const o = overlay || {};
+  const purpose = o.purpose_guidance || '(Describe the problem this slice solves and why it exists.)';
+  const iface = o.interface_guidance || '(List the user-facing commands, files, APIs, or contracts this slice changes.)';
+  const behavior = o.behavior_guidance || '(Describe the expected behavior, including important edge cases.)';
+  const errorCases = o.error_cases_guidance || '(List the failure modes and how the system should respond.)';
+  const acceptance = o.acceptance_tests_guidance || '- [ ] Name the executable checks that prove this slice works.';
+  const extra = o.extra_sections ? `\n${o.extra_sections}\n` : '';
+
+  return `# System Spec — ${projectName}\n\n## Purpose\n\n${purpose}\n\n## Interface\n\n${iface}\n\n## Behavior\n\n${behavior}\n\n## Error Cases\n\n${errorCases}\n\n## Acceptance Tests\n\n${acceptance}\n\n## Open Questions\n\n- (Capture unresolved product or implementation questions here.)\n${extra}`;
+}
+
 export function validateGovernedProjectTemplate(templateId, source = 'agentxchain.json') {
   const effectiveTemplateId = templateId || 'generic';
   const effectiveSource = templateId ? source : 'implicit_default';

package/src/lib/intake-handoff.js

@@ -0,0 +1,58 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { safeWriteJson } from './safe-write.js';
+
+const HANDOFF_DIR = '.agentxchain/multirepo/handoffs';
+
+export function getCoordinatorHandoffDir(workspacePath) {
+  return join(workspacePath, HANDOFF_DIR);
+}
+
+export function getCoordinatorHandoffPath(workspacePath, intentId) {
+  return join(getCoordinatorHandoffDir(workspacePath), `${intentId}.json`);
+}
+
+export function writeCoordinatorHandoff(workspacePath, intentId, handoff) {
+  const dir = getCoordinatorHandoffDir(workspacePath);
+  mkdirSync(dir, { recursive: true });
+  const filePath = getCoordinatorHandoffPath(workspacePath, intentId);
+  safeWriteJson(filePath, handoff);
+  return filePath;
+}
+
+export function readCoordinatorHandoff(workspacePath, intentId) {
+  const filePath = getCoordinatorHandoffPath(workspacePath, intentId);
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function listCoordinatorHandoffs(workspacePath) {
+  const dir = getCoordinatorHandoffDir(workspacePath);
+  if (!existsSync(dir)) {
+    return [];
+  }
+
+  return readdirSync(dir)
+    .filter((entry) => entry.endsWith('.json') && !entry.startsWith('.tmp-'))
+    .map((entry) => {
+      try {
+        return JSON.parse(readFileSync(join(dir, entry), 'utf8'));
+      } catch {
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+export function listWorkstreamHandoffs(workspacePath, workstreamId, superRunId) {
+  return listCoordinatorHandoffs(workspacePath).filter((handoff) => (
+    handoff.workstream_id === workstreamId
+    && (!superRunId || handoff.super_run_id === superRunId)
+  ));
+}