convoke-agents 3.0.4 → 3.2.0

package/scripts/convoke-check.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+/**
+ * Convoke Check — Local CI mirror.
+ *
+ * Runs the same checks as .github/workflows/ci.yml so failures are caught
+ * before push. Intended for use in dev-story step 9 and manual pre-push.
+ *
+ * Steps (matching CI jobs):
+ *   1. Lint          (npm run lint)
+ *   2. Unit tests    (npm test)
+ *   3. Integration   (npm run test:integration)
+ *   4. Jest lib      (npx jest tests/lib/)
+ *   5. Coverage      (npm run test:coverage)  [--skip-coverage to omit]
+ *
+ * @module convoke-check
+ */
+
+const { execSync } = require('child_process');
+const { findProjectRoot } = require('./update/lib/utils');
+
+const STEPS = [
+  { name: 'Lint', cmd: 'npm run lint' },
+  { name: 'Unit tests', cmd: 'npm test' },
+  { name: 'Integration tests', cmd: 'npm run test:integration' },
+  { name: 'Jest lib tests', cmd: 'npx jest tests/lib/ --no-coverage' },
+  { name: 'Coverage', cmd: 'npm run test:coverage', skippable: true }
+];
+
+function run() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    console.log(`
+Usage: convoke-check [options]
+
+Runs the full CI-equivalent validation locally.
+
+Options:
+  --skip-coverage   Skip the coverage step (faster)
+  --help, -h        Show this help
+`);
+    return;
+  }
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.error('Error: Not in a Convoke project. Could not find _bmad/ directory.');
+    process.exit(1);
+  }
+
+  const skipCoverage = args.includes('--skip-coverage');
+  const results = [];
+  let failed = false;
+
+  for (const step of STEPS) {
+    if (step.skippable && skipCoverage) {
+      results.push({ name: step.name, status: 'skipped' });
+      continue;
+    }
+
+    console.log(`\n--- ${step.name} ---`);
+    try {
+      execSync(step.cmd, { cwd: projectRoot, stdio: 'inherit' });
+      results.push({ name: step.name, status: 'pass' });
+    } catch {
+      results.push({ name: step.name, status: 'FAIL' });
+      failed = true;
+      // Continue to run remaining steps so all failures are visible
+    }
+  }
+
+  // Summary
+  console.log('\n=== Convoke Check Summary ===');
+  for (const r of results) {
+    const icon = r.status === 'pass' ? 'PASS' : r.status === 'skipped' ? 'SKIP' : 'FAIL';
+    console.log(`  [${icon}] ${r.name}`);
+  }
+
+  if (failed) {
+    console.log('\nCI check FAILED. Fix the above issues before pushing.');
+    process.exit(1);
+  } else {
+    console.log('\nAll checks passed. Safe to push.');
+  }
+}
+
+run();

package/scripts/convoke-doctor.js

@@ -5,6 +5,11 @@ const path = require('path');
 const chalk = require('chalk');
 const yaml = require('js-yaml');
 const { findProjectRoot, getPackageVersion } = require('./update/lib/utils');
+// Note: parseCsvRow is loaded LAZILY inside loadSkillManifest() (ag-7-2 review patch).
+// Top-level require would crash the doctor on installs missing _team-factory/ — exactly
+// the broken-install case the doctor exists to diagnose. The lazy require is wrapped
+// in try/catch so a missing _team-factory degrades to "skip wrapper checks" instead
+// of crashing the entire CLI.
 
 /**
  * convoke-doctor — Diagnose common Convoke installation issues.
@@ -53,6 +58,10 @@ async function main() {
   });
 
   // 3. Per-module checks
+  // ag-7-2 (I31): load skill-manifest once for the wrapper-name lookup used by
+  // checkModuleSkillWrappers below. Empty Map is safe (falls back to verbatim).
+  const manifestMap = loadSkillManifest(projectRoot);
+
   for (const mod of modules) {
     const configCheck = checkModuleConfig(mod);
     checks.push(configCheck);
@@ -63,6 +72,13 @@ async function main() {
       if (Array.isArray(mod.config.workflows) && mod.config.workflows.length > 0) {
         checks.push(checkModuleWorkflows(mod));
       }
+      // ag-7-2 (I31): verify skill wrappers exist on disk for standalone-skill workflows.
+      // checkModuleSkillWrappers returns null if the module has no manifest entries
+      // (i.e., no standalone-skill workflows), so we filter those out.
+      if (Array.isArray(mod.config.workflows) && mod.config.workflows.length > 0) {
+        const wrapperCheck = checkModuleSkillWrappers(mod, projectRoot, manifestMap);
+        if (wrapperCheck) checks.push(wrapperCheck);
+      }
     }
   }
 
@@ -70,6 +86,7 @@ async function main() {
   checks.push(await checkOutputDir(projectRoot));
   checks.push(checkMigrationLock(projectRoot));
   checks.push(checkVersionConsistency(projectRoot, modules));
+  checks.push(...checkTaxonomy(projectRoot));
 
   printResults(checks);
 
@@ -249,6 +266,161 @@ function checkModuleWorkflows(mod) {
   return { name: label, passed: true, info: `${workflowNames.length} workflows present` };
 }
 
+/**
+ * Load skill-manifest.csv into a Map keyed by source path → canonicalId.
+ * The manifest is the authoritative source for wrapper directory names
+ * (canonicalId = the directory name under .claude/skills/).
+ *
+ * Returns an empty Map and logs a warning on any read/parse error — never throws,
+ * never fails the doctor. checkModuleSkillWrappers will fall back to verbatim
+ * workflow names for any source path not in the map.
+ *
+ * Closes I31 (ag-7-2).
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Map<string, string>} sourcePath → canonicalId
+ */
+function loadSkillManifest(projectRoot) {
+  const manifestPath = path.join(projectRoot, '_bmad/_config/skill-manifest.csv');
+  const map = new Map();
+
+  if (!fs.existsSync(manifestPath)) {
+    console.warn(chalk.yellow(`  ⚠ skill-manifest.csv not found at ${manifestPath}; skill wrapper checks will be skipped`));
+    return map;
+  }
+
+  // Lazy-load parseCsvRow from the optional _team-factory submodule.
+  // ag-7-2 review patch (Edge Case Hunter EH#1): if _team-factory/ is missing
+  // (e.g., user opted out of the team-factory module), the top-level require
+  // would crash the doctor before main() even runs — exactly the broken-install
+  // case the doctor exists to diagnose. Lazy + try/catch degrades cleanly.
+  let parseCsvRow;
+  try {
+    ({ parseCsvRow } = require('../_bmad/bme/_team-factory/lib/utils/csv-utils'));
+  } catch (_err) {
+    console.warn(chalk.yellow(`  ⚠ csv-utils unavailable (_team-factory submodule not installed); skill wrapper checks will be skipped`));
+    return map;
+  }
+
+  try {
+    const content = fs.readFileSync(manifestPath, 'utf8');
+    const lines = content.split('\n').filter(l => l.trim().length > 0);
+    if (lines.length === 0) return map;
+
+    // Parse header to find column indices
+    const header = parseCsvRow(lines[0]);
+    const canonicalIdIdx = header.indexOf('canonicalId');
+    const pathIdx = header.indexOf('path');
+    if (canonicalIdIdx === -1 || pathIdx === -1) {
+      console.warn(chalk.yellow(`  ⚠ skill-manifest.csv missing required columns (canonicalId, path); skill wrapper checks will be skipped`));
+      return map;
+    }
+
+    // Parse data rows
+    for (let i = 1; i < lines.length; i++) {
+      const fields = parseCsvRow(lines[i]);
+      if (fields.length <= Math.max(canonicalIdIdx, pathIdx)) continue;
+      const canonicalId = fields[canonicalIdIdx];
+      const sourcePath = fields[pathIdx];
+      if (canonicalId && sourcePath) {
+        map.set(sourcePath, canonicalId);
+      }
+    }
+  } catch (err) {
+    console.warn(chalk.yellow(`  ⚠ skill-manifest.csv parse error (${err.message}); skill wrapper checks will be skipped`));
+    return new Map();
+  }
+
+  return map;
+}
+
+/**
+ * Check that every standalone-skill workflow declared in a module's config.yaml
+ * has a corresponding skill wrapper at .claude/skills/{canonicalId}/SKILL.md.
+ *
+ * Manifest-as-opt-in semantics:
+ * - The skill-manifest.csv is the OPT-IN marker for "this workflow is a standalone
+ *   skill that needs a wrapper." Modules whose workflows are NOT in the manifest
+ *   (Vortex, Gyre, team-factory, ...) generate menu-patch workflows or agent
+ *   skills, NOT standalone wrappers — those modules are silently skipped here.
+ * - Only Enhance + Artifacts workflows are in the manifest today (after ag-7-2
+ *   Task 0 added the Enhance row).
+ * - If a module has SOME workflows in the manifest and SOME not, only the
+ *   in-manifest ones are checked.
+ *
+ * Resolution: source path `_bmad/bme/{mod.name}/workflows/{workflowName}/SKILL.md`
+ *             → manifest lookup → canonicalId is the wrapper directory name.
+ *
+ * Failures are aggregated into a single result (mirrors validateEnhanceModule
+ * pattern from Story 6.6) so the operator sees every missing wrapper at once.
+ *
+ * Returns null if the module has NO standalone-skill workflows (caller skips
+ * pushing null results into the checks array).
+ *
+ * Closes I31 (ag-7-2).
+ *
+ * @param {object} mod - Module descriptor from discoverModules()
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Map<string, string>} manifestMap - From loadSkillManifest()
+ * @returns {object|null} Doctor check result, or null if module has no standalone-skill workflows
+ */
+function checkModuleSkillWrappers(mod, projectRoot, manifestMap) {
+  const label = `${mod.name} skill wrappers`;
+  const workflowNames = mod.config.workflows;
+  const failures = [];
+  const checked = [];
+
+  // Build the source-path prefix from mod.dir (the absolute module directory
+  // discovered by discoverModules) relative to projectRoot. ag-7-2 review patch
+  // (Blind Hunter BH#1): the previous hardcoded `_bmad/bme/` prefix was correct
+  // for current callers (discoverModules only scans bme submodules) but would
+  // silently miss if a future caller scans a different team directory.
+  const moduleRelPath = path.relative(projectRoot, mod.dir);
+
+  for (const w of workflowNames) {
+    // Null/empty/object-without-name guard. ag-7-2 review patch (Edge Case
+    // Hunter EH#4 / Blind Hunter BH#7): a malformed config.yaml with
+    // `workflows: [null]` or `workflows: [{}]` would otherwise crash the doctor
+    // with a TypeError instead of producing a clean diagnostic.
+    if (!w) continue;
+    const wfName = typeof w === 'object' ? w.name : w;
+    if (!wfName || typeof wfName !== 'string') continue;
+
+    const sourcePath = `${moduleRelPath}/workflows/${wfName}/SKILL.md`;
+
+    // Manifest is opt-in: only workflows declared in skill-manifest.csv are
+    // standalone-skill workflows that need wrappers. Skip the rest silently.
+    const wrapperName = manifestMap.get(sourcePath);
+    if (!wrapperName) continue;
+
+    checked.push(wfName);
+    const wrapperPath = path.join(projectRoot, '.claude', 'skills', wrapperName, 'SKILL.md');
+    if (!fs.existsSync(wrapperPath)) {
+      failures.push(`Missing skill wrapper for ${wfName}: .claude/skills/${wrapperName}/SKILL.md`);
+    }
+  }
+
+  // If no workflows in this module are standalone skills, skip the check entirely.
+  if (checked.length === 0) {
+    return null;
+  }
+
+  if (failures.length > 0) {
+    return {
+      name: label,
+      passed: false,
+      error: failures.join('; '),
+      fix: 'Run convoke-update to regenerate skill wrappers'
+    };
+  }
+
+  return {
+    name: label,
+    passed: true,
+    info: `${checked.length} standalone-skill workflows have wrappers`
+  };
+}
+
 async function checkOutputDir(projectRoot) {
   const outputDir = path.join(projectRoot, '_bmad-output');
 
@@ -367,7 +539,134 @@ function printResults(checks) {
   console.log('');
 }
 
-main().catch(err => {
-  console.error(chalk.red(`Doctor failed: ${err.message}`));
-  process.exit(1);
-});
+// --- Taxonomy Validation ---
+
+/** Valid ID pattern: lowercase alphanumeric with optional dashes */
+const TAXONOMY_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Validate taxonomy configuration file.
+ * Returns array of check results (never throws).
+ * @param {string} projectRoot
+ * @returns {Array<{name: string, passed: boolean, error?: string, warning?: string, fix?: string, info?: string}>}
+ */
+function checkTaxonomy(projectRoot) {
+  const results = [];
+  const configPath = path.join(projectRoot, '_bmad', '_config', 'taxonomy.yaml');
+
+  // Check 1: file exists
+  if (!fs.existsSync(configPath)) {
+    results.push({
+      name: 'Taxonomy: file exists',
+      passed: false,
+      warning: 'taxonomy.yaml not found at _bmad/_config/taxonomy.yaml',
+      fix: 'Run convoke-migrate-artifacts or convoke-update to create it'
+    });
+    return results;
+  }
+  results.push({ name: 'Taxonomy: file exists', passed: true });
+
+  // Check 2: YAML parseable
+  let config;
+  try {
+    config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+  } catch (err) {
+    results.push({
+      name: 'Taxonomy: valid YAML',
+      passed: false,
+      error: `Invalid YAML in taxonomy.yaml: ${err.message}`,
+      fix: 'Fix the YAML syntax in _bmad/_config/taxonomy.yaml'
+    });
+    return results;
+  }
+  results.push({ name: 'Taxonomy: valid YAML', passed: true });
+
+  if (!config || typeof config !== 'object') {
+    results.push({ name: 'Taxonomy: structure', passed: false, error: 'taxonomy.yaml is empty or not an object' });
+    return results;
+  }
+
+  // Check 3: required sections
+  const issues = [];
+  if (!config.initiatives || !Array.isArray(config.initiatives.platform)) {
+    issues.push('Missing initiatives.platform (must be an array)');
+  }
+  if (!config.initiatives || !Array.isArray(config.initiatives.user)) {
+    issues.push('Missing initiatives.user (must be an array)');
+  }
+  if (!Array.isArray(config.artifact_types)) {
+    issues.push('Missing artifact_types (must be an array)');
+  }
+
+  if (issues.length > 0) {
+    results.push({ name: 'Taxonomy: structure', passed: false, error: issues.join('; ') });
+    return results;
+  }
+  results.push({ name: 'Taxonomy: structure', passed: true });
+
+  // Check 4: ID format validation
+  const allPlatform = config.initiatives.platform || [];
+  const allUser = config.initiatives.user || [];
+  const allTypes = config.artifact_types || [];
+  const invalidIds = [];
+
+  for (const id of [...allPlatform, ...allUser]) {
+    if (!TAXONOMY_ID_PATTERN.test(id)) {
+      invalidIds.push(`initiative "${id}"`);
+    }
+  }
+  for (const id of allTypes) {
+    if (!TAXONOMY_ID_PATTERN.test(id)) {
+      invalidIds.push(`artifact_type "${id}"`);
+    }
+  }
+
+  if (invalidIds.length > 0) {
+    results.push({
+      name: 'Taxonomy: ID format',
+      passed: false,
+      error: `Invalid IDs (must be lowercase alphanumeric with dashes): ${invalidIds.join(', ')}`
+    });
+  } else {
+    results.push({ name: 'Taxonomy: ID format', passed: true });
+  }
+
+  // Check 5: duplicates between platform and user
+  const platformSet = new Set(allPlatform);
+  const duplicates = allUser.filter(id => platformSet.has(id));
+  if (duplicates.length > 0) {
+    results.push({
+      name: 'Taxonomy: no duplicates',
+      passed: false,
+      error: `Duplicate IDs in both platform and user sections: ${duplicates.join(', ')}`,
+      fix: 'Remove duplicates from the user section (they are already in platform)'
+    });
+  } else {
+    results.push({ name: 'Taxonomy: no duplicates', passed: true });
+  }
+
+  // Check 6: collisions between initiatives and artifact types
+  const allInitiatives = new Set([...allPlatform, ...allUser]);
+  const collisions = allTypes.filter(t => allInitiatives.has(t));
+  if (collisions.length > 0) {
+    results.push({
+      name: 'Taxonomy: no collisions',
+      passed: false,
+      error: `IDs used as both initiative and artifact type: ${collisions.join(', ')}`,
+      fix: 'Rename the colliding IDs to be unique across sections'
+    });
+  } else {
+    results.push({ name: 'Taxonomy: no collisions', passed: true });
+  }
+
+  return results;
+}
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error(chalk.red(`Doctor failed: ${err.message}`));
+    process.exit(1);
+  });
+}
+
+module.exports = { checkTaxonomy, loadSkillManifest, checkModuleSkillWrappers };