agentxchain 2.92.0 → 2.94.0

package/bin/agentxchain.js

@@ -113,6 +113,7 @@ import { intakeResolveCommand } from '../src/commands/intake-resolve.js';
 import { intakeStatusCommand } from '../src/commands/intake-status.js';
 import { demoCommand } from '../src/commands/demo.js';
 import { historyCommand } from '../src/commands/history.js';
+import { decisionsCommand } from '../src/commands/decisions.js';
 import { diffCommand } from '../src/commands/diff.js';
 import { eventsCommand } from '../src/commands/events.js';
 import { connectorCheckCommand } from '../src/commands/connector.js';
@@ -157,7 +158,7 @@ program
 program
   .command('audit')
   .description('Render a governance audit directly from the current governed project or coordinator workspace')
-  .option('--format <format>', 'Output format: text, json, or markdown', 'text')
+  .option('--format <format>', 'Output format: text, json, markdown, or html', 'text')
   .action(auditCommand);
 
 program
@@ -176,7 +177,7 @@ program
   .command('report')
   .description('Render a human-readable governance summary from an export artifact')
   .option('--input <path>', 'Export artifact path, or "-" for stdin', '-')
-  .option('--format <format>', 'Output format: text, json, or markdown', 'text')
+  .option('--format <format>', 'Output format: text, json, markdown, or html', 'text')
   .action(reportCommand);
 
 program
@@ -333,6 +334,15 @@ program
   .option('-d, --dir <path>', 'Project directory')
   .action(historyCommand);
 
+program
+  .command('decisions')
+  .description('Show repo-level decisions that persist across governed runs')
+  .option('-j, --json', 'Output as JSON')
+  .option('-a, --all', 'Include overridden decisions')
+  .option('-s, --show <id>', 'Show details for a specific decision (e.g. DEC-042)')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(decisionsCommand);
+
 program
   .command('diff <left_run_id> <right_run_id>')
   .description('Compare two recorded governed runs from run-history')

package/package.json

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

package/src/commands/audit.js

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import { buildCoordinatorExport, buildRunExport } from '../lib/export.js';
 import {
   buildGovernanceReport,
+  formatGovernanceReportHtml,
   formatGovernanceReportMarkdown,
   formatGovernanceReportText,
 } from '../lib/report.js';
@@ -43,6 +44,11 @@ function printAndExit(report, format, exitCode) {
     process.exit(exitCode);
   }
 
+  if (format === 'html') {
+    console.log(formatGovernanceReportHtml(report));
+    process.exit(exitCode);
+  }
+
   if (format === 'text') {
     if (report.overall === 'error' || report.overall === 'fail') {
       console.log(chalk.red(formatGovernanceReportText(report)));
@@ -52,7 +58,7 @@ function printAndExit(report, format, exitCode) {
     process.exit(exitCode);
   }
 
-  console.error(`Unsupported audit format "${format}". Use "text", "json", or "markdown".`);
+  console.error(`Unsupported audit format "${format}". Use "text", "json", "markdown", or "html".`);
   process.exit(2);
 }
 

package/src/commands/decisions.js

@@ -0,0 +1,94 @@
+/**
+ * agentxchain decisions — cross-run decision carryover surface.
+ *
+ * Shows repo-level decisions that persist across governed runs.
+ */
+
+import { resolve } from 'path';
+import { existsSync } from 'fs';
+import chalk from 'chalk';
+import { readRepoDecisions, getActiveRepoDecisions, getRepoDecisionById } from '../lib/repo-decisions.js';
+
+/**
+ * @param {object} opts - { json?: boolean, all?: boolean, show?: string, dir?: string }
+ */
+export async function decisionsCommand(opts) {
+  const root = findProjectRoot(opts.dir || process.cwd());
+  if (!root) {
+    console.error(chalk.red('No AgentXchain project found. Run this inside a governed project.'));
+    process.exit(1);
+  }
+
+  // ── Show single decision ───────────────────────────────────────────────
+  if (opts.show) {
+    const dec = getRepoDecisionById(root, opts.show);
+    if (!dec) {
+      console.error(chalk.red(`Decision ${opts.show} not found in repo decisions.`));
+      process.exit(1);
+    }
+    if (opts.json) {
+      console.log(JSON.stringify(dec, null, 2));
+      return;
+    }
+    console.log(chalk.bold(`Decision ${dec.id}`));
+    console.log(`  Category:    ${dec.category}`);
+    console.log(`  Statement:   ${dec.statement}`);
+    console.log(`  Rationale:   ${dec.rationale}`);
+    console.log(`  Status:      ${formatStatus(dec.status)}`);
+    console.log(`  Role:        ${dec.role || '—'}`);
+    console.log(`  Phase:       ${dec.phase || '—'}`);
+    console.log(`  Run:         ${(dec.run_id || '—').slice(0, 16)}`);
+    console.log(`  Turn:        ${(dec.turn_id || '—').slice(0, 16)}`);
+    console.log(`  Created:     ${dec.created_at || '—'}`);
+    if (dec.overridden_by) {
+      console.log(`  Overridden:  ${chalk.yellow(dec.overridden_by)}`);
+    }
+    return;
+  }
+
+  // ── List decisions ─────────────────────────────────────────────────────
+  const decisions = opts.all ? readRepoDecisions(root) : getActiveRepoDecisions(root);
+
+  if (opts.json) {
+    console.log(JSON.stringify(decisions, null, 2));
+    return;
+  }
+
+  if (decisions.length === 0) {
+    console.log(chalk.dim('No repo-level decisions found.'));
+    if (!opts.all) {
+      console.log(chalk.dim('Use --all to include overridden decisions.'));
+    }
+    return;
+  }
+
+  const label = opts.all ? 'Repo Decisions (all)' : 'Active Repo Decisions';
+  console.log(chalk.bold(`${label}: ${decisions.length}`));
+  console.log('');
+
+  for (const dec of decisions) {
+    const status = formatStatus(dec.status);
+    const runShort = (dec.run_id || '').slice(0, 12);
+    const override = dec.overridden_by ? chalk.dim(` → ${dec.overridden_by}`) : '';
+    console.log(`  ${chalk.cyan(dec.id)}  ${status}  ${chalk.dim(dec.category)}  ${dec.statement}${override}`);
+    console.log(`    ${chalk.dim(`by ${dec.role || '?'} in ${runShort || '?'}`)}`);
+  }
+}
+
+function formatStatus(status) {
+  if (status === 'active') return chalk.green('active');
+  if (status === 'overridden') return chalk.yellow('overridden');
+  return chalk.dim(status || '—');
+}
+
+function findProjectRoot(dir) {
+  let current = resolve(dir);
+  while (current !== '/') {
+    if (existsSync(resolve(current, 'agentxchain.json'))) return current;
+    if (existsSync(resolve(current, '.agentxchain'))) return current;
+    const parent = resolve(current, '..');
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}

package/src/commands/report.js

@@ -3,6 +3,7 @@ import chalk from 'chalk';
 import { loadExportArtifact } from '../lib/export-verifier.js';
 import {
   buildGovernanceReport,
+  formatGovernanceReportHtml,
   formatGovernanceReportMarkdown,
   formatGovernanceReportText,
 } from '../lib/report.js';
@@ -18,6 +19,11 @@ function printAndExit(report, format, exitCode) {
     process.exit(exitCode);
   }
 
+  if (format === 'html') {
+    console.log(formatGovernanceReportHtml(report));
+    process.exit(exitCode);
+  }
+
   if (format === 'text') {
     if (report.overall === 'error') {
       console.log(chalk.red(formatGovernanceReportText(report)));
@@ -29,7 +35,7 @@ function printAndExit(report, format, exitCode) {
     process.exit(exitCode);
   }
 
-  console.error(`Unsupported report format "${format}". Use "text", "json", or "markdown".`);
+  console.error(`Unsupported report format "${format}". Use "text", "json", "markdown", or "html".`);
   process.exit(1);
 }
 

package/src/commands/status.js

@@ -105,6 +105,7 @@ function renderGovernedStatus(context, opts) {
       state,
       provenance: state?.provenance || null,
       inherited_context: state?.inherited_context || null,
+      repo_decisions: state?.repo_decisions || null,
       continuity,
       connector_health: connectorHealth,
       workflow_kit_artifacts: workflowKitArtifacts,
@@ -133,6 +134,9 @@ function renderGovernedStatus(context, opts) {
   if (state?.inherited_context?.parent_run_id) {
     console.log(`  ${chalk.dim('Inherits:')} ${chalk.magenta(`parent ${state.inherited_context.parent_run_id} (${state.inherited_context.parent_status || 'unknown'})`)}`);
   }
+  if (state?.repo_decisions?.length > 0) {
+    console.log(`  ${chalk.dim('Repo decisions:')} ${chalk.yellow(`${state.repo_decisions.length} active`)}`);
+  }
   if (state?.accepted_integration_ref) {
     console.log(`  ${chalk.dim('Accepted:')} ${state.accepted_integration_ref}`);
   }

package/src/lib/dispatch-bundle.js

@@ -18,6 +18,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync, readdirSync
 import { join } from 'path';
 import { getActiveTurn, getActiveTurns } from './governed-state.js';
 import { renderInheritedContextMarkdown } from './run-context-inheritance.js';
+import { renderRepoDecisionsMarkdown } from './repo-decisions.js';
 import {
   DISPATCH_INDEX_PATH,
   getDispatchAssignmentPath,
@@ -574,6 +575,11 @@ function renderContext(state, config, root, turn, role) {
         lines.push(`  - ${req}`);
       }
     }
+    if (Array.isArray(dc.required_decision_ids) && dc.required_decision_ids.length > 0) {
+      lines.push(`- **Required decisions:** ${dc.required_decision_ids.join(', ')}`);
+      lines.push('');
+      lines.push('Your accepted turn must emit these decision IDs in `decisions[]` before the parent review may advance the phase or complete the run.');
+    }
     lines.push('');
     lines.push('Focus exclusively on the charter above. Do not expand scope beyond the delegation.');
     lines.push('');
@@ -598,13 +604,26 @@ function renderContext(state, config, root, turn, role) {
       if (result.verification?.status) {
         lines.push(`- **Verification:** ${result.verification.status}`);
       }
+      if (Array.isArray(result.required_decision_ids) && result.required_decision_ids.length > 0) {
+        lines.push(`- **Required decisions:** ${result.required_decision_ids.join(', ')}`);
+        lines.push(`- **Satisfied decisions:** ${(result.satisfied_decision_ids || []).join(', ') || 'none'}`);
+        lines.push(`- **Missing decisions:** ${(result.missing_decision_ids || []).join(', ') || 'none'}`);
+      }
       lines.push('');
     }
-    lines.push('Evaluate whether each delegation met its acceptance contract.');
+    lines.push('Evaluate whether each delegation met its acceptance contract and returned any required named decisions.');
     lines.push('Your turn result should assess the delegation outcomes and decide next steps.');
     lines.push('');
   }
 
+  // Repo-level decisions that persist across runs
+  if (state.repo_decisions && state.repo_decisions.length > 0) {
+    const repoDecMd = renderRepoDecisionsMarkdown(state.repo_decisions);
+    if (repoDecMd) {
+      lines.push(repoDecMd);
+    }
+  }
+
   // 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

@@ -8,6 +8,7 @@ import { loadCoordinatorConfig, COORDINATOR_CONFIG_FILE } from './coordinator-co
 import { loadCoordinatorState } from './coordinator-state.js';
 import { normalizeRunProvenance } from './run-provenance.js';
 import { getDashboardPid, getDashboardSession } from '../commands/dashboard.js';
+import { readRepoDecisions } from './repo-decisions.js';
 
 const EXPORT_SCHEMA_VERSION = '0.3';
 
@@ -30,6 +31,7 @@ export const RUN_EXPORT_INCLUDED_ROOTS = [
   '.agentxchain/session.json',
   '.agentxchain/history.jsonl',
   '.agentxchain/decision-ledger.jsonl',
+  '.agentxchain/repo-decisions.jsonl',
   '.agentxchain/hook-audit.jsonl',
   '.agentxchain/hook-annotations.jsonl',
   '.agentxchain/notification-audit.jsonl',
@@ -208,6 +210,20 @@ function buildDashboardSessionSummary(root) {
   };
 }
 
+export function buildRepoDecisionsSummary(root) {
+  const all = readRepoDecisions(root);
+  if (!all || all.length === 0) return null;
+  const active = all.filter(d => d.status === 'active');
+  const overridden = all.filter(d => d.status === 'overridden');
+  return {
+    total: all.length,
+    active_count: active.length,
+    overridden_count: overridden.length,
+    active: active.map(d => ({ id: d.id, category: d.category, statement: d.statement, role: d.role, run_id: d.run_id })),
+    overridden: overridden.map(d => ({ id: d.id, overridden_by: d.overridden_by, statement: d.statement })),
+  };
+}
+
 export function buildDelegationSummary(files) {
   const historyData = files['.agentxchain/history.jsonl']?.data;
   if (!Array.isArray(historyData)) {
@@ -263,6 +279,9 @@ export function buildDelegationSummary(files) {
         delegation_id: del.id,
         to_role: del.to_role,
         charter: del.charter,
+        required_decision_ids: Array.isArray(del.required_decision_ids) ? del.required_decision_ids : [],
+        satisfied_decision_ids: Array.isArray(reviewResult?.satisfied_decision_ids) ? reviewResult.satisfied_decision_ids : [],
+        missing_decision_ids: Array.isArray(reviewResult?.missing_decision_ids) ? reviewResult.missing_decision_ids : [],
         status: reviewResult?.status || child?.status || 'pending',
         child_turn_id: child?.turn_id || null,
       };
@@ -448,6 +467,7 @@ export function buildRunExport(startDir = process.cwd()) {
         coordinator_present: Object.keys(files).some((path) => path.startsWith('.agentxchain/multirepo/')),
         dashboard_session: buildDashboardSessionSummary(root),
         delegation_summary: buildDelegationSummary(files),
+        repo_decisions: buildRepoDecisionsSummary(root),
       },
       workspace: buildRunWorkspaceMetadata(root),
       files,

package/src/lib/governed-state.js

@@ -44,6 +44,12 @@ import { emitRunEvent } from './run-events.js';
 import { writeSessionCheckpoint } from './session-checkpoint.js';
 import { recordRunHistory } from './run-history.js';
 import { buildDefaultRunProvenance } from './run-provenance.js';
+import {
+  getActiveRepoDecisions,
+  appendRepoDecision,
+  overrideRepoDecision,
+  validateOverride,
+} from './repo-decisions.js';
 import {
   replayVerificationMachineEvidence,
   summarizeVerificationReplay,
@@ -1908,6 +1914,7 @@ export function initializeGovernedRun(root, config, options = {}) {
   const runId = generateId('run');
   const now = new Date().toISOString();
   const provenance = buildDefaultRunProvenance(options.provenance);
+  const repoDecisions = getActiveRepoDecisions(root);
   const updatedState = {
     ...state,
     run_id: runId,
@@ -1922,6 +1929,7 @@ export function initializeGovernedRun(root, config, options = {}) {
     },
     provenance,
     inherited_context: options.inherited_context || null,
+    repo_decisions: repoDecisions.length > 0 ? repoDecisions : null,
   };
 
   writeState(root, updatedState);
@@ -2144,6 +2152,7 @@ export function assignGovernedTurn(root, config, roleId) {
       parent_role: pendingDelegation.parent_role,
       charter: pendingDelegation.charter,
       acceptance_contract: pendingDelegation.acceptance_contract,
+      required_decision_ids: pendingDelegation.required_decision_ids || [],
     };
     // Mark the delegation as active
     pendingDelegation.status = 'active';
@@ -2423,6 +2432,23 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   }
 
   const turnResult = validation.turnResult;
+
+  // Validate cross-run decision overrides against repo-decisions.jsonl
+  if (turnResult.decisions && turnResult.decisions.length > 0) {
+    for (const dec of turnResult.decisions) {
+      if (dec.overrides) {
+        const overrideCheck = validateOverride(root, dec);
+        if (!overrideCheck.ok) {
+          return {
+            ok: false,
+            error: `Override validation failed: ${overrideCheck.error}`,
+            error_code: 'override_validation_failed',
+          };
+        }
+      }
+    }
+  }
+
   const stagingFile = join(root, resolvedStagingPath);
   const now = new Date().toISOString();
   const baseline = currentTurn.baseline || null;
@@ -2717,6 +2743,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
             to_role: delegation.to_role,
             charter: delegation.charter,
             acceptance_contract: delegation.acceptance_contract,
+            required_decision_ids: delegation.required_decision_ids || [],
           })),
         }
       : {}),
@@ -2728,6 +2755,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
             parent_role: currentTurn.delegation_context.parent_role,
             charter: currentTurn.delegation_context.charter,
             acceptance_contract: currentTurn.delegation_context.acceptance_contract,
+            required_decision_ids: currentTurn.delegation_context.required_decision_ids || [],
           },
         }
       : {}),
@@ -2808,6 +2836,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         to_role: del.to_role,
         charter: del.charter,
         acceptance_contract: del.acceptance_contract,
+        required_decision_ids: del.required_decision_ids || [],
         status: 'pending',
         child_turn_id: null,
         created_at: now,
@@ -2834,12 +2863,23 @@ function _acceptGovernedTurnLocked(root, config, opts) {
         // Build delegation review context
         const delegationResults = parentDelegations.map(d => {
           const childHistory = nextHistoryEntries.find(h => h.turn_id === d.child_turn_id);
+          const childDecisionIds = Array.isArray(childHistory?.decisions)
+            ? childHistory.decisions
+              .map((decision) => decision?.id)
+              .filter((id) => typeof id === 'string')
+            : [];
+          const requiredDecisionIds = Array.isArray(d.required_decision_ids) ? d.required_decision_ids : [];
+          const satisfiedDecisionIds = requiredDecisionIds.filter((id) => childDecisionIds.includes(id));
+          const missingDecisionIds = requiredDecisionIds.filter((id) => !childDecisionIds.includes(id));
           return {
             delegation_id: d.delegation_id,
             child_turn_id: d.child_turn_id,
             to_role: d.to_role,
             charter: d.charter,
             acceptance_contract: d.acceptance_contract,
+            required_decision_ids: requiredDecisionIds,
+            satisfied_decision_ids: satisfiedDecisionIds,
+            missing_decision_ids: missingDecisionIds,
             summary: childHistory?.summary || '(no summary)',
             status: d.status,
             files_changed: childHistory?.files_changed || [],
@@ -3296,11 +3336,36 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   };
   writeAcceptanceJournal(root, journal);
 
-  // ── Commit order: history → ledger → talk → state → cleanup → journal ─
+  // ── Commit order: history → ledger → repo-decisions → talk → state → cleanup → journal ─
   appendJsonl(root, HISTORY_PATH, historyEntry);
   for (const entry of ledgerEntries) {
     appendJsonl(root, LEDGER_PATH, entry);
   }
+  // Persist repo-durable decisions and process overrides
+  if (turnResult.decisions && turnResult.decisions.length > 0) {
+    for (const dec of turnResult.decisions) {
+      // Process override first (marks target as overridden in repo-decisions.jsonl)
+      if (dec.overrides) {
+        overrideRepoDecision(root, dec.overrides, dec.id);
+      }
+      // Write to repo-decisions.jsonl if repo-durable or overriding a repo decision
+      if ((dec.durability || 'run') === 'repo' || dec.overrides) {
+        appendRepoDecision(root, {
+          id: dec.id,
+          run_id: state.run_id,
+          turn_id: turnResult.turn_id,
+          role: turnResult.role,
+          phase: state.phase,
+          category: dec.category,
+          statement: dec.statement,
+          rationale: dec.rationale,
+          status: 'active',
+          overridden_by: null,
+          created_at: now,
+        });
+      }
+    }
+  }
   appendTalk(root, talkSection);
   writeState(root, updatedState);
 

package/src/lib/repo-decisions.js

@@ -0,0 +1,100 @@
+/**
+ * Repo Decisions — cross-run decision carryover.
+ *
+ * Decisions with durability: "repo" persist in `.agentxchain/repo-decisions.jsonl`
+ * across governed runs. They act as binding constraints: agents in future runs
+ * must comply with active repo decisions or explicitly override them.
+ *
+ * DEC-SPEC: .planning/CROSS_RUN_DECISION_CARRYOVER_SPEC.md
+ */
+
+import { readFileSync, appendFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+
+const REPO_DECISIONS_PATH = '.agentxchain/repo-decisions.jsonl';
+
+// ── Read ────────────────────────────────────────────────────────────────────
+
+export function readRepoDecisions(root) {
+  const filePath = join(root, REPO_DECISIONS_PATH);
+  if (!existsSync(filePath)) return [];
+  try {
+    const content = readFileSync(filePath, 'utf8').trim();
+    if (!content) return [];
+    return content.split('\n').filter(Boolean).map(line => {
+      try { return JSON.parse(line); } catch { return null; }
+    }).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function getActiveRepoDecisions(root) {
+  return readRepoDecisions(root).filter(d => d.status === 'active');
+}
+
+export function getRepoDecisionById(root, decisionId) {
+  return readRepoDecisions(root).find(d => d.id === decisionId) || null;
+}
+
+// ── Write ───────────────────────────────────────────────────────────────────
+
+export function appendRepoDecision(root, entry) {
+  const filePath = join(root, REPO_DECISIONS_PATH);
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  appendFileSync(filePath, JSON.stringify(entry) + '\n');
+}
+
+export function overrideRepoDecision(root, targetId, overridingId) {
+  const all = readRepoDecisions(root);
+  const updated = all.map(d => {
+    if (d.id === targetId) {
+      return { ...d, status: 'overridden', overridden_by: overridingId };
+    }
+    return d;
+  });
+  const filePath = join(root, REPO_DECISIONS_PATH);
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(filePath, updated.map(d => JSON.stringify(d)).join('\n') + '\n');
+}
+
+// ── Validate Override ───────────────────────────────────────────────────────
+
+export function validateOverride(root, decision) {
+  if (!decision.overrides) return { ok: true };
+  const targetId = decision.overrides;
+  const target = getRepoDecisionById(root, targetId);
+  if (!target) {
+    return { ok: false, error: `decisions: overrides references ${targetId} which does not exist in repo decisions.` };
+  }
+  if (target.status === 'overridden') {
+    return { ok: false, error: `decisions: ${targetId} is already overridden by ${target.overridden_by}.` };
+  }
+  if (target.status !== 'active') {
+    return { ok: false, error: `decisions: ${targetId} has status "${target.status}", only active repo decisions can be overridden.` };
+  }
+  return { ok: true };
+}
+
+// ── Render ──────────────────────────────────────────────────────────────────
+
+export function renderRepoDecisionsMarkdown(activeDecisions) {
+  if (!activeDecisions || activeDecisions.length === 0) return '';
+  const lines = [
+    '## Active Repo Decisions',
+    '',
+    'These decisions persist from prior governed runs. Comply or explicitly override with rationale.',
+    '',
+  ];
+  for (const d of activeDecisions) {
+    lines.push(`- **${d.id}** (${d.category}): ${d.statement}`);
+  }
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ── Constants ───────────────────────────────────────────────────────────────
+
+export { REPO_DECISIONS_PATH };