bmalph 2.3.0 → 2.4.0

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;

package/dist/transition/preflight.js

@@ -0,0 +1,154 @@
+import { extractSection } from "./context.js";
+function hasSection(content, patterns) {
+    return patterns.some((p) => extractSection(content, p) !== "");
+}
+export function validatePrd(content) {
+    if (content === null) {
+        return [
+            {
+                id: "W1",
+                severity: "warning",
+                message: "No PRD document found in planning artifacts",
+                suggestion: "Create a PRD using the /create-prd BMAD workflow.",
+            },
+        ];
+    }
+    const issues = [];
+    if (!hasSection(content, [
+        /^##\s+Executive Summary/m,
+        /^##\s+Vision/m,
+        /^##\s+Goals/m,
+        /^##\s+Project Goals/m,
+    ])) {
+        issues.push({
+            id: "W3",
+            severity: "warning",
+            message: "PRD missing Executive Summary or Vision section",
+            suggestion: "Ralph will lack project context — PROJECT_CONTEXT.md will have empty goals.",
+        });
+    }
+    if (!hasSection(content, [/^##\s+Functional Requirements/m])) {
+        issues.push({
+            id: "W4",
+            severity: "warning",
+            message: "PRD missing Functional Requirements section",
+            suggestion: "Ralph may miss key requirements during implementation.",
+        });
+    }
+    if (!hasSection(content, [/^##\s+Non-Functional/m, /^##\s+NFR/m, /^##\s+Quality/m])) {
+        issues.push({
+            id: "W5",
+            severity: "warning",
+            message: "PRD missing Non-Functional Requirements section",
+            suggestion: "Ralph will not enforce performance, security, or quality constraints.",
+        });
+    }
+    if (!hasSection(content, [/^##\s+Scope/m, /^##\s+In Scope/m, /^##\s+Out of Scope/m])) {
+        issues.push({
+            id: "W6",
+            severity: "warning",
+            message: "PRD missing Scope section",
+            suggestion: "Ralph may implement beyond intended boundaries.",
+        });
+    }
+    return issues;
+}
+export function validateArchitecture(content) {
+    if (content === null) {
+        return [
+            {
+                id: "W2",
+                severity: "warning",
+                message: "No architecture document found in planning artifacts",
+                suggestion: "Create an architecture doc using the /create-architecture BMAD workflow.",
+            },
+        ];
+    }
+    const issues = [];
+    if (!hasSection(content, [/^##\s+Tech Stack/m, /^##\s+Technology Stack/m])) {
+        issues.push({
+            id: "W7",
+            severity: "warning",
+            message: "Architecture missing Tech Stack section",
+            suggestion: "Ralph cannot customize @AGENT.md without knowing the tech stack.",
+        });
+    }
+    return issues;
+}
+export function validateStories(stories, parseWarnings) {
+    const issues = [];
+    for (const warning of parseWarnings) {
+        if (/has no acceptance criteria/i.test(warning)) {
+            issues.push({
+                id: "W8",
+                severity: "warning",
+                message: warning,
+                suggestion: "Ralph cannot verify completion without acceptance criteria.",
+            });
+        }
+        else if (/has no description/i.test(warning)) {
+            issues.push({
+                id: "W9",
+                severity: "warning",
+                message: warning,
+                suggestion: "Ralph will lack context for implementing this story.",
+            });
+        }
+        else if (/not under an epic/i.test(warning)) {
+            issues.push({
+                id: "W10",
+                severity: "warning",
+                message: warning,
+                suggestion: "Story grouping helps Ralph understand feature boundaries.",
+            });
+        }
+    }
+    if (stories.length < 3) {
+        issues.push({
+            id: "I2",
+            severity: "info",
+            message: `Only ${stories.length} ${stories.length === 1 ? "story" : "stories"} found (fewer than 3 is suspiciously small scope)`,
+        });
+    }
+    return issues;
+}
+export function validateReadiness(content) {
+    if (content === null) {
+        return [
+            {
+                id: "I1",
+                severity: "info",
+                message: "No readiness report found (optional artifact)",
+            },
+        ];
+    }
+    if (/NO[-\s]?GO/i.test(content)) {
+        return [
+            {
+                id: "E1",
+                severity: "error",
+                message: "Readiness report indicates NO-GO status",
+                suggestion: "Address issues in the readiness report, or use --force to override.",
+            },
+        ];
+    }
+    return [];
+}
+export function runPreflight(artifactContents, files, stories, parseWarnings) {
+    const prdFile = files.find((f) => /prd/i.test(f));
+    const prdContent = prdFile ? (artifactContents.get(prdFile) ?? null) : null;
+    const archFile = files.find((f) => /architect/i.test(f));
+    const archContent = archFile ? (artifactContents.get(archFile) ?? null) : null;
+    const readinessFile = files.find((f) => /readiness/i.test(f));
+    const readinessContent = readinessFile ? (artifactContents.get(readinessFile) ?? null) : null;
+    const issues = [
+        ...validatePrd(prdContent),
+        ...validateArchitecture(archContent),
+        ...validateStories(stories, parseWarnings),
+        ...validateReadiness(readinessContent),
+    ];
+    return {
+        issues,
+        pass: !issues.some((i) => i.severity === "error"),
+    };
+}

package/dist/transition/specs-index.d.ts

@@ -2,7 +2,7 @@ import type { SpecFileType, Priority, SpecsIndex } from "./types.js";
 /**
  * Detects the type of a spec file based on its filename.
  */
-export declare function detectSpecFileType(filename: string, _content: string): SpecFileType;
+export declare function detectSpecFileType(filename: string, content: string): SpecFileType;
 /**
  * Determines the reading priority for a spec file based on its type.
  */

package/dist/transition/specs-index.js

@@ -3,7 +3,7 @@ import { LARGE_FILE_THRESHOLD_BYTES, DEFAULT_SNIPPET_MAX_LENGTH } from "../utils
 /**
  * Detects the type of a spec file based on its filename.
  */
-export function detectSpecFileType(filename, _content) {
+export function detectSpecFileType(filename, content) {
     const lower = filename.toLowerCase();
     if (lower.includes("prd"))
         return "prd";
@@ -22,6 +22,28 @@ export function detectSpecFileType(filename, _content) {
         return "readiness";
     if (lower.includes("sprint"))
         return "sprint";
+    return detectFromContent(content);
+}
+/**
+ * Content-based fallback when filename doesn't match any known pattern.
+ * Checks first 2000 characters for heading patterns.
+ */
+function detectFromContent(content) {
+    const snippet = content.slice(0, 2000);
+    if (/^##\s+Functional Requirements/m.test(snippet) || /^##\s+Executive Summary/m.test(snippet))
+        return "prd";
+    if (/^##\s+Tech Stack/m.test(snippet) || /^##\s+Architecture Decision/m.test(snippet))
+        return "architecture";
+    if (/^###\s+Story\s+\d+\.\d+:/m.test(snippet))
+        return "stories";
+    if (/^##\s+Design Principles/m.test(snippet) || /^##\s+User Flows/m.test(snippet))
+        return "ux";
+    if (/^##\s+Test Strategy/m.test(snippet) || /^##\s+Test Cases/m.test(snippet))
+        return "test-design";
+    if (/^##\s+GO\s*\/\s*NO-GO/m.test(snippet) || /^##\s+Readiness/m.test(snippet))
+        return "readiness";
+    if (/^##\s+Key Findings/m.test(snippet) || /^##\s+Market Analysis/m.test(snippet))
+        return "research";
     return "other";
 }
 /**
@@ -35,6 +57,7 @@ export function determinePriority(type, _size) {
             return "critical";
         case "test-design":
         case "readiness":
+        case "research":
             return "high";
         case "ux":
         case "sprint":

package/dist/transition/types.d.ts

@@ -6,6 +6,8 @@ export interface ProjectContext {
     scopeBoundaries: string;
     targetUsers: string;
     nonFunctionalRequirements: string;
+    designGuidelines: string;
+    researchInsights: string;
 }
 export interface Story {
     epic: string;
@@ -38,7 +40,7 @@ export interface SpecsChange {
     status: "added" | "modified" | "removed";
     summary?: string;
 }
-export type SpecFileType = "prd" | "architecture" | "stories" | "ux" | "test-design" | "readiness" | "sprint" | "brainstorm" | "other";
+export type SpecFileType = "prd" | "architecture" | "stories" | "ux" | "test-design" | "readiness" | "sprint" | "brainstorm" | "research" | "other";
 export type Priority = "critical" | "high" | "medium" | "low";
 export interface SpecFileMetadata {
     path: string;
@@ -53,8 +55,28 @@ export interface SpecsIndex {
     totalSizeKb: number;
     files: SpecFileMetadata[];
 }
+export type PreflightSeverity = "error" | "warning" | "info";
+export interface PreflightIssue {
+    id: string;
+    severity: PreflightSeverity;
+    message: string;
+    suggestion?: string;
+}
+export interface PreflightResult {
+    issues: PreflightIssue[];
+    pass: boolean;
+}
+export interface TransitionOptions {
+    force?: boolean;
+}
+export interface GeneratedFile {
+    path: string;
+    action: "created" | "updated";
+}
 export interface TransitionResult {
     storiesCount: number;
     warnings: string[];
     fixPlanPreserved: boolean;
+    preflightIssues?: PreflightIssue[];
+    generatedFiles: GeneratedFile[];
 }

package/dist/utils/dryrun.d.ts

@@ -1,5 +1,5 @@
 export interface DryRunAction {
-    type: "create" | "modify" | "skip";
+    type: "create" | "modify" | "skip" | "delete" | "warn";
     path: string;
     reason?: string;
 }

package/dist/utils/dryrun.js

@@ -11,6 +11,12 @@ export function logDryRunAction(action) {
         case "skip":
             console.log(`${prefix} Would skip: ${chalk.dim(action.path)}${action.reason ? ` (${action.reason})` : ""}`);
             break;
+        case "delete":
+            console.log(`${prefix} Would delete: ${chalk.red(action.path)}`);
+            break;
+        case "warn":
+            console.log(`${prefix} Warning: ${chalk.yellow(action.path)}${action.reason ? ` (${action.reason})` : ""}`);
+            break;
     }
 }
 export function formatDryRunSummary(actions) {
@@ -19,9 +25,18 @@ export function formatDryRunSummary(actions) {
     }
     const lines = [];
     lines.push(chalk.blue("\n[dry-run] Would perform the following actions:\n"));
+    const deletes = actions.filter((a) => a.type === "delete");
     const creates = actions.filter((a) => a.type === "create");
     const modifies = actions.filter((a) => a.type === "modify");
     const skips = actions.filter((a) => a.type === "skip");
+    const warns = actions.filter((a) => a.type === "warn");
+    if (deletes.length > 0) {
+        lines.push(chalk.red("Would delete:"));
+        for (const action of deletes) {
+            lines.push(`  ${action.path}`);
+        }
+        lines.push("");
+    }
     if (creates.length > 0) {
         lines.push(chalk.green("Would create:"));
         for (const action of creates) {
@@ -43,6 +58,13 @@ export function formatDryRunSummary(actions) {
         }
         lines.push("");
     }
+    if (warns.length > 0) {
+        lines.push(chalk.yellow("Warnings:"));
+        for (const action of warns) {
+            lines.push(`  ${action.path}${action.reason ? ` (${action.reason})` : ""}`);
+        }
+        lines.push("");
+    }
     lines.push(chalk.dim("No changes made."));
     return lines.join("\n");
 }

package/dist/utils/validate.js

@@ -185,8 +185,8 @@ export function normalizeRalphStatus(data) {
     return {
         loopCount,
         status,
-        tasksCompleted: 0,
-        tasksTotal: 0,
+        tasksCompleted: typeof data.tasks_completed === "number" ? data.tasks_completed : 0,
+        tasksTotal: typeof data.tasks_total === "number" ? data.tasks_total : 0,
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmalph",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop for Claude Code",
   "type": "module",
   "bin": {

package/ralph/ralph_loop.sh

@@ -1436,6 +1436,21 @@ main() {
         exit 1
     fi
 
+    # Check required dependencies
+    if ! command -v jq &> /dev/null; then
+        log_status "ERROR" "Required dependency 'jq' is not installed."
+        echo ""
+        echo "jq is required for JSON processing in the Ralph loop."
+        echo ""
+        echo "Install jq:"
+        echo "  macOS:   brew install jq"
+        echo "  Ubuntu:  sudo apt-get install jq"
+        echo "  Windows: choco install jq  (or: winget install jqlang.jq)"
+        echo ""
+        echo "After installing, run this command again."
+        exit 1
+    fi
+
     # Initialize session tracking before entering the loop
     init_session_tracking
 

package/slash-commands/bmalph-doctor.md

@@ -0,0 +1,16 @@
+# Check Project Health
+
+Run diagnostic checks on the bmalph installation and report any issues.
+
+## How to Run
+
+Execute the CLI command:
+    bmalph doctor
+
+## What It Does
+
+- Verifies required directories exist (`_bmad/`, `.ralph/`, `bmalph/`)
+- Checks that slash commands are installed correctly
+- Validates the instructions file contains the BMAD snippet
+- Reports version mismatches between installed and bundled assets
+- Suggests remediation steps for any issues found