bmalph 1.0.0 → 2.2.1

package/dist/transition/context.js

@@ -0,0 +1,261 @@
+import { SECTION_EXTRACT_MAX_LENGTH } from "../utils/constants.js";
+export function extractSection(content, headingPattern, maxLength = SECTION_EXTRACT_MAX_LENGTH) {
+    return extractSectionWithInfo(content, headingPattern, maxLength).content;
+}
+export function extractSectionWithInfo(content, headingPattern, maxLength = SECTION_EXTRACT_MAX_LENGTH) {
+    const match = headingPattern.exec(content);
+    if (!match)
+        return { content: "", wasTruncated: false, originalLength: 0 };
+    // Determine heading level from the match
+    const headingLevelMatch = match[0].match(/^(#{1,6})\s/);
+    const level = headingLevelMatch ? headingLevelMatch[1].length : 2;
+    const startIndex = (match.index ?? 0) + match[0].length;
+    const rest = content.slice(startIndex);
+    // Find next heading of same or higher level
+    const nextHeadingPattern = new RegExp(`^#{1,${level}}\\s`, "m");
+    const nextMatch = nextHeadingPattern.exec(rest);
+    const sectionBody = nextMatch ? rest.slice(0, nextMatch.index) : rest;
+    const trimmed = sectionBody.trim();
+    if (trimmed.length <= maxLength) {
+        return { content: trimmed, wasTruncated: false, originalLength: trimmed.length };
+    }
+    return {
+        content: trimmed.slice(0, maxLength),
+        wasTruncated: true,
+        originalLength: trimmed.length,
+    };
+}
+function extractFromPatternsWithInfo(content, patterns) {
+    for (const pattern of patterns) {
+        const result = extractSectionWithInfo(content, pattern);
+        if (result.content)
+            return result;
+    }
+    return { content: "", wasTruncated: false, originalLength: 0 };
+}
+export function extractProjectContext(artifacts) {
+    // Combine all content, keyed by likely role
+    let prdContent = "";
+    let archContent = "";
+    for (const [filename, content] of artifacts) {
+        if (/prd/i.test(filename))
+            prdContent += "\n" + content;
+        if (/architect/i.test(filename))
+            archContent += "\n" + content;
+        if (/readiness/i.test(filename))
+            archContent += "\n" + content;
+    }
+    const allContent = prdContent + "\n" + archContent;
+    const truncated = [];
+    const fields = [
+        {
+            field: "projectGoals",
+            source: prdContent || allContent,
+            patterns: [
+                /^##\s+Executive Summary/m,
+                /^##\s+Vision/m,
+                /^##\s+Goals/m,
+                /^##\s+Project Goals/m,
+            ],
+        },
+        {
+            field: "successMetrics",
+            source: prdContent || allContent,
+            patterns: [
+                /^##\s+Success (?:Criteria|Metrics)/m,
+                /^##\s+KPIs?/m,
+                /^##\s+Metrics/m,
+                /^##\s+Key Performance/m,
+            ],
+        },
+        {
+            field: "architectureConstraints",
+            source: archContent || allContent,
+            patterns: [/^##\s+Constraints/m, /^##\s+ADR/m, /^##\s+Architecture Decision/m],
+        },
+        {
+            field: "technicalRisks",
+            source: archContent || allContent,
+            patterns: [/^##\s+Risks/m, /^##\s+Technical Risks/m, /^##\s+Mitigations/m, /^##\s+Risk/m],
+        },
+        {
+            field: "scopeBoundaries",
+            source: prdContent || allContent,
+            patterns: [/^##\s+Scope/m, /^##\s+In Scope/m, /^##\s+Out of Scope/m, /^##\s+Boundaries/m],
+        },
+        {
+            field: "targetUsers",
+            source: prdContent || allContent,
+            patterns: [/^##\s+Target Users/m, /^##\s+Users/m, /^##\s+Personas/m, /^##\s+User Profiles/m],
+        },
+        {
+            field: "nonFunctionalRequirements",
+            source: prdContent || allContent,
+            patterns: [
+                /^##\s+Non-Functional/m,
+                /^##\s+NFR/m,
+                /^##\s+Quality/m,
+                /^##\s+Quality Attributes/m,
+            ],
+        },
+    ];
+    const context = {
+        projectGoals: "",
+        successMetrics: "",
+        architectureConstraints: "",
+        technicalRisks: "",
+        scopeBoundaries: "",
+        targetUsers: "",
+        nonFunctionalRequirements: "",
+    };
+    for (const { field, source, patterns } of fields) {
+        const result = extractFromPatternsWithInfo(source, patterns);
+        context[field] = result.content;
+        if (result.wasTruncated) {
+            truncated.push({
+                field,
+                originalLength: result.originalLength,
+                truncatedTo: result.content.length,
+            });
+        }
+    }
+    return {
+        context,
+        truncated,
+    };
+}
+/**
+ * Converts truncation info into human-readable warnings.
+ */
+export function detectTruncation(truncated) {
+    return truncated.map((t) => `${t.field} was truncated from ${t.originalLength} to ${t.truncatedTo} characters. Some content may be missing.`);
+}
+export function generateProjectContextMd(context, projectName) {
+    const lines = [`# ${projectName} — Project Context`, ""];
+    const sections = [
+        { heading: "Project Goals", content: context.projectGoals },
+        { heading: "Success Metrics", content: context.successMetrics },
+        { heading: "Architecture Constraints", content: context.architectureConstraints },
+        { heading: "Technical Risks", content: context.technicalRisks },
+        { heading: "Scope Boundaries", content: context.scopeBoundaries },
+        { heading: "Target Users", content: context.targetUsers },
+        { heading: "Non-Functional Requirements", content: context.nonFunctionalRequirements },
+    ];
+    for (const { heading, content } of sections) {
+        if (content) {
+            lines.push(`## ${heading}`, "", content, "");
+        }
+    }
+    return lines.join("\n");
+}
+export function generatePrompt(projectName, context) {
+    // Build context sections if provided
+    const contextSections = context
+        ? [
+            context.projectGoals && `### Project Goals\n${context.projectGoals}`,
+            context.successMetrics && `### Success Metrics\n${context.successMetrics}`,
+            context.architectureConstraints &&
+                `### Architecture Constraints\n${context.architectureConstraints}`,
+            context.scopeBoundaries && `### Scope\n${context.scopeBoundaries}`,
+            context.technicalRisks && `### Technical Risks\n${context.technicalRisks}`,
+            context.targetUsers && `### Target Users\n${context.targetUsers}`,
+            context.nonFunctionalRequirements &&
+                `### Non-Functional Requirements\n${context.nonFunctionalRequirements}`,
+        ]
+            .filter(Boolean)
+            .join("\n\n")
+        : "";
+    const projectContextBlock = contextSections
+        ? `
+
+## Project Specifications (CRITICAL - READ THIS)
+
+${contextSections}
+`
+        : "";
+    return `# Ralph Development Instructions
+
+## Context
+You are an autonomous AI development agent working on the ${projectName} project.
+You follow BMAD-METHOD's developer (Amelia) persona and TDD methodology.
+${projectContextBlock}
+## Development Methodology (BMAD Dev Agent)
+
+For each story in @fix_plan.md:
+1. Read the story's inline acceptance criteria (lines starting with \`> AC:\`)
+2. Write failing tests first (RED)
+3. Implement minimum code to pass tests (GREEN)
+4. Refactor while keeping tests green (REFACTOR)
+5. Mark story as complete in @fix_plan.md
+6. Commit with descriptive conventional commit message
+
+## Specs Reading Strategy
+1. Read .ralph/SPECS_INDEX.md first for a prioritized overview of all spec files
+2. Follow the reading order in SPECS_INDEX.md:
+   - **Critical**: Always read fully (PRD, architecture, stories)
+   - **High**: Read for implementation details (test design, readiness)
+   - **Medium**: Reference as needed (UX specs, sprint plans)
+   - **Low**: Optional background (brainstorming sessions)
+3. For files marked [LARGE], scan headers first and read relevant sections
+
+## Current Objectives
+1. Read .ralph/PROJECT_CONTEXT.md for project goals, constraints, and scope
+2. Read .ralph/SPECS_INDEX.md for prioritized spec file overview
+3. Study .ralph/specs/ following the reading order in SPECS_INDEX.md:
+   - planning-artifacts/: PRD, architecture, epics/stories, test design, UX
+   - implementation-artifacts/: sprint plans, detailed stories (if present)
+   - brainstorming/: brainstorming sessions (if present)
+4. Check docs/ for project knowledge and research documents (if present)
+5. Review .ralph/@fix_plan.md for current priorities
+6. Implement the highest priority story using TDD
+7. Run tests after each implementation
+8. Update @fix_plan.md with your progress
+
+## Key Principles
+- ONE story per loop - focus completely on it
+- TDD: tests first, always
+- Search the codebase before assuming something isn't implemented
+- Write comprehensive tests with clear documentation
+- Commit working changes with descriptive messages
+
+## Testing Guidelines
+- Write tests BEFORE implementation (TDD)
+- Focus on acceptance criteria from the story
+- Run the full test suite after implementation
+- Fix any regressions immediately
+
+## Status Reporting (CRITICAL)
+
+At the end of your response, ALWAYS include this status block:
+
+\`\`\`
+---RALPH_STATUS---
+STATUS: IN_PROGRESS | COMPLETE | BLOCKED
+TASKS_COMPLETED_THIS_LOOP: <number>
+FILES_MODIFIED: <number>
+TESTS_STATUS: PASSING | FAILING | NOT_RUN
+WORK_TYPE: IMPLEMENTATION | TESTING | DOCUMENTATION | REFACTORING
+EXIT_SIGNAL: false | true
+RECOMMENDATION: <one line summary of what to do next>
+---END_RALPH_STATUS---
+\`\`\`
+
+### When to set EXIT_SIGNAL: true
+1. All items in @fix_plan.md are marked [x]
+2. All tests are passing
+3. No errors in the last execution
+4. All requirements from specs/ are implemented
+
+## File Structure
+- .ralph/SPECS_INDEX.md: Prioritized index of all spec files with reading order
+- .ralph/PROJECT_CONTEXT.md: High-level project goals, constraints, and scope
+- .ralph/specs/: Project specifications (PRD, architecture, stories)
+- .ralph/@fix_plan.md: Prioritized TODO list (one entry per story)
+- .ralph/@AGENT.md: Project build and run instructions
+- .ralph/PROMPT.md: This file
+- .ralph/logs/: Loop execution logs
+
+## Current Task
+Follow .ralph/@fix_plan.md and implement the next incomplete story using TDD.
+`;
+}

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

@@ -0,0 +1,15 @@
+import type { Story, FixPlanItemWithTitle } from "./types.js";
+export declare function generateFixPlan(stories: Story[], storiesFileName?: string): string;
+export declare function hasFixPlanProgress(content: string): boolean;
+export declare function parseFixPlan(content: string): FixPlanItemWithTitle[];
+/**
+ * Detects completed stories that are no longer in the new BMAD output.
+ * Returns warnings for each orphaned completed story.
+ */
+export declare function detectOrphanedCompletedStories(existingItems: FixPlanItemWithTitle[], newStoryIds: Set<string>): string[];
+/**
+ * Detects stories that may have been renumbered by comparing titles.
+ * Returns warnings when a completed story's title appears under a different ID.
+ */
+export declare function detectRenumberedStories(existingItems: FixPlanItemWithTitle[], newStories: Story[]): string[];
+export declare function mergeFixPlanProgress(newFixPlan: string, completedIds: Set<string>): string;

package/dist/transition/fix-plan.js

@@ -0,0 +1,94 @@
+export function generateFixPlan(stories, storiesFileName) {
+    const lines = ["# Ralph Fix Plan", "", "## Stories to Implement", ""];
+    let currentEpic = "";
+    for (const story of stories) {
+        if (story.epic !== currentEpic) {
+            currentEpic = story.epic;
+            lines.push(`### ${currentEpic}`);
+            if (story.epicDescription) {
+                lines.push(`> Goal: ${story.epicDescription}`);
+            }
+            lines.push("");
+        }
+        lines.push(`- [ ] Story ${story.id}: ${story.title}`);
+        // Add description lines (max 3, split on sentence boundaries)
+        if (story.description) {
+            const descParts = story.description.split(/,\s*(?=So that|I want)|(?<=\.)\s+/);
+            for (const part of descParts.slice(0, 3)) {
+                if (part.trim())
+                    lines.push(`  > ${part.trim()}`);
+            }
+        }
+        // Add acceptance criteria
+        for (const ac of story.acceptanceCriteria) {
+            lines.push(`  > AC: ${ac}`);
+        }
+        // Add spec-link for easy reference to full story details
+        const anchor = story.id.replace(".", "-");
+        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");
+}
+export function hasFixPlanProgress(content) {
+    return /^\s*-\s*\[x\]/im.test(content);
+}
+export function parseFixPlan(content) {
+    const items = [];
+    // Match: - [x] Story 1.1: Title  or  - [ ] Story 2.3: Title
+    const pattern = /^\s*-\s*\[([ xX])\]\s*Story\s+(\d+\.\d+):\s*(.+?)$/gm;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        items.push({
+            id: match[2],
+            completed: match[1].toLowerCase() === "x",
+            title: match[3]?.trim(),
+        });
+    }
+    return items;
+}
+/**
+ * Detects completed stories that are no longer in the new BMAD output.
+ * Returns warnings for each orphaned completed story.
+ */
+export function detectOrphanedCompletedStories(existingItems, newStoryIds) {
+    const warnings = [];
+    for (const item of existingItems) {
+        if (item.completed && !newStoryIds.has(item.id)) {
+            const titlePart = item.title ? ` "${item.title}"` : "";
+            warnings.push(`Completed story ${item.id}${titlePart} was removed from BMAD output. Work may be orphaned.`);
+        }
+    }
+    return warnings;
+}
+/**
+ * Detects stories that may have been renumbered by comparing titles.
+ * Returns warnings when a completed story's title appears under a different ID.
+ */
+export function detectRenumberedStories(existingItems, newStories) {
+    const warnings = [];
+    // Build a map of new story titles (lowercased) to IDs
+    const newTitleToId = new Map();
+    for (const story of newStories) {
+        newTitleToId.set(story.title.toLowerCase().trim(), story.id);
+    }
+    // Check each completed story
+    for (const item of existingItems) {
+        if (!item.completed || !item.title)
+            continue;
+        const normalizedTitle = item.title.toLowerCase().trim();
+        const newId = newTitleToId.get(normalizedTitle);
+        // If title exists under a different ID, warn about renumbering
+        if (newId && newId !== item.id) {
+            warnings.push(`Story "${item.title}" appears to have been renumbered from ${item.id} to ${newId}. Completion status was not preserved.`);
+        }
+    }
+    return warnings;
+}
+export function mergeFixPlanProgress(newFixPlan, completedIds) {
+    // Replace [ ] with [x] for completed story IDs
+    return newFixPlan.replace(/^(\s*-\s*)\[ \](\s*Story\s+(\d+\.\d+):)/gm, (match, prefix, suffix, id) => {
+        return completedIds.has(id) ? `${prefix}[x]${suffix}` : match;
+    });
+}

package/dist/transition/index.d.ts

@@ -0,0 +1,9 @@
+export type { ProjectContext, Story, TechStack, FixPlanItem, SpecsChange, TransitionResult, SpecFileType, Priority, SpecFileMetadata, SpecsIndex, } from "./types.js";
+export { parseStories, parseStoriesWithWarnings } from "./story-parsing.js";
+export { generateFixPlan, hasFixPlanProgress, parseFixPlan, mergeFixPlanProgress, } from "./fix-plan.js";
+export { detectTechStack, customizeAgentMd } from "./tech-stack.js";
+export { findArtifactsDir, validateArtifacts } from "./artifacts.js";
+export { extractSection, extractProjectContext, generateProjectContextMd, generatePrompt, } from "./context.js";
+export { generateSpecsChangelog, formatChangelog } from "./specs-changelog.js";
+export { detectSpecFileType, determinePriority, extractDescription, generateSpecsIndex, formatSpecsIndexMd, } from "./specs-index.js";
+export { runTransition } from "./orchestration.js";

package/dist/transition/index.js

@@ -0,0 +1,16 @@
+// Story parsing
+export { parseStories, parseStoriesWithWarnings } from "./story-parsing.js";
+// Fix plan
+export { generateFixPlan, hasFixPlanProgress, parseFixPlan, mergeFixPlanProgress, } from "./fix-plan.js";
+// Tech stack detection
+export { detectTechStack, customizeAgentMd } from "./tech-stack.js";
+// Artifacts
+export { findArtifactsDir, validateArtifacts } from "./artifacts.js";
+// Context
+export { extractSection, extractProjectContext, generateProjectContextMd, generatePrompt, } from "./context.js";
+// Specs changelog
+export { generateSpecsChangelog, formatChangelog } from "./specs-changelog.js";
+// Specs index
+export { detectSpecFileType, determinePriority, extractDescription, generateSpecsIndex, formatSpecsIndexMd, } from "./specs-index.js";
+// Orchestration
+export { runTransition } from "./orchestration.js";

package/dist/transition/orchestration.d.ts

@@ -0,0 +1,2 @@
+import type { TransitionResult } from "./types.js";
+export declare function runTransition(projectDir: string): Promise<TransitionResult>;

package/dist/transition/orchestration.js

@@ -0,0 +1,243 @@
+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 { 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 { detectTechStack, customizeAgentMd } from "./tech-stack.js";
+import { findArtifactsDir, validateArtifacts } from "./artifacts.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) {
+    info("Locating BMAD artifacts...");
+    const artifactsDir = await findArtifactsDir(projectDir);
+    if (!artifactsDir) {
+        throw new Error("No BMAD artifacts found. Run BMAD planning phases first (at minimum: Create PRD, Create Architecture, Create Epics and Stories).");
+    }
+    // Find and parse stories file
+    const files = await readdir(artifactsDir);
+    const storiesPattern = /^(epics[-_]?(and[-_]?)?)?stor(y|ies)([-_]\d+)?\.md$/i;
+    const storiesFile = files.find((f) => storiesPattern.test(f) || /epic/i.test(f));
+    if (!storiesFile) {
+        debug(`Files in artifacts dir: ${files.join(", ")}`);
+        throw new Error(`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");
+    info("Parsing stories...");
+    const { stories, warnings: parseWarnings } = parseStoriesWithWarnings(storiesContent);
+    if (stories.length === 0) {
+        throw new Error("No stories parsed from the epics file. Ensure stories follow the format: ### Story N.M: Title");
+    }
+    // Check existing fix_plan for completed items (smart merge)
+    let completedIds = new Set();
+    let existingItems = [];
+    const fixPlanPath = join(projectDir, ".ralph/@fix_plan.md");
+    try {
+        const existingFixPlan = await readFile(fixPlanPath, "utf-8");
+        existingItems = parseFixPlan(existingFixPlan);
+        completedIds = new Set(existingItems.filter((i) => i.completed).map((i) => i.id));
+        debug(`Found ${completedIds.size} completed stories in existing fix_plan`);
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            debug("No existing fix_plan found, starting fresh");
+        }
+        else {
+            warn(`Could not read existing fix_plan: ${formatError(err)}`);
+        }
+    }
+    // Detect orphaned completed stories (Bug #2)
+    const newStoryIds = new Set(stories.map((s) => s.id));
+    const orphanWarnings = detectOrphanedCompletedStories(existingItems, newStoryIds);
+    for (const w of orphanWarnings) {
+        warn(w);
+    }
+    // Detect renumbered stories (Bug #3)
+    const renumberWarnings = detectRenumberedStories(existingItems, stories);
+    for (const w of renumberWarnings) {
+        warn(w);
+    }
+    // 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);
+    await atomicWriteFile(fixPlanPath, mergedFixPlan);
+    // Track whether progress was preserved for return value
+    const fixPlanPreserved = completedIds.size > 0;
+    // Generate changelog before overwriting specs/
+    const specsDir = join(projectDir, ".ralph/specs");
+    const bmadOutputDir = join(projectDir, "_bmad-output");
+    try {
+        await access(bmadOutputDir);
+        const changes = await generateSpecsChangelog(specsDir, bmadOutputDir);
+        if (changes.length > 0) {
+            const changelog = formatChangelog(changes, new Date().toISOString());
+            await atomicWriteFile(join(projectDir, ".ralph/SPECS_CHANGELOG.md"), changelog);
+            debug(`Generated SPECS_CHANGELOG.md with ${changes.length} changes`);
+        }
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            debug("Skipping SPECS_CHANGELOG.md (no _bmad-output directory)");
+        }
+        else {
+            warn(`Could not generate SPECS_CHANGELOG.md: ${formatError(err)}`);
+        }
+    }
+    // Copy entire _bmad-output/ tree to .ralph/specs/ (preserving structure)
+    let bmadOutputExists = false;
+    try {
+        await access(bmadOutputDir);
+        bmadOutputExists = true;
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            debug("_bmad-output not found, falling back to artifacts directory");
+        }
+        else {
+            warn(`Error checking _bmad-output: ${formatError(err)}`);
+        }
+    }
+    info("Copying specs to .ralph/specs/...");
+    const specsTmpDir = join(projectDir, ".ralph/specs.new");
+    if (bmadOutputExists) {
+        // Atomic copy: write to temp dir, verify, then swap
+        await rm(specsTmpDir, { recursive: true, force: true });
+        await mkdir(specsTmpDir, { recursive: true });
+        await cp(bmadOutputDir, specsTmpDir, { recursive: true, dereference: false });
+        // Verify the copy succeeded before swapping
+        await access(specsTmpDir);
+        await rm(specsDir, { recursive: true, force: true });
+        await rename(specsTmpDir, specsDir);
+        debug("Copied _bmad-output/ to .ralph/specs/ (atomic)");
+    }
+    else {
+        // Fall back to just artifactsDir if _bmad-output root doesn't exist
+        await rm(specsTmpDir, { recursive: true, force: true });
+        await mkdir(specsTmpDir, { recursive: true });
+        for (const file of files) {
+            await cp(join(artifactsDir, file), join(specsTmpDir, file), {
+                recursive: true,
+                dereference: false,
+            });
+        }
+        await access(specsTmpDir);
+        await rm(specsDir, { recursive: true, force: true });
+        await rename(specsTmpDir, specsDir);
+    }
+    // Generate SPECS_INDEX.md for intelligent spec reading
+    info("Generating SPECS_INDEX.md...");
+    try {
+        const specsIndex = await generateSpecsIndex(specsDir);
+        if (specsIndex.totalFiles > 0) {
+            await atomicWriteFile(join(projectDir, ".ralph/SPECS_INDEX.md"), formatSpecsIndexMd(specsIndex));
+            debug(`Generated SPECS_INDEX.md with ${specsIndex.totalFiles} files`);
+        }
+    }
+    catch (err) {
+        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);
+        if (config?.name) {
+            projectName = config.name;
+        }
+    }
+    catch (err) {
+        debug(`Could not read config for project name: ${formatError(err)}`);
+    }
+    // Extract project context for both PROJECT_CONTEXT.md and PROMPT.md
+    info("Generating PROJECT_CONTEXT.md...");
+    let projectContext = null;
+    let truncationWarnings = [];
+    if (artifactContents.size > 0) {
+        const { context, truncated } = extractProjectContext(artifactContents);
+        projectContext = context;
+        truncationWarnings = detectTruncation(truncated);
+        const contextMd = generateProjectContextMd(projectContext, projectName);
+        await atomicWriteFile(join(projectDir, ".ralph/PROJECT_CONTEXT.md"), contextMd);
+        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;
+    try {
+        const existingPrompt = await readFile(join(projectDir, ".ralph/PROMPT.md"), "utf-8");
+        if (existingPrompt.includes("[YOUR PROJECT NAME]")) {
+            prompt = existingPrompt.replace(/\[YOUR PROJECT NAME\]/g, projectName);
+        }
+        else {
+            // Pass context to embed critical specs directly in PROMPT.md
+            prompt = generatePrompt(projectName, projectContext ?? undefined);
+        }
+    }
+    catch (err) {
+        if (isEnoent(err)) {
+            debug("No existing PROMPT.md found, generating from template");
+        }
+        else {
+            warn(`Could not read existing PROMPT.md: ${formatError(err)}`);
+        }
+        prompt = generatePrompt(projectName, projectContext ?? undefined);
+    }
+    await atomicWriteFile(join(projectDir, ".ralph/PROMPT.md"), prompt);
+    // 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");
+            }
+        }
+        catch (err) {
+            warn(`Could not customize @AGENT.md: ${formatError(err)}`);
+        }
+    }
+    // Validate artifacts and collect warnings
+    const artifactWarnings = await validateArtifacts(files, artifactsDir);
+    const warnings = [
+        ...parseWarnings,
+        ...artifactWarnings,
+        ...orphanWarnings,
+        ...renumberWarnings,
+        ...truncationWarnings,
+    ];
+    // Update phase state to 4 (Implementation) - Bug #1
+    const now = new Date().toISOString();
+    const currentState = await readState(projectDir);
+    const newState = {
+        currentPhase: 4,
+        status: "implementing",
+        startedAt: currentState?.startedAt ?? now,
+        lastUpdated: now,
+    };
+    await writeState(projectDir, newState);
+    info("Transition complete: phase 4 (implementing)");
+    return { storiesCount: stories.length, warnings, fixPlanPreserved };
+}

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

@@ -0,0 +1,3 @@
+import type { SpecsChange } from "./types.js";
+export declare function generateSpecsChangelog(oldSpecsDir: string, newSourceDir: string): Promise<SpecsChange[]>;
+export declare function formatChangelog(changes: SpecsChange[], timestamp: string): string;