agentxchain 2.103.0 → 2.105.0

package/src/commands/doctor.js

@@ -11,6 +11,11 @@ import { loadNormalizedConfig, detectConfigVersion } from '../lib/normalized-con
 import { readDaemonState, evaluateDaemonStatus } from '../lib/run-schedule.js';
 import { getGovernedVersionSurface, formatGovernedVersionLabel } from '../lib/protocol-version.js';
 import { PLUGIN_MANIFEST_FILE } from '../lib/plugins.js';
+import {
+  getRoleRuntimeCapabilityContract,
+  summarizeRoleRuntimeCapability,
+  summarizeRuntimeCapabilityContract,
+} from '../lib/runtime-capabilities.js';
 
 export async function doctorCommand(opts = {}) {
   const root = findProjectRoot(process.cwd());
@@ -76,8 +81,9 @@ function governedDoctor(root, rawConfig, opts) {
   // 3. Runtime reachable — one sub-check per runtime
   // Use normalized runtimes if available, otherwise fall back to raw config
   const runtimes = (normalized && normalized.runtimes) || rawConfig.runtimes || {};
+  const rolesByRuntime = buildRolesByRuntime(normalized?.roles || {});
   for (const [rtId, rt] of Object.entries(runtimes)) {
-    const check = checkRuntimeReachable(rtId, rt);
+    const check = checkRuntimeReachable(rtId, rt, rolesByRuntime[rtId] || []);
     checks.push(check);
   }
   const connectorProbe = getConnectorProbeRecommendation(runtimes);
@@ -290,6 +296,12 @@ function governedDoctor(root, rawConfig, opts) {
             ? chalk.dim('INFO')
             : chalk.red('FAIL');
       console.log(`  ${badge}  ${c.name.padEnd(24)} ${chalk.dim(c.detail)}`);
+      if (c.runtime_contract) {
+        console.log(`        ${chalk.dim(summarizeRuntimeCapabilityContract(c.runtime_contract))}`);
+        if (Array.isArray(c.bound_roles) && c.bound_roles.length > 0) {
+          console.log(`        ${chalk.dim(`roles: ${c.bound_roles.map(summarizeRoleRuntimeCapability).join(' | ')}`)}`);
+        }
+      }
     }
 
     console.log('');
@@ -309,25 +321,45 @@ function governedDoctor(root, rawConfig, opts) {
   process.exit(failCount > 0 ? 1 : 0);
 }
 
-function checkRuntimeReachable(rtId, rt) {
+function buildRolesByRuntime(roles) {
+  const grouped = {};
+  for (const [roleId, role] of Object.entries(roles || {})) {
+    if (!role?.runtime_id) continue;
+    if (!grouped[role.runtime_id]) grouped[role.runtime_id] = [];
+    grouped[role.runtime_id].push([roleId, role]);
+  }
+  return grouped;
+}
+
+function attachRuntimeContract(baseCheck, rtId, rt, boundRoleEntries) {
+  const bound_roles = boundRoleEntries.map(([roleId, role]) => getRoleRuntimeCapabilityContract(roleId, role, rt));
+  return {
+    ...baseCheck,
+    runtime_type: rt?.type || 'unknown',
+    runtime_contract: bound_roles[0]?.runtime_contract || getRoleRuntimeCapabilityContract('__unbound__', { write_authority: 'unknown' }, rt).runtime_contract,
+    bound_roles,
+  };
+}
+
+function checkRuntimeReachable(rtId, rt, boundRoleEntries = []) {
   const base = { id: `runtime_${rtId}`, name: `Runtime: ${rtId}` };
 
   if (!rt || !rt.type) {
-    return { ...base, level: 'warn', detail: 'No runtime type specified' };
+    return attachRuntimeContract({ ...base, level: 'warn', detail: 'No runtime type specified' }, rtId, rt, boundRoleEntries);
   }
 
   switch (rt.type) {
     case 'manual':
-      return { ...base, level: 'pass', detail: 'Manual runtime (no binary needed)' };
+      return attachRuntimeContract({ ...base, level: 'pass', detail: 'Manual runtime (no binary needed)' }, rtId, rt, boundRoleEntries);
 
     case 'local_cli': {
       const cmd = Array.isArray(rt.command) ? rt.command[0] : (typeof rt.command === 'string' ? rt.command.split(/\s+/)[0] : null);
-      if (!cmd) return { ...base, level: 'warn', detail: 'No command configured' };
+      if (!cmd) return attachRuntimeContract({ ...base, level: 'warn', detail: 'No command configured' }, rtId, rt, boundRoleEntries);
       try {
         execSync(`command -v ${cmd}`, { stdio: 'ignore' });
-        return { ...base, level: 'pass', detail: `${cmd} binary found` };
+        return attachRuntimeContract({ ...base, level: 'pass', detail: `${cmd} binary found` }, rtId, rt, boundRoleEntries);
       } catch {
-        return { ...base, level: 'fail', detail: `${cmd} not found in PATH` };
+        return attachRuntimeContract({ ...base, level: 'fail', detail: `${cmd} not found in PATH` }, rtId, rt, boundRoleEntries);
       }
     }
 
@@ -335,34 +367,34 @@ function checkRuntimeReachable(rtId, rt) {
       const envVar = rt.auth_env;
       if (!envVar) {
         // ollama and similar providers may not require auth
-        return { ...base, level: 'pass', detail: `${rt.provider || 'unknown'} provider (no auth required)` };
+        return attachRuntimeContract({ ...base, level: 'pass', detail: `${rt.provider || 'unknown'} provider (no auth required)` }, rtId, rt, boundRoleEntries);
       }
       if (process.env[envVar]) {
-        return { ...base, level: 'pass', detail: `${envVar} is set` };
+        return attachRuntimeContract({ ...base, level: 'pass', detail: `${envVar} is set` }, rtId, rt, boundRoleEntries);
       }
-      return { ...base, level: 'fail', detail: `${envVar} not set` };
+      return attachRuntimeContract({ ...base, level: 'fail', detail: `${envVar} not set` }, rtId, rt, boundRoleEntries);
     }
 
     case 'mcp': {
       const transport = rt.transport || 'stdio';
       if (transport === 'streamable_http') {
-        return { ...base, level: 'warn', detail: 'Remote MCP endpoint (cannot verify at doctor time)' };
+        return attachRuntimeContract({ ...base, level: 'warn', detail: 'Remote MCP endpoint (cannot verify at doctor time)' }, rtId, rt, boundRoleEntries);
       }
       const cmd = Array.isArray(rt.command) ? rt.command[0] : (typeof rt.command === 'string' ? rt.command.split(/\s+/)[0] : null);
-      if (!cmd) return { ...base, level: 'warn', detail: 'No MCP command configured' };
+      if (!cmd) return attachRuntimeContract({ ...base, level: 'warn', detail: 'No MCP command configured' }, rtId, rt, boundRoleEntries);
       try {
         execSync(`command -v ${cmd}`, { stdio: 'ignore' });
-        return { ...base, level: 'pass', detail: `${cmd} binary found` };
+        return attachRuntimeContract({ ...base, level: 'pass', detail: `${cmd} binary found` }, rtId, rt, boundRoleEntries);
       } catch {
-        return { ...base, level: 'fail', detail: `${cmd} not found in PATH` };
+        return attachRuntimeContract({ ...base, level: 'fail', detail: `${cmd} not found in PATH` }, rtId, rt, boundRoleEntries);
       }
     }
 
     case 'remote_agent':
-      return { ...base, level: 'warn', detail: 'Remote agent endpoint (cannot verify at doctor time)' };
+      return attachRuntimeContract({ ...base, level: 'warn', detail: 'Remote agent endpoint (cannot verify at doctor time)' }, rtId, rt, boundRoleEntries);
 
     default:
-      return { ...base, level: 'warn', detail: `Unknown runtime type: ${rt.type}` };
+      return attachRuntimeContract({ ...base, level: 'warn', detail: `Unknown runtime type: ${rt.type}` }, rtId, rt, boundRoleEntries);
   }
 }
 

package/src/commands/generate.js

@@ -1,6 +1,10 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 import chalk from 'chalk';
-import { loadConfig } from '../lib/config.js';
+import { loadConfig, loadProjectContext } from '../lib/config.js';
 import { generateVSCodeFiles } from '../lib/generate-vscode.js';
+import { loadGovernedTemplate } from '../lib/governed-templates.js';
+import { buildGovernedPlanningArtifacts } from '../lib/planning-artifacts.js';
 
 export async function generateCommand() {
   const result = loadConfig();
@@ -42,3 +46,124 @@ export async function generateCommand() {
   console.log(chalk.dim('  Select an agent from the Chat dropdown to start a turn.'));
   console.log('');
 }
+
+function failPlanningGenerate(message, opts = {}) {
+  if (opts.json) {
+    console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+  } else {
+    console.log(chalk.red(`  ${message}`));
+  }
+  process.exit(1);
+}
+
+export async function generatePlanningCommand(opts = {}) {
+  const context = loadProjectContext();
+  if (!context) {
+    failPlanningGenerate('No valid agentxchain.json found. Run `agentxchain init --governed` first.', opts);
+  }
+
+  if (context.version !== 4) {
+    failPlanningGenerate('`generate planning` only works in governed repos.', opts);
+  }
+
+  const templateId = context.rawConfig.template || 'generic';
+  let template;
+  try {
+    template = loadGovernedTemplate(templateId);
+  } catch (err) {
+    failPlanningGenerate(err.message, opts);
+  }
+
+  const projectName = context.config?.project?.name || context.rawConfig?.project?.name || 'AgentXchain Project';
+  const artifacts = buildGovernedPlanningArtifacts({
+    projectName,
+    routing: context.config.routing || {},
+    roles: context.config.roles || {},
+    template,
+    workflowKitConfig: context.config.workflow_kit || null,
+  });
+
+  const created = [];
+  const overwritten = [];
+  const skippedExisting = [];
+
+  for (const artifact of artifacts) {
+    const absPath = join(context.root, artifact.path);
+    if (existsSync(absPath)) {
+      if (opts.force) {
+        overwritten.push(artifact.path);
+      } else {
+        skippedExisting.push(artifact.path);
+        continue;
+      }
+    } else {
+      created.push(artifact.path);
+    }
+
+    if (opts.dryRun) {
+      continue;
+    }
+
+    const parentDir = dirname(absPath);
+    if (!existsSync(parentDir)) {
+      mkdirSync(parentDir, { recursive: true });
+    }
+    writeFileSync(absPath, artifact.content);
+  }
+
+  const payload = {
+    ok: true,
+    mode: 'planning',
+    dry_run: Boolean(opts.dryRun),
+    force: Boolean(opts.force),
+    template: template.id,
+    project: projectName,
+    total_artifacts: artifacts.length,
+    created,
+    overwritten,
+    skipped_existing: skippedExisting,
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log('');
+  console.log(chalk.bold('  Generating governed planning artifacts...'));
+  console.log(chalk.dim(`  Project: ${projectName}`));
+  console.log(chalk.dim(`  Template: ${template.id}`));
+  console.log('');
+
+  if (created.length > 0) {
+    console.log(chalk.green(`  ${opts.dryRun ? 'Would create' : 'Created'} ${created.length} artifact${created.length === 1 ? '' : 's'}:`));
+    for (const path of created) {
+      console.log(chalk.green(`    ${path}`));
+    }
+  }
+
+  if (overwritten.length > 0) {
+    console.log(chalk.yellow(`  ${opts.dryRun ? 'Would overwrite' : 'Overwrote'} ${overwritten.length} artifact${overwritten.length === 1 ? '' : 's'}:`));
+    for (const path of overwritten) {
+      console.log(chalk.yellow(`    ${path}`));
+    }
+  }
+
+  if (skippedExisting.length > 0) {
+    console.log(chalk.dim(`  Preserved ${skippedExisting.length} existing artifact${skippedExisting.length === 1 ? '' : 's'}:`));
+    for (const path of skippedExisting) {
+      console.log(chalk.dim(`    ${path}`));
+    }
+  }
+
+  if (created.length === 0 && overwritten.length === 0) {
+    console.log(chalk.dim(`  ${opts.force ? 'Nothing to overwrite.' : 'All scaffold-owned planning artifacts already exist.'}`));
+  }
+
+  if (opts.dryRun) {
+    console.log('');
+    console.log(chalk.dim('  No files were written. Re-run without `--dry-run` to apply.'));
+  }
+
+  console.log('');
+}

package/src/commands/history.js

@@ -5,10 +5,11 @@
  */
 
 import { resolve } from 'path';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync } from 'fs';
 import chalk from 'chalk';
 import { queryRunHistory, queryRunLineage, isInheritable } from '../lib/run-history.js';
-import { getRunTriggerLabel, summarizeRunProvenance } from '../lib/run-provenance.js';
+import { buildRunOutcomeSummary } from '../lib/history-diff-summary.js';
+import { getRunTriggerLabel } from '../lib/run-provenance.js';
 
 /**
  * @param {object} opts - { json?: boolean, limit?: number, status?: string, dir?: string }
@@ -67,7 +68,11 @@ export async function historyCommand(opts) {
   });
 
   if (opts.json) {
-    const enriched = entries.map(e => ({ ...e, inheritable: isInheritable(e) }));
+    const enriched = entries.map((e) => ({
+      ...e,
+      inheritable: isInheritable(e),
+      outcome_summary: buildRunOutcomeSummary(e),
+    }));
     console.log(JSON.stringify(enriched, null, 2));
     return;
   }
@@ -85,6 +90,7 @@ export async function historyCommand(opts) {
     pad('#', 4),
     pad('Run ID', 14),
     pad('Status', 11),
+    pad('Outcome', 11),
     pad('Trigger', 14),
     pad('Ctx', 4),
     pad('Phases', 8),
@@ -102,6 +108,7 @@ export async function historyCommand(opts) {
     const idx = String(i + 1);
     const runId = (entry.run_id || '—').slice(0, 12);
     const status = formatStatus(entry.status);
+    const outcome = buildRunOutcomeSummary(entry);
     const trigger = getRunTriggerLabel(entry.provenance);
     const ctx = isInheritable(entry) ? '✓' : '—';
     const phases = String(entry.phases_completed?.length || 0);
@@ -121,6 +128,7 @@ export async function historyCommand(opts) {
       pad(idx, 4),
       pad(runId, 14),
       pad(status, 11),
+      pad(outcome.label, 11),
       pad(trigger, 14),
       pad(ctx, 4),
       pad(phases, 8),
@@ -130,6 +138,10 @@ export async function historyCommand(opts) {
       pad(date, 20),
       pad(headline, 42),
     ].join(' '));
+
+    if (outcome.next_action) {
+      console.log(chalk.dim(`     next: ${truncateLine(outcome.next_action, 148)}`));
+    }
   });
 
   console.log(chalk.dim(`\n${entries.length} run(s) shown`));
@@ -176,3 +188,9 @@ function formatHeadline(headline) {
   if (normalized.length <= 40) return normalized;
   return `${normalized.slice(0, 39)}…`;
 }
+
+function truncateLine(value, max) {
+  if (typeof value !== 'string') return '';
+  if (value.length <= max) return value;
+  return `${value.slice(0, max - 1)}…`;
+}

package/src/commands/init.js

@@ -5,8 +5,9 @@ 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 { loadAllGovernedTemplates, loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS, buildSystemSpecContent } from '../lib/governed-templates.js';
+import { loadAllGovernedTemplates, loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
 import { normalizeWorkflowKit, VALID_PROMPT_TRANSPORTS } from '../lib/normalized-config.js';
+import { buildGovernedPlanningArtifacts, interpolateTemplateContent } from '../lib/planning-artifacts.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES_DIR = join(__dirname, '../templates');
@@ -47,24 +48,11 @@ function loadTemplates() {
   return templates;
 }
 
-function interpolateTemplateContent(contentTemplate, projectName) {
-  return contentTemplate.replaceAll('{{project_name}}', projectName);
-}
-
 function appendPromptOverride(basePrompt, override) {
   if (!override || !override.trim()) return basePrompt;
   return `${basePrompt}\n\n---\n\n## Project-Type-Specific Guidance\n\n${override.trim()}\n`;
 }
 
-function appendAcceptanceHints(baseMatrix, acceptanceHints) {
-  if (!Array.isArray(acceptanceHints) || acceptanceHints.length === 0) {
-    return baseMatrix;
-  }
-
-  const hintLines = acceptanceHints.map((hint) => `- [ ] ${hint}`).join('\n');
-  return `${baseMatrix}\n\n## Template Guidance\n${hintLines}\n`;
-}
-
 function findGitRoot(startDir) {
   let current = resolve(startDir);
   while (true) {
@@ -598,20 +586,6 @@ export async function resolveGovernedInitAnswers(opts, prompt = (questions) => i
   };
 }
 
-function generateWorkflowKitPlaceholder(artifact, projectName) {
-  const filename = basename(artifact.path);
-  const title = filename.replace(/\.[^.]+$/, '').replace(/[-_]/g, ' ');
-
-  if (artifact.semantics === 'section_check' && artifact.semantics_config?.required_sections?.length) {
-    const sections = artifact.semantics_config.required_sections
-      .map(s => `${s}\n\n(Content here.)\n`)
-      .join('\n');
-    return `# ${title} — ${projectName}\n\n${sections}`;
-  }
-
-  return `# ${title} — ${projectName}\n\n(Operator fills this in.)\n`;
-}
-
 function cloneJsonCompatible(value) {
   return value == null ? value : JSON.parse(JSON.stringify(value));
 }
@@ -653,29 +627,6 @@ function buildScaffoldConfigFromTemplate(template, localDevRuntime, workflowKitC
   };
 }
 
-const PHASE_DISPLAY_NAMES = Object.freeze({
-  qa: 'QA',
-});
-
-function formatPhaseDisplayName(phaseKey) {
-  if (PHASE_DISPLAY_NAMES[phaseKey]) {
-    return PHASE_DISPLAY_NAMES[phaseKey];
-  }
-  return phaseKey.replace(/_/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
-function buildRoadmapPhaseTable(routing, roles) {
-  const rows = Object.entries(routing).map(([phaseKey, phaseConfig]) => {
-    const phaseName = formatPhaseDisplayName(phaseKey);
-    const entryRole = phaseConfig.entry_role;
-    const role = roles[entryRole];
-    const goal = role?.mandate || phaseName;
-    const status = phaseKey === Object.keys(routing)[0] ? 'In progress' : 'Pending';
-    return `| ${phaseName} | ${goal} | ${status} |`;
-  });
-  return `| Phase | Goal | Status |\n|-------|------|--------|\n${rows.join('\n')}\n`;
-}
-
 function buildPlanningSummaryLines(template, workflowKitConfig) {
   const lines = [
     'PM_SIGNOFF.md / ROADMAP.md / SYSTEM_SPEC.md',
@@ -821,53 +772,20 @@ export function scaffoldGoverned(dir, projectName, projectId, templateId = 'gene
   }
 
   // Planning artifacts
-  writeFileSync(join(dir, '.planning', 'PM_SIGNOFF.md'), `# PM Signoff — ${projectName}\n\nApproved: NO\n\n> This scaffold starts blocked on purpose. Change this to \`Approved: YES\` only after a human reviews the planning artifacts and is ready to open the planning gate.\n\n## Discovery Checklist\n- [ ] Target user defined\n- [ ] Core pain point defined\n- [ ] Core workflow defined\n- [ ] MVP scope defined\n- [ ] Out-of-scope list defined\n- [ ] Success metric defined\n\n## Notes for team\n(PM and human add final kickoff notes here.)\n`);
-  writeFileSync(join(dir, '.planning', 'ROADMAP.md'), `# Roadmap — ${projectName}\n\n## Phases\n\n${buildRoadmapPhaseTable(routing, roles)}`);
-  writeFileSync(join(dir, '.planning', 'SYSTEM_SPEC.md'), buildSystemSpecContent(projectName, template.system_spec_overlay));
-  writeFileSync(join(dir, '.planning', 'IMPLEMENTATION_NOTES.md'), `# Implementation Notes — ${projectName}\n\n## Changes\n\n(Dev fills this during implementation)\n\n## Verification\n\n(Dev fills this during implementation)\n\n## Unresolved Follow-ups\n\n(Dev lists any known gaps, tech debt, or follow-up items here.)\n`);
-  const baseAcceptanceMatrix = `# Acceptance Matrix — ${projectName}\n\n| Req # | Requirement | Acceptance criteria | Test status | Last tested | Status |\n|-------|-------------|-------------------|-------------|-------------|--------|\n| (QA fills this from ROADMAP.md) | | | | | |\n`;
-  writeFileSync(
-    join(dir, '.planning', 'acceptance-matrix.md'),
-    appendAcceptanceHints(baseAcceptanceMatrix, template.acceptance_hints)
-  );
-  writeFileSync(join(dir, '.planning', 'ship-verdict.md'), `# Ship Verdict — ${projectName}\n\n## Verdict: PENDING\n\n## QA Summary\n\n(QA writes the final ship/no-ship assessment here.)\n\n## Open Blockers\n\n(List any blocking issues.)\n\n## Conditions\n\n(List any conditions for shipping.)\n`);
-  writeFileSync(join(dir, '.planning', 'RELEASE_NOTES.md'), `# Release Notes — ${projectName}\n\n## User Impact\n\n(QA fills this during the QA phase)\n\n## Verification Summary\n\n(QA fills this during the QA phase)\n\n## Upgrade Notes\n\n(QA fills this during the QA phase)\n\n## Known Issues\n\n(QA fills this during the QA phase)\n`);
-  for (const artifact of template.planning_artifacts) {
-    writeFileSync(
-      join(dir, '.planning', artifact.filename),
-      interpolateTemplateContent(artifact.content_template, projectName)
-    );
-  }
-
-  // Workflow-kit custom artifacts — only scaffold files from explicit workflow_kit config
-  // that are not already handled by the default scaffold above
-  if (scaffoldWorkflowKitConfig && scaffoldWorkflowKitConfig.phases && typeof scaffoldWorkflowKitConfig.phases === 'object') {
-    const defaultScaffoldPaths = new Set([
-      '.planning/PM_SIGNOFF.md',
-      '.planning/ROADMAP.md',
-      '.planning/SYSTEM_SPEC.md',
-      '.planning/IMPLEMENTATION_NOTES.md',
-      '.planning/acceptance-matrix.md',
-      '.planning/ship-verdict.md',
-      '.planning/RELEASE_NOTES.md',
-    ]);
-
-    for (const phaseConfig of Object.values(scaffoldWorkflowKitConfig.phases)) {
-      if (!Array.isArray(phaseConfig.artifacts)) continue;
-      for (const artifact of phaseConfig.artifacts) {
-        if (!artifact.path || defaultScaffoldPaths.has(artifact.path)) continue;
-        const absPath = join(dir, artifact.path);
-        if (existsSync(absPath)) continue;
-
-        // Ensure parent directory exists
-        const parentDir = dirname(absPath);
-        if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
-
-        // Generate placeholder content based on semantics type
-        const content = generateWorkflowKitPlaceholder(artifact, projectName);
-        writeFileSync(absPath, content);
-      }
+  for (const artifact of buildGovernedPlanningArtifacts({
+    projectName,
+    routing,
+    roles,
+    template,
+    workflowKitConfig: scaffoldWorkflowKitConfig,
+  })) {
+    const absPath = join(dir, artifact.path);
+    if (artifact.source === 'workflow_kit' && existsSync(absPath)) {
+      continue;
     }
+    const parentDir = dirname(absPath);
+    if (!existsSync(parentDir)) mkdirSync(parentDir, { recursive: true });
+    writeFileSync(absPath, artifact.content);
   }
 
   // TALK.md