bmalph 2.2.1 → 2.4.0

package/dist/transition/artifact-scan.js

@@ -0,0 +1,91 @@
+import { readdir } from "fs/promises";
+import { relative } from "path";
+import { findArtifactsDir } from "./artifacts.js";
+const ARTIFACT_RULES = [
+    { pattern: /brief/i, phase: 1, name: "Product Brief", required: false },
+    { pattern: /market/i, phase: 1, name: "Market Research", required: false },
+    { pattern: /domain/i, phase: 1, name: "Domain Research", required: false },
+    { pattern: /tech.*research/i, phase: 1, name: "Technical Research", required: false },
+    { pattern: /prd/i, phase: 2, name: "PRD", required: true },
+    { pattern: /ux/i, phase: 2, name: "UX Design", required: false },
+    { pattern: /architect/i, phase: 3, name: "Architecture", required: true },
+    { pattern: /epic|stor/i, phase: 3, name: "Epics & Stories", required: true },
+    { pattern: /readiness/i, phase: 3, name: "Readiness Report", required: true },
+];
+export function classifyArtifact(filename) {
+    for (const rule of ARTIFACT_RULES) {
+        if (rule.pattern.test(filename)) {
+            return { phase: rule.phase, name: rule.name, required: rule.required };
+        }
+    }
+    return null;
+}
+export function scanArtifacts(files) {
+    const phases = { 1: [], 2: [], 3: [] };
+    for (const file of files) {
+        const classification = classifyArtifact(file);
+        if (classification) {
+            const phaseKey = classification.phase;
+            phases[phaseKey].push({ ...classification, filename: file });
+        }
+    }
+    return phases;
+}
+export function detectPhase(phases) {
+    for (const phase of [3, 2, 1]) {
+        if (phases[phase].length > 0) {
+            return phase;
+        }
+    }
+    return 1;
+}
+export function getMissing(phases) {
+    const missing = [];
+    const foundNames = new Set([...phases[1], ...phases[2], ...phases[3]].map((a) => a.name));
+    for (const rule of ARTIFACT_RULES) {
+        if (rule.required && !foundNames.has(rule.name)) {
+            missing.push(rule.name);
+        }
+    }
+    return missing;
+}
+export function suggestNext(phases, detectedPhase) {
+    const foundNames = new Set([...phases[1], ...phases[2], ...phases[3]].map((a) => a.name));
+    if (detectedPhase <= 1 && phases[1].length === 0) {
+        return "Run /analyst to start analysis";
+    }
+    if (!foundNames.has("PRD")) {
+        return "Run /create-prd to create the PRD";
+    }
+    if (!foundNames.has("Architecture")) {
+        return "Run /architect to create architecture";
+    }
+    if (!foundNames.has("Epics & Stories")) {
+        return "Run /create-epics-stories to define epics and stories";
+    }
+    if (!foundNames.has("Readiness Report")) {
+        return "Run /architect to generate readiness report";
+    }
+    return "Run: bmalph implement";
+}
+export async function scanProjectArtifacts(projectDir) {
+    const artifactsDir = await findArtifactsDir(projectDir);
+    if (!artifactsDir) {
+        return null;
+    }
+    const files = await readdir(artifactsDir);
+    const phases = scanArtifacts(files);
+    const detectedPhase = detectPhase(phases);
+    const missing = getMissing(phases);
+    const nextAction = suggestNext(phases, detectedPhase);
+    const relativeDir = relative(projectDir, artifactsDir).replace(/\\/g, "/");
+    const found = files.filter((f) => classifyArtifact(f) !== null);
+    return {
+        directory: relativeDir,
+        found,
+        detectedPhase,
+        missing,
+        phases,
+        nextAction,
+    };
+}

package/dist/transition/artifacts.d.ts

@@ -1,2 +1,3 @@
 export declare function findArtifactsDir(projectDir: string): Promise<string | null>;
+/** @deprecated Use `runPreflight` from `./preflight.js` instead. Kept for backward compatibility. */
 export declare function validateArtifacts(files: string[], artifactsDir: string): Promise<string[]>;

package/dist/transition/artifacts.js

@@ -19,6 +19,7 @@ export async function findArtifactsDir(projectDir) {
     debug(`No artifacts found. Checked: ${candidates.join(", ")}`);
     return null;
 }
+/** @deprecated Use `runPreflight` from `./preflight.js` instead. Kept for backward compatibility. */
 export async function validateArtifacts(files, artifactsDir) {
     const warnings = [];
     const hasPrd = files.some((f) => /prd/i.test(f));
@@ -39,7 +40,7 @@ export async function validateArtifacts(files, artifactsDir) {
             }
         }
         catch {
-            // Cannot read readiness file, skip
+            warnings.push("Could not read readiness report — NO-GO status unverified");
         }
     }
     return warnings;

package/dist/transition/context.js

@@ -37,6 +37,8 @@ export function extractProjectContext(artifacts) {
     // Combine all content, keyed by likely role
     let prdContent = "";
     let archContent = "";
+    let uxContent = "";
+    let researchContent = "";
     for (const [filename, content] of artifacts) {
         if (/prd/i.test(filename))
             prdContent += "\n" + content;
@@ -44,6 +46,10 @@ export function extractProjectContext(artifacts) {
             archContent += "\n" + content;
         if (/readiness/i.test(filename))
             archContent += "\n" + content;
+        if (/ux/i.test(filename))
+            uxContent += "\n" + content;
+        if (/research|market|domain|brief/i.test(filename))
+            researchContent += "\n" + content;
     }
     const allContent = prdContent + "\n" + archContent;
     const truncated = [];
@@ -98,6 +104,28 @@ export function extractProjectContext(artifacts) {
                 /^##\s+Quality Attributes/m,
             ],
         },
+        {
+            field: "designGuidelines",
+            source: uxContent,
+            patterns: [
+                /^##\s+Design Principles/m,
+                /^##\s+Design System/m,
+                /^##\s+Core Experience/m,
+                /^##\s+User Flows/m,
+                /^##\s+Visual Foundation/m,
+            ],
+        },
+        {
+            field: "researchInsights",
+            source: researchContent,
+            patterns: [
+                /^##\s+Key Findings/m,
+                /^##\s+Recommendations/m,
+                /^##\s+Market Analysis/m,
+                /^##\s+Domain Insights/m,
+                /^##\s+Summary/m,
+            ],
+        },
     ];
     const context = {
         projectGoals: "",
@@ -107,6 +135,8 @@ export function extractProjectContext(artifacts) {
         scopeBoundaries: "",
         targetUsers: "",
         nonFunctionalRequirements: "",
+        designGuidelines: "",
+        researchInsights: "",
     };
     for (const { field, source, patterns } of fields) {
         const result = extractFromPatternsWithInfo(source, patterns);
@@ -140,6 +170,8 @@ export function generateProjectContextMd(context, projectName) {
         { heading: "Scope Boundaries", content: context.scopeBoundaries },
         { heading: "Target Users", content: context.targetUsers },
         { heading: "Non-Functional Requirements", content: context.nonFunctionalRequirements },
+        { heading: "Design Guidelines", content: context.designGuidelines },
+        { heading: "Research Insights", content: context.researchInsights },
     ];
     for (const { heading, content } of sections) {
         if (content) {
@@ -161,6 +193,8 @@ export function generatePrompt(projectName, context) {
             context.targetUsers && `### Target Users\n${context.targetUsers}`,
             context.nonFunctionalRequirements &&
                 `### Non-Functional Requirements\n${context.nonFunctionalRequirements}`,
+            context.designGuidelines && `### Design Guidelines\n${context.designGuidelines}`,
+            context.researchInsights && `### Research Insights\n${context.researchInsights}`,
         ]
             .filter(Boolean)
             .join("\n\n")

package/dist/transition/fix-plan.d.ts

@@ -10,6 +10,12 @@ export declare function detectOrphanedCompletedStories(existingItems: FixPlanIte
 /**
  * Detects stories that may have been renumbered by comparing titles.
  * Returns warnings when a completed story's title appears under a different ID.
+ * Skips stories that were already auto-preserved via title-based merge.
  */
-export declare function detectRenumberedStories(existingItems: FixPlanItemWithTitle[], newStories: Story[]): string[];
-export declare function mergeFixPlanProgress(newFixPlan: string, completedIds: Set<string>): string;
+export declare function detectRenumberedStories(existingItems: FixPlanItemWithTitle[], newStories: Story[], preservedIds?: Set<string>): string[];
+export declare function normalizeTitle(title: string): string;
+/**
+ * Builds a map from normalized (lowercased) title to story ID for completed items.
+ */
+export declare function buildCompletedTitleMap(items: FixPlanItemWithTitle[]): Map<string, string>;
+export declare function mergeFixPlanProgress(newFixPlan: string, completedIds: Set<string>, titleMap?: Map<string, string>, completedTitles?: Map<string, string>): string;

package/dist/transition/fix-plan.js

@@ -65,30 +65,56 @@ export function detectOrphanedCompletedStories(existingItems, newStoryIds) {
 /**
  * Detects stories that may have been renumbered by comparing titles.
  * Returns warnings when a completed story's title appears under a different ID.
+ * Skips stories that were already auto-preserved via title-based merge.
  */
-export function detectRenumberedStories(existingItems, newStories) {
+export function detectRenumberedStories(existingItems, newStories, preservedIds) {
     const warnings = [];
     // Build a map of new story titles (lowercased) to IDs
     const newTitleToId = new Map();
     for (const story of newStories) {
-        newTitleToId.set(story.title.toLowerCase().trim(), story.id);
+        newTitleToId.set(normalizeTitle(story.title), story.id);
     }
     // Check each completed story
     for (const item of existingItems) {
         if (!item.completed || !item.title)
             continue;
-        const normalizedTitle = item.title.toLowerCase().trim();
+        const normalizedTitle = normalizeTitle(item.title);
         const newId = newTitleToId.get(normalizedTitle);
         // If title exists under a different ID, warn about renumbering
-        if (newId && newId !== item.id) {
+        // (unless it was already auto-preserved)
+        if (newId && newId !== item.id && !preservedIds?.has(newId)) {
             warnings.push(`Story "${item.title}" appears to have been renumbered from ${item.id} to ${newId}. Completion status was not preserved.`);
         }
     }
     return warnings;
 }
-export function mergeFixPlanProgress(newFixPlan, completedIds) {
-    // Replace [ ] with [x] for completed story IDs
+export function normalizeTitle(title) {
+    return title.toLowerCase().trim();
+}
+/**
+ * Builds a map from normalized (lowercased) title to story ID for completed items.
+ */
+export function buildCompletedTitleMap(items) {
+    const map = new Map();
+    for (const item of items) {
+        if (item.completed && item.title) {
+            map.set(normalizeTitle(item.title), item.id);
+        }
+    }
+    return map;
+}
+export function mergeFixPlanProgress(newFixPlan, completedIds, titleMap, completedTitles) {
+    // Replace [ ] with [x] for completed story IDs or title matches
     return newFixPlan.replace(/^(\s*-\s*)\[ \](\s*Story\s+(\d+\.\d+):)/gm, (match, prefix, suffix, id) => {
-        return completedIds.has(id) ? `${prefix}[x]${suffix}` : match;
+        if (completedIds.has(id))
+            return `${prefix}[x]${suffix}`;
+        // Title-based fallback: check if title matches a completed story
+        if (titleMap && completedTitles) {
+            const title = titleMap.get(id);
+            if (title && completedTitles.has(normalizeTitle(title))) {
+                return `${prefix}[x]${suffix}`;
+            }
+        }
+        return match;
     });
 }

package/dist/transition/orchestration.d.ts

@@ -1,2 +1,2 @@
-import type { TransitionResult } from "./types.js";
-export declare function runTransition(projectDir: string): Promise<TransitionResult>;
+import type { TransitionResult, TransitionOptions } from "./types.js";
+export declare function runTransition(projectDir: string, options?: TransitionOptions): Promise<TransitionResult>;

package/dist/transition/orchestration.js

@@ -2,17 +2,18 @@ import { readFile, readdir, cp, mkdir, access, rm, rename } from "fs/promises";
 import { join } from "path";
 import { debug, info, warn } from "../utils/logger.js";
 import { isEnoent, formatError } from "../utils/errors.js";
-import { atomicWriteFile } from "../utils/file-system.js";
+import { atomicWriteFile, exists } from "../utils/file-system.js";
 import { readConfig } from "../utils/config.js";
 import { readState, writeState } from "../utils/state.js";
 import { parseStoriesWithWarnings } from "./story-parsing.js";
-import { generateFixPlan, parseFixPlan, mergeFixPlanProgress, detectOrphanedCompletedStories, detectRenumberedStories, } from "./fix-plan.js";
+import { generateFixPlan, parseFixPlan, mergeFixPlanProgress, detectOrphanedCompletedStories, detectRenumberedStories, buildCompletedTitleMap, normalizeTitle, } from "./fix-plan.js";
 import { detectTechStack, customizeAgentMd } from "./tech-stack.js";
-import { findArtifactsDir, validateArtifacts } from "./artifacts.js";
+import { findArtifactsDir } from "./artifacts.js";
+import { runPreflight } from "./preflight.js";
 import { extractProjectContext, generateProjectContextMd, generatePrompt, detectTruncation, } from "./context.js";
 import { generateSpecsChangelog, formatChangelog } from "./specs-changelog.js";
 import { generateSpecsIndex, formatSpecsIndexMd } from "./specs-index.js";
-export async function runTransition(projectDir) {
+export async function runTransition(projectDir, options) {
     info("Locating BMAD artifacts...");
     const artifactsDir = await findArtifactsDir(projectDir);
     if (!artifactsDir) {
@@ -20,6 +21,19 @@ export async function runTransition(projectDir) {
     }
     // Find and parse stories file
     const files = await readdir(artifactsDir);
+    // Read artifact contents early for preflight validation and later use
+    const artifactContents = new Map();
+    for (const file of files) {
+        if (file.endsWith(".md")) {
+            try {
+                const content = await readFile(join(artifactsDir, file), "utf-8");
+                artifactContents.set(file, content);
+            }
+            catch (err) {
+                warn(`Could not read artifact ${file}: ${formatError(err)}`);
+            }
+        }
+    }
     const storiesPattern = /^(epics[-_]?(and[-_]?)?)?stor(y|ies)([-_]\d+)?\.md$/i;
     const storiesFile = files.find((f) => storiesPattern.test(f) || /epic/i.test(f));
     if (!storiesFile) {
@@ -33,10 +47,40 @@ export async function runTransition(projectDir) {
     if (stories.length === 0) {
         throw new Error("No stories parsed from the epics file. Ensure stories follow the format: ### Story N.M: Title");
     }
+    // Pre-flight validation
+    info("Pre-flight validation...");
+    const preflightResult = runPreflight(artifactContents, files, stories, parseWarnings);
+    for (const issue of preflightResult.issues) {
+        if (issue.severity === "error") {
+            warn(`  ERROR  ${issue.id}: ${issue.message}`);
+            if (issue.suggestion)
+                warn(`         ${issue.suggestion}`);
+        }
+        else if (issue.severity === "warning") {
+            warn(`  WARN   ${issue.id}: ${issue.message}`);
+            if (issue.suggestion)
+                warn(`         ${issue.suggestion}`);
+        }
+        else {
+            info(`  INFO   ${issue.id}: ${issue.message}`);
+        }
+    }
+    if (!preflightResult.pass) {
+        if (options?.force) {
+            warn("Pre-flight validation has errors but --force was used, continuing...");
+        }
+        else {
+            const errors = preflightResult.issues.filter((i) => i.severity === "error");
+            throw new Error(`Pre-flight validation failed: ${errors.map((e) => e.message).join("; ")}. Use --force to override.`);
+        }
+    }
+    // Track generated files for summary output
+    const generatedFiles = [];
     // Check existing fix_plan for completed items (smart merge)
     let completedIds = new Set();
     let existingItems = [];
     const fixPlanPath = join(projectDir, ".ralph/@fix_plan.md");
+    const fixPlanExisted = await exists(fixPlanPath);
     try {
         const existingFixPlan = await readFile(fixPlanPath, "utf-8");
         existingItems = parseFixPlan(existingFixPlan);
@@ -57,16 +101,30 @@ export async function runTransition(projectDir) {
     for (const w of orphanWarnings) {
         warn(w);
     }
-    // Detect renumbered stories (Bug #3)
-    const renumberWarnings = detectRenumberedStories(existingItems, stories);
-    for (const w of renumberWarnings) {
-        warn(w);
-    }
+    // Build title maps for title-based merge (Gap 3: renumbered story preservation)
+    const completedTitles = buildCompletedTitleMap(existingItems);
+    const newTitleMap = new Map(stories.map((s) => [s.id, s.title]));
     // Generate new fix_plan from current stories, preserving completion status
     info(`Generating fix plan for ${stories.length} stories...`);
     const newFixPlan = generateFixPlan(stories, storiesFile);
-    const mergedFixPlan = mergeFixPlanProgress(newFixPlan, completedIds);
+    const mergedFixPlan = mergeFixPlanProgress(newFixPlan, completedIds, newTitleMap, completedTitles);
+    // Detect which stories were preserved via title match (for renumber warning suppression)
+    const preservedIds = new Set();
+    for (const [id, title] of newTitleMap) {
+        if (!completedIds.has(id) && completedTitles.has(normalizeTitle(title))) {
+            preservedIds.add(id);
+        }
+    }
+    // Detect renumbered stories (Bug #3), skipping auto-preserved ones
+    const renumberWarnings = detectRenumberedStories(existingItems, stories, preservedIds);
+    for (const w of renumberWarnings) {
+        warn(w);
+    }
     await atomicWriteFile(fixPlanPath, mergedFixPlan);
+    generatedFiles.push({
+        path: ".ralph/@fix_plan.md",
+        action: fixPlanExisted ? "updated" : "created",
+    });
     // Track whether progress was preserved for return value
     const fixPlanPreserved = completedIds.size > 0;
     // Generate changelog before overwriting specs/
@@ -78,6 +136,7 @@ export async function runTransition(projectDir) {
         if (changes.length > 0) {
             const changelog = formatChangelog(changes, new Date().toISOString());
             await atomicWriteFile(join(projectDir, ".ralph/SPECS_CHANGELOG.md"), changelog);
+            generatedFiles.push({ path: ".ralph/SPECS_CHANGELOG.md", action: "updated" });
             debug(`Generated SPECS_CHANGELOG.md with ${changes.length} changes`);
         }
     }
@@ -114,6 +173,7 @@ export async function runTransition(projectDir) {
         await access(specsTmpDir);
         await rm(specsDir, { recursive: true, force: true });
         await rename(specsTmpDir, specsDir);
+        generatedFiles.push({ path: ".ralph/specs/", action: "updated" });
         debug("Copied _bmad-output/ to .ralph/specs/ (atomic)");
     }
     else {
@@ -129,13 +189,20 @@ export async function runTransition(projectDir) {
         await access(specsTmpDir);
         await rm(specsDir, { recursive: true, force: true });
         await rename(specsTmpDir, specsDir);
+        generatedFiles.push({ path: ".ralph/specs/", action: "updated" });
     }
     // Generate SPECS_INDEX.md for intelligent spec reading
     info("Generating SPECS_INDEX.md...");
+    const specsIndexPath = join(projectDir, ".ralph/SPECS_INDEX.md");
+    const specsIndexExisted = await exists(specsIndexPath);
     try {
         const specsIndex = await generateSpecsIndex(specsDir);
         if (specsIndex.totalFiles > 0) {
-            await atomicWriteFile(join(projectDir, ".ralph/SPECS_INDEX.md"), formatSpecsIndexMd(specsIndex));
+            await atomicWriteFile(specsIndexPath, formatSpecsIndexMd(specsIndex));
+            generatedFiles.push({
+                path: ".ralph/SPECS_INDEX.md",
+                action: specsIndexExisted ? "updated" : "created",
+            });
             debug(`Generated SPECS_INDEX.md with ${specsIndex.totalFiles} files`);
         }
     }
@@ -143,18 +210,6 @@ export async function runTransition(projectDir) {
         warn(`Could not generate SPECS_INDEX.md: ${formatError(err)}`);
     }
     // Generate PROJECT_CONTEXT.md from planning artifacts
-    const artifactContents = new Map();
-    for (const file of files) {
-        if (file.endsWith(".md")) {
-            try {
-                const content = await readFile(join(artifactsDir, file), "utf-8");
-                artifactContents.set(file, content);
-            }
-            catch (err) {
-                warn(`Could not read artifact ${file}: ${formatError(err)}`);
-            }
-        }
-    }
     let projectName = "project";
     try {
         const config = await readConfig(projectDir);
@@ -167,6 +222,8 @@ export async function runTransition(projectDir) {
     }
     // Extract project context for both PROJECT_CONTEXT.md and PROMPT.md
     info("Generating PROJECT_CONTEXT.md...");
+    const projectContextPath = join(projectDir, ".ralph/PROJECT_CONTEXT.md");
+    const projectContextExisted = await exists(projectContextPath);
     let projectContext = null;
     let truncationWarnings = [];
     if (artifactContents.size > 0) {
@@ -174,15 +231,21 @@ export async function runTransition(projectDir) {
         projectContext = context;
         truncationWarnings = detectTruncation(truncated);
         const contextMd = generateProjectContextMd(projectContext, projectName);
-        await atomicWriteFile(join(projectDir, ".ralph/PROJECT_CONTEXT.md"), contextMd);
+        await atomicWriteFile(projectContextPath, contextMd);
+        generatedFiles.push({
+            path: ".ralph/PROJECT_CONTEXT.md",
+            action: projectContextExisted ? "updated" : "created",
+        });
         debug("Generated PROJECT_CONTEXT.md");
     }
     // Generate PROMPT.md with embedded context
     info("Generating PROMPT.md...");
     // Try to preserve rich PROMPT.md template if it has the placeholder
     let prompt;
+    let promptExisted = false;
     try {
         const existingPrompt = await readFile(join(projectDir, ".ralph/PROMPT.md"), "utf-8");
+        promptExisted = true;
         if (existingPrompt.includes("[YOUR PROJECT NAME]")) {
             prompt = existingPrompt.replace(/\[YOUR PROJECT NAME\]/g, projectName);
         }
@@ -201,29 +264,39 @@ export async function runTransition(projectDir) {
         prompt = generatePrompt(projectName, projectContext ?? undefined);
     }
     await atomicWriteFile(join(projectDir, ".ralph/PROMPT.md"), prompt);
+    generatedFiles.push({ path: ".ralph/PROMPT.md", action: promptExisted ? "updated" : "created" });
     // Customize @AGENT.md based on detected tech stack from architecture
     const architectureFile = files.find((f) => /architect/i.test(f));
     if (architectureFile) {
-        try {
-            const archContent = await readFile(join(artifactsDir, architectureFile), "utf-8");
-            const stack = detectTechStack(archContent);
-            if (stack) {
-                const agentPath = join(projectDir, ".ralph/@AGENT.md");
-                const agentTemplate = await readFile(agentPath, "utf-8");
-                const customized = customizeAgentMd(agentTemplate, stack);
-                await atomicWriteFile(agentPath, customized);
-                debug("Customized @AGENT.md with detected tech stack");
+        const archContent = artifactContents.get(architectureFile);
+        if (archContent) {
+            try {
+                const stack = detectTechStack(archContent);
+                if (stack) {
+                    const agentPath = join(projectDir, ".ralph/@AGENT.md");
+                    const agentTemplate = await readFile(agentPath, "utf-8");
+                    const customized = customizeAgentMd(agentTemplate, stack);
+                    await atomicWriteFile(agentPath, customized);
+                    generatedFiles.push({ path: ".ralph/@AGENT.md", action: "updated" });
+                    debug("Customized @AGENT.md with detected tech stack");
+                }
+            }
+            catch (err) {
+                warn(`Could not customize @AGENT.md: ${formatError(err)}`);
             }
-        }
-        catch (err) {
-            warn(`Could not customize @AGENT.md: ${formatError(err)}`);
         }
     }
-    // Validate artifacts and collect warnings
-    const artifactWarnings = await validateArtifacts(files, artifactsDir);
+    // Collect warnings from all sources
+    const preflightWarnings = preflightResult.issues
+        .filter((i) => i.severity === "warning" || (i.severity === "error" && options?.force))
+        .map((i) => i.message);
+    // Keep parse warnings not already covered by preflight (e.g., malformed IDs)
+    const nonPreflightParseWarnings = parseWarnings.filter((w) => !/has no acceptance criteria/i.test(w) &&
+        !/has no description/i.test(w) &&
+        !/not under an epic/i.test(w));
     const warnings = [
-        ...parseWarnings,
-        ...artifactWarnings,
+        ...preflightWarnings,
+        ...nonPreflightParseWarnings,
         ...orphanWarnings,
         ...renumberWarnings,
         ...truncationWarnings,
@@ -239,5 +312,11 @@ export async function runTransition(projectDir) {
     };
     await writeState(projectDir, newState);
     info("Transition complete: phase 4 (implementing)");
-    return { storiesCount: stories.length, warnings, fixPlanPreserved };
+    return {
+        storiesCount: stories.length,
+        warnings,
+        fixPlanPreserved,
+        preflightIssues: preflightResult.issues,
+        generatedFiles,
+    };
 }

package/dist/transition/preflight.d.ts

@@ -0,0 +1,6 @@
+import type { Story, PreflightIssue, PreflightResult } from "./types.js";
+export declare function validatePrd(content: string | null): PreflightIssue[];
+export declare function validateArchitecture(content: string | null): PreflightIssue[];
+export declare function validateStories(stories: Story[], parseWarnings: string[]): PreflightIssue[];
+export declare function validateReadiness(content: string | null): PreflightIssue[];
+export declare function runPreflight(artifactContents: Map<string, string>, files: string[], stories: Story[], parseWarnings: string[]): PreflightResult;