agentxchain 2.56.0 → 2.57.0

package/package.json

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

package/src/commands/init.js

@@ -976,6 +976,11 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.bold('agentxchain step')} ${chalk.dim('# run the first governed turn')}`);
   console.log(`    ${chalk.bold('agentxchain status')} ${chalk.dim('# inspect phase, gate, and turn state')}`);
   console.log('');
+  if (!config?.project?.goal) {
+    console.log(`  ${chalk.dim('Tip:')} Add a project goal to guide agent context:`);
+    console.log(`    ${chalk.bold('agentxchain init --governed --goal "Build a ..."')} ${chalk.dim('# or set project.goal in agentxchain.json')}`);
+    console.log('');
+  }
   console.log(`  ${chalk.dim('Guide:')} https://agentxchain.dev/docs/getting-started`);
   console.log('');
 }

package/src/lib/run-context-inheritance.js

@@ -57,6 +57,7 @@ export function buildInheritedContext(root, parentRunId) {
     parent_phases_completed: parentEntry.phases_completed || [],
     parent_roles_used: parentEntry.roles_used || [],
     parent_blocked_reason: parentEntry.blocked_reason || null,
+    parent_retrospective: parentEntry.retrospective || null,
     recent_decisions: recentDecisions,
     recent_accepted_turns: acceptedTurns,
     inherited_at: new Date().toISOString(),
@@ -93,6 +94,20 @@ export function renderInheritedContextMarkdown(inheritedContext, compact = false
   }
   lines.push('');
 
+  if (!compact && inheritedContext.parent_retrospective) {
+    lines.push('### Parent Retrospective');
+    lines.push('');
+    lines.push(`- **Headline:** ${inheritedContext.parent_retrospective.headline || 'n/a'}`);
+    lines.push(`- **Terminal reason:** ${inheritedContext.parent_retrospective.terminal_reason || 'unknown'}`);
+    if (inheritedContext.parent_retrospective.next_operator_action) {
+      lines.push(`- **Next operator action:** ${inheritedContext.parent_retrospective.next_operator_action}`);
+    }
+    if (inheritedContext.parent_retrospective.follow_on_hint) {
+      lines.push(`- **Follow-on hint:** ${inheritedContext.parent_retrospective.follow_on_hint}`);
+    }
+    lines.push('');
+  }
+
   if (!compact && inheritedContext.recent_decisions?.length) {
     lines.push('### Recent Decisions');
     lines.push('');
@@ -153,6 +168,7 @@ function buildPartialContext(parentRunId, parentEntry, decisions, turns, warning
     parent_phases_completed: parentEntry?.phases_completed || [],
     parent_roles_used: parentEntry?.roles_used || [],
     parent_blocked_reason: parentEntry?.blocked_reason || null,
+    parent_retrospective: parentEntry?.retrospective || null,
     recent_decisions: decisions,
     recent_accepted_turns: turns,
     inherited_at: new Date().toISOString(),

package/src/lib/run-history.js

@@ -10,6 +10,7 @@
 import { readFileSync, appendFileSync, existsSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
 import { normalizeRunProvenance } from './run-provenance.js';
+import { deriveRecoveryDescriptor } from './blocked-state.js';
 
 const RUN_HISTORY_PATH = '.agentxchain/run-history.jsonl';
 const HISTORY_PATH = '.agentxchain/history.jsonl';
@@ -83,6 +84,12 @@ export function recordRunHistory(root, state, config, status) {
       connector_used: connectorUsed,
       model_used: modelUsed,
       provenance: normalizeRunProvenance(state?.provenance),
+      retrospective: buildRunRetrospective({
+        state,
+        config,
+        status,
+        historyEntries,
+      }),
       inheritance_snapshot: {
         recent_decisions: buildRecentDecisionSnapshot(ledgerEntries),
         recent_accepted_turns: buildRecentAcceptedTurnSnapshot(historyEntries),
@@ -300,7 +307,7 @@ function buildRecentDecisionSnapshot(entries) {
 
 function buildRecentAcceptedTurnSnapshot(entries) {
   return entries
-    .filter((entry) => entry.status === 'accepted')
+    .filter((entry) => entry?.status !== 'rejected' && typeof entry?.turn_id === 'string' && typeof entry?.role === 'string')
     .slice(-MAX_INHERITANCE_TURNS)
     .map((entry) => ({
       turn_id: entry.turn_id || null,
@@ -309,3 +316,57 @@ function buildRecentAcceptedTurnSnapshot(entries) {
       phase: entry.phase || null,
     }));
 }
+
+function buildRunRetrospective({ state, config, status, historyEntries }) {
+  const acceptedTurns = historyEntries.filter((entry) => entry && typeof entry === 'object');
+  const lastAcceptedTurn = acceptedTurns[acceptedTurns.length - 1] || null;
+  const recovery = status === 'blocked'
+    ? deriveRecoveryDescriptor(state, config)
+    : null;
+
+  return {
+    headline: buildRetrospectiveHeadline({ status, lastAcceptedTurn, recovery, acceptedTurns }),
+    terminal_reason: status === 'completed'
+      ? 'completed'
+      : recovery?.typed_reason || 'blocked',
+    next_operator_action: status === 'blocked'
+      ? recovery?.recovery_action || null
+      : null,
+    follow_on_hint: status === 'completed'
+      ? buildFollowOnHint(state, lastAcceptedTurn)
+      : null,
+  };
+}
+
+function buildRetrospectiveHeadline({ status, lastAcceptedTurn, recovery, acceptedTurns }) {
+  if (status === 'blocked') {
+    if (typeof recovery?.detail === 'string' && recovery.detail.trim()) {
+      return recovery.detail.trim();
+    }
+    if (typeof lastAcceptedTurn?.summary === 'string' && lastAcceptedTurn.summary.trim()) {
+      return `Run blocked after: ${lastAcceptedTurn.summary.trim()}`;
+    }
+    return 'Run blocked.';
+  }
+
+  if (typeof lastAcceptedTurn?.summary === 'string' && lastAcceptedTurn.summary.trim()) {
+    return lastAcceptedTurn.summary.trim();
+  }
+
+  return `Run completed after ${acceptedTurns.length} accepted turn(s).`;
+}
+
+function buildFollowOnHint(state, lastAcceptedTurn) {
+  const runId = state?.run_id;
+  if (typeof runId !== 'string' || !runId.trim()) {
+    return null;
+  }
+
+  const base = `If more scope remains, start a child run with \`agentxchain run --continue-from ${runId} --inherit-context\`.`;
+  const suggestedRole = lastAcceptedTurn?.proposed_next_role;
+  if (typeof suggestedRole === 'string' && suggestedRole.trim() && suggestedRole !== 'human') {
+    return `${base} The last accepted turn suggested \`${suggestedRole}\` next.`;
+  }
+
+  return base;
+}