@orchestrator-claude/definitions 3.38.0 → 3.40.0

package/skills/archify/test/golden.mjs

@@ -0,0 +1,167 @@
+// Golden-file harness for the archify renderers. No test framework needed:
+// renderers are deterministic, so fresh renders must match the checked-in
+// example HTML aside from platform checkout line endings. Also covers schema enforcement (negative cases),
+// template freshness of the architecture-mode example, and version sync.
+//
+// Run from the skill folder: npm test
+
+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 repoRoot = path.resolve(skillRoot, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-test-'));
+
+let failures = 0;
+
+function check(name, ok, detail) {
+  if (ok) {
+    console.log(`  ok    ${name}`);
+  } else {
+    failures += 1;
+    console.error(`  FAIL  ${name}${detail ? ` — ${detail}` : ''}`);
+  }
+}
+
+function render(mode, inputPath, outPath) {
+  execFileSync('node', [
+    path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
+    inputPath,
+    outPath,
+  ], { stdio: ['ignore', 'ignore', 'pipe'] });
+}
+
+function normalizeNewlines(text) {
+  return text.replace(/\r\n?/g, '\n');
+}
+
+// ---------------------------------------------------------------------------
+console.log('golden renders (renderer output must match checked-in examples)');
+
+const GOLDEN = [
+  ['workflow', 'agent-tool-call.workflow.json', 'workflow-agent-tool-call-rendered.html'],
+  ['sequence', 'cache-miss-request.sequence.json', 'sequence-cache-miss-request.html'],
+  ['dataflow', 'product-analytics.dataflow.json', 'dataflow-product-analytics.html'],
+  ['lifecycle', 'agent-run.lifecycle.json', 'lifecycle-agent-run.html'],
+  ['architecture', 'web-app.architecture.json', 'web-app-rendered.html'],
+];
+
+for (const [mode, input, golden] of GOLDEN) {
+  const out = path.join(tmp, golden);
+  try {
+    render(mode, path.join(skillRoot, 'examples', input), out);
+    const fresh = fs.readFileSync(out, 'utf8');
+    const checked = fs.readFileSync(path.join(repoRoot, 'examples', golden), 'utf8');
+    check(`${mode}: ${golden}`, normalizeNewlines(fresh) === normalizeNewlines(checked),
+      `fresh render differs from examples/${golden}; if the change is intentional, re-render the examples and commit them`);
+  } catch (err) {
+    check(`${mode}: ${golden}`, false, String(err.stderr || err.message).slice(0, 300));
+  }
+}
+
+// ---------------------------------------------------------------------------
+console.log('schema enforcement (invalid JSON must fail with a path-prefixed message)');
+
+function expectFailure(name, mode, mutate, expectInMessage) {
+  const base = JSON.parse(fs.readFileSync(
+    path.join(skillRoot, 'examples', GOLDEN.find(([m]) => m === mode)[1]), 'utf8'));
+  mutate(base);
+  const input = path.join(tmp, `neg-${name.replace(/[^a-z0-9]+/gi, '-')}.json`);
+  fs.writeFileSync(input, JSON.stringify(base));
+  try {
+    render(mode, input, path.join(tmp, 'neg-out.html'));
+    check(name, false, 'renderer exited 0 on invalid input');
+  } catch (err) {
+    const message = String(err.stderr || err.message);
+    check(name, message.includes(expectInMessage),
+      `expected "${expectInMessage}" in:\n${message.slice(0, 300)}`);
+  }
+}
+
+expectFailure('card dot outside enum', 'workflow',
+  (d) => { d.cards[0].dot = 'pink'; }, '/cards/0/dot');
+expectFailure('node id starting with a digit', 'workflow',
+  (d) => { d.nodes[0].id = '1user'; }, 'pattern');
+expectFailure('extra property rejected', 'workflow',
+  (d) => { d.nodes[0].colour = 'red'; }, 'additional properties');
+expectFailure('column beyond layout maximum', 'workflow',
+  (d) => { d.nodes[0].col = 7; }, '<= 5');
+expectFailure('missing schema_version', 'sequence',
+  (d) => { delete d.schema_version; }, 'schema_version');
+expectFailure('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');
+expectFailure('zero component width rejected by schema', 'architecture',
+  (d) => { d.components[0].size = [0, 60]; }, '/components/0/size/0');
+expectFailure('zero component height rejected by schema', 'architecture',
+  (d) => { d.components[0].size = [120, 0]; }, '/components/0/size/1');
+expectFailure('negative component width rejected by schema', 'architecture',
+  (d) => { d.components[0].size = [-1, 60]; }, '/components/0/size/0');
+
+// ---------------------------------------------------------------------------
+console.log('template freshness (architecture example must carry the current template)');
+
+function blocks(html, tag) {
+  const re = new RegExp(`<${tag}[^>]*>[\\s\\S]*?<\\/${tag}>`, 'g');
+  return html.match(re) || [];
+}
+
+const template = fs.readFileSync(path.join(skillRoot, 'assets/template.html'), 'utf8');
+const webApp = fs.readFileSync(path.join(repoRoot, 'examples/web-app.html'), 'utf8');
+// <style> and <script> blocks pass through applyTemplate untouched, so the
+// architecture-mode example must contain them verbatim or it has drifted.
+for (const tag of ['style', 'script']) {
+  const t = blocks(template, tag).filter((b) => !b.includes('[PROJECT NAME]'));
+  const w = blocks(webApp, tag).filter((b) => !b.includes('Sample Web App'));
+  check(`web-app.html ${tag} blocks match template`,
+    JSON.stringify(t) === JSON.stringify(w),
+    'examples/web-app.html was generated from a stale template — re-derive it');
+}
+
+// ---------------------------------------------------------------------------
+console.log('version sync');
+
+const pkg = JSON.parse(fs.readFileSync(path.join(skillRoot, 'package.json'), 'utf8'));
+check('template generator meta matches package.json version',
+  template.includes(`<meta name="generator" content="archify ${pkg.version}">`),
+  `package.json says ${pkg.version}`);
+
+const lock = JSON.parse(fs.readFileSync(path.join(skillRoot, 'package-lock.json'), 'utf8'));
+check('package-lock.json version matches package.json',
+  lock.version === pkg.version && lock.packages?.['']?.version === pkg.version,
+  `lockfile says ${lock.version} — run npm install and rebuild the zip`);
+
+const skillMd = fs.readFileSync(path.join(skillRoot, 'SKILL.md'), 'utf8');
+const skillVersion = (skillMd.match(/^\s*version:\s*"([^"]+)"/m) || [])[1];
+check('SKILL.md metadata version matches package.json major.minor',
+  !!skillVersion && pkg.version.startsWith(skillVersion),
+  `SKILL.md says ${skillVersion}, package.json says ${pkg.version}`);
+
+for (const readmeName of ['README.md', 'README_EN.md', 'README_ZH.md']) {
+  const readme = fs.readFileSync(path.join(repoRoot, readmeName), 'utf8');
+  check(`${readmeName} badge matches package.json version`,
+    readme.includes(`/badge/version-${pkg.version}-`),
+    `${readmeName} does not advertise ${pkg.version}`);
+}
+
+const landingPage = fs.readFileSync(path.join(repoRoot, 'docs/index.html'), 'utf8');
+const landingVersions = [...landingPage.matchAll(/\bv\d+\.\d+\.\d+\b/g)].map((m) => m[0]);
+check('GitHub Pages version labels match package.json',
+  landingVersions.length > 0 && landingVersions.every((v) => v === `v${pkg.version}`),
+  `landing page says ${[...new Set(landingVersions)].join(', ') || '(no version)'}`);
+
+// ---------------------------------------------------------------------------
+fs.rmSync(tmp, { recursive: true, force: true });
+if (failures) {
+  console.error(`\n${failures} check(s) failed`);
+  process.exit(1);
+}
+console.log('\nall checks passed');

package/skills/archify/test/grid.test.mjs

@@ -0,0 +1,47 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { gridLayout, resolveComponentPos, validateGridPlacement } from '../renderers/architecture/grid.mjs';
+
+test('gridLayout returns null for free placement', () => {
+  assert.equal(gridLayout({}), null);
+  assert.equal(gridLayout({ layout: undefined }), null);
+});
+
+test('resolveComponentPos prefers explicit pos over row/col', () => {
+  const grid = gridLayout({ layout: { mode: 'grid' } });
+  assert.deepEqual(resolveComponentPos({ pos: [9, 8], row: 0, col: 0 }, grid), [9, 8]);
+});
+
+test('resolveComponentPos maps row/col to pixel origin', () => {
+  const grid = gridLayout({
+    layout: { mode: 'grid', origin: [40, 80], gapX: 30, gapY: 40, cellW: 130, cellH: 64 },
+  });
+  assert.deepEqual(resolveComponentPos({ row: 0, col: 0 }, grid), [40, 80]);
+  assert.deepEqual(resolveComponentPos({ row: 1, col: 2 }, grid), [40 + 2 * 160, 80 + 104]);
+});
+
+test('validateGridPlacement rejects duplicate cells and missing row/col', () => {
+  const grid = gridLayout({ layout: { mode: 'grid', cols: 4 } });
+  const problems = [];
+  validateGridPlacement({
+    components: [
+      { id: 'a', row: 0, col: 0 },
+      { id: 'b', row: 0, col: 0 },
+      { id: 'c' },
+    ],
+  }, grid, problems);
+  assert.ok(problems.some((p) => p.includes('share grid cell')));
+  assert.ok(problems.some((p) => p.includes('"c" needs pos')));
+});
+
+test('validateGridPlacement ignores explicit pos overrides without row/col', () => {
+  const grid = gridLayout({ layout: { mode: 'grid', cols: 4 } });
+  const problems = [];
+  validateGridPlacement({
+    components: [
+      { id: 'a', pos: [40, 80] },
+      { id: 'b', pos: [200, 80] },
+    ],
+  }, grid, problems);
+  assert.deepEqual(problems, []);
+});

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

@@ -0,0 +1,193 @@
+// 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 hash(s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i += 1) h = (h * 31 + s.charCodeAt(i)) | 0;
+  return h;
+}
+
+// [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: 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']],
+
+  // ---- 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']],
+
+  // ---- 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"']],
+
+  // ---- 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']],
+
+  // ---- 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: label wider than component', 'architecture',
+    (d) => { d.components[0].label = 'An Extremely Long Component Label Overflow'; }, ['wider than component', 'shorten the label']],
+  ['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}`);
+    }
+  });
+}
+
+// ---- 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: edge crossing a non-endpoint node is rejected', () => {
+  const d = {
+    schema_version: 1,
+    diagram_type: 'workflow',
+    meta: { title: 'Crossing edge route' },
+    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/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/archify/test/render-output-checks.test.mjs

@@ -0,0 +1,75 @@
+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-output-checks-'));
+const checker = path.join(skillRoot, 'scripts/check-render-output.mjs');
+
+function checkHtml(name, svgBody) {
+  const htmlPath = path.join(tmp, `${name}.html`);
+  fs.writeFileSync(htmlPath, `<!doctype html><html><body><svg viewBox="0 0 240 160">${svgBody}</svg></body></html>`);
+  try {
+    const stdout = execFileSync('node', [checker, htmlPath], { encoding: 'utf8' });
+    return { code: 0, result: JSON.parse(stdout) };
+  } catch (err) {
+    return { code: err.status ?? 1, result: JSON.parse(String(err.stdout || '{}')) };
+  }
+}
+
+test('render output check: accepts orthogonal arrows away from legend', () => {
+  const { code, result } = checkHtml('clean', `
+    <path d="M 20 20 L 120 20 L 120 60" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+    <!-- Legend -->
+    <text x="40" y="120" class="t-primary" font-size="10">Legend</text>
+    <rect x="40" y="132" width="14" height="9" class="c-backend"/>
+    <text x="60" y="140" class="t-muted" font-size="7">Backend</text>
+  `);
+  assert.equal(code, 0);
+  assert.equal(result.ok, true);
+});
+
+test('render output check: rejects two-point diagonal arrows', () => {
+  const { code, result } = checkHtml('diagonal', `
+    <path d="M 20 20 L 120 80" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+    <!-- Legend -->
+    <text x="40" y="120" class="t-primary" font-size="10">Legend</text>
+  `);
+  assert.notEqual(code, 0);
+  const check = result.checks.find((item) => item.name === 'orthogonal_arrows');
+  assert.equal(check.ok, false);
+  assert.match(check.details[0], /path 1/);
+});
+
+test('render output check: rejects arrows crossing legend text', () => {
+  const { code, result } = checkHtml('legend-crossing', `
+    <path d="M 20 112 L 180 112" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+    <!-- Legend -->
+    <text x="40" y="120" class="t-primary" font-size="10">Legend</text>
+    <rect x="40" y="132" width="14" height="9" class="c-backend"/>
+    <text x="60" y="140" class="t-muted" font-size="7">Backend</text>
+  `);
+  assert.notEqual(code, 0);
+  const check = result.checks.find((item) => item.name === 'legend_clearance');
+  assert.equal(check.ok, false);
+  assert.match(check.details[0], /Legend/);
+});
+
+test('render output check: ignores unmarked sequence lifelines near legend', () => {
+  const { code, result } = checkHtml('lifeline-near-legend', `
+    <path d="M 60 20 L 60 126" class="a-default" stroke-width="0.8" stroke-dasharray="3,7"/>
+    <!-- Legend -->
+    <text x="40" y="120" class="t-primary" font-size="10">Legend</text>
+    <path d="M 120 136 L 154 136" class="a-default" stroke-width="1.4" stroke-dasharray="3,5" marker-end="url(#arrowhead)"/>
+    <text x="163" y="139" class="t-muted" font-size="8">return</text>
+  `);
+  assert.equal(code, 0);
+  assert.equal(result.ok, true);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));

package/skills/arquitetura-mediada-arquiteto/SKILL.md

@@ -136,9 +136,23 @@ saber sem decidir, o que já é o resultado.
 
 ### 6.5 O desenho não é a verdade
 
-Diagrama (Archify ou outro) só quando **decide** alguma coisa. Toda figura carrega, no próprio
-artefato, **de que medição foi derivada** e **em que data**. Sem isso ela envelhece em silêncio e
-continua convincente — e vira, em duas sessões, a fonte que alguém cita no lugar do código.
+**Todo mapa que você produz sai também desenhado, em Archify (HTML).** Mapa de topologia, mapa de dead
+code, mapa de dual path: os três. A tabela do relatório continua sendo o mapa; o desenho é **uma
+segunda forma dele**, obrigatória, e não um substituto (D-183, S533: a primeira rodada produziu zero
+diagramas porque esta seção os deixava opcionais). Fora dos mapas, diagrama só quando **decide** alguma
+coisa.
+
+Toda figura carrega **de que medição foi derivada** (o comando, o `arquivo:linha` ou o sha) e **em que
+data**, e isso vai **dentro do desenho**: num elemento do próprio SVG (um nó ou rótulo de
+proveniência), não só no `meta.subtitle`, num card ou num comentário. Na Archify, subtítulo e cards são
+HTML **fora** do `<svg>`, e a exportação serializa **só** o SVG (`assets/template.html`,
+`XMLSerializer` sobre o clone do `<svg>`): o PNG ou o SVG exportado perderia a proveniência. Sem ela a
+figura envelhece em silêncio e continua convincente, e em duas sessões vira a fonte que alguém cita no
+lugar do código.
+
+**O desenho não é a verdade.** Ele é derivado do registro e do relatório, e nunca o contrário. Quando
+os dois divergem, **o registro e o relatório vencem**, e o desenho é que está velho: regenere-o a
+partir deles, sem ajustar a tabela para caber na figura.
 
 ### 6.6 Verificar — e desconfiar do instrumento que concorda
 
@@ -181,6 +195,9 @@ DEAD CODE (se houve varredura)
 DUAL PATH (se houve varredura)
 | contrato | caminho A | caminho B | quem chama A | quem chama B | divergiram desde | qual está certo |
 
+MAPAS ARCHIFY (um por mapa acima: topologia, dead code, dual path — §6.5)
+| mapa | caminho do .html | sha256 do .html | medição de origem (dentro do desenho) | data |
+
 <as seções do seu substrato — o seu charter diz quais>
 
 DECISÃO PROPOSTA

package/skills/kb-api-pattern/SKILL.md

@@ -8,7 +8,7 @@ description: Search and apply API patterns from project KB. Use before implement
 Before implementing, find the canonical pattern:
 
 ### Step 1: Search KB
-Use MCP tool kbSearch or grep the codebase for existing implementations:
+Grep the codebase for existing implementations:
 ```bash
 grep -rl "class.*Controller" src/presentation/http/controllers/ | head -3
 ```