agentxchain 2.93.0 → 2.94.0

package/package.json

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

package/src/lib/dispatch-bundle.js

@@ -575,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('');
@@ -599,9 +604,14 @@ 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('');
   }

package/src/lib/export.js

@@ -279,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,
       };

package/src/lib/governed-state.js

@@ -2152,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';
@@ -2742,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 || [],
           })),
         }
       : {}),
@@ -2753,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 || [],
           },
         }
       : {}),
@@ -2833,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,
@@ -2859,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 || [],

package/src/lib/report.js

@@ -33,6 +33,9 @@ function normalizeDelegationSummary(summary) {
         delegation_id: delegation.delegation_id,
         to_role: delegation.to_role,
         charter: delegation.charter,
+        required_decision_ids: Array.isArray(delegation.required_decision_ids) ? delegation.required_decision_ids : [],
+        satisfied_decision_ids: Array.isArray(delegation.satisfied_decision_ids) ? delegation.satisfied_decision_ids : [],
+        missing_decision_ids: Array.isArray(delegation.missing_decision_ids) ? delegation.missing_decision_ids : [],
         status: delegation.status,
         child_turn_id: delegation.child_turn_id,
       });
@@ -1290,6 +1293,11 @@ export function formatGovernanceReportText(report) {
         lines.push(`  - ${chain.parent_role} (${chain.parent_turn_id}) | outcome: ${chain.outcome} | review: ${chain.review_turn_id || 'pending'}`);
         for (const delegation of chain.delegations) {
           lines.push(`      ${delegation.delegation_id} -> ${delegation.to_role} | ${delegation.status} | child: ${delegation.child_turn_id || 'pending'} | ${delegation.charter}`);
+          if (delegation.required_decision_ids?.length > 0) {
+            lines.push(`        required decisions: ${delegation.required_decision_ids.join(', ')}`);
+            lines.push(`        satisfied decisions: ${delegation.satisfied_decision_ids.join(', ') || 'none'}`);
+            lines.push(`        missing decisions: ${delegation.missing_decision_ids.join(', ') || 'none'}`);
+          }
         }
       }
     }
@@ -1773,7 +1781,7 @@ export function formatGovernanceReportMarkdown(report) {
     if (run.delegation_summary?.delegation_chains?.length > 0) {
       lines.push('', '## Delegation Summary', '');
       lines.push(`- Total delegations issued: ${run.delegation_summary.total_delegations_issued}`, '');
-      lines.push('| Parent Role | Parent Turn | Outcome | Review Turn | Delegation | Child Turn | Status | Charter |', '|-------------|-------------|---------|-------------|------------|------------|--------|---------|');
+      lines.push('| Parent Role | Parent Turn | Outcome | Review Turn | Delegation | Child Turn | Status | Required Decisions | Missing Decisions | Charter |', '|-------------|-------------|---------|-------------|------------|------------|--------|--------------------|-------------------|---------|');
       for (const chain of run.delegation_summary.delegation_chains) {
         for (let i = 0; i < chain.delegations.length; i++) {
           const delegation = chain.delegations[i];
@@ -1782,7 +1790,9 @@ export function formatGovernanceReportMarkdown(report) {
           const outcome = i === 0 ? `\`${chain.outcome}\`` : '';
           const reviewTurn = i === 0 ? `\`${chain.review_turn_id || 'pending'}\`` : '';
           const charter = delegation.charter.replace(/\|/g, '\\|');
-          lines.push(`| ${parentRole} | ${parentTurn} | ${outcome} | ${reviewTurn} | \`${delegation.delegation_id}\` → \`${delegation.to_role}\` | \`${delegation.child_turn_id || 'pending'}\` | \`${delegation.status}\` | ${charter} |`);
+          const requiredDecisions = (delegation.required_decision_ids || []).join(', ').replace(/\|/g, '\\|') || '—';
+          const missingDecisions = (delegation.missing_decision_ids || []).join(', ').replace(/\|/g, '\\|') || '—';
+          lines.push(`| ${parentRole} | ${parentTurn} | ${outcome} | ${reviewTurn} | \`${delegation.delegation_id}\` → \`${delegation.to_role}\` | \`${delegation.child_turn_id || 'pending'}\` | \`${delegation.status}\` | ${requiredDecisions} | ${missingDecisions} | ${charter} |`);
         }
       }
     }
@@ -2392,11 +2402,13 @@ function renderRunHtml(report) {
           `<code>${esc(d.delegation_id)}</code> &rarr; <code>${esc(d.to_role)}</code>`,
           `<code>${esc(d.child_turn_id || 'pending')}</code>`,
           badge(d.status),
+          esc((d.required_decision_ids || []).join(', ') || '\u2014'),
+          esc((d.missing_decision_ids || []).join(', ') || '\u2014'),
           esc(d.charter),
         ]);
       }
     }
-    delHtml += htmlTable(['Parent Role', 'Parent Turn', 'Outcome', 'Review Turn', 'Delegation', 'Child Turn', 'Status', 'Charter'], rows);
+    delHtml += htmlTable(['Parent Role', 'Parent Turn', 'Outcome', 'Review Turn', 'Delegation', 'Child Turn', 'Status', 'Required Decisions', 'Missing Decisions', 'Charter'], rows);
     sections.push(`<div class="section">${htmlSection('Delegation Summary', delHtml)}</div>`);
   }
 

package/src/lib/schemas/turn-result.schema.json

@@ -268,6 +268,16 @@
             "items": { "type": "string", "minLength": 1 },
             "minItems": 1,
             "description": "What the delegate must achieve for this delegation to be considered complete."
+          },
+          "required_decision_ids": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^DEC-\\d+$"
+            },
+            "minItems": 1,
+            "uniqueItems": true,
+            "description": "Optional named decisions the delegated child must emit before the parent review turn may advance phase/run lifecycle."
           }
         }
       }

package/src/lib/turn-result-validator.js

@@ -263,6 +263,16 @@ function validateSchema(tr) {
     }
   }
 
+  if ('delegations' in tr) {
+    if (!Array.isArray(tr.delegations)) {
+      errors.push('delegations must be an array.');
+    } else {
+      for (let i = 0; i < tr.delegations.length; i++) {
+        errors.push(...validateDelegation(tr.delegations[i], i));
+      }
+    }
+  }
+
   errors.push(...collectUnfilledTemplatePlaceholderErrors(tr));
 
   return errors;
@@ -382,6 +392,54 @@ function validateObjection(obj, index) {
   return errors;
 }
 
+function validateDelegation(del, index) {
+  const errors = [];
+  const prefix = `delegations[${index}]`;
+
+  if (del === null || typeof del !== 'object' || Array.isArray(del)) {
+    return [`${prefix} must be an object.`];
+  }
+  if (typeof del.id !== 'string' || !/^del-\d{3}$/.test(del.id)) {
+    errors.push(`${prefix}.id must match pattern del-NNN.`);
+  }
+  if (typeof del.to_role !== 'string' || !/^[a-z0-9_-]+$/.test(del.to_role)) {
+    errors.push(`${prefix}.to_role must match pattern ^[a-z0-9_-]+$.`);
+  }
+  if (typeof del.charter !== 'string' || !del.charter.trim()) {
+    errors.push(`${prefix}.charter must be a non-empty string.`);
+  }
+  if (!Array.isArray(del.acceptance_contract) || del.acceptance_contract.length === 0) {
+    errors.push(`${prefix}.acceptance_contract must be a non-empty array.`);
+  } else {
+    for (let i = 0; i < del.acceptance_contract.length; i++) {
+      if (typeof del.acceptance_contract[i] !== 'string' || !del.acceptance_contract[i].trim()) {
+        errors.push(`${prefix}.acceptance_contract[${i}] must be a non-empty string.`);
+      }
+    }
+  }
+  if (del.required_decision_ids !== undefined) {
+    if (!Array.isArray(del.required_decision_ids) || del.required_decision_ids.length === 0) {
+      errors.push(`${prefix}.required_decision_ids must be a non-empty array when provided.`);
+    } else {
+      const seen = new Set();
+      for (let i = 0; i < del.required_decision_ids.length; i++) {
+        const id = del.required_decision_ids[i];
+        if (typeof id !== 'string' || !/^DEC-\d+$/.test(id)) {
+          errors.push(`${prefix}.required_decision_ids[${i}] must match pattern DEC-NNN.`);
+          continue;
+        }
+        if (seen.has(id)) {
+          errors.push(`${prefix}.required_decision_ids contains duplicate "${id}".`);
+          continue;
+        }
+        seen.add(id);
+      }
+    }
+  }
+
+  return errors;
+}
+
 // ── Stage B: Assignment Validation ───────────────────────────────────────────
 
 function validateAssignment(tr, state) {
@@ -563,6 +621,7 @@ function validateProtocol(tr, state, config) {
 
   const role = config.roles?.[tr.role];
   const writeAuthority = role?.write_authority;
+  const activeTurn = getActiveTurn(state) || state?.current_turn || null;
 
   // Challenge requirement: review_only roles MUST raise at least one objection
   if (config.rules?.challenge_required !== false) {
@@ -628,7 +687,6 @@ function validateProtocol(tr, state, config) {
     }
 
     // No recursive delegation: if this turn is a delegation review, it cannot delegate further
-    const activeTurn = state?.active_turns ? Object.values(state.active_turns)[0] : null;
     if (activeTurn?.delegation_context) {
       errors.push('Delegation review turns cannot contain further delegations.');
     }
@@ -663,6 +721,26 @@ function validateProtocol(tr, state, config) {
     }
   }
 
+  if (activeTurn?.delegation_review) {
+    const unmetDecisionContracts = (activeTurn.delegation_review.results || [])
+      .filter((result) => Array.isArray(result?.missing_decision_ids) && result.missing_decision_ids.length > 0);
+    if (unmetDecisionContracts.length > 0) {
+      const detail = unmetDecisionContracts
+        .map((result) => `${result.delegation_id}: ${result.missing_decision_ids.join(', ')}`)
+        .join('; ');
+      if (tr.phase_transition_request) {
+        errors.push(
+          `Delegation review cannot request phase transition while required child decisions are missing: ${detail}.`
+        );
+      }
+      if (tr.run_completion_request) {
+        errors.push(
+          `Delegation review cannot request run completion while required child decisions are missing: ${detail}.`
+        );
+      }
+    }
+  }
+
   return { errors, warnings };
 }