agentxchain 0.8.8 → 2.1.1

package/src/commands/template-list.js

@@ -0,0 +1,33 @@
+import chalk from 'chalk';
+import { loadAllGovernedTemplates, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
+
+export function templateListCommand(opts) {
+  if (opts.json) {
+    const templates = loadAllGovernedTemplates();
+    const output = templates.map((t) => ({
+      id: t.id,
+      display_name: t.display_name,
+      description: t.description,
+      planning_artifacts: (t.planning_artifacts || []).map((a) => a.filename),
+      prompt_overrides: Object.keys(t.prompt_overrides || {}),
+      acceptance_hints: t.acceptance_hints || [],
+    }));
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold('\n  Available governed templates:\n'));
+  const templates = loadAllGovernedTemplates();
+  for (const t of templates) {
+    const artifacts = (t.planning_artifacts || []).map((a) => a.filename);
+    console.log(`  ${chalk.cyan(t.id)} — ${t.description}`);
+    if (artifacts.length > 0) {
+      console.log(`    Planning artifacts: ${artifacts.join(', ')}`);
+    }
+    if (t.prompt_overrides && Object.keys(t.prompt_overrides).length > 0) {
+      console.log(`    Prompt overrides: ${Object.keys(t.prompt_overrides).join(', ')}`);
+    }
+    console.log('');
+  }
+  console.log(chalk.dim(`  Usage: agentxchain template set <id>\n`));
+}

package/src/commands/template-set.js

@@ -0,0 +1,279 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import chalk from 'chalk';
+import { CONFIG_FILE } from '../lib/config.js';
+import { loadGovernedTemplate, VALID_GOVERNED_TEMPLATE_IDS } from '../lib/governed-templates.js';
+
+const LEDGER_PATH = '.agentxchain/decision-ledger.jsonl';
+const PROMPT_OVERRIDE_SEPARATOR = '## Project-Type-Specific Guidance';
+const ACCEPTANCE_HINTS_SEPARATOR = '## Template Guidance';
+
+function interpolateTemplateContent(contentTemplate, projectName) {
+  return contentTemplate.replaceAll('{{project_name}}', projectName);
+}
+
+function appendJsonl(root, relPath, entry) {
+  const filePath = join(root, relPath);
+  mkdirSync(dirname(filePath), { recursive: true });
+  const line = JSON.stringify(entry) + '\n';
+  writeFileSync(filePath, line, { flag: 'a' });
+}
+
+export async function templateSetCommand(templateId, opts) {
+  const root = process.cwd();
+  const governedWorkspacePath = join(root, '.agentxchain');
+
+  // ── Validate governed project ──────────────────────────────────────────
+  const configPath = join(root, CONFIG_FILE);
+  if (!existsSync(configPath)) {
+    console.error(chalk.red('  Error: No agentxchain.json found.'));
+    process.exit(1);
+  }
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    console.error(chalk.red(`  Error: Failed to read agentxchain.json: ${err.message}`));
+    process.exit(1);
+  }
+
+  if (config.schema_version !== '1.0' && config.schema_version !== '1.1') {
+    console.error(chalk.red('  Error: This is not a governed project. template set requires a governed project (schema_version 1.0 or 1.1).'));
+    process.exit(1);
+  }
+
+  if (!existsSync(governedWorkspacePath)) {
+    console.error(chalk.red('  Error: Governed workspace missing. template set requires an existing .agentxchain/ directory.'));
+    process.exit(1);
+  }
+
+  // ── Validate template ID ──────────────────────────────────────────────
+  if (!VALID_GOVERNED_TEMPLATE_IDS.includes(templateId)) {
+    console.error(chalk.red(`  Error: Unknown template "${templateId}".`));
+    console.error(`  Available templates: ${VALID_GOVERNED_TEMPLATE_IDS.join(', ')}`);
+    process.exit(1);
+  }
+
+  // ── Same template = no-op ─────────────────────────────────────────────
+  const previousTemplate = config.template || 'generic';
+  if (previousTemplate === templateId) {
+    console.log(chalk.green(`  Already set to "${templateId}". No changes.`));
+    process.exit(0);
+  }
+
+  // ── Load manifest ─────────────────────────────────────────────────────
+  const manifest = loadGovernedTemplate(templateId);
+  const projectName = config.project?.name || 'Untitled';
+
+  // ── Build mutation plan ───────────────────────────────────────────────
+  const plan = {
+    config_update: true,
+    files_created: [],
+    files_skipped: [],
+    prompts_appended: [],
+    prompts_existing_guidance: [],
+    prompts_missing_paths: [],
+    prompts_missing_files: [],
+    acceptance_hints_status: 'none',
+  };
+
+  // Planning artifacts
+  for (const artifact of manifest.planning_artifacts || []) {
+    const artifactPath = join(root, '.planning', artifact.filename);
+    if (existsSync(artifactPath)) {
+      plan.files_skipped.push(artifact.filename);
+    } else {
+      plan.files_created.push(artifact.filename);
+    }
+  }
+
+  // Prompt overrides
+  const promptOverrides = manifest.prompt_overrides || {};
+  for (const roleId of Object.keys(promptOverrides)) {
+    const promptRelPath = config.prompts?.[roleId];
+    if (!promptRelPath) {
+      plan.prompts_missing_paths.push(roleId);
+      continue;
+    }
+    const promptPath = join(root, promptRelPath);
+    if (!existsSync(promptPath)) {
+      plan.prompts_missing_files.push({
+        role_id: roleId,
+        path: promptRelPath,
+      });
+      continue;
+    }
+    const content = readFileSync(promptPath, 'utf8');
+    if (content.includes(PROMPT_OVERRIDE_SEPARATOR)) {
+      plan.prompts_existing_guidance.push(roleId);
+    } else {
+      plan.prompts_appended.push(roleId);
+    }
+  }
+
+  // Acceptance hints
+  const acceptanceMatrixPath = join(root, '.planning', 'acceptance-matrix.md');
+  if (Array.isArray(manifest.acceptance_hints) && manifest.acceptance_hints.length > 0) {
+    if (existsSync(acceptanceMatrixPath)) {
+      const matrixContent = readFileSync(acceptanceMatrixPath, 'utf8');
+      if (matrixContent.includes(ACCEPTANCE_HINTS_SEPARATOR)) {
+        plan.acceptance_hints_status = 'existing_guidance';
+      } else {
+        plan.acceptance_hints_status = 'append';
+      }
+    } else {
+      plan.acceptance_hints_status = 'missing_file';
+    }
+  }
+
+  // ── Dry run: print plan and exit ──────────────────────────────────────
+  if (opts.dryRun) {
+    console.log(chalk.bold(`\n  Template: ${previousTemplate} → ${templateId}\n`));
+    console.log('  Config:');
+    console.log(`    agentxchain.json: template field will be updated`);
+    console.log('\n  Planning artifacts:');
+    for (const f of plan.files_created) {
+      console.log(`    .planning/${f}: ${chalk.green('WILL CREATE')}`);
+    }
+    for (const f of plan.files_skipped) {
+      console.log(`    .planning/${f}: ${chalk.dim('EXISTS (skip)')}`);
+    }
+    if (plan.files_created.length === 0 && plan.files_skipped.length === 0) {
+      console.log(`    ${chalk.dim('(none)')}`);
+    }
+    console.log('\n  Prompts:');
+    for (const r of plan.prompts_appended) {
+      const p = config.prompts?.[r] || `<unknown path for ${r}>`;
+      console.log(`    ${p}: ${chalk.green('WILL APPEND override')}`);
+    }
+    for (const r of plan.prompts_existing_guidance) {
+      const p = config.prompts?.[r] || `<unknown path for ${r}>`;
+      console.log(`    ${p}: ${chalk.dim('ALREADY HAS guidance (skip)')}`);
+    }
+    for (const r of plan.prompts_missing_paths) {
+      console.log(`    <no configured path for ${r}>: ${chalk.yellow('NO PROMPT PATH (skip)')}`);
+    }
+    for (const prompt of plan.prompts_missing_files) {
+      console.log(`    ${prompt.path}: ${chalk.yellow('MISSING FILE (skip)')}`);
+    }
+    if (
+      plan.prompts_appended.length === 0
+      && plan.prompts_existing_guidance.length === 0
+      && plan.prompts_missing_paths.length === 0
+      && plan.prompts_missing_files.length === 0
+    ) {
+      console.log(`    ${chalk.dim('(none)')}`);
+    }
+    console.log('\n  Acceptance hints:');
+    if (plan.acceptance_hints_status === 'append') {
+      console.log(`    .planning/acceptance-matrix.md: ${chalk.green('WILL APPEND template guidance')}`);
+    } else if (plan.acceptance_hints_status === 'existing_guidance') {
+      console.log(`    .planning/acceptance-matrix.md: ${chalk.dim('ALREADY HAS guidance (skip)')}`);
+    } else if (plan.acceptance_hints_status === 'missing_file') {
+      console.log(`    .planning/acceptance-matrix.md: ${chalk.yellow('MISSING FILE (skip)')}`);
+    } else {
+      console.log(`    ${chalk.dim('(none)')}`);
+    }
+    console.log(chalk.dim('\n  No changes written. Use without --dry-run to apply.\n'));
+    process.exit(0);
+  }
+
+  // ── Confirmation prompt ───────────────────────────────────────────────
+  if (!opts.yes) {
+    console.log(chalk.bold(`\n  Template: ${previousTemplate} → ${templateId}`));
+    console.log(`  ${plan.files_created.length} files to create, ${plan.prompts_appended.length} prompts to append.\n`);
+    const readline = await import('node:readline');
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => {
+      rl.question('  Apply changes? [y/N] ', resolve);
+    });
+    rl.close();
+    if (answer.trim().toLowerCase() !== 'y') {
+      console.log(chalk.dim('  Aborted.'));
+      process.exit(0);
+    }
+  }
+
+  // ── Execute mutations ─────────────────────────────────────────────────
+
+  // 1. Update config
+  config.template = templateId;
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+
+  // 2. Create planning artifacts
+  mkdirSync(join(root, '.planning'), { recursive: true });
+  for (const artifact of manifest.planning_artifacts || []) {
+    const artifactPath = join(root, '.planning', artifact.filename);
+    if (!existsSync(artifactPath)) {
+      writeFileSync(
+        artifactPath,
+        interpolateTemplateContent(artifact.content_template, projectName)
+      );
+    }
+  }
+
+  // 3. Append prompt overrides
+  for (const roleId of plan.prompts_appended) {
+    const promptPath = join(root, config.prompts[roleId]);
+    const content = readFileSync(promptPath, 'utf8');
+    const override = promptOverrides[roleId];
+    const appended = `${content}\n\n---\n\n${PROMPT_OVERRIDE_SEPARATOR}\n\n${override.trim()}\n`;
+    writeFileSync(promptPath, appended);
+  }
+  // Warn about skipped prompts when switching templates
+  for (const roleId of plan.prompts_existing_guidance) {
+    console.log(chalk.yellow(`  Warning: Prompt for ${roleId} already has project-type guidance. Skipping. Edit manually if you want the new template's guidance.`));
+  }
+  for (const roleId of plan.prompts_missing_paths) {
+    console.log(chalk.yellow(`  Warning: Prompt for ${roleId} has no configured path in agentxchain.json. Skipping template guidance.`));
+  }
+  for (const prompt of plan.prompts_missing_files) {
+    console.log(chalk.yellow(`  Warning: Prompt file for ${prompt.role_id} not found at ${prompt.path}. Skipping template guidance.`));
+  }
+
+  // 4. Append acceptance hints
+  if (plan.acceptance_hints_status === 'append' && existsSync(acceptanceMatrixPath)) {
+    const matrixContent = readFileSync(acceptanceMatrixPath, 'utf8');
+    const hintLines = manifest.acceptance_hints.map((hint) => `- [ ] ${hint}`).join('\n');
+    const appended = `${matrixContent}\n\n${ACCEPTANCE_HINTS_SEPARATOR}\n\n${hintLines}\n`;
+    writeFileSync(acceptanceMatrixPath, appended);
+  } else if (plan.acceptance_hints_status === 'missing_file') {
+    console.log(chalk.yellow('  Warning: .planning/acceptance-matrix.md not found. Skipping template guidance hints.'));
+  }
+
+  // 5. Decision ledger
+  const ledgerEntry = {
+    type: 'template_set',
+    timestamp: new Date().toISOString(),
+    previous_template: previousTemplate,
+    new_template: templateId,
+    files_created: plan.files_created,
+    files_skipped: plan.files_skipped,
+    prompts_appended: plan.prompts_appended,
+    prompts_skipped: [
+      ...plan.prompts_existing_guidance,
+      ...plan.prompts_missing_paths,
+      ...plan.prompts_missing_files.map((prompt) => prompt.role_id),
+    ],
+    prompt_missing_paths: plan.prompts_missing_paths,
+    prompt_missing_files: plan.prompts_missing_files,
+    acceptance_hints_appended: plan.acceptance_hints_status === 'append',
+    acceptance_hints_skipped_reason: plan.acceptance_hints_status === 'append' ? null : plan.acceptance_hints_status,
+    operator: 'human',
+  };
+  appendJsonl(root, LEDGER_PATH, ledgerEntry);
+
+  // ── Summary ───────────────────────────────────────────────────────────
+  console.log(chalk.green(`\n  Template set to "${templateId}".`));
+  if (plan.files_created.length > 0) {
+    console.log(`  Created: ${plan.files_created.map(f => `.planning/${f}`).join(', ')}`);
+  }
+  if (plan.prompts_appended.length > 0) {
+    console.log(`  Appended guidance to: ${plan.prompts_appended.join(', ')} prompts`);
+  }
+  if (plan.acceptance_hints_status === 'append') {
+    console.log(`  Appended template guidance to acceptance-matrix.md`);
+  }
+  console.log('');
+}

package/src/commands/validate.js

@@ -1,28 +1,37 @@
 import chalk from 'chalk';
-import { loadConfig } from '../lib/config.js';
-import { validateProject } from '../lib/validation.js';
+import { loadConfig, loadProjectContext } from '../lib/config.js';
+import { validateGovernedProject, validateProject } from '../lib/validation.js';
 
 export async function validateCommand(opts) {
-  const result = loadConfig();
-  if (!result) {
+  const context = loadProjectContext();
+  if (!context) {
     console.log(chalk.red('No agentxchain.json found. Run `agentxchain init` first.'));
     process.exit(1);
   }
 
-  const { root, config } = result;
   const mode = opts.mode || 'full';
-  const validation = validateProject(root, config, {
-    mode,
-    expectedAgent: opts.agent || null
-  });
+  const validation = context.config.protocol_mode === 'governed'
+    ? validateGovernedProject(context.root, context.rawConfig, context.config, {
+        mode,
+        expectedAgent: opts.agent || null,
+      })
+    : validateProject(context.root, loadConfig()?.config || context.rawConfig, {
+        mode,
+        expectedAgent: opts.agent || null,
+      });
 
   if (opts.json) {
-    console.log(JSON.stringify(validation, null, 2));
+    console.log(JSON.stringify({
+      ...validation,
+      protocol_mode: context.config.protocol_mode,
+      version: context.version,
+    }, null, 2));
   } else {
     console.log('');
     console.log(chalk.bold(`  AgentXchain Validate (${mode})`));
     console.log(chalk.dim('  ' + '─'.repeat(44)));
-    console.log(chalk.dim(`  Root: ${root}`));
+    console.log(chalk.dim(`  Root: ${context.root}`));
+    console.log(chalk.dim(`  Protocol: ${context.config.protocol_mode} (v${context.version})`));
     console.log('');
 
     if (validation.ok) {

package/src/commands/verify.js

@@ -0,0 +1,71 @@
+import chalk from 'chalk';
+import { resolve } from 'node:path';
+import { verifyProtocolConformance } from '../lib/protocol-conformance.js';
+
+export async function verifyProtocolCommand(opts) {
+  const target = opts.target ? resolve(opts.target) : process.cwd();
+  const requestedTier = Number.parseInt(String(opts.tier || '1'), 10);
+  const format = opts.format || 'text';
+
+  let result;
+  try {
+    result = verifyProtocolConformance({
+      targetRoot: target,
+      requestedTier,
+      surface: opts.surface || null,
+    });
+  } catch (error) {
+    if (format === 'json') {
+      console.log(JSON.stringify({
+        overall: 'error',
+        message: error.message,
+      }, null, 2));
+    } else {
+      console.log(chalk.red(`Protocol verification failed: ${error.message}`));
+    }
+    process.exit(2);
+  }
+
+  if (format === 'json') {
+    console.log(JSON.stringify(result.report, null, 2));
+  } else {
+    printProtocolReport(result.report);
+  }
+
+  process.exit(result.exitCode);
+}
+
+function printProtocolReport(report) {
+  console.log('');
+  console.log(chalk.bold('  AgentXchain Protocol Conformance'));
+  console.log(chalk.dim('  ' + '─'.repeat(44)));
+  console.log(chalk.dim(`  Target: ${report.target_root}`));
+  console.log(chalk.dim(`  Implementation: ${report.implementation}`));
+  console.log(chalk.dim(`  Tier requested: ${report.tier_requested}`));
+  console.log('');
+
+  const overallLabel = report.overall === 'pass'
+    ? chalk.green('PASS')
+    : report.overall === 'fail'
+      ? chalk.red('FAIL')
+      : chalk.red('ERROR');
+  console.log(`  Overall: ${overallLabel}`);
+
+  for (const [tierKey, tier] of Object.entries(report.results)) {
+    const label = tier.status === 'pass'
+      ? chalk.green('pass')
+      : tier.status === 'skipped'
+        ? chalk.yellow('skipped')
+        : chalk.red(tier.status);
+    console.log(`  ${tierKey}: ${label} (${tier.fixtures_passed}/${tier.fixtures_run} passed)`);
+
+    for (const failure of tier.failures || []) {
+      console.log(chalk.red(`    - ${failure.fixture_id}: ${failure.message}`));
+    }
+    for (const error of tier.errors || []) {
+      console.log(chalk.red(`    - ${error.fixture_id}: ${error.message}`));
+    }
+  }
+
+  console.log('');
+}