ralphflow 0.5.0 → 0.5.2

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

@@ -12,13 +12,39 @@ Read `.ralph-flow/{{APP_NAME}}/00-story-loop/tracker.md` FIRST to determine wher
 
 ---
 
+## Visual Communication Protocol
+
+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.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**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.
+
+---
+
 ## State Machine (3 stages per story)
 
 **FIRST — Check completion.** Read the tracker. If the Stories Queue has entries
-AND every entry is `[x]` (no pending stories), do NOT write the completion promise yet.
-Instead, go to **"No Stories? Collect Them"** to ask the user for new stories.
+AND every entry is `[x]` (no pending stories):
+1. **Re-scan `stories.md`** — read all `## STORY-{N}:` headers and compare
+   against the Stories Queue in the tracker.
+2. **New stories found** (in `stories.md` but not in the queue) → add them as
+   `- [ ] STORY-{N}: {title}` to the Stories Queue, update the Dependency Graph
+   from their `**Depends on:**` tags, then proceed to process the lowest-numbered
+   ready story via the normal state machine.
+3. **No new stories** → go to **"No Stories? Collect Them"** to ask the user.
+
 Only write `<promise>ALL STORIES PROCESSED</promise>` when the user explicitly
-confirms they have no more stories to add.
+confirms they have no more stories to add AND `stories.md` has no stories
+missing from the tracker queue.
 
 Pick the lowest-numbered `ready` story. NEVER process a `blocked` story.
 
@@ -28,7 +54,8 @@ Pick the lowest-numbered `ready` story. NEVER process a `blocked` story.
 
 **Triggers when:**
 - `stories.md` has no stories at all (first run, empty queue with no entries), OR
-- All stories in the queue are completed (`[x]`) and there are no `pending` stories left
+- All stories in the queue are completed (`[x]`), no `pending` stories remain, AND
+  `stories.md` has been re-scanned and contains no stories missing from the queue
 
 **Flow:**
 1. Tell the user: *"No pending stories. Tell me what you want to build — describe features, problems, or goals in your own words."*
@@ -45,9 +72,13 @@ CLARIFY   → Ask user up to 20 questions (5 at a time) → stage: decompose
 DECOMPOSE → Break into TASK-GROUP(s) + tasks, append to tasks.md, mark done → kill
 ```
 
-## First-Run Handling
+## First-Run / New Story Detection
 
-If Stories Queue in tracker is empty: read `stories.md`, scan `## STORY-{N}:` headers + `**Depends on:**` tags, populate queue as `- [ ] STORY-{N}: {title}`, build Dependency Graph.
+If Stories Queue in tracker is empty OR all entries are `[x]`: read `stories.md`,
+scan `## STORY-{N}:` headers + `**Depends on:**` tags. For any story NOT already
+in the queue, add as `- [ ] STORY-{N}: {title}` and build/update the Dependency Graph.
+If new stories were added, proceed to process them. If the queue is still empty
+after scanning, go to **"No Stories? Collect Them"**.
 
 ---
 
@@ -56,23 +87,32 @@ If Stories Queue in tracker is empty: read `stories.md`, scan `## STORY-{N}:` he
 1. Read tracker → pick lowest-numbered `ready` story
 2. Read the story from `stories.md` (+ any referenced screenshots)
 3. **Explore the codebase** — read `CLAUDE.md` for project context, then **20+ key files** across the areas this story touches. Understand current behavior, patterns, conventions, and what needs to change.
-4. Update tracker: `active_story: STORY-{N}`, `stage: clarify`, log entry
+4. **Render a Scope Map** — output an ASCII architecture/scope diagram showing:
+   - The areas of the codebase this story touches (components, modules, services)
+   - Dependencies and data flow between affected areas
+   - What exists today (`●`) vs. what needs to change (`○`)
+5. Update tracker: `active_story: STORY-{N}`, `stage: clarify`, log entry
 
 ## STAGE 2: CLARIFY
 
 1. Formulate questions about scope, priorities, edge cases, design choices
-2. **Ask up to 20 questions, 5 at a time** via `AskUserQuestion` (with options where possible):
+2. **Present understanding diagram first** — render an ASCII scope/architecture diagram showing your understanding of the story's scope. This gives the user a visual anchor to correct misconceptions before answering questions.
+3. **Ask up to 20 questions, 5 at a time** via `AskUserQuestion` — structure each round visually:
+   - For multi-option decisions: numbered list with one-line descriptions
+   - For design trade-offs: include a **comparison table** showing trade-offs (e.g., approach vs. complexity vs. speed)
+   - For scope boundaries: use an in/out list format
    - Round 1: Scope, intent, must-haves
    - Round 2+: Design choices, edge cases, preferences — based on prior answers
    - Stop early if clear enough
-3. Save Q&A summary in tracker log
-4. Update tracker: `stage: decompose`, log entry with key decisions
+4. Save Q&A summary in tracker log
+5. Update tracker: `stage: decompose`, log entry with key decisions
 
 ## STAGE 3: DECOMPOSE
 
 1. Find next TASK-GROUP and TASK numbers (check existing in `01-tasks-loop/tasks.md`)
 2. **Read already-written tasks** — if sibling tasks exist, read them to align scope boundaries
-3. Break story into TASK-GROUP(s) — one per distinct functional area, 2-6 tasks each
+3. **Render a Decomposition Tree** — output an ASCII tree showing the planned TASK-GROUP(s) and their tasks, with dependency arrows between tasks that depend on each other
+4. Break story into TASK-GROUP(s) — one per distinct functional area, 2-6 tasks each
 4. For each task, ask yourself: *What does success look like? How would someone confirm? What could silently break?*
 5. **Sanity-check:** Do NOT embed specific file paths in tasks — describe *what* changes, not *where*. The tasks loop will explore the codebase itself.
 6. Append to `01-tasks-loop/tasks.md` (format below)
@@ -134,6 +174,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

@@ -14,6 +14,24 @@ Read `.ralph-flow/{{APP_NAME}}/01-tasks-loop/tracker.md` FIRST to determine wher
 
 ---
 
+## Visual Communication Protocol
+
+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.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**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.
+
+---
+
 ## Tracker Lock Protocol
 
 Before ANY write to `tracker.md`, you MUST acquire the lock:
@@ -112,7 +130,11 @@ After completing ANY stage, exit: `kill -INT $PPID`
 3. If sibling tasks are done, read their commits/diffs to align
 4. Read `CLAUDE.md` for project context
 5. Explore codebase — **40+ files:** affected areas, dependencies, patterns
-6. Acquire lock → update tracker: your Agent Status row `active_task: TASK-{N}`, `stage: execute`, `last_heartbeat`, log entry → release lock
+6. **Render an Implementation Map** — output an ASCII diagram showing:
+   - Files/modules to create or modify (grouped by area)
+   - Data flow or control flow for the change
+   - How this task's changes connect to sibling tasks in the group
+7. Acquire lock → update tracker: your Agent Status row `active_task: TASK-{N}`, `stage: execute`, `last_heartbeat`, log entry → release lock
 7. Implement changes. Match existing patterns per `CLAUDE.md`.
 8. Deploy/rebuild (commands in `CLAUDE.md`)
 9. **Quick verify:** check container logs for errors, hit health endpoints, confirm no crashes
@@ -126,7 +148,11 @@ After completing ANY stage, exit: `kill -INT $PPID`
 3. **Functional verify:** test the actual change — hit new/modified endpoints, check DB state, verify expected behavior through CLI/curl/API calls
 4. **FAIL** → fix the issue, re-deploy, re-verify. If stuck, log details in tracker and move on
 5. **PASS** → continue to documentation
-6. Update `CLAUDE.md` (≤150 words net). Commit separately.
+6. **Render a Completion Summary** — output an ASCII status diagram showing:
+   - What was built/changed (files, endpoints, components)
+   - Verification results (pass/fail per acceptance criterion)
+   - How this task fits in the TASK-GROUP progress
+7. Update `CLAUDE.md` (≤150 words net). Commit separately.
 7. Create/update `.claude/skills/` if this task produced reusable knowledge. Skip if nothing reusable.
 8. **Mark done & unblock dependents:**
    - Acquire lock
@@ -149,6 +175,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

@@ -12,6 +12,24 @@ Read `.ralph-flow/{{APP_NAME}}/02-delivery-loop/tracker.md` FIRST to determine w
 
 ---
 
+## Visual Communication Protocol
+
+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.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**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.
+
+---
+
 ## First-Run Handling
 
 If Delivery Queue is empty, build it by scanning the task tracker:
@@ -47,18 +65,23 @@ Phase 1 → Phase 2 flows continuously in one iteration (no kill between them).
 2. Read phase plans from `01-tasks-loop/phases/`
 3. Read `CLAUDE.md` for project context
 4. **Review independently:** Walk through each task's verification steps. Note anything wrong, broken, or inconsistent. Build a presentation narrative.
-5. For cancelled tasks/groups: note what was superseded and why
+5. **Build a Delivery Diagram** — prepare an ASCII diagram for presentation showing:
+   - All task-groups in this story with completion status
+   - Per-task status (`✓` done, `✗` cancelled, `!` issues found)
+   - Data flow or architecture of what was built
+6. For cancelled tasks/groups: note what was superseded and why
 6. Record review notes in tracker log
 7. Update tracker: `active_story: STORY-{N}`, `stage: present-and-feedback`
 8. **Flow directly into Phase 2** (no stop)
 
 ## PHASE 2: PRESENT-AND-FEEDBACK (combined, one AskUserQuestion call)
 
-1. **Present structured walkthrough** of ALL task-groups in the story:
-   - Per task-group: what was built (plain language), how to verify it
+1. **Present structured walkthrough with diagrams:**
+   - Open with an ASCII **architecture/scope diagram** showing what was built (components, data flow, integrations)
+   - Per task-group: what was built (plain language), completion status, how to verify it
    - Any issues the agent found during Phase 1 review
    - Cancelled tasks/groups with brief explanation of what was superseded
-2. **Ask 3-4 questions in ONE `AskUserQuestion` call:**
+2. **Ask 3-4 questions in ONE `AskUserQuestion` call** — use visual grouping:
    - **Q1: Working correctly?** Does everything work as expected? Note any specific issues.
    - **Q2: Behavior or appearance?** Anything to change about look, feel, or behavior?
    - **Q3: Missing or new ideas?** Anything missing, or new ideas sparked by what you see?
@@ -92,6 +115,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

@@ -12,13 +12,37 @@ Read `.ralph-flow/{{APP_NAME}}/00-discovery-loop/tracker.md` FIRST to determine
 
 ---
 
+## Visual Communication Protocol
+
+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.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**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.
+
+---
+
 ## No Brief? Collect One
 
+If the tracker queue has entries and all are `[x]`:
+1. **Re-scan `topics.md`** — read all `## TOPIC-{N}:` headers and compare against
+   the Topics Queue in the tracker. If new topics found, add them as
+   `- [ ] TOPIC-{N}: {title}` with appropriate metadata and proceed to process them.
+2. **No new topics** → proceed to "No Brief? Collect One" below.
+
 If `topics.md` has no unprocessed topics and the tracker queue is empty/all done:
 1. Tell the user: *"No research brief found. Tell me what you want to research — describe questions, problems, or domains you want to understand."*
 2. Use `AskUserQuestion` to prompt: "What do you want to research or understand?" (open-ended)
 3. As the user narrates, capture the research brief in tracker log under `## Research Brief`
-4. **Confirm scope** — present the brief back. Use `AskUserQuestion` (up to 5 questions) to validate: correct scope? right depth? any areas to include/exclude? target audience? desired output format (PDF, PPT, document)?
+4. **Confirm scope with a visual summary** — render an ASCII scope map showing the research boundaries, then use `AskUserQuestion` (up to 5 questions) to validate: correct scope? right depth? any areas to include/exclude? target audience? desired output format (PDF, PPT, document)?
 5. Apply corrections, finalize brief, proceed to normal flow
 
 ---
@@ -31,9 +55,14 @@ EXPLORE  → Search broadly for sub-domains, angles, key questions → stage: de
 DECOMPOSE → Break into TOPIC entries, write to topics.md, seed research tracker → kill
 ```
 
-## First-Run Handling
+## First-Run / New Topic Detection
 
-If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE. If Topics Queue is populated, check for remaining unprocessed items.
+If Topics Queue in tracker is empty OR all entries are `[x]`: read `topics.md`,
+scan `## TOPIC-{N}:` headers + `**Depends on:**` tags. For any topic NOT already
+in the queue, add as `- [ ] TOPIC-{N}: {title}` with appropriate metadata, and
+update Dependencies. If new topics were added, proceed to process them.
+If the queue remains empty and Research Brief exists: proceed to SCOPE.
+If Topics Queue is populated with unchecked items, check for remaining unprocessed items.
 
 ---
 
@@ -46,7 +75,8 @@ If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE.
    - What depth is needed (surface survey vs. deep dive)
    - Who is the audience (technical, executive, public)
    - What output format is expected
-4. Update tracker: `stage: explore`, log entry with scope decisions
+4. **Render a Scope Map** — output an ASCII diagram showing research domain boundaries (in-scope vs. out), key sub-domains identified, audience and depth indicators
+5. Update tracker: `stage: explore`, log entry with scope decisions
 
 ## STAGE 2: EXPLORE
 
@@ -61,7 +91,8 @@ If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE.
 ## STAGE 3: DECOMPOSE
 
 1. Find next TOPIC numbers (check existing in `00-discovery-loop/topics.md`)
-2. Break the research space into **5-15 specific topics**, each:
+2. **Render a Topic Tree** — output an ASCII decomposition tree showing all planned topics with priority markers (H/M/L), dependency arrows between topics, and estimated depth indicators (surface/moderate/deep)
+3. Break the research space into **5-15 specific topics**, each:
    - Independently researchable by a single agent
    - Specific enough to produce focused findings (not "research everything about X")
    - Clearly scoped with guiding questions
@@ -107,6 +138,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

@@ -14,6 +14,24 @@ Read `.ralph-flow/{{APP_NAME}}/01-research-loop/tracker.md` FIRST to determine w
 
 ---
 
+## Visual Communication Protocol
+
+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.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**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.
+
+---
+
 ## Tracker Lock Protocol
 
 Before ANY write to `tracker.md`, you MUST acquire the lock:
@@ -117,7 +135,8 @@ After completing ANY stage, exit: `kill -INT $PPID`
    - Note data points, statistics, quotes, and source URLs
    - If the topic requires it, explore primary sources (government sites, official reports)
 6. **Organize raw notes** — keep structured scratch notes as you research
-7. Acquire lock → update tracker: `stage: synthesize`, `last_heartbeat`, log entry → release lock
+7. **Render an Evidence Map** — output an ASCII diagram showing key findings organized by sub-theme, source quality indicators, consensus vs. disagreement areas, and gaps that need attention
+8. Acquire lock → update tracker: `stage: synthesize`, `last_heartbeat`, log entry → release lock
 8. Exit: `kill -INT $PPID`
 
 ## STAGE 2: SYNTHESIZE
@@ -128,7 +147,8 @@ After completing ANY stage, exit: `kill -INT $PPID`
    - Include specific data points, statistics, and source citations
    - Note confidence level for each key claim
    - Flag gaps — what couldn't be found, what needs primary research
-3. Acquire lock:
+3. **Render a Findings Summary** — output an ASCII status diagram showing key claims with confidence levels (H/M/L), how this topic connects to sibling topics, and gaps flagged for follow-up
+4. Acquire lock:
    - Add topic to `completed_topics` list
    - Check off topic in Topics Queue: `[x]`, set `{completed}`
    - **Unblock dependents:** for each topic in `## Dependencies` that lists the just-completed topic, check if ALL its dependencies are now in `completed_topics`. If yes, update that topic's status from `blocked` → `pending`
@@ -170,6 +190,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

@@ -12,6 +12,24 @@ Read `.ralph-flow/{{APP_NAME}}/02-story-loop/tracker.md` FIRST to determine wher
 
 ---
 
+## Visual Communication Protocol
+
+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.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**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.
+
+---
+
 ## No Findings? Wait
 
 If `findings.md` has no unprocessed findings and the tracker queue is empty/all done:
@@ -47,7 +65,8 @@ If Stories Queue in tracker is empty:
 1. Read tracker → pick next unprocessed story from queue
 2. Read ALL source findings for this story from `findings.md`
 3. Read completed stories from `stories.md` to maintain consistency and avoid repetition
-4. **Draft the narrative:**
+4. **Render a Narrative Map** — output an ASCII diagram showing source findings and how they connect to this story's theme, the narrative arc (hook → evidence → implications), and how this story relates to other completed/planned stories
+5. **Draft the narrative:**
    - Open with a compelling hook or framing question
    - Build the argument/narrative logically
    - Weave in specific data points, statistics, and evidence from findings
@@ -96,6 +115,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.