agentxchain 2.131.0 → 2.132.0

package/package.json

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

package/scripts/release-bump.sh

@@ -82,6 +82,9 @@ ALLOWED_RELEASE_PATHS=(
   ".planning/MARKETING/REDDIT_POSTS.md"
   ".planning/MARKETING/HN_SUBMISSION.md"
   "website-v2/static/llms.txt"
+  "website-v2/docs/getting-started.mdx"
+  "website-v2/docs/quickstart.mdx"
+  "website-v2/docs/five-minute-tutorial.mdx"
   "cli/homebrew/agentxchain.rb"
   "cli/homebrew/README.md"
 )

package/src/commands/events.js

@@ -65,6 +65,9 @@ function printEvent(evt) {
   const conflictDetail = evt.event_type === 'turn_conflicted'
     ? ` — ${formatConflictDetail(evt)}`
     : '';
+  const conflictResolvedDetail = evt.event_type === 'conflict_resolved'
+    ? ` — ${formatConflictResolvedDetail(evt)}`
+    : '';
   const rejectionDetail = evt.event_type === 'turn_rejected' && evt.payload?.reason
     ? ` — ${evt.payload.reason}${evt.payload.failed_stage ? ` (${evt.payload.failed_stage})` : ''}`
     : '';
@@ -82,7 +85,10 @@ function printEvent(evt) {
     : evt.event_type === 'human_escalation_resolved' && evt.payload?.escalation_id
       ? ` ${evt.payload.escalation_id} via ${evt.payload.resolved_via || '?'}`
       : '';
-  console.log(`${chalk.dim(ts)}  ${type}  ${chalk.cyan(runId)}  ${phase}${turnInfo}${intentInfo}${conflictDetail}${rejectionDetail}${acceptanceFailedDetail}${phaseTransitionDetail}${gateFailedDetail}${humanEscalationDetail}`);
+  const coordinatorRetryDetail = evt.event_type === 'coordinator_retry' && evt.payload
+    ? ` — ws ${evt.payload.workstream_id || '?'} repo ${evt.payload.repo_id || '?'} (retry of ${evt.payload.failed_turn_id || '?'})`
+    : '';
+  console.log(`${chalk.dim(ts)}  ${type}  ${chalk.cyan(runId)}  ${phase}${turnInfo}${intentInfo}${conflictDetail}${conflictResolvedDetail}${rejectionDetail}${acceptanceFailedDetail}${phaseTransitionDetail}${gateFailedDetail}${humanEscalationDetail}${coordinatorRetryDetail}`);
 }
 
 function formatConflictDetail(evt) {
@@ -105,6 +111,16 @@ function formatConflictDetail(evt) {
   return parts.filter(Boolean).join(' | ');
 }
 
+function formatConflictResolvedDetail(evt) {
+  const payload = evt.payload || {};
+  const fileSummary = summarizeList(payload.conflicting_files, 3) || 'resolved conflict';
+  const resolvedVia = payload.resolution ? `via ${payload.resolution}` : null;
+  const overlapRatio = typeof payload.overlap_ratio === 'number'
+    ? `${Math.round(payload.overlap_ratio * 100)}% overlap`
+    : null;
+  return [fileSummary, resolvedVia, overlapRatio].filter(Boolean).join(' | ');
+}
+
 function summarizeList(items, limit) {
   if (!Array.isArray(items) || items.length === 0) return '';
   const shown = items.slice(0, limit).join(', ');
@@ -123,6 +139,7 @@ function colorEventType(type) {
     acceptance_failed: chalk.red.bold,
     turn_reissued: chalk.cyan,
     turn_conflicted: chalk.redBright,
+    conflict_resolved: chalk.greenBright,
     phase_entered: chalk.magenta,
     escalation_raised: chalk.red.bold,
     escalation_resolved: chalk.green,
@@ -132,6 +149,9 @@ function colorEventType(type) {
     gate_approved: chalk.green,
     gate_failed: chalk.red,
     budget_exceeded_warn: chalk.yellowBright,
+    coordinator_retry: chalk.cyan.bold,
+    turn_checkpointed: chalk.green,
+    dispatch_progress: chalk.blue.dim,
   };
   const colorFn = colors[type] || chalk.white;
   return colorFn(pad(type, 22));

package/src/lib/governed-state.js

@@ -1088,15 +1088,63 @@ function cleanupTurnArtifacts(root, turnId) {
   } catch { /* best-effort */ }
 }
 
-function detectAcceptanceConflict(targetTurn, conflictFiles, historyEntries) {
+function getWorkflowArtifactOwners(config, filePath) {
+  const owners = new Set();
+  const phases = config?.workflow_kit?.phases;
+  if (!phases || typeof phases !== 'object') {
+    return owners;
+  }
+
+  for (const phaseConfig of Object.values(phases)) {
+    const artifacts = Array.isArray(phaseConfig?.artifacts) ? phaseConfig.artifacts : [];
+    for (const artifact of artifacts) {
+      if (artifact?.path !== filePath) {
+        continue;
+      }
+      if (typeof artifact.owned_by === 'string' && artifact.owned_by.length > 0) {
+        owners.add(artifact.owned_by);
+      }
+    }
+  }
+
+  return owners;
+}
+
+function isForwardRevisionFile(targetTurn, historyEntry, filePath, config) {
+  if (!targetTurn || !historyEntry) {
+    return false;
+  }
+  if (historyEntry.role !== targetTurn.assigned_role) {
+    return false;
+  }
+
+  const explicitOwners = getWorkflowArtifactOwners(config, filePath);
+  if (explicitOwners.size > 0) {
+    return explicitOwners.size === 1 && explicitOwners.has(targetTurn.assigned_role);
+  }
+
+  if (!filePath.startsWith('.planning/')) {
+    return false;
+  }
+
+  return config?.routing?.planning?.entry_role === targetTurn.assigned_role;
+}
+
+function classifyAcceptanceOverlap(targetTurn, conflictFiles, historyEntries, config) {
   const observedFiles = [...new Set(Array.isArray(conflictFiles) ? conflictFiles : [])];
   if (observedFiles.length === 0) {
-    return null;
+    return {
+      conflict: null,
+      forward_revision_files: [],
+      forward_revision_turns: [],
+    };
   }
 
   const observedFileSet = new Set(observedFiles);
   const acceptedSince = [];
   const conflictingFiles = new Set();
+  const forwardRevisionFiles = new Set();
+  const forwardRevisionTurns = new Map();
 
   for (const entry of historyEntries) {
     if ((entry.accepted_sequence || 0) <= (targetTurn.assigned_sequence || 0)) {
@@ -1108,35 +1156,77 @@ function detectAcceptanceConflict(targetTurn, conflictFiles, historyEntries) {
       continue;
     }
 
-    overlap.forEach(file => conflictingFiles.add(file));
-    acceptedSince.push({
-      turn_id: entry.turn_id,
-      role: entry.role,
-      accepted_sequence: entry.accepted_sequence,
-      files_changed: overlap,
-    });
+    const destructiveFiles = [];
+    const forwardFiles = [];
+    for (const file of overlap) {
+      if (isForwardRevisionFile(targetTurn, entry, file, config)) {
+        forwardFiles.push(file);
+      } else {
+        destructiveFiles.push(file);
+      }
+    }
+
+    if (destructiveFiles.length > 0) {
+      destructiveFiles.forEach(file => conflictingFiles.add(file));
+      acceptedSince.push({
+        turn_id: entry.turn_id,
+        role: entry.role,
+        accepted_sequence: entry.accepted_sequence,
+        files_changed: destructiveFiles,
+      });
+    }
+
+    if (forwardFiles.length > 0) {
+      forwardFiles.forEach(file => forwardRevisionFiles.add(file));
+      const existing = forwardRevisionTurns.get(entry.turn_id) || {
+        turn_id: entry.turn_id,
+        role: entry.role,
+        accepted_sequence: entry.accepted_sequence,
+        files_changed: [],
+      };
+      existing.files_changed = [...new Set([...existing.files_changed, ...forwardFiles])];
+      forwardRevisionTurns.set(entry.turn_id, existing);
+    }
   }
 
+  const forwardRevisionContext = {
+    files: [...forwardRevisionFiles],
+    accepted_since_turn_ids: [...forwardRevisionTurns.values()].map((entry) => entry.turn_id),
+    accepted_since: [...forwardRevisionTurns.values()],
+  };
+
   if (acceptedSince.length === 0) {
-    return null;
+    return {
+      conflict: null,
+      forward_revision_files: forwardRevisionContext.files,
+      forward_revision_turns: forwardRevisionContext.accepted_since,
+    };
   }
 
   const conflicting = [...conflictingFiles];
   const overlapRatio = observedFiles.length > 0 ? conflicting.length / observedFiles.length : 0;
 
   return {
-    type: 'file_conflict',
-    conflicting_turn: {
-      turn_id: targetTurn.turn_id,
-      role: targetTurn.assigned_role,
-      attempt: targetTurn.attempt,
-      files_changed: observedFiles,
+    conflict: {
+      type: 'file_conflict',
+      conflicting_turn: {
+        turn_id: targetTurn.turn_id,
+        role: targetTurn.assigned_role,
+        attempt: targetTurn.attempt,
+        files_changed: observedFiles,
+      },
+      accepted_since: acceptedSince,
+      conflicting_files: conflicting,
+      non_conflicting_files: observedFiles.filter(
+        (file) => !conflictingFiles.has(file) && !forwardRevisionFiles.has(file),
+      ),
+      forward_revision_files: forwardRevisionContext.files,
+      forward_revision_turns: forwardRevisionContext.accepted_since,
+      overlap_ratio: overlapRatio,
+      suggested_resolution: overlapRatio < 0.5 ? 'reject_and_reassign' : 'human_merge',
     },
-    accepted_since: acceptedSince,
-    conflicting_files: conflicting,
-    non_conflicting_files: observedFiles.filter(file => !conflictingFiles.has(file)),
-    overlap_ratio: overlapRatio,
-    suggested_resolution: overlapRatio < 0.5 ? 'reject_and_reassign' : 'human_merge',
+    forward_revision_files: forwardRevisionContext.files,
+    forward_revision_turns: forwardRevisionContext.accepted_since,
   };
 }
 
@@ -2749,40 +2839,6 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         error_code: 'protocol_error',
       };
     }
-
-    if (currentTurn.conflict_state.status !== 'human_merging') {
-      appendJsonl(root, LEDGER_PATH, {
-        timestamp: new Date().toISOString(),
-        decision: 'conflict_resolution_selected',
-        turn_id: currentTurn.turn_id,
-        attempt: currentTurn.attempt,
-        role: currentTurn.assigned_role,
-        phase: state.phase,
-        conflict: {
-          conflicting_files: currentTurn.conflict_state.conflict_error?.conflicting_files || [],
-          accepted_since_turn_ids: (currentTurn.conflict_state.conflict_error?.accepted_since || []).map((entry) => entry.turn_id),
-          overlap_ratio: currentTurn.conflict_state.conflict_error?.overlap_ratio ?? 0,
-        },
-        resolution_chosen: 'human_merge',
-      });
-
-      state = {
-        ...state,
-        active_turns: {
-          ...getActiveTurns(state),
-          [currentTurn.turn_id]: {
-            ...currentTurn,
-            status: 'conflicted',
-            conflict_state: {
-              ...currentTurn.conflict_state,
-              status: 'human_merging',
-            },
-          },
-        },
-      };
-      writeState(root, state);
-      currentTurn = state.active_turns[currentTurn.turn_id];
-    }
   }
 
   const turnStagingPath = getTurnStagingResultPath(currentTurn.turn_id);
@@ -3142,11 +3198,29 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     };
   }
 
-  const conflict = detectAcceptanceConflict(
+  const overlapClassification = classifyAcceptanceOverlap(
     currentTurn,
     buildConflictCandidateFiles(rawObservation, observation, turnResult.files_changed || []),
     historyEntries,
+    config,
   );
+  const forwardRevision = overlapClassification.forward_revision_files.length > 0
+    ? {
+        files: overlapClassification.forward_revision_files,
+        accepted_since_turn_ids: overlapClassification.forward_revision_turns.map((entry) => entry.turn_id),
+        accepted_since: overlapClassification.forward_revision_turns,
+      }
+    : null;
+  const conflict = resolutionMode === 'human_merge' ? null : overlapClassification.conflict;
+  const conflictResolution = resolutionMode === 'human_merge'
+    ? {
+        mode: 'human_merge',
+        merge_strategy: 'operator_authoritative_staged_result',
+        conflicting_files: currentTurn.conflict_state?.conflict_error?.conflicting_files || [],
+        accepted_since_turn_ids: (currentTurn.conflict_state?.conflict_error?.accepted_since || []).map((entry) => entry.turn_id),
+        overlap_ratio: currentTurn.conflict_state?.conflict_error?.overlap_ratio ?? 0,
+      }
+    : null;
 
   if (conflict) {
     const detectionCount = (currentTurn.conflict_state?.detection_count || 0) + 1;
@@ -3301,6 +3375,8 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     assigned_sequence: Number.isInteger(currentTurn.assigned_sequence) ? currentTurn.assigned_sequence : acceptedSequence,
     accepted_sequence: acceptedSequence,
     concurrent_with: Array.isArray(currentTurn.concurrent_with) ? currentTurn.concurrent_with : [],
+    ...(forwardRevision ? { forward_revision: forwardRevision } : {}),
+    ...(conflictResolution ? { conflict_resolution: conflictResolution } : {}),
     cost: turnResult.cost || {},
     ...(currentTurn.started_at ? { started_at: currentTurn.started_at } : {}),
     accepted_at: now,
@@ -3357,6 +3433,49 @@ function _acceptGovernedTurnLocked(root, config, opts) {
       });
     }
   }
+  if (forwardRevision) {
+    ledgerEntries.push({
+      timestamp: now,
+      decision: 'forward_revision_accepted',
+      turn_id: currentTurn.turn_id,
+      attempt: currentTurn.attempt,
+      role: currentTurn.assigned_role,
+      phase: state.phase,
+      forward_revision: {
+        files: forwardRevision.files,
+        accepted_since_turn_ids: forwardRevision.accepted_since_turn_ids,
+      },
+    });
+  }
+  if (conflictResolution) {
+    const conflictSummary = {
+      conflicting_files: conflictResolution.conflicting_files,
+      accepted_since_turn_ids: conflictResolution.accepted_since_turn_ids,
+      overlap_ratio: conflictResolution.overlap_ratio,
+    };
+    ledgerEntries.push({
+      timestamp: now,
+      decision: 'conflict_resolution_selected',
+      turn_id: currentTurn.turn_id,
+      attempt: currentTurn.attempt,
+      role: currentTurn.assigned_role,
+      phase: state.phase,
+      conflict: conflictSummary,
+      resolution_chosen: conflictResolution.mode,
+      merge_strategy: conflictResolution.merge_strategy,
+    });
+    ledgerEntries.push({
+      timestamp: now,
+      decision: 'conflict_resolved',
+      turn_id: currentTurn.turn_id,
+      attempt: currentTurn.attempt,
+      role: currentTurn.assigned_role,
+      phase: state.phase,
+      conflict: conflictSummary,
+      resolution_chosen: conflictResolution.mode,
+      merge_strategy: conflictResolution.merge_strategy,
+    });
+  }
 
   const turnNumber = turnResult.turn_id.replace(/^turn_/, '').slice(0, 8);
   const talkSection = `## Turn ${turnNumber} — ${turnResult.role} (${state.phase})\n\n- **Status:** ${turnResult.status}\n- **Summary:** ${turnResult.summary}\n${turnResult.decisions?.length ? turnResult.decisions.map(d => `- **Decision ${d.id}:** ${d.statement}`).join('\n') + '\n' : ''}${turnResult.objections?.length ? turnResult.objections.map(o => `- **Objection ${o.id} (${o.severity}):** ${o.statement}`).join('\n') + '\n' : ''}- **Proposed next:** ${turnResult.proposed_next_role || 'human'}\n\n---\n`;
@@ -4107,6 +4226,22 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     intent_id: currentTurn.intake_context?.intent_id || null,
     payload: turnAcceptedPayload,
   });
+  if (conflictResolution) {
+    emitRunEvent(root, 'conflict_resolved', {
+      run_id: updatedState.run_id,
+      phase: updatedState.phase,
+      status: updatedState.status,
+      turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+      intent_id: currentTurn.intake_context?.intent_id || null,
+      payload: {
+        resolution: conflictResolution.mode,
+        merge_strategy: conflictResolution.merge_strategy,
+        conflicting_files: conflictResolution.conflicting_files,
+        accepted_since_turn_ids: conflictResolution.accepted_since_turn_ids,
+        overlap_ratio: conflictResolution.overlap_ratio,
+      },
+    });
+  }
 
   if (updatedState.status === 'blocked') {
     // DEC-RHTR-SPEC: Record blocked outcome in cross-run history (non-fatal)

package/src/lib/recent-event-summary.js

@@ -36,6 +36,21 @@ function describeEvent(eventType, entry) {
     case 'gate_approved':
     case 'gate_failed':
       return `${prefix}${eventType}${gateId ? ` (${gateId})` : ''}`;
+    case 'turn_conflicted':
+      return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
+    case 'conflict_resolved': {
+      const resolution = trimToNull(entry.payload?.resolution);
+      return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}${resolution ? ` via ${resolution}` : ''}`;
+    }
+    case 'coordinator_retry': {
+      const wsId = trimToNull(entry.payload?.workstream_id);
+      const retryRepo = trimToNull(entry.payload?.repo_id);
+      return `${prefix}${eventType}${wsId ? ` ${wsId}` : ''}${retryRepo ? ` (${retryRepo})` : ''}`;
+    }
+    case 'turn_checkpointed':
+      return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
+    case 'dispatch_progress':
+      return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
     case 'run_blocked':
     case 'run_completed':
     case 'run_started':

package/src/lib/release-alignment.js

@@ -22,6 +22,12 @@ export function formatCount(value) {
   return new Intl.NumberFormat('en-US').format(value);
 }
 
+const ONBOARDING_PREREQ_DOCS = [
+  'website-v2/docs/getting-started.mdx',
+  'website-v2/docs/quickstart.mdx',
+  'website-v2/docs/five-minute-tutorial.mdx',
+];
+
 function normalizeEvidenceText(value) {
   return value
     .replace(/^\s*-\s*/, '')
@@ -137,6 +143,28 @@ function validateTextIncludesVersionAndEvidence(relativePath, label) {
   };
 }
 
+function validateOnboardingPrereqs(ctx, repoRoot) {
+  const errors = [];
+  const requiredTokens = [
+    `Minimum CLI version: \`agentxchain ${ctx.targetVersion}\` or newer`,
+    'agentxchain --version',
+    'npm install -g agentxchain@latest',
+    'brew upgrade agentxchain',
+    'npx --yes -p agentxchain@latest -c "agentxchain <command>"',
+  ];
+
+  for (const relativePath of ONBOARDING_PREREQ_DOCS) {
+    const content = read(repoRoot, relativePath);
+    for (const token of requiredTokens) {
+      if (!content.includes(token)) {
+        errors.push(`${relativePath} must include: ${token}`);
+      }
+    }
+  }
+
+  return errors;
+}
+
 export const RELEASE_ALIGNMENT_SURFACES = [
   {
     id: 'changelog',
@@ -274,6 +302,12 @@ export const RELEASE_ALIGNMENT_SURFACES = [
         : [`website-v2/static/llms.txt must list ${ctx.releaseRoute}`];
     },
   },
+  {
+    id: 'onboarding_prereqs',
+    label: 'onboarding docs CLI-version prerequisites',
+    scopes: [RELEASE_ALIGNMENT_SCOPES.PREBUMP, RELEASE_ALIGNMENT_SCOPES.CURRENT],
+    check: validateOnboardingPrereqs,
+  },
   {
     id: 'homebrew_formula_url',
     label: 'homebrew mirror formula url',

package/src/lib/run-events.js

@@ -18,6 +18,7 @@ export const VALID_RUN_EVENTS = [
   'turn_accepted',
   'turn_rejected',
   'turn_conflicted',
+  'conflict_resolved',
   'acceptance_failed',
   'turn_reissued',
   'turn_checkpointed',