bmalph 2.2.0 → 2.2.1

package/bundled-versions.json

@@ -1,4 +1,3 @@
 {
-  "bmadCommit": "aa573bdb",
-  "ralphCommit": "605e50f7"
+  "bmadCommit": "aa573bdb"
 }

package/dist/cli.js

@@ -44,7 +44,7 @@ async function resolveAndValidateProjectDir() {
     }
     catch (err) {
         if (isEnoent(err)) {
-            throw new Error(`Project directory not found: ${dir}`);
+            throw new Error(`Project directory not found: ${dir}`, { cause: err });
         }
         throw err;
     }
@@ -70,7 +70,7 @@ program
     .action(async (opts) => doctorCommand({ ...opts, projectDir: await resolveAndValidateProjectDir() }));
 program
     .command("check-updates")
-    .description("Check if bundled BMAD/Ralph versions are up to date with upstream")
+    .description("Check if bundled BMAD version is up to date with upstream")
     .option("--json", "Output as JSON")
     .action(checkUpdatesCommand);
 program

package/dist/commands/check-updates.js

@@ -12,11 +12,9 @@ async function runCheckUpdates(options) {
     }
     const result = await checkUpstream(bundled);
     if (options.json) {
-        const hasUpdates = (result.bmad !== null && !result.bmad.isUpToDate) ||
-            (result.ralph !== null && !result.ralph.isUpToDate);
+        const hasUpdates = result.bmad !== null && !result.bmad.isUpToDate;
         const output = {
             bmad: result.bmad,
-            ralph: result.ralph,
             errors: result.errors,
             hasUpdates,
         };
@@ -24,14 +22,11 @@ async function runCheckUpdates(options) {
         return;
     }
     // Human-readable output
-    let updatesCount = 0;
-    // BMAD status
     if (result.bmad) {
         if (result.bmad.isUpToDate) {
             console.log(chalk.green(`  ✓ BMAD-METHOD: up to date (${result.bmad.bundledSha})`));
         }
         else {
-            updatesCount++;
             console.log(chalk.yellow(`  ! BMAD-METHOD: updates available (${result.bmad.bundledSha} → ${result.bmad.latestSha})`));
             console.log(chalk.dim(`    → ${result.bmad.compareUrl}`));
         }
@@ -41,30 +36,13 @@ async function runCheckUpdates(options) {
         const reason = bmadError ? getErrorReason(bmadError) : "unknown error";
         console.log(chalk.yellow(`  ? BMAD-METHOD: Could not check (${reason})`));
     }
-    // Ralph status
-    if (result.ralph) {
-        if (result.ralph.isUpToDate) {
-            console.log(chalk.green(`  ✓ Ralph: up to date (${result.ralph.bundledSha})`));
-        }
-        else {
-            updatesCount++;
-            console.log(chalk.yellow(`  ! Ralph: updates available (${result.ralph.bundledSha} → ${result.ralph.latestSha})`));
-            console.log(chalk.dim(`    → ${result.ralph.compareUrl}`));
-        }
-    }
-    else {
-        const ralphError = result.errors.find((e) => e.repo === "ralph");
-        const reason = ralphError ? getErrorReason(ralphError) : "unknown error";
-        console.log(chalk.yellow(`  ? Ralph: Could not check (${reason})`));
-    }
     // Summary
     console.log();
-    if (updatesCount === 0 && result.errors.length === 0) {
-        console.log(chalk.green("All repositories are up to date."));
+    if (result.bmad !== null && result.bmad.isUpToDate && result.errors.length === 0) {
+        console.log(chalk.green("Up to date."));
     }
-    else if (updatesCount > 0) {
-        const plural = updatesCount === 1 ? "repository has" : "repositories have";
-        console.log(chalk.yellow(`${updatesCount} ${plural} updates available.`));
+    else if (result.bmad !== null && !result.bmad.isUpToDate) {
+        console.log(chalk.yellow("Updates available."));
     }
 }
 function getErrorReason(error) {

package/dist/commands/doctor.js

@@ -248,22 +248,21 @@ async function checkUpstreamVersions(projectDir) {
             return { label, passed: true, detail: "not tracked (pre-1.2.0 install)" };
         }
         const bundled = getBundledVersions();
-        const { bmadCommit, ralphCommit } = config.upstreamVersions;
+        const { bmadCommit } = config.upstreamVersions;
         const bmadMatch = bmadCommit === bundled.bmadCommit;
-        const ralphMatch = ralphCommit === bundled.ralphCommit;
-        if (bmadMatch && ralphMatch) {
+        if (bmadMatch) {
             return {
                 label,
                 passed: true,
-                detail: `BMAD:${bmadCommit.slice(0, 8)}, Ralph:${ralphCommit.slice(0, 8)}`,
+                detail: `BMAD:${bmadCommit.slice(0, 8)}`,
             };
         }
-        const mismatches = [];
-        if (!bmadMatch)
-            mismatches.push(`BMAD:${bmadCommit.slice(0, 8)}→${bundled.bmadCommit.slice(0, 8)}`);
-        if (!ralphMatch)
-            mismatches.push(`Ralph:${ralphCommit.slice(0, 8)}→${bundled.ralphCommit.slice(0, 8)}`);
-        return { label, passed: false, detail: `outdated: ${mismatches.join(", ")}`, hint };
+        return {
+            label,
+            passed: false,
+            detail: `outdated: BMAD:${bmadCommit.slice(0, 8)}→${bundled.bmadCommit.slice(0, 8)}`,
+            hint,
+        };
     }
     catch (err) {
         return { label, passed: false, detail: `error: ${formatError(err)}`, hint };
@@ -397,20 +396,16 @@ async function checkUpstreamGitHubStatus(_projectDir) {
     try {
         const bundled = getBundledVersions();
         const result = await checkUpstream(bundled);
-        // Check if all requests failed
-        if (result.bmad === null && result.ralph === null) {
+        // Check if request failed
+        if (result.bmad === null) {
             const reason = getSkipReason(result.errors);
             return { label, passed: true, detail: `skipped: ${reason}` };
         }
-        // Build status string
-        const statuses = [];
-        if (result.bmad) {
-            statuses.push(`BMAD: ${result.bmad.isUpToDate ? "up to date" : "behind"}`);
-        }
-        if (result.ralph) {
-            statuses.push(`Ralph: ${result.ralph.isUpToDate ? "up to date" : "behind"}`);
-        }
-        return { label, passed: true, detail: statuses.join(", ") };
+        return {
+            label,
+            passed: true,
+            detail: `BMAD: ${result.bmad.isUpToDate ? "up to date" : "behind"}`,
+        };
     }
     catch (err) {
         return { label, passed: true, detail: `skipped: ${formatError(err)}` };

package/dist/commands/init.js

@@ -79,8 +79,7 @@ async function runInit(options) {
     }
     catch (err) {
         throw new Error(`Partial installation: files were copied but configuration failed. ` +
-            `Run 'bmalph init' again to retry. ` +
-            `Cause: ${err instanceof Error ? err.message : String(err)}`);
+            `Run 'bmalph init' again to retry.`, { cause: err });
     }
     console.log(chalk.green("\nbmalph initialized successfully!"));
     console.log(`\n  Project: ${chalk.bold(config.name)}`);

package/dist/installer.d.ts

@@ -1,7 +1,6 @@
 export declare function getPackageVersion(): string;
 export interface BundledVersions {
     bmadCommit: string;
-    ralphCommit: string;
 }
 export declare function getBundledVersions(): BundledVersions;
 export declare function getBundledBmadDir(): string;
@@ -18,6 +17,7 @@ export interface PreviewInstallResult {
 export interface PreviewUpgradeResult {
     wouldUpdate: string[];
     wouldCreate: string[];
+    wouldPreserve: string[];
 }
 export declare function copyBundledAssets(projectDir: string): Promise<UpgradeResult>;
 export declare function installProject(projectDir: string): Promise<void>;

package/dist/installer.js

@@ -22,21 +22,18 @@ export function getBundledVersions() {
     const versionsPath = join(__dirname, "..", "bundled-versions.json");
     try {
         const versions = JSON.parse(readFileSync(versionsPath, "utf-8"));
-        if (!versions ||
-            typeof versions.bmadCommit !== "string" ||
-            typeof versions.ralphCommit !== "string") {
-            throw new Error("Invalid bundled-versions.json structure: missing bmadCommit or ralphCommit");
+        if (!versions || typeof versions.bmadCommit !== "string") {
+            throw new Error("Invalid bundled-versions.json structure: missing bmadCommit");
         }
         return {
             bmadCommit: versions.bmadCommit,
-            ralphCommit: versions.ralphCommit,
         };
     }
     catch (err) {
         if (err instanceof Error && err.message.includes("Invalid bundled-versions.json")) {
             throw err;
         }
-        throw new Error(`Failed to read bundled-versions.json at ${versionsPath}: ${formatError(err)}`);
+        throw new Error(`Failed to read bundled-versions.json at ${versionsPath}`, { cause: err });
     }
 }
 export function getBundledBmadDir() {
@@ -48,6 +45,24 @@ export function getBundledRalphDir() {
 export function getSlashCommandsDir() {
     return join(__dirname, "..", "slash-commands");
 }
+const TEMPLATE_PLACEHOLDERS = {
+    "PROMPT.md": "[YOUR PROJECT NAME]",
+    "AGENT.md": "pip install -r requirements.txt",
+};
+async function isTemplateCustomized(filePath, templateName) {
+    const placeholder = TEMPLATE_PLACEHOLDERS[templateName];
+    if (!placeholder)
+        return false;
+    try {
+        const content = await readFile(filePath, "utf-8");
+        return !content.includes(placeholder);
+    }
+    catch (err) {
+        if (isEnoent(err))
+            return false;
+        throw err;
+    }
+}
 export async function copyBundledAssets(projectDir) {
     const bmadDir = getBundledBmadDir();
     const ralphDir = getBundledRalphDir();
@@ -102,12 +117,19 @@ modules:
 `);
     // Copy Ralph templates → .ralph/
     await mkdir(join(projectDir, ".ralph"), { recursive: true });
-    await cp(join(ralphDir, "templates/PROMPT.md"), join(projectDir, ".ralph/PROMPT.md"), {
-        dereference: false,
-    });
-    await cp(join(ralphDir, "templates/AGENT.md"), join(projectDir, ".ralph/@AGENT.md"), {
-        dereference: false,
-    });
+    // Preserve customized PROMPT.md and @AGENT.md on upgrade
+    const promptCustomized = await isTemplateCustomized(join(projectDir, ".ralph/PROMPT.md"), "PROMPT.md");
+    const agentCustomized = await isTemplateCustomized(join(projectDir, ".ralph/@AGENT.md"), "AGENT.md");
+    if (!promptCustomized) {
+        await cp(join(ralphDir, "templates/PROMPT.md"), join(projectDir, ".ralph/PROMPT.md"), {
+            dereference: false,
+        });
+    }
+    if (!agentCustomized) {
+        await cp(join(ralphDir, "templates/AGENT.md"), join(projectDir, ".ralph/@AGENT.md"), {
+            dereference: false,
+        });
+    }
     await cp(join(ralphDir, "RALPH-REFERENCE.md"), join(projectDir, ".ralph/RALPH-REFERENCE.md"), {
         dereference: false,
     });
@@ -163,20 +185,19 @@ modules:
     }
     // Update .gitignore
     await updateGitignore(projectDir);
-    return {
-        updatedPaths: [
-            "_bmad/",
-            ".ralph/ralph_loop.sh",
-            ".ralph/ralph_import.sh",
-            ".ralph/ralph_monitor.sh",
-            ".ralph/lib/",
-            ".ralph/PROMPT.md",
-            ".ralph/@AGENT.md",
-            ".ralph/RALPH-REFERENCE.md",
-            ".claude/commands/",
-            ".gitignore",
-        ],
-    };
+    const updatedPaths = [
+        "_bmad/",
+        ".ralph/ralph_loop.sh",
+        ".ralph/ralph_import.sh",
+        ".ralph/ralph_monitor.sh",
+        ".ralph/lib/",
+        ...(!promptCustomized ? [".ralph/PROMPT.md"] : []),
+        ...(!agentCustomized ? [".ralph/@AGENT.md"] : []),
+        ".ralph/RALPH-REFERENCE.md",
+        ".claude/commands/",
+        ".gitignore",
+    ];
+    return { updatedPaths };
 }
 export async function installProject(projectDir) {
     // Create user directories (not overwritten by upgrade)
@@ -410,21 +431,28 @@ export async function previewUpgrade(projectDir) {
         { path: ".ralph/ralph_import.sh", isDir: false },
         { path: ".ralph/ralph_monitor.sh", isDir: false },
         { path: ".ralph/lib/", isDir: true },
-        { path: ".ralph/PROMPT.md", isDir: false },
-        { path: ".ralph/@AGENT.md", isDir: false },
+        { path: ".ralph/PROMPT.md", isDir: false, templateName: "PROMPT.md" },
+        { path: ".ralph/@AGENT.md", isDir: false, templateName: "AGENT.md" },
         { path: ".ralph/RALPH-REFERENCE.md", isDir: false },
         { path: ".claude/commands/", isDir: true },
         { path: ".gitignore", isDir: false },
     ];
     const wouldUpdate = [];
     const wouldCreate = [];
-    for (const { path: p } of managedPaths) {
-        if (await exists(join(projectDir, p.replace(/\/$/, "")))) {
-            wouldUpdate.push(p);
+    const wouldPreserve = [];
+    for (const { path: p, templateName } of managedPaths) {
+        const fullPath = join(projectDir, p.replace(/\/$/, ""));
+        if (await exists(fullPath)) {
+            if (templateName && (await isTemplateCustomized(fullPath, templateName))) {
+                wouldPreserve.push(p);
+            }
+            else {
+                wouldUpdate.push(p);
+            }
         }
         else {
             wouldCreate.push(p);
         }
     }
-    return { wouldUpdate, wouldCreate };
+    return { wouldUpdate, wouldCreate, wouldPreserve };
 }

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

@@ -1,5 +1,5 @@
 import type { Story, FixPlanItemWithTitle } from "./types.js";
-export declare function generateFixPlan(stories: Story[]): string;
+export declare function generateFixPlan(stories: Story[], storiesFileName?: string): string;
 export declare function hasFixPlanProgress(content: string): boolean;
 export declare function parseFixPlan(content: string): FixPlanItemWithTitle[];
 /**

package/dist/transition/fix-plan.js

@@ -1,4 +1,4 @@
-export function generateFixPlan(stories) {
+export function generateFixPlan(stories, storiesFileName) {
     const lines = ["# Ralph Fix Plan", "", "## Stories to Implement", ""];
     let currentEpic = "";
     for (const story of stories) {
@@ -25,7 +25,8 @@ export function generateFixPlan(stories) {
         }
         // Add spec-link for easy reference to full story details
         const anchor = story.id.replace(".", "-");
-        lines.push(`  > Spec: specs/planning-artifacts/stories.md#story-${anchor}`);
+        const fileName = storiesFileName ?? "stories.md";
+        lines.push(`  > Spec: specs/planning-artifacts/${fileName}#story-${anchor}`);
     }
     lines.push("", "## Completed", "", "## Notes", "- Follow TDD methodology (red-green-refactor)", "- One story per Ralph loop iteration", "- Update this file after completing each story", "");
     return lines.join("\n");

package/dist/transition/orchestration.js

@@ -64,7 +64,7 @@ export async function runTransition(projectDir) {
     }
     // Generate new fix_plan from current stories, preserving completion status
     info(`Generating fix plan for ${stories.length} stories...`);
-    const newFixPlan = generateFixPlan(stories);
+    const newFixPlan = generateFixPlan(stories, storiesFile);
     const mergedFixPlan = mergeFixPlanProgress(newFixPlan, completedIds);
     await atomicWriteFile(fixPlanPath, mergedFixPlan);
     // Track whether progress was preserved for return value

package/dist/transition/specs-index.js

@@ -10,14 +10,13 @@ export function detectSpecFileType(filename, _content) {
     if (lower.includes("arch"))
         return "architecture";
     // Check stories/epic BEFORE brainstorm (Bug #5: brainstorm-stories.md should be "stories")
-    // Use "stori" to match "stories"/"story" but not "brainstorm" (which contains "stor")
-    if (lower.includes("stori") || lower.includes("epic"))
+    if (/stor(y|ies)/i.test(lower) || lower.includes("epic"))
         return "stories";
     if (lower.includes("brainstorm"))
         return "brainstorm";
     if (lower.includes("ux"))
         return "ux";
-    if (lower.includes("test"))
+    if (/\btest/i.test(lower))
         return "test-design";
     if (lower.includes("readiness"))
         return "readiness";

package/dist/utils/config.d.ts

@@ -1,6 +1,5 @@
 export interface UpstreamVersions {
     bmadCommit: string;
-    ralphCommit: string;
 }
 export interface BmalphConfig {
     name: string;

package/dist/utils/errors.js

@@ -30,6 +30,9 @@ export function isEnoent(err) {
 }
 export function formatError(error) {
     if (error instanceof Error) {
+        if (error.cause) {
+            return `${error.message}: ${formatError(error.cause)}`;
+        }
         return error.message;
     }
     return String(error);

package/dist/utils/github.d.ts

@@ -32,7 +32,6 @@ export interface UpstreamStatus {
 }
 export interface CheckUpstreamResult {
     bmad: UpstreamStatus | null;
-    ralph: UpstreamStatus | null;
     errors: GitHubError[];
 }
 interface FetchOptions {

package/dist/utils/github.js

@@ -4,11 +4,6 @@ const BMAD_REPO = {
     repo: "BMAD-METHOD",
     branch: "main",
 };
-const RALPH_REPO = {
-    owner: "snarktank",
-    repo: "ralph",
-    branch: "main",
-};
 const DEFAULT_TIMEOUT_MS = 10000;
 const DEFAULT_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const DEFAULT_MAX_CACHE_SIZE = 100;
@@ -182,27 +177,15 @@ export class GitHubClient {
     async checkUpstream(bundled) {
         const errors = [];
         let bmadStatus = null;
-        let ralphStatus = null;
-        // Fetch both in parallel
-        const [bmadResult, ralphResult] = await Promise.all([
-            this.fetchLatestCommit(BMAD_REPO),
-            this.fetchLatestCommit(RALPH_REPO),
-        ]);
+        const bmadResult = await this.fetchLatestCommit(BMAD_REPO);
         if (bmadResult.success) {
             bmadStatus = buildUpstreamStatus(BMAD_REPO, bundled.bmadCommit, bmadResult.data.shortSha);
         }
         else {
             errors.push({ ...bmadResult.error, repo: "bmad" });
         }
-        if (ralphResult.success) {
-            ralphStatus = buildUpstreamStatus(RALPH_REPO, bundled.ralphCommit, ralphResult.data.shortSha);
-        }
-        else {
-            errors.push({ ...ralphResult.error, repo: "ralph" });
-        }
         return {
             bmad: bmadStatus,
-            ralph: ralphStatus,
             errors,
         };
     }

package/dist/utils/json.js

@@ -1,5 +1,5 @@
 import { readFile } from "fs/promises";
-import { isEnoent, formatError } from "./errors.js";
+import { isEnoent } from "./errors.js";
 /**
  * Reads and parses a JSON file with proper error discrimination:
  * - File not found → returns null
@@ -21,6 +21,6 @@ export async function readJsonFile(path) {
         return JSON.parse(content);
     }
     catch (err) {
-        throw new Error(`Invalid JSON in ${path}: ${formatError(err)}`);
+        throw new Error(`Invalid JSON in ${path}`, { cause: err });
     }
 }

package/dist/utils/state.js

@@ -1,7 +1,7 @@
 import { mkdir } from "fs/promises";
 import { join } from "path";
 import { readJsonFile } from "./json.js";
-import { validateState, validateRalphLoopStatus } from "./validate.js";
+import { validateState, validateRalphLoopStatus, normalizeRalphStatus } from "./validate.js";
 import { STATE_DIR, RALPH_STATUS_FILE } from "./constants.js";
 import { atomicWriteFile } from "./file-system.js";
 import { warn } from "./logger.js";
@@ -186,6 +186,12 @@ export async function readRalphStatus(projectDir) {
     try {
         return validateRalphLoopStatus(data);
     }
+    catch {
+        // camelCase validation failed — try bash snake_case format
+    }
+    try {
+        return normalizeRalphStatus(data);
+    }
     catch (err) {
         warn(`Ralph status file is corrupted, using defaults: ${formatError(err)}`);
         return DEFAULT_RALPH_STATUS;

package/dist/utils/validate.d.ts

@@ -27,6 +27,7 @@ export interface RalphLoopStatus {
     tasksTotal: number;
 }
 export declare function validateRalphLoopStatus(data: unknown): RalphLoopStatus;
+export declare function normalizeRalphStatus(data: unknown): RalphLoopStatus;
 /**
  * Validates a project name for filesystem safety.
  * Checks for:

package/dist/utils/validate.js

@@ -37,12 +37,8 @@ function validateUpstreamVersions(data) {
     if (typeof data.bmadCommit !== "string") {
         throw new Error("upstreamVersions.bmadCommit must be a string");
     }
-    if (typeof data.ralphCommit !== "string") {
-        throw new Error("upstreamVersions.ralphCommit must be a string");
-    }
     return {
         bmadCommit: data.bmadCommit,
-        ralphCommit: data.ralphCommit,
     };
 }
 export function validateConfig(data) {
@@ -158,6 +154,25 @@ export function validateRalphLoopStatus(data) {
         tasksTotal: data.tasksTotal,
     };
 }
+const BASH_STATUS_MAP = {
+    running: "running",
+    halted: "blocked",
+    stopped: "blocked",
+    completed: "completed",
+    success: "completed",
+};
+export function normalizeRalphStatus(data) {
+    assertObject(data, "normalizeRalphStatus");
+    const loopCount = typeof data.loop_count === "number" ? data.loop_count : 0;
+    const rawStatus = typeof data.status === "string" ? data.status : undefined;
+    const status = (rawStatus !== undefined ? BASH_STATUS_MAP[rawStatus] : undefined) ?? "running";
+    return {
+        loopCount,
+        status,
+        tasksCompleted: 0,
+        tasksTotal: 0,
+    };
+}
 /**
  * Validates a project name for filesystem safety.
  * Checks for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmalph",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop for Claude Code",
   "type": "module",
   "bin": {
@@ -63,13 +63,13 @@
     "inquirer": "^13.2.1"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
+    "@eslint/js": "^10.0.1",
     "@types/node": "^20.0.0",
     "@vitest/coverage-v8": "^4.0.18",
-    "eslint": "^9.39.2",
+    "eslint": "^10.0.1",
     "prettier": "^3.8.1",
     "typescript": "^5.9.3",
-    "typescript-eslint": "^8.53.1",
+    "typescript-eslint": "^8.56.0",
     "vitest": "^4.0.18"
   }
 }