@jabworks/condux 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.21.0",
+  "version": "0.22.0",
   "description": "OpenCode plugin for the condux workflow toolkit — bundles the condux skills and injects the specialist agents (coder, explorer, planner, researcher) plus an opt-in plan-review listener.",
   "type": "module",
   "publishConfig": {

package/skills/blueprint/SKILL.md

@@ -39,8 +39,11 @@ product family.
 │  Wireframes follow references/wireframe-kit.md — wireframe mode  │
 │  by default; render mode when structure is signed off or the     │
 │  user asks for fidelity. Diagrams follow references/             │
-│  diagram-kit.md. All styling from references/token-core.css.     │
-│  No external assets, no CDN, no font files.                      │
+│  diagram-kit.md. Diagrams are checked with references/           │
+│  diagram-check.mjs before Step 3 and delivered only clean; a     │
+│  skipped check is said, never silent. All styling from           │
+│  references/token-core.css. No external assets, no CDN, no       │
+│  font files.                                                     │
 │                                                                  │
 │  Step 3: DELIVER                                                 │
 │  Standalone: open in the browser (xdg-open / open). If neither   │
@@ -145,4 +148,5 @@ mockup into the spec directory first and cite the committed copy.
   both kits; a box the reader can't disagree with isn't evidence
 ✗ Opening a browser tab while running inside /discovery
 ✗ Editing the mockups after design sign-off without saying so
+✗ Delivering a diagram the checker flags, or skipping the check without saying so
 ```

package/skills/blueprint/references/diagram-check.mjs

@@ -0,0 +1,815 @@
+// diagram-check.mjs
+//
+// The eyes of an agent that hand-authors inline SVG diagrams (see
+// diagram-kit.md) and cannot see its own render. It reads one file, finds
+// every inline <svg>…</svg> block, and reports the geometry mistakes a human
+// would catch on sight: an edge that runs through a box it does not connect
+// to, a label sitting on another label or on a node's own title text, an
+// edge nobody labeled, and text that falls outside the canvas.
+//
+// This is a regex-level reader, not a DOM. It understands exactly the
+// idioms diagram-kit.md teaches — `<g transform="translate(x,y)">` offsets,
+// `var(--…)` fills/strokes (never resolved — colors play no part in any
+// check), one shared `<marker>` — and two known approximations:
+//
+//   - text width is estimated at 0.6 em per character (no font metrics);
+//   - Bézier and arc commands (C S Q T A) contribute only their final
+//     endpoint as a straight segment — curvature itself is invisible to it.
+//
+// No dependencies, no network, no shelling out, no filesystem writes.
+
+import fs from 'node:fs';
+import { pathToFileURL } from 'node:url';
+
+// ---------------------------------------------------------------------------
+// Small geometry helpers. A "box" is always { x0, y0, x1, y1 } in viewBox
+// units; nodes/boundaries are boxes with a `line` and (once assigned) a
+// `title`; texts are boxes with `text`, `line`, `free`, `ownEdge`.
+// ---------------------------------------------------------------------------
+
+const shrinkBox = (box, n) => ({ x0: box.x0 + n, y0: box.y0 + n, x1: box.x1 - n, y1: box.y1 - n });
+
+const expandBox = (box, n) => shrinkBox(box, -n);
+
+const rectIntersect = (a, b) => a.x0 < b.x1 && a.x1 > b.x0 && a.y0 < b.y1 && a.y1 > b.y0;
+
+const pointInBox = (px, py, box) => px >= box.x0 && px <= box.x1 && py >= box.y0 && py <= box.y1;
+
+// inner fits inside outer, both ways rounded by `tol` viewBox units.
+const fullyInside = (inner, outer, tol) =>
+  inner.x0 >= outer.x0 - tol && inner.x1 <= outer.x1 + tol && inner.y0 >= outer.y0 - tol && inner.y1 <= outer.y1 + tol;
+
+const containsBox = (outer, inner) => fullyInside(inner, outer, 0);
+
+// Liang-Barsky clip of a segment against a box. Returns the clipped segment
+// and its length, or null when the segment misses the box entirely.
+const liangBarsky = (x1, y1, x2, y2, box) => {
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const p = [-dx, dx, -dy, dy];
+  const q = [x1 - box.x0, box.x1 - x1, y1 - box.y0, box.y1 - y1];
+  let t0 = 0;
+  let t1 = 1;
+
+  for (let i = 0; i < 4; i++) {
+    if (p[i] === 0) {
+      if (q[i] < 0) return null;
+
+      continue;
+    }
+
+    const r = q[i] / p[i];
+    if (p[i] < 0) {
+      if (r > t1) return null;
+      if (r > t0) t0 = r;
+    } else {
+      if (r < t0) return null;
+      if (r < t1) t1 = r;
+    }
+  }
+
+  if (t0 > t1) return null;
+
+  const cx1 = x1 + t0 * dx;
+  const cy1 = y1 + t0 * dy;
+  const cx2 = x1 + t1 * dx;
+  const cy2 = y1 + t1 * dy;
+
+  return { length: Math.hypot(cx2 - cx1, cy2 - cy1) };
+};
+
+const distPointToSegment = (px, py, x1, y1, x2, y2) => {
+  const dx = x2 - x1;
+  const dy = y2 - y1;
+  const lenSq = dx * dx + dy * dy;
+  // A zero-length segment is a point — clamp collapses to it on its own,
+  // but guard the division explicitly rather than relying on NaN behavior.
+  const t = lenSq === 0 ? 0 : Math.max(0, Math.min(1, ((px - x1) * dx + (py - y1) * dy) / lenSq));
+  const nx = x1 + t * dx;
+  const ny = y1 + t * dy;
+
+  return Math.hypot(px - nx, py - ny);
+};
+
+// Distance from a box to a segment: zero when the segment enters the box,
+// else the nearest of the box's corners. Label attribution measures this, not
+// the box centre — a long start-anchored label beside a vertical edge has its
+// centre far from the line and its near edge right on it, and real diagrams
+// (the 2026-09-08 reporting one, six of seven labels) are drawn that way.
+const distBoxToSegment = (box, x1, y1, x2, y2) => {
+  if (liangBarsky(x1, y1, x2, y2, box)) return 0;
+
+  const corners = [
+    [box.x0, box.y0],
+    [box.x1, box.y0],
+    [box.x0, box.y1],
+    [box.x1, box.y1],
+  ];
+
+  return Math.min(...corners.map(([px, py]) => distPointToSegment(px, py, x1, y1, x2, y2)));
+};
+
+const fmt = (n) => Math.round(n * 10) / 10;
+
+// ---------------------------------------------------------------------------
+// Line-number lookup. Built once per source string and reused across every
+// block and element in it, rather than rescanning from zero each time.
+// ---------------------------------------------------------------------------
+
+const makeLineFinder = (source) => {
+  const offsets = [0];
+  for (let i = 0; i < source.length; i++) if (source[i] === '\n') offsets.push(i + 1);
+
+  return (idx) => {
+    let lo = 0;
+    let hi = offsets.length - 1;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (offsets[mid] <= idx) lo = mid;
+      else hi = mid - 1;
+    }
+
+    return lo + 1;
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Attribute and transform parsing.
+// ---------------------------------------------------------------------------
+
+const getAttr = (tag, name) => {
+  const dq = new RegExp(`(?:^|\\s)${name}\\s*=\\s*"([^"]*)"`).exec(tag);
+  if (dq) return dq[1];
+
+  const sq = new RegExp(`(?:^|\\s)${name}\\s*=\\s*'([^']*)'`).exec(tag);
+
+  return sq ? sq[1] : undefined;
+};
+
+// translate(x,y) / translate(x y) / translate(x) — the only transform kind
+// diagram-kit.md uses. Anything else is reported once and treated as identity.
+const parseTranslate = (transform) => {
+  const m = /translate\(\s*(-?[\d.]+)(?:[ ,]+(-?[\d.]+))?\s*\)/.exec(transform);
+  if (!m) return null;
+
+  return { dx: parseFloat(m[1]), dy: m[2] !== undefined ? parseFloat(m[2]) : 0 };
+};
+
+// The kit's labels lean on entities (`HTTP &#183; ReportingBatchRequest`);
+// left undecoded, `&#183;` counts as five characters and every label box
+// grows by four em-fifths per dot — wide enough to invent overlaps.
+const NAMED_ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', middot: '·', rarr: '→' };
+
+const decodeEntities = (s) =>
+  s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, body) => {
+    if (body[0] === '#') {
+      const hex = body[1] === 'x' || body[1] === 'X';
+      const code = hex ? parseInt(body.slice(2), 16) : parseInt(body.slice(1), 10);
+
+      return Number.isFinite(code) ? String.fromCodePoint(code) : whole;
+    }
+
+    return NAMED_ENTITIES[body.toLowerCase()] ?? whole;
+  });
+
+const stripTags = (s) =>
+  decodeEntities(s.replace(/<[^>]+>/g, ''))
+    .replace(/\s+/g, ' ')
+    .trim();
+
+// ---------------------------------------------------------------------------
+// <path d="…"> grammar: M L H V Z absolute/relative, one straight segment per
+// command; C S Q T A keep only the final endpoint (curvature is invisible to
+// this checker — see the header). A second M starts a new subpath, returned
+// as a separate segment list per diagram-kit's "multiple edges in one path"
+// idiom.
+// ---------------------------------------------------------------------------
+
+const CURVE_ARG_COUNTS = { C: 6, S: 4, Q: 4, T: 2, A: 7 };
+
+const parsePathSegments = (d, warnCurve) => {
+  const tokens = d.match(/[a-zA-Z]|-?\d*\.?\d+(?:e-?\d+)?/g) || [];
+  let i = 0;
+  let cx = 0;
+  let cy = 0;
+  let startX = 0;
+  let startY = 0;
+  let cmd = null;
+  let seenM = false;
+  let current = [];
+  const subpaths = [];
+
+  while (i < tokens.length) {
+    if (/^[a-zA-Z]$/.test(tokens[i])) {
+      cmd = tokens[i];
+      i++;
+    }
+
+    if (!cmd) break;
+
+    const letter = cmd.toUpperCase();
+    const isRel = cmd !== letter;
+
+    if (letter === 'M') {
+      if (seenM) {
+        subpaths.push(current);
+        current = [];
+      }
+
+      seenM = true;
+      const x = parseFloat(tokens[i++]);
+      const y = parseFloat(tokens[i++]);
+      cx = isRel ? cx + x : x;
+      cy = isRel ? cy + y : y;
+      startX = cx;
+      startY = cy;
+      // Bare coordinate pairs after M are an implicit lineto.
+      cmd = isRel ? 'l' : 'L';
+
+      continue;
+    }
+
+    if (letter === 'L') {
+      const x = parseFloat(tokens[i++]);
+      const y = parseFloat(tokens[i++]);
+      const nx = isRel ? cx + x : x;
+      const ny = isRel ? cy + y : y;
+      current.push({ x1: cx, y1: cy, x2: nx, y2: ny });
+      cx = nx;
+      cy = ny;
+
+      continue;
+    }
+
+    if (letter === 'H') {
+      const x = parseFloat(tokens[i++]);
+      const nx = isRel ? cx + x : x;
+      current.push({ x1: cx, y1: cy, x2: nx, y2: cy });
+      cx = nx;
+
+      continue;
+    }
+
+    if (letter === 'V') {
+      const y = parseFloat(tokens[i++]);
+      const ny = isRel ? cy + y : y;
+      current.push({ x1: cx, y1: cy, x2: cx, y2: ny });
+      cy = ny;
+
+      continue;
+    }
+
+    if (letter === 'Z') {
+      current.push({ x1: cx, y1: cy, x2: startX, y2: startY });
+      cx = startX;
+      cy = startY;
+
+      continue;
+    }
+
+    if (CURVE_ARG_COUNTS[letter]) {
+      warnCurve();
+      const n = CURVE_ARG_COUNTS[letter];
+      const args = [];
+      for (let k = 0; k < n; k++) args.push(tokens[i++]);
+
+      const x = parseFloat(args[n - 2]);
+      const y = parseFloat(args[n - 1]);
+      const nx = isRel ? cx + x : x;
+      const ny = isRel ? cy + y : y;
+      current.push({ x1: cx, y1: cy, x2: nx, y2: ny });
+      cx = nx;
+      cy = ny;
+
+      continue;
+    }
+
+    // Unknown command letter — skip it rather than spin forever.
+    i++;
+  }
+
+  subpaths.push(current);
+
+  return subpaths.filter((s) => s.length > 0);
+};
+
+// ---------------------------------------------------------------------------
+// Per-<svg>-block walk. A single left-to-right tag scan tracks a stack of
+// <g> offsets (and font-size inheritance), skips <defs>/<marker> subtrees
+// entirely, and special-cases <text>…</text> to pull out its raw content
+// (and any positioned <tspan> children) without a general text-node model.
+// ---------------------------------------------------------------------------
+
+const walkBlock = (source, blockOffset, blockSource, findLine, notify) => {
+  const rects = [];
+  const texts = [];
+  const edges = [];
+
+  const svgOpenMatch = /^<svg\b[^>]*>/.exec(blockSource);
+  const svgOpenTag = svgOpenMatch ? svgOpenMatch[0] : '<svg>';
+  const viewBoxAttr = getAttr(svgOpenTag, 'viewBox');
+  let viewBox = null;
+  if (viewBoxAttr) {
+    const nums = viewBoxAttr.trim().split(/[\s,]+/).map(Number);
+    if (nums.length === 4 && nums.every((n) => Number.isFinite(n))) {
+      const [minX, minY, w, h] = nums;
+      viewBox = { minX, minY, w, h, x0: minX, y0: minY, x1: minX + w, y1: minY + h };
+    }
+  }
+
+  let curOffsetX = 0;
+  let curOffsetY = 0;
+  let curFontSize = parseFloat(getAttr(svgOpenTag, 'font-size') ?? '') || 13;
+  let skipDepth = 0;
+  const stack = [];
+  // The frame a closing tag restores: offsets, inherited font size, and
+  // whether the subtree was inside <defs>/<marker>.
+  const snapshot = () => ({ prevX: curOffsetX, prevY: curOffsetY, prevFontSize: curFontSize, skip: skipDepth > 0 });
+
+  const tagRe = /<\/?[a-zA-Z][^>]*>/g;
+  let m;
+
+  while ((m = tagRe.exec(blockSource))) {
+    const tag = m[0];
+    const idx = m.index;
+    const lineNo = findLine(blockOffset + idx);
+    const closing = tag.startsWith('</');
+    const selfClosing = /\/\s*>$/.test(tag);
+    const nameMatch = /^<\/?([a-zA-Z][\w:-]*)/.exec(tag);
+    const name = nameMatch ? nameMatch[1] : '';
+
+    if (closing) {
+      const frame = stack.pop();
+      if (frame) {
+        curOffsetX = frame.prevX;
+        curOffsetY = frame.prevY;
+        curFontSize = frame.prevFontSize;
+        if (frame.skip) skipDepth--;
+      }
+
+      continue;
+    }
+
+    if (name === 'text' && !selfClosing) {
+      const contentStart = tagRe.lastIndex;
+      const closeIdx = blockSource.indexOf('</text>', contentStart);
+      const rawContent = closeIdx === -1 ? blockSource.slice(contentStart) : blockSource.slice(contentStart, closeIdx);
+
+      if (skipDepth === 0) {
+        processTextElement({
+          tag,
+          rawContent,
+          contentOffset: blockOffset + contentStart,
+          findLine,
+          offX: curOffsetX,
+          offY: curOffsetY,
+          curFontSize,
+          texts,
+          lineNo,
+        });
+      }
+
+      tagRe.lastIndex = closeIdx === -1 ? blockSource.length : closeIdx + '</text>'.length;
+
+      continue;
+    }
+
+    if (name === 'defs' || name === 'marker') {
+      if (!selfClosing) {
+        stack.push({ prevX: curOffsetX, prevY: curOffsetY, prevFontSize: curFontSize, skip: true });
+        skipDepth++;
+      }
+
+      continue;
+    }
+
+    if (name === 'g') {
+      if (!selfClosing) {
+        const transform = getAttr(tag, 'transform');
+        let dx = 0;
+        let dy = 0;
+        if (transform) {
+          const parsed = parseTranslate(transform);
+          if (parsed) {
+            dx = parsed.dx;
+            dy = parsed.dy;
+          } else {
+            notify(`diagram-check: unsupported transform "${transform}" at line ${lineNo} — treated as identity`);
+          }
+        }
+
+        const fontSizeAttr = getAttr(tag, 'font-size');
+        stack.push(snapshot());
+
+        if (skipDepth === 0) {
+          curOffsetX += dx;
+          curOffsetY += dy;
+          if (fontSizeAttr) curFontSize = parseFloat(fontSizeAttr);
+        }
+      }
+
+      continue;
+    }
+
+    if (name === 'svg') {
+      if (!selfClosing) stack.push(snapshot());
+
+      continue;
+    }
+
+    if (skipDepth === 0) {
+      if (name === 'rect') processRect(tag, lineNo, curOffsetX, curOffsetY, rects);
+      else if (name === 'line') processLine(tag, lineNo, curOffsetX, curOffsetY, edges, notify);
+      else if (name === 'polyline') processPolyline(tag, lineNo, curOffsetX, curOffsetY, edges, notify);
+      else if (name === 'path') processPath(tag, lineNo, curOffsetX, curOffsetY, edges, notify);
+    }
+
+    // Any other container tag (unlikely inside a diagram-kit SVG, but a
+    // stray <a> or <clipPath> would otherwise desync the stack) — push a
+    // neutral frame so its closing tag pops correctly.
+    if (!selfClosing) stack.push(snapshot());
+  }
+
+  return { rects, texts, edges, viewBox };
+};
+
+const processRect = (tag, lineNo, offX, offY, rects) => {
+  const x = parseFloat(getAttr(tag, 'x') ?? '0');
+  const y = parseFloat(getAttr(tag, 'y') ?? '0');
+  const w = parseFloat(getAttr(tag, 'width') ?? '0');
+  const h = parseFloat(getAttr(tag, 'height') ?? '0');
+  const stroke = getAttr(tag, 'stroke');
+
+  // No stroke, or an explicit "none", means a decoration (a label halo) —
+  // it never obstructs an edge and never receives a label.
+  if (!stroke || stroke === 'none') return;
+
+  rects.push({ x0: x + offX, y0: y + offY, x1: x + offX + w, y1: y + offY + h, line: lineNo });
+};
+
+// A NaN coordinate compares false against everything, so an edge carrying
+// one would pass every check unseen. Report it and leave it out instead.
+const pushEdge = (edges, edge, notify) => {
+  const finite = edge.segments.every((s) => [s.x1, s.y1, s.x2, s.y2].every(Number.isFinite));
+  if (!finite) {
+    notify(`diagram-check: ${edge.kind} at line ${edge.line} has a non-numeric coordinate — skipped`);
+
+    return;
+  }
+
+  edges.push(edge);
+};
+
+const processLine = (tag, lineNo, offX, offY, edges, notify) => {
+  const x1 = parseFloat(getAttr(tag, 'x1') ?? '0') + offX;
+  const y1 = parseFloat(getAttr(tag, 'y1') ?? '0') + offY;
+  const x2 = parseFloat(getAttr(tag, 'x2') ?? '0') + offX;
+  const y2 = parseFloat(getAttr(tag, 'y2') ?? '0') + offY;
+
+  pushEdge(edges, { kind: 'line', segments: [{ x1, y1, x2, y2 }], line: lineNo }, notify);
+};
+
+const processPolyline = (tag, lineNo, offX, offY, edges, notify) => {
+  const pointsStr = getAttr(tag, 'points');
+  if (!pointsStr) return;
+
+  const nums = pointsStr.trim().split(/[\s,]+/).map(Number);
+  const points = [];
+  for (let i = 0; i + 1 < nums.length; i += 2) points.push({ x: nums[i] + offX, y: nums[i + 1] + offY });
+
+  const segments = [];
+  for (let i = 0; i + 1 < points.length; i++) {
+    segments.push({ x1: points[i].x, y1: points[i].y, x2: points[i + 1].x, y2: points[i + 1].y });
+  }
+
+  if (segments.length > 0) pushEdge(edges, { kind: 'polyline', segments, line: lineNo }, notify);
+};
+
+const processPath = (tag, lineNo, offX, offY, edges, notify) => {
+  const fill = getAttr(tag, 'fill');
+  if (fill && fill !== 'none') return; // fill !== none/absent is a filled shape, not an edge
+
+  const d = getAttr(tag, 'd');
+  if (!d) return;
+
+  for (const segs of parsePathSegments(d, () => notify.curve())) {
+    const offsetSegs = segs.map((s) => ({ x1: s.x1 + offX, y1: s.y1 + offY, x2: s.x2 + offX, y2: s.y2 + offY }));
+    pushEdge(edges, { kind: 'path', segments: offsetSegs, line: lineNo }, notify);
+  }
+};
+
+const pushTextBox = (texts, text, absX, absY, anchor, fontSize, lineNo) => {
+  if (!text) return;
+
+  const width = text.length * fontSize * 0.6;
+  const top = absY - 0.75 * fontSize;
+  const bottom = absY + 0.25 * fontSize;
+  let x0;
+  let x1;
+
+  if (anchor === 'middle') {
+    x0 = absX - width / 2;
+    x1 = absX + width / 2;
+  } else if (anchor === 'end') {
+    x0 = absX - width;
+    x1 = absX;
+  } else {
+    x0 = absX;
+    x1 = absX + width;
+  }
+
+  texts.push({ x0, y0: top, x1, y1: bottom, text, line: lineNo });
+};
+
+const processTextElement = ({ tag, rawContent, contentOffset, findLine, offX, offY, curFontSize, texts, lineNo }) => {
+  const x = parseFloat(getAttr(tag, 'x') ?? '0');
+  const y = parseFloat(getAttr(tag, 'y') ?? '0');
+  const anchor = getAttr(tag, 'text-anchor') ?? 'start';
+  const fontSizeAttr = getAttr(tag, 'font-size');
+  const fontSize = fontSizeAttr ? parseFloat(fontSizeAttr) : curFontSize;
+
+  const tspanRe = /<tspan\b([^>]*)>([\s\S]*?)<\/tspan>/g;
+  const tspans = [];
+  let tm;
+  while ((tm = tspanRe.exec(rawContent))) {
+    const tspanTag = `<tspan ${tm[1]}>`;
+    const tx = getAttr(tspanTag, 'x');
+    const ty = getAttr(tspanTag, 'y');
+    const text = stripTags(tm[2]);
+
+    if (tx !== undefined && ty !== undefined && text) {
+      tspans.push({ tag: tspanTag, x: parseFloat(tx), y: parseFloat(ty), text, index: tm.index });
+    }
+  }
+
+  if (tspans.length > 0) {
+    for (const t of tspans) {
+      const tAnchor = getAttr(t.tag, 'text-anchor') ?? anchor;
+      const tFontSizeAttr = getAttr(t.tag, 'font-size');
+      const tFontSize = tFontSizeAttr ? parseFloat(tFontSizeAttr) : fontSize;
+      const tLine = findLine(contentOffset + t.index);
+      pushTextBox(texts, t.text, t.x + offX, t.y + offY, tAnchor, tFontSize, tLine);
+    }
+
+    return;
+  }
+
+  const content = stripTags(rawContent);
+  pushTextBox(texts, content, x + offX, y + offY, anchor, fontSize, lineNo);
+};
+
+// ---------------------------------------------------------------------------
+// Findings for one parsed block.
+// ---------------------------------------------------------------------------
+
+const describeEdge = (edge) => {
+  const first = edge.segments[0];
+  const last = edge.segments[edge.segments.length - 1];
+
+  return `${edge.kind} (${fmt(first.x1)},${fmt(first.y1)})→(${fmt(last.x2)},${fmt(last.y2)})`;
+};
+
+const describeNode = (node) => (node.title ? `"${node.title}"` : `rect (${fmt(node.x0)},${fmt(node.y0)})`);
+
+const edgeEndpoints = (edge) => {
+  const first = edge.segments[0];
+  const last = edge.segments[edge.segments.length - 1];
+
+  return { start: { x: first.x1, y: first.y1 }, end: { x: last.x2, y: last.y2 } };
+};
+
+const crossesBox = (edge, box) =>
+  edge.segments.some((seg) => {
+    const clip = liangBarsky(seg.x1, seg.y1, seg.x2, seg.y2, box);
+
+    return clip && clip.length > 2;
+  });
+
+const findingsForBlock = ({ rects, texts, edges, viewBox }) => {
+  const findings = [];
+
+  // Classify rects: a stroked rect that fully contains another stroked rect
+  // is a boundary and is never an obstacle; the rest are nodes.
+  for (const r of rects) r.isBoundary = rects.some((o) => o !== r && containsBox(r, o));
+  const nodes = rects.filter((r) => !r.isBoundary);
+
+  // Owned vs. free text, and each node's title (first owned text, in
+  // document order).
+  for (const text of texts) {
+    const owner = nodes.find((node) => fullyInside(text, node, 1));
+    if (owner) {
+      text.free = false;
+      text.owner = owner;
+      if (!owner.title) owner.title = text.text;
+    } else {
+      text.free = true;
+    }
+  }
+
+  // Each free text's own edge: the edge whose nearest segment comes closest
+  // to the text box, when that distance is within labeling range.
+  for (const text of texts) {
+    if (!text.free) continue;
+
+    let best = null;
+    let bestDist = Infinity;
+
+    for (const edge of edges) {
+      for (const seg of edge.segments) {
+        const d = distBoxToSegment(text, seg.x1, seg.y1, seg.x2, seg.y2);
+        if (d < bestDist) {
+          bestDist = d;
+          best = edge;
+        }
+      }
+    }
+
+    text.ownEdge = best && bestDist <= 24 ? best : null;
+  }
+
+  // An edge attaches to a node when either endpoint lands on it (4 units of
+  // slack for arrowheads that stop short of the border).
+  const isAttached = (edge, node) => {
+    const { start, end } = edgeEndpoints(edge);
+    const expanded = expandBox(node, 4);
+
+    return pointInBox(start.x, start.y, expanded) || pointInBox(end.x, end.y, expanded);
+  };
+
+  // 1. edge-through-box
+  for (const edge of edges) {
+    for (const node of nodes) {
+      if (isAttached(edge, node)) continue;
+
+      if (crossesBox(edge, shrinkBox(node, 1))) {
+        findings.push({
+          code: 'edge-through-box',
+          line: edge.line,
+          detail: `${describeEdge(edge)} crosses ${describeNode(node)}`,
+        });
+      }
+    }
+  }
+
+  // 2. label-over-label
+  for (let i = 0; i < texts.length; i++) {
+    for (let j = i + 1; j < texts.length; j++) {
+      const a = texts[i];
+      const b = texts[j];
+      if (rectIntersect(shrinkBox(a, 1), shrinkBox(b, 1))) {
+        findings.push({
+          code: 'label-over-label',
+          line: Math.min(a.line, b.line),
+          detail: `"${a.text}" overlaps "${b.text}"`,
+        });
+      }
+    }
+  }
+
+  // 3. label-over-box (free text straddling a node's border)
+  for (const text of texts) {
+    if (!text.free) continue;
+
+    for (const node of nodes) {
+      if (rectIntersect(shrinkBox(text, 1), node)) {
+        findings.push({
+          code: 'label-over-box',
+          line: text.line,
+          detail: `"${text.text}" straddles ${describeNode(node)}`,
+        });
+      }
+    }
+  }
+
+  // 4. edge-through-label (excluding a free text's own edge)
+  for (const edge of edges) {
+    for (const text of texts) {
+      if (text.ownEdge === edge) continue;
+
+      // A node's own text under an edge that does not attach to the node is
+      // the edge-through-box finding already reported — naming the title too
+      // would print one defect twice.
+      if (text.owner && !isAttached(edge, text.owner)) continue;
+
+      if (crossesBox(edge, shrinkBox(text, 1))) {
+        findings.push({
+          code: 'edge-through-label',
+          line: edge.line,
+          detail: `${describeEdge(edge)} crosses label "${text.text}"`,
+        });
+      }
+    }
+  }
+
+  // 5. unlabeled-edge
+  const labeled = new Set(texts.filter((t) => t.ownEdge).map((t) => t.ownEdge));
+  for (const edge of edges) {
+    if (!labeled.has(edge)) {
+      findings.push({
+        code: 'unlabeled-edge',
+        line: edge.line,
+        detail: `${describeEdge(edge)} has no label within 24px`,
+      });
+    }
+  }
+
+  // 6. text-outside-canvas
+  if (viewBox) {
+    const canvas = `${viewBox.minX} ${viewBox.minY} ${viewBox.w} ${viewBox.h}`;
+
+    for (const text of texts) {
+      const fully = fullyInside(text, viewBox, 0);
+      if (!fully) {
+        findings.push({
+          code: 'text-outside-canvas',
+          line: text.line,
+          detail: `"${text.text}" falls outside the canvas (viewBox ${canvas})`,
+        });
+      }
+    }
+  }
+
+  return findings;
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+// Finds every <svg>…</svg> block in `source` and runs all six checks against
+// each. Returns Finding[] = { code, line, detail }[], sorted by line then code.
+export const checkSvg = (rawSource) => {
+  // The kit's own marker block carries `<!-- usage: <line … /> -->`, and the
+  // kit says to paste it verbatim — scanned raw, that comment is a phantom
+  // zero-length edge at the origin and every diagram fails "clean". Blank
+  // comments character-for-character (newlines kept) so line numbers hold.
+  const source = rawSource.replace(/<!--[\s\S]*?-->/g, (comment) => comment.replace(/[^\n]/g, ' '));
+  const findLine = makeLineFinder(source);
+  let curveWarned = false;
+  const notify = (msg) => process.stderr.write(msg + '\n');
+  notify.curve = () => {
+    if (curveWarned) return;
+    curveWarned = true;
+    notify('diagram-check: curve command (C/S/Q/T/A) approximated as its endpoint only');
+  };
+
+  const findings = [];
+  const blockRe = /<svg\b[^>]*>[\s\S]*?<\/svg>/g;
+  let m;
+
+  while ((m = blockRe.exec(source))) {
+    const parsed = walkBlock(source, m.index, m[0], findLine, notify);
+    findings.push(...findingsForBlock(parsed));
+  }
+
+  findings.sort((a, b) => a.line - b.line || a.code.localeCompare(b.code));
+
+  return findings;
+};
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+
+const runCli = (argv) => {
+  const jsonMode = argv.includes('--json');
+  const file = argv.find((a) => !a.startsWith('--'));
+
+  if (!file) {
+    process.stderr.write('usage: diagram-check.mjs <file.html|file.svg> [--json]\n');
+
+    return 2;
+  }
+
+  let source;
+  try {
+    source = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    process.stderr.write(`diagram-check: cannot read ${file}: ${err.message}\n`);
+
+    return 2;
+  }
+
+  if (!/<svg\b[^>]*>[\s\S]*?<\/svg>/.test(source)) {
+    process.stderr.write(`diagram-check: no <svg> block found in ${file}\n`);
+
+    return 2;
+  }
+
+  const findings = checkSvg(source);
+
+  if (jsonMode) {
+    process.stdout.write(JSON.stringify({ file, findings }) + '\n');
+  } else if (findings.length === 0) {
+    process.stdout.write('clean\n');
+  } else {
+    for (const f of findings) process.stdout.write(`${f.code}  line ${f.line}  ${f.detail}\n`);
+    process.stdout.write(`${findings.length} finding(s)\n`);
+  }
+
+  return findings.length === 0 ? 0 : 1;
+};
+
+if (import.meta.url === pathToFileURL(process.argv[1] ?? '').href) {
+  process.exit(runCli(process.argv.slice(2)));
+}

package/skills/blueprint/references/diagram-kit.md

@@ -28,12 +28,72 @@ of the `<style>` block, verbatim.
     <path d="M0,0 L10,5 L0,10 z" fill="var(--subtle)"/>
   </marker>
 </defs>
-<!-- usage: <line ... stroke="var(--subtle)" marker-end="url(#arrow)"/> -->
+<!-- usage: <line ... stroke="var(--subtle)" marker-end="url(#arrow)"/> or
+     <path ... stroke="var(--subtle)" marker-end="url(#arrow)"/> — the marker
+     works the same on both elements. -->
 ```
 
 - Every relationship line gets a label. An unlabeled arrow is a guess the
   reader has to make.
 
+## Layout and Routing
+
+1. *Grid first.* Assign every node a column and a row before drawing anything.
+   Column pitch is box width plus a gutter of at least 72; row pitch is box
+   height plus a gutter of at least 72. Gutters are edge corridors — wide
+   enough for a label with its halo and two staggered edges. Boundaries wrap
+   whole column/row spans and are drawn behind their members.
+2. *Edges are orthogonal paths.* `<path d="M … H … V … H …">` with the shared
+   arrow marker (it works on `<path>` exactly as on `<line>`). Never a
+   diagonal. An edge leaves the side of its source that faces the target and
+   enters the facing side of the target.
+3. *Ports.* Each side of a box has three ports, at 25%, 50% and 75% of its
+   length. Two edges on the same side take different ports — edges never
+   share a port, so parallel edges never stack.
+4. *Corridors only.* A segment may run only through gutters and across
+   boundaries, never through a box's footprint. If a third box sits in the
+   straight corridor between source and target, either move it to another row
+   or column (preferred — rearranging is free before the drawing exists) or
+   dog-leg through the adjacent gutter.
+5. *Labels.* One label per segment, on the edge's longest free segment,
+   `--mono` 11px: on a horizontal segment it sits 4px above the line, on a
+   vertical segment it is centred on the line over its halo.
+   Every label gets a halo so a crossing edge stays legible: a stroke-less
+   `<rect>` in the fill the label sits on (`var(--background)` on open
+   canvas, `var(--muted)` inside a filled boundary) drawn behind the text —
+   the checker ignores stroke-less rects, so the halo is never mistaken for a
+   node. Two labels never share a corridor position: stagger by 14px or move
+   one to another segment.
+6. *Fan-in is a smell.* More than four edges into one box, or more than three
+   edges in one gutter, means the diagram is answering two questions — split
+   it (same rule as "Choosing the Shape").
+7. *Check before delivering.* Run
+   `node /PATH/TO/blueprint/references/diagram-check.mjs <file>` (the
+   `/PATH/TO/` idiom is the one `plan-review` uses for its scripts — the
+   skill's install location). A finding is a defect in the drawing, never a
+   tolerance to argue with: fix, re-run, deliver only `clean`. If `node` is
+   unavailable, say the check was skipped — never silently.
+
+   | Code | Meaning |
+   |---|---|
+   | `edge-through-box` | an edge segment crosses a node rect it doesn't attach to |
+   | `label-over-label` | two text boxes intersect |
+   | `label-over-box` | a text box straddles a node rect border |
+   | `edge-through-label` | an edge crosses a text box that isn't its own label |
+   | `unlabeled-edge` | no text within 24px of the edge |
+   | `text-outside-canvas` | text escapes the viewBox |
+
+   Two boxes on different rows and columns, joined by a three-segment path
+   with one haloed label and distinct ports:
+
+   ```html
+   <!-- orders → invoices: leave the right side at the 50% port, run the gutter,
+        enter the left side at its 25% port. Label centred on the vertical segment, haloed. -->
+   <path d="M 240 92 H 300 V 180 H 340" fill="none" stroke="var(--subtle)" marker-end="url(#arrow)"/>
+   <rect x="262" y="120" width="76" height="14" fill="var(--background)"/>
+   <text x="300" y="131" text-anchor="middle" font-size="11" fill="var(--muted-foreground)">1..* invoices</text>
+   ```
+
 ## The Specificity Rule
 
 Every label must name something real from *this* design — a path, a command, a