agentxchain 2.138.1 → 2.140.0

package/bin/agentxchain.js

@@ -1031,6 +1031,7 @@ intakeCmd
   .command('resolve')
   .description('Resolve an executing intent by reading the governed run outcome')
   .option('--intent <id>', 'Intent ID to resolve')
+  .option('--outcome <status>', 'Force transition to this status (e.g., "completed")')
   .option('-j, --json', 'Output as JSON')
   .action(intakeResolveCommand);
 

package/package.json

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

package/src/commands/intake-resolve.js

@@ -15,7 +15,11 @@ export async function intakeResolveCommand(opts) {
     process.exit(1);
   }
 
-  const result = resolveIntent(root, opts.intent);
+  const resolveOpts = {};
+  if (opts.outcome) {
+    resolveOpts.outcome = opts.outcome;
+  }
+  const result = resolveIntent(root, opts.intent, resolveOpts);
 
   if (opts.json) {
     console.log(JSON.stringify(result, null, 2));

package/src/lib/governed-state.js

@@ -68,6 +68,10 @@ import {
 } from './verification-replay.js';
 import { executeGateActions } from './gate-actions.js';
 import { detectPendingCheckpoint } from './turn-checkpoint.js';
+import {
+  derivePhaseScopeFromIntentMetadata,
+  evaluateAcceptanceItemLifecycle,
+} from './intent-phase-scope.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -78,6 +82,7 @@ const STAGING_PATH = '.agentxchain/staging/turn-result.json';
 const TALK_PATH = 'TALK.md';
 const ACCEPTANCE_LOCK_PATH = '.agentxchain/locks/accept-turn.lock';
 const ACCEPTANCE_JOURNAL_DIR = '.agentxchain/transactions/accept';
+const INTAKE_INTENTS_DIR = '.agentxchain/intake/intents';
 const STALE_LOCK_TIMEOUT_MS = 30_000;
 const GOVERNED_SCHEMA_VERSION = '1.1';
 
@@ -101,6 +106,113 @@ function buildInitialPhaseGateStatus(config) {
   );
 }
 
+function listIntakeIntentFiles(root) {
+  const intentsDir = join(root, INTAKE_INTENTS_DIR);
+  if (!existsSync(intentsDir)) return [];
+
+  return readdirSync(intentsDir)
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => join(intentsDir, name));
+}
+
+// BUG-45: Reconcile embedded intake_context against the live intent file.
+// The embedded copy is historical state; the live intent file is authoritative.
+// If the live intent cannot be read, acceptance must fail closed instead of
+// silently reusing the stale embedded contract.
+const INTENT_TERMINAL_STATES = ['completed', 'satisfied', 'superseded', 'suppressed', 'failed', 'rejected'];
+
+function reconcileIntakeContext(root, intakeCtx) {
+  if (!intakeCtx || !intakeCtx.intent_id) {
+    return { ok: true, intakeCtx };
+  }
+
+  try {
+    const intentPath = join(root, INTAKE_INTENTS_DIR, `${intakeCtx.intent_id}.json`);
+    if (!existsSync(intentPath)) {
+      return {
+        ok: false,
+        error: `Intent reconciliation failed: live intent ${intakeCtx.intent_id} not found at ${INTAKE_INTENTS_DIR}/${intakeCtx.intent_id}.json`,
+      };
+    }
+
+    const liveIntent = JSON.parse(readFileSync(intentPath, 'utf8'));
+
+    // If the intent has reached a terminal state, skip coverage enforcement
+    if (INTENT_TERMINAL_STATES.includes(liveIntent.status)) {
+      return { ok: true, intakeCtx: null };
+    }
+
+    // Intent is still active — use the CURRENT acceptance_contract from disk
+    if (Array.isArray(liveIntent.acceptance_contract)) {
+      return {
+        ok: true,
+        intakeCtx: { ...intakeCtx, acceptance_contract: liveIntent.acceptance_contract },
+      };
+    }
+
+    return { ok: true, intakeCtx };
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Intent reconciliation failed: could not read live intent ${intakeCtx.intent_id}: ${error.message}`,
+    };
+  }
+}
+
+function retireApprovedPhaseScopedIntents(root, state, config, exitedPhase, now) {
+  const retired = [];
+
+  for (const intentPath of listIntakeIntentFiles(root)) {
+    let intent;
+    try {
+      intent = JSON.parse(readFileSync(intentPath, 'utf8'));
+    } catch {
+      continue;
+    }
+
+    if (!intent || intent.status !== 'approved') continue;
+    if (state?.run_id && intent.approved_run_id && intent.approved_run_id !== state.run_id) continue;
+    if (state?.run_id && !intent.approved_run_id && intent.cross_run_durable !== true) continue;
+
+    const effectivePhaseScope = derivePhaseScopeFromIntentMetadata(intent, config);
+    const acceptanceItems = Array.isArray(intent.acceptance_contract) ? intent.acceptance_contract : [];
+    const lifecycleStates = acceptanceItems.map((item) => evaluateAcceptanceItemLifecycle(
+      item,
+      { phase_scope: effectivePhaseScope },
+      state,
+      config,
+    ));
+    const retireByPhaseExit = effectivePhaseScope === exitedPhase;
+    const retireByGateState = acceptanceItems.length > 0
+      && lifecycleStates.every((entry) => entry.satisfied_by_gate_state || entry.phase_exited);
+
+    if (!retireByPhaseExit && !retireByGateState) continue;
+
+    intent.status = 'satisfied';
+    intent.phase_scope = effectivePhaseScope || intent.phase_scope || null;
+    intent.updated_at = now;
+    intent.satisfied_at = now;
+    intent.satisfied_reason = retireByPhaseExit
+      ? `phase ${exitedPhase} exited; ${exitedPhase}-scoped repair no longer required`
+      : `acceptance items satisfied by gate state after phase advance from ${exitedPhase}`;
+    if (!Array.isArray(intent.history)) {
+      intent.history = [];
+    }
+    intent.history.push({
+      from: 'approved',
+      to: 'satisfied',
+      at: now,
+      reason: intent.satisfied_reason,
+      exited_phase: exitedPhase,
+      entered_phase: state?.phase || null,
+    });
+    safeWriteJson(intentPath, intent);
+    retired.push(intent.intent_id);
+  }
+
+  return retired;
+}
+
 function buildFreshIdleStateForNewRun(state, config) {
   return {
     schema_version: state?.schema_version || GOVERNED_SCHEMA_VERSION,
@@ -3154,12 +3266,38 @@ function _acceptGovernedTurnLocked(root, config, opts) {
     };
   }
 
-  // ── Intent coverage validation (BUG-14) ──────────────────────────────────
-  // When a turn is bound to an injected intent, verify the turn result
-  // addresses each acceptance item.  Default: strict for p0, lenient for others.
-  const intakeCtx = currentTurn.intake_context;
+  // ── BUG-45: Reconcile intake_context against live intent state ──────────
+  // The embedded intake_context is a snapshot from dispatch time. The intent
+  // may have since been completed, satisfied, or had its contract updated.
+  // Re-read the live intent file and reconcile before evaluating coverage.
+  const intakeReconciliation = reconcileIntakeContext(root, currentTurn.intake_context);
+  if (!intakeReconciliation.ok) {
+    transitionToFailedAcceptance(root, state, currentTurn, intakeReconciliation.error, {
+      error_code: 'intent_reconciliation_failed',
+      stage: 'intent_reconciliation',
+      extra: {
+        intent_id: currentTurn.intake_context?.intent_id || null,
+      },
+    });
+    return {
+      ok: false,
+      error: intakeReconciliation.error,
+      validation: {
+        ...validation,
+        ok: false,
+        stage: 'intent_reconciliation',
+        error_class: 'intent_reconciliation_error',
+        errors: [intakeReconciliation.error],
+        warnings: validation.warnings,
+      },
+    };
+  }
+  const intakeCtx = intakeReconciliation.intakeCtx;
   if (intakeCtx && Array.isArray(intakeCtx.acceptance_contract) && intakeCtx.acceptance_contract.length > 0) {
-    const intentCoverage = evaluateIntentCoverage(turnResult, intakeCtx);
+    const intentCoverage = evaluateIntentCoverage(turnResult, intakeCtx, {
+      state,
+      config,
+    });
     const priority = intakeCtx.priority || currentTurn.intake_context?.priority || 'p0';
     const intentCoverageMode = config.intent_coverage_mode
       || (priority === 'p0' ? 'strict' : 'lenient');
@@ -3977,6 +4115,21 @@ function _acceptGovernedTurnLocked(root, config, opts) {
             [gateResult.gate_id || 'no_gate']: 'passed',
           };
           updatedState.queued_phase_transition = null;
+          const retiredIntentIds = retireApprovedPhaseScopedIntents(root, updatedState, config, prevPhase, now);
+          if (retiredIntentIds.length > 0) {
+            emitRunEvent(root, 'intent_retired_by_phase_advance', {
+              run_id: updatedState.run_id,
+              phase: updatedState.phase,
+              status: updatedState.status,
+              turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+              payload: {
+                exited_phase: prevPhase,
+                entered_phase: gateResult.next_phase,
+                retired_count: retiredIntentIds.length,
+                retired_intent_ids: retiredIntentIds,
+              },
+            });
+          }
           emitRunEvent(root, 'phase_entered', {
             run_id: updatedState.run_id,
             phase: updatedState.phase,
@@ -4019,6 +4172,21 @@ function _acceptGovernedTurnLocked(root, config, opts) {
               gate_id: gateResult.gate_id,
               timestamp: now,
             });
+            const retiredIntentIds = retireApprovedPhaseScopedIntents(root, updatedState, config, prevPhase, now);
+            if (retiredIntentIds.length > 0) {
+              emitRunEvent(root, 'intent_retired_by_phase_advance', {
+                run_id: updatedState.run_id,
+                phase: updatedState.phase,
+                status: updatedState.status,
+                turn: { turn_id: currentTurn.turn_id, role_id: currentTurn.assigned_role },
+                payload: {
+                  exited_phase: prevPhase,
+                  entered_phase: gateResult.next_phase,
+                  retired_count: retiredIntentIds.length,
+                  retired_intent_ids: retiredIntentIds,
+                },
+              });
+            }
             emitRunEvent(root, 'phase_entered', {
               run_id: updatedState.run_id,
               phase: updatedState.phase,
@@ -5226,7 +5394,7 @@ function deriveNextRecommendedRole(turnResult, state, config) {
 // intent.  Uses a hybrid approach: structural (`intent_response` field) first,
 // with semantic fallback scanning `summary`, `decisions`, and `files_changed`.
 
-function evaluateIntentCoverage(turnResult, intakeContext) {
+function evaluateIntentCoverage(turnResult, intakeContext, { state = null, config = null } = {}) {
   const acceptanceItems = intakeContext.acceptance_contract || [];
   const addressed = [];
   const unaddressed = [];
@@ -5253,6 +5421,14 @@ function evaluateIntentCoverage(turnResult, intakeContext) {
 
   for (const item of acceptanceItems) {
     const normalizedItem = item.toLowerCase().trim();
+    const lifecycle = state && config
+      ? evaluateAcceptanceItemLifecycle(item, intakeContext, state, config)
+      : null;
+
+    if (lifecycle?.phase_exited || lifecycle?.satisfied_by_gate_state) {
+      addressed.push(item);
+      continue;
+    }
 
     // Check 1: Structural — intent_response field with explicit status
     const structuralEntry = responseMap.get(normalizedItem);

package/src/lib/intake.js

@@ -23,6 +23,10 @@ import {
   formatLegacyIntentMigrationNotice,
   isPhantomIntent,
 } from './intent-startup-migration.js';
+import {
+  derivePhaseScopeFromIntentMetadata,
+  getPhaseOrder,
+} from './intent-phase-scope.js';
 
 const VALID_SOURCES = ['manual', 'ci_failure', 'git_ref_change', 'schedule', 'vision_scan'];
 const VALID_PRIORITIES = ['p0', 'p1', 'p2', 'p3'];
@@ -31,8 +35,8 @@ const INTENT_ID_RE = /^intent_\d+_[0-9a-f]{4}$/;
 
 // V3-S1 through S5 states. `failed` remains read-tolerant for historical/manual
 // intent files, but current first-party intake writers do not transition into it.
-const S1_STATES = new Set(['detected', 'triaged', 'approved', 'planned', 'executing', 'blocked', 'completed', 'failed', 'suppressed', 'rejected']);
-const TERMINAL_STATES = new Set(['suppressed', 'rejected', 'completed', 'failed']);
+const S1_STATES = new Set(['detected', 'triaged', 'approved', 'planned', 'executing', 'blocked', 'completed', 'satisfied', 'failed', 'suppressed', 'rejected']);
+const TERMINAL_STATES = new Set(['suppressed', 'rejected', 'completed', 'satisfied', 'failed']);
 const DISPATCHABLE_STATUSES = new Set(['planned', 'approved']);
 const PRIORITY_RANK = { p0: 0, p1: 1, p2: 2, p3: 3 };
 
@@ -283,7 +287,7 @@ export function validateEventPayload(payload) {
   return { valid: errors.length === 0, errors };
 }
 
-export function validateTriageFields(fields) {
+export function validateTriageFields(fields, config = null) {
   const errors = [];
 
   if (!VALID_PRIORITIES.includes(fields.priority)) {
@@ -302,6 +306,17 @@ export function validateTriageFields(fields) {
     errors.push('acceptance_contract must be a non-empty array');
   }
 
+  if ('phase_scope' in fields && fields.phase_scope != null) {
+    if (typeof fields.phase_scope !== 'string' || !fields.phase_scope.trim()) {
+      errors.push('phase_scope must be a non-empty string when provided');
+    } else if (config) {
+      const validPhases = getPhaseOrder(config);
+      if (validPhases.length > 0 && !validPhases.includes(fields.phase_scope.trim())) {
+        errors.push(`phase_scope must be one of: ${validPhases.join(', ')}`);
+      }
+    }
+  }
+
   return { valid: errors.length === 0, errors };
 }
 
@@ -355,6 +370,7 @@ export function recordEvent(root, payload) {
     template: null,
     charter: null,
     acceptance_contract: [],
+    phase_scope: null,
     requires_human_start: true,
     target_run: null,
     created_at: now,
@@ -420,17 +436,25 @@ export function triageIntent(root, intentId, fields) {
     return { ok: false, error: `cannot triage from status "${intent.status}" (must be detected)`, exitCode: 1 };
   }
 
-  const validation = validateTriageFields(fields);
+  const context = loadProjectContext(root);
+  const config = context?.config || null;
+  const normalizedFields = {
+    ...fields,
+    phase_scope: fields.phase_scope || derivePhaseScopeFromIntentMetadata(fields, config),
+  };
+
+  const validation = validateTriageFields(normalizedFields, config);
   if (!validation.valid) {
     return { ok: false, error: validation.errors.join('; '), exitCode: 1 };
   }
 
   const now = nowISO();
   intent.status = 'triaged';
-  intent.priority = fields.priority;
-  intent.template = fields.template;
-  intent.charter = fields.charter;
-  intent.acceptance_contract = fields.acceptance_contract;
+  intent.priority = normalizedFields.priority;
+  intent.template = normalizedFields.template;
+  intent.charter = normalizedFields.charter;
+  intent.acceptance_contract = normalizedFields.acceptance_contract;
+  intent.phase_scope = normalizedFields.phase_scope || null;
   intent.updated_at = now;
   intent.history.push({ from: 'detected', to: 'triaged', at: now, reason: 'triage completed' });
 
@@ -946,6 +970,7 @@ export function startIntent(root, intentId, options = {}) {
     category: event.category || null,
     charter: intent.charter || null,
     acceptance_contract: Array.isArray(intent.acceptance_contract) ? intent.acceptance_contract : [],
+    phase_scope: intent.phase_scope || null,
   };
 
   // Load governed project context
@@ -1245,7 +1270,7 @@ export function handoffIntent(root, intentId, options = {}) {
 // Resolve — execution exit and intent closure linkage (V3-S5)
 // ---------------------------------------------------------------------------
 
-export function resolveIntent(root, intentId) {
+export function resolveIntent(root, intentId, opts = {}) {
   const loadedIntent = readIntent(root, intentId);
   if (!loadedIntent.ok) {
     return loadedIntent;
@@ -1273,6 +1298,38 @@ export function resolveIntent(root, intentId) {
     };
   }
 
+  // BUG-45: operator-forced completion — transition executing → completed
+  // when the operator knows the work is done but the framework hasn't retired
+  // the intent automatically (e.g., retained-turn deadlock recovery).
+  if (opts.outcome === 'completed' && intent.status === 'executing') {
+    const now = nowISO();
+    const previousStatus = intent.status;
+    intent.status = 'completed';
+    intent.completed_at = now;
+    intent.updated_at = now;
+    if (!Array.isArray(intent.history)) intent.history = [];
+    intent.history.push({
+      from: previousStatus,
+      to: 'completed',
+      at: now,
+      reason: opts.reason || 'operator-resolved: intent marked completed via intake resolve --outcome completed',
+    });
+
+    const obsDir = join(dirs.base, 'observations', intent.intent_id);
+    mkdirSync(obsDir, { recursive: true });
+
+    safeWriteJson(intentPath, intent);
+    return {
+      ok: true,
+      intent,
+      previous_status: previousStatus,
+      new_status: 'completed',
+      run_outcome: 'completed',
+      no_change: false,
+      exitCode: 0,
+    };
+  }
+
   if (intent.target_workstream) {
     return resolveCoordinatorBackedIntent(root, intentPath, dirs, intent);
   }
@@ -1782,6 +1839,7 @@ export function injectIntent(root, description, options = {}) {
     : [description.trim()];
   const approver = options.approver || 'human';
   const noApprove = options.noApprove === true;
+  const phase_scope = options.phase_scope || null;
 
   // Step 1: Record event
   const recordResult = recordEvent(root, {
@@ -1815,6 +1873,7 @@ export function injectIntent(root, description, options = {}) {
     template,
     charter,
     acceptance_contract,
+    phase_scope,
   });
 
   if (!triageResult.ok) {

package/src/lib/intent-phase-scope.js

@@ -0,0 +1,97 @@
+function normalizeText(value) {
+  return typeof value === 'string' ? value.toLowerCase() : '';
+}
+
+export function getPhaseOrder(config) {
+  if (Array.isArray(config?.phases) && config.phases.length > 0) {
+    return config.phases
+      .map((phase) => phase?.id)
+      .filter((phaseId) => typeof phaseId === 'string' && phaseId.trim().length > 0);
+  }
+  return Object.keys(config?.routing || {});
+}
+
+export function buildGateToPhaseMap(config) {
+  const mapping = {};
+  for (const [phaseId, route] of Object.entries(config?.routing || {})) {
+    const gateId = route?.exit_gate;
+    if (typeof gateId === 'string' && gateId.trim().length > 0) {
+      mapping[gateId] = phaseId;
+    }
+  }
+  return mapping;
+}
+
+export function extractReferencedGateIds(text, config) {
+  const haystack = normalizeText(text);
+  if (!haystack) return [];
+
+  return Object.keys(config?.gates || {}).filter((gateId) => haystack.includes(gateId.toLowerCase()));
+}
+
+function derivePhaseScopeFromGateIds(gateIds, config) {
+  const gateToPhase = buildGateToPhaseMap(config);
+  const matchedPhases = [...new Set(
+    gateIds
+      .map((gateId) => gateToPhase[gateId] || null)
+      .filter(Boolean),
+  )];
+  return matchedPhases.length === 1 ? matchedPhases[0] : null;
+}
+
+export function derivePhaseScopeFromIntentMetadata(intentLike, config) {
+  const explicitScope = typeof intentLike?.phase_scope === 'string' && intentLike.phase_scope.trim().length > 0
+    ? intentLike.phase_scope.trim()
+    : null;
+  if (explicitScope) return explicitScope;
+  if (!config) return null;
+
+  const texts = [
+    intentLike?.charter || '',
+    ...(Array.isArray(intentLike?.acceptance_contract) ? intentLike.acceptance_contract : []),
+  ];
+  const gateIds = [...new Set(texts.flatMap((text) => extractReferencedGateIds(text, config)))];
+  return derivePhaseScopeFromGateIds(gateIds, config);
+}
+
+export function deriveAcceptanceItemPhaseScope(item, fallbackPhaseScope, config) {
+  if (!config) return fallbackPhaseScope || null;
+  const gateIds = extractReferencedGateIds(item, config);
+  const derived = derivePhaseScopeFromGateIds(gateIds, config);
+  return derived || fallbackPhaseScope || null;
+}
+
+export function isPhaseExited(currentPhase, scopedPhase, config) {
+  if (!currentPhase || !scopedPhase || !config) return false;
+  const order = getPhaseOrder(config);
+  const currentIndex = order.indexOf(currentPhase);
+  const scopeIndex = order.indexOf(scopedPhase);
+  if (currentIndex === -1 || scopeIndex === -1) return false;
+  return currentIndex > scopeIndex;
+}
+
+export function isAcceptanceItemSatisfiedByGateState(item, state, config) {
+  if (!state || !config) return false;
+  const itemText = normalizeText(item);
+  if (!itemText) return false;
+
+  const gateIds = extractReferencedGateIds(item, config);
+  if (gateIds.length === 0) return false;
+
+  const hasGatePassLanguage = /\b(can advance|advance to|gate can advance|gate passes|gate passed|passes|passed)\b/.test(itemText);
+  if (!hasGatePassLanguage) return false;
+
+  return gateIds.some((gateId) => state?.phase_gate_status?.[gateId] === 'passed');
+}
+
+export function evaluateAcceptanceItemLifecycle(item, intakeContext, state, config) {
+  const fallbackPhaseScope = typeof intakeContext?.phase_scope === 'string' && intakeContext.phase_scope.trim().length > 0
+    ? intakeContext.phase_scope.trim()
+    : null;
+  const phaseScope = deriveAcceptanceItemPhaseScope(item, fallbackPhaseScope, config);
+  return {
+    phase_scope: phaseScope,
+    phase_exited: isPhaseExited(state?.phase || null, phaseScope, config),
+    satisfied_by_gate_state: isAcceptanceItemSatisfiedByGateState(item, state, config),
+  };
+}

package/src/lib/recent-event-summary.js

@@ -57,10 +57,15 @@ function describeEvent(eventType, entry) {
     case 'dispatch_progress':
       return `${prefix}${eventType}${roleId ? ` [${roleId}]` : ''}`;
     case 'intents_migrated':
-    case 'intents_superseded': {
+    case 'intents_superseded':
+    case 'intent_retired_by_phase_advance': {
       const count = Number.isFinite(entry.payload?.archived_count)
         ? entry.payload.archived_count
-        : (Number.isFinite(entry.payload?.superseded_count) ? entry.payload.superseded_count : null);
+        : (
+          Number.isFinite(entry.payload?.superseded_count)
+            ? entry.payload.superseded_count
+            : (Number.isFinite(entry.payload?.retired_count) ? entry.payload.retired_count : null)
+        );
       return `${prefix}${eventType}${count !== null ? ` (${count})` : ''}`;
     }
     case 'run_blocked':

package/src/lib/repo-observer.js

@@ -50,6 +50,7 @@ const ORCHESTRATOR_STATE_FILES = [
   '.agentxchain/human-escalations.jsonl',
   '.agentxchain/sla-reminders.json',
   'TALK.md',
+  'HUMAN_TASKS.md',
 ];
 
 // Evidence paths may legitimately remain dirty across turns without blocking the

package/src/lib/run-events.js

@@ -16,6 +16,7 @@ export const VALID_RUN_EVENTS = [
   'phase_entered',
   'intents_migrated',
   'intents_superseded',
+  'intent_retired_by_phase_advance',
   'turn_dispatched',
   'turn_accepted',
   'turn_rejected',