agentxchain 2.157.0 → 2.159.0

package/bin/agentxchain.js

@@ -124,6 +124,8 @@ import { benchmarkCommand } from '../src/commands/benchmark.js';
 import { benchmarkWorkloadsCommand } from '../src/commands/benchmark-workloads.js';
 import { historyCommand } from '../src/commands/history.js';
 import { decisionsCommand } from '../src/commands/decisions.js';
+import { shipStatusCommand } from '../src/commands/ship-status.js';
+import { attentionCommand } from '../src/commands/attention.js';
 import { diffCommand } from '../src/commands/diff.js';
 import { eventsCommand } from '../src/commands/events.js';
 import { connectorCapabilitiesCommand, connectorCheckCommand, connectorValidateCommand } from '../src/commands/connector.js';
@@ -420,6 +422,22 @@ program
   .option('-d, --dir <path>', 'Project directory')
   .action(decisionsCommand);
 
+program
+  .command('ship-status')
+  .description('Evaluate whether the current project is ready to ship')
+  .option('-j, --json', 'Machine-readable JSON output')
+  .option('-v, --verbose', 'Per-dimension detail breakdown')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(shipStatusCommand);
+
+program
+  .command('attention')
+  .description('Show the cross-run human-decision queue — what needs you, and nothing else (govern by exception)')
+  .option('-j, --json', 'Machine-readable JSON output (full HumanAttentionReport)')
+  .option('-a, --all', 'Include informational/non-blocking items (e.g. pending approved intents)')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(attentionCommand);
+
 program
   .command('diff <left_ref> <right_ref>')
   .description('Compare two recorded governed runs or two export artifacts')
@@ -953,6 +971,12 @@ roleCmd
   .option('-j, --json', 'Output as JSON')
   .action((roleId, opts) => roleCommand('show', roleId, opts));
 
+roleCmd
+  .command('validate [role_id]')
+  .description('Validate role charter well-formedness against the four VISION:123–128 invariants (exit 1 if any role incomplete)')
+  .option('-j, --json', 'Output as JSON')
+  .action((roleId, opts) => roleCommand('validate', roleId, opts));
+
 const turnCmd = program
   .command('turn')
   .description('Inspect active governed turn dispatch bundles');

package/package.json

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

package/src/commands/attention.js

@@ -0,0 +1,66 @@
+/**
+ * CLI command: agentxchain attention
+ *
+ * Answers "what needs MY attention right now — and nothing else?" by composing the
+ * cross-category human-decision queue into a single HumanAttentionReport. All evaluation
+ * logic lives in lib/human-attention.js — this command is presentation only
+ * (Architecture Invariant #6).
+ *
+ * It is a status surface, not a gate: it exits 0 in BOTH the clear and attention states.
+ * When the queue is empty it prints "Nothing needs your attention." — the operational
+ * proof that the human can step back and let governed autonomy run (VISION.md:51).
+ */
+
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import { evaluateHumanAttention } from '../lib/human-attention.js';
+
+export async function attentionCommand(opts) {
+  const dir = opts.dir ? resolve(opts.dir) : process.cwd();
+  const root = findProjectRoot(dir);
+  if (!root) {
+    console.error(chalk.red('No agentxchain project found. Run "agentxchain init" first.'));
+    process.exitCode = 1;
+    return;
+  }
+
+  const report = evaluateHumanAttention(root);
+
+  if (opts.json) {
+    // --json always emits the full, schema-valid HumanAttentionReport; exit 0 in both states.
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  if (report.overall === 'clear') {
+    console.log(chalk.green('Nothing needs your attention.'));
+    return;
+  }
+
+  // Default view surfaces blocking + escalation items first; informational pending-intent
+  // items are summarized as a count unless --all is passed.
+  const visible = opts.all ? report.items : report.items.filter((item) => item.blocking);
+  const hidden = report.items.length - visible.length;
+
+  console.log(
+    `\n${chalk.bold('Attention needed')}: ${report.items_count} `
+    + `item${report.items_count === 1 ? '' : 's'} (${report.blocking_count} blocking)`,
+  );
+
+  visible.forEach((item, idx) => {
+    const tag = chalk.cyan(String(item.category).padEnd(16));
+    const run = item.run_id ? `${chalk.dim(item.run_id)} ` : '';
+    console.log(`  [${idx + 1}] ${tag} ${run}${item.summary}`);
+    console.log(`      ${chalk.dim('→')} ${item.action_hint}`);
+  });
+
+  if (hidden > 0) {
+    console.log(
+      chalk.dim(`  (+${hidden} informational item${hidden === 1 ? '' : 's'} — run with --all to show)`),
+    );
+  }
+
+  console.log('');
+  // Status surface, not a gate — no non-zero exit even in the attention state.
+}

package/src/commands/role.js

@@ -4,6 +4,10 @@ import {
   getRoleRuntimeCapabilityContract,
   summarizeRuntimeCapabilityContract,
 } from '../lib/runtime-capabilities.js';
+import {
+  evaluateRoleCharter,
+  evaluateAllRoleCharters,
+} from '../lib/role-charter.js';
 
 export function roleCommand(subcommand, roleId, opts) {
   const context = loadProjectContext();
@@ -12,7 +16,7 @@ export function roleCommand(subcommand, roleId, opts) {
     process.exit(1);
   }
 
-  const { config, version } = context;
+  const { config, rawConfig, version } = context;
 
   if (version !== 4) {
     console.log(chalk.red('  Not a governed AgentXchain project (requires v4 config).'));
@@ -27,6 +31,10 @@ export function roleCommand(subcommand, roleId, opts) {
     return showRole(roleId, roles, runtimes, roleIds, opts);
   }
 
+  if (subcommand === 'validate') {
+    return validateRoles(roleId, config, rawConfig, roleIds, opts);
+  }
+
   // Default: list
   return listRoles(roles, runtimes, roleIds, opts);
 }
@@ -155,3 +163,63 @@ function showRole(roleId, roles, runtimes, roleIds, opts) {
   }
   console.log('');
 }
+
+function renderCharterReport(report) {
+  const mark = report.overall === 'well_formed' ? chalk.green('✓') : chalk.red('✗');
+  if (report.overall === 'well_formed') {
+    console.log(`  ${mark} ${chalk.cyan(report.role_id)} well-formed (4/4 invariants)`);
+    return;
+  }
+  console.log(`  ${mark} ${chalk.cyan(report.role_id)} incomplete — missing: ${report.missing.join(', ')}`);
+  for (const inv of report.invariants) {
+    if (!inv.satisfied && inv.fix_hint) {
+      console.log(chalk.dim(`      → ${inv.fix_hint}`));
+    }
+  }
+}
+
+function validateRoles(roleId, config, rawConfig, roleIds, opts) {
+  // Single-role validation
+  if (roleId) {
+    if (!config.roles?.[roleId]) {
+      console.log(chalk.red(`  Unknown role: ${roleId}`));
+      console.log(chalk.dim(`  Available: ${roleIds.join(', ')}`));
+      process.exit(1);
+    }
+    const report = evaluateRoleCharter(config, rawConfig, roleId);
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log('');
+      renderCharterReport(report);
+      console.log('');
+    }
+    process.exit(report.overall === 'well_formed' ? 0 : 1);
+  }
+
+  // All-roles validation
+  const all = evaluateAllRoleCharters(config, rawConfig);
+  if (opts.json) {
+    console.log(JSON.stringify(all, null, 2));
+    process.exit(all.incomplete === 0 ? 0 : 1);
+  }
+
+  if (all.total === 0) {
+    console.log('  No roles defined.');
+    process.exit(0);
+  }
+
+  if (all.incomplete === 0) {
+    console.log(chalk.bold(`\n  Role charter validation (${all.total} roles): all well-formed (4/4 invariants each).\n`));
+    process.exit(0);
+  }
+
+  console.log(chalk.bold(`\n  Role charter validation (${all.total} roles):\n`));
+  for (const report of all.roles) {
+    renderCharterReport(report);
+  }
+  console.log('');
+  console.log(`  ${all.incomplete} of ${all.total} roles incomplete.`);
+  console.log('');
+  process.exit(1);
+}

package/src/commands/ship-status.js

@@ -0,0 +1,104 @@
+/**
+ * CLI command: agentxchain ship-status
+ *
+ * Answers "is this ready to ship?" by composing five evidence dimensions into a
+ * single ShipStatusReport. All evaluation logic lives in lib/ship-status.js — this
+ * command is presentation only (Architecture Invariant #5).
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import chalk from 'chalk';
+import { findProjectRoot } from '../lib/config.js';
+import { COORDINATOR_CONFIG_FILE } from '../lib/coordinator-config.js';
+import { evaluateShipStatus, evaluateCoordinatorShipStatus } from '../lib/ship-status.js';
+
+function statusIcon(status) {
+  if (status === 'pass') return chalk.green('✓');
+  if (status === 'fail') return chalk.red('✗');
+  return chalk.yellow('?');
+}
+
+function overallLabel(overall) {
+  if (overall === 'pass') return chalk.green.bold('YES');
+  if (overall === 'fail') return chalk.red.bold('NO');
+  return chalk.yellow.bold('PENDING');
+}
+
+function countPassed(report) {
+  return (report.dimensions || []).filter((d) => d.status === 'pass').length;
+}
+
+function printDimensions(dimensions, indent) {
+  for (const dim of dimensions || []) {
+    console.log(`${indent}${statusIcon(dim.status)}  ${dim.name}: ${dim.detail}`);
+  }
+}
+
+function printSingle(report, opts) {
+  const passed = countPassed(report);
+  const total = (report.dimensions || []).length;
+  const blocking = report.blocking_reasons || [];
+  const suffix = blocking.length ? `, ${blocking.length} blocking` : '';
+  console.log(`\nShip Status: ${overallLabel(report.overall)} (${passed}/${total} dimensions pass${suffix})`);
+
+  if (opts.verbose) {
+    console.log('');
+    printDimensions(report.dimensions, '  ');
+  } else {
+    for (const reason of blocking) {
+      console.log(`  ${chalk.dim('-')} ${reason}`);
+    }
+  }
+  console.log('');
+}
+
+export async function shipStatusCommand(opts) {
+  const dir = opts.dir ? resolve(opts.dir) : process.cwd();
+  const coordinatorConfigPath = join(dir, COORDINATOR_CONFIG_FILE);
+
+  let report;
+  let isCoordinator = false;
+
+  if (existsSync(coordinatorConfigPath)) {
+    isCoordinator = true;
+    report = evaluateCoordinatorShipStatus(dir);
+  } else {
+    const root = findProjectRoot(dir);
+    if (!root) {
+      console.error(chalk.red('No agentxchain project found. Run "agentxchain init" first.'));
+      process.exitCode = 1;
+      return;
+    }
+    report = evaluateShipStatus(root);
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (isCoordinator) {
+    const blocking = report.blocking_repos || [];
+    const total = (report.repos || []).length;
+    const shippable = total - blocking.length;
+    console.log(`\nCoordinator Ship Status: ${overallLabel(report.overall)} (${shippable}/${total} repos shippable)`);
+    for (const entry of report.repos || []) {
+      const passed = countPassed(entry.ship_status);
+      const dimTotal = (entry.ship_status.dimensions || []).length;
+      console.log(`\n  ${chalk.bold(entry.repo_id)}: ${overallLabel(entry.ship_status.overall)} (${passed}/${dimTotal})`);
+      if (opts.verbose) {
+        printDimensions(entry.ship_status.dimensions, '    ');
+      } else {
+        for (const reason of entry.ship_status.blocking_reasons || []) {
+          console.log(`    ${chalk.dim('-')} ${reason}`);
+        }
+      }
+    }
+    console.log('');
+  } else {
+    printSingle(report, opts);
+  }
+
+  // Non-zero exit when not shippable (useful for CI gating).
+  if (report.overall === 'fail') {
+    process.exitCode = 1;
+  }
+}

package/src/lib/dispatch-bundle.js

@@ -471,6 +471,18 @@ function renderPrompt(role, roleId, turn, state, config, root) {
     lines.push('');
   }
 
+  // Single-shot execution model — prevents ghost turns from async / background-wait patterns.
+  lines.push('## Single-Shot Execution (read carefully)');
+  lines.push('');
+  lines.push('You run as a **single, non-interactive `--print` subprocess**. You get exactly ONE invocation with no "later": there is no async wake-up, no second message, and nothing will notify you after you stop responding. The moment you end your turn the subprocess exits — if you have not written your turn result by then, the entire turn is **discarded as a ghost** (no result, wasted run).');
+  lines.push('');
+  lines.push('Therefore:');
+  lines.push('- Do ALL work **synchronously** within this one turn. Run every command to completion in the foreground and read its output inline before continuing.');
+  lines.push('- **NEVER** start a background job and then wait for it. Do not use `ScheduleWakeup`; do not start a `Monitor` or `tail -f` and wait for events; do not background a process with `&` and poll for a notification; do not defer any conclusion to "after the suite/build finishes". You will not be re-invoked to finish.');
+  lines.push('- If you need a long command or test suite result, run it **blocking in the foreground** (e.g. `npm test`) and wait for it to return in-line — the per-turn timeout is generous, so budget your time for it.');
+  lines.push('- Writing the structured turn result below is your **final action**: gather every piece of evidence first, then write the result before you finish.');
+  lines.push('');
+
   // Output format with complete JSON template
   lines.push('## Required Output');
   lines.push('');