@towles/tool 0.0.49 → 0.0.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.49",
+  "version": "0.0.50",
   "description": "CLI tool with autonomous task runner (ralph), observability, and quality-of-life commands for daily development.",
   "keywords": [
     "autonomic",

package/src/commands/ralph/plan/add.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { Flags } from "@oclif/core";
 import consola from "consola";
@@ -44,16 +44,10 @@ export default class PlanAdd extends BaseCommand {
     const ralphSettings = this.settings.settings.ralphSettings;
     const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
 
-    const filePath = resolve(flags.file);
+    const planFilePath = resolve(flags.file);
 
-    if (!existsSync(filePath)) {
-      this.error(`Plan file not found: ${filePath}`);
-    }
-
-    const description = readFileSync(filePath, "utf-8").trim();
-
-    if (!description || description.length < 3) {
-      this.error("Plan file is empty or too short (min 3 chars)");
+    if (!existsSync(planFilePath)) {
+      this.error(`Plan file not found: ${planFilePath}`);
     }
 
     let state = loadState(stateFile);
@@ -62,13 +56,11 @@ export default class PlanAdd extends BaseCommand {
       state = createInitialState();
     }
 
-    const newPlan = addPlanToState(state, description);
+    const newPlan = addPlanToState(state, planFilePath);
     saveState(state, stateFile);
 
-    // Show truncated description for display
-    const displayDesc = description.length > 80 ? `${description.slice(0, 80)}...` : description;
-    consola.log(colors.green(`✓ Added plan #${newPlan.id} from ${flags.file}`));
-    consola.log(colors.dim(`  ${displayDesc.split("\n")[0]}`));
+    consola.log(colors.green(`✓ Added plan #${newPlan.id}`));
+    consola.log(colors.dim(`  File: ${planFilePath}`));
     consola.log(colors.dim(`State saved to: ${stateFile}`));
     consola.log(colors.dim(`Total plans: ${state.plans.length}`));
   }

package/src/commands/ralph/plan/done.ts

@@ -70,7 +70,7 @@ export default class PlanDone extends BaseCommand {
     plan.completedAt = new Date().toISOString();
     saveState(state, stateFile);
 
-    consola.log(colors.green(`✓ Marked plan #${planId} as done: ${plan.description}`));
+    consola.log(colors.green(`✓ Marked plan #${planId} as done: ${plan.planFilePath}`));
 
     const remaining = state.plans.filter((p) => p.status !== "done").length;
     if (remaining === 0) {

package/src/commands/ralph/plan/list.ts

@@ -75,14 +75,15 @@ export default class PlanList extends BaseCommand {
 
     // Show ready plans first (these are actionable)
     // Reserve ~10 chars for "  ○ #XX " prefix
-    const descWidth = Math.max(40, termWidth - 12);
+    const pathWidth = Math.max(40, termWidth - 12);
 
     if (ready.length > 0) {
       for (const plan of ready) {
         const icon = pc.dim("○");
         const id = pc.cyan(`#${plan.id}`);
-        const desc = truncate(plan.description, descWidth);
-        this.log(`  ${icon} ${id} ${desc}`);
+        const filePath = truncate(plan.planFilePath, pathWidth);
+        const errorSuffix = plan.error ? pc.red(` ⚠ ${truncate(plan.error, 30)}`) : "";
+        this.log(`  ${icon} ${id} ${filePath}${errorSuffix}`);
       }
     }
 
@@ -90,8 +91,8 @@ export default class PlanList extends BaseCommand {
     if (done.length > 0) {
       this.log(pc.dim(`  ─── ${done.length} completed ───`));
       for (const plan of done) {
-        const desc = truncate(plan.description, descWidth - 5);
-        this.log(pc.dim(`  ✓ #${plan.id} ${desc}`));
+        const filePath = truncate(plan.planFilePath, pathWidth - 5);
+        this.log(pc.dim(`  ✓ #${plan.id} ${filePath}`));
       }
     }
     this.log();

package/src/commands/ralph/plan/remove.ts

@@ -65,7 +65,7 @@ export default class PlanRemove extends BaseCommand {
     state.plans.splice(planIndex, 1);
     saveState(state, stateFile);
 
-    consola.log(colors.green(`✓ Removed plan #${planId}: ${removedPlan.description}`));
+    consola.log(colors.green(`✓ Removed plan #${planId}: ${removedPlan.planFilePath}`));
     consola.log(colors.dim(`Remaining plans: ${state.plans.length}`));
   }
 }

package/src/commands/ralph/run.test.ts

@@ -70,14 +70,14 @@ describe("ralph-loop", () => {
   describe("saveState and loadState", () => {
     it("should save and load state correctly", () => {
       const state = createInitialState();
-      addPlanToState(state, "test plan");
+      addPlanToState(state, "/tmp/test-plan.md");
 
       saveState(state, testStateFile);
       const loaded = loadState(testStateFile);
 
       expect(loaded).not.toBeNull();
       expect(loaded?.plans).toHaveLength(1);
-      expect(loaded?.plans[0].description).toBe("test plan");
+      expect(loaded?.plans[0].planFilePath).toBe("/tmp/test-plan.md");
     });
 
     it("should return null for non-existent file", () => {
@@ -95,28 +95,45 @@ describe("ralph-loop", () => {
   describe("buildIterationPrompt", () => {
     const testPlan: RalphPlan = {
       id: 1,
-      description: "First plan",
+      planFilePath: "/tmp/first-plan.md",
       status: "ready",
       addedAt: new Date().toISOString(),
     };
+    const testPlanContent = "First plan content";
 
     it("should include completion marker", () => {
-      const prompt = buildIterationPrompt({ completionMarker: "RALPH_DONE", plan: testPlan });
+      const prompt = buildIterationPrompt({
+        completionMarker: "RALPH_DONE",
+        plan: testPlan,
+        planContent: testPlanContent,
+      });
       expect(prompt).toContain("RALPH_DONE");
     });
 
-    it("should include plan id and description", () => {
-      const prompt = buildIterationPrompt({ completionMarker: "RALPH_DONE", plan: testPlan });
-      expect(prompt).toContain("#1: First plan");
+    it("should include plan content", () => {
+      const prompt = buildIterationPrompt({
+        completionMarker: "RALPH_DONE",
+        plan: testPlan,
+        planContent: testPlanContent,
+      });
+      expect(prompt).toContain("First plan content");
     });
 
     it("should include mark done command with plan id", () => {
-      const prompt = buildIterationPrompt({ completionMarker: "RALPH_DONE", plan: testPlan });
+      const prompt = buildIterationPrompt({
+        completionMarker: "RALPH_DONE",
+        plan: testPlan,
+        planContent: testPlanContent,
+      });
       expect(prompt).toContain("tt ralph plan done 1");
     });
 
     it("should include custom completion marker", () => {
-      const prompt = buildIterationPrompt({ completionMarker: "CUSTOM_MARKER", plan: testPlan });
+      const prompt = buildIterationPrompt({
+        completionMarker: "CUSTOM_MARKER",
+        plan: testPlan,
+        planContent: testPlanContent,
+      });
       expect(prompt).toContain("CUSTOM_MARKER");
     });
   });
@@ -263,10 +280,10 @@ describe("ralph-loop", () => {
   describe("addPlanToState", () => {
     it("should add plan with correct structure", () => {
       const state = createInitialState();
-      const plan = addPlanToState(state, "implement feature");
+      const plan = addPlanToState(state, "/tmp/implement-feature.md");
 
       expect(plan.id).toBe(1);
-      expect(plan.description).toBe("implement feature");
+      expect(plan.planFilePath).toBe("/tmp/implement-feature.md");
       expect(plan.status).toBe("ready");
       expect(plan.addedAt).toMatch(/^\d{4}-\d{2}-\d{2}T/);
       expect(plan.completedAt).toBeUndefined();
@@ -275,9 +292,9 @@ describe("ralph-loop", () => {
     it("should increment plan IDs", () => {
       const state = createInitialState();
 
-      const plan1 = addPlanToState(state, "plan 1");
-      const plan2 = addPlanToState(state, "plan 2");
-      const plan3 = addPlanToState(state, "plan 3");
+      const plan1 = addPlanToState(state, "/tmp/plan-1.md");
+      const plan2 = addPlanToState(state, "/tmp/plan-2.md");
+      const plan3 = addPlanToState(state, "/tmp/plan-3.md");
 
       expect(plan1.id).toBe(1);
       expect(plan2.id).toBe(2);
@@ -291,12 +308,12 @@ describe("ralph-loop", () => {
       // Simulate deleted plan by adding with gap
       state.plans.push({
         id: 5,
-        description: "existing plan",
+        planFilePath: "/tmp/existing-plan.md",
         status: "done",
         addedAt: new Date().toISOString(),
       });
 
-      const newPlan = addPlanToState(state, "new plan");
+      const newPlan = addPlanToState(state, "/tmp/new-plan.md");
       expect(newPlan.id).toBe(6);
     });
   });
@@ -310,8 +327,8 @@ describe("ralph-loop", () => {
 
     it("should include summary counts", () => {
       const plans: RalphPlan[] = [
-        { id: 1, description: "plan 1", status: "done", addedAt: "" },
-        { id: 2, description: "plan 2", status: "ready", addedAt: "" },
+        { id: 1, planFilePath: "/tmp/plan-1.md", status: "done", addedAt: "" },
+        { id: 2, planFilePath: "/tmp/plan-2.md", status: "ready", addedAt: "" },
       ];
 
       const formatted = formatPlansAsMarkdown(plans);
@@ -323,32 +340,32 @@ describe("ralph-loop", () => {
 
     it("should format done plans with checked boxes", () => {
       const plans: RalphPlan[] = [
-        { id: 1, description: "completed plan", status: "done", addedAt: "" },
+        { id: 1, planFilePath: "/tmp/completed-plan.md", status: "done", addedAt: "" },
       ];
 
       const formatted = formatPlansAsMarkdown(plans);
 
       expect(formatted).toContain("## Done");
-      expect(formatted).toContain("- [x] **#1** completed plan");
+      expect(formatted).toContain("- [x] **#1** /tmp/completed-plan.md");
       expect(formatted).toContain("`✓ done`");
     });
 
     it("should format ready plans with unchecked boxes", () => {
       const plans: RalphPlan[] = [
-        { id: 2, description: "ready plan", status: "ready", addedAt: "" },
+        { id: 2, planFilePath: "/tmp/ready-plan.md", status: "ready", addedAt: "" },
       ];
 
       const formatted = formatPlansAsMarkdown(plans);
 
       expect(formatted).toContain("## Ready");
-      expect(formatted).toContain("- [ ] **#2** ready plan");
+      expect(formatted).toContain("- [ ] **#2** /tmp/ready-plan.md");
       expect(formatted).toContain("`○ ready`");
     });
 
     it("should group plans by status section", () => {
       const plans: RalphPlan[] = [
-        { id: 1, description: "done plan", status: "done", addedAt: "" },
-        { id: 2, description: "ready plan", status: "ready", addedAt: "" },
+        { id: 1, planFilePath: "/tmp/done-plan.md", status: "done", addedAt: "" },
+        { id: 2, planFilePath: "/tmp/ready-plan.md", status: "ready", addedAt: "" },
       ];
 
       const formatted = formatPlansAsMarkdown(plans);
@@ -361,7 +378,7 @@ describe("ralph-loop", () => {
   describe("formatPlanAsMarkdown", () => {
     it("should include plan header and summary", () => {
       const state = createInitialState();
-      addPlanToState(state, "plan 1");
+      addPlanToState(state, "/tmp/plan-1.md");
 
       const formatted = formatPlanAsMarkdown(state.plans, state);
 
@@ -373,18 +390,18 @@ describe("ralph-loop", () => {
 
     it("should include plans section", () => {
       const state = createInitialState();
-      addPlanToState(state, "implement feature");
+      addPlanToState(state, "/tmp/implement-feature.md");
 
       const formatted = formatPlanAsMarkdown(state.plans, state);
 
       expect(formatted).toContain("## Plans");
-      expect(formatted).toContain("**#1** implement feature");
+      expect(formatted).toContain("**#1** /tmp/implement-feature.md");
     });
 
     it("should include mermaid graph section", () => {
       const state = createInitialState();
-      addPlanToState(state, "plan 1");
-      addPlanToState(state, "plan 2");
+      addPlanToState(state, "/tmp/plan-1.md");
+      addPlanToState(state, "/tmp/plan-2.md");
 
       const formatted = formatPlanAsMarkdown(state.plans, state);
 
@@ -397,28 +414,25 @@ describe("ralph-loop", () => {
 
     it("should format done plans correctly in mermaid", () => {
       const state = createInitialState();
-      const plan = addPlanToState(state, "done plan");
+      const plan = addPlanToState(state, "/tmp/done-plan.md");
       plan.status = "done";
 
       const formatted = formatPlanAsMarkdown(state.plans, state);
 
-      expect(formatted).toContain('P1["#1: done plan"]:::done');
+      expect(formatted).toContain('P1["#1: done-plan.md"]:::done');
     });
 
-    it("should truncate long descriptions in mermaid", () => {
+    it("should truncate long filenames in mermaid", () => {
       const state = createInitialState();
-      addPlanToState(
-        state,
-        "This is a very long plan description that should be truncated for the mermaid graph",
-      );
+      addPlanToState(state, "/tmp/this-is-a-very-long-plan-filename-that-should-be-truncated.md");
 
       const formatted = formatPlanAsMarkdown(state.plans, state);
 
-      // Mermaid section should have truncated description
-      expect(formatted).toContain('P1["#1: This is a very long plan de..."]');
-      // But the Plans section should have full description
+      // Mermaid section should have truncated filename
+      expect(formatted).toContain('P1["#1: this-is-a-very-long-plan-fi..."]');
+      // But the Plans section should have full path
       expect(formatted).toContain(
-        "**#1** This is a very long plan description that should be truncated for the mermaid graph",
+        "**#1** /tmp/this-is-a-very-long-plan-filename-that-should-be-truncated.md",
       );
     });
   });
@@ -426,7 +440,7 @@ describe("ralph-loop", () => {
   describe("formatPlanAsJson", () => {
     it("should return valid JSON", () => {
       const state = createInitialState();
-      addPlanToState(state, "plan 1");
+      addPlanToState(state, "/tmp/plan-1.md");
 
       const json = formatPlanAsJson(state.plans, state);
       const parsed = JSON.parse(json);
@@ -437,9 +451,9 @@ describe("ralph-loop", () => {
 
     it("should include summary counts", () => {
       const state = createInitialState();
-      const plan1 = addPlanToState(state, "done plan");
+      const plan1 = addPlanToState(state, "/tmp/done-plan.md");
       plan1.status = "done";
-      addPlanToState(state, "ready plan");
+      addPlanToState(state, "/tmp/ready-plan.md");
 
       const json = formatPlanAsJson(state.plans, state);
       const parsed = JSON.parse(json);
@@ -451,7 +465,7 @@ describe("ralph-loop", () => {
 
     it("should include all plan fields", () => {
       const state = createInitialState();
-      const plan = addPlanToState(state, "test plan");
+      const plan = addPlanToState(state, "/tmp/test-plan.md");
       plan.status = "done";
       plan.completedAt = "2026-01-10T12:00:00Z";
 
@@ -459,7 +473,7 @@ describe("ralph-loop", () => {
       const parsed = JSON.parse(json);
 
       expect(parsed.plans[0].id).toBe(1);
-      expect(parsed.plans[0].description).toBe("test plan");
+      expect(parsed.plans[0].planFilePath).toBe("/tmp/test-plan.md");
       expect(parsed.plans[0].status).toBe("done");
       expect(parsed.plans[0].addedAt).toBeDefined();
       expect(parsed.plans[0].completedAt).toBe("2026-01-10T12:00:00Z");
@@ -469,8 +483,8 @@ describe("ralph-loop", () => {
   describe("markDone functionality", () => {
     it("should mark plan as done and add completedAt", () => {
       const state = createInitialState();
-      addPlanToState(state, "plan 1");
-      addPlanToState(state, "plan 2");
+      addPlanToState(state, "/tmp/plan-1.md");
+      addPlanToState(state, "/tmp/plan-2.md");
 
       // Simulate marking plan 1 as done
       const plan = state.plans.find((t) => t.id === 1);
@@ -486,18 +500,18 @@ describe("ralph-loop", () => {
 
     it("should find plan by ID", () => {
       const state = createInitialState();
-      addPlanToState(state, "plan 1");
-      addPlanToState(state, "plan 2");
-      addPlanToState(state, "plan 3");
+      addPlanToState(state, "/tmp/plan-1.md");
+      addPlanToState(state, "/tmp/plan-2.md");
+      addPlanToState(state, "/tmp/plan-3.md");
 
       const plan = state.plans.find((p) => p.id === 2);
       expect(plan).toBeDefined();
-      expect(plan?.description).toBe("plan 2");
+      expect(plan?.planFilePath).toBe("/tmp/plan-2.md");
     });
 
     it("should return undefined for non-existent plan ID", () => {
       const state = createInitialState();
-      addPlanToState(state, "plan 1");
+      addPlanToState(state, "/tmp/plan-1.md");
 
       const plan = state.plans.find((t) => t.id === 99);
       expect(plan).toBeUndefined();
@@ -505,7 +519,7 @@ describe("ralph-loop", () => {
 
     it("should persist marked-done plan to file", () => {
       const state = createInitialState();
-      addPlanToState(state, "plan 1");
+      addPlanToState(state, "/tmp/plan-1.md");
 
       const plan = state.plans.find((t) => t.id === 1)!;
       plan.status = "done";

package/src/commands/ralph/run.ts

@@ -14,6 +14,7 @@ import {
   appendHistory,
   resolveRalphPath,
   getRalphPaths,
+  readPlanContent,
 } from "../../lib/ralph/state.js";
 import {
   buildIterationPrompt,
@@ -151,12 +152,19 @@ export default class Run extends BaseCommand {
       consola.log(`  Remaining plans: ${remainingPlans.length}`);
 
       consola.log(colors.cyan("\nCurrent plan:"));
-      consola.log(`  #${currentPlan.id}: ${currentPlan.description}`);
+      consola.log(`  #${currentPlan.id}: ${currentPlan.planFilePath}`);
+
+      // Read plan content
+      const planContent = readPlanContent(currentPlan, state, stateFile);
+      if (!planContent) {
+        this.error(`Cannot read plan file: ${currentPlan.planFilePath}`);
+      }
 
       // Show prompt preview
       const prompt = buildIterationPrompt({
         completionMarker: flags.completionMarker,
         plan: currentPlan,
+        planContent,
         skipCommit: !flags.autoCommit,
       });
       consola.log(colors.dim("─".repeat(60)));
@@ -239,9 +247,19 @@ export default class Run extends BaseCommand {
         logStream.write(`\n✅ All plans completed after ${iteration} iteration(s)\n`);
         break;
       }
+
+      // Read plan content
+      const planContent = readPlanContent(plan, state, stateFile);
+      if (!planContent) {
+        consola.log(colors.yellow(`⚠ Skipping plan #${plan.id}: cannot read file`));
+        logStream.write(`⚠ Skipping plan #${plan.id}: cannot read file\n`);
+        continue;
+      }
+
       const prompt = buildIterationPrompt({
         completionMarker: flags.completionMarker,
         plan: plan,
+        planContent,
         skipCommit: !flags.autoCommit,
       });
 

package/src/lib/ralph/formatter.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from "node:child_process";
+import * as path from "node:path";
 import type { RalphPlan, PlanStatus, RalphState } from "./state.js";
 
 // ============================================================================
@@ -61,7 +62,8 @@ export function formatPlansAsMarkdown(plans: RalphPlan[]): string {
   if (ready.length > 0) {
     lines.push("## Ready", "");
     for (const p of ready) {
-      lines.push(`- [ ] **#${p.id}** ${p.description} ${statusBadge(p.status)}`);
+      const errorSuffix = p.error ? ` ⚠️ ${p.error}` : "";
+      lines.push(`- [ ] **#${p.id}** ${p.planFilePath} ${statusBadge(p.status)}${errorSuffix}`);
     }
     lines.push("");
   }
@@ -69,7 +71,7 @@ export function formatPlansAsMarkdown(plans: RalphPlan[]): string {
   if (done.length > 0) {
     lines.push("## Done", "");
     for (const p of done) {
-      lines.push(`- [x] **#${p.id}** ${p.description} ${statusBadge(p.status)}`);
+      lines.push(`- [x] **#${p.id}** ${p.planFilePath} ${statusBadge(p.status)}`);
     }
     lines.push("");
   }
@@ -98,7 +100,8 @@ export function formatPlanAsMarkdown(plans: RalphPlan[], state: RalphState): str
   for (const p of plans) {
     const checkbox = p.status === "done" ? "[x]" : "[ ]";
     const status = p.status === "done" ? "`done`" : "`ready`";
-    lines.push(`- ${checkbox} **#${p.id}** ${p.description} ${status}`);
+    const errorSuffix = p.error ? ` ⚠️ ${p.error}` : "";
+    lines.push(`- ${checkbox} **#${p.id}** ${p.planFilePath} ${status}${errorSuffix}`);
   }
   lines.push("");
 
@@ -109,16 +112,16 @@ export function formatPlanAsMarkdown(plans: RalphPlan[], state: RalphState): str
   lines.push(`    subgraph Progress["Plans: ${done}/${plans.length} done"]`);
 
   for (const p of plans) {
-    const shortDesc =
-      p.description.length > 30 ? p.description.slice(0, 27) + "..." : p.description;
-    // Escape quotes in descriptions
-    const safeDesc = shortDesc.replace(/"/g, "'");
+    const filename = path.basename(p.planFilePath);
+    const shortName = filename.length > 30 ? filename.slice(0, 27) + "..." : filename;
+    // Escape quotes in filenames
+    const safeName = shortName.replace(/"/g, "'");
     const nodeId = `P${p.id}`;
 
     if (p.status === "done") {
-      lines.push(`        ${nodeId}["#${p.id}: ${safeDesc}"]:::done`);
+      lines.push(`        ${nodeId}["#${p.id}: ${safeName}"]:::done`);
     } else {
-      lines.push(`        ${nodeId}["#${p.id}: ${safeDesc}"]:::ready`);
+      lines.push(`        ${nodeId}["#${p.id}: ${safeName}"]:::ready`);
     }
   }
 
@@ -145,10 +148,11 @@ export function formatPlanAsJson(plans: RalphPlan[], state: RalphState): string
       },
       plans: plans.map((p) => ({
         id: p.id,
-        description: p.description,
+        planFilePath: p.planFilePath,
         status: p.status,
         addedAt: p.addedAt,
         completedAt: p.completedAt,
+        error: p.error,
       })),
     },
     null,
@@ -201,19 +205,21 @@ export function extractOutputSummary(output: string, maxLength: number = 2000):
 export interface BuildPromptOptions {
   completionMarker: string;
   plan: RalphPlan;
+  planContent: string;
   skipCommit?: boolean;
 }
 
 export function buildIterationPrompt({
   completionMarker,
   plan,
+  planContent,
   skipCommit = false,
 }: BuildPromptOptions): string {
   let step = 1;
 
   const prompt = `
 <plan>
-#${plan.id}: ${plan.description}
+${planContent}
 </plan>
 
 <instructions>

package/src/lib/ralph/state.ts

@@ -67,10 +67,11 @@ const PlanStatusSchema = z.enum(["ready", "done", "blocked", "cancelled"]);
 
 const RalphPlanSchema = z.object({
   id: z.number(),
-  description: z.string(),
+  planFilePath: z.string(),
   status: PlanStatusSchema,
   addedAt: z.string(),
   completedAt: z.string().optional(),
+  error: z.string().optional(),
 });
 
 const RalphStateSchema = z.object({
@@ -151,12 +152,12 @@ export function loadState(stateFile: string): RalphState | null {
   }
 }
 
-export function addPlanToState(state: RalphState, description: string): RalphPlan {
+export function addPlanToState(state: RalphState, planFilePath: string): RalphPlan {
   const nextId = state.plans.length > 0 ? Math.max(...state.plans.map((p) => p.id)) + 1 : 1;
 
   const newPlan: RalphPlan = {
     id: nextId,
-    description,
+    planFilePath,
     status: "ready",
     addedAt: new Date().toISOString(),
   };
@@ -164,3 +165,35 @@ export function addPlanToState(state: RalphState, description: string): RalphPla
   state.plans.push(newPlan);
   return newPlan;
 }
+
+/**
+ * Read plan content from file. Updates plan error field and logs warning if file missing.
+ * @returns File content on success, null if file missing/error
+ */
+export function readPlanContent(
+  plan: RalphPlan,
+  state: RalphState,
+  stateFile: string,
+): string | null {
+  try {
+    if (!fs.existsSync(plan.planFilePath)) {
+      const errorMsg = `Plan file not found: ${plan.planFilePath}`;
+      console.warn(pc.yellow(`Warning: ${errorMsg}`));
+      plan.error = errorMsg;
+      saveState(state, stateFile);
+      return null;
+    }
+    // Clear any previous error
+    if (plan.error) {
+      plan.error = undefined;
+      saveState(state, stateFile);
+    }
+    return fs.readFileSync(plan.planFilePath, "utf-8").trim();
+  } catch (err) {
+    const errorMsg = `Failed to read plan file: ${err}`;
+    console.warn(pc.yellow(`Warning: ${errorMsg}`));
+    plan.error = errorMsg;
+    saveState(state, stateFile);
+    return null;
+  }
+}