convoke-agents 3.0.4 → 3.2.0

package/scripts/update/lib/refresh-installation.js

@@ -3,9 +3,10 @@
 const fs = require('fs-extra');
 const path = require('path');
 const yaml = require('js-yaml');
-const { getPackageVersion } = require('./utils');
+const YAML = require('yaml'); // Comment-preserving YAML library (ag-7-1: I29). Use for WRITE sites that need to preserve comments. js-yaml stays for read-only consumers.
+const { getPackageVersion, assertVersion } = require('./utils');
 const configMerger = require('./config-merger');
-const { AGENTS, AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, USER_GUIDES, GYRE_AGENTS, GYRE_AGENT_FILES, GYRE_AGENT_IDS, GYRE_WORKFLOW_NAMES } = require('./agent-registry');
+const { AGENTS, AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, USER_GUIDES, GYRE_AGENTS, GYRE_AGENT_FILES, GYRE_AGENT_IDS, GYRE_WORKFLOW_NAMES, EXTRA_BME_AGENTS } = require('./agent-registry');
 
 /**
  * Refresh Installation for Convoke
@@ -91,6 +92,34 @@ async function refreshInstallation(projectRoot, options = {}) {
     if (verbose) console.log('    Skipped workflow copy (dev environment)');
   }
 
+  // 2b1. Standalone bme submodule trees (e.g., _team-factory)
+  // Each EXTRA_BME_AGENTS entry references a submodule directory under _bmad/bme/
+  // that must be copied wholesale so the agent file, workflows, lib code, and config travel together.
+  // Mirrors the workflow loop pattern (2-step remove-then-copy) so renamed/deleted files
+  // in the package don't survive in the user install as stale leftovers.
+  const copiedExtraSubmodules = new Set();
+  if (!isSameRoot) {
+    for (const agent of EXTRA_BME_AGENTS) {
+      if (copiedExtraSubmodules.has(agent.submodule)) continue;
+      copiedExtraSubmodules.add(agent.submodule);
+      const srcDir = path.join(packageRoot, '_bmad', 'bme', agent.submodule);
+      const destDir = path.join(projectRoot, '_bmad', 'bme', agent.submodule);
+      if (fs.existsSync(srcDir)) {
+        // Remove existing destination first to clear stale files
+        // (e.g., renamed/deleted workflow steps from previous versions)
+        if (fs.existsSync(destDir)) {
+          await fs.remove(destDir);
+        }
+        await fs.copy(srcDir, destDir, { overwrite: true });
+        changes.push(`Refreshed standalone bme submodule: ${agent.submodule}`);
+        if (verbose) console.log(`    Refreshed standalone bme submodule: ${agent.submodule}`);
+      }
+    }
+  } else {
+    changes.push('Skipped standalone bme submodule copy (dev environment — files already in place)');
+    if (verbose) console.log('    Skipped standalone bme submodule copy (dev environment)');
+  }
+
   // 2a. Enhance module — read config, copy directory tree, patch target agent menu
   const packageEnhance = path.join(packageRoot, '_bmad', 'bme', '_enhance');
   const enhanceConfigPath = path.join(packageEnhance, 'config.yaml');
@@ -115,12 +144,17 @@ async function refreshInstallation(projectRoot, options = {}) {
 
     if (!isSameRoot) {
       await fs.copy(packageEnhance, targetEnhance, { overwrite: true });
-      // Stamp enhance config version to match package version
+      // Stamp enhance config version to match package version (ag-7-1: I30 + I29).
+      // Uses comment-preserving YAML.parseDocument so the doc comments survive.
       const targetEnhanceConfig = path.join(targetEnhance, 'config.yaml');
       if (fs.existsSync(targetEnhanceConfig)) {
-        const ecContent = yaml.load(fs.readFileSync(targetEnhanceConfig, 'utf8'));
-        ecContent.version = version;
-        fs.writeFileSync(targetEnhanceConfig, yaml.dump(ecContent, { lineWidth: -1 }), 'utf8');
+        assertVersion(version, 'enhance');
+        const ecDoc = YAML.parseDocument(fs.readFileSync(targetEnhanceConfig, 'utf8'));
+        if (ecDoc.errors && ecDoc.errors.length > 0) {
+          throw new Error(`Refresh: cannot parse Enhance config.yaml: ${ecDoc.errors[0].message}`);
+        }
+        ecDoc.set('version', version);
+        fs.writeFileSync(targetEnhanceConfig, ecDoc.toString({ lineWidth: 0 }), 'utf8');
       }
       changes.push('Refreshed Enhance module: _bmad/bme/_enhance/');
       if (verbose) console.log('    Refreshed Enhance module: _bmad/bme/_enhance/');
@@ -189,6 +223,61 @@ async function refreshInstallation(projectRoot, options = {}) {
     }
   }
 
+  // 2c. Artifacts module — read config, copy directory tree, generate skill wrappers
+  // Workflow-only submodule (no agents). Workflows are STANDALONE: each gets a Claude Code
+  // skill wrapper but NO menu patch. The `standalone: true` flag in the workflow entry is
+  // the discriminator — workflows without it are NOT supported in this module today (Story 6.6).
+  const packageArtifacts = path.join(packageRoot, '_bmad', 'bme', '_artifacts');
+  const artifactsConfigPath = path.join(packageArtifacts, 'config.yaml');
+
+  let artifactsConfig = null;
+  if (fs.existsSync(artifactsConfigPath)) {
+    try {
+      artifactsConfig = yaml.load(fs.readFileSync(artifactsConfigPath, 'utf8'));
+    } catch (err) {
+      const msg = `Artifacts config.yaml parse error: ${err.message} — skipping Artifacts installation`;
+      changes.push(msg);
+      if (verbose) console.log(`    ⚠ ${msg}`);
+    }
+  } else {
+    changes.push('Artifacts config.yaml not found — skipping Artifacts installation');
+    if (verbose) console.log('    ⚠ Artifacts config.yaml not found — skipping Artifacts installation');
+  }
+
+  if (artifactsConfig) {
+    // Copy _artifacts/ directory tree
+    const targetArtifacts = path.join(projectRoot, '_bmad', 'bme', '_artifacts');
+
+    if (!isSameRoot) {
+      // Remove existing destination first to clear stale files
+      if (fs.existsSync(targetArtifacts)) {
+        await fs.remove(targetArtifacts);
+      }
+      await fs.copy(packageArtifacts, targetArtifacts, { overwrite: true });
+      // Stamp artifacts config version to match package version (ag-7-1: I30 + I29).
+      // Uses comment-preserving YAML.parseDocument so the standalone:true doc comments survive.
+      const targetArtifactsConfig = path.join(targetArtifacts, 'config.yaml');
+      if (fs.existsSync(targetArtifactsConfig)) {
+        assertVersion(version, 'artifacts');
+        const acDoc = YAML.parseDocument(fs.readFileSync(targetArtifactsConfig, 'utf8'));
+        if (acDoc.errors && acDoc.errors.length > 0) {
+          throw new Error(`Refresh: cannot parse Artifacts config.yaml: ${acDoc.errors[0].message}`);
+        }
+        acDoc.set('version', version);
+        fs.writeFileSync(targetArtifactsConfig, acDoc.toString({ lineWidth: 0 }), 'utf8');
+      }
+      changes.push('Refreshed Artifacts module: _bmad/bme/_artifacts/');
+      if (verbose) console.log('    Refreshed Artifacts module: _bmad/bme/_artifacts/');
+    } else {
+      changes.push('Skipped Artifacts copy (dev environment — files already in place)');
+      if (verbose) console.log('    Skipped Artifacts copy (dev environment)');
+    }
+
+    // Skill wrapper generation for each workflow happens later in section 6d,
+    // after skillsDir is defined (mirrors Enhance pattern: config/copy here, skill
+    // wrappers in section 6c after agent skills are generated).
+  }
+
   // 2d. Gyre module — copy agents, workflows, contracts, config
   const packageGyre = path.join(packageRoot, '_bmad', 'bme', '_gyre');
   const targetGyre = path.join(projectRoot, '_bmad', 'bme', '_gyre');
@@ -257,6 +346,7 @@ async function refreshInstallation(projectRoot, options = {}) {
         agents: GYRE_AGENT_IDS,
         workflows: GYRE_WORKFLOW_NAMES
       };
+      assertVersion(version, 'config-merger:gyre'); // ag-7-1: defense-in-depth before mergeConfig
       const gyreConfigMerged = await configMerger.mergeConfig(gyreConfigTarget, version, gyreUpdates);
       await configMerger.writeConfig(gyreConfigTarget, gyreConfigMerged);
       changes.push(`Updated Gyre config.yaml to v${version}`);
@@ -282,6 +372,7 @@ async function refreshInstallation(projectRoot, options = {}) {
     workflows: WORKFLOW_NAMES
   };
 
+  assertVersion(version, 'config-merger:vortex'); // ag-7-1: defense-in-depth before mergeConfig
   const merged = await configMerger.mergeConfig(configPath, version, updates);
   await configMerger.writeConfig(configPath, merged);
   changes.push(`Updated config.yaml to v${version}`);
@@ -383,16 +474,46 @@ async function refreshInstallation(projectRoot, options = {}) {
     ].map(csvEscape).join(',');
   }
 
+  // Row builder for standalone bme agents (e.g., team-factory) — submodule path differs from team agents
+  function buildExtraBmeAgentRow610(a) {
+    const p = a.persona;
+    return [
+      csvEscape(a.name),
+      csvEscape(''),
+      csvEscape(a.title),
+      csvEscape(a.icon),
+      csvEscape(''),
+      csvEscape(p.role),
+      csvEscape(p.identity),
+      csvEscape(p.communication_style),
+      csvEscape(p.expertise),
+      csvEscape('bme'),
+      csvEscape(`_bmad/bme/${a.submodule}/agents/${a.id}.md`),
+      csvEscape(`bmad-agent-bme-${a.id}`),
+    ].join(',');
+  }
+
+  function buildExtraBmeAgentRowLegacy(a) {
+    const p = a.persona;
+    return [
+      a.id, a.name, a.title, a.icon,
+      p.role, p.identity, p.communication_style, p.expertise,
+      'bme', `_bmad/bme/${a.submodule}/agents/${a.id}.md`,
+    ].map(csvEscape).join(',');
+  }
+
   let bmeRows;
   if (isV610) {
     bmeRows = [
       ...AGENTS.map(a => buildAgentRow610(a, '_vortex')),
       ...GYRE_AGENTS.map(a => buildAgentRow610(a, '_gyre')),
+      ...EXTRA_BME_AGENTS.map(buildExtraBmeAgentRow610),
     ];
   } else {
     bmeRows = [
       ...AGENTS.map(a => buildAgentRowLegacy(a, '_vortex')),
       ...GYRE_AGENTS.map(a => buildAgentRowLegacy(a, '_gyre')),
+      ...EXTRA_BME_AGENTS.map(buildExtraBmeAgentRowLegacy),
     ];
   }
 
@@ -446,6 +567,7 @@ async function refreshInstallation(projectRoot, options = {}) {
   const currentSkillDirs = new Set([
     ...AGENTS.map(a => `bmad-agent-bme-${a.id}`),
     ...GYRE_AGENTS.map(a => `bmad-agent-bme-${a.id}`),
+    ...EXTRA_BME_AGENTS.map(a => `bmad-agent-bme-${a.id}`),
   ]);
   if (fs.existsSync(skillsDir)) {
     const existingSkills = (await fs.readdir(skillsDir)).filter(d => d.startsWith('bmad-agent-bme-'));
@@ -507,6 +629,31 @@ You must fully embody this agent's persona and follow all activation instruction
     if (verbose) console.log(`    Refreshed skill: bmad-agent-bme-${agent.id}/SKILL.md`);
   }
 
+  // 6b1. Generate .claude/skills/ for standalone bme agents (e.g., team-factory)
+  for (const agent of EXTRA_BME_AGENTS) {
+    const skillDir = path.join(skillsDir, `bmad-agent-bme-${agent.id}`);
+    await fs.ensureDir(skillDir);
+    const content = `---
+name: bmad-agent-bme-${agent.id}
+description: ${agent.id} agent
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from {project-root}/_bmad/bme/${agent.submodule}/agents/${agent.id}.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+    await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf8');
+    changes.push(`Refreshed skill: bmad-agent-bme-${agent.id}/SKILL.md`);
+    if (verbose) console.log(`    Refreshed skill: bmad-agent-bme-${agent.id}/SKILL.md`);
+  }
+
   // 6c. Copy Enhance workflow skill wrappers and register in manifests
   if (enhanceConfig && !isSameRoot) {
     for (const workflow of enhanceConfig.workflows || []) {
@@ -540,7 +687,7 @@ You must fully embody this agent's persona and follow all activation instruction
       if (fs.existsSync(skManifestPath)) {
         const skCsv = fs.readFileSync(skManifestPath, 'utf8');
         if (!skCsv.includes(`"${canonicalId}"`)) {
-          const skRow = `\n"${canonicalId}","${canonicalId}","Manage RICE initiatives backlog — triage review findings, rescore existing items, or bootstrap new backlogs.","bme","_bmad/bme/_enhance/workflows/${workflow.name}/SKILL.md","true"`;
+          const skRow = `\n"${canonicalId}","${canonicalId}","Manage RICE initiatives backlog — triage review findings, rescore existing items, or bootstrap new backlogs.","bme","_bmad/bme/_enhance/workflows/${workflow.name}/SKILL.md","true",,,`;
           fs.appendFileSync(skManifestPath, skRow, 'utf8');
           changes.push(`Added ${canonicalId} to skill-manifest.csv`);
           if (verbose) console.log(`    Added ${canonicalId} to skill-manifest.csv`);
@@ -554,6 +701,80 @@ You must fully embody this agent's persona and follow all activation instruction
     if (verbose) console.log('    Skipped Enhance skill registration (dev environment)');
   }
 
+  // 6d. Copy Artifacts workflow skill wrappers (Story 6.6)
+  // Each standalone:true workflow gets a skill wrapper at .claude/skills/{workflow.name}/SKILL.md.
+  // workflow.name already carries the bmad- prefix, so we use it verbatim (unlike Enhance which
+  // synthesizes bmad-enhance-${workflow.name}). The remove-then-copy pattern clears any leftover
+  // files from prior installs (e.g., the obsolete bmad-portfolio-status/workflow.md thin wrapper).
+  if (artifactsConfig && !isSameRoot) {
+    for (const workflow of artifactsConfig.workflows || []) {
+      if (workflow.standalone !== true) {
+        const msg = `Artifacts: workflow ${workflow.name} has no standalone:true flag — only standalone workflows are supported, skipping`;
+        changes.push(msg);
+        if (verbose) console.log(`    ⚠ ${msg}`);
+        continue;
+      }
+
+      const destSkillDir = path.join(skillsDir, workflow.name);
+
+      // Remove the destination directory first to clear leftover files from prior installs
+      if (fs.existsSync(destSkillDir)) {
+        await fs.remove(destSkillDir);
+      }
+      await fs.ensureDir(destSkillDir);
+
+      // Copy source SKILL.md from the package (the SKILL.md uses an absolute {project-root}
+      // path to load workflow.md, so workflow.md does NOT need to be co-located).
+      const sourceSkillPath = path.join(packageRoot, '_bmad', 'bme', '_artifacts', 'workflows', workflow.name, 'SKILL.md');
+      const targetSkillPath = path.join(destSkillDir, 'SKILL.md');
+      if (fs.existsSync(sourceSkillPath)) {
+        await fs.copy(sourceSkillPath, targetSkillPath, { overwrite: true });
+        changes.push(`Generated skill wrapper: ${workflow.name}`);
+        if (verbose) console.log(`    Generated skill wrapper: ${workflow.name}`);
+      } else {
+        const msg = `Artifacts: source SKILL.md not found for ${workflow.name} at ${sourceSkillPath}`;
+        changes.push(msg);
+        if (verbose) console.log(`    ⚠ ${msg}`);
+      }
+    }
+  } else if (artifactsConfig && isSameRoot) {
+    changes.push('Skipped Artifacts skill wrapper generation (dev environment — source files unchanged)');
+    if (verbose) console.log('    Skipped Artifacts skill wrapper generation (dev environment)');
+  }
+
+  // 6e. Orphan workflow-wrapper cleanup (Story 7.4, I32)
+  // Removes stale .claude/skills/ directories for workflow wrappers that are no longer
+  // declared in the module configs. Uses a two-strategy matching approach:
+  //   Strategy 1 (Enhance): any bmad-enhance-* dir not in the current union → orphan
+  //   Strategy 2 (Artifacts): any dir whose name exactly matches a known Artifacts
+  //     workflow name but is not in the current union → orphan
+  // All other directories (agent wrappers, upstream BMAD skills, third-party) are ignored.
+  if (!isSameRoot) {
+    const currentWorkflowWrappers = new Set();
+    // Enhance wrappers: bmad-enhance-${workflow.name}
+    if (enhanceConfig && Array.isArray(enhanceConfig.workflows)) {
+      for (const wf of enhanceConfig.workflows) {
+        if (wf && wf.name) currentWorkflowWrappers.add(`bmad-enhance-${wf.name}`);
+      }
+    }
+    // Artifacts wrappers: workflow.name verbatim (only standalone:true are installed,
+    // but we track ALL names so a removed standalone workflow is still recognized as an orphan)
+    const knownArtifactsNames = new Set();
+    if (artifactsConfig && Array.isArray(artifactsConfig.workflows)) {
+      for (const wf of artifactsConfig.workflows) {
+        if (wf && wf.name) {
+          knownArtifactsNames.add(wf.name);
+          if (wf.standalone === true) currentWorkflowWrappers.add(wf.name);
+        }
+      }
+    }
+    const orphanChanges = cleanupOrphanWorkflowWrappers(skillsDir, currentWorkflowWrappers, knownArtifactsNames, { verbose });
+    changes.push(...orphanChanges);
+  } else {
+    changes.push('Skipped orphan workflow-wrapper cleanup (dev environment)');
+    if (verbose) console.log('    Skipped orphan workflow-wrapper cleanup (dev environment)');
+  }
+
   // 7. Generate agent customize files (only if they don't already exist)
   const customizeDir = path.join(projectRoot, '_bmad', '_config', 'agents');
   await fs.ensureDir(customizeDir);
@@ -599,4 +820,68 @@ prompts: []
   return changes;
 }
 
-module.exports = { refreshInstallation };
+/**
+ * Remove orphan workflow-wrapper directories from .claude/skills/.
+ *
+ * Two-strategy matching (Story 7.4, I32):
+ *   Strategy 1: Enhance prefix — any dir starting with `bmad-enhance-` that is
+ *               not in `currentWrappers` is an orphan.
+ *   Strategy 2: Artifacts exact-name — any dir whose name is in `knownArtifactsNames`
+ *               but not in `currentWrappers` is an orphan.
+ * Everything else (agent wrappers, upstream BMAD skills, third-party) is ignored.
+ *
+ * @param {string} skillsDir - Absolute path to .claude/skills/
+ * @param {Set<string>} currentWrappers - Union of live workflow wrapper names
+ * @param {Set<string>} knownArtifactsNames - ALL Artifacts workflow names (including non-standalone)
+ * @param {object} [options]
+ * @param {boolean} [options.verbose] - Log each action
+ * @returns {Array<string>} Changes array entries for removed orphans
+ */
+function cleanupOrphanWorkflowWrappers(skillsDir, currentWrappers, knownArtifactsNames, options = {}) {
+  // Deliberately synchronous (fs.removeSync / fs.readdirSync) — the function returns
+  // Array<string>, not a Promise. The sync pattern keeps the contract simple for both
+  // the caller (section 6e spreads the result into changes[]) and the test file (which
+  // imports the function directly without async scaffolding). The existing agent
+  // stale-skill sweep at section 6 uses async fs.remove because it runs inline in the
+  // async refreshInstallation body; this function is extracted to be testable standalone.
+  const { verbose = false } = options;
+  const changes = [];
+
+  if (!fs.existsSync(skillsDir)) return changes;
+
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const name = entry.name;
+
+    // Skip agent wrappers (handled by existing stale-skill sweep)
+    if (name.startsWith('bmad-agent-bme-')) continue;
+
+    // Strategy 1: Enhance prefix (unambiguous — no upstream module uses bmad-enhance-)
+    if (name.startsWith('bmad-enhance-')) {
+      if (!currentWrappers.has(name)) {
+        fs.removeSync(path.join(skillsDir, name));
+        changes.push(`Removed orphan skill wrapper: ${name}`);
+        if (verbose) console.log(`    Removed orphan skill wrapper: ${name}`);
+      }
+      continue;
+    }
+
+    // Strategy 2: Artifacts exact-name match
+    if (knownArtifactsNames.has(name)) {
+      if (!currentWrappers.has(name)) {
+        fs.removeSync(path.join(skillsDir, name));
+        changes.push(`Removed orphan skill wrapper: ${name}`);
+        if (verbose) console.log(`    Removed orphan skill wrapper: ${name}`);
+      }
+      continue;
+    }
+
+    // Everything else: not a workflow wrapper we own — leave alone
+  }
+
+  return changes;
+}
+
+module.exports = { refreshInstallation, cleanupOrphanWorkflowWrappers };

package/scripts/update/lib/taxonomy-merger.js

@@ -0,0 +1,138 @@
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/**
+ * Platform-canonical taxonomy defaults.
+ * Mirrors migrate-artifacts.js constants (separate module boundary).
+ */
+const PLATFORM_INITIATIVES = ['vortex', 'gyre', 'bmm', 'forge', 'helm', 'enhance', 'loom', 'convoke'];
+
+const DEFAULT_ARTIFACT_TYPES = [
+  'prd', 'epic', 'arch', 'adr', 'persona', 'lean-persona', 'empathy-map',
+  'problem-def', 'hypothesis', 'experiment', 'signal', 'decision', 'scope',
+  'pre-reg', 'sprint', 'brief', 'vision', 'report', 'research', 'story', 'spec'
+];
+
+const DEFAULT_ALIASES = {
+  'strategy-perimeter': 'helm',
+  'strategy': 'helm',
+  'strategic': 'helm',
+  'strategic-navigator': 'helm',
+  'strategic-practitioner': 'helm',
+  'team-factory': 'loom'
+};
+
+const TAXONOMY_HEADER = [
+  '# Artifact Governance Taxonomy Configuration',
+  '# Schema version: 1',
+  '# Managed by: convoke-update taxonomy merger',
+  '#',
+  '# This file is the single source of truth for initiative IDs, artifact types,',
+  '# and historical name aliases used by the governance system.',
+  ''
+].join('\n');
+
+/**
+ * Create or merge taxonomy.yaml with platform defaults.
+ * Idempotent: safe to run multiple times.
+ *
+ * - If absent: creates with platform defaults
+ * - If present: merges platform entries (adds missing, preserves user additions)
+ * - Promotes user initiative IDs to platform when they match (FR42)
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<{created: boolean, merged: boolean, promoted: string[]}>}
+ */
+async function mergeTaxonomy(projectRoot) {
+  const configDir = path.join(projectRoot, '_bmad', '_config');
+  const configPath = path.join(configDir, 'taxonomy.yaml');
+
+  await fs.ensureDir(configDir);
+
+  // If no taxonomy exists, create from scratch
+  if (!await fs.pathExists(configPath)) {
+    const defaults = {
+      initiatives: { platform: [...PLATFORM_INITIATIVES], user: [] },
+      artifact_types: [...DEFAULT_ARTIFACT_TYPES],
+      aliases: { ...DEFAULT_ALIASES }
+    };
+    await fs.writeFile(configPath, TAXONOMY_HEADER + yaml.dump(defaults, { lineWidth: -1 }), 'utf8');
+    return { created: true, merged: false, promoted: [] };
+  }
+
+  // Read existing taxonomy (handle corrupt YAML gracefully, matching config-merger pattern)
+  const content = await fs.readFile(configPath, 'utf8');
+  let existing;
+  try {
+    existing = yaml.load(content) || {};
+  } catch {
+    console.warn('Warning: taxonomy.yaml contains invalid YAML. Treating as empty and merging defaults.');
+    existing = {};
+  }
+
+  // Ensure structure
+  if (!existing.initiatives) existing.initiatives = {};
+  if (!Array.isArray(existing.initiatives.platform)) existing.initiatives.platform = [];
+  if (!Array.isArray(existing.initiatives.user)) existing.initiatives.user = [];
+  if (!Array.isArray(existing.artifact_types)) existing.artifact_types = [];
+  if (!existing.aliases || typeof existing.aliases !== 'object') existing.aliases = {};
+
+  let merged = false;
+  const promoted = [];
+
+  // Merge platform initiatives (add missing)
+  const platformSet = new Set(existing.initiatives.platform);
+  for (const id of PLATFORM_INITIATIVES) {
+    if (!platformSet.has(id)) {
+      existing.initiatives.platform.push(id);
+      merged = true;
+    }
+  }
+
+  // Promote user IDs that match platform (FR42)
+  const date = new Date().toISOString().split('T')[0];
+  const newPlatformSet = new Set(existing.initiatives.platform);
+  existing.initiatives.user = existing.initiatives.user.filter(userId => {
+    if (newPlatformSet.has(userId)) {
+      promoted.push(userId);
+      return false; // Remove from user (already in platform)
+    }
+    return true;
+  });
+
+  // Merge artifact types (add missing)
+  const typeSet = new Set(existing.artifact_types);
+  for (const type of DEFAULT_ARTIFACT_TYPES) {
+    if (!typeSet.has(type)) {
+      existing.artifact_types.push(type);
+      merged = true;
+    }
+  }
+
+  // Merge aliases (add missing, don't overwrite existing)
+  for (const [key, value] of Object.entries(DEFAULT_ALIASES)) {
+    if (!(key in existing.aliases)) {
+      existing.aliases[key] = value;
+      merged = true;
+    }
+  }
+
+  // Write back if changes were made
+  if (merged || promoted.length > 0) {
+    let output = TAXONOMY_HEADER + yaml.dump(existing, { lineWidth: -1 });
+
+    // Add promotion comments
+    if (promoted.length > 0) {
+      for (const id of promoted) {
+        output += `# ${id}: promoted from user section on ${date}\n`;
+      }
+    }
+
+    await fs.writeFile(configPath, output, 'utf8');
+  }
+
+  return { created: false, merged: merged || promoted.length > 0, promoted };
+}
+
+module.exports = { mergeTaxonomy, PLATFORM_INITIATIVES, DEFAULT_ARTIFACT_TYPES, DEFAULT_ALIASES };

package/scripts/update/lib/utils.js

@@ -88,9 +88,35 @@ function findProjectRoot() {
   return null;
 }
 
+/**
+ * Assert that a version string is valid before stamping a config file.
+ * Throws a clear error if version is undefined, null, or empty.
+ * Used by refresh-installation.js, config-merger.js, and any future config writer
+ * that stamps a version field — closes I30 (ag-7-1).
+ *
+ * @param {string} version - The version string to validate
+ * @param {string} callSite - Identifier for the call site (e.g., 'enhance', 'artifacts', 'config-merger')
+ * @throws {Error} if version is not a non-empty string
+ */
+function assertVersion(version, callSite) {
+  // Reject all non-string types (numeric 0, boolean false, etc.) — version
+  // must be a non-empty string. Closes Blind Hunter finding #9 (ag-7-1 review).
+  if (typeof version !== 'string' || version === '') {
+    let displayed;
+    if (version === null) displayed = 'null';
+    else if (version === undefined) displayed = 'undefined';
+    else if (version === '') displayed = "''";
+    else displayed = `${typeof version} (${String(version)})`;
+    throw new Error(
+      `Refresh: cannot stamp config — getPackageVersion() returned ${displayed}; check package.json (call site: ${callSite})`
+    );
+  }
+}
+
 module.exports = {
   getPackageVersion,
   compareVersions,
   countUserDataFiles,
-  findProjectRoot
+  findProjectRoot,
+  assertVersion
 };