agentxchain 2.11.0 → 2.13.0

package/README.md

@@ -25,7 +25,7 @@ npm install -g agentxchain
 Or run without installing:
 
 ```bash
-npx agentxchain init --governed -y
+npx agentxchain init --governed --dir my-agentxchain-project -y
 ```
 
 ## Testing
@@ -49,7 +49,7 @@ Duplicate execution remains intentional for the current 36-file slice until a la
 ### Governed workflow
 
 ```bash
-npx agentxchain init --governed -y
+npx agentxchain init --governed --dir my-agentxchain-project -y
 cd my-agentxchain-project
 git init
 git add -A
@@ -58,10 +58,16 @@ agentxchain status
 agentxchain step --role pm
 ```
 
+The default governed dev runtime is `claude --print` with stdin prompt delivery. If your local coding agent uses a different launch contract, set it during scaffold creation:
+
+```bash
+npx agentxchain init --governed --dir my-agentxchain-project --dev-command ./scripts/dev-agent.sh --dev-prompt-transport dispatch_bundle_only -y
+```
+
 If you want template-specific planning artifacts from day one:
 
 ```bash
-npx agentxchain init --governed --template api-service -y
+npx agentxchain init --governed --template api-service --dir my-agentxchain-project -y
 ```
 
 Built-in governed templates:
@@ -83,7 +89,20 @@ agentxchain step --role qa
 agentxchain approve-completion
 ```
 
-Default governed scaffolding configures QA as `api_proxy` with `ANTHROPIC_API_KEY`. For a provider-free walkthrough, switch the QA runtime to `manual` before the QA step.
+Default governed scaffolding configures QA as `api_proxy` with `ANTHROPIC_API_KEY`. For a provider-free walkthrough, switch the QA runtime to `manual` before the QA step. If you override the dev runtime, either include `{prompt}` for argv delivery or set `--dev-prompt-transport` explicitly.
+
+### Multi-repo coordination
+
+For initiatives spanning multiple governed repos, use the coordinator to add cross-repo sequencing and shared gates:
+
+```bash
+npx agentxchain init --governed --template api-service --dir repos/backend -y
+npx agentxchain init --governed --template web-app --dir repos/frontend -y
+agentxchain multi init
+agentxchain multi step --repo backend --role pm
+```
+
+See the [multi-repo quickstart](https://agentxchain.dev/docs/quickstart#multi-repo-cold-start) for the full cold-start walkthrough.
 
 ### Migrate a legacy project
 
@@ -99,7 +118,7 @@ agentxchain step
 
 | Command | What it does |
 |---|---|
-| `init --governed [--template <id>]` | Create a governed project, optionally with project-shape-specific planning artifacts |
+| `init --governed [--dir <path>] [--template <id>]` | Create a governed project, optionally in-place or in an explicit target directory, with project-shape-specific planning artifacts |
 | `migrate` | Convert a legacy v3 project to governed format |
 | `status` | Show current run, template, phase, turn, and approval state |
 | `resume` | Initialize or continue a governed run and assign the next turn |

package/bin/agentxchain.js

@@ -115,7 +115,10 @@ program
   .description('Create a new AgentXchain project folder')
   .option('-y, --yes', 'Skip prompts, use defaults')
   .option('--governed', 'Create a governed project (orchestrator-owned state)')
+  .option('--dir <path>', 'Scaffold target directory. Use "." for in-place bootstrap.')
   .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, library, web-app')
+  .option('--dev-command <parts...>', 'Governed local-dev command parts. Include {prompt} for argv prompt delivery.')
+  .option('--dev-prompt-transport <mode>', 'Governed local-dev prompt transport: argv, stdin, dispatch_bundle_only')
   .option('--schema-version <version>', 'Schema version (3 for legacy, or use --governed for current)')
   .action(initCommand);
 

package/package.json

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

package/src/commands/init.js

@@ -1,11 +1,12 @@
 import { writeFileSync, readFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
-import { join, resolve, dirname } from 'path';
+import { basename, join, relative, resolve, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { CONFIG_FILE, LOCK_FILE, STATE_FILE } from '../lib/config.js';
 import { generateVSCodeFiles } from '../lib/generate-vscode.js';
 import { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
+import { VALID_PROMPT_TRANSPORTS } from '../lib/normalized-config.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '../templates');
@@ -93,9 +94,16 @@ const GOVERNED_ROLES = {
   }
 };
 
+const DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME = Object.freeze({
+  type: 'local_cli',
+  command: ['claude', '--print'],
+  cwd: '.',
+  prompt_transport: 'stdin',
+});
+
 const GOVERNED_RUNTIMES = {
   'manual-pm': { type: 'manual' },
-  'local-dev': { type: 'local_cli', command: ['claude', '--print', '-p', '{prompt}'], cwd: '.', prompt_transport: 'argv' },
+  '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-director': { type: 'manual' }
 };
@@ -353,8 +361,92 @@ ${role.write_authority === 'authoritative'
 `;
 }
 
-export function scaffoldGoverned(dir, projectName, projectId, templateId = 'generic') {
+function commandHasPromptPlaceholder(parts = []) {
+  return parts.some((part) => typeof part === 'string' && part.includes('{prompt}'));
+}
+
+function resolveGovernedLocalDevRuntime(opts = {}) {
+  const customCommand = Array.isArray(opts.devCommand)
+    ? opts.devCommand.map((part) => String(part).trim()).filter(Boolean)
+    : null;
+  const explicitTransport = typeof opts.devPromptTransport === 'string' && opts.devPromptTransport.trim()
+    ? opts.devPromptTransport.trim()
+    : null;
+
+  if (explicitTransport && !VALID_PROMPT_TRANSPORTS.includes(explicitTransport)) {
+    throw new Error(`Unknown --dev-prompt-transport "${explicitTransport}". Valid values: ${VALID_PROMPT_TRANSPORTS.join(', ')}`);
+  }
+
+  if (!customCommand?.length) {
+    const command = [...DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME.command];
+    if (explicitTransport === 'argv') {
+      throw new Error('Default local dev command does not include {prompt}. Use --dev-command ... {prompt} for argv mode.');
+    }
+    return {
+      runtime: {
+        ...DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME,
+        command,
+        prompt_transport: explicitTransport || DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME.prompt_transport,
+      },
+    };
+  }
+
+  const hasPlaceholder = commandHasPromptPlaceholder(customCommand);
+
+  if (!explicitTransport && !hasPlaceholder) {
+    throw new Error('Custom --dev-command must either include {prompt} or set --dev-prompt-transport explicitly.');
+  }
+
+  if (explicitTransport === 'argv' && !hasPlaceholder) {
+    throw new Error('--dev-prompt-transport argv requires {prompt} in --dev-command.');
+  }
+
+  if (explicitTransport && explicitTransport !== 'argv' && hasPlaceholder) {
+    throw new Error(`--dev-prompt-transport ${explicitTransport} must not be combined with {prompt} in --dev-command.`);
+  }
+
+  return {
+    runtime: {
+      type: 'local_cli',
+      command: customCommand,
+      cwd: '.',
+      prompt_transport: explicitTransport || 'argv',
+    },
+  };
+}
+
+function formatGovernedRuntimeCommand(runtime) {
+  return Array.isArray(runtime?.command) ? runtime.command.join(' ') : String(runtime?.command || '');
+}
+
+function resolveInitDirOption(dirOption) {
+  if (dirOption == null) return null;
+  const value = String(dirOption).trim();
+  if (!value) {
+    throw new Error('--dir must not be empty.');
+  }
+  return value;
+}
+
+function inferProjectNameFromTarget(targetPath, fallbackName) {
+  const inferred = basename(resolve(process.cwd(), targetPath));
+  return inferred && inferred.trim() ? inferred : fallbackName;
+}
+
+function formatInitTarget(dir) {
+  const rel = relative(process.cwd(), dir);
+  if (!rel) return '.';
+  if (!rel.startsWith('..')) return rel;
+  return dir;
+}
+
+export function scaffoldGoverned(dir, projectName, projectId, templateId = 'generic', runtimeOptions = {}) {
   const template = loadGovernedTemplate(templateId);
+  const { runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(runtimeOptions);
+  const runtimes = {
+    ...GOVERNED_RUNTIMES,
+    'local-dev': localDevRuntime,
+  };
   const config = {
     schema_version: '1.0',
     template: template.id,
@@ -364,7 +456,7 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
       default_branch: 'main'
     },
     roles: GOVERNED_ROLES,
-    runtimes: GOVERNED_RUNTIMES,
+    runtimes,
     routing: GOVERNED_ROUTING,
     gates: GOVERNED_GATES,
     budget: {
@@ -475,6 +567,14 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
 async function initGoverned(opts) {
   let projectName, folderName;
   const templateId = opts.template || 'generic';
+  let explicitDir;
+
+  try {
+    explicitDir = resolveInitDirOption(opts.dir);
+  } catch (err) {
+    console.error(chalk.red(`  Error: ${err.message}`));
+    process.exit(1);
+  }
 
   if (!VALID_GOVERNED_TEMPLATE_IDS.includes(templateId)) {
     console.error(chalk.red(`  Error: Unknown template "${templateId}".`));
@@ -489,29 +589,44 @@ async function initGoverned(opts) {
   }
 
   if (opts.yes) {
-    projectName = 'My AgentXchain Project';
-    folderName = slugify(projectName);
+    projectName = explicitDir
+      ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain Project')
+      : 'My AgentXchain Project';
+    folderName = explicitDir || slugify(projectName);
   } else {
     const { name } = await inquirer.prompt([{
       type: 'input',
       name: 'name',
       message: 'Project name:',
-      default: 'My AgentXchain Project'
+      default: explicitDir
+        ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain Project')
+        : 'My AgentXchain Project'
     }]);
     projectName = name;
-    folderName = slugify(projectName);
+    folderName = explicitDir || slugify(projectName);
 
-    const { folder } = await inquirer.prompt([{
-      type: 'input',
-      name: 'folder',
-      message: 'Folder name:',
-      default: folderName
-    }]);
-    folderName = folder;
+    if (!explicitDir) {
+      const { folder } = await inquirer.prompt([{
+        type: 'input',
+        name: 'folder',
+        message: 'Folder name:',
+        default: folderName
+      }]);
+      folderName = folder;
+    }
   }
 
   const dir = resolve(process.cwd(), folderName);
+  const targetLabel = formatInitTarget(dir);
   const projectId = slugify(projectName);
+  let localDevRuntime;
+
+  try {
+    ({ runtime: localDevRuntime } = resolveGovernedLocalDevRuntime(opts));
+  } catch (err) {
+    console.error(chalk.red(`  Error: ${err.message}`));
+    process.exit(1);
+  }
 
   if (existsSync(dir) && existsSync(join(dir, CONFIG_FILE))) {
     if (!opts.yes) {
@@ -530,10 +645,10 @@ async function initGoverned(opts) {
 
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 
-  scaffoldGoverned(dir, projectName, projectId, templateId);
+  scaffoldGoverned(dir, projectName, projectId, templateId, opts);
 
   console.log('');
-  console.log(chalk.green(`  ✓ Created governed project ${chalk.bold(folderName)}/`));
+  console.log(chalk.green(`  ✓ Created governed project ${chalk.bold(targetLabel)}/`));
   console.log('');
   console.log(`    ${chalk.dim('├──')} agentxchain.json  ${chalk.dim('(governed)')}`);
   console.log(`    ${chalk.dim('├──')} .agentxchain/`);
@@ -549,10 +664,13 @@ async function initGoverned(opts) {
   console.log('');
   console.log(`  ${chalk.dim('Roles:')} pm, dev, qa, eng_director`);
   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`);
   console.log('');
   console.log(`  ${chalk.cyan('Next:')}`);
-  console.log(`    ${chalk.bold(`cd ${folderName}`)}`);
+  if (dir !== process.cwd()) {
+    console.log(`    ${chalk.bold(`cd ${targetLabel}`)}`);
+  }
   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('');
@@ -564,11 +682,20 @@ export async function initCommand(opts) {
   }
 
   let project, agents, folderName, rules;
+  let explicitDir;
+  try {
+    explicitDir = resolveInitDirOption(opts.dir);
+  } catch (err) {
+    console.error(chalk.red(`  Error: ${err.message}`));
+    process.exit(1);
+  }
 
   if (opts.yes) {
-    project = 'My AgentXchain project';
+    project = explicitDir
+      ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain project')
+      : 'My AgentXchain project';
     agents = DEFAULT_AGENTS;
-    folderName = slugify(project);
+    folderName = explicitDir || slugify(project);
     rules = {
       max_consecutive_claims: 2,
       require_message: true,
@@ -618,7 +745,9 @@ export async function initCommand(opts) {
         type: 'input',
         name: 'projectName',
         message: 'Project name:',
-        default: 'My AgentXchain project'
+        default: explicitDir
+          ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain project')
+          : 'My AgentXchain project'
       }]);
       project = projectName;
     } else {
@@ -626,7 +755,9 @@ export async function initCommand(opts) {
         type: 'input',
         name: 'projectName',
         message: 'Project name:',
-        default: 'My AgentXchain project'
+        default: explicitDir
+          ? inferProjectNameFromTarget(explicitDir, 'My AgentXchain project')
+          : 'My AgentXchain project'
       }]);
       project = projectName;
       agents = {};
@@ -681,14 +812,16 @@ export async function initCommand(opts) {
       }
     }
 
-    folderName = slugify(project);
-    const { folder } = await inquirer.prompt([{
-      type: 'input',
-      name: 'folder',
-      message: 'Folder name:',
-      default: folderName
-    }]);
-    folderName = folder;
+    folderName = explicitDir || slugify(project);
+    if (!explicitDir) {
+      const { folder } = await inquirer.prompt([{
+        type: 'input',
+        name: 'folder',
+        message: 'Folder name:',
+        default: folderName
+      }]);
+      folderName = folder;
+    }
   }
 
   const dir = resolve(process.cwd(), folderName);

package/src/lib/coordinator-recovery.js

@@ -66,6 +66,16 @@ function readRepoLocalHistory(repoPath) {
   }
 }
 
+function isAcceptedRepoHistoryEntry(entry) {
+  if (!entry || typeof entry !== 'object') {
+    return false;
+  }
+
+  // Real governed history records the turn outcome in `status` and acceptance
+  // via `accepted_at`. Older coordinator fixtures used `status: "accepted"`.
+  return Boolean(entry.accepted_at) || entry.status === 'accepted';
+}
+
 // ── Divergence Detection ────────────────────────────────────────────────────
 
 /**
@@ -166,7 +176,7 @@ export function detectDivergence(workspacePath, state, config) {
       // Read repo-local history to determine what happened
       const repoHistory = readRepoLocalHistory(repo.resolved_path);
       const turnAccepted = repoHistory.some(
-        e => e?.turn_id === dispatch.repo_turn_id && e?.status === 'accepted'
+        e => e?.turn_id === dispatch.repo_turn_id && isAcceptedRepoHistoryEntry(e)
       );
       const turnRejected = repoHistory.some(
         e => e?.turn_id === dispatch.repo_turn_id && e?.status === 'rejected'
@@ -279,7 +289,7 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
 
     const repoHistory = readRepoLocalHistory(repo.resolved_path);
     const acceptedEntry = repoHistory.find(
-      e => e?.turn_id === dispatch.repo_turn_id && e?.status === 'accepted'
+      e => e?.turn_id === dispatch.repo_turn_id && isAcceptedRepoHistoryEntry(e)
     );
 
     if (acceptedEntry) {

package/src/lib/gate-evaluator.js

@@ -19,6 +19,7 @@
 
 import { existsSync } from 'fs';
 import { join } from 'path';
+import { evaluateWorkflowGateSemantics } from './workflow-gate-semantics.js';
 
 /**
  * Evaluate whether the current phase exit gate is satisfied.
@@ -113,6 +114,12 @@ export function evaluatePhaseExit({ state, config, acceptedTurn, root }) {
       if (!existsSync(join(root, filePath))) {
         result.missing_files.push(filePath);
         failures.push(`Required file missing: ${filePath}`);
+        continue;
+      }
+
+      const semanticCheck = evaluateWorkflowGateSemantics(root, filePath);
+      if (semanticCheck && !semanticCheck.ok) {
+        failures.push(semanticCheck.reason);
       }
     }
   }
@@ -229,6 +236,12 @@ export function evaluateRunCompletion({ state, config, acceptedTurn, root }) {
       if (!existsSync(join(root, filePath))) {
         result.missing_files.push(filePath);
         failures.push(`Required file missing: ${filePath}`);
+        continue;
+      }
+
+      const semanticCheck = evaluateWorkflowGateSemantics(root, filePath);
+      if (semanticCheck && !semanticCheck.ok) {
+        failures.push(semanticCheck.reason);
       }
     }
   }

package/src/lib/normalized-config.js

@@ -19,7 +19,7 @@ import { SUPPORTED_TOKEN_COUNTER_PROVIDERS } from './token-counter.js';
 const VALID_WRITE_AUTHORITIES = ['authoritative', 'proposed', 'review_only'];
 const VALID_RUNTIME_TYPES = ['manual', 'local_cli', 'api_proxy', 'mcp'];
 const VALID_API_PROXY_PROVIDERS = ['anthropic', 'openai'];
-const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
+export const VALID_PROMPT_TRANSPORTS = ['argv', 'stdin', 'dispatch_bundle_only'];
 const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
 const VALID_PHASES = ['planning', 'implementation', 'qa'];
 const VALID_API_PROXY_RETRY_JITTER = ['none', 'full'];

package/src/lib/reference-conformance-adapter.js

@@ -1,7 +1,7 @@
 import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { evaluatePhaseExit } from './gate-evaluator.js';
+import { evaluatePhaseExit, evaluateRunCompletion } from './gate-evaluator.js';
 import {
   approvePhaseTransition,
   approveRunCompletion,
@@ -708,6 +708,51 @@ function executeFixtureOperation(workspace, fixture) {
       };
     }
 
+    case 'evaluate_run_completion': {
+      const state = readJson(join(root, '.agentxchain', 'state.json'));
+      const acceptedTurn = {
+        run_completion_request: fixture.setup.turn_result?.run_completion_request ?? true,
+        verification: fixture.setup.turn_result?.verification || { status: 'pass' },
+      };
+      const result = evaluateRunCompletion({
+        state,
+        config: fixtureConfig,
+        acceptedTurn,
+        root,
+      });
+
+      if (result.action === 'awaiting_human_approval') {
+        return {
+          result: 'success',
+          action: result.action,
+          new_status: 'paused',
+          pending_run_completion: {
+            phase: state.phase,
+            gate: result.gate_id,
+          },
+        };
+      }
+
+      if (result.action === 'complete') {
+        return {
+          result: 'success',
+          action: result.action,
+          new_status: 'completed',
+        };
+      }
+
+      return {
+        result: 'success',
+        action: result.action,
+        state_unchanged: true,
+        reason: result.missing_files.length > 0
+          ? 'requires_files predicate failed'
+          : result.missing_verification
+            ? 'requires_verification_pass predicate failed'
+            : (result.reasons[0] || null),
+      };
+    }
+
     case 'append_decision': {
       const ledgerPath = join(root, '.agentxchain', 'decision-ledger.jsonl');
       const existingLedger = readJsonl(ledgerPath);

package/src/lib/workflow-gate-semantics.js

@@ -0,0 +1,79 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const PM_SIGNOFF_PATH = '.planning/PM_SIGNOFF.md';
+export const SHIP_VERDICT_PATH = '.planning/ship-verdict.md';
+
+const AFFIRMATIVE_SHIP_VERDICTS = new Set(['YES', 'SHIP', 'SHIP IT']);
+
+function normalizeToken(value) {
+  return value.trim().replace(/\s+/g, ' ').toUpperCase();
+}
+
+function readFile(root, relPath) {
+  const absPath = join(root, relPath);
+  if (!existsSync(absPath)) {
+    return null;
+  }
+  return readFileSync(absPath, 'utf8');
+}
+
+function parseLineValue(content, pattern) {
+  const match = content.match(pattern);
+  return match ? match[1].trim() : null;
+}
+
+function evaluatePmSignoff(content) {
+  const approved = parseLineValue(content, /^Approved\s*:\s*(.+)$/im);
+  if (!approved) {
+    return {
+      ok: false,
+      reason: 'PM signoff must declare `Approved: YES` in .planning/PM_SIGNOFF.md.',
+    };
+  }
+
+  if (normalizeToken(approved) !== 'YES') {
+    return {
+      ok: false,
+      reason: `PM signoff is not approved. Found "Approved: ${approved}" in .planning/PM_SIGNOFF.md; set it to "Approved: YES".`,
+    };
+  }
+
+  return { ok: true };
+}
+
+function evaluateShipVerdict(content) {
+  const verdict = parseLineValue(content, /^##\s+Verdict\s*:\s*(.+)$/im);
+  if (!verdict) {
+    return {
+      ok: false,
+      reason: 'Ship verdict must declare an affirmative `## Verdict:` line in .planning/ship-verdict.md.',
+    };
+  }
+
+  if (!AFFIRMATIVE_SHIP_VERDICTS.has(normalizeToken(verdict))) {
+    return {
+      ok: false,
+      reason: `Ship verdict is not affirmative. Found "## Verdict: ${verdict}" in .planning/ship-verdict.md; use "## Verdict: YES".`,
+    };
+  }
+
+  return { ok: true };
+}
+
+export function evaluateWorkflowGateSemantics(root, relPath) {
+  const content = readFile(root, relPath);
+  if (content === null) {
+    return null;
+  }
+
+  if (relPath === PM_SIGNOFF_PATH) {
+    return evaluatePmSignoff(content);
+  }
+
+  if (relPath === SHIP_VERDICT_PATH) {
+    return evaluateShipVerdict(content);
+  }
+
+  return null;
+}