fix: improve installer validation, transition matching, and state atomicity

- Add source directory validation in copyBundledAssets
- Replace loose epic file matching with proper regex pattern
- Add atomic writes (write-to-temp-then-rename) for state files
- Add --verbose flag with debug logging utility
- Add version marker injection to ralph_loop.sh

Author: LarsCowe

package.json

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

src/cli.ts

@@ -5,13 +5,20 @@ import { resetCommand } from "./commands/reset.js";
 import { upgradeCommand } from "./commands/upgrade.js";
 import { statusCommand } from "./commands/status.js";
 import { doctorCommand } from "./commands/doctor.js";
+import { setVerbose } from "./utils/logger.js";
 
 const program = new Command();
 
 program
   .name("bmalph")
   .description("BMAD-METHOD + Ralph integration — structured planning to autonomous implementation")
-  .version("0.8.0");
+  .version("0.8.1")
+  .option("--verbose", "Enable debug logging")
+  .hook("preAction", () => {
+    if (program.opts().verbose) {
+      setVerbose(true);
+    }
+  });
 
 program
   .command("init")

src/installer.ts

@@ -33,6 +33,23 @@ export async function copyBundledAssets(projectDir: string): Promise<UpgradeResu
   const ralphDir = getRalphDir();
   const slashCommandsDir = getSlashCommandsDir();
 
+  // Validate source directories exist
+  try {
+    await access(bmadDir);
+  } catch {
+    throw new Error(`BMAD source directory not found at ${bmadDir}. Package may be corrupted.`);
+  }
+  try {
+    await access(ralphDir);
+  } catch {
+    throw new Error(`Ralph source directory not found at ${ralphDir}. Package may be corrupted.`);
+  }
+  try {
+    await access(slashCommandsDir);
+  } catch {
+    throw new Error(`Slash commands directory not found at ${slashCommandsDir}. Package may be corrupted.`);
+  }
+
   // Copy BMAD files → _bmad/
   await cp(bmadDir, join(projectDir, "_bmad"), { recursive: true });
 

src/transition.ts

@@ -1,5 +1,6 @@
 import { readFile, writeFile, readdir, cp, mkdir, access } from "fs/promises";
 import { join } from "path";
+import { debug } from "./utils/logger.js";
 
 export interface Story {
   epic: string;
@@ -17,13 +18,17 @@ export async function findArtifactsDir(projectDir: string): Promise<string | nul
   ];
 
   for (const candidate of candidates) {
+    const fullPath = join(projectDir, candidate);
+    debug(`Checking artifacts dir: ${fullPath}`);
     try {
-      await access(join(projectDir, candidate));
-      return join(projectDir, candidate);
+      await access(fullPath);
+      debug(`Found artifacts at: ${fullPath}`);
+      return fullPath;
     } catch {
       continue;
     }
   }
+  debug(`No artifacts found. Checked: ${candidates.join(", ")}`);
   return null;
 }
 
@@ -240,15 +245,18 @@ export async function runTransition(projectDir: string): Promise<{ storiesCount:
 
   // Find and parse stories file
   const files = await readdir(artifactsDir);
+  const STORIES_PATTERN = /^(epics[-_]?(and[-_]?)?)?stor(y|ies)([-_]\d+)?\.md$/i;
   const storiesFile = files.find(
-    (f) => f.includes("epic") || f.includes("stories") || f.includes("story"),
+    (f) => STORIES_PATTERN.test(f) || /epic/i.test(f),
   );
 
   if (!storiesFile) {
+    debug(`Files in artifacts dir: ${files.join(", ")}`);
     throw new Error(
-      "No epics/stories file found in artifacts. Run 'CE' (Create Epics and Stories) first.",
+      `No epics/stories file found in ${artifactsDir}. Available files: ${files.join(", ")}. Run 'CE' (Create Epics and Stories) first.`,
     );
   }
+  debug(`Using stories file: ${storiesFile}`);
 
   const storiesContent = await readFile(join(artifactsDir, storiesFile), "utf-8");
   const stories = parseStories(storiesContent);

src/utils/logger.ts

@@ -0,0 +1,17 @@
+import chalk from "chalk";
+
+let verbose = false;
+
+export function setVerbose(value: boolean): void {
+  verbose = value;
+}
+
+export function isVerbose(): boolean {
+  return verbose;
+}
+
+export function debug(message: string): void {
+  if (verbose) {
+    console.log(chalk.dim(`[debug] ${message}`));
+  }
+}

src/utils/state.ts

@@ -1,4 +1,4 @@
-import { writeFile, mkdir } from "fs/promises";
+import { writeFile, mkdir, rename } from "fs/promises";
 import { join } from "path";
 import { readJsonFile } from "./json.js";
 import { validateState } from "./validate.js";
@@ -34,10 +34,10 @@ export async function readState(projectDir: string): Promise<BmalphState | null>
 
 export async function writeState(projectDir: string, state: BmalphState): Promise<void> {
   await mkdir(join(projectDir, STATE_DIR), { recursive: true });
-  await writeFile(
-    join(projectDir, STATE_DIR, "current-phase.json"),
-    JSON.stringify(state, null, 2) + "\n",
-  );
+  const target = join(projectDir, STATE_DIR, "current-phase.json");
+  const tmp = target + ".tmp";
+  await writeFile(tmp, JSON.stringify(state, null, 2) + "\n");
+  await rename(tmp, target);
 }
 
 export function getPhaseLabel(phase: number): string {