agentxchain 2.138.0 → 2.139.0

package/package.json

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

package/src/commands/intake-approve.js

@@ -24,6 +24,14 @@ export async function intakeApproveCommand(opts) {
     console.log(JSON.stringify(result, null, 2));
   } else if (result.ok) {
     console.log('');
+    if (result.superseded) {
+      console.log(chalk.yellow(`  Superseded intent ${result.intent.intent_id}`));
+      console.log(chalk.dim(`  Approver: ${result.intent.approved_by}`));
+      console.log(chalk.dim(`  Status: ${result.intent.history.at(-2)?.to || 'triaged'} → superseded`));
+      console.log(chalk.dim(`  Reason: ${result.intent.archived_reason}`));
+      console.log('');
+      process.exit(result.exitCode);
+    }
     console.log(chalk.green(`  Approved intent ${result.intent.intent_id}`));
     console.log(chalk.dim(`  Approver: ${result.intent.approved_by}`));
     console.log(chalk.dim(`  Status: triaged → approved`));

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,69 @@ 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));
+}
+
+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,
@@ -3159,7 +3227,10 @@ function _acceptGovernedTurnLocked(root, config, opts) {
   // addresses each acceptance item.  Default: strict for p0, lenient for others.
   const intakeCtx = currentTurn.intake_context;
   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 +4048,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 +4105,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 +5327,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 +5354,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

@@ -21,7 +21,12 @@ import {
   archiveStaleIntentsForRun,
   migratePreBug34Intents,
   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'];
@@ -30,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 };
 
@@ -282,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)) {
@@ -301,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 };
 }
 
@@ -354,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,
@@ -419,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' });
 
@@ -807,6 +832,16 @@ export function approveIntent(root, intentId, options = {}) {
   intent.status = 'approved';
   intent.approved_by = approver;
   intent.updated_at = now;
+
+  const phantomReason = 'planning artifacts for this intent already exist on disk; intent superseded during approval';
+  if (intent.approved_run_id && isPhantomIntent(root, intent)) {
+    intent.status = 'superseded';
+    intent.archived_reason = phantomReason;
+    intent.history.push({ from: previousStatus, to: 'superseded', at: now, reason: phantomReason, approver });
+    safeWriteJson(intentPath, intent);
+    return { ok: true, intent, superseded: true, exitCode: 0 };
+  }
+
   intent.history.push({ from: previousStatus, to: 'approved', at: now, reason, approver });
 
   safeWriteJson(intentPath, intent);
@@ -935,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
@@ -1771,6 +1807,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, {
@@ -1804,6 +1841,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/intent-startup-migration.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 
+import { queryAcceptedTurnHistory } from './accepted-turn-history.js';
 import { safeWriteJson } from './safe-write.js';
 import { VALID_GOVERNED_TEMPLATE_IDS, loadGovernedTemplate } from './governed-templates.js';
 
@@ -28,7 +29,37 @@ function normalizeArtifactPaths(paths) {
   )];
 }
 
-function readPlanningGateFiles(root) {
+function parseTimestamp(value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function hasPlanningHistoryEvidence(root, intent) {
+  const intentId = intent?.intent_id || null;
+  const runId = intent?.approved_run_id || null;
+  const intentTimestamp = parseTimestamp(intent?.approved_at)
+    ?? parseTimestamp(intent?.created_at)
+    ?? parseTimestamp(intent?.updated_at);
+
+  for (const entry of queryAcceptedTurnHistory(root)) {
+    if (entry?.phase !== 'planning') continue;
+
+    if (intentId && entry.intent_id === intentId) {
+      return true;
+    }
+
+    if (!runId || entry.run_id !== runId || intentTimestamp === null) continue;
+    const acceptedAt = parseTimestamp(entry.accepted_at);
+    if (acceptedAt !== null && acceptedAt >= intentTimestamp) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function readPlanningGateFiles(root, intent) {
   const configPath = join(root, 'agentxchain.json');
   if (!existsSync(configPath)) return [];
 
@@ -39,27 +70,10 @@ function readPlanningGateFiles(root) {
     return [];
   }
 
-  // Only use planning gate requires_files for phantom detection when:
-  // 1. The planning gate has NOT been passed yet (once passed, these files
-  //    are expected to exist from normal planning work), AND
-  // 2. At least one turn has been completed (turn_sequence > 0). If no turns
-  //    have been completed, the files are scaffolding templates, not evidence
-  //    of completed planning work. Without this check, ANY approved intent
-  //    in a freshly scaffolded project would be falsely detected as phantom.
-  const statePath = join(root, '.agentxchain', 'state.json');
-  try {
-    const state = JSON.parse(readFileSync(statePath, 'utf8'));
-    const gateStatus = state.phase_gate_status || {};
-    const exitGateId = config?.routing?.planning?.exit_gate;
-    if (exitGateId && gateStatus[exitGateId] === 'passed') return [];
-    const turnSequence = state.turn_sequence || 0;
-    if (turnSequence === 0) return [];
-  } catch {
-    // If state is unreadable, fall through to check gate files
-  }
-
   const exitGateId = config?.routing?.planning?.exit_gate;
   const requiresFiles = exitGateId ? config?.gates?.[exitGateId]?.requires_files : null;
+  if (!Array.isArray(requiresFiles) || requiresFiles.length === 0) return [];
+  if (!hasPlanningHistoryEvidence(root, intent)) return [];
   return normalizeArtifactPaths(requiresFiles);
 }
 
@@ -146,7 +160,7 @@ export function listExpectedPlanningArtifacts(root, intent) {
   return normalizeArtifactPaths([
     ...recordedArtifacts,
     ...templateArtifacts,
-    ...readPlanningGateFiles(root),
+    ...readPlanningGateFiles(root, intent),
   ]);
 }
 

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/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',