convoke-agents 3.0.4 → 3.2.0

package/scripts/lib/portfolio/rules/artifact-chain-rule.js

@@ -0,0 +1,156 @@
+/**
+ * Rule 2: Infer phase from artifact chain analysis.
+ *
+ * Priority order (highest first):
+ *   1. Epic with all stories done/complete/✅/[x]/strikethrough → complete
+ *   2. Epic + sprint artifact → build
+ *   3. Architecture doc → planning
+ *   4. HC artifacts (HC2-HC6) → discovery
+ *   5. PRD or brief only → planning
+ *   6. No recognized artifacts → unknown
+ *
+ * Also detects Vortex HC chain completeness (FR34).
+ *
+ * @param {import('../../types').InitiativeState} state - Current initiative state
+ * @param {Array<{filename: string, dir: string, fullPath: string, type?: string, hcPrefix?: string, date?: string, content?: string}>} artifacts
+ * @param {Object} _options - Reserved
+ * @returns {import('../../types').InitiativeState} Enriched state
+ */
+
+/** Patterns that indicate epic completion — require status context to avoid false positives.
+ * Matches: "status: done", "epic-1: done", "Status:** done", "- [x]", "✅" */
+const DONE_PATTERNS = [
+  /(?:status|epic)[^:]*:\s*done\b/i,
+  /(?:status|epic)[^:]*:\s*complete\b/i,
+  /\*\*\s*done\b/i,     // bold marker: **done**
+  /✅/,
+  /\[x\]/i,
+  /~~[^~]{3,}~~/        // strikethrough (min 3 chars to avoid false matches)
+];
+
+function applyArtifactChainRule(state, artifacts, _options = {}) {
+  // Don't override explicit frontmatter phase
+  if (state.phase.confidence === 'explicit') return state;
+
+  const types = new Set(artifacts.map(a => a.type).filter(Boolean));
+  const hcPrefixes = new Set(artifacts.map(a => a.hcPrefix).filter(Boolean));
+
+  // Track last artifact for this initiative
+  let latestArtifact = null;
+  let latestDate = '';
+  for (const a of artifacts) {
+    const d = a.date || '';
+    if (d >= latestDate) {
+      latestDate = d;
+      latestArtifact = a;
+    }
+  }
+  if (latestArtifact) {
+    state.lastArtifact = { file: latestArtifact.filename, date: latestDate || 'unknown' };
+  }
+
+  // Check for epic completion
+  const epicArtifacts = artifacts.filter(a => a.type === 'epic');
+  if (epicArtifacts.length > 0) {
+    // Use most recent epic (by date, fallback to last in array)
+    const epic = epicArtifacts.reduce((best, a) => {
+      return (a.date || '') >= (best.date || '') ? a : best;
+    }, epicArtifacts[0]);
+
+    if (epic.content && isEpicDone(epic.content)) {
+      state.phase = { value: 'complete', source: 'artifact-chain', confidence: 'inferred' };
+      return state;
+    }
+
+    // Epic exists + sprint artifact → build
+    if (types.has('sprint')) {
+      state.phase = { value: 'build', source: 'artifact-chain', confidence: 'inferred' };
+      return state;
+    }
+  }
+
+  // Architecture doc → planning
+  if (types.has('arch')) {
+    state.phase = { value: 'planning', source: 'artifact-chain', confidence: 'inferred' };
+    // Detect HC chain for nextAction even in planning phase
+    detectHCChain(state, hcPrefixes);
+    return state;
+  }
+
+  // HC artifacts → discovery
+  if (hcPrefixes.size > 0) {
+    state.phase = { value: 'discovery', source: 'artifact-chain', confidence: 'inferred' };
+    detectHCChain(state, hcPrefixes);
+    return state;
+  }
+
+  // PRD or brief → planning
+  if (types.has('prd') || types.has('brief')) {
+    state.phase = { value: 'planning', source: 'artifact-chain', confidence: 'inferred' };
+    return state;
+  }
+
+  // No recognized pattern — collect evidence so the operator can see WHY it's unknown (Story 6.3)
+  const evidence = collectPhaseEvidence(artifacts, types, hcPrefixes);
+  state.phase = { value: 'unknown', source: 'artifact-chain', confidence: 'inferred', evidence };
+  return state;
+}
+
+/**
+ * Collect a one-line description of what the phase inference looked at when it
+ * couldn't determine a phase. Used to populate the Next Action with context
+ * instead of the generic "Create PRD or brief" message.
+ *
+ * @param {Array<Object>} artifacts - All artifacts for this initiative
+ * @param {Set<string>} types - Distinct artifact types present
+ * @param {Set<string>} hcPrefixes - HC prefixes present (e.g. 'hc1', 'hc2')
+ * @returns {string[]} Evidence list, e.g. ["3 artifacts found", "no PRD/brief", "no HC chain", ...]
+ */
+function collectPhaseEvidence(artifacts, types, hcPrefixes) {
+  const evidence = [];
+  const count = artifacts.length;
+  evidence.push(count === 1 ? '1 artifact found' : `${count} artifacts found`);
+
+  // Special-case: only HC1 present (incomplete discovery, doesn't trigger discovery branch)
+  if (hcPrefixes.size === 1 && hcPrefixes.has('hc1')) {
+    evidence.push('incomplete HC chain (needs HC2-HC6)');
+    return evidence;
+  }
+
+  if (!types.has('prd') && !types.has('brief')) evidence.push('no PRD/brief');
+  if (!types.has('arch')) evidence.push('no architecture');
+  if (hcPrefixes.size === 0) evidence.push('no HC chain');
+  if (!types.has('epic')) evidence.push('no epic');
+
+  return evidence;
+}
+
+/**
+ * Check if epic content indicates completion via flexible markers.
+ * @param {string} content - Epic file content
+ * @returns {boolean}
+ */
+function isEpicDone(content) {
+  return DONE_PATTERNS.some(pattern => pattern.test(content));
+}
+
+/**
+ * Detect Vortex HC chain completeness and set nextAction if gaps found.
+ * HC chain: HC2 (Problem Definition) → HC3 (Hypothesis) → HC4 (Experiment) → HC5 (Signal) → HC6 (Decision)
+ * @param {import('../../types').InitiativeState} state
+ * @param {Set<string>} hcPrefixes - Set of HC prefixes present (e.g., 'hc2', 'hc3')
+ */
+function detectHCChain(state, hcPrefixes) {
+  const expectedHCs = ['hc2', 'hc3', 'hc4', 'hc5', 'hc6'];
+  const hcNames = { hc2: 'Problem Definition', hc3: 'Hypothesis', hc4: 'Experiment', hc5: 'Signal', hc6: 'Decision' };
+  const missing = expectedHCs.filter(hc => !hcPrefixes.has(hc));
+
+  if (missing.length === 0) {
+    state.nextAction = { value: 'HC chain complete — ready for learning decision', source: 'chain-gap' };
+  } else if (missing.length < expectedHCs.length) {
+    const nextMissing = missing[0];
+    state.nextAction = { value: `Next: ${hcNames[nextMissing]} (${nextMissing.toUpperCase()})`, source: 'chain-gap' };
+  }
+}
+
+module.exports = { applyArtifactChainRule, isEpicDone, detectHCChain, collectPhaseEvidence, DONE_PATTERNS };

package/scripts/lib/portfolio/rules/conflict-resolver.js

@@ -0,0 +1,99 @@
+/**
+ * Rule 4: Resolve conflicts between inference signals.
+ *
+ * - Explicit confidence always wins over inferred
+ * - For same confidence: later phase overrides earlier
+ * - Ensures lastArtifact and nextAction are populated
+ *
+ * @param {import('../../types').InitiativeState} state - Current initiative state
+ * @param {Array<{filename: string, dir: string, fullPath: string}>} artifacts - Artifacts for this initiative
+ * @param {Object} _options - Reserved
+ * @returns {import('../../types').InitiativeState} Enriched state
+ */
+
+/** Phase priority order (higher index = later phase) */
+const PHASE_PRIORITY = ['unknown', 'discovery', 'planning', 'build', 'complete'];
+
+function applyConflictResolver(state, artifacts, _options = {}) {
+  // Ensure phase has a value
+  if (!state.phase.value) {
+    state.phase = { value: 'unknown', source: 'conflict-resolver', confidence: 'inferred' };
+  }
+
+  // Ensure status has a value
+  if (!state.status.value) {
+    state.status = { value: 'unknown', source: 'conflict-resolver', confidence: 'inferred' };
+  }
+
+  // Ensure lastArtifact is populated
+  if (!state.lastArtifact.file && artifacts.length > 0) {
+    // Fallback to last artifact in array
+    const last = artifacts[artifacts.length - 1];
+    state.lastArtifact = { file: last.filename, date: last.date || 'unknown' };
+  }
+
+  // Story 6.3: If phase is unknown AND a recognized-type artifact exists AND we have evidence,
+  // surface a context-aware next action instead of the generic "Create PRD or brief".
+  // - Initiatives with zero artifacts still get the generic message (legitimate use case).
+  // - Initiatives whose ONLY artifacts are fallback-attributed (synthetic 'unknown' type)
+  //   also get the generic message — those don't reflect a real phase signal worth elaborating on.
+  // This guards against the design-intent inversion caught in code review:
+  // a single fallback-attributed note shouldn't override "Create PRD or brief".
+  const hasRecognizedArtifact = artifacts.some(a => a && a.type && a.type !== 'unknown');
+  if (
+    state.phase.value === 'unknown' &&
+    Array.isArray(state.phase.evidence) &&
+    state.phase.evidence.length > 0 &&
+    hasRecognizedArtifact
+  ) {
+    const summary = state.phase.evidence.slice(0, 2).join(', ');
+    state.nextAction = {
+      value: `Unknown phase: ${summary}`,
+      source: 'conflict-resolver'
+    };
+    return state;
+  }
+
+  // Derive nextAction from phase if not already set by chain-gap analysis
+  if (!state.nextAction.value) {
+    state.nextAction = deriveNextAction(state);
+  }
+
+  return state;
+}
+
+/**
+ * Derive a suggested next action based on current phase.
+ * @param {import('../../types').InitiativeState} state
+ * @returns {{value: string, source: string}}
+ */
+function deriveNextAction(state) {
+  switch (state.phase.value) {
+    case 'unknown':
+      return { value: 'Create PRD or brief to start planning', source: 'conflict-resolver' };
+    case 'discovery':
+      return { value: 'Continue discovery — check HC chain progress', source: 'conflict-resolver' };
+    case 'planning':
+      return { value: 'Create architecture or epics to advance to build', source: 'conflict-resolver' };
+    case 'build':
+      return { value: 'Continue story execution', source: 'conflict-resolver' };
+    case 'complete':
+      return { value: 'Initiative complete — consider retrospective', source: 'conflict-resolver' };
+    default:
+      return { value: 'Review initiative status', source: 'conflict-resolver' };
+  }
+}
+
+/**
+ * Compare two phases by priority.
+ * @param {string} a - Phase name
+ * @param {string} b - Phase name
+ * @returns {number} Negative if a < b, positive if a > b, 0 if equal
+ */
+function comparePhasePriority(a, b) {
+  const idxA = PHASE_PRIORITY.indexOf(a);
+  const idxB = PHASE_PRIORITY.indexOf(b);
+  return (idxA === -1 ? -1 : idxA) - (idxB === -1 ? -1 : idxB);
+}
+
+module.exports = { applyConflictResolver, deriveNextAction, comparePhasePriority, PHASE_PRIORITY };

package/scripts/lib/portfolio/rules/frontmatter-rule.js

@@ -0,0 +1,42 @@
+/**
+ * Rule 1: Read explicit status/phase from frontmatter (highest priority).
+ *
+ * Reads `status` (standard schema field) and `phase` (operator-override, not in standard schema).
+ * Explicit frontmatter signals have highest priority — later rules should not override them.
+ *
+ * @param {import('../../types').InitiativeState} state - Current initiative state
+ * @param {Array<{filename: string, dir: string, fullPath: string, frontmatter?: Object}>} artifacts - Artifacts for this initiative
+ * @param {Object} _options - Reserved
+ * @returns {import('../../types').InitiativeState} Enriched state
+ */
+function applyFrontmatterRule(state, artifacts, _options = {}) {
+  // Process artifacts most-recent-first (by date suffix or array order)
+  // First explicit value found wins
+  for (const artifact of artifacts) {
+    if (!artifact.frontmatter) continue;
+
+    if (!state.status.value || state.status.confidence !== 'explicit') {
+      if (artifact.frontmatter.status != null && artifact.frontmatter.status !== '') {
+        state.status = {
+          value: artifact.frontmatter.status,
+          source: 'frontmatter',
+          confidence: 'explicit'
+        };
+      }
+    }
+
+    if (!state.phase.value || state.phase.confidence !== 'explicit') {
+      if (artifact.frontmatter.phase != null && artifact.frontmatter.phase !== '') {
+        state.phase = {
+          value: artifact.frontmatter.phase,
+          source: 'frontmatter',
+          confidence: 'explicit'
+        };
+      }
+    }
+  }
+
+  return state;
+}
+
+module.exports = { applyFrontmatterRule };

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 = {};