convoke-agents 3.0.3 → 3.1.0

package/scripts/lib/portfolio/rules/git-recency-rule.js

@@ -0,0 +1,69 @@
+/**
+ * Rule 3: Infer status from git recency (stale detection).
+ *
+ * Checks the most recent git commit date for the initiative's artifacts.
+ * If within stale_days → ongoing. If beyond → stale.
+ *
+ * Known limitation: checks current branch only.
+ *
+ * @param {import('../../types').InitiativeState} state - Current initiative state
+ * @param {Array<{filename: string, dir: string, fullPath: string}>} artifacts - Artifacts for this initiative
+ * @param {Object} options
+ * @param {number} [options.staleDays=30] - Days threshold for stale detection
+ * @param {string} options.projectRoot - Absolute path to project root
+ * @returns {import('../../types').InitiativeState} Enriched state
+ */
+
+const { execFileSync } = require('child_process');
+const path = require('path');
+
+function applyGitRecencyRule(state, artifacts, options = {}) {
+  // Don't override explicit frontmatter status
+  if (state.status.confidence === 'explicit') return state;
+
+  const { staleDays = 30, projectRoot } = options;
+  if (!projectRoot || artifacts.length === 0) return state;
+
+  // Find most recent git activity across all artifacts for this initiative
+  let latestDate = null;
+  let latestFile = null;
+
+  for (const artifact of artifacts) {
+    try {
+      const relativePath = path.relative(projectRoot, artifact.fullPath);
+      const dateStr = execFileSync(
+        'git', ['log', '-1', '--format=%as', '--', relativePath],
+        { cwd: projectRoot, encoding: 'utf8', stdio: 'pipe' }
+      ).trim();
+
+      if (dateStr && (!latestDate || dateStr > latestDate)) {
+        latestDate = dateStr;
+        latestFile = artifact.filename;
+      }
+    } catch {
+      // File not tracked or git unavailable — skip
+    }
+  }
+
+  if (!latestDate) return state;
+
+  // Update lastArtifact if git date is more recent than artifact-chain's date
+  if (!state.lastArtifact.file || latestDate > (state.lastArtifact.date || '')) {
+    state.lastArtifact = { file: latestFile, date: latestDate };
+  }
+
+  // Calculate days since last activity
+  const lastActivity = new Date(latestDate);
+  const now = new Date();
+  const daysSince = Math.floor((now - lastActivity) / (1000 * 60 * 60 * 24));
+
+  if (daysSince <= staleDays) {
+    state.status = { value: 'ongoing', source: 'git-recency', confidence: 'inferred' };
+  } else {
+    state.status = { value: 'stale', source: 'git-recency', confidence: 'inferred' };
+  }
+
+  return state;
+}
+
+module.exports = { applyGitRecencyRule };

package/scripts/lib/types.js

@@ -0,0 +1,122 @@
+/**
+ * Shared JSDoc type definitions for the Artifact Governance & Portfolio system.
+ * Used by: artifact-utils.js, migrate-artifacts.js, portfolio-engine.js, archive.js
+ *
+ * @module types
+ */
+
+/**
+ * Inference signal with value, source, and confidence level.
+ * @typedef {Object} InferenceSignal
+ * @property {string} value - The inferred value
+ * @property {string} source - Where the inference came from (e.g., 'frontmatter', 'artifact-chain', 'git-recency')
+ * @property {'explicit'|'inferred'} confidence - Whether this is from explicit data or heuristic inference
+ */
+
+/**
+ * State of an initiative as derived by the portfolio inference rule chain.
+ * This is the core data structure that flows through the rule chain and into formatters.
+ * @typedef {Object} InitiativeState
+ * @property {string} initiative - Initiative ID from taxonomy (e.g., 'helm', 'gyre')
+ * @property {InferenceSignal} phase - Current phase: discovery, planning, build, blocked, complete, unknown
+ * @property {InferenceSignal} status - Current status: ongoing, blocked, paused, complete, stale, unknown
+ * @property {{file: string, date: string}} lastArtifact - Most recently modified artifact for this initiative
+ * @property {{value: string, source: string}} nextAction - Suggested next action based on chain gap analysis
+ */
+
+/**
+ * @deprecated Use ManifestEntry instead. Planning placeholder with incomplete fields.
+ * @typedef {Object} RenameManifestEntry
+ * @property {string} oldPath - Current file path (relative to project root)
+ * @property {string} newPath - Proposed new file path
+ * @property {string} initiative - Inferred initiative ID
+ * @property {string} artifactType - Inferred artifact type
+ * @property {'high'|'low'} confidence - Inference confidence level
+ * @property {'fully-governed'|'half-governed'|'ungoverned'|'invalid-governed'} governanceState - Current governance state
+ */
+
+/**
+ * Manifest entry for dry-run display. Replaces RenameManifestEntry.
+ * @typedef {Object} ManifestEntry
+ * @property {string} oldPath - Current relative path (e.g., 'planning-artifacts/prd-gyre.md')
+ * @property {string|null} newPath - Proposed new path (null for SKIP/CONFLICT/AMBIGUOUS)
+ * @property {string|null} initiative - Resolved initiative ID (null if ambiguous)
+ * @property {string|null} artifactType - Resolved artifact type (null if ungoverned)
+ * @property {'high'|'low'} confidence - Initiative inference confidence
+ * @property {string} source - Inference source (exact/alias/empty/unresolved)
+ * @property {'RENAME'|'SKIP'|'INJECT_ONLY'|'CONFLICT'|'AMBIGUOUS'} action
+ * @property {string} dir - Directory name (e.g., 'planning-artifacts')
+ * @property {{firstLines: string[], gitAuthor: string|null, gitDate: string|null}|null} contextClues
+ * @property {string[]|null} crossReferences - Files referencing this one (verbose only)
+ * @property {string[]} candidates - Possible initiative matches (ambiguous only)
+ * @property {string[]|null} collisionWith - Other files colliding on same newPath
+ * @property {string|null} frontmatterInitiative - Initiative from frontmatter (for CONFLICT display)
+ * @property {string|null} fileInitiative - Initiative from filename (for CONFLICT display)
+ * @property {'high'|'low'} typeConfidence - Artifact type inference confidence
+ * @property {string} typeSource - Artifact type inference source (prefix/alias/none)
+ */
+
+/**
+ * Result of generateManifest() containing all entries, collisions, and summary.
+ * @typedef {Object} ManifestResult
+ * @property {ManifestEntry[]} entries - All manifest entries
+ * @property {Map<string, string[]>} collisions - Colliding newPath -> list of oldPaths
+ * @property {{total: number, skip: number, rename: number, inject: number, conflict: number, ambiguous: number}} summary
+ */
+
+/**
+ * A markdown link that needs updating after file renames.
+ * @typedef {Object} LinkUpdate
+ * @property {string} filePath - Path of the file containing the link
+ * @property {string} oldLink - Original link target
+ * @property {string} newLink - Updated link target
+ * @property {'bracket-link'|'relative-link'|'parent-link'|'frontmatter-array'} pattern - Which link pattern matched
+ */
+
+/**
+ * Parsed taxonomy configuration from _bmad/_config/taxonomy.yaml.
+ * @typedef {Object} TaxonomyConfig
+ * @property {{platform: string[], user: string[]}} initiatives - Initiative IDs split by ownership
+ * @property {string[]} artifact_types - Valid artifact type identifiers
+ * @property {Object<string, string>} aliases - Historical name → canonical initiative ID mapping (migration-only)
+ */
+
+/**
+ * Frontmatter metadata fields for governed artifacts.
+ * @typedef {Object} FrontmatterSchema
+ * @property {string} initiative - Initiative ID from taxonomy
+ * @property {string} artifact_type - Artifact type from taxonomy
+ * @property {'draft'|'validated'|'superseded'|'active'} [status] - Optional artifact-level status
+ * @property {string} created - ISO 8601 date string (YYYY-MM-DD)
+ * @property {number} schema_version - Schema version integer (currently 1)
+ */
+
+/**
+ * Result of parsing a filename against naming conventions.
+ * @typedef {Object} ParsedFilename
+ * @property {string} filename - Original filename
+ * @property {boolean} isDated - Whether the file has a date suffix
+ * @property {string|null} date - Extracted date (YYYY-MM-DD) or null
+ * @property {string} baseName - Filename without date and extension
+ * @property {string|null} category - Extracted category prefix or null
+ * @property {boolean} hasValidCategory - Whether category is in the valid list
+ * @property {boolean} isUppercase - Whether filename contains uppercase characters
+ * @property {boolean} matchesConvention - Whether filename fully matches naming convention
+ */
+
+/**
+ * Result of a frontmatter conflict check.
+ * @typedef {Object} FrontmatterConflict
+ * @property {string} field - The conflicting field name
+ * @property {*} existingValue - Current value in frontmatter
+ * @property {*} newValue - Proposed new value
+ */
+
+/**
+ * Result of injectFrontmatter() including conflict detection.
+ * @typedef {Object} InjectResult
+ * @property {string} content - The modified file content with injected frontmatter
+ * @property {FrontmatterConflict[]} conflicts - Any field conflicts detected (empty if none)
+ */
+
+module.exports = {};

package/scripts/migrate-artifacts.js

@@ -0,0 +1,380 @@
+#!/usr/bin/env node
+
+/**
+ * Convoke Artifact Governance Migration CLI
+ *
+ * Dry-run by default — shows what the migration would do without changing anything.
+ * Use --apply to execute renames. Use --apply --force to skip confirmation.
+ *
+ * @module migrate-artifacts
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const { findProjectRoot } = require('./update/lib/utils');
+const {
+  readTaxonomy,
+  generateManifest,
+  formatManifest,
+  ensureCleanTree,
+  executeRenames,
+  ArtifactMigrationError,
+  verifyHistoryChain,
+  executeInjections,
+  resolveAmbiguous,
+  detectMigrationState,
+  generateGovernanceADR,
+  supersedePreviousADR
+} = require('./lib/artifact-utils');
+
+// --- CLI Argument Parsing ---
+
+const DEFAULT_INCLUDE_DIRS = Object.freeze(['planning-artifacts', 'vortex-artifacts', 'gyre-artifacts']);
+
+/** Pattern for valid directory names: lowercase alphanumeric, dashes, underscores */
+const VALID_DIR_PATTERN = /^[a-zA-Z0-9_-]+$/;
+
+/**
+ * Parse CLI arguments from argv array.
+ *
+ * @param {string[]} argv - Arguments (typically process.argv.slice(2))
+ * @returns {{help: boolean, includeDirs: string[], apply: boolean, force: boolean, verbose: boolean}}
+ */
+function parseArgs(argv) {
+  const help = argv.includes('--help') || argv.includes('-h');
+  const apply = argv.includes('--apply');
+  const force = argv.includes('--force');
+  const verbose = argv.includes('--verbose');
+
+  let includeDirs = [...DEFAULT_INCLUDE_DIRS];
+  const includeIdx = argv.indexOf('--include');
+  if (includeIdx !== -1) {
+    const nextArg = argv[includeIdx + 1];
+    // Skip if next arg is missing or is another flag
+    if (nextArg && !nextArg.startsWith('--')) {
+      const parsed = nextArg.split(',').map(d => d.trim()).filter(Boolean);
+      // Validate: only simple directory names (no path traversal)
+      const valid = parsed.filter(d => VALID_DIR_PATTERN.test(d));
+      const invalid = parsed.filter(d => !VALID_DIR_PATTERN.test(d));
+      if (invalid.length > 0) {
+        console.warn(`Warning: Invalid directory names ignored: ${invalid.join(', ')}`);
+      }
+      if (valid.length > 0) {
+        includeDirs = valid;
+      }
+    }
+  }
+
+  return { help, includeDirs, apply, force, verbose };
+}
+
+// --- Help ---
+
+function printHelp() {
+  console.log(`
+Usage: convoke-migrate-artifacts [options]
+
+Analyze artifact files and show what the governance migration would do.
+Dry-run by default — no files are modified.
+
+Options:
+  --include <dirs>  Comma-separated directory names to scan (relative to _bmad-output/)
+                    Default: planning-artifacts,vortex-artifacts,gyre-artifacts
+  --verbose         Show cross-references for ambiguous files
+  --apply           Execute the rename migration (commit 1: git mv)
+  --force           Bypass confirmation prompt (use with --apply for automation)
+  --help, -h        Show this help
+
+Examples:
+  convoke-migrate-artifacts                          Dry-run with default scope
+  convoke-migrate-artifacts --verbose                Dry-run with cross-references
+  convoke-migrate-artifacts --include planning-artifacts   Dry-run for one directory
+`);
+}
+
+// --- Taxonomy Bootstrap ---
+
+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'
+];
+
+/**
+ * Create taxonomy.yaml with platform defaults if it does not exist.
+ * Idempotent — never overwrites an existing file.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {boolean} true if file was created, false if already existed
+ */
+function bootstrapTaxonomy(projectRoot) {
+  const configDir = path.join(projectRoot, '_bmad', '_config');
+  const configPath = path.join(configDir, 'taxonomy.yaml');
+
+  if (fs.existsSync(configPath)) {
+    return false;
+  }
+
+  const defaults = {
+    initiatives: {
+      platform: PLATFORM_INITIATIVES,
+      user: []
+    },
+    artifact_types: DEFAULT_ARTIFACT_TYPES,
+    aliases: {}
+  };
+
+  const header = [
+    '# Artifact Governance Taxonomy Configuration',
+    '# Schema version: 1',
+    `# Created by: convoke-migrate-artifacts bootstrap`,
+    '#',
+    '# This file is the single source of truth for initiative IDs, artifact types,',
+    '# and historical name aliases used by the governance system.',
+    ''
+  ].join('\n');
+
+  fs.ensureDirSync(configDir);
+  fs.writeFileSync(configPath, header + yaml.dump(defaults, { lineWidth: -1 }), 'utf8');
+  return true;
+}
+
+// --- Interactive Prompt ---
+
+/**
+ * Prompt the operator to confirm migration apply.
+ * Exported for mocking in tests — tests should NEVER interact with real readline.
+ *
+ * @returns {Promise<boolean>} true if operator confirms
+ */
+async function confirmApply() {
+  const readline = require('readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.on('close', () => resolve(false)); // piped/closed stdin → reject
+    rl.question('Apply migration? [y/n] ', answer => {
+      rl.close();
+      resolve(typeof answer === 'string' && answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+// --- Main ---
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) {
+    printHelp();
+    return;
+  }
+
+  if (args.force && !args.apply) {
+    console.log('Warning: --force has no effect without --apply. Running dry-run instead.');
+  }
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.error('Error: Not in a Convoke project. Could not find _bmad/ directory.');
+    process.exit(1);
+  }
+
+  // Archive exclusion (FR50): always strip _archive from includeDirs
+  const excludeDirs = ['_archive'];
+  const filteredIncludeDirs = args.includeDirs.filter(d => {
+    if (d === '_archive') {
+      console.warn('Warning: _archive is always excluded from migration scope (FR50). Ignoring.');
+      return false;
+    }
+    return true;
+  });
+
+  if (filteredIncludeDirs.length === 0) {
+    console.error('Error: No directories to scan. All specified directories were excluded.');
+    process.exit(1);
+  }
+
+  // Taxonomy bootstrap (FR49): create if absent, never overwrite
+  const created = bootstrapTaxonomy(projectRoot);
+  if (created) {
+    console.log('Created _bmad/_config/taxonomy.yaml with platform defaults.');
+  }
+
+  // Validate taxonomy (NFR22: graceful error, no stack traces)
+  try {
+    readTaxonomy(projectRoot);
+  } catch (err) {
+    console.error(`Error: Invalid taxonomy configuration.`);
+    console.error(`  ${err.message}`);
+    console.error(`  Fix the file at: _bmad/_config/taxonomy.yaml`);
+    process.exit(1);
+  }
+
+  // Generate manifest (shared by dry-run and apply)
+  const manifest = await generateManifest(projectRoot, {
+    includeDirs: filteredIncludeDirs,
+    excludeDirs,
+    verbose: args.verbose
+  });
+
+  const output = formatManifest(manifest, { verbose: args.verbose });
+  console.log(output);
+
+  // Dry-run mode (default): just print manifest and exit
+  if (!args.apply) {
+    return;
+  }
+
+  // --- Apply mode ---
+
+  // Idempotent recovery detection
+  let migrationState = detectMigrationState(projectRoot);
+  if (migrationState === 'complete') {
+    // Secondary check: verify manifest confirms all files governed (catches new files added since migration)
+    const hasWork = manifest.entries.some(e => e.action === 'RENAME' || e.action === 'AMBIGUOUS');
+    if (!hasWork) {
+      console.log('\nNothing to migrate -- all files governed.');
+      return;
+    }
+    // New files found — proceed as fresh migration
+    console.log('\nPrevious migration detected, but new ungoverned files found. Proceeding with fresh migration.');
+    migrationState = 'fresh';
+  }
+
+  // Load taxonomy for ambiguous resolution
+  const taxonomy = readTaxonomy(projectRoot);
+
+  // Resolve ambiguous files interactively (or auto-skip in --force mode)
+  const resolution = await resolveAmbiguous(manifest, taxonomy, projectRoot, { force: args.force });
+  if (resolution.resolved > 0 || resolution.skipped > 0) {
+    console.log(`\nAmbiguous resolution: ${resolution.resolved} resolved, ${resolution.skipped} skipped.`);
+  }
+
+  // Re-compute counts and re-check collisions after resolution (new RENAME entries may collide)
+  const { detectCollisions } = require('./lib/artifact-utils');
+  manifest.collisions = detectCollisions(manifest.entries);
+  const renameCount = manifest.summary.rename;
+  const skipCount = manifest.entries.filter(e => e.action === 'SKIP').length;
+  const ambiguousLeft = manifest.summary.ambiguous;
+  console.log(`\n${renameCount} files will be renamed. ${skipCount} skipped. ${ambiguousLeft} still ambiguous.`);
+
+  // Block on collisions (includes post-resolution collisions)
+  if (manifest.collisions.size > 0) {
+    console.error(`Error: ${manifest.collisions.size} filename collision(s) detected. Resolve before applying.`);
+    process.exit(1);
+  }
+
+  if (renameCount === 0) {
+    console.log('Nothing to rename.');
+    return;
+  }
+
+  // Confirmation prompt (unless --force)
+  if (!args.force) {
+    const confirmed = await confirmApply();
+    if (!confirmed) {
+      console.log('Migration aborted.');
+      return;
+    }
+  }
+
+  // Pre-flight: ensure clean tree
+  try {
+    ensureCleanTree(filteredIncludeDirs, projectRoot);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  // Execute migration phases
+  try {
+    // Phase routing based on idempotent recovery state
+    if (migrationState === 'renames-done') {
+      const priorCount = manifest.entries.filter(e => e.action === 'RENAME').length;
+      console.log(`\nDetected partial migration (${priorCount} renames done, frontmatter pending). Resuming commit 2.`);
+    } else {
+      // Commit 1: renames
+      const renameResult = executeRenames(manifest, projectRoot);
+      console.log(`\nRename phase complete. ${renameResult.renamedCount} files renamed. Commit: ${renameResult.commitSha}`);
+
+      // Verify history chain (informational)
+      const renamedEntries = manifest.entries.filter(e => e.action === 'RENAME');
+      const verification = verifyHistoryChain(renamedEntries, projectRoot);
+      if (verification.failed.length > 0) {
+        console.warn(`Warning: git log --follow failed for ${verification.failed.length} file(s):`);
+        for (const f of verification.failed) {
+          console.warn(`  ${f}`);
+        }
+      } else {
+        console.log(`History chain verified for ${verification.verified} sample file(s).`);
+      }
+    }
+
+    // Commit 2: frontmatter injection + link updating + rename map
+    const injResult = await executeInjections(manifest, projectRoot, filteredIncludeDirs);
+    console.log(`\nInjection phase complete. ${injResult.injectedCount} files injected, ${injResult.linkUpdates.updatedLinks} links updated, ${injResult.conflictCount} conflicts skipped. Commit: ${injResult.commitSha}`);
+
+    // Commit 3: ADR generation (non-blocking — failure logs warning, doesn't rollback)
+    try {
+      const date = new Date().toISOString().split('T')[0];
+      const newADRFilename = `adr-artifact-governance-convention-${date}.md`;
+      const adrContent = generateGovernanceADR(date, {
+        renamedCount: renameCount,
+        injectedCount: injResult.injectedCount,
+        linksUpdated: injResult.linkUpdates.updatedLinks,
+        scopeDirs: filteredIncludeDirs
+      });
+
+      const adrDir = path.join(projectRoot, '_bmad-output', 'planning-artifacts');
+      fs.ensureDirSync(adrDir);
+      const adrPath = path.join(adrDir, newADRFilename);
+      // Write new ADR FIRST, then supersede old (prevents orphaned supersession if write fails)
+      fs.writeFileSync(adrPath, adrContent, 'utf8');
+      supersedePreviousADR(projectRoot, newADRFilename);
+
+      const { execFileSync: execGit } = require('child_process');
+      execGit('git', ['add', '_bmad-output/planning-artifacts/'], { cwd: projectRoot, stdio: 'pipe' });
+      execGit('git', ['commit', '-m', 'chore: generate governance convention ADR'], { cwd: projectRoot, stdio: 'pipe' });
+      console.log(`\nADR generated: ${newADRFilename}`);
+    } catch (adrErr) {
+      console.warn(`\nWarning: ADR generation failed: ${adrErr.message}`);
+      console.warn('Migration data is intact (commits 1-2 preserved). ADR can be generated manually.');
+    }
+
+    // Final summary
+    console.log(`\nMigration complete. ${renameCount} files renamed, ${injResult.injectedCount} frontmatter injected, ${injResult.linkUpdates.updatedLinks} links updated, ${skipCount} skipped.`);
+  } catch (err) {
+    if (err instanceof ArtifactMigrationError && err.phase === 'rename') {
+      console.error(`\nRename failed: ${err.message}`);
+      if (err.recoverable) {
+        console.error('Rollback complete. No changes made.');
+      } else {
+        console.error('WARNING: Rollback may have failed. Run `git status` to check working tree state.');
+      }
+      process.exit(1);
+    }
+    if (err instanceof ArtifactMigrationError && err.phase === 'inject') {
+      console.error(`\nInjection failed: ${err.message}`);
+      if (err.recoverable) {
+        console.error('Renames preserved (commit 1). Injections discarded.');
+      } else {
+        console.error('WARNING: Rollback may have failed. Run `git status` to check working tree state.');
+      }
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+// Run if invoked directly
+if (require.main === module) {
+  main().catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { parseArgs, main, confirmApply, bootstrapTaxonomy, DEFAULT_INCLUDE_DIRS, PLATFORM_INITIATIVES, DEFAULT_ARTIFACT_TYPES, VALID_DIR_PATTERN };

package/scripts/update/lib/migration-runner.js

@@ -466,7 +466,7 @@ async function runRefreshOnly(fromVersion, options = {}) {
       try {
         await backupManager.restoreBackup(backupMetadata, projectRoot);
         console.log(chalk.green('✓ Installation restored from backup'));
-      } catch (restoreError) {
+      } catch (_restoreError) {
         console.error(chalk.red('✗ Restore failed!'));
         console.error(chalk.yellow(`Manual restore may be needed from: ${backupMetadata.backup_dir}`));
       }