@arjunkhera/atlas 0.3.21 → 0.3.24

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.21",
+  "version": "0.3.24",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, for any repository.",
   "author": {
     "name": "Arjun Khera"

package/agents/artifact-renderer.md

@@ -47,6 +47,8 @@ are in `${CLAUDE_PLUGIN_ROOT}/skills/sdlc-task/design/README.md`, under
 - A step has a title and one or two sentences. The reader sets the pace.
   The figure prints as stills, and it works with its script removed.
 - Meaning is never by colour alone.
+- A figure for a story walks the story: it draws each step in order, so
+  the reader sees the flow move. The check fails a story with no such figure.
 - Close every tag. `atlas design check <folder>` flags a figure that does
   not.
 

package/door/lib/design.mjs

@@ -5,12 +5,22 @@
 //
 // The check flags what a script can see: a needed part that is missing or
 // empty, a state line (state lives in the tracker), a code with no row in
-// the Key, a part the registry does not know, and a figure whose tags do not
-// close. It proves the shape, not the quality. It never rewrites a word.
+// the Key, a part the registry does not know, a figure whose tags do not
+// close or that woodcut cannot draw, and a part with no picture where the
+// registry asks for one. It proves the shape, not the quality. It never
+// rewrites a word.
+//
+// Pictures are needed (owner, 21 October 2026): "any user is a visual
+// person, they need to see things flowing to make sense of it." The `picture`
+// key in parts.yaml says which part needs one figure, and that each story
+// needs a walkthrough figure and a worked example.
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, dirname, resolve, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { parseYaml, insideRepo } from '../../shape/check.mjs';
+import { WOODCUT_TYPES, fenceOpens, fenceCloses } from './markdown.mjs';
+
+export { WOODCUT_TYPES };
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
 export const PARTS_FILE = join(PACKAGE_ROOT, 'skills', 'sdlc-task', 'design', 'parts.yaml');
@@ -20,6 +30,11 @@ export const NEEDS = Object.freeze(['needed', 'optional', 'none', 'shared']);
 export const DESIGN_KEYS = Object.freeze(['title', 'item', 'product', 'kinds', 'shared', 'look']);
 export const STATE_KEYS = Object.freeze(['status', 'state', 'stage', 'approved', 'locked', 'lock', 'shipped', 'delivered']);
 export const PART_KEYS = Object.freeze(['part', 'title']);
+// What a part's `picture` key may say: `one` means the part holds at least one
+// figure; `each-story` means each story holds a walkthrough figure and a
+// worked example.
+export const PICTURES = Object.freeze(['one', 'each-story']);
+
 
 // A code: capitals then a number, such as M1, A1.7, US-3 or D-6. Common
 // technical names that look like codes are not codes.
@@ -48,6 +63,7 @@ export function loadRegistry(path = PARTS_FILE) {
   const data = parseYaml(readFileSync(path, 'utf8'));
   const kinds = data.kinds.map((one) => one.id);
   for (const part of data.parts) {
+    if (part.picture !== undefined && !PICTURES.includes(part.picture)) throw new Error(`${basename(path)}: part "${part.id}" has picture "${part.picture}"; use ${PICTURES.join(' or ')}`);
     for (const kind of kinds) {
       if (!NEEDS.includes(part[kind])) throw new Error(`${basename(path)}: part "${part.id}" has no valid "${kind}" value; use ${NEEDS.join(', ')}`);
     }
@@ -103,9 +119,9 @@ function scanLines(body, firstLine) {
   let fence = null;
   body.split('\n').forEach((text, index) => {
     const line = firstLine + index;
-    const open = text.match(/^\s*```+\s*(\S*)(?:\s+(\S+))?/);
-    if (open && !fence) { fence = { info: open[1], type: open[2] ?? null, line, lines: [] }; return; }
-    if (fence && /^\s*```+\s*$/.test(text)) { if (fence.info === 'figure' || fence.info === 'woodcut') figures.push(fence); fence = null; return; }
+    if (fence && fenceCloses(text, fence.mark)) { if (fence.info === 'figure' || fence.info === 'woodcut') figures.push(fence); fence = null; return; }
+    const mark = !fence && fenceOpens(text);
+    if (mark) { const [info, type] = text.trim().slice(mark.length).trim().split(/\s+/); fence = { mark, info: info ?? '', type: type ?? null, line, lines: [] }; return; }
     if (fence) { fence.lines.push(text); return; }
     prose.push({ text, line });
   });
@@ -143,6 +159,175 @@ export function figureFault(html) {
   return stack.length ? `<${stack[stack.length - 1]}> does not close` : null;
 }
 
+// Why woodcut cannot draw this figure, or null. It reads the shape the
+// renderer reads: a viewBox, the lists the type draws, the fields each entry
+// needs, and the ids each step names. Any other throw is a finding too: a
+// figure the check cannot read is a figure the page cannot draw.
+export function woodcutFault(type, data) {
+  try { return woodcutShapeFault(type, data); } catch (error) { return `woodcut cannot read the figure data: ${error.message}`; }
+}
+
+const isObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+// A list the renderer walks: absent is an empty list; anything else must be
+// an array of objects.
+function listOf(v, key) {
+  if (v[key] === undefined) return { list: [] };
+  if (!Array.isArray(v[key])) return { fault: `"${key}" must be a list` };
+  if (!v[key].every(isObject)) return { fault: `each entry of "${key}" must be an object` };
+  return { list: v[key] };
+}
+
+function woodcutShapeFault(type, data) {
+  const shape = WOODCUT_TYPES[type];
+  if (!shape) return `woodcut has no figure "${type}", so the page draws nothing; use ${Object.keys(WOODCUT_TYPES).join(', ')}, or draw your own in a \`figure\` block`;
+  if (!isObject(data)) return 'the woodcut data is not one JSON object';
+  if (data.variants !== undefined && !Array.isArray(data.variants)) return 'the woodcut "variants" must be a list';
+  const variants = data.variants ?? [data];
+  if (!variants.length) return 'the woodcut "variants" list is empty';
+  for (const [n, v] of variants.entries()) {
+    const at = variants.length > 1 ? ` in variant ${n + 1}` : '';
+    if (!isObject(v)) return `variant ${n + 1} is not an object`;
+    if (!Array.isArray(v.viewBox) || v.viewBox.length !== 2 || !v.viewBox.every(Number.isFinite)) return `the woodcut data needs "viewBox": [width, height]${at}`;
+    const lists = {};
+    for (const key of [shape.needs, ...shape.ids, ...(shape.more ?? []), 'scenarios']) {
+      const { list, fault } = listOf(v, key);
+      if (fault) return fault + at;
+      lists[key] = list;
+    }
+    if (!lists[shape.needs].length) return `a ${type} needs a non-empty "${shape.needs}" list${at}`;
+    if (lists[shape.needs].some((one) => one.id === undefined)) return `each entry of "${shape.needs}" needs an "id"${at}`;
+    const fault = elementFault(type, v, lists);
+    if (fault) return fault + at;
+    const ids = new Set(shape.ids.flatMap((key) => lists[key].map((one) => one.id)).filter((id) => id !== undefined));
+    if (type === 'wc-state-machine' && v.start) ids.add('start');
+    for (const sc of lists.scenarios) {
+      if (!Array.isArray(sc.steps)) return `the scenario "${sc.name ?? sc.id ?? '?'}" needs a "steps" list${at}`;
+      for (const step of sc.steps) {
+        if (!isObject(step)) return `each step of the scenario "${sc.name ?? sc.id ?? '?'}" must be an object${at}`;
+        for (const key of ['active', 'denied']) if (step[key] !== undefined && !Array.isArray(step[key])) return `a step's "${key}" must be a list of ids${at}`;
+        for (const id of [...(step.active ?? []), ...(step.denied ?? [])]) {
+          if (!ids.has(id)) return `a step names "${id}", which is not an element of the figure${at}`;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+// The fields each element needs, or the renderer throws and the figure stays
+// blank: a place for each box, the points of each line, and a place for each
+// label on a line.
+const num = (value) => Number.isFinite(value);
+const pair = (value) => Array.isArray(value) && value.length === 2 && value.every(num);
+function elementFault(type, v, lists) {
+  const name = (one) => `"${one.id ?? one.label ?? '?'}"`;
+  if (type === 'wc-sequence') {
+    const actors = new Set(lists.actors.map((one) => one.id));
+    for (const a of lists.actors) if (!num(a.x)) return `the actor ${name(a)} needs a number "x"`;
+    for (const m of lists.messages) {
+      if (!num(m.y)) return `the message ${name(m)} needs a number "y"`;
+      if (!actors.has(m.from) || !actors.has(m.to)) return `the message ${name(m)} names an actor that is not in "actors"`;
+    }
+    for (const act of lists.activations) if (!actors.has(act.actor) || !num(act.y1) || !num(act.y2)) return `each activation needs an "actor" from "actors" and numbers "y1" and "y2"`;
+    return null;
+  }
+  if (type === 'wc-state-machine') {
+    for (const st of lists.states) if (![st.x, st.y, st.w, st.h].every(num)) return `the state ${name(st)} needs numbers "x", "y", "w" and "h"`;
+    for (const t of lists.transitions) {
+      if (typeof t.path !== 'string' || !pair(t.tip) || !pair(t.tipDir)) return `the transition ${name(t)} needs "path", "tip": [x, y] and "tipDir": [dx, dy]`;
+      if (t.label && !pair(t.labelAt)) return `the transition ${name(t)} has a label, so it needs "labelAt": [x, y]`;
+    }
+    if (v.start !== undefined && !(isObject(v.start) && pair(v.start.at))) return 'the start needs "at": [x, y]';
+    return null;
+  }
+  for (const n of lists.nodes) {
+    if (n.shape === 'end' ? ![n.x, n.y].every(num) : ![n.x, n.y, n.w, n.h].every(num)) return `the node ${name(n)} needs numbers "x", "y", "w" and "h"`;
+    if (n.shape === 'end' && n.label && !pair(n.labelAt)) return `the end node ${name(n)} has a label, so it needs "labelAt": [x, y]`;
+  }
+  for (const e of lists.edges) {
+    const fewest = e.noTip ? 1 : 2;
+    if (!Array.isArray(e.points) || e.points.length < fewest || !e.points.every(pair)) return `the edge ${name(e)} needs "points": ${fewest === 1 ? 'one or more' : 'two or more'} [x, y] pairs`;
+    if (e.label && !pair(e.labelAt)) return `the edge ${name(e)} has a label, so it needs "labelAt": [x, y]`;
+  }
+  for (const lane of lists.lanes) if (![lane.y1, lane.y2].every(num)) return `the lane "${lane.label ?? '?'}" needs numbers "y1" and "y2"`;
+  for (const g of lists.groups) if (![g.x, g.y, g.w, g.h].every(num)) return `the group "${g.label ?? '?'}" needs numbers "x", "y", "w" and "h"`;
+  return null;
+}
+
+// A woodcut figure walks when one of its scenarios has two or more steps and
+// each step has a title: the reader steps through it, and the panel tells
+// what happens at each step. It runs only on data that woodcutFault passed.
+export function woodcutWalks(data) {
+  const variants = Array.isArray(data?.variants) ? data.variants : [data];
+  return variants.some((v) => (v?.scenarios ?? []).some((sc) => Array.isArray(sc.steps) && sc.steps.length >= 2 && sc.steps.every((step) => step && step.title)));
+}
+
+// A custom figure counts as a picture when it draws: an SVG shape, or HTML
+// with at least three elements. An empty <svg> or a line of text is not one.
+const SHAPE = /<(?:rect|circle|ellipse|path|line|polyline|polygon|text|image)\b/i;
+export function figureDraws(html) {
+  const text = html.replace(/<!--[\s\S]*?-->/g, '');
+  return SHAPE.test(text) || (text.match(/<[a-zA-Z][\w-]*\b/g)?.length ?? 0) >= 3;
+}
+
+// A story heading carries a code, such as "### US-1: a test goes red". The
+// stories are the coded headings at the level of the first one; a deeper
+// heading, or an uncoded heading such as "## Overview", stays inside the story
+// before it. HTML comments and fenced blocks hold no stories.
+const STORY_CODE = /(?<![\w./-])[A-Z]{1,4}-?\d+(?:\.\d+)*(?![\w/-])/;
+function storiesOf(body, firstLine) {
+  const rows = [];
+  let fence = null;
+  let comment = false;
+  body.split('\n').forEach((text, index) => {
+    const line = firstLine + index;
+    if (fence) { if (fenceCloses(text, fence)) fence = null; rows.push({ text, line }); return; }
+    const open = fenceOpens(text);
+    if (open) { fence = open; rows.push({ text, line }); return; }
+    if (comment) { if (text.includes('-->')) comment = false; rows.push({ text, line }); return; }
+    if (/^\s*<!--/.test(text) && !text.includes('-->')) { comment = true; rows.push({ text, line }); return; }
+    const heading = text.match(/^(#{2,6})\s+(.*)$/);
+    rows.push({ text, line, heading: heading && STORY_CODE.test(heading[2].replace(/`[^`]*`/g, '')) ? { level: heading[1].length, name: heading[2].trim() } : null });
+  });
+  const level = rows.find((row) => row.heading)?.heading.level;
+  const stories = [];
+  for (const row of rows) {
+    if (row.heading && row.heading.level === level) stories.push({ name: row.heading.name, line: row.line, lines: [] });
+    else if (stories.length) stories[stories.length - 1].lines.push(row.text);
+  }
+  return stories;
+}
+
+// A worked example: a label that names the input and one that names the
+// output, such as "**Input:** ..." and "**Output:** ...". "Ask" and "Answer",
+// "Given" and "Result" count too, and so does a table with Input and Output
+// columns.
+const LABEL = (words) => new RegExp(`(?:^|[^\\w])(?:\\*\\*|__)?(?:${words})(?:\\*\\*|__)?\\s*(?::|—|–)|(?:\\*\\*|__)(?:${words})[:.](?:\\*\\*|__)|^\\s*\\|.*\\b(?:${words})\\b.*\\|`, 'i');
+const EXAMPLE_INPUT = LABEL('inputs?|ask|given|example input');
+const EXAMPLE_OUTPUT = LABEL('outputs?|answer|result|example output');
+// A part that says "No change" and why needs no picture, as the empty rule allows.
+const NO_CHANGE = /^\s*(?:#{1,6}\s.*\n\s*)*(?:\*\*|__)?no change\b/i;
+
+function pictureFindings(one, rule, figures, finding) {
+  if (NO_CHANGE.test(one.body)) return;
+  const drawn = figures.filter((figure) => !figure.open && !figure.fault && (figure.info !== 'figure' || figureDraws(figure.lines.join('\n'))));
+  if (rule === 'one') {
+    if (!drawn.length) finding(one.file, one.bodyLine, 'picture', `part "${one.part}" needs a figure; a reader must see it, not only read it. Add a \`woodcut\` or a \`figure\` block`);
+    return;
+  }
+  const stories = storiesOf(one.body, one.bodyLine);
+  if (!stories.length) { finding(one.file, one.bodyLine, 'picture', 'write each story under a heading with its code, such as "### US-1: a test goes red", with a walkthrough figure and a worked example'); return; }
+  for (const story of stories) {
+    const inside = drawn.filter((figure) => figure.line > story.line && figure.line <= story.line + story.lines.length);
+    const walks = inside.some((figure) => figure.info === 'figure' || figure.walks);
+    if (!walks) finding(one.file, story.line, 'picture', `the story "${story.name}" needs a walkthrough figure: a woodcut figure with a scenario whose steps each have a title, or a figure of your own`);
+    const words = story.lines;
+    if (!words.some((line) => EXAMPLE_INPUT.test(line)) || !words.some((line) => EXAMPLE_OUTPUT.test(line))) {
+      finding(one.file, story.line, 'picture', `the story "${story.name}" needs a worked example: an "Input:" line and an "Output:" line with real values`);
+    }
+  }
+}
+
 export function checkDesign(design, registry = loadRegistry()) {
   const findings = [];
   const finding = (file, line, rule, why) => findings.push({ file, line, rule, why });
@@ -196,10 +381,17 @@ export function checkDesign(design, registry = loadRegistry()) {
       let fault = figure.open ? 'the figure block does not close' : null;
       if (!fault && figure.info === 'woodcut') {
         if (!/^wc-[a-z-]+$/.test(figure.type ?? '')) fault = 'a woodcut block names its figure type, such as "woodcut wc-flowchart"';
-        else { try { JSON.parse(figure.lines.join('\n')); } catch (error) { fault = `the woodcut data is not JSON: ${error.message}`; } }
+        else {
+          let data;
+          try { data = JSON.parse(figure.lines.join('\n')); } catch (error) { fault = `the woodcut data is not JSON: ${error.message}`; }
+          if (!fault) fault = woodcutFault(figure.type, data);
+          if (!fault) figure.walks = woodcutWalks(data);
+        }
       } else if (!fault) fault = figureFault(figure.lines.join('\n'));
-      if (fault) finding(one.file, figure.line, 'figure', fault);
+      if (fault) { figure.fault = fault; finding(one.file, figure.line, 'figure', fault); }
     }
+    const picture = registry.byId.get(one.part).picture;
+    if (picture && !isEmpty(one.body)) pictureFindings(one, picture, figures, finding);
   }
   for (const [id, { need, by }] of needs) {
     if (need === 'needed' && !seen.has(id)) {

package/door/lib/markdown.mjs

@@ -6,6 +6,31 @@
 //
 // No dependencies. The text is the repo's own; a custom figure is trusted
 // the same way a page in the repo is.
+// The figure types that woodcut 0.4.0 defines (WOODCUT in design-build.mjs), and the list each one cannot
+// draw without. A name outside this map is an element the browser does not
+// know, so it draws nothing. The ids lists name the arrays whose ids a
+// walkthrough step may name.
+export const WOODCUT_TYPES = Object.freeze({
+  'wc-block-diagram': { needs: 'nodes', ids: ['nodes', 'edges', 'groups'], more: ['lanes'] },
+  'wc-flowchart': { needs: 'nodes', ids: ['nodes', 'edges', 'groups'], more: ['lanes'] },
+  'wc-swimlane': { needs: 'nodes', ids: ['nodes', 'edges', 'groups'], more: ['lanes'] },
+  'wc-sequence': { needs: 'actors', ids: ['actors', 'messages'], more: ['activations'] },
+  'wc-state-machine': { needs: 'states', ids: ['states', 'transitions'] },
+});
+
+// One fence rule for every reader of a page (the check, this renderer and
+// atlas ste), as CommonMark has it: a fence opens with three or more of one
+// mark, and closes only on a run of the same mark at least as long, with
+// nothing after it. So a ```` block may hold a ``` block.
+export function fenceOpens(line) {
+  const match = /^\s*(`{3,}|~{3,})/.exec(line);
+  return match ? match[1] : null;
+}
+export function fenceCloses(line, mark) {
+  const match = /^\s*(`{3,}|~{3,})\s*$/.exec(line);
+  return Boolean(match) && match[1][0] === mark[0] && match[1].length >= mark.length;
+}
+
 export const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 export const slug = (text) => String(text).toLowerCase().replace(/<[^>]+>/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
 
@@ -60,16 +85,19 @@ export function render(body, ctx) {
   };
   while (i < lines.length) {
     const line = lines[i];
-    const fence = line.match(/^\s*```+\s*(.*)$/);
-    if (fence) {
+    const mark = fenceOpens(line);
+    if (mark) {
       flush();
-      const info = fence[1].trim();
+      const info = line.trim().slice(mark.length).trim();
       const buf = [];
       i += 1;
-      while (i < lines.length && !/^\s*```+\s*$/.test(lines[i])) buf.push(lines[i++]);
+      while (i < lines.length && !fenceCloses(lines[i], mark)) buf.push(lines[i++]);
       i += 1;
       const woodcut = info.match(/^woodcut\s+(wc-[a-z-]+)/);
-      if (woodcut) {
+      if (woodcut && !WOODCUT_TYPES[woodcut[1]]) {
+        // A draft page shows the fault where the figure should be, never a blank.
+        out.push(`<p class="draft">This figure does not draw: woodcut has no figure "${esc(woodcut[1])}". Run atlas design check.</p>`);
+      } else if (woodcut) {
         let data;
         try { data = JSON.parse(buf.join('\n')); } catch (error) { throw new Error(`${ctx.file}: bad woodcut JSON in ${woodcut[1]}: ${error.message}`); }
         ctx.figures.push(woodcut[1]);

package/door/lib/ste.mjs

@@ -13,6 +13,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { dirname, extname, join, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { privacyFindings, loadPrivateTerms } from './privacy.mjs';
+import { fenceOpens, fenceCloses } from './markdown.mjs';
 
 export const LIMITS = Object.freeze({ step: 20, sentence: 25, paragraph: 6 });
 
@@ -64,9 +65,10 @@ export function markdownUnits(text) {
   for (; index < lines.length; index += 1) {
     const line = lines[index];
     const number = index + 1;
-    const fenceMark = /^\s*(```|~~~)/.exec(line);
-    if (fence) { if (fenceMark && fenceMark[1] === fence) fence = null; continue; }
-    if (fenceMark) { close(); fence = fenceMark[1]; continue; }
+    // The fence rule of the design renderer: a ```` block may hold a ``` block.
+    if (fence) { if (fenceCloses(line, fence)) fence = null; continue; }
+    const mark = fenceOpens(line);
+    if (mark) { close(); fence = mark; continue; }
     if (!line.trim()) { close(); continue; }
     if (/^\s*>/.test(line)) { close(); continue; }
     if (comment) { if (line.includes('-->')) comment = false; continue; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arjunkhera/atlas",
-  "version": "0.3.21",
+  "version": "0.3.24",
   "description": "Atlas: the delivery lifecycle, its crews and the Atlas tools, as a Claude Code plugin for any repository.",
   "type": "module",
   "license": "UNLICENSED",

package/skills/sdlc-task/SKILL.md

@@ -38,7 +38,7 @@ checks and the transition log; each verb's own description says what it needs.
 | Ask the owner something, or record the answer | `question_ask`, `question_answer` |
 | Record a decision in the owner's words | `decision_record` |
 | Mark it delivered, or reopen it | `item_done`, `item_reopen` |
-| Say where things stand | `where_are_we`, `in_flight`, `needs_me` |
+| Say where things stand | `roundup` for a whole product; `where_are_we`, `in_flight`, `needs_me` for one question |
 
 The repo's own facts come from `atlas.yaml` and `atlas/`. Its kinds (`service`,
 `library`, `schema`, `cli`, `plugin`) decide which procedures it has and what
@@ -114,7 +114,8 @@ A lock is the owner's approval of a short design.
    shows in bold at the top.
 2. **Show the design's page before you ask.** Run
    `atlas design check <folder>` and `atlas ste` on the folder, and fix each
-   finding by hand. A part that needs a custom figure goes to the
+   finding by hand. The check needs pictures, as `design/README.md`
+   "Figures" says. A part that needs a custom figure goes to the
    `atlas:artifact-renderer` crew first. Run
    `atlas design build <folder> --tracker <item.json>`, with the tracker
    data that `design/README.md` names. Run `atlas ste` on the page and

package/skills/sdlc-task/design/README.md

@@ -90,12 +90,10 @@ gets. The kind sets which parts the design has. The two are separate: an
 initiative-tier piece of work can be a Decide design, and an Initiative
 design holds a family of designs.
 
-At initiative tier, a Decide design goes deep:
-
-1. The Problem today part has a figure of today. The Proposal part has a
-   figure of the target.
-2. At least two options get full depth in Alternatives: their costs, their
-   risks and why each one lost.
+At every tier, the Problem today part has a figure of today and the
+Proposal part has a figure of the target. At initiative tier, a Decide
+design also goes deep. At least two options get full depth in
+Alternatives: their costs, their risks and why each one lost.
 
 At standard tier, one chosen approach and one rejected option are enough.
 
@@ -167,18 +165,48 @@ Without the key, the design folder is `docs/design-docs`.
    An empty part fails the check.
 4. Put every code you use, such as `US-3` or `M1`, in the Key.
 5. Never write a state line, such as "Status: approved". The check flags it.
+6. Draw the parts that the Figures section names. The check fails a part
+   with no figure where one is needed.
 
 ## Figures
 
-1. Use a woodcut figure when a stock figure fits: a flow chart, a sequence,
-   a state machine or swim lanes. Use a fenced block with the info string
-   `woodcut wc-<type>`. It holds the figure data as JSON, in the woodcut
-   shape.
-2. Draw your own figure when the subject has its own shape. Git lanes, a
+A reader must see the design move, not only read it (owner, 21 October
+2026: "any user is a visual person, they need to see things flowing to make
+sense of it"). The check enforces it. The `picture` key in
+[parts.yaml](parts.yaml) says where:
+
+| Part | The check needs |
+|---|---|
+| Summary | One figure. |
+| Problem today | One figure of today. |
+| Proposal | One figure of the target. |
+| States | One state figure. |
+| Stories | For each story: a walkthrough figure, and a worked example with real values. The example has an `Input:` label and an `Output:` label. `Ask` and `Answer`, or a table with Input and Output columns, also count. |
+
+A story starts at a heading that holds its code, such as
+`### US-1: a test goes red`. A deeper heading stays inside the story. A part
+that says "No change" and why needs no figure.
+
+A walkthrough figure is a woodcut figure with a scenario of two or more
+steps, each with a title and one or two sentences. The reader clicks or
+presses the arrow keys, and each step lights up the part that moves. A
+figure of your own also counts.
+
+1. Use a woodcut figure when a stock figure fits. Use a fenced block with
+   the info string `woodcut <type>`. It holds the figure data as JSON.
+   The template for Stories has a full example.
+2. Pick the type by its question. `wc-sequence`: in what order?
+   `wc-swimlane`: who does it? `wc-flowchart`: which way?
+   `wc-state-machine`: what state is it in? `wc-block-diagram`: what are
+   the parts?
+3. Any other type name draws nothing, so the check refuses it. The check
+   also refuses data that the figure cannot draw. Examples are a missing
+   `viewBox`, a box with no place and a line with no points.
+4. Draw your own figure when the subject has its own shape. Git lanes, a
    time line and a data diff are examples. Use a fenced block with the info
    string `figure`. It holds the HTML. Use the page tokens, such as
    `var(--accent)` and `var(--line)`, so the figure works in both themes.
-3. Both kinds follow the same rules. A step has a title and one or two
+5. Both kinds follow the same rules. A step has a title and one or two
    sentences. The reader sets the pace. The figure prints as stills.
    Meaning is never by colour alone.
 

package/skills/sdlc-task/design/parts/problem.md

@@ -8,7 +8,8 @@ Rules:
 
 1. Say what happens today, with one real example.
 2. Cite the source: a pull request, an issue or a log line.
-3. Do not propose a fix here.
+3. Draw today with a figure. The check fails the part with no figure.
+4. Do not propose a fix here.
 
 Example, in a file of its own:
 
@@ -19,4 +20,20 @@ part: problem
 # Problem today
 
 Today the tests run after the merge. On 2 October pull request 88 merged, and its tests went red one hour later.
+
+```woodcut wc-flowchart
+{
+  "label": "Today: the tests run after the merge",
+  "viewBox": [460, 70],
+  "nodes": [
+    { "id": "pr", "x": 10, "y": 18, "w": 110, "h": 34, "label": "Pull request", "shape": "pill" },
+    { "id": "merge", "x": 175, "y": 18, "w": 110, "h": 34, "label": "Merge" },
+    { "id": "tests", "x": 340, "y": 18, "w": 110, "h": 34, "label": "Tests: red", "kind": "accent" }
+  ],
+  "edges": [
+    { "id": "e1", "points": [[120, 35], [173, 35]] },
+    { "id": "e2", "points": [[285, 35], [338, 35]] }
+  ]
+}
+```
 ````

package/skills/sdlc-task/design/parts/proposal.md

@@ -8,7 +8,7 @@ Rules:
 
 1. Name the option we pick, and say how it works in steps.
 2. Give a worked example: the input, the process and the output.
-3. Link the figure that shows it.
+3. Draw the target with a figure. The check fails the part with no figure.
 
 Example, in a file of its own:
 
@@ -18,7 +18,35 @@ part: proposal
 ---
 # Proposal
 
+The tests run before the merge.
+
+```woodcut wc-flowchart
+{
+  "label": "Target: the tests run before the merge",
+  "viewBox": [460, 70],
+  "nodes": [
+    { "id": "pr", "x": 10, "y": 18, "w": 110, "h": 34, "label": "Pull request", "shape": "pill" },
+    { "id": "tests", "x": 175, "y": 18, "w": 110, "h": 34, "label": "Tests", "kind": "accent" },
+    { "id": "merge", "x": 340, "y": 18, "w": 110, "h": 34, "label": "Merge" }
+  ],
+  "edges": [
+    { "id": "e1", "points": [[120, 35], [173, 35]] },
+    { "id": "e2", "points": [[285, 35], [338, 35]], "label": "green only", "labelAt": [311, 12] }
+  ],
+  "scenarios": [{
+    "name": "Pull request 88",
+    "steps": [
+      { "title": "A pull request opens", "body": "Pull request 88 changes src/pay.mjs.", "active": ["pr"] },
+      { "title": "The gate runs the tests", "body": "The test pay rounds down goes red.", "active": ["e1", "tests"] },
+      { "title": "The merge waits", "body": "Only a green run opens the merge.", "active": ["e2", "merge"] }
+    ]
+  }]
+}
+```
+
 1. A pull request opens.
 2. The gate runs the tests on its head.
 3. A red test blocks the merge button.
+
+Input: pull request 88 with one failing test. Output: the merge button stays grey.
 ````

package/skills/sdlc-task/design/parts/states.md

@@ -8,7 +8,7 @@ Rules:
 
 1. List the states a thing moves through.
 2. Say what moves it from each state to the next.
-3. Draw it as a state figure.
+3. Draw it as a state figure. The check fails the part with no figure.
 
 Example, in a file of its own:
 
@@ -18,6 +18,22 @@ part: states
 ---
 # States
 
+```woodcut wc-state-machine
+{
+  "label": "A test run",
+  "viewBox": [440, 90],
+  "states": [
+    { "id": "waiting", "x": 10, "y": 30, "w": 100, "h": 32, "label": "Waiting" },
+    { "id": "running", "x": 170, "y": 30, "w": 100, "h": 32, "label": "Running" },
+    { "id": "red", "x": 330, "y": 30, "w": 100, "h": 32, "label": "Red", "terminal": true }
+  ],
+  "transitions": [
+    { "id": "start", "path": "M 110 46 L 168 46", "tip": [168, 46], "tipDir": [1, 0], "label": "tests start", "labelAt": [139, 22] },
+    { "id": "fail", "path": "M 270 46 L 328 46", "tip": [328, 46], "tipDir": [1, 0], "label": "a test fails", "labelAt": [299, 22] }
+  ]
+}
+```
+
 | From | Event | To |
 |---|---|---|
 | Waiting | The tests start | Running |

package/skills/sdlc-task/design/parts/stories.md

@@ -6,9 +6,18 @@ Needs: Decide: optional, Flow: needed, Contract: optional, Initiative: none.
 
 Rules:
 
-1. Write one walkthrough for each story, step by step.
-2. Each step has a title and one or two sentences.
-3. Give each story a code, such as `US-1`, and put the code in the Key.
+1. Write each story under its own heading, with a code, such as `US-1`.
+   Put the code in the Key.
+2. Give each story a walkthrough figure. The reader steps through it and
+   sees what moves at each step. Use a woodcut figure with a scenario. Give
+   each step a title and one or two sentences. A figure of your own also
+   counts. The check fails a story with no walkthrough figure.
+3. Give each story a worked example with real values: an `Input:` line, the
+   steps, and an `Output:` line. The check fails a story with no worked
+   example.
+4. Pick the figure by the question it answers: `wc-sequence` for "in what
+   order", `wc-swimlane` for "who does it", `wc-flowchart` for "which
+   way", `wc-state-machine` for "what state is it in".
 
 Example, in a file of its own:
 
@@ -20,7 +29,36 @@ part: stories
 
 ### US-1: a test goes red
 
-1. The lead opens a pull request.
-2. The gate runs the tests, and one goes red.
+**Input:** pull request 88 changes `src/pay.mjs`. The test `pay rounds down` fails on it.
+
+```woodcut wc-sequence
+{
+  "label": "US-1: a test goes red",
+  "viewBox": [460, 190],
+  "actors": [
+    { "id": "lead", "x": 70, "label": "Lead" },
+    { "id": "gate", "x": 230, "label": "Gate" },
+    { "id": "owner", "x": 390, "label": "Owner" }
+  ],
+  "messages": [
+    { "id": "open", "from": "lead", "to": "gate", "y": 70, "label": "open pull request 88" },
+    { "id": "red", "from": "gate", "to": "lead", "y": 110, "label": "1 test red", "kind": "return" },
+    { "id": "block", "from": "gate", "to": "owner", "y": 150, "label": "merge blocked" }
+  ],
+  "scenarios": [{
+    "name": "US-1",
+    "steps": [
+      { "title": "The lead opens a pull request", "body": "Pull request 88 changes src/pay.mjs.", "active": ["lead", "open"] },
+      { "title": "The gate runs the tests", "body": "The test pay rounds down fails.", "active": ["gate", "red"] },
+      { "title": "The owner sees the block", "body": "The merge button stays grey and names the failing check.", "active": ["owner", "block"] }
+    ]
+  }]
+}
+```
+
+1. The lead opens pull request 88.
+2. The gate runs the tests, and `pay rounds down` goes red.
 3. The merge button stays blocked, and the owner sees the failing check.
+
+**Output:** the merge button is grey. The check list shows `pay rounds down: failed`.
 ````

package/skills/sdlc-task/design/parts/summary.md

@@ -7,7 +7,8 @@ Needs: Decide: needed, Flow: needed, Contract: needed, Initiative: needed.
 Rules:
 
 1. Lead with the answer: what changes, for whom, and why now.
-2. Keep it to two short paragraphs and one picture.
+2. Keep it to two short paragraphs and one picture. The check fails a
+   Summary with no figure.
 3. A reader who stops here knows the whole design.
 
 Example, in a file of its own:

package/skills/sdlc-task/design/parts.yaml

@@ -12,6 +12,13 @@
 #   none      the kind does not use it
 #   shared    needed when design.yaml says `shared: true`, optional when not
 #
+# A part may say what picture it needs (owner, 21 October 2026: "any user is
+# a visual person, they need to see things flowing to make sense of it"):
+#   picture: one          the part holds at least one figure that draws
+#   picture: each-story   each story holds a walkthrough figure and a worked
+#                         example, with an Input line and an Output line
+# The check reads it whenever the part is in the folder.
+#
 # A design keeps no state. The tracker parts at the end are read from the
 # tracker at build time. No part file may hold them.
 
@@ -50,6 +57,7 @@ parts:
     name: Summary
     group: start
     holds: The answer in a few lines, and one picture.
+    picture: one
     decide: needed
     flow: needed
     contract: needed
@@ -75,6 +83,7 @@ parts:
     name: Problem today
     group: decide
     holds: What happens today, with a real example.
+    picture: one
     decide: needed
     flow: optional
     contract: optional
@@ -91,6 +100,7 @@ parts:
     name: Proposal
     group: decide
     holds: The option we pick, and how it works.
+    picture: one
     decide: needed
     flow: none
     contract: none
@@ -132,6 +142,7 @@ parts:
     name: Stories
     group: flow
     holds: One walkthrough for each story, step by step.
+    picture: each-story
     decide: optional
     flow: needed
     contract: optional
@@ -156,6 +167,7 @@ parts:
     name: States
     group: flow
     holds: The states a thing moves through, and what moves it.
+    picture: one
     decide: none
     flow: optional
     contract: none

package/work/lib/roundup.mjs

@@ -0,0 +1,206 @@
+// The roundup: where one product stands, and where it is going (target design
+// flow 9). Tracker item b1610d9b moved it forward from stage 4 (decision
+// 3c268725).
+//
+// It joins the reads that ship already and adds no store:
+//   1. Needs you        the same read as needs_me
+//   2. Where we stand   items tagged stage-<n>, in ladder order, and a count of
+//                       every item of the product by lifecycle
+//   3. What moved       delivery marks, merged pull requests and new items in
+//                       the window
+//   4. Stuck or drifting active items with no change for STUCK_DAYS, merged
+//                       but not marked, open pull requests that name no item,
+//                       and questions that wait longer than STUCK_DAYS
+//   5. Trend            per week, for TREND_WEEKS weeks: merges, deliveries,
+//                       new items; and the open questions with the oldest age
+// Every row carries a citation: an item id, a question id or a pull request
+// URL. It is computed at read time and never stored.
+import { refuse, isoDate, LIVE_LIFECYCLES } from './verb-fields.mjs';
+import { oneLine, ROW_LINE_MAX } from './questions.mjs';
+import { readPullsByRepo, pullsOfItem, daysBetween, listLine } from './delivery.mjs';
+
+export const ROUNDUP_READ_VERBS = Object.freeze(['roundup']);
+
+// A free tag that places an item on its product's ladder. An item tagged
+// stage-2 is the stage 2 item or one of its parts.
+export const STAGE_TAG = /^stage-(\d{1,2})$/;
+export const STUCK_DAYS = 14;
+export const TREND_WEEKS = 4;
+const DEFAULT_WINDOW = 7;
+const MAX_WINDOW = 90;
+const MAX_ITEMS = 500;
+const MAX_REPOS = 16;
+const SHOWN = 8;
+const DAY = 86_400_000;
+const LIFECYCLE_ORDER = ['active', 'proposed', 'paused', 'done', 'dropped'];
+
+const plural = (count, word) => `${count} ${count === 1 ? word : (/[^aeiou]y$/.test(word) ? `${word.slice(0, -1)}ies` : `${word}s`)}`;
+const dayOf = (value) => String(value ?? '').slice(0, 10);
+const minus = (readAt, days) => new Date(Date.parse(readAt) - days * DAY).toISOString();
+
+export function stageOf(item) {
+  const tags = Array.isArray(item?.tags) ? item.tags : [];
+  const numbers = tags.map((tag) => STAGE_TAG.exec(String(tag).toLowerCase())).filter(Boolean).map((match) => Number(match[1]));
+  return numbers.length ? Math.min(...numbers) : null;
+}
+
+// The ladder: each stage number with its items, lowest stage first. A stage
+// reads "done" only when every item on it is done or dropped.
+export function ladderOf(items) {
+  const byStage = new Map();
+  for (const item of items) {
+    const stage = stageOf(item);
+    if (stage === null) continue;
+    if (!byStage.has(stage)) byStage.set(stage, []);
+    byStage.get(stage).push(item);
+  }
+  return [...byStage.entries()].sort((a, b) => a[0] - b[0]).map(([stage, list]) => {
+    const rows = list.map((item) => ({ item: item.id, title: oneLine(item.title, 120), lifecycle: item.fields?.lifecycle ?? 'unknown', stage: item.fields?.stage ?? '' }))
+      .sort((a, b) => LIFECYCLE_ORDER.indexOf(a.lifecycle) - LIFECYCLE_ORDER.indexOf(b.lifecycle) || a.title.localeCompare(b.title));
+    const counts = countBy(rows.map((row) => row.lifecycle));
+    const live = rows.filter((row) => LIVE_LIFECYCLES.includes(row.lifecycle));
+    const state = !live.length ? 'done' : (rows.some((row) => row.lifecycle === 'active') ? 'doing' : (rows.some((row) => row.lifecycle === 'done') ? 'started' : 'not started'));
+    return { stage, state, counts, rows };
+  });
+}
+
+export function countBy(values) {
+  const counts = {};
+  for (const value of values) counts[value] = (counts[value] ?? 0) + 1;
+  return Object.fromEntries(Object.entries(counts).sort((a, b) => {
+    const rank = (key) => { const at = LIFECYCLE_ORDER.indexOf(key); return at === -1 ? LIFECYCLE_ORDER.length : at; };
+    return rank(a[0]) - rank(b[0]) || a[0].localeCompare(b[0]);
+  }));
+}
+const countLine = (counts) => Object.entries(counts).map(([key, value]) => `${value} ${key}`).join(', ') || 'none';
+
+// The week a moment falls in, counted back from the read: week 1 is the last
+// seven days. A moment outside the trend is null.
+export function weekOf(at, readAt, weeks = TREND_WEEKS) {
+  const age = Date.parse(readAt) - Date.parse(at ?? '');
+  if (Number.isNaN(age) || age < 0) return null;
+  const week = Math.floor(age / (7 * DAY)) + 1;
+  return week > weeks ? null : week;
+}
+
+export function createRoundupVerbs(core) {
+  const { client, now, typeNamed, registry, requireProduct, readGitHub, inFlight, needsMe } = core;
+  return {
+    async roundup(args = {}) {
+      if (args.product === undefined) refuse('product is required: a roundup answers for one product');
+      const reg = await registry();
+      const product = (await requireProduct(args.product, reg)).fields.registry_id;
+      const windowDays = args.days === undefined ? DEFAULT_WINDOW : args.days;
+      if (!Number.isInteger(windowDays) || windowDays < 1 || windowDays > MAX_WINDOW) refuse(`days must be a whole number from 1 to ${MAX_WINDOW}`);
+      const readAt = now();
+      const since = minus(readAt, windowDays);
+      const trendFrom = minus(readAt, Math.max(windowDays, TREND_WEEKS * 7));
+
+      // Parts 1 and 4 reuse the two views that ship, so one rule serves both.
+      const needs = await needsMe({ product });
+      const flight = await inFlight({ product, since: isoDate(dayOf(trendFrom), 'since') });
+
+      const container = await typeNamed('container');
+      const all = await client.listAllEntities({ type: container.name, state: 'active' });
+      const items = all.filter((row) => row.fields?.product === product);
+      if (items.length > MAX_ITEMS) refuse(`${items.length} items belong to ${product}; the roundup reads at most ${MAX_ITEMS}`);
+
+      const repoIds = [...reg.repos.values()].filter((repo) => repo.fields.product === product).map((repo) => repo.fields.registry_id).sort();
+      if (repoIds.length > MAX_REPOS) refuse(`${repoIds.length} repos are registered for ${product}; the roundup reads at most ${MAX_REPOS}`);
+      const { pullsByRepo, repoErrors } = await readPullsByRepo(repoIds, readGitHub);
+
+      // Which item each pull request belongs to: an item that links it or
+      // whose id it names, as in_flight reads it.
+      const owner = new Map();
+      for (const item of items) for (const pull of pullsOfItem(item, pullsByRepo, repoIds)) if (!owner.has(pull.url)) owner.set(pull.url, item.id);
+      const pulls = [...pullsByRepo.values()].flat();
+
+      // 1. Needs you.
+      const needRows = (needs.products?.[0]?.rows ?? []).map((row) => ({
+        question: row.question_id, item: row.item, text: oneLine(row.folded?.question ?? row.lines?.[0] ?? '', 200), item_title: oneLine(row.folded?.item_title ?? '', 120),
+        asked_at: row.asked_at, days_waiting: daysBetween(row.asked_at, readAt), cost: row.cost,
+      }));
+
+      // 2. Where we stand.
+      const ladder = ladderOf(items);
+      const lifecycles = countBy(items.map((row) => row.fields?.lifecycle ?? 'unknown'));
+      const active = (flight.products?.[0]?.rows ?? []).map((row) => ({ item: row.item, title: oneLine(row.folded?.title ?? '', 120), stage: row.stage, days_since_last_change: row.days_since_last_change, waits_on: row.waits_on ?? null }));
+
+      // 3. What moved, in the window.
+      const merged = pulls.filter((pull) => pull.state === 'merged' && String(pull.merged_at) >= since)
+        .map((pull) => ({ pr: pull.url, title: pull.title, merged_at: pull.merged_at, item: owner.get(pull.url) ?? null }))
+        .sort((a, b) => String(b.merged_at).localeCompare(String(a.merged_at)));
+      const deliveries = (flight.delivered ?? []).filter((row) => String(row.delivered_at) >= since)
+        .map((row) => ({ item: row.item, title: row.item_title, verdict: row.verdict, delivered_at: row.delivered_at, prs: row.prs }));
+      const created = items.filter((row) => String(row.created_at ?? '') >= since)
+        .map((row) => ({ item: row.id, title: oneLine(row.title, 120), lifecycle: row.fields?.lifecycle ?? 'unknown', created_at: row.created_at }))
+        .sort((a, b) => String(b.created_at).localeCompare(String(a.created_at)));
+
+      // 4. Stuck or drifting.
+      const stale = active.filter((row) => row.days_since_last_change !== null && row.days_since_last_change >= STUCK_DAYS);
+      const notMarked = (flight.merged_not_marked ?? []).map((row) => ({ item: row.item, pr: row.pr, title: row.title, days: row.days }));
+      const openNoItem = pulls.filter((pull) => pull.state === 'open' && !owner.has(pull.url)).map((pull) => ({ pr: pull.url, title: pull.title, updated_at: pull.updated_at }));
+      const longWaits = needRows.filter((row) => row.days_waiting !== null && row.days_waiting >= STUCK_DAYS);
+
+      // 5. Trend, per week; week 1 is the last seven days.
+      const weeks = Array.from({ length: TREND_WEEKS }, (_, index) => ({ week: index + 1, from: dayOf(minus(readAt, (index + 1) * 7)), to: dayOf(minus(readAt, index * 7)), merged: 0, delivered: 0, new_items: 0 }));
+      const bump = (at, key) => { const week = weekOf(at, readAt); if (week) weeks[week - 1][key] += 1; };
+      for (const pull of pulls) if (pull.state === 'merged') bump(pull.merged_at, 'merged');
+      for (const row of flight.delivered ?? []) bump(row.delivered_at, 'delivered');
+      for (const row of items) bump(row.created_at, 'new_items');
+      const oldest = needRows.reduce((max, row) => Math.max(max, row.days_waiting ?? 0), 0);
+
+      const text = render({ product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, weeks, oldest, repoErrors });
+      return {
+        verb: 'roundup', read_at: readAt, product, window_days: windowDays, since,
+        needs_you: needRows,
+        where_we_stand: { ladder, lifecycles, active },
+        what_moved: { merged, delivered: deliveries, new_items: created },
+        stuck_or_drifting: { stale, merged_not_marked: notMarked, open_prs_with_no_item: openNoItem, long_waits: longWaits, stuck_days: STUCK_DAYS },
+        trend: { weeks, open_questions: needRows.length, oldest_question_days: oldest },
+        repos_read: repoIds, repo_errors: repoErrors,
+        citation: { product, read_at: readAt, items: items.length, repos: repoIds },
+        text,
+      };
+    },
+  };
+}
+
+function render(view) {
+  const { product, readAt, windowDays, needRows, ladder, lifecycles, active, merged, deliveries, created, stale, notMarked, openNoItem, longWaits, weeks, oldest, repoErrors } = view;
+  const more = (list) => (list.length > SHOWN ? [`   and ${list.length - SHOWN} more`] : []);
+  const out = [`${product} — roundup, ${dayOf(readAt)}`];
+
+  out.push([`1. Needs you (${needRows.length})`,
+    ...(needRows.length ? needRows.slice(0, SHOWN).map((row) => listLine(row.text, `${row.question} · asked ${dayOf(row.asked_at)}, ${plural(row.days_waiting ?? 0, 'day')}`)) : ['   nothing']),
+    ...more(needRows)].join('\n'));
+
+  const stand = [`2. Where we stand · items: ${countLine(lifecycles)}`];
+  if (ladder.length) for (const step of ladder) stand.push(`   ${oneLine(`Stage ${step.stage}: ${step.state} · ${countLine(step.counts)} · ${step.rows.filter((row) => LIVE_LIFECYCLES.includes(row.lifecycle)).map((row) => `${row.title} (${row.lifecycle}, ${row.item.slice(0, 8)})`).join('; ') || 'all closed'}`, ROW_LINE_MAX - 3)}`);
+  else stand.push('   no item carries a stage-<n> tag');
+  stand.push(`   in flight (${active.length})`);
+  stand.push(...(active.length ? active.slice(0, SHOWN).map((row) => listLine(row.title, `${row.item} · ${row.stage || 'no stage'} · ${row.days_since_last_change ?? '?'} days since last change`, '     ')) : ['     nothing']));
+  out.push(stand.join('\n'));
+
+  out.push([`3. What moved, last ${plural(windowDays, 'day')}`,
+    `   ${plural(deliveries.length, 'delivery')} · ${plural(merged.length, 'merged pull request')} · ${plural(created.length, 'new item')}`,
+    ...deliveries.slice(0, SHOWN).map((row) => listLine(`delivered: ${row.title}`, `${row.item} · ${dayOf(row.delivered_at)}`)),
+    ...merged.slice(0, SHOWN).map((row) => listLine(`merged: ${row.title}`, `${row.pr} · ${dayOf(row.merged_at)}${row.item ? '' : ' · no item'}`)),
+    ...more(merged),
+    ...created.slice(0, SHOWN).map((row) => listLine(`new: ${row.title}`, `${row.item} · ${row.lifecycle}`)),
+    ...more(created)].join('\n'));
+
+  const stuck = [`4. Stuck or drifting`];
+  stuck.push(`   no change in ${STUCK_DAYS} days or more (${stale.length})`, ...stale.slice(0, SHOWN).map((row) => listLine(row.title, `${row.item} · ${row.days_since_last_change} days`, '     ')));
+  stuck.push(`   merged, not marked (${notMarked.length})`, ...notMarked.slice(0, SHOWN).map((row) => listLine(row.title, `${row.pr} · ${row.item}`, '     ')));
+  stuck.push(`   open pull requests with no item (${openNoItem.length})`, ...openNoItem.slice(0, SHOWN).map((row) => listLine(row.title, row.pr, '     ')));
+  stuck.push(`   questions waiting ${STUCK_DAYS} days or more (${longWaits.length})`, ...longWaits.slice(0, SHOWN).map((row) => listLine(row.text, `${row.question} · ${row.days_waiting} days`, '     ')));
+  out.push(stuck.join('\n'));
+
+  out.push([`5. Trend, per week (week 1 is the last seven days)`,
+    ...weeks.map((week) => `   week ${week.week} (${week.from} to ${week.to}): ${plural(week.merged, 'merge')} · ${plural(week.delivered, 'delivery')} · ${plural(week.new_items, 'new item')}`),
+    `   waiting on you: ${plural(needRows.length, 'question')}${needRows.length ? `, oldest ${plural(oldest, 'day')}` : ''}`].join('\n'));
+
+  if (repoErrors.length) out.push([`GitHub did not answer for ${plural(repoErrors.length, 'repo')}; parts 3 to 5 count from the graph only`, ...repoErrors.map((row) => oneLine(`   ${row.repo} — ${row.reason}`, ROW_LINE_MAX))].join('\n'));
+  return out.join('\n\n');
+}

package/work/lib/verbs.mjs

@@ -20,6 +20,7 @@ import { createQuestionVerbs, COSTS, QUESTION_WRITE_VERBS, QUESTION_READ_VERBS,
 import { createDeliveryVerbs, DELIVERY_WRITE_VERBS, DELIVERY_READ_VERBS } from './delivery.mjs';
 import { createCapabilityVerbs, CAPABILITY_READ_VERBS, hubOf } from './capability.mjs';
 import { createSweepVerbs, SWEEP_WRITE_VERBS, SWEEP_READ_VERBS } from './sweep.mjs';
+import { createRoundupVerbs, ROUNDUP_READ_VERBS } from './roundup.mjs';
 import { createActivityVerbs, diffOf, LOG_VERBS, ENTRY_VERBS, ACTIVITY_WRITE_VERBS, ACTIVITY_READ_VERBS } from './activity.mjs';
 
 export { VerbError, canonicalJson, sha256, COSTS, LIVE_LIFECYCLES, REPO_KINDS, LIVE_KINDS, repoKinds };
@@ -751,11 +752,12 @@ export function createVerbs({ client, store, writer, session, agent = 'lead', bo
   Object.assign(verbs, createDeliveryVerbs({ ...core, ownerPresent, readGitHub, readLive }));
   Object.assign(verbs, createCapabilityVerbs({ ...core, readGitHub }));
   Object.assign(verbs, createSweepVerbs({ ...core, requireRepos, inFlight: (args) => verbs.in_flight(args), stages: STAGES, tiers: TIERS, drivers: DRIVERS }));
+  Object.assign(verbs, createRoundupVerbs({ ...core, readGitHub, inFlight: (args) => verbs.in_flight(args), needsMe: (args) => verbs.needs_me(args) }));
   const activity = createActivityVerbs(core);
   Object.assign(verbs, activity.verbs);
 
   const WRITE_VERBS = Object.freeze(['setup', 'product_add', 'product_edit', 'repo_add', 'repo_edit', 'item_propose', 'item_lock', 'item_split', 'item_park', 'item_resume', 'item_drop', 'item_edit', 'item_block', 'item_unblock', 'item_stage', 'item_link', ...QUESTION_WRITE_VERBS, ...DELIVERY_WRITE_VERBS, ...SWEEP_WRITE_VERBS, ...ACTIVITY_WRITE_VERBS]);
-  const READ_VERBS = Object.freeze(['registry_list', ...QUESTION_READ_VERBS, ...DELIVERY_READ_VERBS, ...CAPABILITY_READ_VERBS, ...SWEEP_READ_VERBS, ...ACTIVITY_READ_VERBS]);
+  const READ_VERBS = Object.freeze(['registry_list', ...QUESTION_READ_VERBS, ...DELIVERY_READ_VERBS, ...CAPABILITY_READ_VERBS, ...SWEEP_READ_VERBS, ...ROUNDUP_READ_VERBS, ...ACTIVITY_READ_VERBS]);
 
   async function run(verb, args = {}) {
     if (!verbs[verb]) refuse(`unknown verb: ${verb}`);

package/work/mcp.mjs

@@ -69,6 +69,7 @@ export const TOOLS = [
   { name: 'in_flight', description: 'Answer "what are we working on, and what changed since a date?". Active items per product, ordered by the owner\'s current priority decision first, when it carries an order, then by days since the last change with the latest on top, and the days shown on each row. Each row says what the item waits on. Movement is read from the marks and from each registered repo\'s recent pull requests: the item\'s own pr links, plus any pull request whose title, body or branch names the item id. Merged pull requests with no delivery mark are listed as "merged, not marked". A legacy seal reads as a delivery mark with verdict "legacy". Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.'), since: S('ISO date. Adds what was delivered since then.') }, additionalProperties: false } },
   { name: 'sweep_check', description: 'Check the sweep against the "In flight" view: the newest decision record of kind sweep names the items the owner called in flight, and this reads the view and names every difference — what is listed and not in flight, and what is in flight and not listed. A product with no sweep on record is named too. It answers two things apart: `matches` says each product\'s view holds exactly what its sweep lists, and `complete` says that and that no item in the tenant sits outside every product. An item nobody adopted is missing from both sides, so `matches` alone can read "equal" over an unfinished sweep. Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { product: S('Limit the check to one product id.') }, additionalProperties: false } },
   { name: 'needs_me', description: 'Answer "what needs me?": every open question on a proposed, active or paused item, per product, ordered by what waiting costs. A row on an item that is not active names its lifecycle. Each row is three lines, the question, the item and the cost, with the context folded under it. Computed at read time and never stored. Scope: read, no owner flag needed. Pass the row text back as rendered when the owner answers.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.') }, additionalProperties: false } },
+  { name: 'roundup', description: 'Answer "where does this product stand, and where is it going?" in five parts: 1 needs you (the needs_me read); 2 where we stand (items tagged stage-<n> in ladder order, a count of every item by lifecycle, and the active items); 3 what moved in the window (delivery marks, merged pull requests, new items); 4 stuck or drifting (active items with no change for 14 days, merged but not marked, open pull requests that name no item, questions waiting 14 days); 5 the trend per week for four weeks. Every row cites an item, a question or a pull request. Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', required: ['product'], properties: { product: S('Product id.'), days: { type: 'integer', minimum: 1, maximum: 90, description: 'The window for part 3, in days. Default 7.' } }, additionalProperties: false } },
   { name: 'code_read_brief', description: 'The brief for the sub-agents that read the code for "where are we with X", one per registered repo of the product. It carries the never-read and never-quote rules, the citation contract and the JSON shape of the digest. Give one brief to one sub-agent; sub-agents never receive this server or the Engram MCP. Pass each digest back in where_are_we.code. When: before answering "where are we with X". Scope: read, no owner flag needed; it opens no repo and writes nothing.', inputSchema: { type: 'object', required: ['product', 'capability'], properties: { product: S('Product registry id.'), capability: S('The capability to read for, the X of the question.'), repos: { type: 'array', description: 'Limit the briefs to these registered repo ids. Default: every repo of the product.', items: { type: 'string' } }, roots: { type: 'object', description: 'Repo id to the local checkout path the sub-agent reads.', additionalProperties: { type: 'string' } }, commits: { type: 'object', description: 'Repo id to the commit the read runs against.', additionalProperties: { type: 'string' } }, focus: { type: 'array', description: 'Extra things the read should look for.', items: { type: 'string' } } }, additionalProperties: false } },
   { name: 'where_are_we', description: 'Answer "where are we with X" in six parts: live support and known limits from the code read at question time, then in progress, delivered and proposed from the items, then the current priority decision. Every row carries a citation: a path and a line, an entity id, a pull request, or a decision date. The code half comes from the sub-agent digests, which are refused when they cite a never-read path or quote a never-quote path, and every string is scrubbed by pattern. Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', required: ['product', 'capability', 'code'], properties: { product: S('Product registry id.'), capability: S('The capability the question is about, the X.'), code: { type: 'array', description: 'One digest per repo, from the sub-agents briefed by code_read_brief. At least one is required: an answer with no code read says nothing about what the code does today.', items: CODE_DIGEST }, items: { type: 'array', description: 'Item ids the lead judges to answer this question.', items: { type: 'string' } }, match: { type: 'array', description: 'Terms to match against item titles, summaries and tags. Give items, match, or both.', items: { type: 'string' } }, movement_repos: { type: 'array', description: "Narrow the movement read to these registered repo ids. Default: every repo of the product. The digests' own repos are always read.", items: { type: 'string' } }, since: S('ISO date. Adds what changed since then.') }, additionalProperties: false } },
   { name: 'built_pending_possible', description: 'Answer "what are we building, what is built, what is pending and what can be done": delivered items by date, active items, paused items with their reason, proposed items with their age, and the decisions that set the order. Item records, delivery marks and decisions only; no code read and no GitHub read. Computed at read time and never stored. Scope: read, no owner flag needed.', inputSchema: { type: 'object', properties: { product: S('Limit the view to one product id.'), since: S('ISO date. Limits built and the decisions to what came after it.') }, additionalProperties: false } },