@xgent-ai/skills 0.3.0 → 0.4.0

package/skills/archify/test/artifact-receipt-flush.test.mjs

@@ -0,0 +1,126 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { after, test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const checker = path.join(skillRoot, 'scripts/check-render-output.mjs');
+const cli = path.join(skillRoot, 'bin/archify.mjs');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-receipt-flush-'));
+after(() => fs.rmSync(tmp, { recursive: true, force: true }));
+
+function run(script, args, options = {}) {
+  return spawnSync(process.execPath, [script, ...args], {
+    cwd: skillRoot,
+    encoding: 'utf8',
+    timeout: 30_000,
+    ...options,
+  });
+}
+
+for (const profile of ['standard', 'showcase']) {
+  test(`artifact checker flushes a large ${profile} receipt to a pipe`, () => {
+    // Distinct relationships sharing one corridor produce a real, large
+    // composition receipt: warnings in standard, errors in showcase.
+    const count = 24;
+    const arrows = Array.from({ length: count }, (_, index) => (
+      `<path data-edge-id="edge-${index}" data-edge-from="source-${index}" data-edge-to="target-${index}" d="M 20 40 L 220 40" class="a-default" marker-end="url(#arrowhead)"/>`
+    )).join('\n');
+    const html = path.join(tmp, `${profile}.html`);
+    fs.writeFileSync(html, `<svg viewBox="0 0 240 160" data-quality-profile="${profile}">${arrows}</svg>`);
+
+    // A regular file is the synchronous-output control. The pipe must carry
+    // exactly the same bytes, including the final diagnostic and closing JSON.
+    const reference = path.join(tmp, `${profile}.json`);
+    const descriptor = fs.openSync(reference, 'w');
+    let fileRun;
+    try {
+      fileRun = run(checker, [html], { stdio: ['ignore', descriptor, 'pipe'] });
+    } finally {
+      fs.closeSync(descriptor);
+    }
+    const expectedCode = profile === 'standard' ? 0 : 1;
+    assert.equal(fileRun.status, expectedCode, fileRun.stderr);
+    const expected = fs.readFileSync(reference, 'utf8');
+    assert.ok(Buffer.byteLength(expected) > 64 * 1024, 'fixture must exceed a 64 KiB pipe buffer');
+    const receipt = JSON.parse(expected);
+    assert.equal(receipt.ok, profile === 'standard');
+    assert.equal(receipt.composition.issues.length, count * (count - 1) / 2);
+    assert.ok(receipt.composition.issues.every((issue) => (
+      issue.code === 'composition/ambiguous-corridor'
+      && issue.severity === (profile === 'standard' ? 'warning' : 'error')
+    )));
+
+    const piped = run(checker, [html]);
+    assert.equal(piped.status, expectedCode, piped.stderr);
+    assert.equal(piped.stderr, '');
+    assert.equal(Buffer.byteLength(piped.stdout), Buffer.byteLength(expected), 'pipe must not truncate the receipt');
+    assert.equal(piped.stdout, expected);
+    assert.deepEqual(JSON.parse(piped.stdout), receipt);
+  });
+}
+
+function denseArchitecture() {
+  const count = 20;
+  const components = [];
+  const connections = [];
+  for (let index = 0; index < count; index += 1) {
+    const sourceX = 40 + index * 160;
+    const targetX = 40 + (count - 1 - index) * 160;
+    components.push(
+      { id: `source-${index}`, type: 'backend', label: `Source ${index}`, pos: [sourceX, 40], size: [120, 60] },
+      { id: `target-${index}`, type: 'database', label: `Target ${index}`, pos: [targetX, 400], size: [120, 60] },
+    );
+    connections.push({
+      id: `edge-${index}`,
+      from: `source-${index}`,
+      to: `target-${index}`,
+      fromSide: 'bottom',
+      toSide: 'top',
+      via: [[sourceX + 60, 240], [targetX + 60, 240]],
+    });
+  }
+  return {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Large receipt regression', quality_profile: 'standard' },
+    components,
+    connections,
+  };
+}
+
+for (const command of ['validate', 'deliver', 'compare']) {
+  test(`${command} consumes a complete artifact receipt larger than 64 KiB`, () => {
+    const source = denseArchitecture();
+    const input = path.join(tmp, `${command}.architecture.json`);
+    const output = path.join(tmp, `${command}.html`);
+    fs.writeFileSync(input, JSON.stringify(source));
+    const args = command === 'validate' ? [input]
+      : command === 'deliver' ? [input, output]
+        : [input, input, output];
+    const result = run(cli, [command, 'architecture', ...args, '--json']);
+    assert.equal(result.status, 0, result.stderr || result.stdout);
+    assert.equal(result.stderr, '');
+    const receipt = JSON.parse(result.stdout);
+    assert.equal(receipt.ok, true);
+    assert.equal(receipt.command, command);
+    if (command === 'validate') {
+      assert.ok(Buffer.byteLength(result.stdout) > 64 * 1024);
+      assert.ok(receipt.checks.every((check) => check.ok));
+      assert.ok(receipt.composition.issues.length > 100);
+    } else {
+      const artifact = fs.readFileSync(output);
+      assert.ok(artifact.length > 0);
+      if (command === 'deliver') {
+        assert.equal(receipt.artifact.sha256, createHash('sha256').update(artifact).digest('hex'));
+      } else {
+        assert.equal(receipt.completeness, 'complete');
+        assert.equal(receipt.proofLevel, 'authored');
+      }
+    }
+  });
+}

package/skills/archify/test/authored-reachability.test.mjs

@@ -0,0 +1,95 @@
+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 vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const template = fs.readFileSync(path.join(skillRoot, 'assets/template.html'), 'utf8');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-authored-reach-'));
+
+const CASES = {
+  architecture: 'web-app.architecture.json',
+  workflow: 'agent-tool-call.workflow.json',
+  sequence: 'cache-miss-request.sequence.json',
+  dataflow: 'product-analytics.dataflow.json',
+  lifecycle: 'agent-run.lifecycle.json',
+};
+
+function render(mode, example) {
+  const output = path.join(tmp, `${mode}.html`);
+  execFileSync(process.execPath, [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    path.join(skillRoot, 'examples', example),
+    output,
+  ]);
+  return fs.readFileSync(output, 'utf8');
+}
+
+function canonicalSvg(html) {
+  return html.match(/<svg\b[\s\S]*?<\/svg>/)?.[0] || '';
+}
+
+function reachabilityFunction() {
+  const start = template.indexOf('function computeReachability(');
+  const end = template.indexOf('\n      function reachabilityFor(', start);
+  assert.ok(start >= 0 && end > start, 'template exposes one extractable reachability function');
+  return vm.runInNewContext(`(${template.slice(start, end)})`);
+}
+
+test('authored reachability is available in every typed artifact without entering canonical SVG', () => {
+  for (const [mode, example] of Object.entries(CASES)) {
+    const html = render(mode, example);
+    assert.match(html, /id="focus-reach" hidden/);
+    assert.match(html, /id="btn-reach-upstream"[^>]+aria-pressed="false"/);
+    assert.match(html, /id="btn-reach-downstream"[^>]+aria-pressed="false"/);
+    assert.match(html, /function computeReachability\(originId, direction, relationships\)/);
+    assert.match(html, /svg\.setAttribute\('data-reach-active', direction\)/);
+    assert.doesNotMatch(canonicalSvg(html), /data-reach-(?:active|match|origin|depth)/, mode);
+  }
+});
+
+test('reachability uses stable breadth-first depth, supports cycles, and deduplicates edge fragments', () => {
+  const compute = reachabilityFunction();
+  const relationships = [
+    { key: 'a-b', from: 'a', to: 'b' },
+    { key: 'a-c', from: 'a', to: 'c' },
+    { key: 'b-d', from: 'b', to: 'd' },
+    { key: 'c-d', from: 'c', to: 'd' },
+    { key: 'd-b', from: 'd', to: 'b' },
+    { key: 'x-a', from: 'x', to: 'a' },
+    { key: 'a-b', from: 'a', to: 'b' },
+  ];
+
+  const downstream = compute('a', 'downstream', relationships);
+  assert.deepEqual(Array.from(downstream.nodeIds), ['a', 'b', 'c', 'd']);
+  assert.deepEqual({ ...downstream.depths }, { a: 0, b: 1, c: 1, d: 2 });
+  assert.deepEqual(Array.from(downstream.edgeKeys), ['a-b', 'a-c', 'b-d', 'c-d', 'd-b']);
+  assert.equal(downstream.maxDepth, 2);
+
+  const upstream = compute('d', 'upstream', relationships);
+  assert.deepEqual(Array.from(upstream.nodeIds), ['d', 'b', 'c', 'a', 'x']);
+  assert.deepEqual({ ...upstream.depths }, { d: 0, b: 1, c: 1, a: 2, x: 3 });
+  assert.equal(upstream.maxDepth, 3);
+  assert.equal(compute('a', 'sideways', relationships), null);
+});
+
+test('reachability stays explicit, deep-linkable, keyboard reachable, and export-clean', () => {
+  assert.match(template, /Authored Reachability is a bounded graph query over the relationships/);
+  assert.match(template, /direction !== 'upstream' && direction !== 'downstream'/);
+  assert.match(template, /encodeURIComponent\(activeIds\[0\]\) \+ '&reach=' \+ direction/);
+  assert.match(template, /applyReachability\(reach, \{ updateUrl: false, toggle: false, reveal: false \}\)/);
+  assert.match(template, /upstreamBtn\.addEventListener\('click'/);
+  assert.match(template, /downstreamBtn\.addEventListener\('click'/);
+  assert.match(template, /clone\.removeAttribute\('data-reach-active'\)/);
+  assert.match(template, /clone\.querySelectorAll\('\[data-reach-match\], \[data-reach-origin\], \[data-reach-depth\]'/);
+  assert.match(template, /!clone\.hasAttribute\('data-reach-active'\)/);
+  assert.match(template, /svg\[data-preset="blueprint"\]\[data-reach-active\]/);
+  assert.match(template, /\.diagram-container svg\[data-reach-active\] \[data-node-id\]/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/authoring-safety-contract.test.mjs

@@ -0,0 +1,54 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');
+const authoringContract = fs.readFileSync(
+  path.join(skillRoot, 'references', 'authoring-contract.md'),
+  'utf8',
+);
+const schemaReadme = fs.readFileSync(path.join(skillRoot, 'schemas', 'README.md'), 'utf8');
+
+test('semantic relationship labels are preserved and deletion is not a geometry repair', () => {
+  for (const [name, source] of [['SKILL.md', skill], ['authoring contract', authoringContract]]) {
+    assert.match(source, /Relationship labels are semantic data/i, name);
+    assert.match(source, /move the label[\s\S]*adjust the route or spacing[\s\S]*shorten/i, name);
+    assert.match(source, /protocol[\s\S]*action[\s\S]*direction[\s\S]*synchronous[\s\S]*asynchronous[\s\S]*cross-boundary mechanism/i, name);
+    assert.match(source, /Omit only wording[\s\S]*fully implied by both endpoints/i, name);
+    assert.match(source, /Preserve every meaningful label/i, name);
+    assert.match(source, /deleting it is not\s+a (?:geometry|spacing) repair/i, name);
+  }
+});
+
+test('schema policy documents the workflow v1/v2 compatibility boundary', () => {
+  assert.match(schemaReadme, /Workflow[^\n]*schema versions? 1 and 2/i);
+  assert.match(schemaReadme, /other four[^\n]*schema_version[^\n]*1/i);
+  assert.doesNotMatch(schemaReadme, /schema_version` is `"const": 1`/);
+});
+
+test('deployment ownership stays explicit, fact-backed, and cannot be removed to pass', () => {
+  assert.match(skill, /Omit `meta\.engineering_profile` by default/);
+  assert.match(skill, /Region.*cluster.*security boundar.*do not.*enable/i);
+  assert.match(skill, /production deployment topology.*ownership.*fail-closed deployment review/i);
+  assert.match(skill, /must not remove.*engineering profile.*pass validation/i);
+});
+
+test('visual-check stays a pending sidecar receipt instead of a polish claim', () => {
+  const deliveryContract = fs.readFileSync(
+    path.join(skillRoot, 'references', 'delivery-contract.md'),
+    'utf8',
+  );
+  assert.match(skill, /visual-check <output\.html> --json/);
+  assert.match(skill, /automated browser evidence[\s\S]*perceptual visual review/i);
+  assert.match(skill, /references\/delivery-contract\.md/);
+  assert.match(skill, /without (?:rerendering or )?modifying/i);
+
+  assert.match(deliveryContract, /visual-check <output\.html> --json/);
+  assert.match(deliveryContract, /1440×900[\s\S]*1600×1000[\s\S]*1920×1080[\s\S]*2048×1320/);
+  assert.match(deliveryContract, /visualReview: "pending"/);
+  assert.match(deliveryContract, /never changes.*delivered|without (?:rerendering or )?modifying/i);
+});

package/skills/archify/test/automatic-port-spread.test.mjs

@@ -0,0 +1,376 @@
+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, '..');
+
+function render(mode, doc) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-port-spread-'));
+  const input = path.join(tmp, 'input.json');
+  const output = path.join(tmp, 'output.html');
+  fs.writeFileSync(input, JSON.stringify(doc));
+  try {
+    execFileSync('node', [
+      path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+      input,
+      output,
+    ], { stdio: ['ignore', 'ignore', 'pipe'] });
+    return fs.readFileSync(output, 'utf8');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+function connectionPoints(html, id) {
+  const pattern = new RegExp(`data-edge-id="${id}"[^>]+data-composition-points="([^"]+)"`);
+  const match = html.match(pattern);
+  assert.ok(match, `missing rendered connection ${id}`);
+  return match[1].split(';').map((point) => point.split(',').map(Number));
+}
+
+function fanOutArchitecture(connections) {
+  return {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Automatic port spread' },
+    components: [
+      { id: 'hub', type: 'backend', label: 'Hub', pos: [100, 280], size: [120, 60] },
+      { id: 'upper', type: 'external', label: 'Upper', pos: [500, 100], size: [120, 60] },
+      { id: 'middle', type: 'database', label: 'Middle', pos: [500, 280], size: [120, 60] },
+      { id: 'lower', type: 'cloud', label: 'Lower', pos: [500, 460], size: [120, 60] },
+    ],
+    connections,
+  };
+}
+
+test('architecture: automatic fan-out uses distinct symmetric ports with corner clearance', () => {
+  const html = render('architecture', fanOutArchitecture([
+    { id: 'to-upper', from: 'hub', to: 'upper' },
+    { id: 'to-middle', from: 'hub', to: 'middle' },
+    { id: 'to-lower', from: 'hub', to: 'lower' },
+  ]));
+
+  assert.deepEqual(connectionPoints(html, 'to-upper')[0], [220, 296]);
+  assert.deepEqual(connectionPoints(html, 'to-middle')[0], [220, 310]);
+  assert.deepEqual(connectionPoints(html, 'to-lower')[0], [220, 324]);
+});
+
+test('architecture: automatic port assignment is stable when relationship input order changes', () => {
+  const connections = [
+    { id: 'to-upper', from: 'hub', to: 'upper' },
+    { id: 'to-middle', from: 'hub', to: 'middle' },
+    { id: 'to-lower', from: 'hub', to: 'lower' },
+  ];
+  const forward = render('architecture', fanOutArchitecture(connections));
+  const reversed = render('architecture', fanOutArchitecture([...connections].reverse()));
+
+  for (const connection of connections) {
+    assert.deepEqual(
+      connectionPoints(forward, connection.id),
+      connectionPoints(reversed, connection.id),
+      `${connection.id} moved after input reordering`,
+    );
+  }
+});
+
+test('architecture: a singly spread near-aligned vertical relationship keeps one direct axis', () => {
+  const html = render('architecture', {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Near-aligned fan-out' },
+    components: [
+      { id: 'api', type: 'backend', label: 'API', pos: [675, 300], size: [120, 60] },
+      { id: 'auth', type: 'security', label: 'Auth', pos: [570, 120], size: [100, 60] },
+      { id: 'cache', type: 'database', label: 'Cache', pos: [685, 120], size: [100, 60] },
+    ],
+    connections: [
+      { id: 'verify', from: 'api', to: 'auth', fromSide: 'top', toSide: 'bottom' },
+      { id: 'read', from: 'api', to: 'cache', fromSide: 'top', toSide: 'bottom' },
+    ],
+  });
+
+  assert.deepEqual(connectionPoints(html, 'read'), [[742, 300], [742, 180]]);
+  assert.notDeepEqual(connectionPoints(html, 'verify')[0], connectionPoints(html, 'read')[0]);
+});
+
+test('architecture: a singly spread near-aligned horizontal relationship keeps one direct axis', () => {
+  const html = render('architecture', {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Near-aligned horizontal fan-out' },
+    components: [
+      { id: 'hub', type: 'backend', label: 'Hub', pos: [100, 100], size: [120, 60] },
+      { id: 'direct', type: 'database', label: 'Direct', pos: [500, 107], size: [120, 60] },
+      { id: 'branch', type: 'cloud', label: 'Branch', pos: [500, 300], size: [120, 60] },
+    ],
+    connections: [
+      { id: 'hub-direct', from: 'hub', to: 'direct', fromSide: 'right', toSide: 'left' },
+      { id: 'hub-branch', from: 'hub', to: 'branch', fromSide: 'right', toSide: 'left' },
+    ],
+  });
+
+  assert.deepEqual(connectionPoints(html, 'hub-direct'), [[220, 123], [500, 123]]);
+  assert.notDeepEqual(connectionPoints(html, 'hub-branch')[0], connectionPoints(html, 'hub-direct')[0]);
+});
+
+test('architecture: a shared bottom port keeps its aligned child relationship straight', () => {
+  const doc = {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Vertical child relationship' },
+    components: [
+      { id: 'parent', type: 'backend', label: 'Parent Session', pos: [300, 100], size: [200, 60] },
+      { id: 'terminal', type: 'backend', label: 'Background terminal', pos: [300, 300], size: [200, 60] },
+      { id: 'workflow', type: 'backend', label: 'Workflow', pos: [560, 300], size: [180, 60] },
+    ],
+    connections: [
+      { id: 'parent-terminal', from: 'parent', to: 'terminal', fromSide: 'bottom', toSide: 'top' },
+      { id: 'parent-workflow', from: 'parent', to: 'workflow', fromSide: 'bottom', toSide: 'top' },
+    ],
+  };
+  const forward = render('architecture', doc);
+  const reversed = render('architecture', {
+    ...doc,
+    connections: [...doc.connections].reverse(),
+  });
+
+  assert.deepEqual(connectionPoints(forward, 'parent-terminal'), [[393, 160], [393, 300]]);
+  assert.notDeepEqual(
+    connectionPoints(forward, 'parent-workflow')[0],
+    connectionPoints(forward, 'parent-terminal')[0],
+  );
+  for (const connection of doc.connections) {
+    assert.deepEqual(
+      connectionPoints(forward, connection.id),
+      connectionPoints(reversed, connection.id),
+      `${connection.id} moved after input reordering`,
+    );
+  }
+});
+
+test('architecture: incoming and outgoing relationships keep distinct bottom ports while the direct child stays straight', () => {
+  const html = render('architecture', {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Shared incoming and outgoing side' },
+    components: [
+      { id: 'workflow', type: 'backend', label: 'Workflow', pos: [80, 320], size: [180, 60] },
+      { id: 'child', type: 'security', label: 'Child boundary', pos: [300, 100], size: [200, 60] },
+      { id: 'footer', type: 'frontend', label: 'Footer', pos: [300, 320], size: [200, 60] },
+    ],
+    connections: [
+      { id: 'workflow-child', from: 'workflow', to: 'child', fromSide: 'right', toSide: 'bottom' },
+      { id: 'child-footer', from: 'child', to: 'footer', fromSide: 'bottom', toSide: 'top' },
+    ],
+  });
+
+  assert.deepEqual(connectionPoints(html, 'child-footer'), [[407, 160], [407, 320]]);
+  assert.notDeepEqual(
+    connectionPoints(html, 'workflow-child').at(-1),
+    connectionPoints(html, 'child-footer')[0],
+  );
+});
+
+test('architecture: a near-aligned relationship keeps the outside bridge when both endpoints are spread', () => {
+  const html = render('architecture', {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Two-sided port competition' },
+    components: [
+      { id: 'source', type: 'backend', label: 'Source', pos: [300, 320], size: [160, 60] },
+      { id: 'source-peer', type: 'backend', label: 'Source peer', pos: [80, 320], size: [160, 60] },
+      { id: 'target', type: 'database', label: 'Target', pos: [300, 100], size: [160, 60] },
+      { id: 'target-peer', type: 'database', label: 'Target peer', pos: [560, 100], size: [160, 60] },
+    ],
+    connections: [
+      { id: 'source-target', from: 'source', to: 'target', fromSide: 'top', toSide: 'bottom' },
+      { id: 'source-peer-target', from: 'source-peer', to: 'target', fromSide: 'top', toSide: 'bottom' },
+      { id: 'source-target-peer', from: 'source', to: 'target-peer', fromSide: 'top', toSide: 'bottom' },
+    ],
+  });
+
+  const points = connectionPoints(html, 'source-target');
+  assert.ok(points.length > 2);
+  assert.notEqual(points[0][0], points.at(-1)[0]);
+});
+
+test('architecture: a singly spread near-aligned relationship keeps the bridge when its direct axis is blocked', () => {
+  const html = render('architecture', {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Blocked vertical axis' },
+    components: [
+      { id: 'parent', type: 'backend', label: 'Parent', pos: [300, 100], size: [200, 60] },
+      { id: 'terminal', type: 'backend', label: 'Terminal', pos: [300, 400], size: [200, 60] },
+      { id: 'workflow', type: 'backend', label: 'Workflow', pos: [560, 400], size: [180, 60] },
+      { id: 'obstacle', type: 'external', label: 'X', pos: [382, 245], size: [26, 60] },
+    ],
+    connections: [
+      { id: 'parent-terminal', from: 'parent', to: 'terminal', fromSide: 'bottom', toSide: 'top' },
+      { id: 'parent-workflow', from: 'parent', to: 'workflow', fromSide: 'bottom', toSide: 'top' },
+    ],
+  });
+
+  const points = connectionPoints(html, 'parent-terminal');
+  assert.ok(points.length > 2);
+  assert.notEqual(points[0][0], points.at(-1)[0]);
+});
+
+test('architecture: single and explicitly positioned relationships keep legacy anchors', () => {
+  const doc = fanOutArchitecture([
+    { id: 'single', from: 'hub', to: 'middle' },
+    { id: 'via', from: 'hub', to: 'upper', via: [[300, 310], [300, 130]] },
+    { id: 'fixed-route', from: 'hub', to: 'lower', route: 'orthogonal-h' },
+    { id: 'fixed-label', from: 'hub', to: 'upper', label: 'contract', labelAt: [360, 200] },
+  ]);
+  const html = render('architecture', doc);
+
+  assert.deepEqual(connectionPoints(html, 'single'), [[220, 310], [500, 310]]);
+  assert.deepEqual(connectionPoints(html, 'via'), [[220, 310], [300, 310], [300, 130], [500, 130]]);
+  assert.deepEqual(connectionPoints(html, 'fixed-route'), [[220, 310], [360, 310], [360, 490], [500, 490]]);
+  assert.deepEqual(connectionPoints(html, 'fixed-label'), [[220, 310], [360, 310], [360, 130], [500, 130]]);
+});
+
+test('architecture: an unspread near-aligned connection shares one horizontal axis', () => {
+  const html = render('architecture', {
+    schema_version: 1,
+    diagram_type: 'architecture',
+    meta: { title: 'Near-aligned single connection' },
+    components: [
+      { id: 'console', type: 'frontend', label: 'Console', pos: [260, 300], size: [170, 64] },
+      { id: 'controlplane', type: 'backend', label: 'Control plane', pos: [500, 300], size: [190, 72] },
+    ],
+    connections: [
+      { id: 'console-controlplane', from: 'console', to: 'controlplane', label: 'REST /api', variant: 'emphasis', labelDy: -36 },
+    ],
+  });
+
+  assert.deepEqual(connectionPoints(html, 'console-controlplane'), [[430, 332], [500, 332]]);
+});
+
+test('workflow: automatic cross-lane fan-out selects distinct perpendicular source sides', () => {
+  const html = render('workflow', {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: { title: 'Workflow port spread' },
+    lanes: [
+      { id: 'upper-lane', label: 'Upper' },
+      { id: 'hub-lane', label: 'Hub' },
+      { id: 'lower-lane', label: 'Lower' },
+    ],
+    nodes: [
+      { id: 'hub', lane: 'hub-lane', col: 0, type: 'backend', label: 'Hub' },
+      { id: 'upper', lane: 'upper-lane', col: 3, type: 'external', label: 'Upper' },
+      { id: 'middle', lane: 'hub-lane', col: 3, type: 'database', label: 'Middle' },
+      { id: 'lower', lane: 'lower-lane', col: 3, type: 'cloud', label: 'Lower' },
+    ],
+    edges: [
+      { id: 'to-upper', from: 'hub', to: 'upper' },
+      { id: 'to-middle', from: 'hub', to: 'middle' },
+      { id: 'to-lower', from: 'hub', to: 'lower' },
+    ],
+  });
+
+  assert.deepEqual(connectionPoints(html, 'to-upper')[0], [88, 217]);
+  assert.deepEqual(connectionPoints(html, 'to-middle')[0], [134, 243]);
+  assert.deepEqual(connectionPoints(html, 'to-lower')[0], [88, 269]);
+});
+
+test('dataflow: automatic fan-out spreads flows without changing their authored topology', () => {
+  const html = render('dataflow', {
+    schema_version: 1,
+    diagram_type: 'dataflow',
+    meta: { title: 'Data-flow port spread' },
+    stages: [{ label: 'Source' }, { label: 'Transform' }, { label: 'Sinks' }],
+    nodes: [
+      { id: 'hub', type: 'backend', label: 'Hub', stage: 0, row: 2 },
+      { id: 'upper', type: 'external', label: 'Upper', stage: 2, row: 0 },
+      { id: 'middle', type: 'database', label: 'Middle', stage: 2, row: 2 },
+      { id: 'lower', type: 'cloud', label: 'Lower', stage: 2, row: 4 },
+    ],
+    flows: [
+      { id: 'to-upper', from: 'hub', to: 'upper', label: 'upper feed' },
+      { id: 'to-middle', from: 'hub', to: 'middle', label: 'middle feed' },
+      { id: 'to-lower', from: 'hub', to: 'lower', label: 'lower feed' },
+    ],
+  });
+
+  assert.deepEqual(connectionPoints(html, 'to-upper')[0], [156, 372]);
+  assert.deepEqual(connectionPoints(html, 'to-middle')[0], [156, 385]);
+  assert.deepEqual(connectionPoints(html, 'to-lower')[0], [156, 398]);
+});
+
+test('lifecycle: automatic fan-out spreads transitions across lifecycle bands', () => {
+  const html = render('lifecycle', {
+    schema_version: 1,
+    diagram_type: 'lifecycle',
+    meta: { title: 'Lifecycle port spread' },
+    lanes: [
+      { id: 'main', label: 'Main' },
+      { id: 'event', label: 'Events' },
+      { id: 'terminal', label: 'Outcomes' },
+    ],
+    states: [
+      { id: 'hub', type: 'active', label: 'Hub', lane: 'event', col: 0 },
+      { id: 'upper', type: 'waiting', label: 'Upper', lane: 'main', col: 4 },
+      { id: 'middle', type: 'success', label: 'Middle', lane: 'event', col: 2 },
+      { id: 'lower', type: 'failure', label: 'Lower', lane: 'terminal', col: 2 },
+    ],
+    transitions: [
+      { id: 'to-upper', from: 'hub', to: 'upper' },
+      { id: 'to-middle', from: 'hub', to: 'middle' },
+      { id: 'to-lower', from: 'hub', to: 'lower' },
+    ],
+  });
+
+  assert.deepEqual(connectionPoints(html, 'to-upper')[0], [465, 294]);
+  assert.deepEqual(connectionPoints(html, 'to-middle')[0], [465, 307]);
+  assert.deepEqual(connectionPoints(html, 'to-lower')[0], [465, 320]);
+});
+
+test('lifecycle: same-band port spread remains orthogonal', () => {
+  const html = render('lifecycle', {
+    schema_version: 1,
+    diagram_type: 'lifecycle',
+    meta: { title: 'Orthogonal same-band spread' },
+    lanes: [{ id: 'main', label: 'Main' }],
+    states: [
+      { id: 'hub', type: 'active', label: 'Hub', lane: 'main', col: 0 },
+      { id: 'upper', type: 'waiting', label: 'Upper', lane: 'main', col: 2, yOffset: -50 },
+      { id: 'lower', type: 'success', label: 'Lower', lane: 'main', col: 4, yOffset: 50 },
+    ],
+    transitions: [
+      { id: 'to-upper', from: 'hub', to: 'upper' },
+      { id: 'to-lower', from: 'hub', to: 'lower' },
+    ],
+  });
+
+  assert.deepEqual(connectionPoints(html, 'to-upper'), [
+    [153, 150], [248, 150], [248, 107], [343, 107],
+  ]);
+  assert.deepEqual(connectionPoints(html, 'to-lower'), [
+    [153, 164], [402, 164], [402, 207], [651, 207],
+  ]);
+});
+
+test('skill and READMEs describe automatic port spread as bounded default behavior', () => {
+  const skill = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');
+  assert.match(skill, /Automatic Port Spread is a default renderer behavior/);
+  assert.match(skill, /single relationship|single relationships/);
+  assert.match(skill, /explicit `via`.*`channelX`.*`channelY`.*`labelAt`/);
+  assert.match(skill, /facing automatic ports \(`left`\/`right` or `top`\/`bottom`\).*one shared axis/);
+
+  const authoringContract = fs.readFileSync(path.join(skillRoot, 'references/authoring-contract.md'), 'utf8');
+  assert.match(authoringContract, /unobstructed facing ports.*may share one horizontal or vertical axis/);
+
+  const repoRoot = path.resolve(skillRoot, '..');
+  for (const file of ['README.md', 'README_EN.md']) {
+    assert.match(fs.readFileSync(path.join(repoRoot, file), 'utf8'), /shared automatic endpoints spread deterministically/);
+  }
+  assert.match(fs.readFileSync(path.join(repoRoot, 'README_ZH.md'), 'utf8'), /共享的自动端点会确定性展开/);
+});