agentxchain 2.24.1 → 2.24.2

package/package.json

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

package/scripts/release-postflight.sh

@@ -101,6 +101,27 @@ trim_last_line() {
   printf '%s\n' "$1" | awk 'NF { line=$0 } END { gsub(/^[[:space:]]+|[[:space:]]+$/, "", line); print line }'
 }
 
+extract_matching_line() {
+  local output="$1"
+  local expected="$2"
+  printf '%s\n' "$output" | awk -v expected="$expected" '
+    {
+      line=$0
+      gsub(/^[[:space:]]+|[[:space:]]+$/, "", line)
+      if (line == expected) {
+        print line
+        found=1
+        exit
+      }
+    }
+    END {
+      if (!found) {
+        exit 1
+      }
+    }
+  '
+}
+
 run_install_smoke() {
   if [[ -z "$TARBALL_URL" ]]; then
     echo "registry tarball metadata unavailable for install smoke" >&2
@@ -147,18 +168,21 @@ run_npx_smoke() {
   local npx_status
 
   smoke_root="$(mktemp -d "${TMPDIR:-/tmp}/agentxchain-npx-postflight.XXXXXX")"
-  mkdir -p "${smoke_root}/home" "${smoke_root}/cache" "${smoke_root}/npm-cache"
+  mkdir -p "${smoke_root}/home" "${smoke_root}/cache" "${smoke_root}/npm-cache" "${smoke_root}/workspace"
 
   smoke_npmrc="${smoke_root}/.npmrc"
   echo "registry=https://registry.npmjs.org/" > "$smoke_npmrc"
 
   npx_output="$(
-    env -u NODE_AUTH_TOKEN \
-      HOME="${smoke_root}/home" \
-      XDG_CACHE_HOME="${smoke_root}/cache" \
-      NPM_CONFIG_CACHE="${smoke_root}/npm-cache" \
-      NPM_CONFIG_USERCONFIG="$smoke_npmrc" \
-      npx --yes "${PACKAGE_NAME}@${TARGET_VERSION}" --version 2>&1
+    (
+      cd "${smoke_root}/workspace" || exit 1
+      env -u NODE_AUTH_TOKEN \
+        HOME="${smoke_root}/home" \
+        XDG_CACHE_HOME="${smoke_root}/cache" \
+        NPM_CONFIG_CACHE="${smoke_root}/npm-cache" \
+        NPM_CONFIG_USERCONFIG="$smoke_npmrc" \
+        npx --yes -p "${PACKAGE_NAME}@${TARGET_VERSION}" -c "${PACKAGE_BIN_NAME} --version" 2>&1
+    )
   )"
   npx_status=$?
 
@@ -342,7 +366,7 @@ fi
 
 echo "[5/7] npx smoke"
 if run_with_retry NPX_OUTPUT "npx smoke" nonempty "" run_npx_smoke; then
-  NPX_VERSION="$(trim_last_line "$NPX_OUTPUT")"
+  NPX_VERSION="$(extract_matching_line "$NPX_OUTPUT" "$TARGET_VERSION" 2>/dev/null || trim_last_line "$NPX_OUTPUT")"
   if [[ "$NPX_VERSION" == "$TARGET_VERSION" ]]; then
     pass "published npx command resolves and reports ${TARGET_VERSION}"
   else

package/src/commands/demo.js

@@ -605,7 +605,7 @@ All acceptance criteria met. OBJ-002 (clock skew) noted for follow-up. OBJ-003 (
       console.log(chalk.dim('  ─'.repeat(26)));
       console.log('');
       console.log(`  ${chalk.bold('Try it for real:')}  agentxchain init --governed`);
-      console.log(`  ${chalk.bold('Step by step:')}    https://agentxchain.dev/docs/first-turn`);
+      console.log(`  ${chalk.bold('Step by step:')}    https://agentxchain.dev/docs/getting-started`);
       console.log(`  ${chalk.bold('Read more:')}       https://agentxchain.dev/docs/quickstart`);
       console.log('');
     }

package/src/commands/init.js

@@ -105,6 +105,7 @@ const GOVERNED_RUNTIMES = {
   'manual-pm': { type: 'manual' },
   'local-dev': DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME,
   'api-qa': { type: 'api_proxy', provider: 'anthropic', model: 'claude-sonnet-4-6', auth_env: 'ANTHROPIC_API_KEY' },
+  'manual-qa': { type: 'manual' },
   'manual-director': { type: 'manual' }
 };
 
@@ -684,6 +685,29 @@ async function initGoverned(opts) {
   console.log(`  ${chalk.dim('Dev runtime:')} ${formatGovernedRuntimeCommand(localDevRuntime)} ${chalk.dim(`(${localDevRuntime.prompt_transport})`)}`);
   console.log(`  ${chalk.dim('Protocol:')} governed convergence`);
   console.log('');
+
+  // Readiness hint: tell user which roles work immediately vs which need API keys
+  const allRuntimes = { ...GOVERNED_RUNTIMES, 'local-dev': localDevRuntime };
+  const needsKey = Object.entries(allRuntimes)
+    .filter(([, rt]) => rt.auth_env)
+    .map(([id, rt]) => ({ id, env: rt.auth_env }));
+  if (needsKey.length > 0) {
+    const envVars = [...new Set(needsKey.map(r => r.env))];
+    const roleNames = needsKey.map(r => r.id);
+    const hasKeys = envVars.every(v => process.env[v]);
+    if (hasKeys) {
+      console.log(`  ${chalk.green('Ready:')} all runtimes configured (${envVars.join(', ')} detected)`);
+    } else {
+      console.log(`  ${chalk.yellow('Mixed-mode:')} pm and eng_director work immediately (manual).`);
+      console.log(`  ${chalk.yellow('  ')}${roleNames.join(', ')} need ${chalk.bold(envVars.join(', '))} to dispatch automatically.`);
+      console.log(`  ${chalk.yellow('  ')}Without it, those turns fall back to manual input.`);
+      if (allRuntimes['manual-qa']) {
+        console.log(`  ${chalk.yellow('  ')}No-key QA path: change ${chalk.bold('roles.qa.runtime')} from ${chalk.bold('"api-qa"')} to ${chalk.bold('"manual-qa"')} in ${chalk.bold('agentxchain.json')}.`);
+      }
+    }
+    console.log('');
+  }
+
   console.log(`  ${chalk.cyan('Next:')}`);
   if (dir !== process.cwd()) {
     console.log(`    ${chalk.bold(`cd ${targetLabel}`)}`);
@@ -691,6 +715,8 @@ async function initGoverned(opts) {
   console.log(`    ${chalk.bold('agentxchain step')} ${chalk.dim('# run the first governed turn')}`);
   console.log(`    ${chalk.bold('agentxchain status')} ${chalk.dim('# inspect phase, gate, and turn state')}`);
   console.log('');
+  console.log(`  ${chalk.dim('Guide:')} https://agentxchain.dev/docs/getting-started`);
+  console.log('');
 }
 
 export async function initCommand(opts) {

package/src/commands/run.js

@@ -47,7 +47,7 @@ export async function runCommand(opts) {
     process.exit(1);
   }
 
-  const { root, config } = context;
+  const { root, config, rawConfig } = context;
 
   if (config.protocol_mode !== 'governed') {
     console.log(chalk.red('The run command is only available for governed projects.'));
@@ -112,6 +112,7 @@ export async function runCommand(opts) {
 
   // ── Track first-call for --role override ────────────────────────────────
   let firstSelectRole = true;
+  let qaMissingCredentialsFallback = null;
 
   // ── Callbacks ───────────────────────────────────────────────────────────
   const callbacks = {
@@ -134,6 +135,7 @@ export async function runCommand(opts) {
       const runtime = cfg.runtimes?.[runtimeId];
       const runtimeType = runtime?.type || role?.runtime_class || 'manual';
       const hooksConfig = cfg.hooks || {};
+      qaMissingCredentialsFallback = null;
 
       // Manual adapter is not supported in run mode
       if (runtimeType === 'manual') {
@@ -219,6 +221,18 @@ export async function runCommand(opts) {
 
       // Adapter failure
       if (!adapterResult.ok) {
+        if (shouldPrintManualQaFallback({
+          roleId,
+          runtimeId,
+          classified: adapterResult.classified,
+          rawConfig,
+        })) {
+          qaMissingCredentialsFallback = {
+            roleId,
+            runtimeId,
+            errorClass: adapterResult.classified.error_class,
+          };
+        }
         const errorDetail = adapterResult.classified
           ? `${adapterResult.classified.error_class}: ${adapterResult.classified.recovery}`
           : adapterResult.error;
@@ -317,6 +331,10 @@ export async function runCommand(opts) {
     }
   }
 
+  if (qaMissingCredentialsFallback) {
+    printManualQaFallback();
+  }
+
   // Recovery guidance for blocked/rejected states
   if (result.state && (result.stop_reason === 'blocked' || result.stop_reason === 'reject_exhausted' || result.stop_reason === 'dispatch_error')) {
     const recovery = deriveRecoveryDescriptor(result.state);
@@ -391,3 +409,18 @@ function promptUser(question) {
     rl.on('close', () => resolve(''));
   });
 }
+
+function shouldPrintManualQaFallback({ roleId, runtimeId, classified, rawConfig }) {
+  return classified?.error_class === 'missing_credentials'
+    && roleId === 'qa'
+    && runtimeId === 'api-qa'
+    && rawConfig?.runtimes?.['manual-qa']?.type === 'manual';
+}
+
+function printManualQaFallback() {
+  console.log('');
+  console.log(chalk.dim('  No-key QA fallback:'));
+  console.log(chalk.dim('  - Edit agentxchain.json and change roles.qa.runtime from "api-qa" to "manual-qa"'));
+  console.log(chalk.dim('  - Then recover the retained QA turn with: agentxchain step --resume'));
+  console.log(chalk.dim('  - Guide: https://agentxchain.dev/docs/getting-started'));
+}

package/src/commands/step.js

@@ -71,7 +71,7 @@ export async function stepCommand(opts) {
     process.exit(1);
   }
 
-  const { root, config } = context;
+  const { root, config, rawConfig } = context;
 
   if (config.protocol_mode !== 'governed') {
     console.log(chalk.red('The step command is only available for governed projects.'));
@@ -422,6 +422,18 @@ export async function stepCommand(opts) {
         console.log(chalk.dim(`  Retry trace: ${apiResult.retry_trace_path}`));
       }
 
+      if (
+        apiResult.classified?.error_class === 'missing_credentials'
+        && roleId === 'qa'
+        && config.roles?.qa?.runtime_id === 'api-qa'
+        && rawConfig?.runtimes?.['manual-qa']?.type === 'manual'
+      ) {
+        console.log(chalk.dim('  No-key QA fallback:'));
+        console.log(chalk.dim('  - Edit agentxchain.json and change roles.qa.runtime from "api-qa" to "manual-qa"'));
+        console.log(chalk.dim('  - Then rerun: agentxchain step --resume'));
+        console.log(chalk.dim('  - Guide: https://agentxchain.dev/docs/getting-started'));
+      }
+
       console.log(chalk.dim('The turn remains assigned. You can:'));
       console.log(chalk.dim('  - Fix the issue and retry: agentxchain step --resume'));
       console.log(chalk.dim('  - Complete manually: edit .agentxchain/staging/turn-result.json'));

package/src/lib/adapters/manual-adapter.js

@@ -30,31 +30,100 @@ export function printManualDispatchInstructions(state, config, options = {}) {
   const role = config.roles?.[turn.assigned_role];
   const promptPath = getDispatchPromptPath(turn.turn_id);
   const stagingPath = getTurnStagingResultPath(turn.turn_id);
+  const phase = state.phase || 'planning';
+  const roleId = turn.assigned_role;
 
   const lines = [];
   lines.push('');
   lines.push('  +---------------------------------------------------------+');
   lines.push('  |  MANUAL TURN REQUIRED                                    |');
   lines.push('  |                                                          |');
-  lines.push(`  |  Role:    ${pad(turn.assigned_role, 46)}|`);
+  lines.push(`  |  Role:    ${pad(roleId, 46)}|`);
   lines.push(`  |  Turn:    ${pad(turn.turn_id, 46)}|`);
-  lines.push(`  |  Phase:   ${pad(state.phase, 46)}|`);
+  lines.push(`  |  Phase:   ${pad(phase, 46)}|`);
   lines.push(`  |  Attempt: ${pad(String(turn.attempt), 46)}|`);
   lines.push('  |                                                          |');
   lines.push(`  |  Prompt:  ${pad(promptPath, 46)}|`);
   lines.push(`  |  Result:  ${pad(stagingPath, 46)}|`);
-  lines.push('  |                                                          |');
-  lines.push('  |  1. Read the prompt at the path above                    |');
-  lines.push('  |  2. Complete the work described in the prompt             |');
-  lines.push('  |  3. Write your turn result JSON to the result path       |');
-  lines.push('  |                                                          |');
-  lines.push('  |  The step command will detect the file and proceed.      |');
   lines.push('  +---------------------------------------------------------+');
   lines.push('');
+  lines.push('  Steps:');
+  lines.push(`    1. Read the prompt:   cat ${promptPath}`);
+  lines.push('    2. Do the work described in the prompt');
+  lines.push(`    3. Write turn-result.json to:  ${stagingPath}`);
+  lines.push('    4. The step command will detect the file and proceed');
+  lines.push('');
+
+  // Phase-aware guidance
+  const gateHints = getPhaseGateHints(phase, roleId, config);
+  if (gateHints.length > 0) {
+    lines.push('  Gate files to update this phase:');
+    for (const hint of gateHints) {
+      lines.push(`    - ${hint}`);
+    }
+    lines.push('');
+  }
+
+  // Minimal turn-result example
+  lines.push('  Minimal turn-result.json:');
+  lines.push('  {');
+  lines.push('    "schema_version": "1.0",');
+  lines.push(`    "run_id": "${state.run_id || 'run_...'}",`);
+  lines.push(`    "turn_id": "${turn.turn_id}",`);
+  lines.push(`    "role": "${roleId}",`);
+  lines.push(`    "runtime_id": "${role?.runtime || 'manual'}",`);
+  lines.push('    "status": "completed",');
+  lines.push('    "summary": "...",');
+  lines.push('    "decisions": [{"id":"DEC-001","category":"scope","statement":"...","rationale":"..."}],');
+  lines.push('    "objections": [{"id":"OBJ-001","severity":"medium","statement":"...","status":"raised"}],');
+  lines.push('    "files_changed": [],');
+  lines.push('    "verification": {"status":"skipped","commands":[],"evidence_summary":"..."},');
+  lines.push('    "artifact": {"type":"review","ref":null},');
+  lines.push(`    "proposed_next_role": "${getDefaultNextRole(roleId, config)}",`);
+  lines.push('    "phase_transition_request": null,');
+  lines.push('    "run_completion_request": null');
+  lines.push('  }');
+  lines.push('');
+  lines.push('  Docs: https://agentxchain.dev/docs/getting-started');
+  lines.push('');
 
   return lines.join('\n');
 }
 
+/**
+ * Return gate-file hints relevant to the current phase and role.
+ */
+function getPhaseGateHints(phase, roleId, config) {
+  const hints = [];
+  const gates = config.gates || {};
+
+  if (phase === 'planning' && (roleId === 'pm' || roleId === 'human')) {
+    hints.push('.planning/PM_SIGNOFF.md — change "Approved: NO" → "Approved: YES" when ready');
+    hints.push('.planning/ROADMAP.md — define phases and acceptance criteria');
+    hints.push('.planning/SYSTEM_SPEC.md — define ## Purpose, ## Interface, ## Acceptance Tests');
+  } else if (phase === 'implementation' && (roleId === 'dev' || roleId === 'human')) {
+    hints.push('.planning/IMPLEMENTATION_NOTES.md — record what you built and how to verify');
+  } else if (phase === 'qa' && (roleId === 'qa' || roleId === 'human')) {
+    hints.push('.planning/acceptance-matrix.md — mark each requirement PASS/FAIL');
+    hints.push('.planning/ship-verdict.md — change "## Verdict: PENDING" → "## Verdict: SHIP"');
+    hints.push('.planning/RELEASE_NOTES.md — user impact, verification summary, upgrade notes');
+  }
+
+  return hints;
+}
+
+/**
+ * Suggest a reasonable next role based on current role.
+ */
+function getDefaultNextRole(roleId, config) {
+  const routing = config.routing || {};
+  if (routing[roleId]?.default_next) return routing[roleId].default_next;
+  if (roleId === 'pm') return 'dev';
+  if (roleId === 'dev') return 'qa';
+  if (roleId === 'qa') return 'human';
+  return 'human';
+}
+
 /**
  * Wait for the staged turn result file to appear.
  *