Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

Expose failed architecture geometry and actionable boundary repairs

tt-a1ie07556b2a735
diff --git a/archify/SKILL.md b/archify/SKILL.md
index d74b0b47..4f46310e 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -18,7 +18,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer R
1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.
2. Read one matching schema in `schemas/`, `schemas/common.schema.json`, and one matching JSON example in `examples/`. Read only those files. Fresh authorship means new stable IDs, domain wording, and layout; use the example for field shape, not facts. New workflow sources use `schema_version: 2` and its readable layout contract; keep `schema_version: 1` only when preserving an existing workflow's fixed geometry. When real product identity matters, query `node bin/archify.mjs brands "<name>" --json`; read `references/brand-marks.md` only for an unknown brand with a user-provided URL.
-3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, and sparse labels. Use roughly 12 primary nodes as an initial readability budget. Preserve every node and relationship required by the user's question; for larger diagrams, group related content where the selected schema supports it. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; repair one diagnosed geometry problem at a time. Before manual routing, read the relevant routing rules in `references/authoring-contract.md` and inspect layout evidence: use `validate <type> <candidate.json> --layout-json` for architecture/workflow; for other types, use validation diagnostics and the rendered SVG geometry. Check whether unnecessary agent-added controls disable automatic port spread; preserve user-required route intent. If several edges share a constrained channel, plan the smallest coupled change from measured geometry and validate it together.
+3. Artifact first: the next tool action must write the candidate. Write the candidate before inspecting renderer internals. Do not plan exact coordinates in prose. Start with one clear main path, short side branches, and sparse labels. Use roughly 12 primary nodes as an initial readability budget. Preserve every node and relationship required by the user's question; for larger diagrams, group related content where the selected schema supports it. Set `meta.quality_profile` to `"showcase"` unless the user explicitly requests a dense `standard` map. Start with automatic routes and labels. Do not add `via`, `channelX`, `channelY`, or `labelAt` before a diagnostic calls for one; test one repair hypothesis per round. When geometry fails or repeats, read the repair order in `references/authoring-contract.md` and inspect measured layout before manual routing: use `validate <type> <candidate.json> --layout-json` for architecture/workflow; for other types, use validation diagnostics and the rendered SVG geometry. Check whether unnecessary agent-added controls disable automatic port spread; preserve user-required route intent. If several edges share a constrained channel, compare a small node-layout change with adding route controls; validate the coupled change together while preserving required nodes, relationships, labels, and boundary membership.
4. Validate after every candidate edit and immediately before handoff:
```bash
@@ -32,7 +32,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer R
node bin/archify.mjs deliver <type> <candidate.json> <output.html> --quality showcase --json
```
- A non-zero exit can never be described as success. Continue to the strict delivery gate below only after `deliver` exits zero. If validation fails, change only the diagnosed `subject`, verify `evidence`, choose from `supportedFixes`, and rerun. Continue focused correction while the objective error count reaches a new minimum. If two consecutive rounds do not improve that best count, stop and report the unresolved diagnostics truthfully.
+ A non-zero exit can never be described as success. Continue to the strict delivery gate below only after `deliver` exits zero. If validation fails, use the diagnosed subjects and measured evidence to choose one repair hypothesis, then rerun. Missing evidence is a reason to inspect layout, not guess a constraint from the message. Compare remaining diagnostic codes and subjects within the same validation stage; a later stage can reveal new issues. If the same issue survives two focused repairs, inspect its measured geometry or the relevant implementation before changing that hypothesis. If it remains unresolved after that investigation and one evidence-based repair, stop and report it truthfully. A lower error count does not justify changing the diagram’s meaning.
## Update awareness
@@ -43,7 +43,7 @@ After the first candidate exists, run the packaged checker `scripts/check-update
The notice is information, not permission. Keep the installed version unchanged; this v0.1 workflow never downloads, installs, or executes an update, and silence is never consent.
-Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate. Inspect implementation only for an unsupported internal diagnostic or after two focused repairs fail.
+Do not read `renderers/shared/geometry.mjs`, renderer source, validator source, tests, or benchmarks before the first candidate. Inspect implementation only for a diagnostic without actionable evidence or after two focused repairs fail.
Workflow note: use schema v2 for new workflows; preserve schema v1 when an
existing source needs fixed legacy geometry. For sequential stages stacked in
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.md
index 9b96d74e..e2c5991a 100644
--- a/archify/references/authoring-contract.md
+++ b/archify/references/authoring-contract.md
@@ -182,6 +182,25 @@ Before adding manual routes, check whether unnecessary agent-added controls
disable automatic port spread; preserve user-required route intent. Use the
measured clearance rules above rather than guessing coordinates.
+### Repair evidence
+
+For architecture, `validate architecture <input.json> --layout-json` exposes the
+resolved component boxes, boundary frames, connection points, and label positions.
+A measurable rejected layout also returns these fields, with `ok: false`,
+`contract: "archify-architecture-layout-v1"`, diagnostics, and exit 1. This is
+repair evidence, not artifact acceptance; it writes no HTML. Malformed input or
+an implementation failure retains the ordinary failure receipt without layout.
+
+Use the measured failing side for `layout/boundary-out-of-bounds`. Left/top
+negative coordinates need an inward move; increasing viewBox width/height only
+addresses right/bottom overflow. Boundaries may wrap members across rows. Keep
+real membership intact and recheck connected routes after moving members.
+
+When several crossing/corridor diagnoses involve the same nodes, consider their
+placement together before adding route controls. Apply one coherent repair and
+validate it; independent label nudges cannot fix a shared layout bottleneck.
+Compare diagnostics by code, subject, and stage instead of total count alone.
+
### Repair order
1. Fix missing/invalid `meta.quality_profile` and schema errors.
diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjs
index d41e4b80..cea118b9 100644
--- a/archify/renderers/architecture/render-architecture.mjs
+++ b/archify/renderers/architecture/render-architecture.mjs
@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
import { esc, renderDefinitions, renderSemanticSigil, textUnits } from '../shared/utils.mjs';
import { animateAttr, focusEdgeAttrs, focusNodeAttrs, focusNodeTitle, loadDiagramWithBrandMarks, writeDiagram, svgAccessibleText, svgRootAttrs } from '../shared/cli.mjs';
import { componentBox, boundaryBox, connectionPath } from '../shared/layout-report.mjs';
-import { throwDiagnosticProblems } from '../shared/diagnostics.mjs';
+import { rendererFailure, throwDiagnosticProblems } from '../shared/diagnostics.mjs';
import { legendFootprint, relationshipLegendObstacles, resolveLegend, renderLegend as renderResolvedLegend } from '../shared/legend.mjs';
import { availableNodeTextWidth, fittedNodeFontSize, minimumNodeTextWidth } from '../shared/text-fit.mjs';
import { brandLabelFitWidth, brandMetadataFor, brandTopRailProblem, renderBrandMark } from '../shared/brand-marks.mjs';
@@ -366,6 +366,7 @@ const legendY = () => viewBox[1] - 16;
// ---- Validation: mechanical correctness, never layout taste -----------------
function validateArchitecture() {
const problems = [];
+ const diagnostics = [];
if (resolvedBoundaryTitles.readabilityProblem) {
problems.push(resolvedBoundaryTitles.readabilityProblem);
}
@@ -521,7 +522,36 @@ function validateArchitecture() {
}
for (const b of boundaries) {
if (b.x < 0 || b.y < 0 || b.x + b.width > viewBox[0] || b.y + b.height > viewBox[1]) {
- problems.push(`Boundary "${b.label}" extends outside the viewBox — its members sit too close to the canvas edge; add margin or enlarge meta.viewBox.`);
+ const overflow = {
+ left: Math.max(0, -b.x),
+ top: Math.max(0, -b.y),
+ right: Math.max(0, b.x + b.width - viewBox[0]),
+ bottom: Math.max(0, b.y + b.height - viewBox[1]),
+ };
+ const sides = Object.entries(overflow).filter(([, pixels]) => pixels > 0)
+ .map(([side, pixels]) => `${side} by ${Math.ceil(pixels)}px`).join(', ');
+ const supportedFixes = [];
+ if (overflow.left || overflow.top) {
+ supportedFixes.push(`move the wrapped components right by at least ${Math.ceil(overflow.left)}px and down by at least ${Math.ceil(overflow.top)}px, then revalidate connected routes and the opposite canvas sides; enlarging meta.viewBox cannot fix left/top overflow`);
+ }
+ if (overflow.right || overflow.bottom) {
+ supportedFixes.push(`increase meta.viewBox to at least [${Math.ceil(Math.max(viewBox[0], b.x + b.width))}, ${Math.ceil(Math.max(viewBox[1], b.y + b.height))}] for right/bottom overflow, or move the wrapped components inward; revalidate desktop readability`);
+ }
+ const message = `Boundary "${b.label}" extends outside the viewBox (${sides}) — preserve wraps membership and repair the measured canvas side.`;
+ diagnostics.push({
+ code: 'layout/boundary-out-of-bounds',
+ severity: 'error',
+ message,
+ subject: { diagramType: 'architecture', boundary: { kind: b.kind, label: b.label, wraps: b.wraps } },
+ evidence: {
+ bounds: { x: b.x, y: b.y, width: b.width, height: b.height },
+ viewBox: [...viewBox],
+ overflow,
+ members: asArray(b.wraps).map((id) => components.get(id)).filter(Boolean).map(componentBox),
+ },
+ supportedFixes,
+ });
+ problems.push(message);
}
}
@@ -633,6 +663,7 @@ function validateArchitecture() {
if (problems.length) {
throwDiagnosticProblems('Architecture layout validation failed', problems, {
subject: { diagramType: 'architecture' },
+ diagnostics,
});
}
}
@@ -774,17 +805,30 @@ ${renderLegend()}
</svg>`;
}
-validateArchitecture();
if (layoutJsonMode) {
- console.log(JSON.stringify(buildLayoutReport(), null, 2));
- process.exit(0);
+ try {
+ validateArchitecture();
+ } catch (error) {
+ // A rejected layout is still useful repair evidence. Input/implementation
+ // failures must retain their existing failure boundary, not partial geometry.
+ if (!error.archifyDiagnostics?.length) throw error;
+ console.log(JSON.stringify({
+ ...buildLayoutReport(),
+ ...rendererFailure(error),
+ contract: 'archify-architecture-layout-v1',
+ }, null, 2));
+ process.exitCode = 1;
+ }
+ if (!process.exitCode) console.log(JSON.stringify(buildLayoutReport(), null, 2));
+} else {
+ validateArchitecture();
+ writeDiagram({
+ outPath,
+ template,
+ diagramType: 'architecture',
+ meta: arch.meta,
+ svg: renderSvg(),
+ cards: arch.cards,
+ sourceEvidence,
+ });
}
-writeDiagram({
- outPath,
- template,
- diagramType: 'architecture',
- meta: arch.meta,
- svg: renderSvg(),
- cards: arch.cards,
- sourceEvidence,
-});
diff --git a/archify/renderers/shared/diagnostics.mjs b/archify/renderers/shared/diagnostics.mjs
index 0b267363..c725c62e 100644
--- a/archify/renderers/shared/diagnostics.mjs
+++ b/archify/renderers/shared/diagnostics.mjs
@@ -53,9 +53,10 @@ export function throwDiagnosticError(message, diagnostics) {
throw error;
}
-export function throwDiagnosticProblems(prefix, problems, { code = 'layout/constraint', subject = {} } = {}) {
+export function throwDiagnosticProblems(prefix, problems, { code = 'layout/constraint', subject = {}, diagnostics: details = [] } = {}) {
const messages = (problems || []).map((problem) => String(problem));
- const diagnostics = messages.map((message) => normalizedDiagnostic({
+ const byMessage = new Map(details.map((entry) => [entry.message, entry]));
+ const diagnostics = messages.map((message) => normalizedDiagnostic(byMessage.get(message) || {
code,
severity: 'error',
message,
@@ -77,7 +78,7 @@ function fallbackDiagnostic(error) {
supportedFixes: [],
});
}
-function rendererFailure(error) {
+export function rendererFailure(error) {
const attached = Array.isArray(error?.archifyDiagnostics)
? error.archifyDiagnostics.map(normalizedDiagnostic)
: [];
diff --git a/archify/test/architecture-repair-evidence.test.mjs b/archify/test/architecture-repair-evidence.test.mjs
new file mode 100644
index 00000000..adcd9818
--- /dev/null
+++ b/archify/test/architecture-repair-evidence.test.mjs
@@ -0,0 +1,124 @@
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import test from 'node:test';
+import { fileURLToPath } from 'node:url';
+
+const root = fileURLToPath(new URL('../', import.meta.url));
+const cli = path.join(root, 'bin/archify.mjs');
+const renderer = path.join(root, 'renderers/architecture/render-architecture.mjs');
+function setup(t, positions, viewBox = [600, 420]) {
+ const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-repair-evidence-'));
+ t.after(() => fs.rmSync(cwd, { recursive: true, force: true }));
+ const input = path.join(cwd, 'source.json');
+ const diagram = {
+ schema_version: 1, diagram_type: 'architecture',
+ meta: { title: 'Backend', quality_profile: 'standard', viewBox },
+ components: positions.map((pos, index) => ({ id: `n${index}`, type: 'backend', label: `Node ${index}`, pos, size: [120, 60] })),
+ boundaries: [{ kind: 'region', label: 'Backend', wraps: positions.map((_, i) => `n${i}`) }],
+ };
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ return { cwd, input, diagram };
+}
+function run(args, cwd) {
+ return spawnSync(process.execPath, args, { cwd, encoding: 'utf8' });
+}
+function validate(input, cwd, flags = []) {
+ const result = run([cli, 'validate', 'architecture', input, '--json', ...flags], cwd);
+ assert.equal(result.stderr, '', result.stderr);
+ return { result, receipt: JSON.parse(result.stdout) };
+}
+
+for (const [side, positions, expected, growsCanvas] of [
+ ['left', [[20, 70], [80, 240]], 10, false],
+ ['top', [[80, 20], [150, 240]], 10, false],
+ ['right', [[480, 70], [440, 240]], 30, true],
+ ['bottom', [[80, 70], [150, 350]], 10, true],
+]) {
+ test(`boundary ${side} overflow gives measured side, members and applicable fixes`, t => {
+ const { cwd, input } = setup(t, positions);
+ const { result, receipt } = validate(input, cwd);
+ assert.equal(result.status, 1);
+ const entries = receipt.diagnostics.filter(d => d.code === 'layout/boundary-out-of-bounds');
+ assert.equal(entries.length, 1);
+ const diagnostic = entries[0];
+ assert.deepEqual(diagnostic.subject.boundary.wraps, ['n0', 'n1']);
+ assert.equal(diagnostic.evidence.overflow[side], expected);
+ assert.deepEqual(diagnostic.evidence.members.map(m => m.id), ['n0', 'n1']);
+ assert.deepEqual(diagnostic.evidence.viewBox, [600, 420]);
+ assert.equal(diagnostic.supportedFixes.some(f => f.startsWith('increase meta.viewBox')), growsCanvas);
+ if (!growsCanvas) assert.match(diagnostic.supportedFixes.join(' '), /enlarging meta.viewBox cannot fix left\/top/);
+ assert.equal(receipt.diagnostics.filter(d => d.message === diagnostic.message).length, 1);
+ });
+}
+
+test('enlarging the canvas cannot repair top overflow; moving members preserves a valid multi-row boundary', t => {
+ const { cwd, input, diagram } = setup(t, [[80, 20], [150, 240]]);
+ diagram.meta.viewBox = [1200, 800];
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ assert.equal(validate(input, cwd).result.status, 1);
+ diagram.meta.viewBox = [600, 420];
+ diagram.components.forEach(c => { c.pos[1] += 30; });
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ const { result, receipt } = validate(input, cwd);
+ assert.equal(result.status, 0, result.stdout);
+ assert.equal(receipt.ok, true);
+ assert.deepEqual(diagram.boundaries[0].wraps, ['n0', 'n1']);
+});
+
+test('rejected layout JSON retains geometry and diagnostics without changing source or trusted output', t => {
+ const { cwd, input } = setup(t, [[80, 20], [150, 240]]);
+ const before = fs.readFileSync(input);
+ const output = path.join(cwd, 'trusted.html');
+ fs.writeFileSync(output, 'trusted artifact');
+ for (const args of [
+ [cli, 'validate', 'architecture', input, '--layout-json'],
+ [cli, 'validate', 'architecture', input, '--layout-json', '--json'],
+ [renderer, input, output, '--layout-json'],
+ [cli, 'inspect', 'architecture', input],
+ ]) {
+ const result = run(args, cwd);
+ assert.equal(result.status, 1, result.stderr);
+ assert.equal(result.stderr, '');
+ const receipt = JSON.parse(result.stdout);
+ assert.equal(receipt.ok, false);
+ assert.equal(receipt.contract, 'archify-architecture-layout-v1');
+ assert.equal(receipt.components.length, 2);
+ assert.equal(receipt.boundaries[0].y, -10);
+ assert.deepEqual(receipt.connections, []);
+ assert.ok(receipt.diagnostics.some(d => d.code === 'layout/boundary-out-of-bounds'));
+ assert.deepEqual(fs.readFileSync(input), before);
+ assert.equal(fs.readFileSync(output, 'utf8'), 'trusted artifact');
+ assert.deepEqual(fs.readdirSync(cwd).sort(), ['source.json', 'trusted.html']);
+ }
+ const delivery = run([cli, 'deliver', 'architecture', input, output, '--json'], cwd);
+ assert.equal(delivery.status, 1);
+ assert.equal(fs.readFileSync(output, 'utf8'), 'trusted artifact');
+});
+
+test('direct renderer text explains the boundary repair and retains non-zero exit', t => {
+ const { cwd, input } = setup(t, [[80, 20], [150, 240]]);
+ const result = run([renderer, input, path.join(cwd, 'out.html')], cwd);
+ assert.equal(result.status, 1);
+ assert.equal(result.stdout, '');
+ assert.match(result.stderr, /layout\/boundary-out-of-bounds/);
+ assert.match(result.stderr, /top by 10px/);
+ assert.match(result.stderr, /enlarging meta.viewBox cannot fix left\/top overflow/);
+ assert.equal(fs.existsSync(path.join(cwd, 'out.html')), false);
+});
+
+test('successful layout keeps existing fields; malformed input never masquerades as computed layout', t => {
+ const { cwd, input } = setup(t, [[80, 70], [150, 240]]);
+ const good = validate(input, cwd, ['--layout-json']);
+ assert.equal(good.result.status, 0);
+ assert.equal(good.receipt.ok, true);
+ assert.equal(good.receipt.components.length, 2);
+ assert.equal(good.receipt.contract, undefined);
+ fs.writeFileSync(input, '{"components":');
+ const invalid = validate(input, cwd, ['--layout-json']);
+ assert.equal(invalid.result.status, 1);
+ assert.equal(invalid.receipt.components, undefined);
+ assert.ok(invalid.receipt.diagnostics.some(d => d.code === 'input/json-parse'));
+});