@xgent-ai/skills 0.3.0 → 0.5.0

package/skills/archify/test/layout-rules.test.mjs

@@ -0,0 +1,1498 @@
+// Per-rule coverage for the renderers' layout validators. The golden suite's
+// negative cases mostly trip ajv SCHEMA rules; this file targets the hand-
+// written LAYOUT rules (the `problems.push(...)` checks) — the layer that has
+// regressed before — by mutating a valid example into exactly one violation
+// and asserting the renderer exits non-zero with the expected message.
+//
+// It also locks the error-message CONTRACT: representative messages must carry
+// both the numeric threshold and a remediation hint, since the consumer is an
+// LLM that fixes the JSON from the message alone.
+//
+//   node --test test/*.test.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-rules-'));
+
+const EXAMPLES = {
+  workflow: 'agent-tool-call.workflow.json',
+  sequence: 'cache-miss-request.sequence.json',
+  dataflow: 'product-analytics.dataflow.json',
+  lifecycle: 'agent-run.lifecycle.json',
+  architecture: 'web-app.architecture.json',
+};
+
+function load(mode) {
+  return JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', EXAMPLES[mode]), 'utf8'));
+}
+
+// Returns { code, stderr }. Never throws on non-zero exit.
+function render(mode, doc) {
+  const input = path.join(tmp, `${mode}-${Math.abs(hash(JSON.stringify(doc)))}.json`);
+  const outPath = path.join(tmp, `${mode}-${Math.abs(hash(JSON.stringify(doc)))}.html`);
+  fs.writeFileSync(input, JSON.stringify(doc));
+  try {
+    execFileSync('node', [
+      path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+      input,
+      outPath,
+    ], { stdio: ['ignore', 'ignore', 'pipe'] });
+    return { code: 0, stderr: '', outPath };
+  } catch (err) {
+    return { code: err.status ?? 1, stderr: String(err.stderr || ''), outPath };
+  }
+}
+
+function validateCli(mode, doc, quality = 'showcase') {
+  const input = path.join(tmp, `${mode}-cli-${Math.abs(hash(JSON.stringify(doc)))}.json`);
+  fs.writeFileSync(input, JSON.stringify(doc));
+  try {
+    const stdout = execFileSync('node', [
+      path.join(skillRoot, 'bin', 'archify.mjs'),
+      'validate',
+      mode,
+      input,
+      '--quality',
+      quality,
+      '--json',
+    ], { encoding: 'utf8' });
+    return { code: 0, result: JSON.parse(stdout) };
+  } catch (err) {
+    return {
+      code: err.status ?? 1,
+      result: JSON.parse(String(err.stdout || '{}')),
+    };
+  }
+}
+
+function hash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i += 1) h = (h * 31 + s.charCodeAt(i)) | 0;
+  return h;
+}
+
+function workflowEdgePoints(html, id) {
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pointsAttribute = html.match(
+    new RegExp(`data-edge-id="${escapedId}" data-composition-points="([^"]+)"`),
+  )?.[1];
+  assert.ok(pointsAttribute, `expected rendered workflow edge points for ${id}`);
+  return pointsAttribute.split(';').map((point) => point.split(',').map(Number));
+}
+
+function workflowNodeRect(html, id) {
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = html.match(new RegExp(
+    `<g id="node-${escapedId}"[^>]*>[\\s\\S]*?<rect x="([^"]+)" y="([^"]+)" width="([^"]+)" height="([^"]+)"`,
+  ));
+  assert.ok(match, `expected rendered workflow node rect for ${id}`);
+  const [, x, y, width, height] = match.map(Number);
+  return { x, y, width, height };
+}
+
+function boundaryFrameRect(html, index) {
+  const match = html.match(new RegExp(
+    `<rect data-graph-role="structural-frame"[^>]*data-composition-frame-id="${index}"[^>]*x="([^"]+)" y="([^"]+)" width="([^"]+)" height="([^"]+)"`,
+  ));
+  assert.ok(match, `expected boundary frame ${index}`);
+  const [, x, y, width, height] = match.map(Number);
+  return { x, y, width, height };
+}
+
+function boundaryTitleMasks(html) {
+  return [...html.matchAll(
+    /<g data-graph-role="structural-frame-label"[^>]*data-composition-frame-id="(\d+)"[^>]*>[\s\S]*?<rect data-graph-role="structural-frame-label-mask" x="([^"]+)" y="([^"]+)" width="([^"]+)" height="([^"]+)"/g,
+  )].map((match) => ({
+    index: Number(match[1]),
+    x: Number(match[2]),
+    y: Number(match[3]),
+    width: Number(match[4]),
+    height: Number(match[5]),
+  }));
+}
+
+function rectContainsRect(outer, inner) {
+  return outer.x <= inner.x
+    && outer.y <= inner.y
+    && outer.x + outer.width >= inner.x + inner.width
+    && outer.y + outer.height >= inner.y + inner.height;
+}
+
+function rectanglesOverlap(left, right) {
+  return left.x < right.x + right.width
+    && left.x + left.width > right.x
+    && left.y < right.y + right.height
+    && left.y + left.height > right.y;
+}
+
+function workflowEdgeLabelPoint(html, id) {
+  const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = html.match(new RegExp(
+    `<g data-detail="context"[^>]*data-edge-id="${escapedId}"[^>]*>[\\s\\S]*?<text x="([^"]+)" y="([^"]+)"`,
+  ));
+  assert.ok(match, `expected rendered workflow edge label for ${id}`);
+  return match.slice(1).map(Number);
+}
+
+function axisOverlapLength(a1, a2, b1, b2) {
+  return Math.max(0, Math.min(Math.max(a1, a2), Math.max(b1, b2))
+    - Math.max(Math.min(a1, a2), Math.min(b1, b2)));
+}
+
+function workflowNodeBorderOverlap(points, rect) {
+  const hits = [];
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const [start, end] = [points[index], points[index + 1]];
+    if (start[0] === end[0] && (start[0] === rect.x || start[0] === rect.x + rect.width)) {
+      const length = axisOverlapLength(start[1], end[1], rect.y, rect.y + rect.height);
+      if (length > 0) hits.push({ segment: index, length, start, end });
+    }
+    if (start[1] === end[1] && (start[1] === rect.y || start[1] === rect.y + rect.height)) {
+      const length = axisOverlapLength(start[0], end[0], rect.x, rect.x + rect.width);
+      if (length > 0) hits.push({ segment: index, length, start, end });
+    }
+  }
+  return hits;
+}
+
+function assertRelationshipsAvoidAllNodeBorders(html, relationships, diagramNodes) {
+  for (const [edgeIndex, edge] of relationships.entries()) {
+    const edgeId = edge.id || `edge-${edgeIndex}`;
+    const points = workflowEdgePoints(html, edgeId);
+    for (const node of diagramNodes) {
+      const hits = workflowNodeBorderOverlap(points, workflowNodeRect(html, node.id));
+      assert.deepEqual(
+        hits,
+        [],
+        `workflow edge ${edgeId} runs along node ${node.id} border: ${JSON.stringify(hits)}`,
+      );
+    }
+  }
+}
+
+function assertWorkflowEdgesAvoidAllNodeBorders(html, doc) {
+  assertRelationshipsAvoidAllNodeBorders(html, doc.edges, doc.nodes);
+}
+
+// [name, mode, mutate(doc), expectedSubstrings[]] — every mutation introduces
+// exactly one layout violation. Each expected substring must appear in stderr.
+const CASES = [
+  // ---- workflow layout rules ----
+  ['workflow: unknown lane', 'workflow', (d) => { d.nodes[0].lane = 'ghost'; }, ['unknown lane "ghost"']],
+  ['workflow: node label wider than box', 'workflow',
+    (d) => { d.nodes[0].label = 'An Extremely Long Node Label That Overflows'; }, ['wider than node', 'shorten the label']],
+  ['workflow: node sublabel wider than its legible minimum', 'workflow',
+    (d) => { d.nodes[0].sublabel = 'This supporting sentence is much too long for one workflow node'; }, ['Sublabel', 'legible', 'increase node.width']],
+  ['workflow: node tag wider than its legible minimum', 'workflow',
+    (d) => { d.nodes[0].tag = 'This tag is far too long to sit inside one workflow node box'; },
+    ['Tag', 'legible', 'increase node.width']],
+  ['workflow: viewBox width below schema min', 'workflow',
+    (d) => { d.meta.viewBox = [699, 900]; }, ['700']],
+  ['workflow: nodes too close in a lane', 'workflow',
+    (d) => { d.nodes.push({ ...d.nodes[0], id: 'dupe', col: d.nodes[0].col }); }, ['less than 8px apart']],
+  ['workflow: empty group', 'workflow',
+    (d) => { d.groups = [{ id: 'empty', label: 'Empty group', lane: 'ui', fromCol: 3, toCol: 4 }]; }, ['does not contain any nodes']],
+  ['workflow: mainPath missing edge', 'workflow',
+    (d) => { d.mainPath = ['user', 'planner']; }, ['mainPath step "user" -> "planner" has no matching edge']],
+  ['workflow: mainPath moves backward', 'workflow',
+    (d) => { d.mainPath = ['external', 'trace']; }, ['moves backward from col']],
+  ['workflow: phase ranges overlap', 'workflow',
+    (d) => { d.phases[2].fromCol = d.phases[1].toCol; }, ['overlaps phase', 'start at col 4 or later']],
+
+  // ---- sequence layout rules ----
+  ['sequence: message references unknown participant', 'sequence',
+    (d) => { d.messages[0].from = 'ghost'; }, ['unknown source "ghost"']],
+  ['sequence: message y outside timeline', 'sequence',
+    (d) => { d.messages[0].y = 9000; }, ['outside the readable timeline', 'keep y between']],
+  ['sequence: segment to <= from', 'sequence',
+    (d) => { d.segments = [{ from: 400, to: 300, label: 'bad' }]; }, ['invalid y range', 'greater than']],
+  ['sequence: segment label exceeds segment frame available width', 'sequence',
+    (d) => { d.segments[0].label = 'Long Segment Label '.repeat(10); },
+    ['exceeds the segment frame\'s available width', 'increase meta.viewBox[0]']],
+  ['sequence: participant sublabel wider than its legible minimum', 'sequence',
+    (d) => { d.participants[0].sublabel = 'This supporting sentence is far too long for one sequence participant'; },
+    ['Sublabel', 'legible', 'shorten the sublabel']],
+
+  // ---- dataflow layout rules ----
+  ['dataflow: flow missing label', 'dataflow',
+    (d) => { delete d.flows[0].label; }, ['label']],
+  ['dataflow: flow references unknown node', 'dataflow',
+    (d) => { d.flows[0].to = 'ghost'; }, ['unknown target "ghost"']],
+  ['dataflow: explicit via keeps every route segment orthogonal', 'dataflow',
+    (d) => {
+      d.flows[0].via = [[195, 140], [195, 260]];
+    }, ['diagonal segment', 'align via[0]']],
+  ['dataflow: node sublabel wider than its legible minimum', 'dataflow',
+    (d) => { d.nodes[0].sublabel = 'This supporting sentence is far too long for one data-flow node box'; },
+    ['Sublabel', 'legible', 'increase node.width']],
+  ['dataflow: node tag wider than its legible minimum', 'dataflow',
+    (d) => { d.nodes[0].tag = 'This tag is far too long to sit inside one data-flow node box'; },
+    ['Tag', 'legible', 'increase node.width']],
+
+  // ---- lifecycle layout rules ----
+  ['lifecycle: missing reserved main lane', 'lifecycle',
+    (d) => {
+      d.lanes = d.lanes.map((l) => (l.id === 'main' ? { ...l, id: 'primary' } : l));
+      d.states = d.states.map((s) => (s.lane === 'main' ? { ...s, lane: 'primary' } : s));
+    }, ['"main"', 'reserved']],
+  ['lifecycle: cross-lane state overlap', 'lifecycle',
+    (d) => {
+      const approval = d.states.find((s) => s.id === 'approval');
+      const failed = d.states.find((s) => s.id === 'failed');
+      delete failed.yOffset;
+      failed.col = approval.col;
+    }, ['less than 10px apart']],
+  ['lifecycle: viewBox height below schema min', 'lifecycle',
+    (d) => { d.meta.viewBox = [980, 565]; }, ['566']],
+  ['lifecycle: state sublabel wider than its legible minimum', 'lifecycle',
+    (d) => { d.states[0].sublabel = 'This supporting sentence is far too long for one lifecycle state box'; },
+    ['Sublabel', 'legible', 'increase state.width']],
+  ['lifecycle: state tag wider than its legible minimum', 'lifecycle',
+    (d) => { d.states[0].tag = 'This tag is far too long to sit inside one lifecycle state box'; },
+    ['Tag', 'legible', 'increase state.width']],
+
+  // ---- architecture layout rules ----
+  ['architecture: components overlap', 'architecture',
+    (d) => { d.components[1].pos = [...d.components[0].pos]; }, ['less than 8px apart']],
+  ['architecture: connection references unknown component', 'architecture',
+    (d) => { d.connections[0].to = 'ghost'; }, ['unknown target "ghost"']],
+  ['architecture: boundary wraps unknown component', 'architecture',
+    (d) => { d.boundaries[0].wraps.push('ghost'); }, ['wraps unknown component "ghost"']],
+  ['architecture: boundary title must fit inside its own frame', 'architecture',
+    (d) => {
+      d.meta.quality_profile = 'standard';
+      d.meta.viewBox = [500, 400];
+      d.components = [{
+        id: 'narrow',
+        type: 'backend',
+        label: 'Narrow',
+        pos: [330, 100],
+        size: [128, 60],
+      }];
+      delete d.meta.views;
+      d.connections = [];
+      d.cards = [];
+      d.boundaries = [{
+        kind: 'region',
+        label: 'A boundary title that cannot fit its narrow authored frame',
+        wraps: ['narrow'],
+        pad: 0,
+      }];
+    }, ['Boundary label', 'fit', 'shorten']],
+  ['architecture: boundary title must stay inside the authored viewBox', 'architecture',
+    (d) => {
+      d.meta.quality_profile = 'standard';
+      d.meta.viewBox = [500, 400];
+      d.components = [{
+        id: 'near-top',
+        type: 'backend',
+        label: 'Near top',
+        pos: [120, 8],
+        size: [128, 60],
+      }];
+      delete d.meta.views;
+      d.connections = [];
+      d.cards = [];
+      d.boundaries = [{
+        kind: 'region',
+        label: 'Viewport title',
+        wraps: ['near-top'],
+        pad: 0,
+      }];
+    }, ['Boundary label', 'outside the viewBox', 'move wrapped components']],
+  ['architecture: label wider than component', 'architecture',
+    (d) => { d.components[0].label = 'An Extremely Long Component Label Overflow'; }, ['wider than component', 'shorten the label']],
+  ['architecture: component sublabel wider than its legible minimum', 'architecture',
+    (d) => { d.components[0].sublabel = 'This supporting sentence is far too long for one architecture component'; },
+    ['Sublabel', 'legible', 'widen size']],
+  ['architecture: component tag wider than its legible minimum', 'architecture',
+    (d) => { d.components[0].tag = 'This tag is far too long to sit inside one architecture component box'; },
+    ['Tag', 'legible', 'widen size']],
+  ['architecture: component overlap suggests fix', 'architecture',
+    (d) => { d.components[1].pos = [...d.components[0].pos]; }, ['Suggested fix', 'move "']],
+
+];
+
+for (const [name, mode, mutate, expected] of CASES) {
+  test(name, () => {
+    const doc = load(mode);
+    mutate(doc);
+    const { code, stderr } = render(mode, doc);
+    assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+    assert.doesNotMatch(stderr, /TypeError|is not a function|Cannot read/, `crashed instead of reporting:\n${stderr}`);
+    for (const sub of expected) {
+      assert.ok(stderr.includes(sub), `expected "${sub}" in stderr:\n${stderr}`);
+    }
+  });
+}
+
+test('architecture: ordinary boundaries may express orthogonal overlapping memberships', () => {
+  const d = load('architecture');
+  d.boundaries[1].wraps.push('auth');
+  const { code, stderr, outPath } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  assert.equal(rectanglesOverlap(boundaryFrameRect(html, 0), boundaryFrameRect(html, 1)), true);
+  const masks = boundaryTitleMasks(html);
+  assert.equal(masks.length, 2);
+  assert.equal(rectanglesOverlap(masks[0], masks[1]), false);
+});
+
+test('architecture: profile-less v1 keeps rendering when a boundary title cannot meet strict composition', () => {
+  const d = load('architecture');
+  delete d.meta.quality_profile;
+  d.meta.viewBox = [500, 400];
+  d.components = [{
+    id: 'narrow',
+    type: 'backend',
+    label: 'Narrow',
+    pos: [330, 100],
+    size: [128, 60],
+  }];
+  delete d.meta.views;
+  d.connections = [];
+  d.cards = [];
+  d.boundaries = [{
+    kind: 'region',
+    label: 'A boundary title that cannot fit its narrow authored frame',
+    wraps: ['narrow'],
+    pad: 0,
+  }];
+
+  const { code, stderr } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+});
+
+test('architecture: profile-less v1 keeps legacy boundary geometry at the top edge', () => {
+  const d = load('architecture');
+  delete d.meta.quality_profile;
+  d.meta.viewBox = [500, 400];
+  d.components = [{
+    id: 'near-top',
+    type: 'backend',
+    label: 'Near top',
+    pos: [120, 22],
+    size: [128, 60],
+  }];
+  delete d.meta.views;
+  d.connections = [];
+  d.cards = [];
+  d.boundaries = [{
+    kind: 'region',
+    label: 'Legacy top edge',
+    wraps: ['near-top'],
+    pad: 0,
+  }];
+
+  const { code, stderr } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+});
+
+test('architecture: deployment ownership requires nested membership geometry to agree', () => {
+  const d = JSON.parse(fs.readFileSync(
+    path.join(skillRoot, 'examples/production-deployment.architecture.json'),
+    'utf8',
+  ));
+  d.boundaries.find((boundary) => boundary.label === 'private application network').pad = 260;
+  const { code, stderr } = render('architecture', d);
+  assert.notEqual(code, 0);
+  assert.match(stderr, /final frames partially overlap/);
+  assert.match(stderr, /adjust wraps, pad, or component positions/);
+});
+
+test('architecture: boundary labels reserve readable space above wrapped components', () => {
+  const d = load('architecture');
+  d.boundaries = [{
+    kind: 'security-group',
+    label: 'Tool effects and permissions',
+    wraps: ['lb', 'api'],
+    pad: 14,
+  }];
+
+  const { code, stderr, outPath } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  const label = html.match(
+    /<text data-boundary-label="" x="[^"]+" y="([^"]+)" class="t-security" font-size="[^"]+" font-weight="600">Tool effects and permissions<\/text>/,
+  );
+  assert.ok(label, 'expected the security boundary label');
+  const labelBaseline = Number(label[1]);
+  const firstWrappedNodeY = Math.min(
+    workflowNodeRect(html, 'lb').y,
+    workflowNodeRect(html, 'api').y,
+  );
+  assert.ok(
+    labelBaseline <= firstWrappedNodeY - 4,
+    `expected the boundary label baseline (${labelBaseline}) to clear the first wrapped node (${firstWrappedNodeY})`,
+  );
+});
+
+test('architecture: auto viewBox keeps expanded boundary titles readable at desktop scale', () => {
+  const d = load('architecture');
+  delete d.meta.viewBox;
+  d.meta.quality_profile = 'showcase';
+  delete d.meta.views;
+  d.components = [{
+    id: 'node',
+    type: 'backend',
+    label: 'Current node',
+    pos: [800, 100],
+    size: [120, 60],
+  }];
+  d.connections = [];
+  d.cards = [];
+  d.boundaries = [{
+    kind: 'region',
+    label: 'Disaster recovery boundary Disaster recovery boundary Disaster recovery boundary',
+    wraps: ['node'],
+    pad: 30,
+  }];
+
+  const { code, stderr, outPath } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  const viewBoxWidth = Number(html.match(/\bviewBox="0 0 ([\d.]+) [\d.]+"/)?.[1]);
+  const sourceFontPx = Number(html.match(/<text data-boundary-label[^>]*font-size="([\d.]+)"/)?.[1]);
+  const projectedFontPx = sourceFontPx * Math.min(1, 930 / viewBoxWidth);
+  assert.ok(
+    projectedFontPx >= 6,
+    `expected the final ${viewBoxWidth}px viewBox to project its ${sourceFontPx}px boundary title at 6px or larger, got ${projectedFontPx}px`,
+  );
+});
+
+test('architecture: boundary labels and their masks paint above relationship routes', () => {
+  const d = load('architecture');
+  const { code, stderr, outPath } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  const lastRoute = html.lastIndexOf('data-composition-points=');
+  const firstBoundaryLabel = html.indexOf('data-graph-role="structural-frame-label"');
+  assert.ok(lastRoute >= 0, 'expected at least one rendered relationship route');
+  assert.ok(firstBoundaryLabel >= 0, 'expected a foreground boundary label group');
+  assert.ok(
+    firstBoundaryLabel > lastRoute,
+    'boundary labels must paint after relationship routes so routes cannot cross the title text',
+  );
+  assert.match(
+    html.slice(firstBoundaryLabel, firstBoundaryLabel + 500),
+    /data-graph-role="structural-frame-label-mask"/,
+    'expected an opaque mask behind the foreground boundary title',
+  );
+});
+
+test('architecture: nested boundary title rails stay inside frames and avoid labels and nodes', () => {
+  const d = JSON.parse(fs.readFileSync(
+    path.join(skillRoot, 'examples/production-deployment.architecture.json'),
+    'utf8',
+  ));
+  const { code, stderr, outPath } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  const masks = boundaryTitleMasks(html);
+  assert.equal(masks.length, d.boundaries.length);
+
+  for (const mask of masks) {
+    assert.ok(
+      rectContainsRect(boundaryFrameRect(html, mask.index), mask),
+      `boundary title mask ${mask.index} must stay inside its frame: ${JSON.stringify(mask)}`,
+    );
+    for (const component of d.components) {
+      assert.equal(
+        rectanglesOverlap(mask, workflowNodeRect(html, component.id)),
+        false,
+        `boundary title mask ${mask.index} overlaps component ${component.id}`,
+      );
+    }
+  }
+
+  for (let left = 0; left < masks.length; left += 1) {
+    for (let right = left + 1; right < masks.length; right += 1) {
+      assert.equal(
+        rectanglesOverlap(masks[left], masks[right]),
+        false,
+        `boundary title masks ${left} and ${right} overlap`,
+      );
+    }
+  }
+});
+
+test('architecture: boundary title masks cannot obscure connection labels', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Boundary and connection labels', quality_profile: 'standard', viewBox: [700, 500] },
+    components: [
+      { id: 'scoped', type: 'backend', label: 'Scoped', pos: [250, 100], size: [120, 60] },
+      { id: 'source', type: 'external', label: 'Source', pos: [50, 300], size: [100, 50] },
+      { id: 'target', type: 'external', label: 'Target', pos: [500, 300], size: [100, 50] },
+    ],
+    boundaries: [{ kind: 'region', label: 'Runtime scope', wraps: ['scoped'] }],
+    connections: [{
+      from: 'source',
+      to: 'target',
+      label: 'Route label',
+      route: 'straight',
+      labelAt: [270, 88],
+    }],
+  };
+
+  const { code, stderr } = render('architecture', d);
+  assert.notEqual(code, 0);
+  assert.match(stderr, /Boundary label "Runtime scope" overlaps connection label "Route label"/);
+  assert.match(stderr, /labelAt\/labelDx\/labelDy\/labelSegment/);
+});
+
+// ---- sublabel/tag shrink-to-fit: the render half of the same rule ----
+// Validation only rejects text that cannot fit even at its legible minimum.
+// Everything between "fits at the preferred size" and that floor must shrink,
+// not overflow — otherwise the common case still paints over its neighbours.
+const SHRINK_CASES = [
+  // [mode, mutate(doc), preferredFontSize, selector for the sublabel <text>]
+  ['architecture', (d) => { d.components[0].sublabel = 'Browser and mobile apps'; }, 9],
+  ['sequence', (d) => {
+    d.meta.column_fit = 'fixed';
+    d.participants[0].sublabel = 'long browser session';
+  }, 7],
+  ['dataflow', (d) => { d.nodes[0].sublabel = 'browser SDK and mobile SDK'; }, 7],
+  ['lifecycle', (d) => { d.states[0].sublabel = 'request accepted and queued'; }, 7],
+];
+
+for (const [mode, mutate, preferred] of SHRINK_CASES) {
+  test(`${mode}: an over-long sublabel shrinks to fit instead of overflowing`, () => {
+    const d = load(mode);
+    mutate(d);
+    const { code, stderr, outPath } = render(mode, d);
+    assert.equal(code, 0, stderr);
+    const html = fs.readFileSync(outPath, 'utf8');
+    const sub = html.match(/<text data-detail="context"[^>]*font-size="([\d.]+)"[^>]*>/);
+    assert.ok(sub, 'expected a sublabel <text> in the rendered SVG');
+    const fontSize = Number(sub[1]);
+    assert.ok(
+      fontSize < preferred,
+      `expected the sublabel to shrink below the ${preferred}px preferred size, got ${fontSize}`,
+    );
+    assert.ok(fontSize >= 6, `expected the sublabel to stay legible, got ${fontSize}`);
+  });
+}
+
+const TAG_SHRINK_CASES = [
+  // [mode, collection, tag, preferredFontSize]
+  ['architecture', 'components', 'owner: platform operations team', 7],
+  ['dataflow', 'nodes', 'owner: analytics platform', 7],
+  ['lifecycle', 'states', 'owner: platform operations pod', 7],
+  ['workflow', 'nodes', 'owner: runtime execution squad A', 7],
+];
+
+for (const [mode, collection, tag, preferred] of TAG_SHRINK_CASES) {
+  test(`${mode}: an over-long tag shrinks to fit instead of overflowing`, () => {
+    const d = load(mode);
+    d[collection][0].tag = tag;
+    const { code, stderr, outPath } = render(mode, d);
+    assert.equal(code, 0, stderr);
+    const html = fs.readFileSync(outPath, 'utf8');
+    const escapedTag = tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const match = html.match(new RegExp(
+      `<text data-detail="fine"[^>]*font-size="([\\d.]+)"[^>]*>${escapedTag}</text>`,
+    ));
+    assert.ok(match, `expected a tag <text> for "${tag}" in the rendered SVG`);
+    const fontSize = Number(match[1]);
+    assert.ok(
+      fontSize < preferred,
+      `expected the tag to shrink below the ${preferred}px preferred size, got ${fontSize}`,
+    );
+    assert.ok(fontSize >= 6, `expected the tag to stay legible, got ${fontSize}`);
+  });
+}
+
+test('contract: a too-wide label is never redirected into sublabel', () => {
+  // Every renderer used to advise "move detail to sublabel" for an over-long
+  // label. Sublabels are measured now, so that advice would move the problem
+  // rather than fix it.
+  const LABELS = {
+    workflow: 'An Extremely Long Node Label That Overflows',
+    sequence: 'An Extremely Long Participant Label That Overflows',
+    dataflow: 'An Extremely Long Node Label That Overflows',
+    lifecycle: 'An Extremely Long State Label That Overflows',
+    architecture: 'An Extremely Long Component Label Overflow',
+  };
+  const FIELD = {
+    workflow: 'nodes', sequence: 'participants', dataflow: 'nodes',
+    lifecycle: 'states', architecture: 'components',
+  };
+  for (const [mode, label] of Object.entries(LABELS)) {
+    const d = load(mode);
+    d[FIELD[mode]][0].label = label;
+    const { code, stderr } = render(mode, d);
+    assert.notEqual(code, 0, `${mode}: expected non-zero exit; stderr:\n${stderr}`);
+    assert.ok(stderr.includes('wider than'), `${mode}: expected a width message:\n${stderr}`);
+    assert.ok(
+      !/move detail to sublabel/.test(stderr),
+      `${mode}: label advice still points at the measured sublabel field:\n${stderr}`,
+    );
+  }
+});
+
+// ---- error-message contract: threshold + remediation, not just a path ----
+test('contract: short-edge message carries both the px minimum and a fix verb', () => {
+  const d = load('workflow');
+  // Force a too-short labeled edge between adjacent same-lane columns.
+  d.nodes.push({ id: 'a1', lane: d.nodes[0].lane, col: 0, type: 'backend', label: 'A' });
+  d.nodes.push({ id: 'a2', lane: d.nodes[0].lane, col: 0, type: 'backend', label: 'B', yOffset: 30 });
+  d.edges.push({ from: 'a1', to: 'a2', label: 'x', route: 'straight' });
+  const { stderr } = render('workflow', d);
+  // Whatever rule fires, the messages must remain actionable (threshold + verb).
+  assert.match(stderr, /\d+px|at least \d+|0\.\.\d+|less than/);
+});
+
+test('contract: ajv path errors are annotated with the element id', () => {
+  const d = load('workflow');
+  d.nodes[3].colour = 'red'; // unknown property → ajv additionalProperties
+  const { stderr } = render('workflow', d);
+  // Only meaningful when ajv is installed; skip the assertion in degraded mode.
+  if (!/schema validation failed/.test(stderr)) return;
+  assert.match(stderr, /id\/label:/);
+});
+
+test('workflow: same-lane offset auto edge stays orthogonal', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: { title: 'Same-lane offset route' },
+    lanes: [{ id: 'main', label: 'Main lane' }],
+    nodes: [
+      { id: 'left', lane: 'main', col: 1, type: 'backend', label: 'A', width: 32, height: 38, yOffset: -14 },
+      { id: 'right', lane: 'main', col: 2, type: 'backend', label: 'B', width: 32, height: 38, yOffset: 14 },
+    ],
+    edges: [{ from: 'left', to: 'right' }],
+  };
+  const { code, stderr, outPath } = render('workflow', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  assert.doesNotMatch(html, /M 236 105 L 284 133/);
+  assert.match(html, /M 236 105 L 260 105 L 260 133 L 284 133/);
+});
+
+test('workflow: automatic routing uses one bend and avoids every node border', () => {
+  const d = JSON.parse(fs.readFileSync(
+    path.join(skillRoot, 'test/fixtures/automatic-routing-node-border-clearance.workflow.json'),
+    'utf8',
+  ));
+  const { code, stderr, outPath } = render('workflow', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  const points = workflowEdgePoints(html, 'stdin');
+  const target = workflowNodeRect(html, 'team_send');
+  assert.equal(points.length, 3, `expected one bend, received ${JSON.stringify(points)}`);
+  assert.equal(points[0][0], points[1][0], 'edge must leave the source vertically');
+  assert.ok(points[1][1] < points[0][1], 'edge must leave the source through its top side');
+  assert.equal(points[1][1], points[2][1], 'edge must enter the target horizontally');
+  assert.ok(points[2][0] > points[1][0], 'edge must enter the target through its left side');
+  assert.equal(points[2][0], target.x, 'edge must stop at the target border');
+  assert.ok(
+    points[2][1] > target.y && points[2][1] < target.y + target.height,
+    'edge must meet the target inside its left-side anchor range',
+  );
+  assertWorkflowEdgesAvoidAllNodeBorders(html, d);
+
+  const [labelX, labelY] = workflowEdgeLabelPoint(html, 'stdin');
+  assert.equal(labelX, points[0][0], 'the label should use the longer vertical segment');
+  assert.ok(labelY > points[1][1] && labelY < points[0][1], 'the label should stay inside that segment');
+});
+
+test('workflow: shared automatic endpoints avoid every node border', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: { title: 'Shared endpoint border invariant' },
+    lanes: [
+      { id: 'target-lane', label: 'Target' },
+      { id: 'source-lane', label: 'Sources' },
+    ],
+    nodes: [
+      { id: 'target', lane: 'target-lane', col: 2, type: 'backend', label: 'Target' },
+      { id: 'source-left', lane: 'source-lane', col: 1, type: 'backend', label: 'Left' },
+      { id: 'source-right', lane: 'source-lane', col: 3, type: 'backend', label: 'Right' },
+    ],
+    edges: [
+      { id: 'left-to-target', from: 'source-left', to: 'target' },
+      { id: 'right-to-target', from: 'source-right', to: 'target' },
+    ],
+  };
+  const { code, stderr, outPath } = render('workflow', d);
+  assert.equal(code, 0, stderr);
+  assertWorkflowEdgesAvoidAllNodeBorders(fs.readFileSync(outPath, 'utf8'), d);
+});
+
+test('workflow: blocked first one-bend candidate selects the clear one-bend orientation', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: { title: 'Blocked one-bend candidate', quality_profile: 'showcase' },
+    lanes: [
+      { id: 'target-lane', label: 'Target' },
+      { id: 'obstacle-lane', label: 'Obstacle' },
+      { id: 'source-lane', label: 'Source' },
+    ],
+    nodes: [
+      { id: 'target', lane: 'target-lane', col: 3, type: 'backend', label: 'Target' },
+      { id: 'obstacle', lane: 'obstacle-lane', col: 1, type: 'security', label: 'Obstacle' },
+      { id: 'source', lane: 'source-lane', col: 1, type: 'backend', label: 'Source' },
+    ],
+    edges: [{ id: 'clear-corner', from: 'source', to: 'target' }],
+  };
+  const { code, stderr, outPath } = render('workflow', d);
+  assert.equal(code, 0, stderr);
+  const points = workflowEdgePoints(fs.readFileSync(outPath, 'utf8'), 'clear-corner');
+  assert.equal(points.length, 3, `expected the alternate one-bend route, received ${JSON.stringify(points)}`);
+  assert.equal(points[0][1], points[1][1], 'blocked vertical-first candidate must switch to horizontal-first');
+  assert.ok(points[1][0] > points[0][0], 'edge must leave the source through its right side');
+  assert.equal(points[1][0], points[2][0], 'edge must enter the target vertically');
+  assert.ok(points[2][1] < points[1][1], 'edge must enter the target through its bottom side');
+});
+
+test('workflow: explicit drop routing remains authoritative over the one-bend preference', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: { title: 'Explicit route compatibility', quality_profile: 'showcase' },
+    lanes: [
+      { id: 'target-lane', label: 'Target' },
+      { id: 'source-lane', label: 'Source' },
+    ],
+    nodes: [
+      { id: 'target', lane: 'target-lane', col: 3, type: 'backend', label: 'Target' },
+      { id: 'source', lane: 'source-lane', col: 1, type: 'backend', label: 'Source' },
+    ],
+    edges: [{
+      id: 'authored-drop',
+      from: 'source',
+      to: 'target',
+      route: 'drop',
+      fromSide: 'top',
+      toSide: 'bottom',
+    }],
+  };
+  const { code, stderr, outPath } = render('workflow', d);
+  assert.equal(code, 0, stderr);
+  const points = workflowEdgePoints(fs.readFileSync(outPath, 'utf8'), 'authored-drop');
+  assert.equal(points.length, 4, `explicit drop route was replaced: ${JSON.stringify(points)}`);
+  assert.equal(points[0][0], points[1][0]);
+  assert.equal(points[1][1], points[2][1]);
+  assert.equal(points[2][0], points[3][0]);
+});
+
+test('workflow: authored endpoint sides that follow a border are rejected generically', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: { title: 'Authored endpoint border run' },
+    lanes: [
+      { id: 'target-lane', label: 'Target' },
+      { id: 'source-lane', label: 'Source' },
+    ],
+    nodes: [
+      { id: 'target', lane: 'target-lane', col: 3, type: 'backend', label: 'Target' },
+      { id: 'source', lane: 'source-lane', col: 1, type: 'backend', label: 'Source' },
+    ],
+    edges: [{
+      id: 'invalid-drop',
+      from: 'source',
+      to: 'target',
+      route: 'drop',
+      fromSide: 'right',
+      toSide: 'left',
+    }],
+  };
+  const { code, stderr } = render('workflow', d);
+  assert.notEqual(code, 0);
+  assert.match(stderr, /\[clean-flow\/endpoint-side-direction\] workflow edges\[0\] id "invalid-drop"/);
+  assert.match(stderr, /cross node borders perpendicularly/);
+});
+
+test('dataflow: authored endpoint sides that follow a border are rejected generically', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'dataflow',
+    meta: { title: 'Data-flow endpoint border run' },
+    stages: [{ label: 'Source' }, { label: 'Target' }],
+    nodes: [
+      { id: 'source', stage: 0, row: 0, type: 'backend', label: 'Source' },
+      { id: 'target', stage: 1, row: 2, type: 'database', label: 'Target' },
+    ],
+    flows: [{
+      id: 'invalid-bottom',
+      from: 'source',
+      to: 'target',
+      label: 'payload',
+      route: 'bottom-channel',
+      fromSide: 'right',
+      toSide: 'left',
+    }],
+  };
+  const { code, stderr } = render('dataflow', d);
+  assert.notEqual(code, 0);
+  assert.match(stderr, /\[clean-flow\/endpoint-side-direction\] dataflow flows\[0\] id "invalid-bottom"/);
+  assert.match(stderr, /cross node borders perpendicularly/);
+});
+
+test('lifecycle: automatic cross-lane routes avoid every state border', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'lifecycle',
+    meta: { title: 'Lifecycle endpoint border invariant' },
+    lanes: [
+      { id: 'main', label: 'Main' },
+      { id: 'terminal', label: 'Terminal' },
+    ],
+    states: [
+      { id: 'target', lane: 'main', col: 3, type: 'success', label: 'Target' },
+      { id: 'source', lane: 'terminal', col: 1, type: 'active', label: 'Source' },
+    ],
+    transitions: [{ id: 'automatic-transition', from: 'source', to: 'target' }],
+  };
+  const { code, stderr, outPath } = render('lifecycle', d);
+  assert.equal(code, 0, stderr);
+  assertRelationshipsAvoidAllNodeBorders(
+    fs.readFileSync(outPath, 'utf8'),
+    d.transitions,
+    d.states,
+  );
+});
+
+function tangentViaLifecycle() {
+  return {
+    schema_version: 1,
+    diagram_type: 'lifecycle',
+    meta: { title: 'Legacy tangent via compatibility' },
+    lanes: [
+      { id: 'main', label: 'Main' },
+      { id: 'terminal', label: 'Terminal' },
+    ],
+    states: [
+      { id: 'source', lane: 'main', col: 1, type: 'active', label: 'Source' },
+      { id: 'target', lane: 'terminal', col: 0, type: 'success', label: 'Target' },
+    ],
+    transitions: [{
+      id: 'legacy-via',
+      from: 'source',
+      to: 'target',
+      fromSide: 'bottom',
+      toSide: 'top',
+      via: [[320, 188], [320, 430], [402, 430]],
+    }],
+  };
+}
+
+test('lifecycle: legacy tangent via is rendered exactly instead of silently rewritten', () => {
+  const d = tangentViaLifecycle();
+  const { code, stderr, outPath } = render('lifecycle', d);
+  assert.equal(code, 0, stderr);
+  assert.deepEqual(workflowEdgePoints(fs.readFileSync(outPath, 'utf8'), 'legacy-via'), [
+    [248, 188], [320, 188], [320, 430], [402, 430], [402, 450],
+  ]);
+});
+
+for (const qualityProfile of ['standard', 'showcase']) {
+  test(`lifecycle: ${qualityProfile} keeps an authored tangent via authoritative`, () => {
+    const d = tangentViaLifecycle();
+    d.meta.quality_profile = qualityProfile;
+    const { code, stderr, outPath } = render('lifecycle', d);
+    assert.equal(code, 0, stderr);
+    assert.deepEqual(workflowEdgePoints(fs.readFileSync(outPath, 'utf8'), 'legacy-via'), [
+      [248, 188], [320, 188], [320, 430], [402, 430], [402, 450],
+    ]);
+  });
+
+  test(`lifecycle: public validate accepts an authoritative authored tangent via in ${qualityProfile}`, () => {
+    const d = tangentViaLifecycle();
+    d.meta.quality_profile = qualityProfile;
+    const { code, result } = validateCli('lifecycle', d);
+    assert.equal(code, 0, JSON.stringify(result, null, 2));
+    assert.equal(result.ok, true);
+  });
+}
+
+test('workflow: explicit labelAt remains authoritative on an automatic one-bend edge', () => {
+  const d = JSON.parse(fs.readFileSync(
+    path.join(skillRoot, 'test/fixtures/automatic-routing-node-border-clearance.workflow.json'),
+    'utf8',
+  ));
+  d.edges[0].labelAt = [350, 166];
+  const { code, stderr, outPath } = render('workflow', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  assert.deepEqual(workflowEdgeLabelPoint(html, 'stdin'), [350, 166]);
+});
+
+test('workflow: bounded font fitting keeps an ordinary long sublabel inside its node', () => {
+  const d = load('workflow');
+  d.nodes[0].width = 92;
+  d.nodes[0].sublabel = 'shell / browser / MCP';
+  const { code, stderr, outPath } = render('workflow', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  assert.match(html, /font-size="6\.6"[^>]*>shell \/ browser \/ MCP<\/text>/);
+});
+
+test('workflow: edge crossing a non-endpoint node is rejected', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: { title: 'Crossing edge route', quality_profile: 'standard' },
+    lanes: [{ id: 'main', label: 'Main lane' }],
+    nodes: [
+      { id: 'left', lane: 'main', col: 0, type: 'backend', label: 'Left', width: 60 },
+      { id: 'middle', lane: 'main', col: 2, type: 'database', label: 'Middle', width: 70 },
+      { id: 'right', lane: 'main', col: 4, type: 'backend', label: 'Right', width: 60 },
+    ],
+    edges: [{ from: 'left', to: 'right', route: 'straight' }],
+  };
+  const { code, stderr } = render('workflow', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /crosses node "middle"/);
+  assert.match(stderr, /fromSide\/toSide|channel|lane\/column/);
+});
+
+test('architecture: Clean Flow Gate rejects a connection through a component', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Opaque component crossing', quality_profile: 'standard' },
+    components: [
+      { id: 'left', type: 'frontend', label: 'Left', pos: [60, 120], size: [100, 54] },
+      { id: 'middle', type: 'security', label: 'Middle', pos: [270, 120], size: [100, 54] },
+      { id: 'right', type: 'backend', label: 'Right', pos: [480, 120], size: [100, 54] },
+    ],
+    connections: [{ id: 'direct', from: 'left', to: 'right', route: 'straight' }],
+  };
+  const { code, stderr } = render('architecture', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[clean-flow\/edge-through-node\] architecture connections\[0\] id "direct"/);
+  assert.match(stderr, /crosses component "middle"/);
+  assert.match(stderr, /segment 0 .*2px clearance/);
+});
+
+test('dataflow: showcase rejects a relationship label that hides another route', () => {
+  const d = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', 'event-stream.dataflow.json'), 'utf8'));
+  const approvedReplay = d.flows.find((flow) => flow.label === 'approved replay');
+  delete approvedReplay.labelAt;
+  delete approvedReplay.labelDx;
+  delete approvedReplay.labelDy;
+  delete approvedReplay.labelSegment;
+  const { code, stderr } = render('dataflow', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[composition\/label-route-clearance\] showcase dataflow/);
+  assert.match(stderr, /approved replay.*failure sample/);
+  assert.match(stderr, /labelAt.*labelDx.*labelDy.*labelSegment/);
+});
+
+test('dataflow: validator and SVG share the 27px CJK/emoji classification mask', () => {
+  const d = load('dataflow');
+  const flow = d.flows[0];
+  flow.label = '写入🚀';
+  flow.classification = '机密🔐';
+  const { code, stderr, outPath } = render('dataflow', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  const group = html.match(/<g data-detail="context"[^>]*data-edge-id="web-clickstream"[^>]*>[\s\S]*?<\/g>/)?.[0] || '';
+  assert.match(group, /data-edge-label="写入🚀"/);
+  assert.match(group, /<rect x="[^\"]+" y="[^\"]+" width="41\.4" height="27" rx="4" class="c-mask"\/>/);
+  assert.match(group, />机密🔐<\/text>/);
+});
+
+test('architecture: showcase rejects a connection label that hides another route', () => {
+  const d = load('architecture');
+  d.connections[0].labelAt = [620, 330];
+  const { code, stderr } = render('architecture', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[composition\/label-route-clearance\] showcase architecture/);
+  assert.match(stderr, /HTTPS.*lb-to-api/);
+});
+
+test('workflow: showcase rejects an edge label that hides another route', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: {
+      title: 'Workflow label-route clearance',
+      quality_profile: 'showcase',
+      viewBox: [720, 400],
+      legend: { mode: 'hidden' },
+    },
+    lanes: [
+      { id: 'label', label: 'Label owner' },
+      { id: 'route', label: 'Other route' },
+    ],
+    nodes: [
+      { id: 'a', lane: 'label', col: 0, type: 'backend', label: 'A' },
+      { id: 'b', lane: 'label', col: 2, type: 'backend', label: 'B' },
+      { id: 'c', lane: 'route', col: 0, type: 'backend', label: 'C' },
+      { id: 'd', lane: 'route', col: 2, type: 'backend', label: 'D' },
+    ],
+    edges: [
+      { id: 'labeled-edge', from: 'a', to: 'b', label: 'plan', labelAt: [200, 243] },
+      { id: 'other-route', from: 'c', to: 'd' },
+    ],
+  };
+  const { code, stderr } = render('workflow', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[composition\/label-route-clearance\] showcase workflow/);
+  assert.match(stderr, /plan.*other-route/);
+});
+
+test('lifecycle: showcase rejects a transition label that hides another route', () => {
+  const d = load('lifecycle');
+  d.transitions[0].label = 'approval gate';
+  d.transitions[0].labelAt = [556, 250];
+  const { code, stderr } = render('lifecycle', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[composition\/label-route-clearance\] showcase lifecycle/);
+  assert.match(stderr, /approval gate.*review-blocked/);
+});
+
+test('sequence: showcase rejects a message label that hides an adjacent route', () => {
+  const d = load('sequence');
+  d.messages = d.messages.slice(0, 2);
+  d.messages[0].label = 'customer authorization context';
+  d.messages[0].y = 250;
+  d.messages[1].label = 'ok';
+  d.messages[1].y = 245;
+  d.segments = [];
+  d.activations = [];
+  const { code, stderr } = render('sequence', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[composition\/label-route-clearance\] showcase sequence/);
+  assert.match(stderr, /customer authorization context.*dashboard-request/);
+});
+
+function autoRoutePassThroughDocument(connection) {
+  return {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Auto-route pass-through regression' },
+    components: [
+      { id: 'api', type: 'backend', label: 'API', pos: [400, 280], size: [160, 76] },
+      { id: 'cache', type: 'database', label: 'Cache', pos: [645, 130], size: [130, 60] },
+      { id: 'queue', type: 'cloud', label: 'Queue', pos: [880, 130] },
+    ],
+    connections: [connection],
+  };
+}
+
+test('architecture: default auto route selects a safe orthogonal candidate around an unrelated component', () => {
+  const d = autoRoutePassThroughDocument({ from: 'api', to: 'queue', variant: 'dashed' });
+  const { code, stderr, outPath } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  assert.match(html, /data-composition-points="560,318;856,318;856,160;880,160"/);
+});
+
+test('architecture: auto route enters explicit top and bottom ports perpendicularly', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Endpoint direction regression' },
+    components: [
+      { id: 'cli-agents', type: 'external', label: 'CLI Agents', pos: [300, 100], size: [100, 60] },
+      { id: 'tasks-watch', type: 'backend', label: 'Tasks Watcher', pos: [100, 240], size: [100, 60] },
+    ],
+    connections: [
+      { id: 'tasks-file', from: 'cli-agents', to: 'tasks-watch', variant: 'dashed', fromSide: 'bottom', toSide: 'top' },
+    ],
+  };
+  const { code, stderr, outPath } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  assert.match(html, /data-composition-points="350,160;350,200;150,200;150,240"/);
+});
+
+test('architecture: auto route preserves inferred side normals when the primary dogleg is blocked', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Inferred endpoint direction regression' },
+    components: [
+      { id: 'workspace', type: 'frontend', label: 'Workspace UI', pos: [40, 300], size: [120, 60] },
+      { id: 'runtime-server', type: 'backend', label: 'Runtime Server', pos: [220, 300], size: [120, 60] },
+      { id: 'runtime-store', type: 'backend', label: 'Runtime Store', pos: [400, 300], size: [120, 60] },
+      { id: 'stream-hub', type: 'messagebus', label: 'Terminal Stream Hub', pos: [700, 100], size: [120, 60] },
+    ],
+    connections: [
+      { id: 'terminal-return', from: 'stream-hub', to: 'workspace' },
+    ],
+  };
+  const { code, stderr, outPath } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  assert.match(html, /data-composition-points="700,130;184,130;184,330;160,330"/);
+  assert.doesNotMatch(html, /data-composition-points="700,130;700,230;160,230;160,330"/);
+});
+
+test('architecture: explicit via cannot run tangentially into an authored top port', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Tangent endpoint regression' },
+    components: [
+      { id: 'cli-agents', type: 'external', label: 'CLI Agents', pos: [300, 100], size: [100, 60] },
+      { id: 'tasks-watch', type: 'backend', label: 'Tasks Watcher', pos: [100, 240], size: [100, 60] },
+    ],
+    connections: [
+      {
+        id: 'tasks-file',
+        from: 'cli-agents',
+        to: 'tasks-watch',
+        variant: 'dashed',
+        fromSide: 'bottom',
+        toSide: 'top',
+        via: [[350, 200], [100, 200], [100, 240]],
+      },
+    ],
+  };
+  const { code, stderr } = render('architecture', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[clean-flow\/endpoint-side-direction\] architecture connections\[0\] id "tasks-file"/);
+  assert.match(stderr, /final segment 3 \[100, 240\] -> \[150, 240\]/);
+  assert.match(stderr, /toSide "top".*vertical downward from above/);
+});
+
+test('architecture: explicit orthogonal route remains authoritative when it crosses a component', () => {
+  const d = autoRoutePassThroughDocument({
+    from: 'api',
+    to: 'queue',
+    variant: 'dashed',
+    route: 'orthogonal-h',
+  });
+  const { code, stderr } = render('architecture', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /connections\[0\] "api" -> "queue" crosses component "cache"/);
+});
+
+test('architecture: auto route still fails closed when doglegs and side-aware bridges are blocked', () => {
+  const d = autoRoutePassThroughDocument({ from: 'api', to: 'queue', variant: 'dashed' });
+  d.components.push({ id: 'guard', type: 'security', label: 'Guard', pos: [825, 215], size: [70, 50] });
+  const { code, stderr } = render('architecture', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /connections\[0\] "api" -> "queue" crosses component "cache"/);
+});
+
+test('architecture: explicit waypoints around an obstacle remain valid by default', () => {
+  const d = autoRoutePassThroughDocument({
+    from: 'api',
+    to: 'queue',
+    variant: 'dashed',
+    fromSide: 'right',
+    toSide: 'top',
+    via: [[620, 318], [620, 100], [940, 100]],
+  });
+  const { code, stderr } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+});
+
+test('architecture: showcase rejects an unrelated proper edge crossing', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Showcase crossing', quality_profile: 'showcase' },
+    components: [
+      { id: 'a', type: 'frontend', label: 'A', pos: [60, 80], size: [60, 40] },
+      { id: 'b', type: 'backend', label: 'B', pos: [360, 260], size: [60, 40] },
+      { id: 'c', type: 'database', label: 'C', pos: [60, 260], size: [60, 40] },
+      { id: 'd', type: 'external', label: 'D', pos: [360, 80], size: [60, 40] },
+    ],
+    connections: [
+      { id: 'down-right', from: 'a', to: 'b', route: 'orthogonal-h' },
+      { id: 'up-right', from: 'c', to: 'd', route: 'orthogonal-v', fromSide: 'top', toSide: 'bottom' },
+    ],
+  };
+  const { code, stderr } = render('architecture', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[composition\/proper-crossing\] showcase architecture/);
+  assert.match(stderr, /connections\[0\] id "down-right"/);
+  assert.match(stderr, /connections\[1\] id "up-right"/);
+  assert.match(stderr, /at \[240, 190\]/);
+  assert.match(stderr, /segments 1 and 1/);
+  assert.match(stderr, /route\/via|fromSide\/toSide/);
+});
+
+test('architecture: showcase preserves a straight-through explicit waypoint as an authored touch', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: {
+      title: 'Forward-collinear waypoint compatibility',
+      quality_profile: 'showcase',
+      viewBox: [600, 320],
+      legend: { mode: 'hidden' },
+    },
+    components: [
+      { id: 'a', type: 'backend', label: 'A', pos: [50, 100], size: [80, 60] },
+      { id: 'b', type: 'backend', label: 'B', pos: [450, 100], size: [80, 60] },
+      { id: 'c', type: 'backend', label: 'C', pos: [260, 0], size: [80, 60] },
+      { id: 'd', type: 'backend', label: 'D', pos: [260, 200], size: [80, 60] },
+    ],
+    connections: [
+      { id: 'horizontal', from: 'a', to: 'b', via: [[300, 130]] },
+      { id: 'vertical', from: 'c', to: 'd' },
+    ],
+  };
+
+  const { code, stderr } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+});
+
+test('architecture: standard keeps the same proper crossing renderable', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Standard crossing', quality_profile: 'standard' },
+    components: [
+      { id: 'a', type: 'frontend', label: 'A', pos: [60, 80], size: [60, 40] },
+      { id: 'b', type: 'backend', label: 'B', pos: [360, 260], size: [60, 40] },
+      { id: 'c', type: 'database', label: 'C', pos: [60, 260], size: [60, 40] },
+      { id: 'd', type: 'external', label: 'D', pos: [360, 80], size: [60, 40] },
+    ],
+    connections: [
+      { from: 'a', to: 'b', route: 'orthogonal-h' },
+      { from: 'c', to: 'd', route: 'orthogonal-v', fromSide: 'top', toSide: 'bottom' },
+    ],
+  };
+  const { code, stderr } = render('architecture', d);
+  assert.equal(code, 0, stderr);
+});
+
+function ambiguousCorridorDocument(profile) {
+  return {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Ambiguous corridor', quality_profile: profile },
+    components: [
+      { id: 'a', type: 'frontend', label: 'A', pos: [40, 60], size: [60, 40] },
+      { id: 'b', type: 'backend', label: 'B', pos: [400, 60], size: [60, 40] },
+      { id: 'c', type: 'database', label: 'C', pos: [120, 220], size: [60, 40] },
+      { id: 'd', type: 'external', label: 'D', pos: [480, 220], size: [60, 40] },
+    ],
+    connections: [
+      { id: 'first', from: 'a', to: 'b', fromSide: 'right', toSide: 'left', route: 'straight' },
+      { id: 'second', from: 'c', to: 'd', fromSide: 'top', toSide: 'top', via: [[150, 80], [390, 80], [390, 180], [510, 180]] },
+    ],
+  };
+}
+
+test('architecture: showcase rejects an unrelated shared route corridor', () => {
+  const { code, stderr } = render('architecture', ambiguousCorridorDocument('showcase'));
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[composition\/ambiguous-corridor\] showcase architecture/);
+  assert.match(stderr, /connections\[0\] id "first" "a" -> "b" shares a 240px corridor with connections\[1\] id "second" "c" -> "d"/);
+  assert.match(stderr, /\[150, 80\] -> \[390, 80\]/);
+  assert.match(stderr, /do not visually merge/);
+});
+
+test('architecture: standard keeps an ambiguous corridor renderable for repair', () => {
+  const { code, stderr } = render('architecture', ambiguousCorridorDocument('standard'));
+  assert.equal(code, 0, stderr);
+});
+
+test('architecture: route rhythm warns in standard and blocks a showcase micro segment', () => {
+  const base = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Readable turn rhythm' },
+    components: [
+      { id: 'a', type: 'frontend', label: 'A', pos: [60, 80], size: [60, 40] },
+      { id: 'b', type: 'backend', label: 'B', pos: [360, 80], size: [60, 40] },
+    ],
+    connections: [
+      { id: 'tight', from: 'a', to: 'b', fromSide: 'right', toSide: 'bottom', via: [[125, 100], [125, 160], [390, 160]] },
+    ],
+  };
+  const standard = structuredClone(base);
+  standard.meta.quality_profile = 'standard';
+  assert.equal(render('architecture', standard).code, 0);
+
+  const showcase = structuredClone(base);
+  showcase.meta.quality_profile = 'showcase';
+  const { code, stderr } = render('architecture', showcase);
+  assert.notEqual(code, 0);
+  assert.match(stderr, /\[composition\/micro-segment\] showcase architecture connections\[0\] id "tight"/);
+  assert.match(stderr, /5px source-stub segment 0/);
+  assert.match(stderr, /wider corridor|move the component/);
+});
+
+test('architecture: container border run is blocking in standard and showcase', () => {
+  for (const profile of ['standard', 'showcase']) {
+    const d = load('architecture');
+    d.meta.quality_profile = profile;
+    d.connections.find((connection) => connection.id === 'jwt-verification').via = [[620, 142], [620, 270], [735, 270]];
+    const { code, stderr } = render('architecture', d);
+    assert.notEqual(code, 0, `expected ${profile} to reject a border run`);
+    assert.match(stderr, /\[composition\/container-border-run\] architecture connections\[1\] id "jwt-verification"/);
+    assert.match(stderr, /security-group "sg-api :443\/:8000" top border/);
+  }
+});
+
+test('dataflow: stage border run is blocking and the inter-stage gutter passes', () => {
+  const bad = load('dataflow');
+  bad.flows.find((flow) => flow.id === 'web-clickstream').via = [[184, 157], [184, 271]];
+  const failed = render('dataflow', bad);
+  assert.notEqual(failed.code, 0);
+  assert.match(failed.stderr, /\[composition\/container-border-run\] dataflow flows\[0\] id "web-clickstream"/);
+  assert.match(failed.stderr, /stage "Sources" right border for 114px/);
+
+  const clean = load('dataflow');
+  const passed = render('dataflow', clean);
+  assert.equal(passed.code, 0, passed.stderr);
+});
+
+test('sequence: a message cannot masquerade as a time-segment border', () => {
+  const d = load('sequence');
+  d.messages.find((message) => message.id === 'cache-read').y = d.segments[1].from;
+  const { code, stderr } = render('sequence', d);
+  assert.notEqual(code, 0);
+  assert.match(stderr, /\[composition\/container-border-run\] sequence messages\[4\] id "cache-read"/);
+  assert.match(stderr, /segment "Fallback" top border/);
+});
+
+test('dataflow: Clean Flow Gate rejects a flow through an unrelated node', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'dataflow',
+    meta: { title: 'Opaque data node crossing', quality_profile: 'standard' },
+    stages: [{ label: 'Source' }, { label: 'Middle' }, { label: 'Sink' }],
+    nodes: [
+      { id: 'left', type: 'frontend', label: 'Left', stage: 0, row: 1 },
+      { id: 'middle', type: 'security', label: 'Middle', stage: 1, row: 1 },
+      { id: 'right', type: 'database', label: 'Right', stage: 2, row: 1 },
+    ],
+    flows: [{ id: 'direct', from: 'left', to: 'right', label: 'payload', route: 'straight', labelAt: [315, 190] }],
+  };
+  const { code, stderr } = render('dataflow', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[clean-flow\/edge-through-node\] dataflow flows\[0\] id "direct"/);
+  assert.match(stderr, /crosses node "middle"/);
+  assert.match(stderr, /stage\/row/);
+});
+
+test('lifecycle: Clean Flow Gate rejects a transition through an unrelated state', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'lifecycle',
+    meta: { title: 'Opaque state crossing', quality_profile: 'standard' },
+    lanes: [{ id: 'main', label: 'Main' }],
+    states: [
+      { id: 'left', type: 'start', label: 'Left', lane: 'main', col: 0 },
+      { id: 'middle', type: 'waiting', label: 'Middle', lane: 'main', col: 2 },
+      { id: 'right', type: 'success', label: 'Right', lane: 'main', col: 4 },
+    ],
+    transitions: [{ id: 'direct', from: 'left', to: 'right', route: 'straight' }],
+  };
+  const { code, stderr } = render('lifecycle', d);
+  assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+  assert.match(stderr, /\[clean-flow\/edge-through-node\] lifecycle transitions\[0\] id "direct"/);
+  assert.match(stderr, /crosses state "middle"/);
+  assert.match(stderr, /col\/yOffset/);
+});
+
+test('sequence: lifelines and activation bars remain intentional pass-through geometry', () => {
+  const d = load('sequence');
+  const { code, stderr } = render('sequence', d);
+  assert.equal(code, 0, stderr);
+  assert.doesNotMatch(stderr, /Clean Flow Gate/);
+});
+
+test('sequence: segment titles render as foreground badges above their borders', () => {
+  const d = load('sequence');
+  const { code, stderr, outPath } = render('sequence', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  const firstSegment = d.segments[0];
+  const segmentLabelsAt = html.indexOf('<!-- Segment Labels -->');
+  const activationsAt = html.indexOf('<!-- Activations -->');
+  const messagesAt = html.indexOf('<!-- Messages -->');
+
+  assert.ok(segmentLabelsAt > activationsAt, 'segment labels should stay above lifelines, messages, and activations');
+  assert.ok(messagesAt > activationsAt, 'message arrows and labels should stay above activation bars');
+  assert.match(html, new RegExp(`data-graph-role="segment-label"[^>]*data-segment-id="0"`));
+  assert.match(html, new RegExp(`<text x="62" y="${firstSegment.from - 9}"[^>]*>${firstSegment.label}</text>`));
+});
+
+test('sequence: segment title badge clears a nearby first message label', () => {
+  const d = load('sequence');
+  const firstSegment = d.segments[0];
+  const firstMessage = d.messages[0];
+  firstSegment.from = 180;
+  firstMessage.y = firstSegment.from + 5;
+
+  const { code, stderr, outPath } = render('sequence', d);
+  assert.equal(code, 0, stderr);
+  const html = fs.readFileSync(outPath, 'utf8');
+  const segment = html.match(
+    /<g data-graph-role="segment-label" data-segment-id="0">\s*<rect x="([^"]+)" y="([^"]+)" width="([^"]+)" height="([^"]+)"/,
+  );
+  const message = html.match(new RegExp(
+    `<g [^>]*data-edge-id="${firstMessage.id}"[\\s\\S]*?<rect x="([^"]+)" y="([^"]+)" width="([^"]+)" height="([^"]+)"`,
+  ));
+  assert.ok(segment, 'expected the first segment badge rectangle');
+  assert.ok(message, 'expected the first message label rectangle');
+
+  const [segmentX, segmentY, segmentW, segmentH] = segment.slice(1).map(Number);
+  const [messageX, messageY, messageW, messageH] = message.slice(1).map(Number);
+  const overlaps = segmentX < messageX + messageW
+    && segmentX + segmentW > messageX
+    && segmentY < messageY + messageH
+    && segmentY + segmentH > messageY;
+  assert.equal(overlaps, false, 'segment title badge must not cover the first message label');
+});
+
+test('sequence: segment label exceeding segment frame available width fails layout validation with remediation', () => {
+  const d = load('sequence');
+  d.meta.viewBox[0] = 820;
+  d.meta.column_fit = 'fixed';
+  d.segments[0].label = 'Phase 1: Dual-Certificate mTLS Handshake & Distributed Token Verification Protocol Negotiation'.repeat(2);
+
+  const { code, stderr } = render('sequence', d);
+  assert.equal(code, 1);
+  assert.match(stderr, /Segment "Phase 1: Dual-Certificate mTLS Handshake & Distributed Token Verification Protocol NegotiationPhase 1: Dual-Certificate mTLS Handshake & Distributed Token Verification Protocol Negotiation" label \(~992px\) exceeds the segment frame's available width \(716px\) — shorten the label or increase meta\.viewBox\[0\] to at least 1096\./);
+
+  // Remediating by increasing viewBox[0] to the suggested minimum allows it to pass cleanly
+  d.meta.viewBox[0] = 1096;
+  const fixed = render('sequence', d);
+  assert.equal(fixed.code, 0, fixed.stderr);
+});
+
+test('sequence: segment label boundary containment within canvas vs segment frame and exact-fit', () => {
+  // Available width in this fixed-column boundary scenario (viewBox[0] = 820):
+  // frame right edge = 820 - 48 = 772
+  // labelBox.x = 56
+  // availableWidth = 772 - 56 = 716px
+  // 135 ASCII units -> labelW = 135 * 5.2 + 14 = 716px -> label right edge = 56 + 716 = 772px (exact fit)
+  // 136 ASCII units -> labelW = 136 * 5.2 + 14 = 721.2px -> label right edge = 56 + 721.2 = 777.2px
+  // (777.2px <= 820 canvas width, but > 772 segment frame edge)
+
+  // 1. Fits within canvas (777.2 <= 820) but exceeds segment frame (777.2 > 772)
+  const dExceed = load('sequence');
+  dExceed.meta.viewBox[0] = 820;
+  dExceed.meta.column_fit = 'fixed';
+  dExceed.segments[0].label = 'A'.repeat(136);
+  const resExceed = render('sequence', dExceed);
+  assert.equal(resExceed.code, 1, 'label exceeding segment frame must fail even if within canvas');
+  assert.match(resExceed.stderr, /label \(~721px\) exceeds the segment frame's available width \(716px\) — shorten the label or increase meta\.viewBox\[0\] to at least 826\./);
+
+  // 2. Exact-fit case at the frame's right edge (56 + 716 = 772 === 820 - 48)
+  const dExact = load('sequence');
+  dExact.meta.viewBox[0] = 820;
+  dExact.meta.column_fit = 'fixed';
+  dExact.segments[0].label = 'A'.repeat(135);
+  const resExact = render('sequence', dExact);
+  assert.equal(resExact.code, 0, `exact-fit label at segment frame boundary must pass cleanly: ${resExact.stderr}`);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));