agentxchain 2.102.0 → 2.103.0

package/package.json

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

package/src/commands/decisions.js

@@ -5,9 +5,9 @@
  */
 
 import { resolve } from 'path';
-import { existsSync } from 'fs';
+import { existsSync, readFileSync } from 'fs';
 import chalk from 'chalk';
-import { readRepoDecisions, getActiveRepoDecisions, getRepoDecisionById } from '../lib/repo-decisions.js';
+import { readRepoDecisions, getActiveRepoDecisions, getRepoDecisionById, resolveDecisionAuthority } from '../lib/repo-decisions.js';
 
 /**
  * @param {object} opts - { json?: boolean, all?: boolean, show?: string, dir?: string }
@@ -39,6 +39,18 @@ export async function decisionsCommand(opts) {
     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(`  Durability:  ${dec.durability || 'repo'}`);
+    // Show decision authority if config has it
+    const config = loadConfig(root);
+    if (config && dec.role) {
+      const auth = resolveDecisionAuthority(dec.role, config);
+      if (auth !== null && !(typeof auth === 'object' && auth.unknown)) {
+        console.log(`  Authority:   ${auth} (${dec.role})`);
+      }
+    }
+    if (dec.overrides) {
+      console.log(`  Supersedes:  ${chalk.yellow(dec.overrides)}`);
+    }
     console.log(`  Created:     ${dec.created_at || '—'}`);
     if (dec.overridden_by) {
       console.log(`  Overridden:  ${chalk.yellow(dec.overridden_by)}`);
@@ -69,7 +81,11 @@ export async function decisionsCommand(opts) {
   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}`) : '';
+    const override = dec.overridden_by
+      ? chalk.dim(` → ${dec.overridden_by}`)
+      : dec.overrides
+        ? chalk.dim(` ← supersedes ${dec.overrides}`)
+        : '';
     console.log(`  ${chalk.cyan(dec.id)}  ${status}  ${chalk.dim(dec.category)}  ${dec.statement}${override}`);
     console.log(`    ${chalk.dim(`by ${dec.role || '?'} in ${runShort || '?'}`)}`);
   }
@@ -92,3 +108,13 @@ function findProjectRoot(dir) {
   }
   return null;
 }
+
+function loadConfig(root) {
+  const configPath = resolve(root, 'agentxchain.json');
+  if (!existsSync(configPath)) return null;
+  try {
+    return JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}

package/src/commands/role.js

@@ -37,13 +37,19 @@ function listRoles(roles, roleIds, opts) {
   }
 
   if (opts.json) {
-    const output = roleIds.map((id) => ({
-      id,
-      title: roles[id].title,
-      mandate: roles[id].mandate,
-      write_authority: roles[id].write_authority,
-      runtime: roles[id].runtime,
-    }));
+    const output = roleIds.map((id) => {
+      const entry = {
+        id,
+        title: roles[id].title,
+        mandate: roles[id].mandate,
+        write_authority: roles[id].write_authority,
+        runtime: roles[id].runtime,
+      };
+      if (typeof roles[id].decision_authority === 'number') {
+        entry.decision_authority = roles[id].decision_authority;
+      }
+      return entry;
+    });
     console.log(JSON.stringify(output, null, 2));
     return;
   }
@@ -56,7 +62,8 @@ function listRoles(roles, roleIds, opts) {
       : r.write_authority === 'proposed'
         ? chalk.yellow(r.write_authority)
         : chalk.dim(r.write_authority);
-    console.log(`  ${chalk.cyan(id)} — ${r.title} [${authority}] → ${chalk.dim(r.runtime)}`);
+    const decAuth = typeof r.decision_authority === 'number' ? chalk.dim(` dec:${r.decision_authority}`) : '';
+    console.log(`  ${chalk.cyan(id)} — ${r.title} [${authority}${decAuth}] → ${chalk.dim(r.runtime)}`);
   }
   console.log('');
   console.log(chalk.dim('  Usage: agentxchain role show <role_id>\n'));
@@ -81,13 +88,17 @@ function showRole(roleId, roles, roleIds, opts) {
   const r = roles[roleId];
 
   if (opts.json) {
-    console.log(JSON.stringify({
+    const entry = {
       id: roleId,
       title: r.title,
       mandate: r.mandate,
       write_authority: r.write_authority,
       runtime: r.runtime,
-    }, null, 2));
+    };
+    if (typeof r.decision_authority === 'number') {
+      entry.decision_authority = r.decision_authority;
+    }
+    console.log(JSON.stringify(entry, null, 2));
     return;
   }
 
@@ -101,6 +112,9 @@ function showRole(roleId, roles, roleIds, opts) {
   console.log(`  Title:      ${r.title}`);
   console.log(`  Mandate:    ${r.mandate}`);
   console.log(`  Authority:  ${authority}`);
+  if (typeof r.decision_authority === 'number') {
+    console.log(`  Decision:   ${r.decision_authority}`);
+  }
   console.log(`  Runtime:    ${chalk.dim(r.runtime)}`);
   console.log('');
 }

package/src/lib/dispatch-bundle.js

@@ -618,7 +618,7 @@ function renderContext(state, config, root, turn, role) {
 
   // Repo-level decisions that persist across runs
   if (state.repo_decisions && state.repo_decisions.length > 0) {
-    const repoDecMd = renderRepoDecisionsMarkdown(state.repo_decisions);
+    const repoDecMd = renderRepoDecisionsMarkdown(state.repo_decisions, config);
     if (repoDecMd) {
       lines.push(repoDecMd);
     }

package/src/lib/export-verifier.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
+import { summarizeRepoDecisions } from './repo-decisions.js';
 
 const SUPPORTED_EXPORT_SCHEMA_VERSIONS = new Set(['0.2', '0.3']);
 const VALID_FILE_FORMATS = new Set(['json', 'jsonl', 'text']);
@@ -369,38 +370,18 @@ function verifyDelegationSummary(artifact, errors) {
   }
 }
 
-function buildExpectedRepoDecisionsSummary(files) {
+function buildExpectedRepoDecisionsSummary(files, config = null) {
   const repoDecisionsData = files?.['.agentxchain/repo-decisions.jsonl']?.data;
   if (!Array.isArray(repoDecisionsData) || repoDecisionsData.length === 0) {
     return null;
   }
-
-  const active = repoDecisionsData.filter((d) => d.status === 'active');
-  const overridden = repoDecisionsData.filter((d) => d.status === 'overridden');
-
-  return {
-    total: repoDecisionsData.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,
-    })),
-  };
+  return summarizeRepoDecisions(repoDecisionsData, config);
 }
 
 function verifyRepoDecisionsSummary(artifact, errors) {
   const summary = artifact.summary?.repo_decisions;
   const hasFile = '.agentxchain/repo-decisions.jsonl' in (artifact.files || {});
-  const expected = buildExpectedRepoDecisionsSummary(artifact.files);
+  const expected = buildExpectedRepoDecisionsSummary(artifact.files, artifact.config || null);
 
   if (summary === null && expected === null) {
     return;

package/src/lib/export.js

@@ -8,7 +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';
+import { readRepoDecisions, summarizeRepoDecisions } from './repo-decisions.js';
 import { RUN_EVENTS_PATH } from './run-events.js';
 
 const EXPORT_SCHEMA_VERSION = '0.3';
@@ -211,18 +211,8 @@ 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 buildRepoDecisionsSummary(root, config = null) {
+  return summarizeRepoDecisions(readRepoDecisions(root), config);
 }
 
 export function buildDelegationSummary(files) {
@@ -471,7 +461,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),
+        repo_decisions: buildRepoDecisionsSummary(root, rawConfig),
       },
       workspace: buildRunWorkspaceMetadata(root),
       files,

package/src/lib/governed-state.js

@@ -2437,7 +2437,7 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   if (turnResult.decisions && turnResult.decisions.length > 0) {
     for (const dec of turnResult.decisions) {
       if (dec.overrides) {
-        const overrideCheck = validateOverride(root, dec);
+        const overrideCheck = validateOverride(root, { ...dec, role: dec.role || turnResult.role }, config);
         if (!overrideCheck.ok) {
           return {
             ok: false,
@@ -3359,6 +3359,8 @@ function _acceptGovernedTurnLocked(root, config, opts) {
           category: dec.category,
           statement: dec.statement,
           rationale: dec.rationale,
+          durability: dec.durability || 'repo',
+          overrides: dec.overrides || null,
           status: 'active',
           overridden_by: null,
           created_at: now,

package/src/lib/normalized-config.js

@@ -366,6 +366,11 @@ export function validateV4Config(data, projectRoot) {
       if (!VALID_WRITE_AUTHORITIES.includes(role.write_authority)) {
         errors.push(`Role "${id}": write_authority must be one of: ${VALID_WRITE_AUTHORITIES.join(', ')}`);
       }
+      if (role.decision_authority !== undefined && role.decision_authority !== null) {
+        if (!Number.isInteger(role.decision_authority) || role.decision_authority < 0 || role.decision_authority > 99) {
+          errors.push(`Role "${id}": decision_authority must be an integer between 0 and 99`);
+        }
+      }
       if (typeof role.runtime !== 'string' || !role.runtime.trim()) errors.push(`Role "${id}": runtime required`);
     }
   }

package/src/lib/repo-decisions.js

@@ -37,6 +37,74 @@ export function getRepoDecisionById(root, decisionId) {
   return readRepoDecisions(root).find(d => d.id === decisionId) || null;
 }
 
+export function getDecisionAuthorityMetadata(roleId, config) {
+  const resolved = resolveDecisionAuthority(roleId, config);
+  if (resolved === null) return null;
+  if (typeof resolved === 'object' && resolved.unknown) {
+    return {
+      level: resolved.level,
+      source: 'unknown_role',
+      role: roleId || null,
+    };
+  }
+  if (roleId === 'human') {
+    const explicitHumanAuthority = typeof config?.roles?.human?.decision_authority === 'number';
+    return {
+      level: resolved,
+      source: explicitHumanAuthority ? 'configured' : 'human_default',
+      role: roleId,
+    };
+  }
+  return {
+    level: resolved,
+    source: 'configured',
+    role: roleId || null,
+  };
+}
+
+export function summarizeRepoDecisions(decisions, config) {
+  if (!Array.isArray(decisions) || decisions.length === 0) return null;
+  const active = decisions.filter((d) => d.status === 'active');
+  const overridden = decisions.filter((d) => d.status === 'overridden');
+  const addAuthority = (decision) => {
+    const authority = getDecisionAuthorityMetadata(decision.role, config);
+    return {
+      id: decision.id,
+      category: decision.category,
+      statement: decision.statement,
+      role: decision.role,
+      run_id: decision.run_id,
+      overrides: decision.overrides || null,
+      durability: decision.durability || 'repo',
+      authority_level: authority?.level ?? null,
+      authority_source: authority?.source || null,
+    };
+  };
+  return {
+    total: decisions.length,
+    active_count: active.length,
+    overridden_count: overridden.length,
+    active: active.map(addAuthority),
+    overridden: overridden.map((d) => {
+      const authority = getDecisionAuthorityMetadata(d.role, config);
+      return {
+        id: d.id,
+        overridden_by: d.overridden_by,
+        statement: d.statement,
+        overrides: d.overrides || null,
+        durability: d.durability || 'repo',
+        role: d.role || null,
+        authority_level: authority?.level ?? null,
+        authority_source: authority?.source || null,
+      };
+    }),
+  };
+}
+
+export function buildRepoDecisionsSummary(decisions) {
+  return summarizeRepoDecisions(decisions, null);
+}
+
 // ── Write ───────────────────────────────────────────────────────────────────
 
 export function appendRepoDecision(root, entry) {
@@ -62,7 +130,16 @@ export function overrideRepoDecision(root, targetId, overridingId) {
 
 // ── Validate Override ───────────────────────────────────────────────────────
 
-export function validateOverride(root, decision) {
+/**
+ * Validate that an override is allowed.
+ * @param {string} root - project root
+ * @param {object} decision - the overriding decision (must have .overrides, .id, optionally .role)
+ * @param {object} [config] - agentxchain config (used for authority enforcement)
+ * @returns {{ ok: boolean, error?: string, warning?: string }}
+ *
+ * DEC-SPEC: .planning/DECISION_AUTHORITY_SPEC.md
+ */
+export function validateOverride(root, decision, config) {
   if (!decision.overrides) return { ok: true };
   const targetId = decision.overrides;
   const target = getRepoDecisionById(root, targetId);
@@ -75,21 +152,104 @@ export function validateOverride(root, decision) {
   if (target.status !== 'active') {
     return { ok: false, error: `decisions: ${targetId} has status "${target.status}", only active repo decisions can be overridden.` };
   }
+
+  // Authority enforcement (opt-in via decision_authority on roles)
+  const authorityResult = checkOverrideAuthority(decision, target, config);
+  if (!authorityResult.ok) return authorityResult;
+
+  return authorityResult.warning ? { ok: true, warning: authorityResult.warning } : { ok: true };
+}
+
+/**
+ * Resolve the decision_authority level for a role.
+ * - 'human' defaults to 100 unless explicitly configured.
+ * - Unknown roles default to 0 (with warning).
+ * - Null means opt-out (no enforcement).
+ */
+export function resolveDecisionAuthority(roleId, config) {
+  if (!config || !config.roles) return null;
+  if (roleId === 'human') {
+    const humanRole = config.roles.human;
+    if (humanRole && typeof humanRole.decision_authority === 'number') {
+      return humanRole.decision_authority;
+    }
+    return 100; // human default
+  }
+  const role = config.roles[roleId];
+  if (!role) return { level: 0, unknown: true };
+  if (typeof role.decision_authority !== 'number') return null;
+  return role.decision_authority;
+}
+
+/**
+ * Check whether the overriding role has sufficient authority to override
+ * a decision made by the target role.
+ */
+function checkOverrideAuthority(overridingDecision, targetDecision, config) {
+  if (!config || !config.roles) return { ok: true };
+
+  const overridingRole = overridingDecision.role;
+  const targetRole = targetDecision.role;
+
+  // Same-role override is always allowed
+  if (overridingRole && targetRole && overridingRole === targetRole) return { ok: true };
+
+  const targetAuth = resolveDecisionAuthority(targetRole, config);
+  const overridingAuth = resolveDecisionAuthority(overridingRole, config);
+
+  // Handle unknown target role
+  let warning;
+  if (targetAuth && typeof targetAuth === 'object' && targetAuth.unknown) {
+    warning = `decisions: target decision role '${targetRole}' not found in current config, treating as authority 0.`;
+    // targetAuth is effectively 0, allow override
+    return { ok: true, warning };
+  }
+
+  // Opt-in: if either side is null (not configured), allow
+  if (targetAuth === null || overridingAuth === null) return { ok: true };
+
+  // Handle unknown overriding role (shouldn't normally happen, but be safe)
+  const overridingLevel = (typeof overridingAuth === 'object' && overridingAuth.unknown) ? 0 : overridingAuth;
+  const targetLevel = (typeof targetAuth === 'object') ? 0 : targetAuth;
+
+  if (overridingLevel < targetLevel) {
+    return {
+      ok: false,
+      error: `decisions: role '${overridingRole}' (authority ${overridingLevel}) cannot override ${targetDecision.id} made by '${targetRole}' (authority ${targetLevel}). Override requires authority >= ${targetLevel}.`,
+    };
+  }
+
   return { ok: true };
 }
 
 // ── Render ──────────────────────────────────────────────────────────────────
 
-export function renderRepoDecisionsMarkdown(activeDecisions) {
+export function renderRepoDecisionsMarkdown(activeDecisions, config) {
   if (!activeDecisions || activeDecisions.length === 0) return '';
+  const hasAuthorityPolicy = Object.values(config?.roles || {}).some((role) => (
+    role && typeof role.decision_authority === 'number'
+  ));
   const lines = [
     '## Active Repo Decisions',
     '',
     'These decisions persist from prior governed runs. Comply or explicitly override with rationale.',
     '',
   ];
+  if (hasAuthorityPolicy) {
+    lines.push('When both roles declare `decision_authority`, overrides require authority greater than or equal to the originating role.');
+    lines.push('');
+  }
   for (const d of activeDecisions) {
-    lines.push(`- **${d.id}** (${d.category}): ${d.statement}`);
+    const authority = getDecisionAuthorityMetadata(d.role, config);
+    const authorityText = authority
+      ? authority.source === 'human_default'
+        ? ' authority 100 (human default)'
+        : authority.source === 'unknown_role'
+          ? ' authority 0 (role no longer in config)'
+          : ` authority ${authority.level}`
+      : '';
+    const supersedes = d.overrides ? ` Supersedes ${d.overrides}.` : '';
+    lines.push(`- **${d.id}** (${d.category}, by ${d.role || 'unknown'}${authorityText}): ${d.statement}${supersedes}`);
   }
   lines.push('');
   return lines.join('\n');

package/src/lib/report.js

@@ -1320,7 +1320,13 @@ export function formatGovernanceReportText(report) {
       lines.push('', 'Repo Decisions:');
       lines.push(`  Active: ${run.repo_decisions.active_count}  Overridden: ${run.repo_decisions.overridden_count}`);
       for (const d of run.repo_decisions.active) {
-        lines.push(`  - ${d.id} (${d.category}): ${d.statement}`);
+        const supersedes = d.overrides ? ` | supersedes ${d.overrides}` : '';
+        const authority = d.authority_level == null ? '' : ` | authority ${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
+        lines.push(`  - ${d.id} (${d.category}): ${d.statement}${supersedes}${authority}`);
+      }
+      for (const d of run.repo_decisions.overridden || []) {
+        const authority = d.authority_level == null ? '' : ` | authority ${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
+        lines.push(`  - ${d.id} (overridden by ${d.overridden_by || 'unknown'}${authority})`);
       }
     }
 
@@ -1825,10 +1831,20 @@ export function formatGovernanceReportMarkdown(report) {
     if (run.repo_decisions?.active?.length > 0) {
       lines.push('', '## Repo Decisions', '');
       lines.push(`Active: ${run.repo_decisions.active_count} | Overridden: ${run.repo_decisions.overridden_count}`, '');
-      lines.push('| ID | Category | Statement | Role | Run |', '|----|----------|-----------|------|-----|');
+      lines.push('| ID | Category | Statement | Role | Authority | Run | Supersedes |', '|----|----------|-----------|------|-----------|-----|------------|');
       for (const d of run.repo_decisions.active) {
         const stmt = (d.statement || '').replace(/\|/g, '\\|');
-        lines.push(`| ${d.id} | ${d.category} | ${stmt} | ${d.role || '—'} | \`${(d.run_id || '').slice(0, 12)}\` |`);
+        const authority = d.authority_level == null ? '—' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
+        lines.push(`| ${d.id} | ${d.category} | ${stmt} | ${d.role || '—'} | ${authority} | \`${(d.run_id || '').slice(0, 12)}\` | ${d.overrides || '—'} |`);
+      }
+      if (run.repo_decisions.overridden?.length > 0) {
+        lines.push('', 'Overridden decisions:', '');
+        lines.push('| ID | Statement | Authority | Overridden By |', '|----|-----------|-----------|---------------|');
+        for (const d of run.repo_decisions.overridden) {
+          const stmt = (d.statement || '').replace(/\|/g, '\\|');
+          const authority = d.authority_level == null ? '—' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`;
+          lines.push(`| ${d.id} | ${stmt} | ${authority} | ${d.overridden_by || '—'} |`);
+        }
       }
     }
 
@@ -2453,9 +2469,28 @@ function renderRunHtml(report) {
   if (run.repo_decisions?.active?.length > 0) {
     let rdHtml = `<p>Active: ${run.repo_decisions.active_count} | Overridden: ${run.repo_decisions.overridden_count}</p>`;
     rdHtml += htmlTable(
-      ['ID', 'Category', 'Statement', 'Role', 'Run'],
-      run.repo_decisions.active.map((d) => [esc(d.id), esc(d.category), esc(d.statement || ''), esc(d.role || '\u2014'), `<code>${esc((d.run_id || '').slice(0, 12))}</code>`]),
+      ['ID', 'Category', 'Statement', 'Role', 'Authority', 'Run', 'Supersedes'],
+      run.repo_decisions.active.map((d) => [
+        esc(d.id),
+        esc(d.category),
+        esc(d.statement || ''),
+        esc(d.role || '\u2014'),
+        esc(d.authority_level == null ? '\u2014' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`),
+        `<code>${esc((d.run_id || '').slice(0, 12))}</code>`,
+        esc(d.overrides || '\u2014'),
+      ]),
     );
+    if (run.repo_decisions.overridden?.length > 0) {
+      rdHtml += htmlTable(
+        ['ID', 'Statement', 'Authority', 'Overridden By'],
+        run.repo_decisions.overridden.map((d) => [
+          esc(d.id),
+          esc(d.statement || ''),
+          esc(d.authority_level == null ? '\u2014' : `${d.authority_level}${d.authority_source === 'human_default' ? ' (human default)' : ''}`),
+          esc(d.overridden_by || '\u2014'),
+        ]),
+      );
+    }
     sections.push(`<div class="section">${htmlSection('Repo Decisions', rdHtml)}</div>`);
   }