agentxchain 2.101.0 → 2.103.0

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`);
     }
   }
@@ -556,82 +561,13 @@ export function validateV4Config(data, projectRoot) {
     errors.push(...timeoutValidation.errors);
   }
 
-  warnings.push(...collectRemoteReviewOnlyGateWarnings(data));
+  // Admission control (ADM-001..004) is handled by the validate, doctor, and
+  // run-loop paths which call runAdmissionControl() directly. Config schema
+  // validation here should not duplicate that surface.
 
   return { ok: errors.length === 0, errors, warnings };
 }
 
-export function collectRemoteReviewOnlyGateWarnings(data) {
-  const warnings = [];
-  const routing = data?.routing;
-  const gates = data?.gates;
-  const roles = data?.roles;
-  const runtimes = data?.runtimes;
-
-  if (!routing || !gates || !roles || !runtimes) {
-    return warnings;
-  }
-
-  for (const [phase, route] of Object.entries(routing)) {
-    const exitGateId = route?.exit_gate;
-    if (!exitGateId || !gates[exitGateId]) {
-      continue;
-    }
-
-    const requiredFiles = Array.isArray(gates[exitGateId]?.requires_files)
-      ? gates[exitGateId].requires_files.filter(filePath => typeof filePath === 'string' && filePath.trim())
-      : [];
-    if (requiredFiles.length === 0) {
-      continue;
-    }
-
-    const candidateRoleIds = [
-      route?.entry_role,
-      ...(Array.isArray(route?.allowed_next_roles) ? route.allowed_next_roles : []),
-    ].filter((roleId) => roleId && roleId !== 'human');
-
-    if (candidateRoleIds.length === 0) {
-      continue;
-    }
-
-    const candidateRoles = [...new Set(candidateRoleIds)]
-      .map((roleId) => {
-        const role = roles[roleId];
-        const runtime = role?.runtime ? runtimes[role.runtime] : null;
-        if (!role || !runtime) {
-          return null;
-        }
-        return { roleId, role, runtime };
-      })
-      .filter(Boolean);
-
-    if (candidateRoles.length === 0) {
-      continue;
-    }
-
-    const hasFileProducingRole = candidateRoles.some(({ role }) =>
-      role.write_authority === 'authoritative' || role.write_authority === 'proposed');
-    if (hasFileProducingRole) {
-      continue;
-    }
-
-    const allRemoteReviewOnly = candidateRoles.every(({ role, runtime }) =>
-      role.write_authority === 'review_only' && (runtime.type === 'api_proxy' || runtime.type === 'remote_agent'));
-    if (!allRemoteReviewOnly) {
-      continue;
-    }
-
-    const roleSummary = candidateRoles
-      .map(({ roleId, runtime }) => `${roleId}:${runtime.type}`)
-      .join(', ');
-    warnings.push(
-      `Routing "${phase}" exits through gate "${exitGateId}" with requires_files (${requiredFiles.join(', ')}) but all participating roles are review_only remote runtimes (${roleSummary}). Those files cannot be produced through governed turns; add a proposed/authoritative writer, remove the gate files, or expect operator-managed out-of-band artifacts.`,
-    );
-  }
-
-  return warnings;
-}
-
 export function validateBudgetConfig(budget) {
   const errors = [];
 

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>`);
   }
 

package/src/lib/run-loop.js

@@ -32,6 +32,7 @@ import {
   RUNNER_INTERFACE_VERSION,
 } from './runner-interface.js';
 
+import { runAdmissionControl } from './admission-control.js';
 import { mkdirSync, writeFileSync } from 'fs';
 import { join, dirname } from 'path';
 
@@ -65,6 +66,13 @@ export async function runLoop(root, config, callbacks, options = {}) {
     }
   };
 
+  // ── Admission control — reject provably dead-end configs ────────────────
+  const admission = runAdmissionControl(config, config);
+  if (!admission.ok) {
+    return makeResult(false, 'admission_rejected', null, 0, [], 0,
+      admission.errors.map(e => `Admission control: ${e}`));
+  }
+
   // ── Initialize if idle ──────────────────────────────────────────────────
   let state = loadState(root, config);
   const shouldRestartCompleted = state?.status === 'completed' && options.startNewRunFromCompleted === true;

package/src/lib/validation.js

@@ -9,7 +9,7 @@ import {
   validateAcceptanceHintCompletion,
   validateGovernedWorkflowKit,
 } from './governed-templates.js';
-import { collectRemoteReviewOnlyGateWarnings } from './normalized-config.js';
+import { runAdmissionControl } from './admission-control.js';
 
 const DEFAULT_REQUIRED_FILES = [
   '.planning/PROJECT.md',
@@ -116,8 +116,10 @@ export function validateGovernedProject(root, rawConfig, config, opts = {}) {
   errors.push(...workflowKit.errors);
   warnings.push(...workflowKit.warnings);
 
-  // Config-shape warnings (dead-end gates, etc.) — mirrors doctor/config --set surfaces
-  warnings.push(...collectRemoteReviewOnlyGateWarnings(rawConfig));
+  // Admission control — reject provably dead-end configs
+  const admission = runAdmissionControl(config, rawConfig);
+  errors.push(...admission.errors);
+  warnings.push(...admission.warnings);
 
   const mustExist = [
     config.files?.state || '.agentxchain/state.json',