npm - ralphflow - Versions diffs - 0.5.1 → 0.5.3 - Mend

ralphflow 0.5.1 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (64) hide show

package/src/dashboard/ui/archives.js CHANGED Viewed

@@ -1,13 +1,14 @@
 // Archive browsing: listing, file tree, file viewer.
 import { state, actions } from './state.js';
-import { fetchJson, esc } from './utils.js';
+import { fetchJson, esc, renderMarkdown } from './utils.js';
 export function switchAppTab(tab) {
   if (tab === state.activeAppTab) return;
   state.activeAppTab = tab;
   state.expandedArchive = null;
   state.archiveFilesCache = {};
+  state.archiveSummaryCache = {};
   state.viewingArchiveFile = null;
   actions.renderContent();
 }
@@ -52,8 +53,21 @@ function renderArchivesView(container, appName) {
     if (isExpanded) {
       const files = state.archiveFilesCache[archive.timestamp];
       if (files) {
+        // Show summary.md prominently at top if available, otherwise show CLI hint
+        const summaryContent = state.archiveSummaryCache[archive.timestamp];
+        if (summaryContent) {
+          html += `<div class="archive-summary">${renderMarkdown(summaryContent)}</div>`;
+        } else {
+          html += `<div class="archive-summary-hint">
+            <span class="archive-summary-hint-text">No summary yet. Generate one with:</span>
+            <code class="archive-summary-hint-cmd">npx ralphflow summarize ${esc(appName)} ${esc(archive.timestamp)}</code>
+          </div>`;
+        }
+        // Filter summary.md from regular file list
+        const displayFiles = files.filter(f => f.path !== 'summary.md');
         html += '<div class="archive-files">';
-        for (const file of files) {
+        for (const file of displayFiles) {
           const isActive = state.viewingArchiveFile === file.path;
           html += `<div class="archive-file-item${isActive ? ' active' : ''}" data-archive-file="${esc(file.path)}" data-archive-ts="${esc(archive.timestamp)}">
             <span class="archive-file-icon">&#128196;</span>
@@ -129,6 +143,17 @@ async function toggleArchiveCard(appName, timestamp) {
     try {
       const files = await fetchJson(`/api/apps/${encodeURIComponent(appName)}/archives/${encodeURIComponent(timestamp)}/files`);
       state.archiveFilesCache[timestamp] = files;
+      // Auto-fetch summary.md if present
+      const hasSummary = files.some(f => f.path === 'summary.md');
+      if (hasSummary) {
+        try {
+          const data = await fetchJson(`/api/apps/${encodeURIComponent(appName)}/archives/${encodeURIComponent(timestamp)}/files/summary.md`);
+          state.archiveSummaryCache[timestamp] = data.content || '';
+        } catch {
+          // summary fetch failed — skip display
+        }
+      }
     } catch {
       state.archiveFilesCache[timestamp] = [];
     }

package/src/dashboard/ui/index.html CHANGED Viewed

@@ -9,7 +9,7 @@
 <body>
 <div class="header">
-  <h1>RalphFlow Dashboard</h1>
+  <h1 id="pageTitle">RalphFlow Dashboard</h1>
   <span class="host" id="hostDisplay"></span>
 </div>

package/src/dashboard/ui/loop-detail.js CHANGED Viewed

@@ -604,7 +604,7 @@ async function submitDeleteApp(overlay, appName) {
     if (state.selectedApp && state.selectedApp.appName === appName) {
       state.selectedApp = null;
       state.selectedLoop = null;
-      document.title = 'RalphFlow Dashboard';
+      document.title = state.projectName ? state.projectName + ' \u00b7 RalphFlow Dashboard' : 'RalphFlow Dashboard';
     }
     actions.fetchApps();
   } catch (err) {

package/src/dashboard/ui/prompt-builder.js CHANGED Viewed

@@ -67,6 +67,26 @@ export function renderPromptConfigForm(loopIdx, loop, allLoops) {
   return html;
 }
+// -----------------------------------------------------------------------
+// Visual Communication Protocol for generated prompts
+// -----------------------------------------------------------------------
+function generateVisualProtocol() {
+  let s = '';
+  s += `## Visual Communication Protocol\n\n`;
+  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.\n\n`;
+  s += `**Character set:** \`┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶\`\n\n`;
+  s += `**Diagram types to use:**\n\n`;
+  s += `- **Scope/Architecture Map** — components and their relationships in a bordered grid\n`;
+  s += `- **Decomposition Tree** — hierarchical breakdown with \`├──\` and \`└──\` branches\n`;
+  s += `- **Data Flow** — arrows (\`──→\`) showing how information moves between components\n`;
+  s += `- **Comparison Table** — bordered table for trade-offs and design options\n`;
+  s += `- **Status Summary** — bordered box with completion indicators (\`✓\` done, \`◌\` pending)\n\n`;
+  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.\n\n`;
+  s += `---\n\n`;
+  return s;
+}
 // -----------------------------------------------------------------------
 // Prompt generation engine
 // -----------------------------------------------------------------------
@@ -114,6 +134,9 @@ export function generatePromptFromConfig(loop, loopIndex, allLoops) {
   p += `**Pipeline:** \`${pipelineIn} → YOU → ${pipelineOut}\`\n\n`;
   p += `---\n\n`;
+  // ── VISUAL COMMUNICATION PROTOCOL ──
+  p += generateVisualProtocol();
   // ── MULTI-AGENT SECTIONS (conditional) ──
   if (loop.multi_agent) {
     // Tracker Lock Protocol
@@ -199,11 +222,15 @@ export function generatePromptFromConfig(loop, loopIndex, allLoops) {
   p += `After completing ANY stage, exit: \`kill -INT $PPID\`\n\n`;
   p += `---\n\n`;
-  // ── FIRST-RUN HANDLING ──
-  if (loop.multi_agent) {
-    p += `## First-Run Handling\n\n`;
+  // ── FIRST-RUN / NEW ITEM 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.\n\n`;
+    p += `## First-Run / New ${entityTitle} Detection\n\n`;
+    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.\n\n`;
+    } 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.\n\n`;
+    }
     p += `---\n\n`;
   }
@@ -248,6 +275,14 @@ export function generatePromptFromConfig(loop, loopIndex, allLoops) {
       }
     }
+    // Visual diagram trigger
+    if (i === 0) {
+      p += `${step++}. **Render a Scope Diagram** — output an ASCII architecture/scope map showing the areas this ${entityLower} touches, dependencies, and what needs to change\n`;
+    }
+    if (i === stageCount - 1 && stageCount > 1) {
+      p += `${step++}. **Render a Completion Summary** — output an ASCII status diagram showing what was built/changed, verification results, and how this ${entityLower} fits in overall progress\n`;
+    }
     // Tracker update
     if (loop.multi_agent) {
       p += `${step++}. Acquire lock → update tracker: stage, \`last_heartbeat\`, log entry → release lock\n`;

package/src/dashboard/ui/sidebar.js CHANGED Viewed

@@ -79,7 +79,7 @@ export function selectApp(app) {
   state.viewingTemplateName = null;
   state.viewingTemplateConfig = null;
   state.viewingTemplatePrompts = {};
-  document.title = app.appName + ' - RalphFlow Dashboard';
+  document.title = app.appName + ' \u00b7 ' + (state.projectName || 'RalphFlow Dashboard');
   renderSidebar();
   actions.renderContent();
   actions.fetchAppStatus(app.appName);

package/src/dashboard/ui/state.js CHANGED Viewed

@@ -4,6 +4,7 @@
 export const $ = (sel) => document.querySelector(sel);
 export const dom = {
+  pageTitle: $('#pageTitle'),
   hostDisplay: $('#hostDisplay'),
   sidebarApps: $('#sidebarApps'),
   content: $('#content'),
@@ -34,7 +35,9 @@ export const state = {
   archivesData: [],
   expandedArchive: null,
   archiveFilesCache: {},
+  archiveSummaryCache: {},
   viewingArchiveFile: null,
+  projectName: null,
   currentPage: 'app',
   templatesList: [],
   showTemplateBuilder: false,

package/src/dashboard/ui/styles.css CHANGED Viewed

@@ -1195,6 +1195,62 @@ body {
   transform: rotate(90deg);
 }
+/* Archive summary display */
+.archive-summary {
+  border-top: 1px solid var(--border);
+  padding: 16px 20px;
+  background: var(--bg);
+  font-family: var(--mono);
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--text);
+  overflow-x: auto;
+}
+.archive-summary h1,
+.archive-summary h2,
+.archive-summary h3 {
+  color: var(--text);
+  margin: 12px 0 6px;
+  font-size: 14px;
+}
+.archive-summary h1 { font-size: 15px; margin-top: 0; }
+.archive-summary .md-code-block {
+  background: var(--bg-surface);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 12px 16px;
+  margin: 8px 0;
+  overflow-x: auto;
+  white-space: pre;
+  font-size: 12px;
+  line-height: 1.5;
+}
+.archive-summary .md-code-block code {
+  font-family: var(--mono);
+}
+.archive-summary-hint {
+  border-top: 1px solid var(--border);
+  padding: 12px 20px;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-wrap: wrap;
+}
+.archive-summary-hint-text {
+  font-size: 12px;
+  color: var(--text-dim);
+}
+.archive-summary-hint-cmd {
+  font-family: var(--mono);
+  font-size: 11px;
+  color: var(--text-dim);
+  background: var(--bg);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  padding: 3px 8px;
+  user-select: all;
+}
 /* Archive file browser */
 .archive-files {
   border-top: 1px solid var(--border);
@@ -1474,6 +1530,27 @@ body {
   font-weight: 600;
   margin-bottom: 8px;
 }
+.wizard-description-ref {
+  border-left: 3px solid var(--accent);
+  padding: 8px 12px;
+  margin-bottom: 16px;
+  background: rgba(99, 102, 241, 0.06);
+  border-radius: 0 6px 6px 0;
+}
+.wizard-description-ref-label {
+  font-size: 10px;
+  text-transform: uppercase;
+  letter-spacing: 0.5px;
+  color: var(--accent);
+  font-weight: 600;
+}
+.wizard-description-ref p {
+  margin: 4px 0 0;
+  font-size: 13px;
+  color: var(--text-secondary);
+  line-height: 1.5;
+  font-style: italic;
+}
 .wizard-hint {
   font-size: 13px;
   color: var(--text-dim);

package/src/dashboard/ui/templates.js CHANGED Viewed

@@ -248,6 +248,9 @@ function renderTemplateWizard() {
   } else if (step === 1) {
     // Step 2: Define pipeline steps
     html += '<div class="wizard-step-card">';
+    if (wd.description) {
+      html += `<div class="wizard-description-ref"><span class="wizard-description-ref-label">Your description</span><p>${esc(wd.description)}</p></div>`;
+    }
     html += '<h3 class="wizard-question">Define your pipeline steps</h3>';
     html += '<p class="wizard-hint">Each step becomes a loop. For each, give it a name and optionally list its stages (comma-separated). Stages define what the AI agent does in each iteration cycle.</p>';
     html += '<div class="wizard-loops-list" id="wizardLoopsList">';

package/src/dashboard/ui/utils.js CHANGED Viewed

@@ -17,10 +17,36 @@ export function renderMarkdown(md) {
   const lines = md.split('\n');
   let inTable = false;
   let tableHtml = '';
+  let inCodeBlock = false;
+  let codeBlockContent = '';
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
+    // Fenced code blocks
+    if (line.startsWith('```')) {
+      if (inCodeBlock) {
+        html += `<pre class="md-code-block"><code>${esc(codeBlockContent)}</code></pre>`;
+        codeBlockContent = '';
+        inCodeBlock = false;
+      } else {
+        if (inTable) {
+          inTable = false;
+          tableHtml += '</tbody></table>';
+          html += tableHtml;
+          tableHtml = '';
+        }
+        inCodeBlock = true;
+        codeBlockContent = '';
+      }
+      continue;
+    }
+    if (inCodeBlock) {
+      codeBlockContent += (codeBlockContent ? '\n' : '') + line;
+      continue;
+    }
     // Table detection
     if (line.match(/^\|.+\|$/)) {
       if (!inTable) {
@@ -68,6 +94,10 @@ export function renderMarkdown(md) {
     html += tableHtml;
   }
+  if (inCodeBlock) {
+    html += `<pre class="md-code-block"><code>${esc(codeBlockContent)}</code></pre>`;
+  }
   return html;
 }

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

@@ -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)

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

@@ -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

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

@@ -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?

package/src/templates/code-review/loops/00-collect-loop/changesets.md ADDED Viewed

@@ -0,0 +1,3 @@
+# Changesets
+<!-- Populated by the Collect Loop -->