ralphflow 0.5.0 → 0.5.1

package/src/dashboard/ui/utils.js

@@ -0,0 +1,115 @@
+// Shared utility functions used across dashboard modules.
+
+export function esc(s) {
+  if (s == null) return '';
+  const d = document.createElement('div');
+  d.textContent = String(s);
+  return d.innerHTML;
+}
+
+export async function fetchJson(url) {
+  const res = await fetch(url);
+  return res.json();
+}
+
+export function renderMarkdown(md) {
+  let html = '';
+  const lines = md.split('\n');
+  let inTable = false;
+  let tableHtml = '';
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    // Table detection
+    if (line.match(/^\|.+\|$/)) {
+      if (!inTable) {
+        inTable = true;
+        tableHtml = '<table>';
+        // Header row
+        const cells = line.split('|').filter(Boolean).map(c => c.trim());
+        tableHtml += '<thead><tr>' + cells.map(c => `<th>${esc(c)}</th>`).join('') + '</tr></thead><tbody>';
+        continue;
+      }
+      // Separator row
+      if (line.match(/^\|[\s\-|]+\|$/)) continue;
+      // Data row
+      const cells = line.split('|').filter(Boolean).map(c => c.trim());
+      tableHtml += '<tr>' + cells.map(c => `<td>${esc(c)}</td>`).join('') + '</tr>';
+      continue;
+    } else if (inTable) {
+      inTable = false;
+      tableHtml += '</tbody></table>';
+      html += tableHtml;
+      tableHtml = '';
+    }
+
+    // Headers
+    if (line.startsWith('### ')) { html += `<h3>${esc(line.slice(4))}</h3>`; continue; }
+    if (line.startsWith('## ')) { html += `<h2>${esc(line.slice(3))}</h2>`; continue; }
+    if (line.startsWith('# ')) { html += `<h1>${esc(line.slice(2))}</h1>`; continue; }
+
+    // Checkboxes
+    if (line.match(/^- \[x\]/i)) {
+      html += `<div class="cb-done">${esc(line)}</div>`;
+      continue;
+    }
+    if (line.match(/^- \[ \]/)) {
+      html += `<div class="cb-todo">${esc(line)}</div>`;
+      continue;
+    }
+
+    // Regular lines
+    html += line.trim() === '' ? '<br>' : `<div>${esc(line)}</div>`;
+  }
+
+  if (inTable) {
+    tableHtml += '</tbody></table>';
+    html += tableHtml;
+  }
+
+  return html;
+}
+
+export function calculatePipelineProgress(loops) {
+  const perLoop = [];
+  let aggCompleted = 0;
+  let aggTotal = 0;
+  for (const loop of (loops || [])) {
+    const st = loop.status || {};
+    const completed = st.completed || 0;
+    const total = st.total || 0;
+    const fraction = total > 0 ? completed / total : 0;
+    perLoop.push({ key: loop.key, completed, total, fraction });
+    if (total > 0) {
+      aggCompleted += completed;
+      aggTotal += total;
+    }
+  }
+  const percentage = aggTotal > 0 ? Math.round(aggCompleted / aggTotal * 100) : 0;
+  return { perLoop, completed: aggCompleted, total: aggTotal, percentage };
+}
+
+export function formatModelName(model) {
+  if (!model) return null;
+  return model.replace(/^claude-/, '');
+}
+
+export function getLoopStatusClass(loop) {
+  if (!loop.status) return 'pending';
+  const st = loop.status;
+  if (st.total > 0 && st.completed === st.total) return 'complete';
+  if (st.agents && st.agents.length > 0) return 'running';
+  if (st.total > 0 && st.completed > 0 && st.completed < st.total) return 'running';
+  if (st.stage && st.stage !== '—' && st.stage !== 'idle') return 'running';
+  return 'pending';
+}
+
+export function extractNotifMessage(payload) {
+  if (!payload) return 'Attention needed';
+  if (typeof payload === 'string') return payload;
+  if (payload.message) return payload.message;
+  if (payload.type) return payload.type;
+  if (payload.event) return payload.event;
+  return 'Attention needed';
+}

package/src/templates/code-implementation/loops/00-story-loop/prompt.md

@@ -134,6 +134,28 @@ If Stories Queue in tracker is empty: read `stories.md`, scan `## STORY-{N}:` he
 
 ---
 
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Scope boundary decisions (included/excluded functionality from a story)
+- Approach choices (why you decomposed tasks one way vs. another)
+- Trade-off resolutions (prioritizing one concern over another)
+- Interpretation of ambiguous requirements (how you resolved unclear user intent)
+- Self-answered clarification questions (questions you could have asked but resolved yourself)
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"STORY-{N}","agent":"story-loop","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: picking the next story, updating tracker, stage transitions, heartbeat updates. Only report substantive choices that affect the work product.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
 ## Rules
 
 - One story at a time. All 3 stages run in one iteration, one `kill` at the end.

package/src/templates/code-implementation/loops/01-tasks-loop/prompt.md

@@ -149,6 +149,29 @@ After completing ANY stage, exit: `kill -INT $PPID`
 
 If Tasks Queue in tracker is empty: read `tasks.md`, scan `## TASK-{N}:` headers, populate queue with `{agent: -, status: pending|blocked}` metadata (compute from Dependencies), then start.
 
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Scope boundary decisions (what's included/excluded from the task)
+- Approach choices (implementation strategy, library selection, architecture decisions)
+- Trade-off resolutions (performance vs. readability, scope vs. complexity)
+- Interpretation of ambiguous requirements (how you resolved unclear task intent)
+- Self-answered clarification questions (questions you could have asked but resolved yourself)
+- File overlap or conflict decisions (how you handled shared files with other agents)
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"TASK-{N}","agent":"{{AGENT_NAME}}","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: claiming a task, updating heartbeat, stage transitions, waiting for blocked tasks. Only report substantive choices that affect the implementation.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
 ## Rules
 
 - One task at a time per agent. One stage per iteration.

package/src/templates/code-implementation/loops/02-delivery-loop/prompt.md

@@ -92,6 +92,27 @@ After resolving all feedback:
 
 ---
 
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Feedback categorization decisions (classifying feedback as BUG vs. CHANGE)
+- Scope decisions during bug fixes (what to fix now vs. defer to a new story)
+- Presentation choices (how you framed or organized the walkthrough)
+- Trade-off resolutions when multiple feedback items conflict
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"STORY-{N}","agent":"delivery-loop","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: picking the next story, updating tracker, phase transitions. Only report substantive choices that affect the delivery outcome.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
 ## Rules
 
 - One STORY at a time. All 3 phases run in one iteration, one `kill` at the end.

package/src/templates/research/loops/00-discovery-loop/prompt.md

@@ -107,6 +107,28 @@ If all topics have been discovered and queue is empty: `<promise>ALL TOPICS DISC
 
 ---
 
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Scope boundary decisions (what's in/out of the research scope)
+- Topic decomposition choices (why topics were split a certain way)
+- Priority assignments (why a topic is high vs. medium vs. low priority)
+- Depth decisions (surface vs. deep investigation for specific areas)
+- Dependency structure choices (why certain topics must precede others)
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"TOPIC-{N}","agent":"discovery-loop","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: updating tracker, stage transitions. Only report substantive choices that affect the research direction.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
 ## Rules
 
 - One research brief at a time. All 3 stages run in one iteration, one `kill` at the end.

package/src/templates/research/loops/01-research-loop/prompt.md

@@ -170,6 +170,28 @@ After completing ANY stage, exit: `kill -INT $PPID`
 
 If Topics Queue in tracker is empty: read `topics.md`, scan `## TOPIC-{N}:` headers + `**Depends on:**` tags, populate queue with `{agent: -, status: pending|blocked}` metadata, then start.
 
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Research direction choices (which angles to pursue vs. skip)
+- Source credibility judgments (why you trusted or dismissed a source)
+- Scope boundary decisions (what's in/out for this topic's investigation)
+- Conflicting evidence resolution (how you weighed contradictory findings)
+- Gap identification decisions (what couldn't be found and whether to flag it)
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"TOPIC-{N}","agent":"{{AGENT_NAME}}","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: claiming a topic, updating heartbeat, stage transitions, waiting for blocked topics. Only report substantive choices that affect the research findings.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
 ## Rules
 
 - One topic at a time per agent. One stage per iteration.

package/src/templates/research/loops/02-story-loop/prompt.md

@@ -96,6 +96,28 @@ If all stories written: `<promise>ALL STORIES WRITTEN</promise>`
 
 ---
 
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Theme grouping decisions (why findings were clustered into specific stories)
+- Narrative framing choices (how you chose to frame the story's angle)
+- Evidence weighting (which data points to emphasize vs. downplay)
+- Audience adaptation decisions (how you adjusted tone or depth for the target audience)
+- Scope decisions (what to include/exclude from a story's narrative)
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"STORY-{N}","agent":"story-loop","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: picking the next story, updating tracker, stage transitions. Only report substantive choices that affect the story content.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
 ## Rules
 
 - One story at a time. Both stages run in one iteration, one `kill` at the end.

package/src/templates/research/loops/03-document-loop/prompt.md

@@ -109,6 +109,28 @@ Read `.ralph-flow/{{APP_NAME}}/03-document-loop/tracker.md` FIRST to determine w
 
 ---
 
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Document structure decisions (how you organized the overall narrative)
+- Story ordering choices (why stories were arranged in a particular sequence)
+- Format decisions (how you adapted content for the chosen output format)
+- Editorial choices (what to include in the executive summary, what to put in appendices)
+- Audience adaptation decisions (how you adjusted tone or depth)
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"DOCUMENT","agent":"document-loop","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: reading files, updating tracker. Only report substantive choices that affect the final document.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
 ## Rules
 
 - This runs ONCE, on-demand. It is not a recurring loop.