eai-cli 0.0.0-bootstrap.0

package/resources/gofer/node-scripts/lib/marp-deck.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * marp-deck.mjs
+ *
+ * Optional Marp deck generator (FR-030). Reads `<featureDir>/visuals/*.md`
+ * in deterministic alphabetical order and emits a single Marp slide deck:
+ * Marp frontmatter, then each visual as its own slide, separated by `---`.
+ *
+ * Public API:
+ *   generateMarpDeck(featureDir, outputPath)
+ *     -> Promise<{ ok: true, slides: number, written: string } |
+ *                { ok: false, reason: string }>
+ *
+ * CLI usage:
+ *   node marp-deck.mjs <featureDir> <outputPath>
+ */
+
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const MARP_FRONTMATTER = `---
+marp: true
+theme: default
+paginate: true
+---
+`;
+
+/**
+ * @param {string} featureDir   Absolute path to the feature directory
+ * @param {string} outputPath   Absolute path for the .marp.md output
+ */
+export async function generateMarpDeck(featureDir, outputPath) {
+  const visualsDir = path.join(featureDir, 'visuals');
+
+  let entries;
+  try {
+    entries = await readdir(visualsDir, { withFileTypes: true });
+  } catch (err) {
+    if (err && /** @type {any} */ (err).code === 'ENOENT') {
+      return { ok: false, reason: 'visuals-dir-missing' };
+    }
+    return { ok: false, reason: `readdir-error: ${err.message}` };
+  }
+
+  const mdFiles = entries
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => e.name)
+    .sort(); // deterministic alphabetical order
+
+  if (mdFiles.length === 0) {
+    return { ok: false, reason: 'no-visuals' };
+  }
+
+  const slideContents = [];
+  for (const name of mdFiles) {
+    const raw = await readFile(path.join(visualsDir, name), 'utf8');
+    slideContents.push(raw.trimEnd());
+  }
+
+  const body = [MARP_FRONTMATTER, ...slideContents].join('\n\n---\n\n') + '\n';
+
+  await writeFile(outputPath, body, 'utf8');
+
+  return { ok: true, slides: slideContents.length, written: outputPath };
+}
+
+// CLI entrypoint
+const isMain =
+  process.argv[1] &&
+  (process.argv[1].endsWith('marp-deck.mjs') ||
+    process.argv[1] === new URL(import.meta.url).pathname);
+
+if (isMain) {
+  const [, , featureDir, outputPath] = process.argv;
+  if (!featureDir || !outputPath) {
+    console.error('Usage: marp-deck.mjs <featureDir> <outputPath>');
+    process.exit(1);
+  }
+  const result = await generateMarpDeck(path.resolve(featureDir), path.resolve(outputPath));
+  if (result.ok) {
+    console.log(`marp-deck: wrote ${result.written} (${result.slides} slides)`);
+    process.exit(0);
+  } else {
+    console.error(`marp-deck failed: ${result.reason}`);
+    process.exit(1);
+  }
+}

package/resources/gofer/node-scripts/lib/mermaid-tabular-fallback.mjs

@@ -0,0 +1,264 @@
+/**
+ * mermaid-tabular-fallback.mjs
+ *
+ * Provides a markdown-table fallback for Mermaid diagrams when the Mermaid
+ * renderer is unavailable, fails, or the consumer surface does not support
+ * Mermaid (e.g. plain-text release notes, terminal output).
+ *
+ * Supported chart types:
+ *   - quadrantChart   → | Item | X | Y | Quadrant |
+ *   - xychart-beta    → | X | Y |
+ *   - C4Context       → | Element | Type | Description |
+ *   - C4Container     → | Element | Type | Description |
+ *
+ * Usage:
+ *   import { tabularFallback } from './mermaid-tabular-fallback.mjs';
+ *   const md = tabularFallback(blockString, 'quadrantChart');
+ *
+ * If the input cannot be parsed for the declared chart type, the module
+ * returns a rescue block containing the original Mermaid source verbatim,
+ * preceded by a notice. This guarantees no information is lost.
+ */
+
+const SUPPORTED = new Set([
+  'xychart-beta',
+  'quadrantChart',
+  'C4Context',
+  'C4Container',
+]);
+
+/**
+ * Render a Mermaid block as a markdown-table fallback.
+ *
+ * @param {string} mermaidBlock The Mermaid source. May or may not be wrapped
+ *   in a ```` ```mermaid ```` code fence; the wrapper is stripped if present.
+ * @param {('xychart-beta'|'quadrantChart'|'C4Context'|'C4Container')} chartType
+ * @returns {string} Markdown table or a rescue block.
+ */
+export function tabularFallback(mermaidBlock, chartType) {
+  if (typeof mermaidBlock !== 'string' || mermaidBlock.length === 0) {
+    return rescue(mermaidBlock ?? '');
+  }
+  if (!SUPPORTED.has(chartType)) {
+    return rescue(mermaidBlock);
+  }
+
+  const source = stripFence(mermaidBlock);
+
+  try {
+    switch (chartType) {
+      case 'quadrantChart':
+        return renderQuadrant(source);
+      case 'xychart-beta':
+        return renderXyChart(source);
+      case 'C4Context':
+      case 'C4Container':
+        return renderC4(source);
+      default:
+        return rescue(mermaidBlock);
+    }
+  } catch (_err) {
+    return rescue(mermaidBlock);
+  }
+}
+
+export default tabularFallback;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function stripFence(input) {
+  const fenceRe = /^```mermaid\s*\n([\s\S]*?)\n```\s*$/m;
+  const m = input.match(fenceRe);
+  return m ? m[1] : input;
+}
+
+function rescue(original) {
+  const trimmed = (original ?? '').trimEnd();
+  return (
+    '_Diagram unavailable; see source._\n\n' +
+    '```\n' +
+    trimmed +
+    '\n```\n'
+  );
+}
+
+function nonEmptyLines(source) {
+  return source
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+}
+
+// ---------------------------------------------------------------------------
+// quadrantChart
+// ---------------------------------------------------------------------------
+
+/**
+ * Parses a Mermaid quadrantChart definition into a markdown table.
+ *
+ * Rows shaped like `Label: [0.3, 0.7]` are extracted. Quadrant assignment
+ * follows Mermaid's convention:
+ *   - x ≥ 0.5 && y ≥ 0.5 → quadrant-1 (declared)
+ *   - x <  0.5 && y ≥ 0.5 → quadrant-2
+ *   - x <  0.5 && y <  0.5 → quadrant-3
+ *   - x ≥ 0.5 && y <  0.5 → quadrant-4
+ */
+function renderQuadrant(source) {
+  const lines = nonEmptyLines(source);
+  if (lines.length === 0 || !lines[0].toLowerCase().startsWith('quadrantchart')) {
+    throw new Error('Not a quadrantChart');
+  }
+
+  const quadrantNames = { 1: 'Q1', 2: 'Q2', 3: 'Q3', 4: 'Q4' };
+  const ITEM_RE = /^([^:]+?):\s*\[\s*([0-9.]+)\s*,\s*([0-9.]+)\s*\]\s*$/;
+  const QUAD_DECL = /^quadrant-([1-4])\s+(.+)$/i;
+
+  const items = [];
+  for (const line of lines) {
+    const qmatch = line.match(QUAD_DECL);
+    if (qmatch) {
+      quadrantNames[Number(qmatch[1])] = qmatch[2].trim();
+      continue;
+    }
+    const im = line.match(ITEM_RE);
+    if (im) {
+      const label = im[1].trim();
+      const x = Number(im[2]);
+      const y = Number(im[3]);
+      items.push({ label, x, y });
+    }
+  }
+
+  let body =
+    '| Item | X | Y | Quadrant |\n' +
+    '|------|---|---|----------|\n';
+  if (items.length === 0) {
+    body += '| _none_ | _n/a_ | _n/a_ | _n/a_ |\n';
+    return body;
+  }
+  for (const it of items) {
+    const q = quadrantOf(it.x, it.y, quadrantNames);
+    body += `| ${escapeCell(it.label)} | ${it.x} | ${it.y} | ${escapeCell(q)} |\n`;
+  }
+  return body;
+}
+
+function quadrantOf(x, y, names) {
+  if (x >= 0.5 && y >= 0.5) return names[1];
+  if (x < 0.5 && y >= 0.5) return names[2];
+  if (x < 0.5 && y < 0.5) return names[3];
+  return names[4];
+}
+
+// ---------------------------------------------------------------------------
+// xychart-beta
+// ---------------------------------------------------------------------------
+
+/**
+ * Parses a Mermaid xychart-beta block. Extracts:
+ *   - x-axis labels: `x-axis [a, b, c]` or `x-axis "Title" [a, b, c]`
+ *   - bar/line series: `bar [n, n, ...]` / `line [n, n, ...]`
+ */
+function renderXyChart(source) {
+  const lines = nonEmptyLines(source);
+  if (lines.length === 0 || !lines[0].toLowerCase().startsWith('xychart-beta')) {
+    throw new Error('Not an xychart-beta');
+  }
+
+  const X_AXIS_RE = /^x-axis(?:\s+"[^"]*")?\s*\[([^\]]+)\]\s*$/i;
+  const SERIES_RE = /^(?:bar|line)\s+\[([^\]]+)\]\s*$/i;
+
+  let xLabels = [];
+  let yValues = [];
+  for (const line of lines) {
+    const xm = line.match(X_AXIS_RE);
+    if (xm) {
+      xLabels = splitArray(xm[1]).map(stripQuotes);
+      continue;
+    }
+    const sm = line.match(SERIES_RE);
+    if (sm && yValues.length === 0) {
+      yValues = splitArray(sm[1]).map(Number);
+    }
+  }
+
+  let body =
+    '| X | Y |\n' +
+    '|---|---|\n';
+
+  const rows = Math.max(xLabels.length, yValues.length);
+  if (rows === 0) {
+    body += '| _none_ | _n/a_ |\n';
+    return body;
+  }
+
+  for (let i = 0; i < rows; i += 1) {
+    const x = xLabels[i] ?? `_row ${i + 1}_`;
+    const y = yValues[i] ?? '_n/a_';
+    body += `| ${escapeCell(String(x))} | ${escapeCell(String(y))} |\n`;
+  }
+  return body;
+}
+
+function splitArray(inner) {
+  return inner
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+function stripQuotes(s) {
+  return s.replace(/^"(.*)"$/, '$1');
+}
+
+// ---------------------------------------------------------------------------
+// C4Context / C4Container
+// ---------------------------------------------------------------------------
+
+/**
+ * Parses Person/System/System_Ext/Container declarations into a table.
+ * Lines look like:
+ *   Person(alias, "label")
+ *   System(alias, "label")
+ *   System_Ext(alias, "label")
+ *   Container(alias, "label", "tech")
+ */
+function renderC4(source) {
+  const lines = nonEmptyLines(source);
+  if (lines.length === 0 || !/^c4(context|container)/i.test(lines[0])) {
+    throw new Error('Not a C4 block');
+  }
+
+  const ELEMENT_RE = /^(Person|Person_Ext|System|System_Ext|Container|Container_Ext|ContainerDb|SystemDb)\s*\(\s*([A-Za-z0-9_]+)\s*,\s*"([^"]*)"(?:\s*,\s*"([^"]*)")?\s*\)\s*$/;
+
+  const rows = [];
+  for (const line of lines) {
+    const m = line.match(ELEMENT_RE);
+    if (m) {
+      const type = m[1];
+      const alias = m[2];
+      const label = m[3];
+      const tech = m[4];
+      const desc = tech ? `${label} — ${tech}` : label;
+      rows.push({ alias, type, desc });
+    }
+  }
+
+  let body =
+    '| Element | Type | Description |\n' +
+    '|---------|------|-------------|\n';
+  if (rows.length === 0) {
+    body += '| _none_ | _n/a_ | _n/a_ |\n';
+    return body;
+  }
+  for (const r of rows) {
+    body += `| ${escapeCell(r.alias)} | ${escapeCell(r.type)} | ${escapeCell(r.desc)} |\n`;
+  }
+  return body;
+}
+
+function escapeCell(value) {
+  return String(value).replace(/\\/g, '\\\\').replace(/\|/g, '\\|');
+}

package/resources/gofer/node-scripts/lib/render-visual.mjs

@@ -0,0 +1,54 @@
+/**
+ * render-visual.mjs
+ *
+ * Simple template renderer for visual templates under
+ * `.specify/templates/visuals/`.
+ *
+ * - Reads a template file from disk.
+ * - Replaces every `{{KEY}}` token with `data[KEY]` when present.
+ * - Leaves unmatched `{{KEY}}` placeholders in place untouched.
+ * - Returns the rendered markdown as a string.
+ *
+ * Used by the two-pass canvas pipeline (visual-pass-pipeline.mjs) and
+ * directly by stage commands that need to produce visual artefacts.
+ */
+
+import { readFile } from 'node:fs/promises';
+
+const PLACEHOLDER_RE = /\{\{([A-Z0-9_]+)\}\}/g;
+
+/**
+ * Render a template by substituting `{{KEY}}` placeholders with values from
+ * `data`. Unmatched placeholders are preserved verbatim.
+ *
+ * @param {string} templatePath Absolute path to the template file.
+ * @param {Record<string, string|number>} data Substitution map keyed by
+ *   placeholder name (without braces).
+ * @returns {Promise<string>} Rendered markdown content.
+ */
+export async function renderVisual(templatePath, data = {}) {
+  const raw = await readFile(templatePath, 'utf8');
+  return renderString(raw, data);
+}
+
+/**
+ * Render an in-memory string with the same substitution rules. Exposed for
+ * tests and for callers that have already loaded the template (e.g. pass-2
+ * canvas refresh re-uses the existing on-disk artefact rather than the
+ * pristine template).
+ *
+ * @param {string} input Raw template content.
+ * @param {Record<string, string|number>} data Substitution map.
+ * @returns {string} Rendered string.
+ */
+export function renderString(input, data = {}) {
+  return input.replace(PLACEHOLDER_RE, (match, key) => {
+    if (Object.prototype.hasOwnProperty.call(data, key)) {
+      const value = data[key];
+      return value === undefined || value === null ? match : String(value);
+    }
+    return match;
+  });
+}
+
+export default renderVisual;

package/resources/gofer/node-scripts/lib/validate-aliases.mjs

@@ -0,0 +1,85 @@
+/**
+ * validate-aliases.mjs
+ *
+ * Loads all `.specify/commands/*.md` source-of-truth files (via parseStageCommand)
+ * and validates that every alias and `name` is unique across the set.
+ *
+ * Used by `tests/unit/scripts/alias-uniqueness.test.ts` and by the source-of-truth
+ * generator's pre-flight check (so we never emit two providers that claim the same
+ * `gofer:*` namespace).
+ *
+ * Public API:
+ *   loadStages(commandsDir)
+ *     -> Promise<Array<{ filePath, name, aliases }>>
+ *
+ *   validateAliases(stages)
+ *     -> { ok: boolean, conflicts: Array<{ alias, owners: string[] }> }
+ *
+ * The two are split so tests can feed synthetic stage arrays into validateAliases
+ * without touching the filesystem.
+ */
+
+import { readdir } from 'fs/promises';
+import path from 'path';
+import { parseStageCommand } from '../parse-stage-command.mjs';
+
+/**
+ * Load every `.md` file in `commandsDir` (non-recursive) and return a normalized
+ * stage descriptor: { filePath, name, aliases }.
+ *
+ * @param {string} commandsDir Absolute path to `.specify/commands`
+ * @returns {Promise<Array<{ filePath: string, name: string, aliases: string[] }>>}
+ */
+export async function loadStages(commandsDir) {
+  const entries = await readdir(commandsDir, { withFileTypes: true });
+  const mdFiles = entries
+    .filter((e) => e.isFile() && e.name.endsWith('.md'))
+    .map((e) => path.join(commandsDir, e.name));
+
+  const stages = [];
+  for (const filePath of mdFiles) {
+    const { frontmatter } = await parseStageCommand(filePath);
+    const aliases = Array.isArray(frontmatter.aliases) ? frontmatter.aliases : [];
+    stages.push({
+      filePath,
+      name: String(frontmatter.name),
+      aliases,
+    });
+  }
+  return stages;
+}
+
+/**
+ * Detect duplicate identifiers across a set of stages.
+ *
+ * The "identifier set" for a stage is its `name` plus every entry in its
+ * `aliases` array. Two stages may not share any identifier; if they do, the
+ * conflict is reported.
+ *
+ * @param {Array<{ filePath: string, name: string, aliases: string[] }>} stages
+ * @returns {{ ok: boolean, conflicts: Array<{ alias: string, owners: string[] }> }}
+ */
+export function validateAliases(stages) {
+  /** @type {Map<string, string[]>} */
+  const owners = new Map();
+
+  for (const stage of stages) {
+    const ids = [stage.name, ...stage.aliases];
+    for (const id of ids) {
+      if (!id) continue;
+      if (!owners.has(id)) {
+        owners.set(id, []);
+      }
+      owners.get(id).push(stage.filePath);
+    }
+  }
+
+  const conflicts = [];
+  for (const [alias, files] of owners.entries()) {
+    if (files.length > 1) {
+      conflicts.push({ alias, owners: files });
+    }
+  }
+
+  return { ok: conflicts.length === 0, conflicts };
+}

package/resources/gofer/node-scripts/lib/visual-counts.mjs

@@ -0,0 +1,44 @@
+/**
+ * visual-counts.mjs
+ *
+ * Walks a TO-BE value-stream markdown document and counts how many steps
+ * carry each AI-leverage verb tag (Replace / Augment / Automate / Observe).
+ *
+ * The convention enforced by `visual-value-stream-writer` and the persona-pack
+ * gate is that every TO-BE step renders the verb inline as `AI: <Verb>` —
+ * either inside a Mermaid node (`S1[Step text<br/>AI: Augment]`) or in the
+ * surrounding markdown. This function detects the inline tag with a
+ * case-insensitive regex and returns a totals object suitable for feeding
+ * directly into the Impact Canvas pie chart.
+ */
+
+import { VERBS, validateVerb } from './ai-leverage-tagger.mjs';
+
+const TAG_RE = /AI:\s*(Replace|Augment|Automate|Observe)\b/gi;
+
+/**
+ * Count AI-leverage verbs in a TO-BE value-stream markdown string.
+ *
+ * @param {string} valueStreamMarkdown Raw markdown content of `value-stream-tobe.md`.
+ * @returns {{ replace: number, augment: number, automate: number, observe: number }}
+ *   Totals keyed by lowercased verb name. Missing verbs are reported as 0.
+ */
+export function countVerbs(valueStreamMarkdown) {
+  const totals = { replace: 0, augment: 0, automate: 0, observe: 0 };
+  if (typeof valueStreamMarkdown !== 'string' || valueStreamMarkdown.length === 0) {
+    return totals;
+  }
+
+  for (const match of valueStreamMarkdown.matchAll(TAG_RE)) {
+    const raw = match[1];
+    const canonical = raw.charAt(0).toUpperCase() + raw.slice(1).toLowerCase();
+    validateVerb(canonical); // Defensive: never count a non-canonical verb.
+    const key = canonical.toLowerCase();
+    totals[key] += 1;
+  }
+
+  return totals;
+}
+
+export { VERBS };
+export default countVerbs;

package/resources/gofer/node-scripts/lib/visual-pass-pipeline.mjs

@@ -0,0 +1,134 @@
+/**
+ * visual-pass-pipeline.mjs
+ *
+ * Two-pass canvas pipeline for the Impact Canvas visual.
+ *
+ * Pass 1 runs inside `/2_gofer_specify`: a fresh `impact-canvas.md` is
+ * rendered from the template using heuristic risks pulled from the spec's
+ * NFR + Out-of-Scope sections.
+ *
+ * Pass 2 runs inside `/6_gofer_validate`: the existing `impact-canvas.md` is
+ * read back, and ONLY the "Top Three Risks" block is rewritten with the
+ * validation council's output. Every other byte (header, problem statement,
+ * personas, AI-leverage pie, outcomes) is preserved.  The frontmatter
+ * `pass:` marker is bumped from 1 to 2 so consumers can tell which pass
+ * produced the artefact.
+ */
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { renderVisual } from './render-visual.mjs';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_PATH = path.resolve(
+  __dirname,
+  '../../../templates/visuals/impact-canvas.md'
+);
+
+// Match the full "## Top Three Risks" section greedily, stopping at the next
+// `## ` heading or end-of-file. Using a greedy `[\s\S]*` plus a positive
+// lookahead avoids the degenerate non-greedy zero-width match that would
+// only consume the heading itself.
+const RISKS_BLOCK_RE = /## Top Three Risks[\s\S]*?(?=\n## |$)/;
+
+/**
+ * Build the canonical "Top Three Risks" markdown block from a list of risks.
+ *
+ * @param {string[]} risks Array of three risk descriptions.
+ * @param {'pass-1'|'pass-2'} source Which pass produced the risks.
+ * @returns {string} Markdown block ending without a trailing blank line.
+ */
+function buildRisksBlock(risks, source) {
+  const safeRisks = [risks[0] ?? '', risks[1] ?? '', risks[2] ?? ''];
+  const passComment =
+    source === 'pass-2'
+      ? '<!-- pass-2: validation council output -->'
+      : '<!-- pass-1: heuristic from spec NFRs and Out-of-Scope -->';
+  return [
+    '## Top Three Risks',
+    passComment,
+    `1. ${safeRisks[0]}`,
+    `2. ${safeRisks[1]}`,
+    `3. ${safeRisks[2]}`,
+    '',
+  ].join('\n');
+}
+
+/**
+ * Pass 1 — render a complete Impact Canvas with heuristic risks.
+ *
+ * @param {string} featureDir Absolute path to `.specify/specs/<feature>/`.
+ * @param {object} specData Substitution payload.
+ * @param {string} specData.FEATURE_NAME
+ * @param {string} specData.DATE  ISO date string.
+ * @param {string} specData.PROBLEM_STATEMENT
+ * @param {string} specData.PERSONA_LIST
+ * @param {number} specData.REPLACE_COUNT
+ * @param {number} specData.AUGMENT_COUNT
+ * @param {number} specData.AUTOMATE_COUNT
+ * @param {number} specData.OBSERVE_COUNT
+ * @param {string[]} specData.HEURISTIC_RISKS  Length-3 array.
+ * @param {string} specData.OUTCOMES
+ * @returns {Promise<string>} Absolute path of the written canvas.
+ */
+export async function runPass1(featureDir, specData) {
+  const visualsDir = path.join(featureDir, 'visuals');
+  await mkdir(visualsDir, { recursive: true });
+
+  const data = {
+    PASS: 1,
+    FEATURE_NAME: specData.FEATURE_NAME ?? '',
+    DATE: specData.DATE ?? new Date().toISOString().slice(0, 10),
+    PROBLEM_STATEMENT: specData.PROBLEM_STATEMENT ?? '',
+    PERSONA_LIST: specData.PERSONA_LIST ?? '',
+    REPLACE_COUNT: specData.REPLACE_COUNT ?? 0,
+    AUGMENT_COUNT: specData.AUGMENT_COUNT ?? 0,
+    AUTOMATE_COUNT: specData.AUTOMATE_COUNT ?? 0,
+    OBSERVE_COUNT: specData.OBSERVE_COUNT ?? 0,
+    RISK_1: (specData.HEURISTIC_RISKS ?? [])[0] ?? '',
+    RISK_2: (specData.HEURISTIC_RISKS ?? [])[1] ?? '',
+    RISK_3: (specData.HEURISTIC_RISKS ?? [])[2] ?? '',
+    OUTCOMES: specData.OUTCOMES ?? '',
+  };
+
+  const rendered = await renderVisual(TEMPLATE_PATH, data);
+  const outPath = path.join(visualsDir, 'impact-canvas.md');
+  await writeFile(outPath, rendered, 'utf8');
+  return outPath;
+}
+
+/**
+ * Pass 2 — re-read the existing canvas, swap ONLY the Top Three Risks block,
+ * and bump the `pass:` field. Throws if `impact-canvas.md` does not exist.
+ *
+ * @param {string} featureDir Absolute path to `.specify/specs/<feature>/`.
+ * @param {object} validationData
+ * @param {string[]} validationData.VALIDATED_RISKS Length-3 array from the
+ *   validation council.
+ * @returns {Promise<string>} Absolute path of the rewritten canvas.
+ */
+export async function runPass2(featureDir, validationData) {
+  const canvasPath = path.join(featureDir, 'visuals', 'impact-canvas.md');
+  const original = await readFile(canvasPath, 'utf8');
+
+  const risks = validationData?.VALIDATED_RISKS ?? [];
+  const newBlock = buildRisksBlock(risks, 'pass-2');
+
+  if (!RISKS_BLOCK_RE.test(original)) {
+    throw new Error(
+      `runPass2: impact-canvas.md at ${canvasPath} is missing the "## Top Three Risks" section`
+    );
+  }
+
+  let updated = original.replace(RISKS_BLOCK_RE, `${newBlock}\n`);
+
+  // Bump `pass:` field in frontmatter from 1 to 2 (or any other digit -> 2).
+  updated = updated.replace(/^(pass:\s*).*$/m, `$12`);
+
+  await writeFile(canvasPath, updated, 'utf8');
+  return canvasPath;
+}
+
+export default { runPass1, runPass2 };