ralphflow 0.5.1 → 0.5.3

package/dist/{chunk-DOC64TD6.js → chunk-CA4XP6KI.js}

@@ -4,7 +4,7 @@ import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { stringify as stringifyYaml } from "yaml";
 var __dirname = dirname(fileURLToPath(import.meta.url));
-var BUILT_IN_TEMPLATES = ["code-implementation", "research"];
+var BUILT_IN_TEMPLATES = ["code-implementation", "research", "tdd-implementation", "systematic-debugging", "design-review", "code-review"];
 function resolveTemplatePath(templateName) {
   const candidates = [
     join(__dirname, "..", "templates", templateName),

package/dist/ralphflow.js

@@ -12,11 +12,11 @@ import {
   resolveFlowDir,
   resolveLoop,
   showStatus
-} from "./chunk-DOC64TD6.js";
+} from "./chunk-CA4XP6KI.js";
 
 // src/cli/index.ts
-import { Command as Command7 } from "commander";
-import chalk8 from "chalk";
+import { Command as Command8 } from "commander";
+import chalk9 from "chalk";
 import { exec } from "child_process";
 
 // src/cli/init.ts
@@ -29,9 +29,9 @@ import { join } from "path";
 import { createInterface } from "readline";
 import chalk from "chalk";
 function ask(rl, question) {
-  return new Promise((resolve2) => {
+  return new Promise((resolve3) => {
     rl.question(chalk.cyan("? ") + question + " ", (answer) => {
-      resolve2(answer.trim());
+      resolve3(answer.trim());
     });
   });
 }
@@ -100,7 +100,7 @@ function listFlows(ralphFlowDir) {
 }
 
 // src/cli/init.ts
-var initCommand = new Command("init").description("Initialize a new RalphFlow flow").option("-t, --template <name>", "Template to use (code-implementation, research)").option("-n, --name <name>", "Custom name for the flow").action(async (opts) => {
+var initCommand = new Command("init").description("Initialize a new RalphFlow flow").option("-t, --template <name>", "Template to use (code-implementation, research, tdd-implementation, systematic-debugging, design-review, code-review)").option("-n, --name <name>", "Custom name for the flow").action(async (opts) => {
   try {
     await initProject(process.cwd(), { template: opts.template, name: opts.name });
   } catch (err) {
@@ -136,7 +136,7 @@ async function spawnClaude(options) {
   if (model) {
     args.unshift("--model", model);
   }
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     const child = spawn("claude", args, {
       cwd,
       stdio: "inherit",
@@ -146,7 +146,7 @@ async function spawnClaude(options) {
       reject(new Error(`Failed to spawn claude: ${err.message}`));
     });
     child.on("close", (code, signal) => {
-      resolve2({
+      resolve3({
         output: "",
         exitCode: code,
         signal
@@ -231,6 +231,48 @@ function checkTrackerAllChecked(flowDir, loop) {
   const unchecked = (content.match(/- \[ \]/g) || []).length;
   return checked > 0 && unchecked === 0;
 }
+function hasNewItemsInDataFile(flowDir, loop, config) {
+  if (!loop.entities || loop.entities.length === 0) return false;
+  const entityName = loop.entities[0];
+  const entity = config.entities?.[entityName];
+  if (!entity) return false;
+  const dataFilePath = join2(flowDir, entity.data_file);
+  if (!existsSync2(dataFilePath)) return false;
+  const trackerPath = join2(flowDir, loop.tracker);
+  if (!existsSync2(trackerPath)) return false;
+  const dataContent = readFileSync(dataFilePath, "utf-8");
+  const trackerContent = readFileSync(trackerPath, "utf-8");
+  const prefix = entity.prefix;
+  const itemRegex = new RegExp(`^## (${prefix}-\\d+):`, "gm");
+  const dataFileIds = [...dataContent.matchAll(itemRegex)].map((m) => m[1]);
+  if (dataFileIds.length === 0) return false;
+  const trackerIdRegex = new RegExp(`\\[[ x]\\]\\s*(${prefix}-\\d+)`, "gi");
+  const trackerIds = [...trackerContent.matchAll(trackerIdRegex)].map((m) => m[1]);
+  return dataFileIds.some((id) => !trackerIds.includes(id));
+}
+function stripStaleCompletion(flowDir, loop, config) {
+  if (!hasNewItemsInDataFile(flowDir, loop, config)) return false;
+  const trackerPath = join2(flowDir, loop.tracker);
+  if (!existsSync2(trackerPath)) return false;
+  let content = readFileSync(trackerPath, "utf-8");
+  const hadCompletion = content.includes(`<promise>${loop.completion}</promise>`) || content.includes(loop.completion);
+  if (!hadCompletion) return false;
+  content = content.replace(new RegExp(`<promise>${loop.completion}</promise>`, "g"), "");
+  content = content.replace(new RegExp(loop.completion, "g"), "");
+  writeFileSync(trackerPath, content);
+  console.log(chalk3.cyan(`  \u21BB New items detected in data file \u2014 cleared stale completion for ${loop.name}`));
+  return true;
+}
+function stripCompletionString(flowDir, loop) {
+  const trackerPath = join2(flowDir, loop.tracker);
+  if (!existsSync2(trackerPath)) return;
+  let content = readFileSync(trackerPath, "utf-8");
+  const had = content.includes(`<promise>${loop.completion}</promise>`) || content.includes(loop.completion);
+  if (!had) return;
+  content = content.replace(new RegExp(`<promise>${loop.completion}</promise>`, "g"), "");
+  content = content.replace(new RegExp(loop.completion, "g"), "");
+  writeFileSync(trackerPath, content);
+}
 async function runLoop(loopName, options) {
   const flowDir = resolveFlowDir(options.cwd, options.flow);
   const config = loadConfig(flowDir);
@@ -264,22 +306,25 @@ async function runLoop(loopName, options) {
     cleanup();
     process.exit(143);
   });
+  stripCompletionString(flowDir, loop);
   try {
-    await iterationLoop(key, loop, flowDir, options, agentName);
+    await iterationLoop(key, loop, flowDir, options, agentName, void 0, void 0, true, config);
   } finally {
     cleanup();
   }
 }
-async function iterationLoop(configKey, loop, flowDir, options, agentName, db, flowName, forceFirstIteration) {
+async function iterationLoop(configKey, loop, flowDir, options, agentName, db, flowName, forceFirstIteration, config) {
   const loopKey = loop.name;
   const appName = basename(flowDir);
+  if (config) stripStaleCompletion(flowDir, loop, config);
   for (let i = 1; i <= options.maxIterations; i++) {
     if (!(forceFirstIteration && i === 1)) {
       if (db && flowName && isLoopComplete(db, flowName, loopKey)) {
         console.log(chalk3.green(`  \u2713 ${loop.name} \u2014 already complete`));
         return;
       }
-      if (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop)) {
+      const newItemsExist = config ? hasNewItemsInDataFile(flowDir, loop, config) : false;
+      if (!newItemsExist && (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop))) {
         if (db && flowName) markLoopComplete(db, flowName, loopKey);
         console.log(chalk3.green(`  \u2713 ${loop.name} \u2014 complete`));
         return;
@@ -301,7 +346,8 @@ async function iterationLoop(configKey, loop, flowDir, options, agentName, db, f
       skipPermissions: loop.skip_permissions
     });
     if (db && flowName) incrementIteration(db, flowName, loopKey);
-    if (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop)) {
+    const newItemsAfter = config ? hasNewItemsInDataFile(flowDir, loop, config) : false;
+    if (!newItemsAfter && (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop))) {
       if (db && flowName) markLoopComplete(db, flowName, loopKey);
       console.log();
       console.log(chalk3.green(`  Loop complete: ${loop.completion}`));
@@ -346,7 +392,8 @@ async function runE2E(options) {
           console.log(chalk3.green(`  \u2713 ${loop.name} \u2014 complete, skipping`));
           continue;
         }
-        if (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop)) {
+        const loopHasNewItems = hasNewItemsInDataFile(flowDir, loop, config);
+        if (!loopHasNewItems && (checkTrackerForCompletion(flowDir, loop) || checkTrackerMetadataCompletion(flowDir, loop) || checkTrackerAllChecked(flowDir, loop))) {
           markLoopComplete(db, flowName, loopKey);
           console.log(chalk3.green(`  \u2713 ${loop.name} \u2014 complete, skipping`));
           continue;
@@ -362,7 +409,7 @@ async function runE2E(options) {
         agentName = acquireAgentId(agentDir, loop.multi_agent.max_agents);
       }
       try {
-        await iterationLoop(key, loop, flowDir, options, agentName, db, flowName, isFirstLoop);
+        await iterationLoop(key, loop, flowDir, options, agentName, db, flowName, isFirstLoop, config);
       } finally {
         if (agentDir && agentName) releaseAgentId(agentDir, agentName);
       }
@@ -477,7 +524,7 @@ var runCommand = new Command2("run").description("Run a loop").argument("<loop>"
   try {
     let dashboardHandle;
     if (opts.ui) {
-      const { startDashboard } = await import("./server-EX5MWYW4.js");
+      const { startDashboard } = await import("./server-64NQCIKJ.js");
       dashboardHandle = await startDashboard({ cwd: process.cwd() });
     }
     await runLoop(loop, {
@@ -503,7 +550,7 @@ var e2eCommand = new Command3("e2e").description("Run all loops end-to-end with
   try {
     let dashboardHandle;
     if (opts.ui) {
-      const { startDashboard } = await import("./server-EX5MWYW4.js");
+      const { startDashboard } = await import("./server-64NQCIKJ.js");
       dashboardHandle = await startDashboard({ cwd: process.cwd() });
     }
     await runE2E({
@@ -540,7 +587,7 @@ var statusCommand = new Command4("status").description("Show pipeline status").o
 // src/cli/dashboard.ts
 import { Command as Command5 } from "commander";
 var dashboardCommand = new Command5("dashboard").alias("ui").description("Start the web dashboard").option("-p, --port <port>", "Port number", "4242").action(async (opts) => {
-  const { startDashboard } = await import("./server-EX5MWYW4.js");
+  const { startDashboard } = await import("./server-64NQCIKJ.js");
   await startDashboard({ cwd: process.cwd(), port: parseInt(opts.port, 10) });
 });
 
@@ -595,6 +642,39 @@ function buildPromptLoopConfig(loopDef) {
     stageConfigs
   };
 }
+function generateVisualProtocol() {
+  let s = "";
+  s += `## Visual Communication Protocol
+
+`;
+  s += `When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+`;
+  s += `**Character set:** \`\u250C \u2500 \u2510 \u2502 \u2514 \u2518 \u251C \u2524 \u252C \u2534 \u253C \u2550 \u25CF \u25CB \u25BC \u25B6\`
+
+`;
+  s += `**Diagram types to use:**
+
+`;
+  s += `- **Scope/Architecture Map** \u2014 components and their relationships in a bordered grid
+`;
+  s += `- **Decomposition Tree** \u2014 hierarchical breakdown with \`\u251C\u2500\u2500\` and \`\u2514\u2500\u2500\` branches
+`;
+  s += `- **Data Flow** \u2014 arrows (\`\u2500\u2500\u2192\`) showing how information moves between components
+`;
+  s += `- **Comparison Table** \u2014 bordered table for trade-offs and design options
+`;
+  s += `- **Status Summary** \u2014 bordered box with completion indicators (\`\u2713\` done, \`\u25CC\` pending)
+
+`;
+  s += `**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+`;
+  s += `---
+
+`;
+  return s;
+}
 function generatePromptFromConfig(loop, loopIndex, allLoops) {
   const loopName = loop.name || "Loop " + (loopIndex + 1);
   const inputFiles = (loop.inputFiles || "").trim();
@@ -641,6 +721,7 @@ function generatePromptFromConfig(loop, loopIndex, allLoops) {
   p += `---
 
 `;
+  p += generateVisualProtocol();
   if (loop.multi_agent) {
     p += `## Tracker Lock Protocol
 
@@ -800,14 +881,20 @@ function generatePromptFromConfig(loop, loopIndex, allLoops) {
   p += `---
 
 `;
-  if (loop.multi_agent) {
-    p += `## First-Run Handling
+  {
+    const scanFile = primaryInputFile || "input.md";
+    p += `## First-Run / New ${entityTitle} Detection
 
 `;
-    const scanFile = primaryInputFile || "input.md";
-    p += `If ${entityTitle}s Queue in tracker is empty: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers, populate queue with \`{agent: -, status: pending|blocked}\` metadata (compute from Dependencies), then start.
+    if (loop.multi_agent) {
+      p += `If ${entityTitle}s Queue in tracker is empty OR all entries are \`[x]\`: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers + \`**Depends on:**\` tags. For any ${entityLower} NOT already in the queue, add as \`- [ ] ${entityKey}: {title}\` with \`{agent: -, status: pending|blocked}\` metadata (compute from Dependencies), then start.
 
 `;
+    } else {
+      p += `If ${entityTitle}s Queue in tracker is empty OR all entries are \`[x]\`: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers + \`**Depends on:**\` tags. For any ${entityLower} NOT already in the queue, add as \`- [ ] ${entityKey}: {title}\` and update Dependencies. If new ${entityPlural} were added, proceed to process them.
+
+`;
+    }
     p += `---
 
 `;
@@ -857,6 +944,14 @@ function generatePromptFromConfig(loop, loopIndex, allLoops) {
 `;
       }
     }
+    if (i === 0) {
+      p += `${step++}. **Render a Scope Diagram** \u2014 output an ASCII architecture/scope map showing the areas this ${entityLower} touches, dependencies, and what needs to change
+`;
+    }
+    if (i === stageCount - 1 && stageCount > 1) {
+      p += `${step++}. **Render a Completion Summary** \u2014 output an ASCII status diagram showing what was built/changed, verification results, and how this ${entityLower} fits in overall progress
+`;
+    }
     if (loop.multi_agent) {
       p += `${step++}. Acquire lock \u2192 update tracker: stage, \`last_heartbeat\`, log entry \u2192 release lock
 `;
@@ -999,28 +1094,142 @@ var createTemplateCommand = new Command6("create-template").description("Create
   }
 });
 
+// src/cli/summarize.ts
+import { Command as Command7 } from "commander";
+import chalk8 from "chalk";
+import { existsSync as existsSync3 } from "fs";
+import { join as join3, resolve as resolve2 } from "path";
+var SUMMARIZE_PROMPT = `You are summarizing an archived RalphFlow workflow run.
+
+## What to read
+
+This directory is an archived app snapshot. It contains:
+- Loop subdirectories (e.g. \`00-story-loop/\`, \`01-tasks-loop/\`, \`02-delivery-loop/\`) \u2014 each has:
+  - \`stories.md\` or \`tasks.md\` \u2014 the work items with \`## STORY-N:\` or \`## TASK-N:\` headers
+  - \`tracker.md\` \u2014 completion state with \`- [x]\` (done) and \`- [ ]\` (incomplete) checkboxes, \`completed_tasks\`/\`completed_stories\` lists, and agent activity logs
+- \`ralphflow.yaml\` \u2014 pipeline configuration
+
+Read ALL \`.md\` files across all subdirectories. Parse stories, task groups (\`# TASK-GROUP-N:\` headers in tasks.md), and individual tasks. Determine completion from tracker checkboxes: \`[x]\` = completed, \`[ ]\` = incomplete.
+
+## What to write
+
+Write a file called \`summary.md\` in the current directory with this exact structure:
+
+\`\`\`
+# Archive Summary
+
+**N stories \xB7 N task groups \xB7 N/N tasks completed \xB7 N agents**
+
+## Pipeline
+
+\\\`\\\`\\\`
+STORY-1: Title
+\u251C\u2500\u2500 TASK-GROUP-1: Title
+\u2502   \u251C\u2500\u2500 \u2713 TASK-1: Title
+\u2502   \u251C\u2500\u2500 \u2713 TASK-2: Title
+\u2502   \u2514\u2500\u2500 \u25CB TASK-3: Title
+\u2514\u2500\u2500 TASK-GROUP-2: Title
+    \u2514\u2500\u2500 \u2713 TASK-4: Title
+
+STORY-2: Title
+\u2514\u2500\u2500 TASK-GROUP-3: Title
+    \u251C\u2500\u2500 \u2713 TASK-5: Title
+    \u2514\u2500\u2500 \u2713 TASK-6: Title
+\\\`\\\`\\\`
+
+## What was built
+
+**STORY-1: Title** \u2014 1-2 sentence narrative of what was accomplished and why.
+
+**STORY-2: Title** \u2014 1-2 sentence narrative.
+
+## Key decisions
+
+- Decision or trade-off noted in tracker logs or task descriptions
+- Another significant decision
+\`\`\`
+
+Rules:
+- Use \`\u2713\` for completed tasks, \`\u25CB\` for incomplete
+- The ASCII tree uses box-drawing characters (\`\u251C\u2500\u2500 \u2514\u2500\u2500 \u2502\`)
+- Stats line counts: stories (from stories.md headers), task groups, tasks completed vs total, unique agents (from tracker agent columns)
+- Story narratives should capture *what was built and why* \u2014 not just list tasks
+- Key decisions come from tracker logs, task descriptions, or trade-offs visible in the work
+- Keep the whole file under 80 lines \u2014 it should fit on one screen
+- If no tasks.md exists (e.g. a research pipeline), adapt: use whatever entity headers exist (topics, stories, etc.)
+
+After writing summary.md, you are done. Do not modify any other files.`;
+var summarizeCommand = new Command7("summarize").description("Generate a summary of an archived workflow run").argument("<app>", "App name (e.g., code-implementation)").argument("<archive-date>", "Archive timestamp (e.g., 2026-03-14_15-30)").option("-m, --model <model>", "Claude model to use").action(async (app, archiveDate, opts) => {
+  if (app.includes("..") || app.includes("/") || app.includes("\\")) {
+    console.error(chalk8.red("\n  Invalid app name.\n"));
+    process.exit(1);
+  }
+  if (archiveDate.includes("..") || archiveDate.includes("/") || archiveDate.includes("\\")) {
+    console.error(chalk8.red("\n  Invalid archive date.\n"));
+    process.exit(1);
+  }
+  const archiveDir = resolve2(process.cwd(), ".ralph-flow", ".archives", app, archiveDate);
+  if (!existsSync3(archiveDir)) {
+    const appArchivesDir = join3(process.cwd(), ".ralph-flow", ".archives", app);
+    if (!existsSync3(appArchivesDir)) {
+      console.error(chalk8.red(`
+  No archives found for app "${app}".`));
+      console.error(chalk8.dim(`  Archive an app first via the dashboard.
+`));
+    } else {
+      const { readdirSync: readdirSync3 } = await import("fs");
+      const available = readdirSync3(appArchivesDir, { withFileTypes: true }).filter((d) => d.isDirectory()).map((d) => d.name).sort().reverse();
+      console.error(chalk8.red(`
+  Archive "${archiveDate}" not found for app "${app}".`));
+      if (available.length > 0) {
+        console.error(chalk8.dim(`  Available archives:`));
+        for (const a of available) {
+          console.error(chalk8.dim(`    ${a}`));
+        }
+      }
+      console.error("");
+    }
+    process.exit(1);
+  }
+  console.log(chalk8.dim(`
+  Summarizing archive: ${app}/${archiveDate}
+`));
+  try {
+    await spawnClaude({
+      prompt: SUMMARIZE_PROMPT,
+      model: opts.model,
+      cwd: archiveDir
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(chalk8.red(`
+  ${msg}
+`));
+    process.exit(1);
+  }
+});
+
 // src/cli/index.ts
-var program = new Command7().name("ralphflow").description("Multi-agent AI workflow orchestration for Claude Code").version("0.1.0").addCommand(initCommand).addCommand(runCommand).addCommand(e2eCommand).addCommand(statusCommand).addCommand(dashboardCommand).addCommand(createTemplateCommand).action(async () => {
-  const port = 4242;
-  const { startDashboard } = await import("./server-EX5MWYW4.js");
-  await startDashboard({ cwd: process.cwd(), port });
+var program = new Command8().name("ralphflow").description("Multi-agent AI workflow orchestration for Claude Code").version("0.1.0").addCommand(initCommand).addCommand(runCommand).addCommand(e2eCommand).addCommand(statusCommand).addCommand(dashboardCommand).addCommand(createTemplateCommand).addCommand(summarizeCommand).action(async () => {
+  const { startDashboard } = await import("./server-64NQCIKJ.js");
+  const { port } = await startDashboard({ cwd: process.cwd() });
   const url = `http://localhost:${port}`;
   exec(`open "${url}"`, (err) => {
     if (err) {
-      console.log(chalk8.dim(`  Open ${url} in your browser`));
+      console.log(chalk9.dim(`  Open ${url} in your browser`));
     }
   });
 });
 process.on("SIGINT", () => {
   console.log();
-  console.log(chalk8.dim("  Interrupted."));
+  console.log(chalk9.dim("  Interrupted."));
   process.exit(130);
 });
 program.configureOutput({
   writeErr: (str) => {
     const clean = str.replace(/^error: /, "");
     if (clean.trim()) {
-      console.error(chalk8.red(`  ${clean.trim()}`));
+      console.error(chalk9.red(`  ${clean.trim()}`));
     }
   }
 });

package/dist/{server-EX5MWYW4.js → server-64NQCIKJ.js}

@@ -15,12 +15,12 @@ import {
   resolveFlowDir,
   resolveTemplatePathWithCustom,
   validateTemplateName
-} from "./chunk-DOC64TD6.js";
+} from "./chunk-CA4XP6KI.js";
 
 // src/dashboard/server.ts
 import { Hono as Hono2 } from "hono";
 import { cors } from "hono/cors";
-import { serve } from "@hono/node-server";
+import { createAdaptorServer } from "@hono/node-server";
 import { readFileSync as readFileSync3, existsSync as existsSync3 } from "fs";
 import { join as join4, dirname, extname } from "path";
 import { fileURLToPath } from "url";
@@ -45,13 +45,13 @@ function broadcastWs(wss, event) {
     }
   }
 }
-function createApiRoutes(cwd, port = 4242, wss) {
+function createApiRoutes(cwd, portRef, wss) {
   const api = new Hono();
   api.get("/api/context", (c) => {
     return c.json({
       cwd,
       projectName: basename(cwd),
-      port
+      port: portRef.value
     });
   });
   api.get("/api/apps", (c) => {
@@ -175,24 +175,51 @@ function createApiRoutes(cwd, port = 4242, wss) {
       mkdirSync(archiveDir, { recursive: true });
       cpSync(flowDir, archiveDir, { recursive: true });
       let templateDir;
+      let usedFallbackReset = false;
       try {
         templateDir = resolveTemplatePathWithCustom(config.name, cwd);
       } catch {
+        usedFallbackReset = true;
+        console.warn(`[archive] Template "${config.name}" not found \u2014 using fallback reset`);
       }
-      for (const loop of Object.values(config.loops)) {
+      for (const [loopKey, loop] of Object.entries(config.loops)) {
+        const appTracker = join(flowDir, loop.tracker);
         if (templateDir) {
           const templateTracker = join(templateDir, "loops", loop.tracker);
-          const appTracker = join(flowDir, loop.tracker);
           if (existsSync(templateTracker)) {
             writeFileSync(appTracker, readFileSync(templateTracker, "utf-8"));
           }
+        } else if (existsSync(appTracker)) {
+          const title = loop.name || loopKey;
+          writeFileSync(appTracker, `# ${title} \u2014 Tracker
+
+- stage: idle
+`);
         }
-        if (loop.data_files && templateDir) {
+        if (loop.data_files) {
           for (const dataFile of loop.data_files) {
-            const templateData = join(templateDir, "loops", dataFile);
             const appData = join(flowDir, dataFile);
-            if (existsSync(templateData)) {
-              writeFileSync(appData, readFileSync(templateData, "utf-8"));
+            if (templateDir) {
+              const templateData = join(templateDir, "loops", dataFile);
+              if (existsSync(templateData)) {
+                writeFileSync(appData, readFileSync(templateData, "utf-8"));
+              }
+            } else if (existsSync(appData)) {
+              const fileName = basename(dataFile, ".md");
+              const header = fileName.charAt(0).toUpperCase() + fileName.slice(1);
+              writeFileSync(appData, `# ${header}
+`);
+            }
+          }
+        }
+        if (loop.directories) {
+          for (const dir of loop.directories) {
+            const dirPath = join(flowDir, dir);
+            if (existsSync(dirPath)) {
+              for (const entry of readdirSync(dirPath)) {
+                const entryPath = join(dirPath, entry);
+                rmSync(entryPath, { recursive: true, force: true });
+              }
             }
           }
         }
@@ -224,7 +251,11 @@ function createApiRoutes(cwd, port = 4242, wss) {
         }
       }
       const archivePath = `.ralph-flow/.archives/${appName}/${archiveTimestamp}`;
-      return c.json({ ok: true, archivePath, timestamp: archiveTimestamp });
+      const result = { ok: true, archivePath, timestamp: archiveTimestamp };
+      if (usedFallbackReset) {
+        result.warning = `Template "${config.name}" not found \u2014 reset used fallback (minimal empty content)`;
+      }
+      return c.json(result);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       return c.json({ error: `Archive failed: ${msg}` }, 500);
@@ -913,6 +944,7 @@ function removeNotificationHook(cwd) {
 
 // src/dashboard/server.ts
 var __dirname = dirname(fileURLToPath(import.meta.url));
+var MAX_PORT_ATTEMPTS = 10;
 var CONTENT_TYPES = {
   ".css": "text/css",
   ".js": "text/javascript",
@@ -933,15 +965,33 @@ function resolveUiDir() {
 ${candidates.map((c) => join4(c, "index.html")).join("\n")}`
   );
 }
+function tryListen(server, hostname, port) {
+  return new Promise((resolve2, reject) => {
+    const onError = (err) => {
+      server.removeListener("listening", onListening);
+      reject(err);
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      const addr = server.address();
+      const boundPort = addr && typeof addr === "object" ? addr.port : port;
+      resolve2(boundPort);
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, hostname);
+  });
+}
 async function startDashboard(options) {
-  const { cwd, port = 4242 } = options;
+  const { cwd, port: requestedPort = 4242 } = options;
   const app = new Hono2();
   const wss = new WebSocketServer3({ noServer: true });
+  const portRef = { value: requestedPort };
   app.use("*", cors({
     origin: (origin) => origin || "*",
     allowMethods: ["GET", "PUT", "POST", "DELETE"]
   }));
-  const apiRoutes = createApiRoutes(cwd, port, wss);
+  const apiRoutes = createApiRoutes(cwd, portRef, wss);
   app.route("/", apiRoutes);
   const uiDir = resolveUiDir();
   app.get("/", (c) => {
@@ -958,11 +1008,25 @@ async function startDashboard(options) {
     const contentType = CONTENT_TYPES[extname(filePath)] || "text/plain";
     return c.text(content, 200, { "Content-Type": contentType });
   });
-  const server = serve({
-    fetch: app.fetch,
-    port,
-    hostname: "127.0.0.1"
-  });
+  let server = createAdaptorServer({ fetch: app.fetch });
+  let actualPort = requestedPort;
+  for (let attempt = 0; attempt < MAX_PORT_ATTEMPTS; attempt++) {
+    const candidatePort = requestedPort + attempt;
+    try {
+      actualPort = await tryListen(server, "127.0.0.1", candidatePort);
+      break;
+    } catch (err) {
+      const nodeErr = err;
+      if (nodeErr.code !== "EADDRINUSE") throw err;
+      if (attempt >= MAX_PORT_ATTEMPTS - 1) {
+        throw new Error(
+          `Could not find an available port (tried ${requestedPort}\u2013${requestedPort + MAX_PORT_ATTEMPTS - 1})`
+        );
+      }
+      server = createAdaptorServer({ fetch: app.fetch });
+    }
+  }
+  portRef.value = actualPort;
   server.on("upgrade", (request, socket, head) => {
     const url = new URL(request.url || "/", `http://${request.headers.host}`);
     if (url.pathname === "/ws") {
@@ -975,14 +1039,17 @@ async function startDashboard(options) {
   });
   const watcherHandle = setupWatcher(cwd, wss);
   try {
-    installNotificationHook(cwd, port);
+    installNotificationHook(cwd, actualPort);
     console.log(chalk.dim(`  Configured Claude hook \u2192 .claude/settings.local.json`));
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.log(chalk.yellow(`  \u26A0 Could not configure Claude hook: ${msg}`));
   }
   console.log();
-  console.log(chalk.bold(`  Dashboard ${chalk.dim("\u2192")} http://localhost:${port}`));
+  if (actualPort !== requestedPort) {
+    console.log(chalk.yellow(`  Port ${requestedPort} was busy, using ${actualPort} instead`));
+  }
+  console.log(chalk.bold(`  Dashboard ${chalk.dim("\u2192")} http://localhost:${actualPort}`));
   console.log(chalk.dim(`  Watching ${cwd}/.ralph-flow/`));
   console.log();
   let closed = false;
@@ -1014,7 +1081,7 @@ async function startDashboard(options) {
       }
     }
   });
-  return { close };
+  return { close, port: actualPort };
 }
 export {
   startDashboard

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ralphflow",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Multi-agent AI workflow orchestration framework for Claude Code. Define pipelines as loops, coordinate parallel agents, and ship structured work.",
   "type": "module",
   "bin": {

package/src/dashboard/ui/app.js

@@ -56,6 +56,9 @@ fetch('/api/context')
   .then(r => r.json())
   .then(ctx => {
     dom.hostDisplay.textContent = ctx.projectName + ' :' + ctx.port;
+    dom.pageTitle.textContent = ctx.projectName;
+    document.title = ctx.projectName + ' \u00b7 RalphFlow Dashboard';
+    state.projectName = ctx.projectName;
   })
   .catch(() => { /* keep location.host as fallback */ });
 
@@ -183,7 +186,7 @@ document.getElementById('templatesNav').addEventListener('click', () => {
   state.showTemplateWizard = false;
   state.wizardStep = 0;
   state.wizardData = null;
-  document.title = 'Templates - RalphFlow Dashboard';
+  document.title = 'Templates \u00b7 ' + (state.projectName || 'RalphFlow Dashboard');
   renderSidebar();
   renderContent();
 });