ralph-prd 1.1.0 → 3.0.0

package/ralph/lib/plan-parser.mjs

@@ -1,5 +1,12 @@
 import { readFileSync } from 'fs';
 
+/**
+ * @typedef {Object} Task
+ * @property {number} index - 0-based index within the phase
+ * @property {string} description - The task description text
+ * @property {string[]} acceptanceCriteria - Subset of criteria relevant to this task (or all if unsplittable)
+ */
+
 /**
  * @typedef {Object} Phase
  * @property {number} index - 0-based index among executable phases
@@ -7,6 +14,7 @@ import { readFileSync } from 'fs';
  * @property {string} body - Raw lines of the section body joined with newlines
  * @property {string[]} acceptanceCriteria - Criterion text strings (checkbox prefix stripped)
  * @property {boolean} hasVerification - True when at least one criterion exists
+ * @property {Task[]} tasks - Individual tasks extracted from "What to build" (at least 1)
  */
 
 /**
@@ -76,14 +84,109 @@ export function parsePlanContent(content) {
       }
     }
 
+    const body = section.lines.join('\n').trimEnd();
+    const tasks = extractTasks(section.lines, acceptanceCriteria);
+
     phases.push({
       index: phases.length,
       title: section.title,
-      body: section.lines.join('\n').trimEnd(),
+      body,
       acceptanceCriteria,
       hasVerification: acceptanceCriteria.length > 0,
+      tasks,
     });
   }
 
   return { phases };
 }
+
+/**
+ * Extract individual tasks from the "What to build" section of a phase.
+ *
+ * Looks for numbered items (1. / 2. / etc.) or top-level bullet items (- / * )
+ * within the "### What to build" section. If the section is a single block of
+ * prose with no list items, the entire phase becomes a single task.
+ *
+ * @param {string[]} lines - All lines of the phase section
+ * @param {string[]} allCriteria - All acceptance criteria for the phase
+ * @returns {Task[]}
+ */
+function extractTasks(lines, allCriteria) {
+  // Find the "What to build" section boundaries
+  let inWhatToBuild = false;
+  const wtbLines = [];
+
+  for (const line of lines) {
+    if (/^### What to build\b/i.test(line)) {
+      inWhatToBuild = true;
+      continue;
+    }
+    if (/^### /.test(line)) {
+      if (inWhatToBuild) break;
+      continue;
+    }
+    if (inWhatToBuild) {
+      wtbLines.push(line);
+    }
+  }
+
+  // Try to split by numbered items (1. / 2. / etc.)
+  const numberedItems = splitByPattern(wtbLines, /^\d+\.\s+/);
+  if (numberedItems.length > 1) {
+    return numberedItems.map((desc, i) => ({
+      index: i,
+      description: desc,
+      acceptanceCriteria: allCriteria, // all criteria visible to each task
+    }));
+  }
+
+  // Try to split by top-level bullet items (- or *)
+  const bulletItems = splitByPattern(wtbLines, /^[-*]\s+/);
+  if (bulletItems.length > 1) {
+    return bulletItems.map((desc, i) => ({
+      index: i,
+      description: desc,
+      acceptanceCriteria: allCriteria,
+    }));
+  }
+
+  // Single block — the whole phase is one task
+  const fullDesc = wtbLines.join('\n').trim();
+  return [{
+    index: 0,
+    description: fullDesc || lines.join('\n').trim(),
+    acceptanceCriteria: allCriteria,
+  }];
+}
+
+/**
+ * Split lines into groups by a leading pattern (numbered items or bullets).
+ * Continuation lines (not matching the pattern) are appended to the current item.
+ *
+ * @param {string[]} lines
+ * @param {RegExp} pattern
+ * @returns {string[]} Array of task descriptions (empty lines trimmed)
+ */
+function splitByPattern(lines, pattern) {
+  const items = [];
+  let current = null;
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      // Blank line — separator between items, or padding
+      if (current !== null) current += '\n';
+      continue;
+    }
+    if (pattern.test(trimmed)) {
+      if (current !== null) items.push(current.trim());
+      current = trimmed;
+    } else if (current !== null) {
+      current += '\n' + trimmed;
+    }
+    // Lines before the first matching item are ignored
+  }
+  if (current !== null) items.push(current.trim());
+
+  return items.filter(Boolean);
+}

package/ralph/lib/prompts/commit.md

@@ -24,6 +24,15 @@ For each repository listed above, output a commit plan using EXACTLY this format
   DESCRIPTION:
   - <bullet: what changed and why — focus on intent, not mechanics>
   - <add one bullet per logical group of changes>
+  DECISIONS:
+  - <bullet: key architectural or library choice you made and WHY>
+  - <include trade-offs considered, alternatives rejected>
+  BLOCKERS:
+  - <bullet: dependency not yet available, workaround applied, TODO left>
+  - <omit this section entirely if there are no blockers>
+  NEXT:
+  - <bullet: what the next task or phase needs to know about this work>
+  - <mention any setup, patterns, or utilities created that should be reused>
   END_COMMIT
 
 Rules:
@@ -31,5 +40,8 @@ Rules:
 - Use paths exactly as shown in the git status output (relative to repo root).
 - COMMIT line: start with "ralph: " then a short imperative verb phrase (≤72 chars total).
 - DESCRIPTION bullets: explain *what* moved or changed and *why*, not line-by-line mechanics.
+- DECISIONS bullets: document choices that future developers (or the next phase) need to understand. Skip if no notable decisions were made.
+- BLOCKERS bullets: flag incomplete work, missing dependencies, or temporary workarounds. Skip if none.
+- NEXT bullets: leave breadcrumbs for whoever works on this codebase next. Skip if nothing notable.
 - If a repository has no files relevant to this phase, output: REPO: <name>\nSKIP
 - Do not output anything outside the structured REPO / END_COMMIT blocks.

package/ralph/lib/prompts/implementation.md

@@ -4,9 +4,9 @@ Your job is to implement exactly the phase described below and nothing more.
 ## Repositories in scope
 
 {{repoLines}}{{writableLines}}
-
+{{recentCommits}}
 ---
-
+{{prdSection}}
 ## Full plan (for context)
 
 {{planContent}}
@@ -23,18 +23,24 @@ Your job is to implement exactly the phase described below and nothing more.
 
 ## Implementation approach
 
-For **backend code** (server logic, API routes, business logic, database layers, services, data models, utilities):
-Follow a strict red → green → refactor cycle, one behaviour at a time:
+### Tracer-bullet principle
+
+Build one thin vertical slice end-to-end before writing the next. A tracer bullet pierces all layers — route → handler → service → database — for a single behaviour, proving the path works before you widen it. Do not build all routes first, then all handlers, then all services. Build one complete behaviour at a time.
+
+### For backend code (server logic, API routes, business logic, database layers, services, data models, utilities)
+
+Apply red → green → refactor within each tracer bullet:
+
+1. **RED** — Write one failing test for the behaviour this slice delivers. Run it to confirm it fails before writing any production code.
+2. **GREEN** — Write the minimum production code across all layers to make that one test pass. Nothing more.
+3. Repeat from step 1 for the next slice of behaviour.
+4. **REFACTOR** — Clean up without changing behaviour. Re-run tests to confirm they still pass.
 
-1. **RED** — Write one failing test for a single behaviour. Run it to confirm it fails before writing any production code.
-2. **GREEN** — Write the minimum production code to make that one test pass. Nothing more.
-3. **REFACTOR** — Clean up without changing behaviour. Re-run tests to confirm they still pass.
-4. Repeat for the next behaviour.
+Do NOT write multiple tests upfront. Do NOT build out a full layer before proving a slice works end-to-end.
 
-Work in tracer-bullet style: one thin slice end-to-end before moving to the next.
-Do NOT write multiple tests upfront. Do NOT write production code before a failing test exists.
+### Frontend code (UI components, CSS, HTML, browser JS, view templates)
 
-**Frontend code** (UI components, CSS, HTML, browser JS, view templates) is exempt — implement it directly without the TDD cycle.
+Exempt from the TDD cycle — implement it directly. Still follow the tracer-bullet principle: one complete UI slice at a time, not all markup then all styles then all scripts.
 
 ---
 

package/ralph/lib/prompts/implementation_closing_commit.md

@@ -1 +1,18 @@
-When you are done with all file changes, commit everything with a clear commit message in the format: "ralph: <short imperative summary>" followed by a blank line and a bullet list describing what changed and why. Then output a brief summary of what you changed.
+When you are done with all file changes, commit everything with a clear commit message using this format:
+
+```
+ralph: <short imperative summary>
+
+- <what changed and why — one bullet per logical group>
+
+Decisions:
+- <key architectural or library choice and WHY — skip if none>
+
+Blockers:
+- <dependency not available, workaround applied, TODO left — skip if none>
+
+Next:
+- <what the next task/phase needs to know — skip if nothing notable>
+```
+
+Then output a brief summary of what you changed.

package/ralph/lib/prompts/repair.md

@@ -14,7 +14,7 @@ Your job is to fix exactly the issues listed in the failure notes and nothing mo
 
 ---
 
-## Full plan (for context)
+{{prdSection}}## Full plan (for context)
 
 {{planContent}}
 

package/ralph/lib/prompts/verification.md

@@ -14,7 +14,7 @@ You are Ralph's verification agent. Your only job is to check whether the implem
 
 ---
 
-## Full plan (for context)
+{{prdSection}}## Full plan (for context)
 
 {{planContent}}
 

package/ralph/lib/state.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'fs';
+import { readFileSync, writeFileSync, existsSync, unlinkSync, renameSync } from 'fs';
 import { resolve, dirname, basename } from 'path';
 
 /**
@@ -7,6 +7,7 @@ import { resolve, dirname, basename } from 'path';
  * @property {'implementation'|'verification'|'commit'} step - last completed step
  * @property {string} implementationOutput - result text from the implementation session
  * @property {number} taskNum           - next taskNum for the phase
+ * @property {number} [completedTaskIndex] - 0-based index of the last fully completed task within the phase (-1 = none)
  */
 
 /**
@@ -52,7 +53,10 @@ export function loadState(planPath) {
  * @param {RalphState} state
  */
 export function saveState(planPath, state) {
-  writeFileSync(stateFilePath(planPath), JSON.stringify(state, null, 2) + '\n', 'utf8');
+  const file = stateFilePath(planPath);
+  const tmp = file + '.tmp';
+  writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', 'utf8');
+  renameSync(tmp, file);
 }
 
 /**

package/ralph/lib/transport.mjs

@@ -19,6 +19,7 @@
  */
 
 import { spawn, spawnSync } from 'child_process';
+import { relative } from 'path';
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -70,9 +71,8 @@ function resolveCLI() {
 /** Strip the absolute repo prefix so paths are readable. */
 function shortPath(p) {
   if (!p) return '';
-  // Try to trim everything up to and including the repo root segment
-  const idx = p.indexOf('/mazadLive-backend/');
-  return idx !== -1 ? p.slice(idx + '/mazadLive-backend/'.length) : p;
+  const rel = relative(process.cwd(), p);
+  return rel.startsWith('..') ? p : rel;
 }
 
 /**

package/ralph/lib/verifier.mjs

@@ -105,13 +105,17 @@ export function gatherRepoState(repos) {
  * @param {import('./config.mjs').Repo[]} opts.repos
  * @param {string} opts.implementationOutput - Full text from the implementation session
  * @param {string} opts.safetyHeader
+ * @param {string} [opts.prdContent=''] - Raw PRD markdown for business context
  * @returns {string}
  */
-function buildVerificationPrompt({ planContent, phase, repos, implementationOutput, safetyHeader }) {
+function buildVerificationPrompt({ planContent, phase, repos, implementationOutput, safetyHeader, prdContent = '' }) {
   const repoState = gatherRepoState(repos);
   const criteriaList = phase.acceptanceCriteria
     .map((c, i) => `  ${i + 1}. ${c}`)
     .join('\n');
+  const prdSection = prdContent
+    ? `## Source PRD (business context)\n\n${prdContent.trim()}\n\n---\n\n`
+    : '';
 
   return (
     safetyHeader +
@@ -119,6 +123,7 @@ function buildVerificationPrompt({ planContent, phase, repos, implementationOutp
       phaseTitle: phase.title,
       phaseBody: phase.body.trim(),
       criteriaList,
+      prdSection,
       planContent: planContent.trim(),
       repoState,
       implementationOutput: implementationOutput.trim(),
@@ -136,9 +141,10 @@ function buildVerificationPrompt({ planContent, phase, repos, implementationOutp
  * @param {import('./config.mjs').Repo[]} opts.repos
  * @param {string} opts.safetyHeader
  * @param {string} opts.failureNotes
+ * @param {string} [opts.prdContent=''] - Raw PRD markdown for business context
  * @returns {string}
  */
-function buildRepairPrompt({ planContent, phase, repos, safetyHeader, failureNotes }) {
+function buildRepairPrompt({ planContent, phase, repos, safetyHeader, failureNotes, prdContent = '' }) {
   const primaryRepos = repos.filter(r => !r.writableOnly);
   const writableDirs = repos.filter(r => r.writableOnly);
 
@@ -149,6 +155,9 @@ function buildRepairPrompt({ planContent, phase, repos, safetyHeader, failureNot
     ? '\nAdditional writable directories:\n' +
       writableDirs.map(r => `  - ${r.path}`).join('\n')
     : '';
+  const prdSection = prdContent
+    ? `## Source PRD (business context)\n\n${prdContent.trim()}\n\n---\n\n`
+    : '';
 
   return (
     safetyHeader +
@@ -156,6 +165,7 @@ function buildRepairPrompt({ planContent, phase, repos, safetyHeader, failureNot
       failureNotes: failureNotes.trim(),
       repoLines,
       writableLines,
+      prdSection,
       planContent: planContent.trim(),
       phaseTitle: phase.title,
       phaseBody: phase.body.trim(),
@@ -277,6 +287,7 @@ async function runSession({ stepName, phaseName, prompt, logWriter, phaseNum, ta
  * @param {number}   opts.stepIndex
  * @param {Function} opts.send
  * @param {number}  [opts.maxRepairs=3]  - Maximum repair attempts before giving up
+ * @param {string}  [opts.prdContent=''] - Raw PRD markdown for business context
  * @returns {Promise<{ nextTaskNum: number }>}
  * @throws {VerificationError} when all repair attempts are exhausted
  */
@@ -291,6 +302,7 @@ export async function runVerificationLoop({
   startTaskNum,
   send,
   maxRepairs = 3,
+  prdContent = '',
 }) {
   let taskNum = startTaskNum;
   let lastFailureNotes = '';
@@ -298,7 +310,7 @@ export async function runVerificationLoop({
   // ── Initial verification ───────────────────────────────────────────────────
 
   const initialPrompt = buildVerificationPrompt({
-    planContent, phase, repos, implementationOutput, safetyHeader,
+    planContent, phase, repos, implementationOutput, safetyHeader, prdContent,
   });
 
   const initialText = await runSession({
@@ -332,7 +344,7 @@ export async function runVerificationLoop({
   for (let attempt = 1; attempt <= maxRepairs; attempt++) {
     // Repair
     const repairPrompt = buildRepairPrompt({
-      planContent, phase, repos, safetyHeader,
+      planContent, phase, repos, safetyHeader, prdContent,
       failureNotes: lastFailureNotes || 'The verifier did not provide specific failure notes.',
     });
 
@@ -350,7 +362,7 @@ export async function runVerificationLoop({
     const reVerifyPrompt = buildVerificationPrompt({
       planContent, phase, repos,
       implementationOutput: `(repair attempt ${attempt} completed — see repair-${attempt} log)`,
-      safetyHeader,
+      safetyHeader, prdContent,
     });
 
     const reVerifyText = await runSession({