feat(implement): Updated Planning artifact detection to use _bmad/config.yaml first (#138)

* feat(implement): Updated Planning artifact detection to use _bmad/config.yaml configuration. If not found, continue with normal artifactDir search flow.

* feat(implement): Generalizing BMAD config.yaml loading and defining constant variables

* docs(ralph): add driver interface contract for ralph_loop.sh (#139)

Document the sourceable driver contract: required hooks, optional
capability hooks, metadata hooks, global variables, capability matrix,
session ID recovery chain, and a minimal skeleton for new drivers.

Closes #135

* fix(run): trust RALPH_STATUS block over heuristic analysis (#140)

When a valid RALPH_STATUS block is parsed from text output, skip all
heuristic analysis (completion keywords, test-only detection, stuck
detection, no-work patterns, output length trends). The status block
is authoritative — heuristics only run as fallback when no block is
present. This brings the text path to parity with the JSON path which
already returns early on structured data.

Also fix a pre-existing division-by-zero bug in output length trend
analysis when .last_output_length contains 0.

Fixes: #123

* fix(implement): Addressing code concerns. Added test coverage, validating BMAD configuration, preventing path traversal risk, validating directory existence.

* fix(installer): Updating bmad-assets.ts to use new constant.

* fix(utils): Update error handling for isDirectory() to match exists()

* fix(artifacts): Fixing blocking finding with path validation

* fix(utils): Adding unit tests for isDirectory()

* fix(utils): Updating validation for modules in BmadConfig

* fix(artifacts): Handling if planning_artifacts is whitespace edge case

* fix(tests): Adding additional test coverages for artifact and config validation functions

* fix(artifacts): Fixing Windows path test failure

---------

Co-authored-by: Lars <120098061+LarsCowe@users.noreply.github.com>

Author: clee231

package-lock.json

@@ -66,7 +66,8 @@
     "@inquirer/input": "^4.1.9",
     "@inquirer/select": "^4.2.0",
     "chalk": "^5.6.2",
-    "commander": "^14.0.2"
+    "commander": "^14.0.2",
+    "yaml": "^2.8.3"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package.json

@@ -3,7 +3,7 @@ import { basename, join } from "node:path";
 import { debug, warn } from "../utils/logger.js";
 import { atomicWriteFile, exists } from "../utils/file-system.js";
 import { formatError, isEnoent } from "../utils/errors.js";
-import { CONFIG_FILE } from "../utils/constants.js";
+import { CONFIG_FILE, BMAD_CONFIG_FILE } from "../utils/constants.js";
 import type { Platform } from "../platform/types.js";
 import { classifyCommands, generateCommandIndex } from "./commands.js";
 import type { ClassifiedCommand } from "./types.js";
@@ -167,7 +167,7 @@ async function finalizeBmadInstall(
   const projectName = await deriveProjectName(projectDir);
   const escapedName = projectName.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
   await atomicWriteFile(
-    join(projectDir, "_bmad/config.yaml"),
+    join(projectDir, BMAD_CONFIG_FILE),
     `# BMAD Configuration - Generated by bmalph
 platform: ${platform.id}
 project_name: "${escapedName}"

src/installer/bmad-assets.ts

@@ -1,8 +1,24 @@
-import { join, relative } from "node:path";
-import { debug } from "../utils/logger.js";
-import { exists } from "../utils/file-system.js";
+import { join, relative, resolve, sep } from "node:path";
+import { debug, warn } from "../utils/logger.js";
+import { isDirectory } from "../utils/file-system.js";
+import { readBmadConfig } from "../utils/config.js";
 
 export async function findArtifactsDir(projectDir: string): Promise<string | null> {
+  const bmadConfig = await readBmadConfig(projectDir);
+  const trimmed = bmadConfig?.planning_artifacts?.trim();
+  if (trimmed) {
+    const resolved = resolve(projectDir, trimmed);
+    debug(`Checking config-specified artifacts dir: ${resolved}`);
+
+    const projectRoot = resolve(projectDir);
+    if (!resolved.startsWith(projectRoot + sep) && resolved !== projectRoot) {
+      warn(`planning_artifacts path escapes project directory, ignoring: ${trimmed}`);
+    } else if (await isDirectory(resolved)) {
+      debug(`Found artifacts at: ${resolved}`);
+      return resolved;
+    }
+  }
+
   const candidates = [
     "_bmad-output/planning-artifacts",
     "_bmad-output/planning_artifacts",
@@ -12,7 +28,7 @@ export async function findArtifactsDir(projectDir: string): Promise<string | nul
   for (const candidate of candidates) {
     const fullPath = join(projectDir, candidate);
     debug(`Checking artifacts dir: ${fullPath}`);
-    if (await exists(fullPath)) {
+    if (await isDirectory(fullPath)) {
       debug(`Found artifacts at: ${fullPath}`);
       return fullPath;
     }

src/transition/artifacts.ts

@@ -1,17 +1,32 @@
-import { mkdir } from "node:fs/promises";
+import { mkdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { parse } from "yaml";
 import { readJsonFile } from "./json.js";
-import { validateConfig } from "./validate.js";
-import { CONFIG_FILE } from "./constants.js";
+import { validateConfig, validateBmadConfig } from "./validate.js";
+import { CONFIG_FILE, BMAD_CONFIG_FILE } from "./constants.js";
 import { atomicWriteFile } from "./file-system.js";
-import { warn } from "./logger.js";
-import { formatError } from "./errors.js";
+import { warn, debug } from "./logger.js";
+import { formatError, isEnoent } from "./errors.js";
 import type { PlatformId } from "../platform/types.js";
 
 export interface UpstreamVersions {
   bmadCommit: string;
 }
 
+export interface BmadConfig {
+  platform?: string;
+  project_name?: string;
+  output_folder?: string;
+  user_name?: string;
+  communication_language?: string;
+  document_output_language?: string;
+  user_skill_level?: string;
+  planning_artifacts?: string;
+  implementation_artifacts?: string;
+  project_knowledge?: string;
+  modules?: string[];
+}
+
 export interface BmalphConfig {
   name: string;
   description: string;
@@ -41,3 +56,21 @@ export async function writeConfig(projectDir: string, config: BmalphConfig): Pro
   await mkdir(join(projectDir, "bmalph"), { recursive: true });
   await atomicWriteFile(join(projectDir, CONFIG_FILE), JSON.stringify(config, null, 2) + "\n");
 }
+
+export async function readBmadConfig(projectDir: string): Promise<BmadConfig | null> {
+  const configPath = join(projectDir, BMAD_CONFIG_FILE);
+  try {
+    const content = await readFile(configPath, "utf-8");
+    const parsed: unknown = parse(content);
+    const config = validateBmadConfig(parsed);
+    debug(`Read BMAD config from: ${configPath}`);
+    return config;
+  } catch (err) {
+    if (isEnoent(err)) {
+      debug(`BMAD config not found at: ${configPath}`);
+      return null;
+    }
+    warn(`Error reading BMAD config: ${formatError(err)}`);
+    return null;
+  }
+}

src/utils/config.ts

@@ -71,6 +71,9 @@ export const STATE_DIR = "bmalph/state";
 /** bmalph config file path */
 export const CONFIG_FILE = "bmalph/config.json";
 
+/** BMAD config file path */
+export const BMAD_CONFIG_FILE = "_bmad/config.yaml";
+
 /** Ralph status file path */
 export const RALPH_STATUS_FILE = ".ralph/status.json";
 

src/utils/constants.ts

@@ -16,6 +16,20 @@ export async function exists(path: string): Promise<boolean> {
   }
 }
 
+/**
+ * Checks whether a directory exists at the given path.
+ * Returns false if the path doesn't exist or is a file.
+ */
+export async function isDirectory(path: string): Promise<boolean> {
+  try {
+    const stats = await stat(path);
+    return stats.isDirectory();
+  } catch (err) {
+    if (isEnoent(err)) return false;
+    throw err;
+  }
+}
+
 /**
  * Writes content to a file atomically using a temp file + rename.
  * Prevents partial writes from corrupting the target file.

src/utils/file-system.ts

@@ -1,4 +1,4 @@
-import type { BmalphConfig, UpstreamVersions } from "./config.js";
+import type { BmalphConfig, BmadConfig, UpstreamVersions } from "./config.js";
 import type { BmalphState } from "./state.js";
 import { PLATFORM_IDS, type PlatformId } from "../platform/types.js";
 import {
@@ -95,6 +95,115 @@ export function validateConfig(data: unknown): BmalphConfig {
   };
 }
 
+export function validateBmadConfig(data: unknown): BmadConfig {
+  assertObject(data, "bmadConfig");
+
+  let platform: string | undefined;
+  if (data.platform !== undefined) {
+    if (typeof data.platform !== "string") {
+      throw new Error("bmadConfig.platform must be a string");
+    }
+    platform = data.platform;
+  }
+
+  let project_name: string | undefined;
+  if (data.project_name !== undefined) {
+    if (typeof data.project_name !== "string") {
+      throw new Error("bmadConfig.project_name must be a string");
+    }
+    project_name = data.project_name;
+  }
+
+  let output_folder: string | undefined;
+  if (data.output_folder !== undefined) {
+    if (typeof data.output_folder !== "string") {
+      throw new Error("bmadConfig.output_folder must be a string");
+    }
+    output_folder = data.output_folder;
+  }
+
+  let user_name: string | undefined;
+  if (data.user_name !== undefined) {
+    if (typeof data.user_name !== "string") {
+      throw new Error("bmadConfig.user_name must be a string");
+    }
+    user_name = data.user_name;
+  }
+
+  let communication_language: string | undefined;
+  if (data.communication_language !== undefined) {
+    if (typeof data.communication_language !== "string") {
+      throw new Error("bmadConfig.communication_language must be a string");
+    }
+    communication_language = data.communication_language;
+  }
+
+  let document_output_language: string | undefined;
+  if (data.document_output_language !== undefined) {
+    if (typeof data.document_output_language !== "string") {
+      throw new Error("bmadConfig.document_output_language must be a string");
+    }
+    document_output_language = data.document_output_language;
+  }
+
+  let user_skill_level: string | undefined;
+  if (data.user_skill_level !== undefined) {
+    if (typeof data.user_skill_level !== "string") {
+      throw new Error("bmadConfig.user_skill_level must be a string");
+    }
+    user_skill_level = data.user_skill_level;
+  }
+
+  let planning_artifacts: string | undefined;
+  if (data.planning_artifacts !== undefined) {
+    if (typeof data.planning_artifacts !== "string") {
+      throw new Error("bmadConfig.planning_artifacts must be a string");
+    }
+    planning_artifacts = data.planning_artifacts;
+  }
+
+  let implementation_artifacts: string | undefined;
+  if (data.implementation_artifacts !== undefined) {
+    if (typeof data.implementation_artifacts !== "string") {
+      throw new Error("bmadConfig.implementation_artifacts must be a string");
+    }
+    implementation_artifacts = data.implementation_artifacts;
+  }
+
+  let project_knowledge: string | undefined;
+  if (data.project_knowledge !== undefined) {
+    if (typeof data.project_knowledge !== "string") {
+      throw new Error("bmadConfig.project_knowledge must be a string");
+    }
+    project_knowledge = data.project_knowledge;
+  }
+
+  let modules: string[] | undefined;
+  if (data.modules !== undefined) {
+    if (
+      !Array.isArray(data.modules) ||
+      !data.modules.every((m: unknown) => typeof m === "string")
+    ) {
+      throw new Error("bmadConfig.modules must be an array of strings");
+    }
+    modules = data.modules;
+  }
+
+  return {
+    platform,
+    project_name,
+    output_folder,
+    user_name,
+    communication_language,
+    document_output_language,
+    user_skill_level,
+    planning_artifacts,
+    implementation_artifacts,
+    project_knowledge,
+    modules,
+  };
+}
+
 export function validateState(data: unknown): BmalphState {
   assertObject(data, "state");