convoke-agents 3.0.4 → 3.1.0

package/scripts/lib/portfolio/formatters/markdown-formatter.js

@@ -0,0 +1,40 @@
+/**
+ * Markdown formatter — standard markdown table output with confidence markers.
+ *
+ * @module markdown-formatter
+ */
+
+/**
+ * Format InitiativeState array as markdown table.
+ *
+ * @param {import('../../types').InitiativeState[]} initiatives
+ * @returns {string}
+ */
+function formatMarkdown(initiatives) {
+  if (initiatives.length === 0) {
+    return 'No initiatives found.\n';
+  }
+
+  const lines = [];
+  lines.push('| Initiative | Phase | Status | Next Action / Context |');
+  lines.push('|------------|-------|--------|----------------------|');
+
+  for (const s of initiatives) {
+    const phase = s.phase.value || 'unknown';
+    const statusVal = s.status.value || 'unknown';
+    const conf = s.status.confidence === 'explicit' ? '(explicit)' : '(inferred)';
+    const status = `${statusVal} ${conf}`;
+
+    const context = s.nextAction.value
+      ? s.nextAction.value
+      : s.lastArtifact.file
+        ? `Last: ${s.lastArtifact.file} (${s.lastArtifact.date || '?'})`
+        : 'No artifacts';
+
+    lines.push(`| ${s.initiative} | ${phase} | ${status} | ${context} |`);
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+module.exports = { formatMarkdown };

package/scripts/lib/portfolio/formatters/terminal-formatter.js

@@ -0,0 +1,56 @@
+/**
+ * Terminal formatter — aligned column output with confidence markers.
+ * No library used — padEnd() for alignment.
+ *
+ * @module terminal-formatter
+ */
+
+/**
+ * Format InitiativeState array as aligned terminal table.
+ *
+ * @param {import('../../types').InitiativeState[]} initiatives
+ * @returns {string}
+ */
+function formatTerminal(initiatives) {
+  if (initiatives.length === 0) {
+    return 'No initiatives found.';
+  }
+
+  // Dynamic init column width: at least 14, grows for long names
+  const maxInitLen = Math.max(14, ...initiatives.map(s => s.initiative.length + 2));
+  const COL = { init: maxInitLen, phase: 12, status: 24, action: 50 };
+  const lines = [];
+
+  // Header
+  lines.push(
+    'Initiative'.padEnd(COL.init) +
+    'Phase'.padEnd(COL.phase) +
+    'Status'.padEnd(COL.status) +
+    'Next Action / Context'
+  );
+  lines.push('-'.repeat(COL.init + COL.phase + COL.status + COL.action));
+
+  for (const s of initiatives) {
+    const phase = s.phase.value || 'unknown';
+    const statusVal = s.status.value || 'unknown';
+    const conf = s.status.confidence === 'explicit' ? '(explicit)' : '(inferred)';
+    const status = `${statusVal} ${conf}`;
+
+    const context = s.nextAction.value
+      ? s.nextAction.value
+      : s.lastArtifact.file
+        ? `Last: ${s.lastArtifact.file} (${s.lastArtifact.date || '?'})`
+        : 'No artifacts';
+
+    lines.push(
+      s.initiative.padEnd(COL.init) +
+      phase.padEnd(COL.phase) +
+      status.padEnd(COL.status) +
+      context
+    );
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = { formatTerminal };

package/scripts/lib/portfolio/portfolio-engine.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+/**
+ * Convoke Portfolio Engine — scan → parse → infer → sort → format → output.
+ * Read-only: no git writes, no file modifications.
+ *
+ * @module portfolio-engine
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const {
+  readTaxonomy,
+  scanArtifactDirs,
+  parseFrontmatter,
+  inferArtifactType,
+  inferInitiative
+} = require('../artifact-utils');
+const { findProjectRoot } = require('../../update/lib/utils');
+const { applyFrontmatterRule } = require('./rules/frontmatter-rule');
+const { applyArtifactChainRule } = require('./rules/artifact-chain-rule');
+const { applyGitRecencyRule } = require('./rules/git-recency-rule');
+const { applyConflictResolver } = require('./rules/conflict-resolver');
+const { formatTerminal } = require('./formatters/terminal-formatter');
+const { formatMarkdown } = require('./formatters/markdown-formatter');
+
+/** Directories to exclude from portfolio scan */
+const EXCLUDE_DIRS = ['_archive', 'brainstorming', 'design-artifacts', 'journey-examples', 'project-documentation', 'test-artifacts', 'drafts'];
+
+/**
+ * Create an empty InitiativeState for a given initiative.
+ * @param {string} initiative - Initiative ID
+ * @returns {import('../types').InitiativeState}
+ */
+function makeEmptyState(initiative) {
+  return {
+    initiative,
+    phase: { value: null, source: null, confidence: null },
+    status: { value: null, source: null, confidence: null },
+    lastArtifact: { file: null, date: null },
+    nextAction: { value: null, source: null }
+  };
+}
+
+/**
+ * Generate portfolio view of all initiatives.
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @param {Object} [options={}]
+ * @param {string} [options.sort='alpha'] - Sort mode: 'alpha' or 'last-activity'
+ * @param {number} [options.staleDays=30] - Days threshold for stale detection
+ * @returns {Promise<{initiatives: import('../types').InitiativeState[], summary: {total: number, governed: number, ungoverned: number}}>}
+ */
+async function generatePortfolio(projectRoot, options = {}) {
+  const { sort = 'alpha', staleDays = 30, wipThreshold = 4, filter = null } = options;
+
+  // Pre-flight: read taxonomy (FR39 — error if absent)
+  const taxonomy = readTaxonomy(projectRoot);
+
+  // Scan: discover subdirectories dynamically
+  const outputDir = path.join(projectRoot, '_bmad-output');
+  if (!fs.existsSync(outputDir)) {
+    console.warn('Warning: _bmad-output/ directory not found.');
+    return { initiatives: [], summary: { total: 0, governed: 0, ungoverned: 0 } };
+  }
+  const allDirs = fs.readdirSync(outputDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && !e.name.startsWith('.') && !EXCLUDE_DIRS.includes(e.name))
+    .map(e => e.name);
+
+  const allFiles = await scanArtifactDirs(projectRoot, allDirs, ['_archive']);
+
+  // Parse: index files by initiative
+  const registry = new Map();
+  let governed = 0;
+  let ungoverned = 0;
+  let unattributed = 0;
+
+  const mdFiles = allFiles.filter(f => f.filename.endsWith('.md'));
+
+  for (const file of mdFiles) {
+
+    const typeResult = inferArtifactType(file.filename, taxonomy);
+    const initResult = typeResult.type
+      ? inferInitiative(typeResult.remainder, taxonomy)
+      : { initiative: null, confidence: 'low', source: 'no-type', candidates: [] };
+
+    // Files with no resolved initiative cannot be attributed — skip
+    if (!initResult.initiative) {
+      unattributed++;
+      continue;
+    }
+
+    // Read frontmatter to classify governed vs ungoverned
+    let frontmatter = null;
+    let content = '';
+    try {
+      content = fs.readFileSync(file.fullPath, 'utf8');
+      frontmatter = parseFrontmatter(content).data;
+    } catch {
+      // Unreadable — treat as no frontmatter
+    }
+
+    // Governed = has frontmatter with matching initiative field
+    const isGoverned = !!(frontmatter && frontmatter.initiative && frontmatter.initiative === initResult.initiative);
+    if (isGoverned) {
+      governed++;
+    } else {
+      ungoverned++;
+    }
+
+    const enriched = {
+      filename: file.filename,
+      dir: file.dir,
+      fullPath: file.fullPath,
+      type: typeResult.type,
+      hcPrefix: typeResult.hcPrefix,
+      date: typeResult.date,
+      initiative: initResult.initiative,
+      frontmatter,
+      content,
+      isGoverned,
+      degradedMode: !isGoverned
+    };
+
+    if (!registry.has(initResult.initiative)) {
+      registry.set(initResult.initiative, []);
+    }
+    registry.get(initResult.initiative).push(enriched);
+  }
+
+  // FR39: warn if no governed artifacts
+  if (governed === 0 && mdFiles.length > 0) {
+    console.warn('Warning: No governed artifacts found. Run migration to populate.');
+  }
+
+  // Infer: run rule chain for each initiative in taxonomy
+  const allInitiatives = [...taxonomy.initiatives.platform, ...taxonomy.initiatives.user];
+  let results = [];
+
+  for (const initiative of allInitiatives) {
+    const artifacts = registry.get(initiative) || [];
+    let state = makeEmptyState(initiative);
+    state = applyFrontmatterRule(state, artifacts, { projectRoot });
+    state = applyArtifactChainRule(state, artifacts, { projectRoot });
+    state = applyGitRecencyRule(state, artifacts, { projectRoot, staleDays });
+    state = applyConflictResolver(state, artifacts, { projectRoot });
+    results.push(state);
+  }
+
+  // Sort
+  if (sort === 'last-activity') {
+    results.sort((a, b) => (b.lastArtifact.date || '').localeCompare(a.lastArtifact.date || ''));
+  } else {
+    results.sort((a, b) => a.initiative.localeCompare(b.initiative));
+  }
+
+  // Filter by initiative prefix (before WIP count)
+  if (filter) {
+    const prefix = filter.replace(/\*$/, '');
+    results = results.filter(s => s.initiative.startsWith(prefix));
+  }
+
+  // WIP radar: count active initiatives (ongoing, blocked, or stale)
+  const activeStatuses = ['ongoing', 'stale', 'blocked'];
+  const activeInitiatives = results.filter(s => activeStatuses.includes(s.status.value));
+  const wipRadar = activeInitiatives.length > wipThreshold
+    ? {
+      active: activeInitiatives.length,
+      threshold: wipThreshold,
+      initiatives: activeInitiatives
+        .sort((a, b) => (b.lastArtifact.date || '').localeCompare(a.lastArtifact.date || ''))
+        .map(s => s.initiative)
+    }
+    : null;
+
+  // Calculate governance health score (of attributable files only — excludes unattributed)
+  const attributable = governed + ungoverned;
+  const healthPercentage = attributable > 0 ? Math.round((governed / attributable) * 100) : 0;
+
+  return {
+    initiatives: results,
+    wipRadar,
+    summary: {
+      total: mdFiles.length,
+      governed,
+      ungoverned,
+      unattributed,
+      healthScore: { governed, total: attributable, percentage: healthPercentage }
+    }
+  };
+}
+
+// --- CLI ---
+
+function printHelp() {
+  console.log(`
+Usage: convoke-portfolio [options]
+
+Generate a portfolio view of all initiatives from artifact analysis.
+
+Options:
+  --terminal        Terminal table output (default)
+  --markdown        Markdown table output
+  --sort <mode>     Sort: alpha (default), last-activity
+  --filter <prefix> Filter initiatives by prefix (e.g., --filter gyre)
+  --verbose         Show inference trace per initiative (source + confidence)
+  --help, -h        Show this help
+
+Examples:
+  convoke-portfolio                      Default terminal view
+  convoke-portfolio --markdown           Markdown output for chat/docs
+  convoke-portfolio --sort last-activity Sort by most recent activity
+`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help') || args.includes('-h')) {
+    printHelp();
+    return;
+  }
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.error('Error: Not in a Convoke project. Could not find _bmad/ directory.');
+    process.exit(1);
+  }
+
+  const useMarkdown = args.includes('--markdown');
+  const useVerbose = args.includes('--verbose');
+  const sortMode = args.includes('--sort') && args[args.indexOf('--sort') + 1] === 'last-activity'
+    ? 'last-activity'
+    : 'alpha';
+  const filterIdx = args.indexOf('--filter');
+  const filterPattern = (filterIdx !== -1 && args[filterIdx + 1] && !args[filterIdx + 1].startsWith('--'))
+    ? args[filterIdx + 1]
+    : null;
+
+  // Read portfolio config from _bmad/bmm/config.yaml (optional)
+  let wipThreshold = 4;
+  let staleDays = 30;
+  try {
+    const yaml = require('js-yaml');
+    const configPath = path.join(projectRoot, '_bmad', 'bmm', 'config.yaml');
+    if (fs.existsSync(configPath)) {
+      const config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+      if (config && config.portfolio) {
+        const wt = Number(config.portfolio.wip_threshold);
+        if (!isNaN(wt)) wipThreshold = wt;
+        const sd = Number(config.portfolio.stale_days);
+        if (!isNaN(sd)) staleDays = sd;
+      }
+    }
+  } catch {
+    // Config read failed — use defaults
+  }
+
+  try {
+    const result = await generatePortfolio(projectRoot, {
+      sort: sortMode,
+      filter: filterPattern,
+      wipThreshold,
+      staleDays
+    });
+
+    const output = useMarkdown
+      ? formatMarkdown(result.initiatives)
+      : formatTerminal(result.initiatives);
+
+    console.log(output);
+
+    // WIP radar (only when threshold exceeded)
+    if (result.wipRadar) {
+      console.log(`\nWIP: ${result.wipRadar.active} active (threshold: ${result.wipRadar.threshold}) -- sorted by last activity`);
+      console.log(`  ${result.wipRadar.initiatives.join(', ')}`);
+    }
+
+    console.log(`\nTotal: ${result.summary.total} artifacts | Governed: ${result.summary.governed} | Ungoverned: ${result.summary.ungoverned} | Unattributed: ${result.summary.unattributed}`);
+    const hs = result.summary.healthScore;
+    console.log(`Governance: ${hs.governed}/${hs.total} artifacts governed (${hs.percentage}%)`);
+
+    // Verbose: inference trace per initiative
+    if (useVerbose) {
+      console.log('\n--- Inference Trace ---');
+      for (const s of result.initiatives) {
+        const p = s.phase;
+        const st = s.status;
+        console.log(`  [${s.initiative}] phase: ${p.value} (${p.source}, ${p.confidence}) | status: ${st.value} (${st.source}, ${st.confidence})`);
+      }
+    }
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = { generatePortfolio, makeEmptyState, EXCLUDE_DIRS };

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

@@ -0,0 +1,126 @@
+/**
+ * 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
+  state.phase = { value: 'unknown', source: 'artifact-chain', confidence: 'inferred' };
+  return state;
+}
+
+/**
+ * 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, DONE_PATTERNS };

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

@@ -0,0 +1,77 @@
+/**
+ * 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' };
+  }
+
+  // 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 };