agentxchain 2.127.0 → 2.129.0

package/README.md

@@ -15,6 +15,7 @@ Legacy IDE-window coordination is still shipped as a compatibility mode for team
 - [CLI reference](https://agentxchain.dev/docs/cli/)
 - [Lights-Out Scheduling](https://agentxchain.dev/docs/lights-out-scheduling/)
 - [Templates](https://agentxchain.dev/docs/templates/)
+- [Automation Patterns](https://agentxchain.dev/docs/automation-patterns/)
 - [Export schema reference](https://agentxchain.dev/docs/export-schema/)
 - [Adapter reference](https://agentxchain.dev/docs/adapters/)
 - [Protocol v7](https://agentxchain.dev/docs/protocol/)
@@ -107,6 +108,7 @@ Built-in governed templates:
 - `cli-tool`: command surface, platform support, distribution checklist
 - `library`: public API, compatibility policy, release and adoption checklist
 - `web-app`: user flows, UI acceptance, browser support
+- `full-local-cli`: human-gated automation pattern with PM, Dev, QA, and Director all on authoritative `local_cli`
 - `enterprise-app`: enterprise planning artifacts plus blueprint-backed `architect` and `security_reviewer` phases
 
 Inspect the shipped template surfaces instead of inferring them from docs:
@@ -172,7 +174,8 @@ agentxchain step
 | `template validate` | Prove the template registry, workflow-kit scaffold contract, and planning artifact completeness (`--json` exposes a `workflow_kit` block) |
 | `verify turn` | Replay a staged turn's declared machine-evidence commands to confirm reproducibility before acceptance |
 | `replay turn` | Replay an accepted turn's machine-evidence commands from history for audit and drift detection |
-| `verify protocol` | Run the shipped protocol conformance suite against a target implementation |
+| `conformance check` | Preferred front door for the shipped protocol conformance suite |
+| `verify protocol` | Compatibility alias for the shipped protocol conformance suite |
 | `dashboard` | Open the live local governance dashboard in your browser for the current repo/workspace or multi-repo coordinator initiative, including pending gate approvals |
 | `run [--auto-approve] [--max-turns N] [--dry-run]` | Drive a governed run from start to completion — dispatches turns, handles gates, manages rejection/retry |
 
@@ -247,9 +250,11 @@ Partial coordinator artifacts are first-class here too: `audit` and `report` kee
 AgentXchain ships a conformance kit under `.agentxchain-conformance/`. Use it to prove a runner or fork still implements the governed workflow contract:
 
 ```bash
-agentxchain verify protocol --tier 3 --target .
+agentxchain conformance check --tier 3 --target .
 ```
 
+`agentxchain verify protocol` remains available as a compatibility alias.
+
 Useful flags:
 
 - `--tier 1|2|3`: maximum conformance tier to verify

package/bin/agentxchain.js

@@ -72,6 +72,7 @@ import { injectCommand } from '../src/commands/inject.js';
 import { escalateCommand } from '../src/commands/escalate.js';
 import { acceptTurnCommand } from '../src/commands/accept-turn.js';
 import { rejectTurnCommand } from '../src/commands/reject-turn.js';
+import { reissueTurnCommand } from '../src/commands/reissue-turn.js';
 import { proposalListCommand, proposalDiffCommand, proposalApplyCommand, proposalRejectCommand } from '../src/commands/proposal.js';
 import { stepCommand } from '../src/commands/step.js';
 import { runCommand } from '../src/commands/run.js';
@@ -124,7 +125,7 @@ import { eventsCommand } from '../src/commands/events.js';
 import { connectorCheckCommand, connectorValidateCommand } from '../src/commands/connector.js';
 import { scheduleDaemonCommand, scheduleListCommand, scheduleRunDueCommand, scheduleStatusCommand } from '../src/commands/schedule.js';
 import { chainLatestCommand, chainListCommand, chainShowCommand } from '../src/commands/chain.js';
-import { missionAttachChainCommand, missionListCommand, missionPlanApproveCommand, missionPlanAutopilotCommand, missionPlanCommand, missionPlanLaunchCommand, missionPlanListCommand, missionPlanShowCommand, missionShowCommand, missionStartCommand } from '../src/commands/mission.js';
+import { missionAttachChainCommand, missionBindCoordinatorCommand, missionListCommand, missionPlanApproveCommand, missionPlanAutopilotCommand, missionPlanCommand, missionPlanLaunchCommand, missionPlanListCommand, missionPlanShowCommand, missionShowCommand, missionStartCommand } from '../src/commands/mission.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -142,7 +143,7 @@ program
   .option('-y, --yes', 'Skip guided 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, enterprise-app')
+  .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, library, web-app, full-local-cli, enterprise-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('--goal <text>', 'Project goal — persisted in config and rendered in every dispatch bundle')
@@ -445,10 +446,23 @@ missionCmd
   .option('--constraint <text>', 'Add a constraint to the planner when using --plan (repeatable)', collectOption, [])
   .option('--role-hint <role>', 'Hint available roles to the planner when using --plan (repeatable)', collectOption, [])
   .option('--planner-output-file <path>', 'Read planner JSON output from a file instead of calling the configured planner')
+  .option('--multi', 'Create a multi-repo mission with coordinator initialization')
+  .option('--coordinator-config <path>', 'Path to agentxchain-multi.json (required with --multi)')
+  .option('--coordinator-workspace <path>', 'Coordinator workspace path (defaults to project root)')
   .option('-j, --json', 'Output as JSON')
   .option('-d, --dir <path>', 'Project directory')
   .action(missionStartCommand);
 
+missionCmd
+  .command('bind-coordinator [mission_id]')
+  .description('Bind an existing coordinator super_run to a mission')
+  .requiredOption('--super-run-id <id>', 'Coordinator super_run_id to bind')
+  .option('--coordinator-config <path>', 'Path to agentxchain-multi.json')
+  .option('--coordinator-workspace <path>', 'Coordinator workspace path')
+  .option('-j, --json', 'Output as JSON')
+  .option('-d, --dir <path>', 'Project directory')
+  .action(missionBindCoordinatorCommand);
+
 missionCmd
   .command('list')
   .description('List mission artifacts newest first')
@@ -542,6 +556,22 @@ program
   .option('-j, --json', 'Output as JSON')
   .action(validateCommand);
 
+const conformanceCmd = program
+  .command('conformance')
+  .description('Run protocol conformance checks against local or remote implementations');
+
+conformanceCmd
+  .command('check')
+  .description('Run the shipped protocol conformance fixture suite against a target implementation')
+  .option('--tier <tier>', 'Conformance tier to verify (1, 2, or 3)', '1')
+  .option('--surface <surface>', 'Restrict verification to a single surface')
+  .option('--target <path>', 'Target root containing .agentxchain-conformance/capabilities.json', '.')
+  .option('--remote <url>', 'Remote HTTP conformance endpoint base URL')
+  .option('--token <token>', 'Bearer token for remote HTTP conformance endpoint')
+  .option('--timeout <ms>', 'Per-fixture remote HTTP timeout in milliseconds', '30000')
+  .option('--format <format>', 'Output format: text or json', 'text')
+  .action(verifyProtocolCommand);
+
 const verifyCmd = program
   .command('verify')
   .description('Verify governed turns, export artifacts, and protocol conformance targets');
@@ -609,6 +639,7 @@ program
   .description('Resume a governed project: initialize or continue a run and assign the next turn')
   .option('--role <role>', 'Override the target role (default: phase entry role)')
   .option('--turn <id>', 'Target a specific retained turn when multiple exist')
+  .option('--no-intent', 'Do not bind the next queued approved/planned intake intent to the next turn')
   .action(resumeCommand);
 
 program
@@ -620,7 +651,7 @@ program
   .command('inject <description>')
   .description('Inject a priority work item into the intake queue (composed record + triage + approve)')
   .option('--priority <level>', 'Priority level (p0, p1, p2, p3)', 'p0')
-  .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-app, enterprise-app)', 'generic')
+  .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-app, full-local-cli, enterprise-app)', 'generic')
   .option('--charter <text>', 'Delivery charter (defaults to description)')
   .option('--acceptance <text>', 'Comma-separated acceptance criteria')
   .option('--approver <name>', 'Approver identity', 'human')
@@ -652,14 +683,23 @@ program
   .option('--reassign', 'Immediately re-dispatch a conflicted turn with conflict context')
   .action(rejectTurnCommand);
 
+program
+  .command('reissue-turn')
+  .description('Invalidate an active turn and reissue it against current repo state (baseline drift recovery)')
+  .option('--turn <id>', 'Target a specific active turn when multiple turns exist')
+  .option('--reason <reason>', 'Reason for the reissue (e.g., baseline drift, runtime rebinding)')
+  .action(reissueTurnCommand);
+
 program
   .command('step')
   .description('Run a single governed turn: assign, dispatch, wait, validate, accept/reject')
   .option('--role <role>', 'Override the target role (default: phase entry role)')
   .option('--resume', 'Resume waiting for an already-active turn')
   .option('--turn <id>', 'Target a specific active turn (required with --resume when multiple turns exist)')
+  .option('--no-intent', 'Do not bind the next queued approved/planned intake intent to the next turn')
   .option('--poll <seconds>', 'Polling interval for manual adapter in seconds', '2')
   .option('--verbose', 'Stream local_cli subprocess output while the turn is running')
+  .option('--stream', 'Stream live subprocess output to terminal (alias for --verbose)')
   .option('--auto-reject', 'Auto-reject and retry on validation failure')
   .action(stepCommand);
 
@@ -895,7 +935,7 @@ intakeCmd
   .description('Triage a detected intent — set priority, template, charter, and acceptance')
   .option('--intent <id>', 'Intent ID to triage')
   .option('--priority <level>', 'Priority level (p0, p1, p2, p3)')
-  .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-app, enterprise-app)')
+  .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-app, full-local-cli, enterprise-app)')
   .option('--charter <text>', 'Delivery charter text')
   .option('--acceptance <text>', 'Comma-separated acceptance criteria')
   .option('--suppress', 'Suppress the intent instead of triaging')

package/package.json

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

package/scripts/verify-post-publish.sh

@@ -19,6 +19,18 @@ cd "$CLI_DIR"
 
 TARGET_VERSION=""
 
+FORMULA_PATH="${CLI_DIR}/homebrew/agentxchain.rb"
+
+formula_url() {
+  local formula_path="$1"
+  grep -E '^\s*url\s+"' "$formula_path" | sed 's/.*url *"\([^"]*\)".*/\1/' || true
+}
+
+formula_sha() {
+  local formula_path="$1"
+  grep -E '^\s*sha256\s+"' "$formula_path" | sed 's/.*sha256 *"\([a-f0-9]*\)".*/\1/' || true
+}
+
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --target-version)
@@ -59,18 +71,56 @@ echo "[2/4] Syncing repo mirror to published tarball..."
 bash "${SCRIPT_DIR}/sync-homebrew.sh" --target-version "$TARGET_VERSION"
 echo "  OK: repo mirror synced"
 
-# Step 3: Run the full test suite WITHOUT the preflight skip
-echo "[3/4] Running full test suite (no preflight skip)..."
-echo "  This verifies the Homebrew mirror contract passes with the real SHA."
+# Step 3: Explicitly prove the repo mirror now matches registry truth
+echo "[3/5] Verifying repo mirror against registry tarball..."
+TARBALL_URL="$(npm view "agentxchain@${TARGET_VERSION}" dist.tarball 2>/dev/null || echo "")"
+if [[ -z "$TARBALL_URL" ]]; then
+  echo "  FAIL: npm did not return dist.tarball for agentxchain@${TARGET_VERSION}"
+  exit 1
+fi
+
+TARBALL_SHA="$(curl -sL "$TARBALL_URL" | shasum -a 256 | awk '{print $1}')"
+if [[ -z "$TARBALL_SHA" ]] || [[ ${#TARBALL_SHA} -ne 64 ]]; then
+  echo "  FAIL: could not compute valid SHA256 from registry tarball"
+  exit 1
+fi
+
+if [[ ! -f "$FORMULA_PATH" ]]; then
+  echo "  FAIL: Homebrew formula not found at ${FORMULA_PATH}"
+  exit 1
+fi
+
+FORMULA_URL="$(formula_url "$FORMULA_PATH")"
+FORMULA_SHA="$(formula_sha "$FORMULA_PATH")"
+
+if [[ "$FORMULA_URL" != "$TARBALL_URL" ]]; then
+  echo "  FAIL: repo mirror formula URL does not match registry tarball"
+  echo "    formula:  ${FORMULA_URL:-<missing>}"
+  echo "    registry: ${TARBALL_URL}"
+  exit 1
+fi
+echo "  OK: repo mirror formula URL matches registry tarball"
+
+if [[ "$FORMULA_SHA" != "$TARBALL_SHA" ]]; then
+  echo "  FAIL: repo mirror formula SHA256 does not match registry tarball"
+  echo "    formula:  ${FORMULA_SHA:-<missing>}"
+  echo "    registry: ${TARBALL_SHA}"
+  exit 1
+fi
+echo "  OK: repo mirror formula SHA256 matches registry tarball"
+
+# Step 4: Run the full test suite WITHOUT the preflight skip
+echo "[4/5] Running full test suite (no preflight skip)..."
+echo "  This verifies the broader Homebrew mirror contract passes with the real SHA."
 npm test
 echo "  OK: full test suite green"
 
-# Step 4: Summary
+# Step 5: Summary
 echo ""
 echo "============================================="
 echo "Post-publish verification PASSED."
 echo "  - npm: agentxchain@${TARGET_VERSION} live"
-echo "  - repo mirror: SHA synced to published tarball"
+echo "  - repo mirror: formula URL and SHA match the published tarball"
 echo "  - test suite: green without preflight skip"
 echo ""
 echo "Main is now in Phase 3 (post-sync). Commit and push the mirror update."

package/src/commands/connector.js

@@ -27,7 +27,11 @@ function printText(result, exitCode) {
   console.log('');
 
   for (const connector of result.connectors) {
-    const badge = connector.level === 'pass' ? chalk.green('PASS') : chalk.red('FAIL');
+    const badge = connector.level === 'pass'
+      ? chalk.green('PASS')
+      : connector.level === 'warn'
+        ? chalk.yellow('WARN')
+        : chalk.red('FAIL');
     console.log(`  ${badge}  ${connector.runtime_id} (${connector.type})`);
     console.log(`        ${chalk.dim('Target:')} ${connector.target}`);
     console.log(`        ${chalk.dim('Probe:')}  ${connector.probe_kind}`);
@@ -44,12 +48,22 @@ function printText(result, exitCode) {
       console.log(`        ${chalk.dim('Time:')}   ${connector.latency_ms}ms`);
     }
     console.log(`        ${chalk.dim('Detail:')} ${connector.detail}`);
+    if (Array.isArray(connector.authority_warnings) && connector.authority_warnings.length > 0) {
+      for (const warning of connector.authority_warnings) {
+        console.log(`        ${chalk.yellow('⚠')} ${warning.detail}`);
+        if (warning.fix) {
+          console.log(`          ${chalk.dim('Fix:')} ${warning.fix}`);
+        }
+      }
+    }
   }
 
   console.log('');
   const summary = result.overall === 'pass'
     ? chalk.green(`  ✓ ${result.pass_count}/${result.connectors.length} connectors passed`)
-    : chalk.red(`  ${result.fail_count} connector failure(s), ${result.pass_count} passed`);
+    : result.overall === 'warn'
+      ? chalk.yellow(`  ⚠ ${result.warn_count} connector warning(s), ${result.pass_count} passed`)
+      : chalk.red(`  ${result.fail_count} connector failure(s), ${result.pass_count} passed`);
   console.log(summary);
   console.log('');
   process.exit(exitCode);
@@ -110,6 +124,7 @@ export async function connectorCheckCommand(runtimeId, options = {}) {
     overall: result.overall,
     timeout_ms: result.timeout_ms,
     pass_count: result.pass_count,
+    warn_count: result.warn_count,
     fail_count: result.fail_count,
     connectors: result.connectors,
   };

package/src/commands/doctor.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'fs';
 import { execFileSync, execSync } from 'child_process';
 import { join } from 'path';
 import chalk from 'chalk';
-import { loadConfig, loadLock, findProjectRoot } from '../lib/config.js';
+import { loadConfig, loadLock, findProjectRoot, loadProjectState } from '../lib/config.js';
 import { validateProject } from '../lib/validation.js';
 import { runAdmissionControl } from '../lib/admission-control.js';
 import { getWatchPid } from './watch.js';
@@ -10,12 +10,16 @@ import { getDashboardPid, getDashboardSession } from './dashboard.js';
 import { loadNormalizedConfig, detectConfigVersion } from '../lib/normalized-config.js';
 import { readDaemonState, evaluateDaemonStatus } from '../lib/run-schedule.js';
 import { getGovernedVersionSurface, formatGovernedVersionLabel } from '../lib/protocol-version.js';
+import { getCliVersionHealth } from '../lib/cli-version.js';
 import { PLUGIN_MANIFEST_FILE } from '../lib/plugins.js';
 import {
   getRoleRuntimeCapabilityContract,
   summarizeRoleRuntimeCapability,
   summarizeRuntimeCapabilityContract,
 } from '../lib/runtime-capabilities.js';
+import { detectActiveTurnBindingDrift } from '../lib/governed-state.js';
+import { findPendingApprovedIntents } from '../lib/intake.js';
+import { checkCleanBaseline } from '../lib/repo-observer.js';
 
 export async function doctorCommand(opts = {}) {
   const root = findProjectRoot(process.cwd());
@@ -55,6 +59,9 @@ export async function doctorCommand(opts = {}) {
 
 function governedDoctor(root, rawConfig, opts) {
   const checks = [];
+  const cliVersionHealth = getCliVersionHealth();
+
+  checks.push(buildCliVersionCheck(cliVersionHealth));
 
   // 1. Config validation
   const configResult = loadNormalizedConfig(rawConfig, root);
@@ -113,6 +120,63 @@ function governedDoctor(root, rawConfig, opts) {
     checks.push({ id: 'state_health', name: 'State health', level: 'warn', detail: 'No state file yet (first run pending)' });
   }
 
+  // 5b. Active turn binding drift (B-7: detect runtime rebinding mid-run)
+  if (normalized && existsSync(join(root, '.agentxchain', 'state.json'))) {
+    try {
+      const stateData = loadProjectState(root, normalized);
+      const drifts = detectActiveTurnBindingDrift(stateData, normalized);
+      if (drifts.length > 0) {
+        const driftSummary = drifts.map(d => {
+          const parts = [];
+          if (d.runtime_changed) parts.push(`runtime ${d.old_runtime} → ${d.new_runtime}`);
+          if (d.authority_changed) parts.push(`authority ${d.old_authority} → ${d.new_authority}`);
+          return `${d.turn_id} (${d.role_id}): ${parts.join(', ')}`;
+        }).join('; ');
+        checks.push({
+          id: 'binding_drift',
+          name: 'Active turn binding',
+          level: 'warn',
+          detail: `Stale binding: ${driftSummary}. Run: agentxchain reissue-turn`,
+          drifts,
+        });
+      } else if (Object.keys(stateData?.active_turns || {}).length > 0) {
+        checks.push({
+          id: 'binding_drift',
+          name: 'Active turn binding',
+          level: 'pass',
+          detail: 'Active turns match current config bindings',
+        });
+      }
+    } catch {
+      // State couldn't be loaded — skip drift check
+    }
+  }
+
+  // 5c. Clean working tree pre-flight for authoritative/proposed roles
+  if (normalized?.roles) {
+    const writableRoles = Object.entries(normalized.roles)
+      .filter(([, role]) => role.write_authority === 'authoritative' || role.write_authority === 'proposed')
+      .map(([id]) => id);
+    if (writableRoles.length > 0) {
+      const cleanCheck = checkCleanBaseline(root, 'authoritative');
+      if (cleanCheck.clean) {
+        checks.push({
+          id: 'clean_baseline',
+          name: 'Clean working tree',
+          level: 'pass',
+          detail: 'Working tree is clean for authoritative/proposed turns',
+        });
+      } else {
+        checks.push({
+          id: 'clean_baseline',
+          name: 'Clean working tree',
+          level: 'warn',
+          detail: `${cleanCheck.reason} Writable roles: ${writableRoles.join(', ')}`,
+        });
+      }
+    }
+  }
+
   // 6. Schedule health (only when schedules configured)
   const schedules = normalized?.schedules;
   const hasSchedules = schedules && typeof schedules === 'object' && Object.keys(schedules).length > 0;
@@ -258,6 +322,20 @@ function governedDoctor(root, rawConfig, opts) {
     }
   }
 
+  // 11. Pending intake intents (BUG-15 — informational)
+  {
+    const pendingIntents = findPendingApprovedIntents(root);
+    if (pendingIntents.length > 0) {
+      const summary = pendingIntents.map(pi => `[${pi.priority}] ${pi.intent_id}`).join(', ');
+      checks.push({
+        id: 'pending_intents',
+        name: 'Pending intents',
+        level: 'info',
+        detail: `${pendingIntents.length} approved intent(s) in queue, next turn will consume them: ${summary}`,
+      });
+    }
+  }
+
   // Compute summary
   const failCount = checks.filter(c => c.level === 'fail').length;
   const warnCount = checks.filter(c => c.level === 'warn').length;
@@ -270,6 +348,10 @@ function governedDoctor(root, rawConfig, opts) {
       project: projectId,
       ...versionSurface,
       config_version: versionSurface.config_generation,
+      cli_version: cliVersionHealth.current_version,
+      docs_min_cli_version: cliVersionHealth.docs_min_cli_version,
+      cli_version_status: cliVersionHealth.status,
+      cli_version_source: cliVersionHealth.source,
       overall,
       connector_probe_recommended: connectorProbe.recommended,
       connector_probe_runtime_ids: connectorProbe.runtimeIds,
@@ -312,6 +394,11 @@ function governedDoctor(root, rawConfig, opts) {
     } else {
       console.log(chalk.red(`  Not ready: ${failCount} failure${failCount > 1 ? 's' : ''}, ${warnCount} warning${warnCount > 1 ? 's' : ''}.`));
     }
+    if (cliVersionHealth.stale) {
+      console.log(chalk.yellow('  Fix: npm install -g agentxchain@latest'));
+      console.log(chalk.yellow('       brew upgrade agentxchain'));
+      console.log(chalk.yellow('       npx --yes -p agentxchain@latest -c "agentxchain doctor"'));
+    }
     if (failCount === 0 && connectorProbe.recommended) {
       console.log(chalk.dim(`  Next: ${connectorProbe.detail}`));
     }
@@ -341,6 +428,33 @@ function attachRuntimeContract(baseCheck, rtId, rt, boundRoleEntries) {
   };
 }
 
+function buildCliVersionCheck(cliVersionHealth) {
+  if (cliVersionHealth.status === 'stale') {
+    return {
+      id: 'cli_version',
+      name: 'CLI version',
+      level: 'warn',
+      detail: `${cliVersionHealth.detail} Fix with npm install -g agentxchain@latest, brew upgrade agentxchain, or npx --yes -p agentxchain@latest -c "agentxchain doctor".`,
+    };
+  }
+
+  if (cliVersionHealth.status === 'ok') {
+    return {
+      id: 'cli_version',
+      name: 'CLI version',
+      level: 'pass',
+      detail: cliVersionHealth.detail,
+    };
+  }
+
+  return {
+    id: 'cli_version',
+    name: 'CLI version',
+    level: 'info',
+    detail: cliVersionHealth.detail,
+  };
+}
+
 function checkRuntimeReachable(rtId, rt, boundRoleEntries = []) {
   const base = { id: `runtime_${rtId}`, name: `Runtime: ${rtId}` };
 
@@ -449,8 +563,10 @@ function legacyDoctor(root, opts) {
 
   const { config } = result;
   const lock = loadLock(root);
+  const cliVersionHealth = getCliVersionHealth();
   const checks = [];
 
+  checks.push(buildCliVersionCheck(cliVersionHealth));
   checks.push(checkFile('agentxchain.json', existsSync(join(root, 'agentxchain.json')), 'Project config exists'));
   checks.push(checkFile('lock.json', !!lock, 'Lock file exists'));
   checks.push(checkBinary('cursor', 'Cursor CLI available (optional for non-macOS launch)'));
@@ -489,6 +605,11 @@ function legacyDoctor(root, opts) {
   } else {
     console.log(chalk.red(`  Not ready: ${failCount} blocking issue(s).`));
   }
+  if (cliVersionHealth.stale) {
+    console.log(chalk.yellow('  Fix: npm install -g agentxchain@latest'));
+    console.log(chalk.yellow('       brew upgrade agentxchain'));
+    console.log(chalk.yellow('       npx --yes -p agentxchain@latest -c "agentxchain doctor"'));
+  }
   console.log('');
 }
 

package/src/commands/events.js

@@ -61,12 +61,16 @@ function printEvent(evt) {
   const runId = evt.run_id ? evt.run_id.slice(0, 12) : '—';
   const phase = evt.phase || '—';
   const turnInfo = evt.turn?.role_id ? ` [${evt.turn.role_id}]` : '';
+  const intentInfo = evt.intent_id ? ` intent=${evt.intent_id}` : '';
   const conflictDetail = evt.event_type === 'turn_conflicted'
     ? ` — ${formatConflictDetail(evt)}`
     : '';
   const rejectionDetail = evt.event_type === 'turn_rejected' && evt.payload?.reason
     ? ` — ${evt.payload.reason}${evt.payload.failed_stage ? ` (${evt.payload.failed_stage})` : ''}`
     : '';
+  const acceptanceFailedDetail = evt.event_type === 'acceptance_failed' && evt.payload?.reason
+    ? ` — ${evt.payload.reason}${evt.payload.stage ? ` (${evt.payload.stage})` : ''}`
+    : '';
   const phaseTransitionDetail = evt.event_type === 'phase_entered' && evt.payload?.from && evt.payload?.to
     ? ` ${evt.payload.from} → ${evt.payload.to}${evt.payload.trigger ? ` (${evt.payload.trigger})` : ''}`
     : '';
@@ -78,7 +82,7 @@ function printEvent(evt) {
     : evt.event_type === 'human_escalation_resolved' && evt.payload?.escalation_id
       ? ` ${evt.payload.escalation_id} via ${evt.payload.resolved_via || '?'}`
       : '';
-  console.log(`${chalk.dim(ts)}  ${type}  ${chalk.cyan(runId)}  ${phase}${turnInfo}${conflictDetail}${rejectionDetail}${phaseTransitionDetail}${gateFailedDetail}${humanEscalationDetail}`);
+  console.log(`${chalk.dim(ts)}  ${type}  ${chalk.cyan(runId)}  ${phase}${turnInfo}${intentInfo}${conflictDetail}${rejectionDetail}${acceptanceFailedDetail}${phaseTransitionDetail}${gateFailedDetail}${humanEscalationDetail}`);
 }
 
 function formatConflictDetail(evt) {
@@ -116,6 +120,8 @@ function colorEventType(type) {
     turn_dispatched: chalk.blue,
     turn_accepted: chalk.green,
     turn_rejected: chalk.yellow,
+    acceptance_failed: chalk.red.bold,
+    turn_reissued: chalk.cyan,
     turn_conflicted: chalk.redBright,
     phase_entered: chalk.magenta,
     escalation_raised: chalk.red.bold,

package/src/commands/init.js

@@ -257,9 +257,11 @@ You are QA. Your mandate: **${role.mandate}**
    - \`.planning/ship-verdict.md\` — your overall ship/no-ship recommendation
    - \`.planning/RELEASE_NOTES.md\` — user-facing release notes with impact and verification summary
 
-## You Cannot Modify Code
+## File Access
 
-You have \`review_only\` write authority. You may NOT modify product files. You may only create/modify files under \`.planning/\` and \`.agentxchain/reviews/\`. Your artifact type must be \`review\`.
+${role.write_authority === 'review_only'
+    ? 'You have `review_only` write authority. You may NOT modify product files. You may only create/modify files under `.planning/` and `.agentxchain/reviews/`. Your artifact type must be `review`.'
+    : 'You have direct write access for this role. Use it to create or update QA-owned evidence and verification artifacts directly in the repo. Do not make unrelated product changes. Your artifact type should normally be `workspace` when you modify repo files directly.'}
 
 ## Runtime Truth
 
@@ -337,9 +339,11 @@ You are invoked when the normal PM → Dev → QA loop is stuck:
 - You may NOT override human decisions — escalate to \`human\` if needed
 - Every override must be recorded as a decision with clear rationale
 
-## You Cannot Modify Code
+## File Access
 
-You have \`review_only\` write authority. Like QA, you must raise at least one objection (protocol requirement). Your artifact type is \`review\`.
+${role.write_authority === 'review_only'
+    ? 'You have `review_only` write authority. Like QA, you must raise at least one objection (protocol requirement). Your artifact type is `review`.'
+    : 'You have direct write access for this role. Use it sparingly to resolve tactical deadlocks or correct governance artifacts when necessary. Do not use Director authority as a shortcut around the normal PM -> Dev -> QA loop.'}
 
 ## Objection Requirement
 
@@ -441,10 +445,20 @@ function commandHasPromptPlaceholder(parts = []) {
   return parts.some((part) => typeof part === 'string' && part.includes('{prompt}'));
 }
 
+function normalizeGovernedDevCommand(parts = []) {
+  if (!Array.isArray(parts) || parts.length === 0) {
+    return null;
+  }
+  const [head, ...rest] = parts;
+  const normalizedHead = String(head || '').trim().split(/\s+/).filter(Boolean);
+  const normalizedRest = rest
+    .map((part) => String(part).trim())
+    .filter(Boolean);
+  return [...normalizedHead, ...normalizedRest];
+}
+
 function resolveGovernedLocalDevRuntime(opts = {}) {
-  const customCommand = Array.isArray(opts.devCommand)
-    ? opts.devCommand.map((part) => String(part).trim()).filter(Boolean)
-    : null;
+  const customCommand = normalizeGovernedDevCommand(opts.devCommand);
   const explicitTransport = typeof opts.devPromptTransport === 'string' && opts.devPromptTransport.trim()
     ? opts.devPromptTransport.trim()
     : null;
@@ -503,6 +517,16 @@ function formatRuntimeSummary(runtimeId, runtime) {
   return `${command} (${runtime.prompt_transport || runtime.type})`;
 }
 
+function runtimeMatchesDefaultGovernedLocalCli(runtime) {
+  if (!runtime || runtime.type !== 'local_cli') return false;
+  const command = Array.isArray(runtime.command) ? runtime.command : [];
+  return (
+    runtime.cwd === DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME.cwd
+    && runtime.prompt_transport === DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME.prompt_transport
+    && JSON.stringify(command) === JSON.stringify(DEFAULT_GOVERNED_LOCAL_DEV_RUNTIME.command)
+  );
+}
+
 function hasTemplateDefinedRouting(template) {
   return Boolean(template?.scaffold_blueprint?.routing && Object.keys(template.scaffold_blueprint.routing).length > 0);
 }
@@ -610,9 +634,15 @@ function buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitC
     (Array.isArray(runtimeOptions.devCommand) && runtimeOptions.devCommand.length > 0)
     || (typeof runtimeOptions.devPromptTransport === 'string' && runtimeOptions.devPromptTransport.trim())
   );
-
-  if (!blueprint || Object.values(roles).some((role) => role?.runtime === 'local-dev') || explicitLocalDevRequested) {
-    runtimes['local-dev'] = localDevRuntime;
+  const defaultLocalRuntimeIds = Object.entries(runtimes)
+    .filter(([, runtime]) => runtimeMatchesDefaultGovernedLocalCli(runtime))
+    .map(([runtimeId]) => runtimeId);
+
+  if (!blueprint || defaultLocalRuntimeIds.length > 0 || explicitLocalDevRequested) {
+    const runtimeIdsToReplace = defaultLocalRuntimeIds.length > 0 ? defaultLocalRuntimeIds : ['local-dev'];
+    for (const runtimeId of runtimeIdsToReplace) {
+      runtimes[runtimeId] = cloneJsonCompatible(localDevRuntime);
+    }
   }
 
   if (explicitLocalDevRequested && roles?.dev?.runtime === 'manual-dev') {
@@ -803,14 +833,23 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
   // TALK.md
   writeFileSync(join(dir, 'TALK.md'), `# ${projectName} — Team Talk File\n\nCanonical human-readable handoff log for all agents.\n\n---\n\n`);
 
-  // .gitignore additions
+  // .gitignore additions with inline comments so operators know what to commit vs. ignore
   const gitignorePath = join(dir, '.gitignore');
-  const requiredIgnores = ['.env', '.agentxchain/staging/', '.agentxchain/dispatch/'];
+  const gitignoreContent = [
+    '# AgentXchain — secrets',
+    '.env',
+    '',
+    '# AgentXchain — transient execution artifacts (never commit)',
+    '.agentxchain/staging/',
+    '.agentxchain/dispatch/',
+    '.agentxchain/transactions/',
+  ].join('\n') + '\n';
+  const requiredPaths = ['.env', '.agentxchain/staging/', '.agentxchain/dispatch/', '.agentxchain/transactions/'];
   if (!existsSync(gitignorePath)) {
-    writeFileSync(gitignorePath, requiredIgnores.join('\n') + '\n');
+    writeFileSync(gitignorePath, gitignoreContent);
   } else {
     const existingIgnore = readFileSync(gitignorePath, 'utf8');
-    const missing = requiredIgnores.filter(entry => !existingIgnore.split(/\r?\n/).includes(entry));
+    const missing = requiredPaths.filter(entry => !existingIgnore.split(/\r?\n/).includes(entry));
     if (missing.length > 0) {
       const prefix = existingIgnore.endsWith('\n') ? '' : '\n';
       writeFileSync(gitignorePath, existingIgnore + prefix + missing.join('\n') + '\n');
@@ -854,6 +893,8 @@ async function initGoverned(opts) {
     console.error('    cli-tool      Governed scaffold for a CLI tool');
     console.error('    library       Governed scaffold for a reusable package');
     console.error('    web-app       Governed scaffold for a web application');
+    console.error('    full-local-cli Human-gated automation pattern with all roles on local_cli');
+    console.error('    enterprise-app Governed scaffold for multi-role enterprise delivery');
     process.exit(1);
   }
   selectedTemplate = loadGovernedTemplate(templateId);