agentxchain 2.3.0 → 2.5.0

package/README.md

@@ -67,6 +67,7 @@ Built-in governed templates:
 - `generic`: baseline governed scaffold
 - `api-service`: API contract, operational readiness, error budget
 - `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
 
 `step` writes a turn-scoped bundle under `.agentxchain/dispatch/turns/<turn_id>/` and expects a staged result at `.agentxchain/staging/<turn_id>/turn-result.json`. Typical continuation:

package/bin/agentxchain.js

@@ -79,6 +79,7 @@ import {
 } from '../src/commands/plugin.js';
 import { templateSetCommand } from '../src/commands/template-set.js';
 import { templateListCommand } from '../src/commands/template-list.js';
+import { templateValidateCommand } from '../src/commands/template-validate.js';
 import {
   multiInitCommand,
   multiStatusCommand,
@@ -110,7 +111,7 @@ 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('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, web-app')
+  .option('--template <id>', 'Governed scaffold template: generic, api-service, cli-tool, library, web-app')
   .option('--schema-version <version>', 'Schema version (3 for legacy, or use --governed for current)')
   .action(initCommand);
 
@@ -336,6 +337,12 @@ templateCmd
   .option('-j, --json', 'Output as JSON')
   .action(templateListCommand);
 
+templateCmd
+  .command('validate')
+  .description('Validate the built-in governed template registry and current project template binding')
+  .option('-j, --json', 'Output as JSON')
+  .action(templateValidateCommand);
+
 const multiCmd = program
   .command('multi')
   .description('Multi-repo coordinator orchestration');
@@ -394,7 +401,7 @@ intakeCmd
   .description('Triage a detected intent — set priority, template, charter, and acceptance')
   .requiredOption('--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, web-app)')
+  .option('--template <id>', 'Governed template (generic, api-service, cli-tool, library, web-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.3.0",
+  "version": "2.5.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {
@@ -48,10 +48,12 @@
   "homepage": "https://agentxchain.dev",
   "dependencies": {
     "@anthropic-ai/tokenizer": "0.0.4",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "chalk": "^5.4.0",
     "commander": "^13.0.0",
     "inquirer": "^12.0.0",
-    "ora": "^8.0.0"
+    "ora": "^8.0.0",
+    "zod": "^4.3.6"
   },
   "engines": {
     "node": ">=18.17.0 || >=20.5.0"

package/src/commands/init.js

@@ -483,6 +483,7 @@ async function initGoverned(opts) {
     console.error('    generic       Default governed scaffold');
     console.error('    api-service   Governed scaffold for a backend service');
     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');
     process.exit(1);
   }

package/src/commands/step.js

@@ -17,6 +17,7 @@
  *   - local_cli: implemented via subprocess dispatch + staged turn result
  *   - api_proxy: implemented for synchronous review-only turns and stages
  *     provider-backed JSON before validation/acceptance
+ *   - mcp: implemented for synchronous MCP stdio or streamable_http tool dispatch
  */
 
 import chalk from 'chalk';
@@ -45,6 +46,7 @@ import {
   saveDispatchLogs,
   resolvePromptTransport,
 } from '../lib/adapters/local-cli-adapter.js';
+import { describeMcpRuntimeTarget, dispatchMcp, resolveMcpTransport } from '../lib/adapters/mcp-adapter.js';
 import {
   getDispatchAssignmentPath,
   getDispatchContextPath,
@@ -423,12 +425,65 @@ export async function stepCommand(opts) {
       console.log(chalk.dim(`  Tokens: ${apiResult.usage.input_tokens || 0} in / ${apiResult.usage.output_tokens || 0} out`));
     }
     console.log('');
+  } else if (runtimeType === 'mcp') {
+    const mcpTransport = resolveMcpTransport(runtime);
+    console.log(chalk.cyan(`Dispatching to MCP ${mcpTransport}: ${describeMcpRuntimeTarget(runtime)}`));
+    console.log(chalk.dim(`Turn: ${turn.turn_id}  Role: ${roleId}  Phase: ${state.phase}  Tool: ${runtime?.tool_name || 'agentxchain_turn'}`));
+
+    const mcpResult = await dispatchMcp(root, state, config, {
+      signal: controller.signal,
+      onStatus: (msg) => console.log(chalk.dim(`  ${msg}`)),
+      onStderr: opts.verbose ? (text) => process.stderr.write(chalk.yellow(text)) : undefined,
+      verifyManifest: true,
+    });
+
+    if (mcpResult.logs?.length) {
+      saveDispatchLogs(root, turn.turn_id, mcpResult.logs);
+    }
+
+    if (mcpResult.aborted) {
+      console.log('');
+      console.log(chalk.yellow('Aborted. Turn remains assigned.'));
+      console.log(chalk.dim('Resume later with: agentxchain step --resume'));
+      console.log(chalk.dim('Or accept/reject manually: agentxchain accept-turn / reject-turn'));
+      process.exit(0);
+    }
+
+    if (!mcpResult.ok) {
+      const blocked = markRunBlocked(root, {
+        blockedOn: 'dispatch:mcp_failure',
+        category: 'dispatch_error',
+        recovery: {
+          typed_reason: 'dispatch_error',
+          owner: 'human',
+          recovery_action: 'Resolve the MCP dispatch issue, then run agentxchain step --resume',
+          turn_retained: true,
+          detail: mcpResult.error,
+        },
+        turnId: turn.turn_id,
+        hooksConfig,
+      });
+      if (blocked.ok) {
+        state = blocked.state;
+      }
+
+      console.log('');
+      console.log(chalk.red(`MCP dispatch failed: ${mcpResult.error}`));
+      console.log(chalk.dim('The turn remains assigned. You can:'));
+      console.log(chalk.dim('  - Fix the MCP server/runtime and retry: agentxchain step --resume'));
+      console.log(chalk.dim('  - Complete manually: edit .agentxchain/staging/turn-result.json'));
+      console.log(chalk.dim('  - Reject: agentxchain reject-turn --reason "mcp dispatch failed"'));
+      process.exit(1);
+    }
+
+    console.log(chalk.green(`MCP tool completed${mcpResult.toolName ? ` (${mcpResult.toolName})` : ''}. Staged result detected.`));
+    console.log('');
   }
 
   // ── Phase 3: Wait for turn completion ─────────────────────────────────────
 
-  if (runtimeType === 'api_proxy') {
-    // api_proxy is synchronous — result already staged in Phase 2
+  if (runtimeType === 'api_proxy' || runtimeType === 'mcp') {
+    // api_proxy and mcp are synchronous — result already staged in Phase 2
   } else if (runtimeType === 'local_cli') {
     // ── Local CLI adapter: spawn subprocess ──
     const transport = runtime ? resolvePromptTransport(runtime) : 'dispatch_bundle_only';

package/src/commands/template-validate.js

@@ -0,0 +1,159 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { CONFIG_FILE, findProjectRoot } from '../lib/config.js';
+import {
+  validateGovernedProjectTemplate,
+  validateGovernedTemplateRegistry,
+  validateProjectPlanningArtifacts,
+  validateAcceptanceHintCompletion,
+} from '../lib/governed-templates.js';
+
+function loadProjectTemplateValidation() {
+  const root = findProjectRoot();
+  if (!root) {
+    return {
+      present: false,
+      root: null,
+      template: null,
+      source: null,
+      ok: true,
+      errors: [],
+      warnings: [],
+    };
+  }
+
+  const configPath = join(root, CONFIG_FILE);
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    return {
+      present: true,
+      root,
+      template: null,
+      source: 'agentxchain.json',
+      ok: false,
+      errors: [`Failed to parse ${CONFIG_FILE}: ${err.message}`],
+      warnings: [],
+    };
+  }
+
+  const projectValidation = validateGovernedProjectTemplate(parsed.template);
+  return {
+    present: true,
+    root,
+    ...projectValidation,
+  };
+}
+
+export function templateValidateCommand(opts = {}) {
+  const registry = validateGovernedTemplateRegistry();
+  const project = loadProjectTemplateValidation();
+
+  // Planning artifact completeness check
+  let planningArtifacts = null;
+  if (project.present && project.ok && project.root) {
+    planningArtifacts = validateProjectPlanningArtifacts(project.root, project.template);
+  }
+
+  // Acceptance hint completion check
+  let acceptanceHints = null;
+  if (project.present && project.ok && project.root) {
+    acceptanceHints = validateAcceptanceHintCompletion(project.root, project.template);
+  }
+
+  const errors = [
+    ...registry.errors,
+    ...project.errors,
+    ...(planningArtifacts?.errors || []),
+  ];
+  const warnings = [
+    ...registry.warnings,
+    ...project.warnings,
+    ...(planningArtifacts?.warnings || []),
+    ...(acceptanceHints?.warnings || []),
+  ];
+  const ok = errors.length === 0;
+
+  const payload = {
+    ok,
+    registry,
+    project,
+    planning_artifacts: planningArtifacts,
+    acceptance_hints: acceptanceHints,
+    errors,
+    warnings,
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    if (!ok) process.exit(1);
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Template Validate'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log('');
+
+  if (ok) {
+    console.log(chalk.green('  ✓ Template validation passed.'));
+  } else {
+    console.log(chalk.red(`  ✗ Template validation failed (${errors.length} errors).`));
+  }
+
+  console.log('');
+  console.log(`  ${chalk.dim('Registry:')} ${registry.ok ? chalk.green('OK') : chalk.red('FAIL')} (${registry.registered_ids.length} registered, ${registry.manifest_ids.length} manifests)`);
+
+  if (project.present) {
+    const sourceLabel = project.source === 'implicit_default'
+      ? 'implicit default'
+      : project.source;
+    console.log(`  ${chalk.dim('Project:')}  ${project.ok ? chalk.green('OK') : chalk.red('FAIL')} (${project.template} via ${sourceLabel})`);
+    if (project.root && existsSync(project.root)) {
+      console.log(`  ${chalk.dim('Root:')}     ${project.root}`);
+    }
+    if (planningArtifacts) {
+      const total = planningArtifacts.expected.length;
+      const found = planningArtifacts.present.length;
+      if (total === 0) {
+        console.log(`  ${chalk.dim('Planning:')}   ${chalk.green('OK')} (no template artifacts required)`);
+      } else if (planningArtifacts.ok) {
+        console.log(`  ${chalk.dim('Planning:')}   ${chalk.green('OK')} (${found}/${total} present)`);
+      } else {
+        console.log(`  ${chalk.dim('Planning:')}   ${chalk.red('FAIL')} (${planningArtifacts.missing.length}/${total} missing: ${planningArtifacts.missing.join(', ')})`);
+      }
+    }
+    if (acceptanceHints) {
+      if (acceptanceHints.total === 0) {
+        console.log(`  ${chalk.dim('Acceptance:')} ${chalk.green('OK')} (no template hints defined)`);
+      } else if (acceptanceHints.unchecked === 0) {
+        console.log(`  ${chalk.dim('Acceptance:')} ${chalk.green('OK')} (${acceptanceHints.checked}/${acceptanceHints.total} checked)`);
+      } else {
+        console.log(`  ${chalk.dim('Acceptance:')} ${chalk.yellow('WARN')} (${acceptanceHints.unchecked}/${acceptanceHints.total} unchecked)`);
+      }
+    }
+  } else {
+    console.log(`  ${chalk.dim('Project:')}  ${chalk.dim('No project detected; registry-only validation')}`);
+  }
+
+  if (errors.length > 0) {
+    console.log('');
+    console.log(chalk.red('  Errors:'));
+    for (const error of errors) {
+      console.log(`    - ${error}`);
+    }
+  }
+
+  if (warnings.length > 0) {
+    console.log('');
+    console.log(chalk.yellow('  Warnings:'));
+    for (const warning of warnings) {
+      console.log(`    - ${warning}`);
+    }
+  }
+
+  console.log('');
+  if (!ok) process.exit(1);
+}

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

@@ -0,0 +1,369 @@
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import {
+  getDispatchAssignmentPath,
+  getDispatchContextPath,
+  getDispatchPromptPath,
+  getDispatchTurnDir,
+  getTurnStagingDir,
+  getTurnStagingResultPath,
+} from '../turn-paths.js';
+import { verifyDispatchManifestForAdapter } from '../dispatch-manifest.js';
+
+export const DEFAULT_MCP_TOOL_NAME = 'agentxchain_turn';
+export const DEFAULT_MCP_TRANSPORT = 'stdio';
+
+/**
+ * Dispatch a governed turn to an MCP server.
+ *
+ * Current scope:
+ *   - stdio or streamable_http transport
+ *   - single tool call per turn
+ *   - required governed-turn tool contract
+ *   - synchronous dispatch/wait flow (like api_proxy)
+ *
+ * The MCP tool must return a valid AgentXchain turn result either as:
+ *   - structuredContent, or
+ *   - JSON text in a text content block
+ */
+export async function dispatchMcp(root, state, config, options = {}) {
+  const { signal, onStatus, onStderr, turnId } = options;
+
+  const turn = resolveTargetTurn(state, turnId);
+  if (!turn) {
+    return { ok: false, error: 'No active turn in state' };
+  }
+
+  const manifestCheck = verifyDispatchManifestForAdapter(root, turn.turn_id, options);
+  if (!manifestCheck.ok) {
+    return { ok: false, error: `Dispatch manifest verification failed: ${manifestCheck.error}` };
+  }
+
+  const runtimeId = turn.runtime_id;
+  const runtime = config.runtimes?.[runtimeId];
+  if (!runtime) {
+    return { ok: false, error: `Runtime "${runtimeId}" not found in config` };
+  }
+
+  const promptPath = join(root, getDispatchPromptPath(turn.turn_id));
+  const contextPath = join(root, getDispatchContextPath(turn.turn_id));
+  if (!existsSync(promptPath)) {
+    return { ok: false, error: 'Dispatch bundle not found. Run writeDispatchBundle() first.' };
+  }
+
+  const prompt = readFileSync(promptPath, 'utf8');
+  const context = existsSync(contextPath) ? readFileSync(contextPath, 'utf8') : '';
+  const { command, args } = resolveMcpCommand(runtime);
+  const transportType = resolveMcpTransport(runtime);
+  if (transportType === 'stdio' && !command) {
+    return { ok: false, error: `Cannot resolve MCP command for runtime "${runtimeId}". Expected "command" field in runtime config.` };
+  }
+
+  const timeoutMs = turn.deadline_at
+    ? Math.max(0, new Date(turn.deadline_at).getTime() - Date.now())
+    : 1200000;
+  const toolName = resolveMcpToolName(runtime);
+  const logs = [];
+
+  const stagingDir = join(root, getTurnStagingDir(turn.turn_id));
+  mkdirSync(stagingDir, { recursive: true });
+
+  const transport = buildMcpClientTransport({
+    root,
+    runtime,
+    command,
+    args,
+    logs,
+    onStderr,
+  });
+  if (!transport.ok) {
+    return { ok: false, error: transport.error, logs };
+  }
+
+  const client = new Client({
+    name: 'agentxchain-mcp-adapter',
+    version: '1.0.0',
+  });
+  client.onerror = (error) => {
+    logs.push(`[client-error] ${error.message}`);
+  };
+  transport.onerror = (error) => {
+    logs.push(`[transport-error] ${error.message}`);
+  };
+
+  try {
+    if (signal?.aborted) {
+      return { ok: false, aborted: true, logs };
+    }
+
+    onStatus?.(`Connecting to MCP ${transportType} server (${describeMcpRuntimeTarget(runtime)})`);
+    await client.connect(transport.transport);
+
+    if (signal?.aborted) {
+      return { ok: false, aborted: true, logs };
+    }
+
+    onStatus?.(`Listing MCP tools`);
+    const toolsResult = await client.listTools(undefined, {
+      signal,
+      timeout: timeoutMs,
+      maxTotalTimeout: timeoutMs,
+    });
+    const toolNames = toolsResult.tools.map((tool) => tool.name);
+    if (!toolNames.includes(toolName)) {
+      return {
+        ok: false,
+        error: `MCP server does not expose required tool "${toolName}". Available tools: ${toolNames.join(', ') || '(none)'}`,
+        logs,
+      };
+    }
+
+    if (signal?.aborted) {
+      return { ok: false, aborted: true, logs };
+    }
+
+    onStatus?.(`Calling MCP tool "${toolName}"`);
+    const toolResult = await client.callTool({
+      name: toolName,
+      arguments: {
+        run_id: state.run_id,
+        turn_id: turn.turn_id,
+        role: turn.assigned_role,
+        phase: state.phase,
+        runtime_id: runtimeId,
+        project_root: root,
+        dispatch_dir: join(root, getDispatchTurnDir(turn.turn_id)),
+        assignment_path: join(root, getDispatchAssignmentPath(turn.turn_id)),
+        prompt_path: promptPath,
+        context_path: contextPath,
+        staging_path: join(root, getTurnStagingResultPath(turn.turn_id)),
+        prompt,
+        context,
+      },
+    }, undefined, {
+      signal,
+      timeout: timeoutMs,
+      maxTotalTimeout: timeoutMs,
+      resetTimeoutOnProgress: true,
+    });
+
+    if (toolResult?.isError) {
+      return {
+        ok: false,
+        error: buildMcpToolError(toolName, toolResult),
+        logs,
+      };
+    }
+
+    const turnResult = extractTurnResultFromMcpToolResult(toolResult);
+    if (!turnResult.ok) {
+      return { ok: false, error: turnResult.error, logs };
+    }
+
+    const stagingPath = join(root, getTurnStagingResultPath(turn.turn_id));
+    writeFileSync(stagingPath, JSON.stringify(turnResult.result, null, 2));
+
+    return {
+      ok: true,
+      toolName,
+      logs,
+    };
+  } catch (error) {
+    if (signal?.aborted) {
+      return { ok: false, aborted: true, logs };
+    }
+    return {
+      ok: false,
+      error: `MCP dispatch failed: ${error.message}`,
+      logs,
+    };
+  } finally {
+    await safeCloseClient(client, transport.transport);
+  }
+}
+
+export function resolveMcpCommand(runtime) {
+  if (!runtime?.command) return { command: null, args: [] };
+
+  if (Array.isArray(runtime.command)) {
+    const [command, ...args] = runtime.command;
+    return { command, args };
+  }
+
+  return {
+    command: runtime.command,
+    args: Array.isArray(runtime.args) ? runtime.args : [],
+  };
+}
+
+export function resolveMcpToolName(runtime) {
+  return typeof runtime?.tool_name === 'string' && runtime.tool_name.trim()
+    ? runtime.tool_name.trim()
+    : DEFAULT_MCP_TOOL_NAME;
+}
+
+export function resolveMcpTransport(runtime) {
+  return typeof runtime?.transport === 'string' && runtime.transport.trim()
+    ? runtime.transport.trim()
+    : DEFAULT_MCP_TRANSPORT;
+}
+
+export function describeMcpRuntimeTarget(runtime) {
+  return resolveMcpTransport(runtime) === 'streamable_http'
+    ? runtime?.url || '(unknown)'
+    : resolveMcpCommand(runtime).command || '(unknown)';
+}
+
+export function extractTurnResultFromMcpToolResult(toolResult) {
+  const directCandidates = [
+    toolResult?.structuredContent,
+    toolResult?.toolResult?.structuredContent,
+    toolResult?.toolResult,
+  ];
+
+  for (const candidate of directCandidates) {
+    if (looksLikeTurnResult(candidate)) {
+      return { ok: true, result: candidate };
+    }
+  }
+
+  const textBlocks = [
+    ...(Array.isArray(toolResult?.content) ? toolResult.content : []),
+    ...(Array.isArray(toolResult?.toolResult?.content) ? toolResult.toolResult.content : []),
+  ].filter((item) => item?.type === 'text' && typeof item.text === 'string');
+
+  for (const block of textBlocks) {
+    const parsed = tryParseJson(block.text);
+    if (looksLikeTurnResult(parsed) || isPlainObject(parsed)) {
+      return { ok: true, result: parsed };
+    }
+  }
+
+  if (textBlocks.length === 0) {
+    return {
+      ok: false,
+      error: 'MCP tool returned no structuredContent and no text content blocks containing a turn result.',
+    };
+  }
+
+  return {
+    ok: false,
+    error: 'MCP tool returned text content, but none of the text blocks contained valid turn-result JSON.',
+  };
+}
+
+function buildMcpToolError(toolName, toolResult) {
+  const text = Array.isArray(toolResult?.content)
+    ? toolResult.content
+      .filter((item) => item?.type === 'text' && typeof item.text === 'string')
+      .map((item) => item.text.trim())
+      .filter(Boolean)
+      .join(' ')
+    : '';
+  if (text) {
+    return `MCP tool "${toolName}" returned an error: ${text}`;
+  }
+  return `MCP tool "${toolName}" returned an error without diagnostic text.`;
+}
+
+function buildTransportEnv(env) {
+  const result = {};
+  for (const [key, value] of Object.entries(env || {})) {
+    if (typeof value === 'string') {
+      result[key] = value;
+    }
+  }
+  return result;
+}
+
+function buildMcpClientTransport({ root, runtime, command, args, logs, onStderr }) {
+  if (resolveMcpTransport(runtime) === 'streamable_http') {
+    try {
+      const requestHeaders = buildRequestHeaders(runtime?.headers);
+      return {
+        ok: true,
+        transport: new StreamableHTTPClientTransport(new URL(runtime.url), {
+          requestInit: requestHeaders ? { headers: requestHeaders } : undefined,
+        }),
+      };
+    } catch (error) {
+      logs.push(`[transport-error] ${error.message}`);
+      return {
+        ok: false,
+        error: `Cannot resolve MCP streamable_http runtime: ${error.message}`,
+      };
+    }
+  }
+
+  const transport = new StdioClientTransport({
+    command,
+    args,
+    cwd: runtime.cwd ? join(root, runtime.cwd) : root,
+    env: buildTransportEnv(process.env),
+    stderr: 'pipe',
+  });
+
+  if (transport.stderr) {
+    transport.stderr.on('data', (chunk) => {
+      const text = chunk.toString();
+      logs.push(`[stderr] ${text}`);
+      if (onStderr) onStderr(text);
+    });
+  }
+
+  return { ok: true, transport };
+}
+
+function buildRequestHeaders(headers) {
+  if (!headers || typeof headers !== 'object' || Array.isArray(headers)) {
+    return null;
+  }
+
+  const result = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (typeof value === 'string') {
+      result[key] = value;
+    }
+  }
+  return Object.keys(result).length > 0 ? result : null;
+}
+
+function isPlainObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function looksLikeTurnResult(value) {
+  if (!isPlainObject(value)) return false;
+  const hasIdentity = 'run_id' in value || 'turn_id' in value;
+  const hasLifecycle = 'status' in value || 'role' in value || 'runtime_id' in value;
+  return hasIdentity && hasLifecycle;
+}
+
+function tryParseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function resolveTargetTurn(state, turnId) {
+  if (turnId && state?.active_turns?.[turnId]) {
+    return state.active_turns[turnId];
+  }
+  return state?.current_turn || Object.values(state?.active_turns || {})[0];
+}
+
+async function safeCloseClient(client, transport) {
+  try {
+    await client.close();
+    return;
+  } catch {}
+
+  try {
+    await transport.close();
+  } catch {}
+}

package/src/lib/governed-templates.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -9,6 +9,7 @@ export const VALID_GOVERNED_TEMPLATE_IDS = Object.freeze([
   'generic',
   'api-service',
   'cli-tool',
+  'library',
   'web-app',
 ]);
 
@@ -143,3 +144,237 @@ export function loadGovernedTemplate(templateId) {
 export function loadAllGovernedTemplates() {
   return VALID_GOVERNED_TEMPLATE_IDS.map((templateId) => loadGovernedTemplate(templateId));
 }
+
+export function listGovernedTemplateManifestIds(manifestDir = GOVERNED_TEMPLATES_DIR) {
+  if (!existsSync(manifestDir)) {
+    return [];
+  }
+
+  return readdirSync(manifestDir)
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => entry.slice(0, -'.json'.length))
+    .sort();
+}
+
+export function validateGovernedTemplateRegistry(options = {}) {
+  const manifestDir = options.manifestDir || GOVERNED_TEMPLATES_DIR;
+  const registeredIds = options.registeredIds || [...VALID_GOVERNED_TEMPLATE_IDS];
+  const errors = [];
+  const warnings = [];
+  const manifestIds = listGovernedTemplateManifestIds(manifestDir);
+
+  for (const templateId of registeredIds) {
+    const manifestPath = join(manifestDir, `${templateId}.json`);
+    if (!existsSync(manifestPath)) {
+      errors.push(`Registered template "${templateId}" is missing its manifest file.`);
+      continue;
+    }
+
+    let manifest;
+    try {
+      manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+    } catch (err) {
+      errors.push(`Template "${templateId}" manifest is invalid JSON: ${err.message}`);
+      continue;
+    }
+
+    const validation = validateGovernedTemplateManifest(manifest, templateId);
+    if (!validation.ok) {
+      errors.push(`Template "${templateId}" manifest is invalid: ${validation.errors.join('; ')}`);
+    }
+  }
+
+  for (const manifestId of manifestIds) {
+    if (!registeredIds.includes(manifestId)) {
+      errors.push(`Manifest "${manifestId}.json" exists on disk but is not registered in VALID_GOVERNED_TEMPLATE_IDS.`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    registered_ids: registeredIds,
+    manifest_ids: manifestIds,
+    errors,
+    warnings,
+  };
+}
+
+export function validateProjectPlanningArtifacts(root, templateId) {
+  const effectiveTemplateId = templateId || 'generic';
+  const errors = [];
+  const warnings = [];
+
+  let manifest;
+  try {
+    manifest = loadGovernedTemplate(effectiveTemplateId);
+  } catch {
+    // Template load failure is already reported by validateGovernedProjectTemplate.
+    // Skip artifact check — we cannot know what artifacts to expect.
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      expected: [],
+      present: [],
+      missing: [],
+      errors,
+      warnings: ['Template could not be loaded; planning artifact check skipped.'],
+    };
+  }
+
+  const artifacts = manifest.planning_artifacts || [];
+  const expected = artifacts.map((a) => a.filename);
+  const present = [];
+  const missing = [];
+
+  for (const filename of expected) {
+    const artifactPath = join(root, '.planning', filename);
+    if (existsSync(artifactPath)) {
+      present.push(filename);
+    } else {
+      missing.push(filename);
+      errors.push(`Template "${effectiveTemplateId}" requires planning artifact ".planning/${filename}" but it is missing.`);
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    template: effectiveTemplateId,
+    expected,
+    present,
+    missing,
+    errors,
+    warnings,
+  };
+}
+
+const TEMPLATE_GUIDANCE_HEADER = '## Template Guidance';
+
+export function validateAcceptanceHintCompletion(root, templateId) {
+  const effectiveTemplateId = templateId || 'generic';
+  const errors = [];
+  const warnings = [];
+
+  let manifest;
+  try {
+    manifest = loadGovernedTemplate(effectiveTemplateId);
+  } catch {
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      total: 0,
+      checked: 0,
+      unchecked: 0,
+      missing_file: false,
+      missing_section: false,
+      unchecked_hints: [],
+      errors,
+      warnings: ['Template could not be loaded; acceptance hint check skipped.'],
+    };
+  }
+
+  const hints = manifest.acceptance_hints || [];
+  if (hints.length === 0) {
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      total: 0,
+      checked: 0,
+      unchecked: 0,
+      missing_file: false,
+      missing_section: false,
+      unchecked_hints: [],
+      errors,
+      warnings,
+    };
+  }
+
+  const matrixPath = join(root, '.planning', 'acceptance-matrix.md');
+  if (!existsSync(matrixPath)) {
+    warnings.push('acceptance-matrix.md not found; cannot verify template acceptance hints.');
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      total: hints.length,
+      checked: 0,
+      unchecked: hints.length,
+      missing_file: true,
+      missing_section: false,
+      unchecked_hints: [...hints],
+      errors,
+      warnings,
+    };
+  }
+
+  const matrixContent = readFileSync(matrixPath, 'utf8');
+  const sectionIndex = matrixContent.indexOf(TEMPLATE_GUIDANCE_HEADER);
+  if (sectionIndex === -1) {
+    warnings.push('acceptance-matrix.md has no "## Template Guidance" section; cannot verify template acceptance hints.');
+    return {
+      ok: true,
+      template: effectiveTemplateId,
+      total: hints.length,
+      checked: 0,
+      unchecked: hints.length,
+      missing_file: false,
+      missing_section: true,
+      unchecked_hints: [...hints],
+      errors,
+      warnings,
+    };
+  }
+
+  // Parse the Template Guidance section for checked/unchecked items
+  const sectionContent = matrixContent.slice(sectionIndex);
+  const checkedPattern = /^- \[x\]\s+(.+)$/gim;
+  const checkedTexts = new Set();
+  let match;
+  while ((match = checkedPattern.exec(sectionContent)) !== null) {
+    checkedTexts.add(match[1].trim());
+  }
+
+  const uncheckedHints = [];
+  let checkedCount = 0;
+
+  for (const hint of hints) {
+    if (checkedTexts.has(hint)) {
+      checkedCount++;
+    } else {
+      uncheckedHints.push(hint);
+      warnings.push(`Acceptance hint unchecked: "${hint}"`);
+    }
+  }
+
+  return {
+    ok: true,
+    template: effectiveTemplateId,
+    total: hints.length,
+    checked: checkedCount,
+    unchecked: uncheckedHints.length,
+    missing_file: false,
+    missing_section: false,
+    unchecked_hints: uncheckedHints,
+    errors,
+    warnings,
+  };
+}
+
+export function validateGovernedProjectTemplate(templateId, source = 'agentxchain.json') {
+  const effectiveTemplateId = templateId || 'generic';
+  const effectiveSource = templateId ? source : 'implicit_default';
+  const errors = [];
+  const warnings = [];
+
+  try {
+    loadGovernedTemplate(effectiveTemplateId);
+  } catch (err) {
+    errors.push(err.message);
+  }
+
+  return {
+    ok: errors.length === 0,
+    template: effectiveTemplateId,
+    source: effectiveSource,
+    errors,
+    warnings,
+  };
+}

package/src/lib/normalized-config.js

@@ -16,9 +16,10 @@ import { validateHooksConfig } from './hook-runner.js';
 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'];
+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'];
+const VALID_MCP_TRANSPORTS = ['stdio', 'streamable_http'];
 const VALID_PHASES = ['planning', 'implementation', 'qa'];
 const VALID_API_PROXY_RETRY_JITTER = ['none', 'full'];
 const VALID_API_PROXY_RETRY_CLASSES = [
@@ -46,6 +47,92 @@ const VALID_API_PROXY_PREFLIGHT_FIELDS = [
   'safety_margin_tokens',
 ];
 
+function validateMcpRuntime(runtimeId, runtime, errors) {
+  const transport = typeof runtime?.transport === 'string' && runtime.transport.trim()
+    ? runtime.transport.trim()
+    : 'stdio';
+  const command = runtime?.command;
+
+  if (!VALID_MCP_TRANSPORTS.includes(transport)) {
+    errors.push(`Runtime "${runtimeId}": mcp transport must be one of: ${VALID_MCP_TRANSPORTS.join(', ')}`);
+  }
+
+  if ('tool_name' in runtime && (typeof runtime.tool_name !== 'string' || !runtime.tool_name.trim())) {
+    errors.push(`Runtime "${runtimeId}": mcp tool_name must be a non-empty string`);
+  }
+
+  if (transport === 'streamable_http') {
+    if (typeof runtime?.url !== 'string' || !runtime.url.trim()) {
+      errors.push(`Runtime "${runtimeId}": mcp streamable_http requires "url"`);
+    } else {
+      try {
+        const parsed = new URL(runtime.url);
+        if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+          errors.push(`Runtime "${runtimeId}": mcp url must use http or https`);
+        }
+      } catch {
+        errors.push(`Runtime "${runtimeId}": mcp url must be a valid absolute URL`);
+      }
+    }
+
+    if ('headers' in runtime) {
+      if (!runtime.headers || typeof runtime.headers !== 'object' || Array.isArray(runtime.headers)) {
+        errors.push(`Runtime "${runtimeId}": mcp headers must be an object of string values`);
+      } else {
+        for (const [key, value] of Object.entries(runtime.headers)) {
+          if (typeof value !== 'string') {
+            errors.push(`Runtime "${runtimeId}": mcp headers["${key}"] must be a string`);
+          }
+        }
+      }
+    }
+
+    if ('command' in runtime) {
+      errors.push(`Runtime "${runtimeId}": mcp streamable_http does not accept "command"`);
+    }
+
+    if ('args' in runtime) {
+      errors.push(`Runtime "${runtimeId}": mcp streamable_http does not accept "args"`);
+    }
+
+    if ('cwd' in runtime) {
+      errors.push(`Runtime "${runtimeId}": mcp streamable_http does not accept "cwd"`);
+    }
+
+    return;
+  }
+
+  if (typeof command === 'string') {
+    if (!command.trim()) {
+      errors.push(`Runtime "${runtimeId}": mcp command must be a non-empty string`);
+    }
+  } else if (Array.isArray(command)) {
+    if (command.length === 0 || command.some((part) => typeof part !== 'string' || !part.trim())) {
+      errors.push(`Runtime "${runtimeId}": mcp command array must contain at least one non-empty string and no empty parts`);
+    }
+  } else {
+    errors.push(`Runtime "${runtimeId}": mcp requires "command" as a string or string array`);
+  }
+
+  if ('args' in runtime) {
+    if (!Array.isArray(runtime.args) || runtime.args.some((part) => typeof part !== 'string')) {
+      errors.push(`Runtime "${runtimeId}": mcp args must be an array of strings`);
+    }
+  }
+
+  if ('cwd' in runtime && (typeof runtime.cwd !== 'string' || !runtime.cwd.trim())) {
+    errors.push(`Runtime "${runtimeId}": mcp cwd must be a non-empty string`);
+  }
+
+  if ('url' in runtime) {
+    errors.push(`Runtime "${runtimeId}": mcp stdio does not accept "url"`);
+  }
+
+  if ('headers' in runtime) {
+    errors.push(`Runtime "${runtimeId}": mcp stdio does not accept "headers"`);
+  }
+}
+
 function validateApiProxyRetryPolicy(runtimeId, retryPolicy, errors) {
   if (!retryPolicy || typeof retryPolicy !== 'object' || Array.isArray(retryPolicy)) {
     errors.push(`Runtime "${runtimeId}": retry_policy must be an object`);
@@ -263,6 +350,9 @@ export function validateV4Config(data, projectRoot) {
           validateApiProxyPreflightTokenization(id, rt, errors);
         }
       }
+      if (rt.type === 'mcp') {
+        validateMcpRuntime(id, rt, errors);
+      }
     }
   }
 

package/src/lib/repo-observer.js

@@ -270,13 +270,13 @@ export function buildObservedArtifact(observation, baseline) {
  *
  * Normalization rules (spec §5.3):
  *   - manual + external pass → attested_pass
- *   - local_cli + pass + machine evidence all zero → pass
- *   - local_cli + pass + no reproducible evidence → not_reproducible
+ *   - executable runtime + pass + machine evidence all zero → pass
+ *   - executable runtime + pass + no reproducible evidence → not_reproducible
  *   - any external fail → fail
  *   - external skipped → skipped
  *
  * @param {object} verification — the actor-supplied verification object
- * @param {string} runtimeType — 'manual' | 'local_cli' | 'api_proxy'
+ * @param {string} runtimeType — 'manual' | 'local_cli' | 'api_proxy' | 'mcp'
  * @returns {{ status: string, reason: string, reproducible: boolean }}
  */
 export function normalizeVerification(verification, runtimeType) {
@@ -299,18 +299,18 @@ export function normalizeVerification(verification, runtimeType) {
     return { status: 'attested_pass', reason: 'API proxy runtime — no direct execution environment', reproducible: false };
   }
 
-  // local_cli — check for machine evidence
+  // local_cli / mcp — check for machine evidence
   const evidence = verification?.machine_evidence;
   if (Array.isArray(evidence) && evidence.length > 0) {
     const allZero = evidence.every(e => typeof e.exit_code === 'number' && e.exit_code === 0);
     if (allZero) {
-      return { status: 'pass', reason: 'local_cli turn provided machine evidence with zero exit codes', reproducible: true };
+      return { status: 'pass', reason: `${runtimeType} turn provided machine evidence with zero exit codes`, reproducible: true };
     }
-    return { status: 'not_reproducible', reason: 'local_cli turn has machine evidence with non-zero exit codes despite claiming pass', reproducible: false };
+    return { status: 'not_reproducible', reason: `${runtimeType} turn has machine evidence with non-zero exit codes despite claiming pass`, reproducible: false };
   }
 
-  // local_cli + pass but no machine evidence
-  return { status: 'not_reproducible', reason: 'local_cli turn claimed pass but provided no machine evidence', reproducible: false };
+  // executable runtime + pass but no machine evidence
+  return { status: 'not_reproducible', reason: `${runtimeType} turn claimed pass but provided no machine evidence`, reproducible: false };
 }
 
 // ── Declared vs Observed Comparison ─────────────────────────────────────────

package/src/lib/validation.js

@@ -2,6 +2,12 @@ import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { validateStagedTurnResult, STAGING_PATH } from './turn-result-validator.js';
 import { getActiveTurn } from './governed-state.js';
+import {
+  validateGovernedProjectTemplate,
+  validateGovernedTemplateRegistry,
+  validateProjectPlanningArtifacts,
+  validateAcceptanceHintCompletion,
+} from './governed-templates.js';
 
 const DEFAULT_REQUIRED_FILES = [
   '.planning/PROJECT.md',
@@ -87,6 +93,23 @@ export function validateGovernedProject(root, rawConfig, config, opts = {}) {
   const errors = [];
   const warnings = [];
 
+  const templateRegistry = validateGovernedTemplateRegistry();
+  errors.push(...templateRegistry.errors);
+  warnings.push(...templateRegistry.warnings);
+
+  const projectTemplate = validateGovernedProjectTemplate(rawConfig?.template);
+  errors.push(...projectTemplate.errors);
+  warnings.push(...projectTemplate.warnings);
+
+  // Validate planning artifact completeness against the configured template
+  const planningArtifacts = validateProjectPlanningArtifacts(root, rawConfig?.template);
+  errors.push(...planningArtifacts.errors);
+  warnings.push(...planningArtifacts.warnings);
+
+  // Validate acceptance hint completion against the configured template
+  const acceptanceHints = validateAcceptanceHintCompletion(root, rawConfig?.template);
+  warnings.push(...acceptanceHints.warnings);
+
   const mustExist = [
     config.files?.state || '.agentxchain/state.json',
     config.files?.history || '.agentxchain/history.jsonl',

package/src/templates/governed/library.json

@@ -0,0 +1,31 @@
+{
+  "id": "library",
+  "display_name": "Library",
+  "description": "Governed scaffold for reusable packages with public-API, compatibility, and adoption planning.",
+  "version": "1",
+  "protocol_compatibility": ["1.0", "1.1"],
+  "planning_artifacts": [
+    {
+      "filename": "public-api.md",
+      "content_template": "# Public API — {{project_name}}\n\n## Supported Entrypoints\n- Package name:\n- Import / require paths:\n- Stable vs experimental exports:\n\n## Consumer-Facing Surface\n| Export / command | Consumer use case | Stability | Notes |\n|------------------|-------------------|-----------|-------|\n| | | | |\n\n## Breaking-Change Triggers\n- What counts as breaking:\n- What can ship behind deprecation first:\n- What must stay internal:\n"
+    },
+    {
+      "filename": "compatibility-policy.md",
+      "content_template": "# Compatibility Policy — {{project_name}}\n\n## Versioning Contract\n- Semver policy:\n- Supported runtime versions:\n- Supported platforms / environments:\n\n## Deprecation And Migration\n| Surface | Deprecation path | Migration guidance | Removal target |\n|---------|------------------|--------------------|----------------|\n| | | | |\n\n## Compatibility Risks\n- Dependency upgrade hazards:\n- Packaging / module-format risks:\n- Consumer breakage watchpoints:\n"
+    },
+    {
+      "filename": "release-adoption.md",
+      "content_template": "# Release And Adoption — {{project_name}}\n\n## Consumer Smoke Proof\n- Install command:\n- Import / usage smoke check:\n- Example consumer environment:\n\n## Release Notes Inputs\n- User-visible changes:\n- Upgrade steps:\n- Rollback or pinning advice:\n\n## Adoption Risks\n- Migration blockers:\n- Documentation gaps:\n- Support expectations after release:\n"
+    }
+  ],
+  "prompt_overrides": {
+    "pm": "Define the exported surface, compatibility promise, and consumer upgrade expectations before the team treats the package as ready to ship.",
+    "dev": "Treat exported entrypoints, backward compatibility, and package-consumer install or import paths as product behavior, not release polish.",
+    "qa": "Verify public API stability, install/import smoke, migration notes, and compatibility risks across supported runtimes before sign-off."
+  },
+  "acceptance_hints": [
+    "Public API surface reviewed and intentionally versioned",
+    "Compatibility or migration expectations documented for consumers",
+    "Install/import or package-consumer smoke path verified"
+  ]
+}