Skip to content

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

fix(architecture): identify nodes behind route detours in repair evidence

tt-a1i3f4329c768fd
diff --git a/archify/SKILL.md b/archify/SKILL.md
index 03141704..7035ece2 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -39,7 +39,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer R
A passing receipt proves that the included `validate`, `deliver`, strict `check`, and deterministic real-browser `browser-check` gates passed. Do not read its full sidecar or rerun individual commands afterward; use a standalone command only for an explicitly separate execution or focused failure diagnosis.
-5. A non-zero exit is never success. Use its compact stdout or `evidence.summaryReceipt`; read the full receipt only if the summary is truncated and lacks enough evidence for a coherent repair. After a validation failure, edit the connected neighborhood named by the evidence in one coherent change. When several affected routes share nodes, read [Architecture layout repair](references/architecture-layout-repair.md) for Architecture, then reposition those nodes and their neighbors together. Choose endpoint sides for the main rail and return corridors as part of that same repair; reserve detailed waypoints or label overrides for an isolated remaining defect. Keep unrelated geometry intact. Do not run validate, layout, render, or finalize first; edit the existing JSON in place. Geometry never authorizes deleting or merging a source-backed component, relationship, reference, view, card, boundary, or semantic label; reroute, reposition, or add readable canvas space instead. After the edit, rerun the complete `finalize` command from step 4 once, retaining `--quality showcase` and `--repo-root <repo-root>` for repository-backed candidates. If that output already has browser evidence from a different candidate, preserve it and add a fresh `--out-dir <output-stem>.review-<revision>` for the new candidate; use the same directory for its `visual-check`. After editing, omit any earlier `--candidate-sha256`: it binds the previous candidate. Use `--layout-json` before the edit only when compact evidence lacks needed geometry. A receipt with only 4 artifact checks is basic validation: require all 9 checks with 0 composition errors and 0 warnings. Fix `meta.quality_profile` before geometry. For workflow v2, use the stable compiler receipt; solver internals are not authoring controls. Use standalone `validate` only for focused diagnosis, with `--repo-root <repo-root>` for a repository. A passing validation returns `candidateFrozen: true`; do not edit, revalidate, or reread it. Run its `nextAction.arguments`, replacing only `<output.html>`. Retry later environment or evidence failures against the frozen candidate. If measured evidence requires a source edit, treat it as a new candidate and rerun the complete `finalize` command without the old hash. If one issue survives two focused repairs, inspect measured geometry or the relevant contract; after one evidence-based retry, stop truthfully. A lower error count never justifies changing meaning.
+5. A non-zero exit is never success. Use its compact stdout or `evidence.summaryReceipt`; read the full receipt only if the summary is truncated and lacks enough evidence for a coherent repair. After a validation failure, edit the connected neighborhood named by the evidence in one coherent change. When several affected routes share nodes, read [Architecture layout repair](references/architecture-layout-repair.md) for Architecture, then reposition those nodes and their neighbors together. Choose endpoint sides for the main rail and return corridors as part of that same repair; reserve detailed waypoints or label overrides for an isolated remaining defect. Keep unrelated geometry intact only when the surrounding composition already reads clearly; a blocked main path requires reflowing the connected scene. Do not run validate, layout, render, or finalize first; edit the existing JSON in place. Geometry never authorizes deleting or merging a source-backed component, relationship, reference, view, card, boundary, or semantic label; reroute, reposition, or add readable canvas space instead. After the edit, rerun the complete `finalize` command from step 4 once, retaining `--quality showcase` and `--repo-root <repo-root>` for repository-backed candidates. If that output already has browser evidence from a different candidate, preserve it and add a fresh `--out-dir <output-stem>.review-<revision>` for the new candidate; use the same directory for its `visual-check`. After editing, omit any earlier `--candidate-sha256`: it binds the previous candidate. Use `--layout-json` before the edit only when compact evidence lacks needed geometry. A receipt with only 4 artifact checks is basic validation: require all 9 checks with 0 composition errors and 0 warnings. Fix `meta.quality_profile` before geometry. For workflow v2, use the stable compiler receipt; solver internals are not authoring controls. Use standalone `validate` only for focused diagnosis, with `--repo-root <repo-root>` for a repository. A passing validation returns `candidateFrozen: true`; do not edit, revalidate, or reread it. Run its `nextAction.arguments`, replacing only `<output.html>`. Retry later environment or evidence failures against the frozen candidate. If measured evidence requires a source edit, treat it as a new candidate and rerun the complete `finalize` command without the old hash. If one issue survives two focused repairs, inspect measured geometry or the relevant contract; after one evidence-based retry, stop truthfully. A lower error count never justifies changing meaning.
## Update awareness
diff --git a/archify/bin/finalize.mjs b/archify/bin/finalize.mjs
index 3c8aa453..88620a9f 100644
--- a/archify/bin/finalize.mjs
+++ b/archify/bin/finalize.mjs
@@ -519,7 +519,7 @@ export function compactFinalizeReceipt(receipt) {
detours: routeReview.detours.slice(0, 8),
truncated: routeReview.crossings.length > 8 || routeReview.detours.length > 8,
},
- repair: 'Trace these relationships at the desktop viewport. If several routes tangle around the same nodes, reposition that connected neighborhood together, preserving all semantics and unrelated geometry; rerun finalize once. Choose endpoint sides for the main rail and return corridors together with placement; reserve detailed waypoints or label overrides for an isolated remaining defect.',
+ repair: 'Trace these relationships at the desktop viewport. For Architecture, use references/architecture-layout-repair.md: reflow a blocked main path or tangled connected scene, and repair an isolated defect locally only when the surrounding composition is accepted. Preserve all semantic content and user-fixed geometry. Rerun finalize once after the edit.',
} : {}),
};
}
@@ -527,7 +527,9 @@ export function compactFinalizeReceipt(receipt) {
compact.nextAction = {
action: 'edit-in-place',
candidate: receipt.specification?.path,
- constraint: 'Preserve unaffected semantics and geometry; do not replace the whole candidate.',
+ constraint: receipt.type === 'architecture'
+ ? 'Preserve all semantics and user-fixed geometry. Use references/architecture-layout-repair.md to choose a local repair or connected-scene reflow; edit the existing candidate.'
+ : 'Preserve unaffected semantics and geometry; do not replace the whole candidate.',
then: 'finalize-once',
};
}
diff --git a/archify/references/architecture-layout-repair.md b/archify/references/architecture-layout-repair.md
index 6614a66d..c3ecad93 100644
--- a/archify/references/architecture-layout-repair.md
+++ b/archify/references/architecture-layout-repair.md
@@ -2,6 +2,12 @@
Use this after actual visual review finds several tangled routes. A successful machine receipt does not settle composition. Work on the existing candidate, retaining all required components, relationships, labels, evidence, boundaries, and node sizes.
+## Choose the repair scope
+
+If the main and secondary chains already read clearly, repair the isolated defect locally. If a main chain is blocked, several routes tangle, or a local fix repeatedly damages another route, reflow the connected scene in one edit. Preserve all semantics and user-fixed geometry; agent-generated positions and route controls may change. After moving nodes, remove stale generated route overrides before selecting sides for the new placement.
+
+The receipt's `directCorridorBlockers`, when present, names nodes between an edge's aligned endpoints. This is geometric evidence, not proof that the edge is the main path or a new validation failure. Trace the reader's actual main path first. When a listed blocker interrupts that path, reposition the connected group instead of adding another detour.
+
## One coherent repair
1. Trace the affected relationships and their endpoints in the JSON. Before choosing coordinates, write the reader’s main path as an ordered list of existing edges, then identify shared state and real feedback cycles. Every neighboring pair in that main path must have the relationship being explained; place other components on branches beside their actual owner. Use `validate architecture <candidate.json> --layout-json --repo-root <root>` once if the compact receipt and screenshot do not reveal the needed route or label geometry; omit `--repo-root` only for a design without repository evidence. Do not guess repeated waypoint coordinates.
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index aa66991e..e8736b35 100644
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@ -261,7 +261,7 @@ Complete stage receipts and timings remain available for auditing in
`<path>-summary.json`. Read the full receipt only when the compact summary is
truncated and its shown subjects and evidence cannot identify a coherent local
repair, or when complete audit evidence was explicitly requested. The compact
-receipt reports `visualReview: "not-requested"`; the automated gate does not create images or require a perceptual reviewer. A compact `visualReviewRecommendation` retains positive crossover and route-detour metrics from the strict check so the author can apply the review escalation below without reading the full receipt. A recommendation does not change the machine exit code or claim that review happened. Its `affectedRoutes` identifies crossing pairs and detours (up to eight of each, with a truncation flag); the full strict-check `composition.routeReview` retains all affected relationships. Use these IDs to trace the routes in the captured default viewport. When multiple defects share a hub, repair that connected neighborhood together before tuning individual sides or labels; preserve every semantic fact and unrelated geometry.
+receipt reports `visualReview: "not-requested"`; the automated gate does not create images or require a perceptual reviewer. A compact `visualReviewRecommendation` retains positive crossover and route-detour metrics from the strict check so the author can apply the review escalation below without reading the full receipt. A recommendation does not change the machine exit code or claim that review happened. Its `affectedRoutes` identifies crossing pairs and detours (up to eight of each, with a truncation flag); the full strict-check `composition.routeReview` retains all affected relationships. Use these IDs to trace the routes in the captured default viewport. Detours may include `directCorridorBlockers`, identifying nodes between aligned endpoints. These are geometric review clues, not new validation failures or inferred main-path semantics. For a blocked main path or several tangled routes, follow [Architecture layout repair](architecture-layout-repair.md) and reflow the connected scene before tuning individual sides or labels. Preserve every semantic fact; retain unrelated positions only when their surrounding composition is already accepted.
A passing finalizer receipt is sufficient evidence for all four gates. Merely
naming the gates or requiring each one to pass does not require replaying their
diff --git a/archify/scripts/check-render-output.mjs b/archify/scripts/check-render-output.mjs
index fea6db2c..10d6e26d 100644
--- a/archify/scripts/check-render-output.mjs
+++ b/archify/scripts/check-render-output.mjs
@@ -151,6 +151,7 @@ if (svgMatches.length === 1) {
const routedRelationships = arrows
.filter((arrow) => arrow.from && arrow.to && arrow.routePoints.length)
.map((arrow) => ({ relation: arrow, relationIndex: arrow.index, points: arrow.routePoints }));
+ const nodeRects = svgAttrs.transform ? [] : collectUntransformedNodeRects(beforeLegend);
const routeMetrics = routeBudgetMetrics({ routedRelations: routedRelationships });
const routeRhythmIssues = collectRouteRhythmIssues({ routedRelations: routedRelationships });
const ambiguousCorridors = collectAmbiguousCorridors({
@@ -237,10 +238,12 @@ if (svgMatches.length === 1) {
})),
detours: routedRelationships.flatMap((entry) => {
const metrics = routeBudgetMetrics({ routedRelations: [entry] });
+ const blockers = directCorridorBlockers(entry.relation, nodeRects);
return metrics.routesOverSuggestedBends || metrics.routesOverSuggestedStretch ? [{
relationship: relationshipRecord(entry.relation),
bends: metrics.maxBends,
stretch: metrics.maxStretch == null ? null : Math.round(metrics.maxStretch * 1000) / 1000,
+ ...(blockers.length ? { directCorridorBlockers: blockers } : {}),
}] : [];
}),
},
@@ -578,6 +581,53 @@ function relationshipName(arrow) {
: `relationship "${arrow.from}" -> "${arrow.to}"`;
}
+// Review evidence only. Mask rectangles are the visible node bounds emitted by
+// our renderers. Skip transformed ancestry rather than mixing coordinate spaces.
+function collectUntransformedNodeRects(fragment) {
+ const groups = [];
+ const nodes = new Map();
+ for (const token of fragment.matchAll(SVG_TAG_TOKEN)) {
+ if (!token[2]) continue;
+ const name = token[2].toLowerCase();
+ if (name === 'g') {
+ if (token[1]) groups.pop();
+ else if (!/\/\s*>$/.test(token[0])) groups.push(parseAttrs(token[0]));
+ continue;
+ }
+ if (name !== 'rect' || token[1] || groups.some((group) => group.transform)) continue;
+ const attrs = parseAttrs(token[0]);
+ const owner = [...groups].reverse().find((group) => group['data-node-id']);
+ if (!owner || attrs.transform || !String(attrs.class || '').split(/\s+/).includes('c-mask')) continue;
+ const box = ['x', 'y', 'width', 'height'].map((key) => numberAttr(attrs, key));
+ if (!box.every(Number.isFinite) || box[2] <= 0 || box[3] <= 0) continue;
+ const id = owner['data-node-id'];
+ // Ambiguous ownership is not reliable evidence for moving a node.
+ nodes.set(id, nodes.has(id) ? null : { id, label: owner['data-node-label'] || id, box });
+ }
+ return [...nodes.values()].filter(Boolean);
+}
+
+function directCorridorBlockers(relation, nodes) {
+ const from = nodes.find((node) => node.id === relation.from);
+ const to = nodes.find((node) => node.id === relation.to);
+ if (!from || !to || from === to) return [];
+ const center = ({ box: [x, y, w, h] }) => [x + w / 2, y + h / 2];
+ const a = center(from);
+ const b = center(to);
+ const horizontal = Math.abs(a[1] - b[1]) < 0.01;
+ const vertical = Math.abs(a[0] - b[0]) < 0.01;
+ if (horizontal === vertical) return [];
+ const axis = horizontal ? 0 : 1;
+ const cross = 1 - axis;
+ const [first, last] = a[axis] < b[axis] ? [from, to] : [to, from];
+ const low = first.box[axis] + first.box[axis + 2];
+ const high = last.box[axis];
+ if (high <= low) return [];
+ return nodes.filter((node) => node !== from && node !== to
+ && node.box[axis] < high && node.box[axis] + node.box[axis + 2] > low
+ && node.box[cross] < a[cross] && node.box[cross] + node.box[cross + 2] > a[cross]);
+}
+
function relationshipRecord(arrow) {
const stableIndex = Number(arrow.key);
return {
diff --git a/archify/test/architecture-repair-evidence.test.mjs b/archify/test/architecture-repair-evidence.test.mjs
index 2044c5a9..b825b6d0 100644
--- a/archify/test/architecture-repair-evidence.test.mjs
+++ b/archify/test/architecture-repair-evidence.test.mjs
@@ -31,6 +31,22 @@ function validate(input, cwd, flags = []) {
return { result, receipt: JSON.parse(result.stdout) };
}
+test('delivered Architecture review names a node blocking the direct main corridor', t => {
+ const { cwd, input, diagram } = setup(t, [[50, 100], [250, 100], [450, 100]], [680, 320]);
+ diagram.connections = [{ from: 'n0', to: 'n2', fromSide: 'right', toSide: 'left' }];
+ fs.writeFileSync(input, JSON.stringify(diagram));
+ const output = path.join(cwd, 'diagram.html');
+ const rendered = run([cli, 'render', 'architecture', input, output], cwd);
+ assert.equal(rendered.status, 0, rendered.stdout + rendered.stderr);
+ const checked = run([path.join(root, 'scripts/check-render-output.mjs'), output], cwd);
+ assert.equal(checked.status, 0, checked.stdout + checked.stderr);
+ const report = JSON.parse(checked.stdout);
+ assert.deepEqual(report.composition.routeReview.detours[0].directCorridorBlockers, [{
+ id: 'n1', label: 'Node 1', box: [250, 100, 120, 60],
+ }]);
+ assert.equal(report.composition.summary.errors, 0, 'an obstacle-aware route remains legal');
+});
+
for (const [side, positions, expected, growsCanvas] of [
['left', [[20, 70], [80, 240]], 10, false],
['top', [[80, 20], [150, 240]], 10, false],
diff --git a/archify/test/finalize.test.mjs b/archify/test/finalize.test.mjs
index 35d9b559..03384fd4 100644
--- a/archify/test/finalize.test.mjs
+++ b/archify/test/finalize.test.mjs
@@ -281,7 +281,9 @@ test('compact success retains route-quality review signals without claiming perc
test('compact success bounds review context and preserves relationship identity', () => {
const crossings = Array.from({ length: 10 }, (_, index) => ({ left: { id: `edge-${index}` }, right: { id: 'hub' }, point: [index, 50] }));
- const detours = [{ relationship: { id: 'return', from: 'worker', to: 'api' }, bends: 4, stretch: 1.5 }];
+ const detours = [{ relationship: { id: 'return', from: 'worker', to: 'api' }, bends: 4, stretch: 1.5,
+ directCorridorBlockers: [{ id: 'store', label: 'Shared store', box: [100, 40, 80, 50] }],
+ }];
const compact = compactFinalizeReceipt({ ok: true, stages: { check: { receipt: { composition: {
metrics: { resolvedCrossovers: 10, routesOverSuggestedBends: 1 }, routeReview: { crossings, detours },
} } } } });
@@ -290,6 +292,7 @@ test('compact success bounds review context and preserves relationship identity'
});
assert.equal(crossings.length, 10, 'compaction does not truncate the full evidence');
assert.equal(compact.visualReview, 'not-requested');
+ assert.match(compact.visualReviewRecommendation.repair, /architecture-layout-repair\.md/);
});
test('compact failure receipts retain diverse actionable subjects without embedding full stage evidence', () => {
@@ -322,6 +325,8 @@ test('compact failure receipts retain diverse actionable subjects without embedd
assert.equal(new Set(compact.diagnostics.map(({ subject }) => subject.id)).size, 8);
assert.deepEqual(compact.diagnosticSummary, { total: 20, shown: 8, truncated: true });
assert.equal(compact.nextAction.action, 'edit-in-place');
+ assert.match(compact.nextAction.constraint, /Preserve all semantics and user-fixed geometry/);
+ assert.match(compact.nextAction.constraint, /local repair or connected-scene reflow/);
assert.equal('stages' in compact, false);
assert.ok(JSON.stringify(compact).length < JSON.stringify(receipt).length / 4);
});
diff --git a/archify/test/render-output-checks.test.mjs b/archify/test/render-output-checks.test.mjs
index 4db7a82d..6a67843b 100644
--- a/archify/test/render-output-checks.test.mjs
+++ b/archify/test/render-output-checks.test.mjs
@@ -765,6 +765,30 @@ test('render output check: composition receipt records neutral normalized route
assert.deepEqual(result.composition.suggestedLimits, { bendsPerRelationship: 2, stretch: 1.35, segmentPx: 16, microSegmentPx: 8 });
});
+test('render output check: detours identify intervening nodes without failing valid routing', () => {
+ for (const vertical of [false, true]) {
+ const point = (x, y) => vertical ? [y, x] : [x, y];
+ const rect = (id, x, y, extra = '') => {
+ const [left, top] = point(x, y);
+ return `<g data-node-id="${id}" data-node-label="${id} role" ${extra}><rect class="c-mask" x="${left}" y="${top}" width="40" height="40"/></g>`;
+ };
+ const points = [[50, 70], [70, 70], [70, 20], [190, 20], [190, 70], [210, 70]].map(([x, y]) => point(x, y));
+ const edge = `<path data-edge-from="a" data-edge-to="b" data-composition-points="${points.map(p => p.join(',')).join(';')}" d="M ${points.map(p => p.join(' ')).join(' L ')}" class="a-default" marker-end="url(#arrowhead)"/>`;
+ const endpoints = rect('a', 10, 50) + rect('b', 210, 50);
+ const { code, result } = checkHtml(`blocked-direct-${vertical}`, endpoints + rect('blocker', 110, 50) + rect('off-row', 110, 100) + edge, 'showcase', '0 0 560 280');
+ assert.equal(code, 0, 'a legal route around an intervening node is still valid');
+ assert.deepEqual(result.composition.summary, { errors: 0, warnings: 0 });
+ assert.deepEqual(result.composition.routeReview.detours[0].directCorridorBlockers, [{
+ id: 'blocker', label: 'blocker role', box: [...point(110, 50), 40, 40],
+ }]);
+
+ const transformed = checkHtml(`transformed-blocker-${vertical}`, endpoints + `<g transform="translate(100 100)">${rect('blocker', 110, 50)}</g>` + edge, 'showcase', '0 0 560 280');
+ assert.equal(transformed.result.composition.routeReview.detours[0].directCorridorBlockers, undefined, 'unresolved coordinate spaces are not guessed');
+ const offset = checkHtml(`offset-endpoints-${vertical}`, rect('a', 10, 40) + rect('b', 210, 50) + rect('blocker', 110, 50) + edge, 'showcase', '0 0 560 280');
+ assert.equal(offset.result.composition.routeReview.detours[0].directCorridorBlockers, undefined, 'different rows have no single direct corridor');
+ }
+});
+
test('render output check: endpoint stubs from 8px pass while cramped interior turns are profile-aware', () => {
const clean = checkHtml('endpoint-stubs', `
<path data-edge-id="lane-hop" data-edge-from="a" data-edge-to="b" data-composition-points="0,20;13,20;13,60;80,60;80,73" d="M 0 20 L 13 20 L 13 60 L 80 60 L 80 73" class="a-default" marker-end="url(#arrowhead)"/>