forgesmith 0.7.0 → 0.7.1

package/dist/index.cjs

@@ -2844,6 +2844,583 @@ async function generateKnowledgeCapture(options) {
   return buildFallback7(options);
 }
 
+// src/generators/generateApiChangelog.ts
+function buildPromptContext(opts) {
+  const { apiChangeContext: ctx, amberContext, gitContext } = opts;
+  const lines = [
+    `## Change Range`,
+    `From: ${ctx.from}  To: ${ctx.to}`,
+    `Total API changes: ${ctx.totalChanged}`,
+    ``
+  ];
+  if (ctx.breakingChanges.length > 0) {
+    lines.push(`## Breaking Changes (${ctx.breakingChanges.length})`);
+    for (const c of ctx.breakingChanges) {
+      const capHint = c.capabilityName ? ` [${c.capabilityName}]` : "";
+      lines.push(`- ${c.endpoint}${capHint} \u2014 ${c.description ?? "no description"} (file: ${c.file})`);
+    }
+    lines.push("");
+  }
+  if (ctx.newEndpoints.length > 0) {
+    lines.push(`## New Endpoints (${ctx.newEndpoints.length})`);
+    for (const c of ctx.newEndpoints) {
+      const capHint = c.capabilityName ? ` [${c.capabilityName}]` : "";
+      lines.push(`- ${c.endpoint}${capHint} \u2014 ${c.description ?? "new"} (file: ${c.file})`);
+    }
+    lines.push("");
+  }
+  if (ctx.removedEndpoints.length > 0) {
+    lines.push(`## Removed Endpoints (${ctx.removedEndpoints.length})`);
+    for (const c of ctx.removedEndpoints) {
+      lines.push(`- ${c.endpoint} \u2014 removed from ${c.file}`);
+    }
+    lines.push("");
+  }
+  const modified = ctx.changes.filter((c) => c.changeType === "modified");
+  if (modified.length > 0) {
+    lines.push(`## Modified Endpoints (${modified.length})`);
+    for (const c of modified) {
+      const capHint = c.capabilityName ? ` [${c.capabilityName}]` : "";
+      lines.push(`- ${c.endpoint}${capHint} \u2014 ${c.description ?? "modified"} (file: ${c.file})`);
+    }
+    lines.push("");
+  }
+  if (amberContext) {
+    lines.push(`## AMBER Capability Context`, amberContext.summary, "");
+  }
+  if (gitContext && gitContext.commitMessages.length > 0) {
+    lines.push(
+      `## Recent Commits`,
+      ...gitContext.commitMessages.slice(0, 8).map((m) => `- ${m}`),
+      ""
+    );
+  }
+  return lines.join("\n");
+}
+function buildSystemPrompt14(audience, format) {
+  const audienceDesc = audience === "external" ? "external API consumers (third-party developers)" : audience === "partner" ? "integration partners with existing API contracts" : "internal engineering teams";
+  const formatDesc = format === "migration-guide" ? "a step-by-step migration guide with code examples" : format === "release-notes" ? "polished release notes suitable for a public changelog page" : "a structured API changelog";
+  return `You are a developer relations engineer writing ${formatDesc} for ${audienceDesc}. Be precise about endpoint paths, HTTP methods, and request/response changes. For breaking changes, always include a migration path. Generate ONLY valid JSON \u2014 no markdown fences, no prose outside the JSON object.`;
+}
+function buildUserPrompt14(opts, context) {
+  const { projectName, version, targetAudience, format } = opts;
+  const v = version || opts.apiChangeContext.to;
+  return [
+    `Generate an API ${format} for: ${projectName}`,
+    `Version: ${v}`,
+    `Target audience: ${targetAudience}`,
+    `Format: ${format}`,
+    ``,
+    context,
+    ``,
+    `## Output Format`,
+    `Return a single JSON object with this EXACT shape:`,
+    `{`,
+    `  "version": "<version string>",`,
+    `  "date": "<ISO date YYYY-MM-DD>",`,
+    `  "targetAudience": "<audience>",`,
+    `  "breakingChanges": [`,
+    `    { "endpoint": "<METHOD /path>", "description": "<what changed>", "migration": "<how to migrate>" }`,
+    `  ],`,
+    `  "newFeatures": [`,
+    `    { "endpoint": "<METHOD /path>", "description": "<what it does>", "example": "<optional curl/code hint>" }`,
+    `  ],`,
+    `  "improvements": [`,
+    `    { "endpoint": "<METHOD /path>", "description": "<what improved>" }`,
+    `  ],`,
+    `  "deprecations": [`,
+    `    { "endpoint": "<METHOD /path>", "description": "<what is deprecated>", "sunset": "<optional date>" }`,
+    `  ],`,
+    `  "migrationGuide": "<full migration guidance as prose \u2014 2\u20135 paragraphs>",`,
+    `  "consumerImpactSummary": "<1 paragraph copy-ready summary for consumers>"`,
+    `}`,
+    ``,
+    `Rules:`,
+    `- Every breaking change MUST have a non-empty migration string.`,
+    `- For external/partner audiences, omit internal implementation details.`,
+    `- migrationGuide should be empty string if no breaking changes.`,
+    `- Return ONLY valid JSON. No markdown fences.`
+  ].join("\n");
+}
+function buildFallback8(opts) {
+  const ctx = opts.apiChangeContext;
+  const v = opts.version ?? ctx.to;
+  return {
+    version: v,
+    date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    targetAudience: opts.targetAudience,
+    breakingChanges: ctx.breakingChanges.map((c) => ({
+      endpoint: c.endpoint,
+      description: c.description ?? "Breaking change detected",
+      migration: "Review the updated API contract and update your client accordingly."
+    })),
+    newFeatures: ctx.newEndpoints.map((c) => ({
+      endpoint: c.endpoint,
+      description: c.description ?? "New endpoint added"
+    })),
+    improvements: ctx.changes.filter((c) => c.changeType === "modified").map((c) => ({
+      endpoint: c.endpoint,
+      description: c.description ?? "Endpoint updated"
+    })),
+    deprecations: ctx.removedEndpoints.map((c) => ({
+      endpoint: c.endpoint,
+      description: "This endpoint has been removed."
+    })),
+    migrationGuide: ctx.breakingChanges.length > 0 ? `This release contains ${ctx.breakingChanges.length} breaking change(s). Review the breaking changes section and update your API client before deploying. Test all affected endpoints in a staging environment.` : "",
+    consumerImpactSummary: `Version ${v} includes ${ctx.newEndpoints.length} new endpoint(s), ${ctx.breakingChanges.length} breaking change(s), and ${ctx.changes.filter((c) => c.changeType === "modified").length} improvement(s). ` + (ctx.breakingChanges.length > 0 ? "Migration is required before upgrading." : "This release is backward-compatible.")
+  };
+}
+function parseLlmResponse8(raw) {
+  let text = raw.trim();
+  if (text.startsWith("```")) {
+    text = text.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "").trim();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  function parseChangeArray(key, required) {
+    if (!Array.isArray(parsed[key])) return [];
+    return parsed[key].filter((item) => {
+      if (typeof item !== "object" || item === null) return false;
+      return required.every((k) => k in item);
+    });
+  }
+  return {
+    version: typeof parsed.version === "string" ? parsed.version : "",
+    date: typeof parsed.date === "string" ? parsed.date : (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    targetAudience: typeof parsed.targetAudience === "string" ? parsed.targetAudience : "",
+    breakingChanges: parseChangeArray("breakingChanges", ["endpoint", "description", "migration"]),
+    newFeatures: parseChangeArray("newFeatures", ["endpoint", "description"]),
+    improvements: parseChangeArray("improvements", ["endpoint", "description"]),
+    deprecations: parseChangeArray("deprecations", ["endpoint", "description"]),
+    migrationGuide: typeof parsed.migrationGuide === "string" ? parsed.migrationGuide : "",
+    consumerImpactSummary: typeof parsed.consumerImpactSummary === "string" ? parsed.consumerImpactSummary : ""
+  };
+}
+async function generateApiChangelog(opts) {
+  const context = buildPromptContext(opts);
+  try {
+    const response = await opts.llm.complete({
+      systemPrompt: buildSystemPrompt14(opts.targetAudience, opts.format),
+      messages: [{ role: "user", content: buildUserPrompt14(opts, context) }],
+      maxTokens: 3072
+    });
+    const parsed = parseLlmResponse8(response.content);
+    if (parsed) return parsed;
+  } catch {
+  }
+  return buildFallback8(opts);
+}
+
+// src/generators/generateChangeImpactBrief.ts
+function buildPromptContext2(opts) {
+  const { gitContext, changeImpactContext: ctx, amberContext, greenContext } = opts;
+  const lines = [
+    `## Change Range`,
+    `From: ${ctx.from}`,
+    `To:   ${ctx.to}`,
+    `Commits: ${ctx.commitCount}`,
+    `Files changed: ${ctx.filesChanged.length}`,
+    ``,
+    `## Changed Files (sample)`,
+    ...ctx.filesChanged.slice(0, 20).map((f) => `- ${f}`)
+  ];
+  if (ctx.breakingChanges.length > 0) {
+    lines.push(``, `## Breaking Changes`, ...ctx.breakingChanges.map((b) => `- ${b}`));
+  }
+  if (ctx.affectedCapabilities.length > 0) {
+    lines.push(``, `## Affected Business Capabilities`);
+    for (const cap of ctx.affectedCapabilities) {
+      lines.push(
+        `- [${cap.criticality.toUpperCase()}] ${cap.name} (${cap.changedFiles.length} files changed, drift: ${cap.driftCount})`
+      );
+    }
+  }
+  if (ctx.regulatoryCapabilities.length > 0) {
+    lines.push(
+      ``,
+      `## Critical Capabilities Touched (require approval)`,
+      ...ctx.regulatoryCapabilities.map((c) => `- ${c}`)
+    );
+  }
+  if (ctx.coherenceScoreBefore !== null || ctx.coherenceScoreAfter !== null) {
+    lines.push(
+      ``,
+      `## Architecture Coherence`,
+      `Score before: ${ctx.coherenceScoreBefore ?? "unknown"}`,
+      `Score after:  ${ctx.coherenceScoreAfter ?? "unknown"}`,
+      `Delta:        ${ctx.coherenceDelta !== null ? (ctx.coherenceDelta > 0 ? "+" : "") + ctx.coherenceDelta : "unknown"}`
+    );
+  }
+  if (ctx.topRisks.length > 0) {
+    lines.push(``, `## Top Risks`, ...ctx.topRisks.map((r) => `- ${r}`));
+  }
+  if (amberContext) {
+    lines.push(``, `## AMBER Layer Context`, amberContext.summary);
+  }
+  if (greenContext) {
+    lines.push(``, `## GREEN Layer Context`, greenContext.summary);
+  }
+  if (gitContext.commitMessages.length > 0) {
+    lines.push(
+      ``,
+      `## Recent Commit Messages (sample)`,
+      ...gitContext.commitMessages.slice(0, 10).map((m) => `- ${m}`)
+    );
+  }
+  return lines.join("\n");
+}
+function buildSystemPrompt15(audience) {
+  if (audience === "executive") {
+    return "You are a VP of Engineering preparing a release briefing for the CTO and board. Write in plain business language \u2014 no jargon, no technical acronyms. Be direct about risks. Generate ONLY valid JSON \u2014 no markdown fences, no prose outside the JSON.";
+  }
+  if (audience === "cab") {
+    return "You are a senior engineering manager preparing a Change Advisory Board (CAB) submission. Balance technical precision with business impact. Highlight rollback complexity and compliance implications. Generate ONLY valid JSON \u2014 no markdown fences, no prose outside the JSON.";
+  }
+  return "You are a principal engineer preparing a technical change impact brief. Be precise about files, capabilities, and risk vectors. Generate ONLY valid JSON \u2014 no markdown fences, no prose outside the JSON.";
+}
+function buildUserPrompt15(opts, context) {
+  const { projectName, releaseVersion, audience } = opts;
+  const version = releaseVersion || opts.changeImpactContext.to;
+  return [
+    `Generate a change impact brief for: ${projectName}`,
+    `Release version: ${version}`,
+    `Audience: ${audience}`,
+    ``,
+    context,
+    ``,
+    `## Output Format`,
+    `Return a single JSON object with this EXACT shape:`,
+    `{`,
+    `  "title": "<brief title>",`,
+    `  "releaseVersion": "<version string>",`,
+    `  "date": "<ISO date>",`,
+    `  "audience": "<audience>",`,
+    `  "executiveSummary": "<3 bullet points separated by \\n, plain language, max 120 chars each>",`,
+    `  "technicalSummary": "<2-3 sentences for CAB technical reviewers>",`,
+    `  "affectedBusinessAreas": ["<area 1>", "<area 2>"],`,
+    `  "riskLevel": "<one of: low | medium | high | critical>",`,
+    `  "riskJustification": "<1-2 sentences explaining the risk rating>",`,
+    `  "complianceImpact": "<which regulated capabilities are touched, or 'None' if clean>",`,
+    `  "rollbackComplexity": "<one of: simple | moderate | complex>",`,
+    `  "rollbackGuidance": "<concise rollback instructions>",`,
+    `  "recommendedActions": ["<action 1>", "<action 2>", "<action 3>"],`,
+    `  "approvalRequired": <true | false>,`,
+    `  "metrics": {`,
+    `    "commits": <number>,`,
+    `    "filesChanged": <number>,`,
+    `    "capabilitiesAffected": <number>,`,
+    `    "coherenceDelta": <number | null>`,
+    `  }`,
+    `}`,
+    ``,
+    `Rules:`,
+    `- riskLevel = "critical" if any critical capabilities touched OR breaking changes exist.`,
+    `- riskLevel = "high" if 3+ capabilities affected or coherenceDelta < -5.`,
+    `- approvalRequired = true if riskLevel is "critical" or "high".`,
+    `- rollbackComplexity = "complex" if breaking changes or critical capabilities touched.`,
+    `- executiveSummary must be EXACTLY 3 bullet lines joined by \\n \u2014 each starting with a dash.`,
+    `- Return ONLY valid JSON. No markdown. No prose outside the JSON object.`
+  ].join("\n");
+}
+function buildFallback9(opts) {
+  const ctx = opts.changeImpactContext;
+  const hasCritical = ctx.regulatoryCapabilities.length > 0 || ctx.breakingChanges.length > 0;
+  const hasHigh = ctx.affectedCapabilities.filter((c) => c.criticality === "high").length >= 2;
+  const riskLevel = hasCritical ? "critical" : hasHigh || ctx.affectedCapabilities.length >= 3 ? "high" : ctx.affectedCapabilities.length >= 1 ? "medium" : "low";
+  const approvalRequired = riskLevel === "critical" || riskLevel === "high";
+  const rollbackComplexity = hasCritical ? "complex" : ctx.affectedCapabilities.length >= 3 ? "moderate" : "simple";
+  return {
+    title: `Change Impact Brief \u2014 ${opts.projectName}`,
+    releaseVersion: opts.releaseVersion ?? ctx.to,
+    date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    audience: opts.audience,
+    executiveSummary: `- ${ctx.commitCount} commit(s) deployed across ${ctx.filesChanged.length} files
+- ${ctx.affectedCapabilities.length} business capability(ies) affected
+- Risk level: ${riskLevel.toUpperCase()}${hasCritical ? " \u2014 critical capabilities touched" : ""}`,
+    technicalSummary: `${ctx.commitCount} commit(s) between ${ctx.from} and ${ctx.to}, changing ${ctx.filesChanged.length} file(s). ` + (ctx.breakingChanges.length > 0 ? `${ctx.breakingChanges.length} breaking change(s) detected. ` : "") + (ctx.coherenceDelta !== null ? `Coherence score moved ${ctx.coherenceDelta > 0 ? "+" : ""}${ctx.coherenceDelta}.` : ""),
+    affectedBusinessAreas: ctx.affectedCapabilities.map((c) => c.name),
+    riskLevel,
+    riskJustification: hasCritical ? "Critical business capabilities were modified, requiring formal CAB sign-off." : `${ctx.affectedCapabilities.length} capabilities affected with potential for regression.`,
+    complianceImpact: ctx.regulatoryCapabilities.length > 0 ? ctx.regulatoryCapabilities.join(", ") : "None",
+    rollbackComplexity,
+    rollbackGuidance: rollbackComplexity === "complex" ? "Prepare a full environment snapshot before deploying. Coordinate rollback with database team if schema changes exist." : rollbackComplexity === "moderate" ? "Tag the current deployment. Roll back using git revert on the merge commit." : "Revert the feature flag or redeploy the previous container image.",
+    recommendedActions: [
+      approvalRequired ? "Obtain formal CAB sign-off before deploying to production" : "Deploy during low-traffic window",
+      ctx.breakingChanges.length > 0 ? "Notify API consumers of breaking changes at least 48h in advance" : "Run full regression suite",
+      "Monitor error rates and coherence score for 30 minutes post-deploy"
+    ],
+    approvalRequired,
+    metrics: {
+      commits: ctx.commitCount,
+      filesChanged: ctx.filesChanged.length,
+      capabilitiesAffected: ctx.affectedCapabilities.length,
+      coherenceDelta: ctx.coherenceDelta
+    }
+  };
+}
+var RISK_LEVELS = ["low", "medium", "high", "critical"];
+var ROLLBACK_LEVELS = ["simple", "moderate", "complex"];
+function parseLlmResponse9(raw) {
+  let text = raw.trim();
+  if (text.startsWith("```")) {
+    text = text.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "").trim();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const riskLevel = RISK_LEVELS.includes(parsed.riskLevel) ? parsed.riskLevel : "medium";
+  const rollbackComplexity = ROLLBACK_LEVELS.includes(
+    parsed.rollbackComplexity
+  ) ? parsed.rollbackComplexity : "moderate";
+  const recommendedActions = Array.isArray(parsed.recommendedActions) ? parsed.recommendedActions.filter((a) => typeof a === "string") : [];
+  const affectedBusinessAreas = Array.isArray(parsed.affectedBusinessAreas) ? parsed.affectedBusinessAreas.filter((a) => typeof a === "string") : [];
+  const metricsRaw = parsed.metrics && typeof parsed.metrics === "object" ? parsed.metrics : {};
+  return {
+    title: typeof parsed.title === "string" ? parsed.title : "Change Impact Brief",
+    releaseVersion: typeof parsed.releaseVersion === "string" ? parsed.releaseVersion : "",
+    date: typeof parsed.date === "string" ? parsed.date : (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
+    audience: typeof parsed.audience === "string" ? parsed.audience : "",
+    executiveSummary: typeof parsed.executiveSummary === "string" ? parsed.executiveSummary : "",
+    technicalSummary: typeof parsed.technicalSummary === "string" ? parsed.technicalSummary : "",
+    affectedBusinessAreas,
+    riskLevel,
+    riskJustification: typeof parsed.riskJustification === "string" ? parsed.riskJustification : "",
+    complianceImpact: typeof parsed.complianceImpact === "string" ? parsed.complianceImpact : "None",
+    rollbackComplexity,
+    rollbackGuidance: typeof parsed.rollbackGuidance === "string" ? parsed.rollbackGuidance : "",
+    recommendedActions,
+    approvalRequired: parsed.approvalRequired === true,
+    metrics: {
+      commits: typeof metricsRaw.commits === "number" ? metricsRaw.commits : 0,
+      filesChanged: typeof metricsRaw.filesChanged === "number" ? metricsRaw.filesChanged : 0,
+      capabilitiesAffected: typeof metricsRaw.capabilitiesAffected === "number" ? metricsRaw.capabilitiesAffected : 0,
+      coherenceDelta: typeof metricsRaw.coherenceDelta === "number" ? metricsRaw.coherenceDelta : null
+    }
+  };
+}
+async function generateChangeImpactBrief(opts) {
+  const context = buildPromptContext2(opts);
+  try {
+    const response = await opts.llm.complete({
+      systemPrompt: buildSystemPrompt15(opts.audience),
+      messages: [{ role: "user", content: buildUserPrompt15(opts, context) }],
+      maxTokens: 2048
+    });
+    const parsed = parseLlmResponse9(response.content);
+    if (parsed) return parsed;
+  } catch {
+  }
+  return buildFallback9(opts);
+}
+
+// src/generators/generateRoiSlide.ts
+var CURRENCY_SYMBOL = {
+  EUR: "\u20AC",
+  USD: "$",
+  GBP: "\xA3"
+};
+function fmtK(n, sym) {
+  if (n >= 1e6) return `${sym}${(n / 1e6).toFixed(1)}M`;
+  if (n >= 1e3) return `${sym}${Math.round(n / 1e3)}k`;
+  return `${sym}${Math.round(n)}`;
+}
+function buildFallback10(opts) {
+  const { roiEstimate: r, organizationName, currency } = opts;
+  const sym = CURRENCY_SYMBOL[currency] ?? "\u20AC";
+  const org = organizationName ?? "Your Organization";
+  const costYr = fmtK(r.maintenanceCostPerYear, sym);
+  const saveYr = fmtK(r.savedCostPerYear, sym);
+  const saveMo = fmtK(r.savedCostPerMonth, sym);
+  const slides = [
+    {
+      type: "title",
+      title: "Technical Debt Cost Analysis",
+      content: `${org} \xB7 Architecture Health Report \xB7 ${(/* @__PURE__ */ new Date()).toLocaleDateString("en-GB", { month: "long", year: "numeric" })}`,
+      highlight: r.currentGrade,
+      highlightLabel: "Current Architecture Grade"
+    },
+    {
+      type: "problem",
+      title: "The Hidden Cost of Architecture Debt",
+      content: `Your codebase currently has grade ${r.currentGrade} (${r.currentScore}/100). This translates directly to developer time lost to maintenance overhead every month.`,
+      highlight: fmtK(r.maintenanceCostPerMonth, sym),
+      highlightLabel: "Estimated monthly maintenance cost",
+      bullets: [
+        `Import cycles: ${r.breakdown.importCycles.count} cycles consuming ${r.breakdown.importCycles.hoursPerMonth}h/mo`,
+        `Documentation drift: ${r.breakdown.documentationDrift.count} drifted capabilities \u2014 ${r.breakdown.documentationDrift.hoursPerMonth}h/mo in context-searching`,
+        `High-churn files: ${r.breakdown.highChurnFiles.count} hot files adding ${r.breakdown.highChurnFiles.hoursPerMonth}h/mo in review overhead`,
+        `Orphaned capabilities: ${r.breakdown.orphanedCode.count} untracked modules \u2014 ${r.breakdown.orphanedCode.hoursPerMonth}h/mo wasted`
+      ]
+    },
+    {
+      type: "cost-breakdown",
+      title: "Where Developer Time Goes",
+      content: `Total: ${r.estimatedMaintenanceHoursPerMonth}h/month in maintenance overhead = ${costYr}/year at current state`,
+      bullets: [
+        `Import cycles \u2192 ${fmtK(r.breakdown.importCycles.cost, sym)}/mo (${r.breakdown.importCycles.hoursPerMonth}h debugging)`,
+        `Doc drift \u2192 ${fmtK(r.breakdown.documentationDrift.cost, sym)}/mo (${r.breakdown.documentationDrift.hoursPerMonth}h searching context)`,
+        `Churn overhead \u2192 ${fmtK(r.breakdown.highChurnFiles.cost, sym)}/mo (${r.breakdown.highChurnFiles.hoursPerMonth}h in review)`,
+        `Orphaned code \u2192 ${fmtK(r.breakdown.orphanedCode.cost, sym)}/mo (${r.breakdown.orphanedCode.hoursPerMonth}h ownership gaps)`
+      ]
+    },
+    {
+      type: "scenarios",
+      title: "What Reaching Grade B Saves",
+      content: `Moving from ${r.currentGrade} to ${r.targetGrade} cuts maintenance overhead by ~${Math.round(r.savedCostPerMonth / Math.max(r.maintenanceCostPerMonth, 1) * 100)}%.`,
+      highlight: saveYr,
+      highlightLabel: `Annual savings at grade ${r.targetGrade}`,
+      bullets: [
+        `Monthly savings: ${saveMo}/mo`,
+        `ROI multiple: ${r.roiMultiple}\xD7 return on remediation investment`,
+        `Break-even: ~${r.breakEvenMonths < 1 ? `${Math.round(r.breakEvenMonths * 30)} days` : `${r.breakEvenMonths} months`}`,
+        `Remediation effort: ~${r.estimatedRemediationDays} engineering days`
+      ]
+    },
+    {
+      type: "recommendation",
+      title: "Recommended Remediation Path",
+      content: r.recommendation,
+      bullets: [
+        `Step 1: Resolve ${r.breakdown.importCycles.count} import cycles (est. ${Math.round(r.estimatedRemediationDays * 0.4)} days)`,
+        `Step 2: Fix ${r.breakdown.documentationDrift.count} drifted capability docs (est. ${Math.round(r.estimatedRemediationDays * 0.3)} days)`,
+        `Step 3: Assign ownership for ${r.breakdown.orphanedCode.count} orphaned capabilities (est. ${Math.round(r.estimatedRemediationDays * 0.2)} days)`,
+        `Step 4: Add coverage to top churn files (est. ${Math.round(r.estimatedRemediationDays * 0.1)} days)`
+      ]
+    },
+    {
+      type: "cta",
+      title: `Approve ${(/* @__PURE__ */ new Date()).toLocaleString("default", { month: "short" })} Refactoring Budget`,
+      content: `Investment: ~${fmtK(r.estimatedRemediationDays * 8 * 150, sym)} (${r.estimatedRemediationDays} days of engineering effort)
+Return: ${saveYr}/year in recovered developer capacity`,
+      highlight: `${r.roiMultiple}\xD7`,
+      highlightLabel: "ROI multiple",
+      bullets: [
+        `${saveYr}/year recurring savings`,
+        `Break-even in ${r.breakEvenMonths < 1 ? `${Math.round(r.breakEvenMonths * 30)} days` : `${r.breakEvenMonths} months`}`,
+        `Measurable via PRISM architecture grade (${r.currentGrade} \u2192 ${r.targetGrade})`
+      ]
+    }
+  ];
+  const executiveSummary = [
+    `\u2022 Current architecture grade ${r.currentGrade} (${r.currentScore}/100) costs ~${costYr}/year in maintenance overhead.`,
+    `\u2022 Improving to grade ${r.targetGrade} saves ~${saveYr}/year \u2014 ${r.roiMultiple}\xD7 return on a ${r.estimatedRemediationDays}-day remediation effort.`,
+    `\u2022 Break-even: ~${r.breakEvenMonths < 1 ? `${Math.round(r.breakEvenMonths * 30)} days` : `${r.breakEvenMonths} months`}. Primary sources: ${r.breakdown.importCycles.count} import cycles, ${r.breakdown.documentationDrift.count} drifted docs, ${r.breakdown.orphanedCode.count} orphaned capabilities.`
+  ].join("\n");
+  const oneLinePitch = `Moving from ${r.currentGrade} to ${r.targetGrade} saves ${saveYr} annually \u2014 ${r.roiMultiple}\xD7 ROI on a ${r.estimatedRemediationDays}-day investment.`;
+  return {
+    title: `Technical Debt ROI \u2014 ${org}`,
+    slides,
+    executiveSummary,
+    oneLinePitch
+  };
+}
+function buildSystemPrompt16() {
+  return "You are a VP of Engineering creating a concise, business-value-focused presentation for C-suite audiences. Generate ONLY valid JSON \u2014 no markdown fences, no prose outside the JSON object.";
+}
+function buildUserPrompt16(opts) {
+  const { roiEstimate: r, organizationName, currency } = opts;
+  const sym = CURRENCY_SYMBOL[currency] ?? "\u20AC";
+  const org = organizationName ?? "the organization";
+  return [
+    `Generate a 6-slide executive ROI presentation for ${org}.`,
+    ``,
+    `## ROI Data`,
+    `Current grade: ${r.currentGrade} (score ${r.currentScore}/100)`,
+    `Target grade: ${r.targetGrade} (score ${r.targetScore}/100)`,
+    `Monthly maintenance cost: ${sym}${r.maintenanceCostPerMonth.toLocaleString()}`,
+    `Annual maintenance cost: ${sym}${r.maintenanceCostPerYear.toLocaleString()}`,
+    `Monthly savings if improved: ${sym}${r.savedCostPerMonth.toLocaleString()}`,
+    `Annual savings if improved: ${sym}${r.savedCostPerYear.toLocaleString()}`,
+    `ROI multiple: ${r.roiMultiple}x`,
+    `Break-even: ${r.breakEvenMonths} months`,
+    `Remediation days: ${r.estimatedRemediationDays}`,
+    ``,
+    `## Pain sources`,
+    `Import cycles: ${r.breakdown.importCycles.count} cycles, ${r.breakdown.importCycles.hoursPerMonth}h/mo, ${sym}${r.breakdown.importCycles.cost.toLocaleString()}/mo`,
+    `Doc drift: ${r.breakdown.documentationDrift.count} drifted, ${r.breakdown.documentationDrift.hoursPerMonth}h/mo, ${sym}${r.breakdown.documentationDrift.cost.toLocaleString()}/mo`,
+    `High churn: ${r.breakdown.highChurnFiles.count} files, ${r.breakdown.highChurnFiles.hoursPerMonth}h/mo, ${sym}${r.breakdown.highChurnFiles.cost.toLocaleString()}/mo`,
+    `Orphaned: ${r.breakdown.orphanedCode.count} capabilities, ${r.breakdown.orphanedCode.hoursPerMonth}h/mo, ${sym}${r.breakdown.orphanedCode.cost.toLocaleString()}/mo`,
+    ``,
+    `## Output Format`,
+    `Return a single JSON object with this exact shape:`,
+    `{`,
+    `  "title": "<deck title>",`,
+    `  "slides": [`,
+    `    {`,
+    `      "type": "<title|problem|cost-breakdown|scenarios|recommendation|cta>",`,
+    `      "title": "<slide title>",`,
+    `      "content": "<1-2 sentences of slide body copy>",`,
+    `      "highlight": "<optional large callout \u2014 a number or grade>",`,
+    `      "highlightLabel": "<label for the highlight>",`,
+    `      "bullets": ["<bullet 1>", "<bullet 2>", "<bullet 3>"]`,
+    `    }`,
+    `  ],`,
+    `  "executiveSummary": "<3-bullet executive summary as a single string, bullets separated by \\n>",`,
+    `  "oneLinePitch": "<one sentence pitch for email subject line>"`,
+    `}`,
+    ``,
+    `Rules:`,
+    `- Exactly 6 slides in order: title, problem, cost-breakdown, scenarios, recommendation, cta`,
+    `- bullets: max 4 per slide, each \u2264 90 characters`,
+    `- content: 1\u20132 sentences, specific numbers from the data above`,
+    `- Use business language \u2014 avoid engineering jargon`,
+    `- Return ONLY valid JSON. No markdown. No prose outside the JSON.`
+  ].join("\n");
+}
+function parseResponse(raw) {
+  let text = raw.trim();
+  if (text.startsWith("```")) {
+    text = text.replace(/^```(?:json)?\n?/, "").replace(/\n?```$/, "").trim();
+  }
+  try {
+    const parsed = JSON.parse(text);
+    const rawSlides = Array.isArray(parsed.slides) ? parsed.slides : [];
+    if (rawSlides.length === 0) return null;
+    const VALID_TYPES = ["title", "problem", "cost-breakdown", "scenarios", "recommendation", "cta"];
+    const slides = rawSlides.map((s, i) => {
+      const slide = s ?? {};
+      const type = typeof slide.type === "string" && VALID_TYPES.includes(slide.type) ? slide.type : VALID_TYPES[i] ?? "recommendation";
+      const bullets = Array.isArray(slide.bullets) ? slide.bullets.filter((b) => typeof b === "string").slice(0, 4) : void 0;
+      return {
+        type,
+        title: typeof slide.title === "string" ? slide.title : `Slide ${i + 1}`,
+        content: typeof slide.content === "string" ? slide.content : "",
+        ...typeof slide.highlight === "string" && slide.highlight ? { highlight: slide.highlight } : {},
+        ...typeof slide.highlightLabel === "string" && slide.highlightLabel ? { highlightLabel: slide.highlightLabel } : {},
+        ...bullets && bullets.length > 0 ? { bullets } : {}
+      };
+    });
+    return {
+      title: typeof parsed.title === "string" ? parsed.title : "Technical Debt ROI",
+      slides,
+      executiveSummary: typeof parsed.executiveSummary === "string" ? parsed.executiveSummary : "",
+      oneLinePitch: typeof parsed.oneLinePitch === "string" ? parsed.oneLinePitch : ""
+    };
+  } catch {
+    return null;
+  }
+}
+async function generateRoiSlide(opts) {
+  try {
+    const response = await opts.llm.complete({
+      systemPrompt: buildSystemPrompt16(),
+      messages: [{ role: "user", content: buildUserPrompt16(opts) }],
+      maxTokens: 3e3
+    });
+    const parsed = parseResponse(response.content);
+    if (parsed) return parsed;
+  } catch {
+  }
+  return buildFallback10(opts);
+}
+
 // src/forge/types.ts
 var asAudienceId = (id) => id;
 
@@ -5368,7 +5945,7 @@ function getDispatchChannel(id) {
 }
 
 // src/forge/dispatch.ts
-function buildSystemPrompt14(channel, audience, brand, blueprintContext, toneOffset) {
+function buildSystemPrompt17(channel, audience, brand, blueprintContext, toneOffset) {
   const lines = [
     `You are a skilled content writer producing a ${channel.name} post.`,
     "",
@@ -5419,7 +5996,7 @@ function truncate(content, maxLength) {
 async function generateForChannel(ask, channel, provider, opts) {
   const now = (/* @__PURE__ */ new Date()).toISOString();
   try {
-    const system = buildSystemPrompt14(
+    const system = buildSystemPrompt17(
       channel,
       opts.audience,
       opts.brand,
@@ -5564,7 +6141,7 @@ function nextVersionNumber(versions) {
 }
 
 // src/forge/refineAsset.ts
-function buildSystemPrompt15(input) {
+function buildSystemPrompt18(input) {
   const parts = [
     `You are a content refinement assistant for a developer-focused content tool (forge0x2B).`,
     `You are refining an existing ${input.assetType.replace(/-/g, " ")} asset.`,
@@ -5603,7 +6180,7 @@ function parseRefinedResponse(raw) {
   return { newContent, llmReply };
 }
 async function refineAsset(input, provider) {
-  const systemPrompt = buildSystemPrompt15(input);
+  const systemPrompt = buildSystemPrompt18(input);
   if (scanForSecrets(systemPrompt)) {
     throw new Error("refineAsset: secret pattern detected in asset content. Refusing to send to LLM.");
   }
@@ -5831,9 +6408,11 @@ exports.exportToBufferCsv = exportToBufferCsv;
 exports.exportToHypefuryCsv = exportToHypefuryCsv;
 exports.exportToICalendar = exportToICalendar;
 exports.generateADR = generateADR;
+exports.generateApiChangelog = generateApiChangelog;
 exports.generateArc42 = generateArc42;
 exports.generateArchitectureWalkthrough = generateArchitectureWalkthrough;
 exports.generateAskDrivenAsset = generateAskDrivenAsset;
+exports.generateChangeImpactBrief = generateChangeImpactBrief;
 exports.generateChangesSince = generateChangesSince;
 exports.generateComplianceDoc = generateComplianceDoc;
 exports.generateKnowledgeCapture = generateKnowledgeCapture;
@@ -5843,6 +6422,7 @@ exports.generatePresentation = generatePresentation;
 exports.generateRadio = generateRadio;
 exports.generateRefactoringReport = generateRefactoringReport;
 exports.generateReleaseNotes = generateReleaseNotes;
+exports.generateRoiSlide = generateRoiSlide;
 exports.generateSprintRetro = generateSprintRetro;
 exports.getDispatchChannel = getDispatchChannel;
 exports.getPrismTemplate = getPrismTemplate;