agentxchain 2.55.0 → 2.57.0

package/bin/agentxchain.js

@@ -128,6 +128,7 @@ program
   .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, library, web-app, enterprise-app')
   .option('--dev-command <parts...>', 'Governed local-dev command parts. Include {prompt} for argv prompt delivery.')
   .option('--dev-prompt-transport <mode>', 'Governed local-dev prompt transport: argv, stdin, dispatch_bundle_only')
+  .option('--goal <text>', 'Project goal — persisted in config and rendered in every dispatch bundle')
   .option('--schema-version <version>', 'Schema version (3 for legacy, or use --governed for current)')
   .action(initCommand);
 

package/package.json

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

package/src/commands/demo.js

@@ -19,7 +19,7 @@ function makeConfig() {
   return {
     schema_version: 4,
     protocol_mode: 'governed',
-    project: { id: 'agentxchain-demo', name: 'AgentXchain Demo', default_branch: 'main' },
+    project: { id: 'agentxchain-demo', name: 'AgentXchain Demo', goal: 'Build an auth token rotation service with expiry, graceful rollover, and audit logging', default_branch: 'main' },
     roles: {
       pm: {
         title: 'Product Manager',

package/src/commands/init.js

@@ -656,12 +656,14 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
         .filter(Boolean)
     )].map((gateId) => [gateId, 'pending'])
   );
+  const projectGoal = runtimeOptions.goal;
   const config = {
     schema_version: '1.0',
     template: template.id,
     project: {
       id: projectId,
       name: projectName,
+      ...(typeof projectGoal === 'string' && projectGoal.trim() ? { goal: projectGoal.trim() } : {}),
       default_branch: 'main'
     },
     roles,
@@ -974,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/commands/status.js

@@ -89,6 +89,7 @@ function renderGovernedStatus(context, opts) {
       version,
       protocol_mode: config.protocol_mode,
       template: config.template || 'generic',
+      project_goal: config.project?.goal || null,
       config,
       state,
       provenance: state?.provenance || null,
@@ -106,6 +107,9 @@ function renderGovernedStatus(context, opts) {
   console.log('');
 
   console.log(`  ${chalk.dim('Project:')}  ${config.project.name}`);
+  if (config.project.goal) {
+    console.log(`  ${chalk.dim('Goal:')}     ${config.project.goal}`);
+  }
   console.log(`  ${chalk.dim('Protocol:')} ${chalk.cyan(`governed (v${version})`)}`);
   console.log(`  ${chalk.dim('Template:')} ${config.template || 'generic'}`);
   console.log(`  ${chalk.dim('Phase:')}    ${state?.phase ? formatGovernedPhase(state.phase) : chalk.dim('unknown')}`);

package/src/lib/dispatch-bundle.js

@@ -512,6 +512,15 @@ function renderContext(state, config, root, turn, role) {
   }
   lines.push('');
 
+  // Project goal (when set in agentxchain.json)
+  const projectGoal = config?.project?.goal;
+  if (typeof projectGoal === 'string' && projectGoal.trim()) {
+    lines.push('## Project Goal');
+    lines.push('');
+    lines.push(projectGoal.trim());
+    lines.push('');
+  }
+
   // Inherited context from parent run (when --inherit-context was used)
   if (state.inherited_context) {
     // First turn gets the full rendering; subsequent turns get compact

package/src/lib/export.js

@@ -295,11 +295,13 @@ export function buildRunExport(startDir = process.cwd()) {
       project: {
         id: config.project.id,
         name: config.project.name,
+        goal: config.project.goal || null,
         template: config.template || 'generic',
         protocol_mode: config.protocol_mode,
         schema_version: version,
       },
       summary: {
+        project_goal: config.project.goal || null,
         run_id: state?.run_id || null,
         status: state?.status || null,
         phase: state?.phase || null,

package/src/lib/normalized-config.js

@@ -340,6 +340,16 @@ export function validateV4Config(data, projectRoot) {
   } else {
     if (typeof data.project.id !== 'string' || !data.project.id.trim()) errors.push('project.id must be a non-empty string');
     if (typeof data.project.name !== 'string' || !data.project.name.trim()) errors.push('project.name must be a non-empty string');
+    // Optional project.goal field
+    if (data.project.goal !== undefined && data.project.goal !== null) {
+      if (typeof data.project.goal !== 'string') {
+        errors.push('project.goal must be a string');
+      } else if (!data.project.goal.trim()) {
+        errors.push('project.goal must be a non-empty string when provided');
+      } else if (data.project.goal.trim().length > 500) {
+        errors.push('project.goal must be 500 characters or fewer');
+      }
+    }
   }
 
   // Roles
@@ -968,6 +978,7 @@ export function normalizeV4(raw) {
     project: {
       id: raw.project?.id || 'unknown',
       name: raw.project?.name || 'Unknown',
+      ...(typeof raw.project?.goal === 'string' && raw.project.goal.trim() ? { goal: raw.project.goal.trim() } : {}),
       default_branch: raw.project?.default_branch || 'main',
     },
     roles,

package/src/lib/report.js

@@ -630,6 +630,7 @@ function buildRunSubject(artifact) {
     project: {
       id: artifact.project?.id || null,
       name: artifact.project?.name || null,
+      goal: artifact.project?.goal || null,
       template: artifact.project?.template || 'generic',
       protocol_mode: artifact.project?.protocol_mode || null,
       schema_version: artifact.project?.schema_version || null,
@@ -876,6 +877,7 @@ export function formatGovernanceReportText(report) {
       `Export kind: ${report.export_kind}`,
       'Verification: PASS',
       `Project: ${project.name || 'unknown'} (${project.id || 'unknown'})`,
+      ...(project.goal ? [`Goal: ${project.goal}`] : []),
       `Template: ${project.template}`,
       `Protocol: ${project.protocol_mode || 'unknown'} (config schema ${project.schema_version || 'unknown'})`,
       `Run: ${run.run_id || 'none'}`,
@@ -1285,6 +1287,7 @@ export function formatGovernanceReportMarkdown(report) {
       `- Export kind: \`${report.export_kind}\``,
       '- Verification: `pass`',
       `- Project: ${project.name || 'unknown'} (\`${project.id || 'unknown'}\`)`,
+      ...(project.goal ? [`- Goal: ${project.goal}`] : []),
       `- Template: \`${project.template}\``,
       `- Protocol: \`${project.protocol_mode || 'unknown'}\` (config schema \`${project.schema_version || 'unknown'}\`)`,
       `- Run: \`${run.run_id || 'none'}\``,

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;
+}