@arjunkhera/atlas 0.3.22 → 0.3.24

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "atlas",
-  "version": "0.3.22",
+  "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.22",
+  "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

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