agentxchain 2.24.3 → 2.25.0

package/package.json

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

package/src/commands/init.js

@@ -681,6 +681,7 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.dim('└──')} TALK.md`);
   console.log('');
   console.log(`  ${chalk.dim('Roles:')} pm, dev, qa, eng_director`);
+  console.log(`  ${chalk.dim('Phases:')} planning → implementation → qa ${chalk.dim('(default; extend via routing in agentxchain.json)')}`);
   console.log(`  ${chalk.dim('Template:')} ${templateId}`);
   console.log(`  ${chalk.dim('Dev runtime:')} ${formatGovernedRuntimeCommand(localDevRuntime)} ${chalk.dim(`(${localDevRuntime.prompt_transport})`)}`);
   console.log(`  ${chalk.dim('Protocol:')} governed convergence`);

package/src/lib/coordinator-config.js

@@ -6,7 +6,8 @@ import { safeParseJson } from './schema.js';
 export const COORDINATOR_CONFIG_FILE = 'agentxchain-multi.json';
 
 const VALID_ID = /^[a-z0-9_-]+$/;
-const VALID_PHASES = new Set(['planning', 'implementation', 'qa']);
+const DEFAULT_PHASES = new Set(['planning', 'implementation', 'qa']);
+const VALID_PHASE_NAME = /^[a-z][a-z0-9_-]*$/;
 const VALID_BARRIER_TYPES = new Set([
   'all_repos_accepted',
   'interface_alignment',
@@ -88,11 +89,14 @@ function validateWorkstreams(raw, repoIds, errors) {
       continue;
     }
 
-    if (!VALID_PHASES.has(workstream.phase)) {
+    // Derive valid phases from routing keys when present; fall back to defaults
+    const validPhases = raw.routing ? new Set(Object.keys(raw.routing)) : DEFAULT_PHASES;
+    if (!validPhases.has(workstream.phase)) {
+      const phaseList = [...validPhases].join(', ');
       pushError(
         errors,
         'workstream_phase_invalid',
-        `workstream "${workstreamId}" phase must be one of: planning, implementation, qa`,
+        `workstream "${workstreamId}" phase must be one of: ${phaseList}`,
       );
     }
 
@@ -279,8 +283,8 @@ function validateRouting(raw, workstreamIds, errors) {
 
   const workstreamIdSet = new Set(workstreamIds);
   for (const [phase, route] of Object.entries(raw.routing)) {
-    if (!VALID_PHASES.has(phase)) {
-      pushError(errors, 'routing_phase_invalid', `routing phase "${phase}" must be one of: planning, implementation, qa`);
+    if (!VALID_PHASE_NAME.test(phase)) {
+      pushError(errors, 'routing_phase_invalid', `routing phase "${phase}" must be lowercase alphanumeric starting with a letter (hyphens and underscores allowed)`);
     }
 
     if (!route || typeof route !== 'object' || Array.isArray(route)) {

package/src/lib/gate-evaluator.js

@@ -73,6 +73,15 @@ export function evaluatePhaseExit({ state, config, acceptedTurn, root }) {
     };
   }
 
+  const invalidOrderReason = getInvalidPhaseTransitionReason(currentPhase, transitionRequest, routing);
+  if (invalidOrderReason) {
+    return {
+      ...baseResult,
+      action: 'gate_failed',
+      reasons: [invalidOrderReason],
+    };
+  }
+
   // Find the exit gate for the current phase
   const currentRouting = routing[currentPhase];
   if (!currentRouting || !currentRouting.exit_gate) {
@@ -285,6 +294,43 @@ export function getPhaseOrder(routing) {
   return Object.keys(routing || {});
 }
 
+/**
+ * Return the next declared phase after the current phase, or null when the
+ * current phase is final or not part of the routing config.
+ *
+ * @param {string} currentPhase
+ * @param {object} routing
+ * @returns {string|null}
+ */
+export function getNextPhase(currentPhase, routing) {
+  const phases = getPhaseOrder(routing || {});
+  const currentIndex = phases.indexOf(currentPhase);
+  if (currentIndex === -1 || currentIndex >= phases.length - 1) {
+    return null;
+  }
+  return phases[currentIndex + 1];
+}
+
+/**
+ * Validate that a requested phase transition follows the declared routing
+ * order. Returns null when the request is valid.
+ *
+ * @param {string} currentPhase
+ * @param {string} requestedPhase
+ * @param {object} routing
+ * @returns {string|null}
+ */
+export function getInvalidPhaseTransitionReason(currentPhase, requestedPhase, routing) {
+  const nextPhase = getNextPhase(currentPhase, routing);
+  if (!nextPhase) {
+    return `phase_transition_request "${requestedPhase}" is invalid in final phase "${currentPhase}"; use run_completion_request instead.`;
+  }
+  if (requestedPhase !== nextPhase) {
+    return `phase_transition_request "${requestedPhase}" is invalid from phase "${currentPhase}"; next phase is "${nextPhase}".`;
+  }
+  return null;
+}
+
 /**
  * Check if a phase is the final phase in the routing config.
  *

package/src/lib/normalized-config.js

@@ -21,7 +21,8 @@ const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp'];
 const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai'];
 export const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
-const VALID_PHASES = ['planning', 'implementation', 'qa'];
+const DEFAULT_PHASES = ['planning', 'implementation', 'qa'];
+const VALID_PHASE_NAME = /^[a-z][a-z0-9_-]*$/;
 const VALID_API_PROXY_RETRY_JITTER = ['none', 'full'];
 const VALID_API_PROXY_RETRY_CLASSES = [
   'rate_limited',
@@ -400,10 +401,11 @@ export function validateV4Config(data, projectRoot) {
   }
 
   // Routing (optional but validated if present)
+  // Phase names are derived from routing keys when present; fall back to defaults
   if (data.routing) {
     for (const [phase, route] of Object.entries(data.routing)) {
-      if (!VALID_PHASES.includes(phase)) {
-        errors.push(`Routing references unknown phase: "${phase}"`);
+      if (!VALID_PHASE_NAME.test(phase)) {
+        errors.push(`Routing phase name "${phase}" must be lowercase alphanumeric starting with a letter (hyphens and underscores allowed)`);
       }
       if (route.entry_role && data.roles && !data.roles[route.entry_role]) {
         errors.push(`Routing "${phase}": entry_role "${route.entry_role}" is not a defined role`);

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

@@ -15,6 +15,7 @@
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { getActiveTurn } from './governed-state.js';
+import { getInvalidPhaseTransitionReason } from './gate-evaluator.js';
 
 // ── Constants ────────────────────────────────────────────────────────────────
 
@@ -519,6 +520,15 @@ function validateProtocol(tr, state, config) {
       errors.push(
         `phase_transition_request "${tr.phase_transition_request}" is not a defined phase in routing.`
       );
+    } else if (config.routing && state?.phase) {
+      const invalidOrderReason = getInvalidPhaseTransitionReason(
+        state.phase,
+        tr.phase_transition_request,
+        config.routing
+      );
+      if (invalidOrderReason) {
+        errors.push(invalidOrderReason);
+      }
     }
   }