bmalph 2.2.1 → 2.4.0

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-changelog.js

@@ -36,7 +36,10 @@ export async function generateSpecsChangelog(oldSpecsDir, newSourceDir) {
                 debug(`Could not read old spec file ${file}: ${formatError(err)}`);
                 return "";
             });
-            const newContent = await readFile(join(newSourceDir, file), "utf-8");
+            const newContent = await readFile(join(newSourceDir, file), "utf-8").catch((err) => {
+                debug(`Could not read new spec file ${file}: ${formatError(err)}`);
+                return "";
+            });
             if (oldContent !== newContent) {
                 changes.push({
                     file,

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/config.d.ts

@@ -1,3 +1,4 @@
+import type { PlatformId } from "../platform/types.js";
 export interface UpstreamVersions {
     bmadCommit: string;
 }
@@ -5,6 +6,7 @@ export interface BmalphConfig {
     name: string;
     description: string;
     createdAt: string;
+    platform?: PlatformId;
     upstreamVersions?: UpstreamVersions;
 }
 export declare function readConfig(projectDir: string): Promise<BmalphConfig | null>;

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

@@ -1,4 +1,12 @@
 import { MAX_PROJECT_NAME_LENGTH } from "./constants.js";
+const VALID_PLATFORM_IDS = [
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "copilot",
+    "aider",
+];
 const VALID_STATUSES = ["planning", "implementing", "completed"];
 // Invalid filesystem characters (Windows + POSIX)
 const INVALID_FS_CHARS = /[<>:"/\\|?*]/;
@@ -50,6 +58,13 @@ export function validateConfig(data) {
         throw new Error("config.createdAt must be a string");
     }
     const description = typeof data.description === "string" ? data.description : "";
+    let platform;
+    if (data.platform !== undefined) {
+        if (typeof data.platform !== "string" || !VALID_PLATFORM_IDS.includes(data.platform)) {
+            throw new Error(`config.platform must be one of: ${VALID_PLATFORM_IDS.join(", ")}`);
+        }
+        platform = data.platform;
+    }
     const upstreamVersions = data.upstreamVersions !== undefined
         ? validateUpstreamVersions(data.upstreamVersions)
         : undefined;
@@ -57,6 +72,7 @@ export function validateConfig(data) {
         name: data.name,
         description,
         createdAt: data.createdAt,
+        ...(platform !== undefined && { platform }),
         upstreamVersions,
     };
 }
@@ -169,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.2.1",
+  "version": "2.4.0",
   "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop for Claude Code",
   "type": "module",
   "bin": {

package/ralph/drivers/claude-code.sh

@@ -0,0 +1,118 @@
+#!/bin/bash
+# Claude Code driver for Ralph
+# Provides platform-specific CLI invocation logic
+
+# Driver identification
+driver_name() {
+    echo "claude-code"
+}
+
+driver_display_name() {
+    echo "Claude Code"
+}
+
+driver_cli_binary() {
+    echo "claude"
+}
+
+driver_min_version() {
+    echo "2.0.76"
+}
+
+# Check if the CLI binary is available
+driver_check_available() {
+    command -v "$(driver_cli_binary)" &>/dev/null
+}
+
+# Valid tool patterns for --allowedTools validation
+# Sets the global VALID_TOOL_PATTERNS array
+driver_valid_tools() {
+    VALID_TOOL_PATTERNS=(
+        "Write"
+        "Read"
+        "Edit"
+        "MultiEdit"
+        "Glob"
+        "Grep"
+        "Task"
+        "TodoWrite"
+        "WebFetch"
+        "WebSearch"
+        "Bash"
+        "Bash(git *)"
+        "Bash(npm *)"
+        "Bash(bats *)"
+        "Bash(python *)"
+        "Bash(node *)"
+        "NotebookEdit"
+    )
+}
+
+# Build the CLI command arguments
+# Populates global CLAUDE_CMD_ARGS array
+# Parameters:
+#   $1 - prompt_file: path to the prompt file
+#   $2 - loop_context: context string for session continuity
+#   $3 - session_id: session ID for resume (empty for new session)
+driver_build_command() {
+    local prompt_file=$1
+    local loop_context=$2
+    local session_id=$3
+
+    # Note: We do NOT use --dangerously-skip-permissions here. Tool permissions
+    # are controlled via --allowedTools from CLAUDE_ALLOWED_TOOLS in .ralphrc.
+    # This preserves the permission denial circuit breaker (Issue #101).
+    CLAUDE_CMD_ARGS=("$(driver_cli_binary)")
+
+    if [[ ! -f "$prompt_file" ]]; then
+        echo "ERROR: Prompt file not found: $prompt_file" >&2
+        return 1
+    fi
+
+    # Output format
+    if [[ "$CLAUDE_OUTPUT_FORMAT" == "json" ]]; then
+        CLAUDE_CMD_ARGS+=("--output-format" "json")
+    fi
+
+    # Allowed tools
+    if [[ -n "$CLAUDE_ALLOWED_TOOLS" ]]; then
+        CLAUDE_CMD_ARGS+=("--allowedTools")
+        local IFS=','
+        read -ra tools_array <<< "$CLAUDE_ALLOWED_TOOLS"
+        for tool in "${tools_array[@]}"; do
+            tool=$(echo "$tool" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')
+            if [[ -n "$tool" ]]; then
+                CLAUDE_CMD_ARGS+=("$tool")
+            fi
+        done
+    fi
+
+    # Session resume
+    # IMPORTANT: Use --resume with explicit session ID instead of --continue.
+    # --continue resumes the "most recent session in current directory" which
+    # can hijack active Claude Code sessions. --resume with a specific session ID
+    # ensures we only resume Ralph's own sessions. (Issue #151)
+    if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
+        CLAUDE_CMD_ARGS+=("--resume" "$session_id")
+    fi
+
+    # Loop context as system prompt
+    if [[ -n "$loop_context" ]]; then
+        CLAUDE_CMD_ARGS+=("--append-system-prompt" "$loop_context")
+    fi
+
+    # Prompt content
+    local prompt_content
+    prompt_content=$(cat "$prompt_file")
+    CLAUDE_CMD_ARGS+=("-p" "$prompt_content")
+}
+
+# Whether this driver supports session continuity
+driver_supports_sessions() {
+    return 0  # true
+}
+
+# Stream filter for live output (jq filter for JSON streaming)
+driver_stream_filter() {
+    echo '.content // empty | select(type == "string")'
+}

package/ralph/drivers/codex.sh

@@ -0,0 +1,81 @@
+#!/bin/bash
+# OpenAI Codex driver for Ralph
+# Provides platform-specific CLI invocation logic for Codex
+
+driver_name() {
+    echo "codex"
+}
+
+driver_display_name() {
+    echo "OpenAI Codex"
+}
+
+driver_cli_binary() {
+    echo "codex"
+}
+
+driver_min_version() {
+    echo "0.1.0"
+}
+
+driver_check_available() {
+    command -v "$(driver_cli_binary)" &>/dev/null
+}
+
+# Codex tool names differ from Claude Code
+driver_valid_tools() {
+    VALID_TOOL_PATTERNS=(
+        "shell"
+        "read_file"
+        "write_file"
+        "edit_file"
+        "list_directory"
+        "search_files"
+    )
+}
+
+# Build Codex CLI command
+# Codex uses: codex exec [--resume <id>] --json "prompt"
+driver_build_command() {
+    local prompt_file=$1
+    local loop_context=$2
+    local session_id=$3
+
+    CLAUDE_CMD_ARGS=("$(driver_cli_binary)" "exec")
+
+    if [[ ! -f "$prompt_file" ]]; then
+        echo "ERROR: Prompt file not found: $prompt_file" >&2
+        return 1
+    fi
+
+    # JSON output
+    CLAUDE_CMD_ARGS+=("--json")
+
+    # Sandbox mode - workspace write access
+    CLAUDE_CMD_ARGS+=("--sandbox" "workspace-write")
+
+    # Session resume — gated on CLAUDE_USE_CONTINUE to respect --no-continue flag
+    if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
+        CLAUDE_CMD_ARGS+=("--resume" "$session_id")
+    fi
+
+    # Build prompt with context
+    local prompt_content
+    prompt_content=$(cat "$prompt_file")
+    if [[ -n "$loop_context" ]]; then
+        prompt_content="$loop_context
+
+$prompt_content"
+    fi
+
+    CLAUDE_CMD_ARGS+=("$prompt_content")
+}
+
+driver_supports_sessions() {
+    return 0  # true - Codex supports session resume
+}
+
+# Codex outputs JSONL events
+driver_stream_filter() {
+    echo 'select(.type == "message") | .content // empty'
+}

package/ralph/ralph_import.sh

@@ -7,6 +7,17 @@ set -e
 # Configuration
 CLAUDE_CODE_CMD="claude"
 
+# Platform driver support
+SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
+PLATFORM_DRIVER="${PLATFORM_DRIVER:-claude-code}"
+
+# Source platform driver if available
+if [[ -f "$SCRIPT_DIR/drivers/${PLATFORM_DRIVER}.sh" ]]; then
+    # shellcheck source=/dev/null
+    source "$SCRIPT_DIR/drivers/${PLATFORM_DRIVER}.sh"
+    CLAUDE_CODE_CMD="$(driver_cli_binary)"
+fi
+
 # Modern CLI Configuration (Phase 1.1)
 # These flags enable structured JSON output and controlled file operations
 CLAUDE_OUTPUT_FORMAT="json"