Skip to content

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

fix: make first diagram delivery trustworthy (#31)

tt-a1if0806ad2a6cc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5c3a2806..c342ee31 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -58,6 +58,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
- **Generated Proof Lab.** `node scripts/build-gallery.mjs` now regenerates 11 live scenario proofs across all five diagram modes, their exact JSON sources, 77 artifact checks, composition receipts, byte sizes, SHA-256 digests, and three-step reader stories. A dedicated test fails when any recipe lacks a proof or any checked-in artifact drifts.
### Changed
+- The Skill delivery loop now treats a successful render as a candidate: after deterministic validation it requires a final browser/raster readback when available, allows at most two focused correction rounds, and reports explicit `validation`, `visual_review`, and `correction_rounds` evidence. Environments without an image reader must say the review was skipped instead of claiming visual approval.
- Embedded artifacts now pause ambient trace loops by default. The landing-page Live Proof Stage opts into one named chapter at a time, gallery cards stay static and cheap, direct proof actions open a self-playing Presentation Stage, and the README reel captures the same bounded chapter contract.
- Wide diagrams now use a contained 720px mobile reading surface instead of shrinking labels into an unreadable thumbnail. Guided views auto-center the authored path, internal swiping never widens the page, and zoom/focus controls remain pinned while the diagram moves underneath.
- The landing page now shows a real moving, explorable artifact before leading uncertain users into the scenario chooser; the full Proof Lab remains the broader evidence surface for rendered capability.
@@ -66,6 +67,8 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
- Generated diagrams support `?embed=1`, a chrome-free read-only surface used by the live gallery previews.
### Fixed
+- Clean Flow is now a universal semantic correctness invariant instead of an opt-in composition gate. Profile-less default rendering rejects a relationship whose routed geometry passes through an unrelated opaque node, including the real auto-route regression from #24, while explicit waypoints around the obstacle remain valid. `standard` and `showcase` still control only the stricter composition budgets.
+- East Asian text measurement now includes wide vertical punctuation and supplementary script blocks while keeping halfwidth Katakana at one unit. Regression coverage preserves Hiragana, Katakana, Bopomofo, Hangul compatibility letters, fullwidth forms, emoji, and supplementary CJK behavior.
- WebM export now renders an explicit time-varying canvas scene over the static canonical diagram instead of repeatedly drawing one browser-cached SVG image frame. Signals follow the real authored `path` / `line` / `polyline` geometry, node pulses retain authored order, and the six-second browser-native recording is visibly animated without mutating the SVG, adding dependencies, or leaking viewer state.
- WebM export now requests a final encoder flush before stopping. Embedded browser shells that still report MediaRecorder support but return an empty stream fail with a machine-readable receipt, disable the unavailable menu item, and show a non-blocking toast instead of trapping the reader in repeated alert dialogs; animated SVG and the rest of the export surface remain available.
- Guided-view and node-focus state now follows same-document `#view=` / `#focus=` hash changes, so browser history and manually edited deep links cannot leave the address bar and diagram out of sync.
diff --git a/README.md b/README.md
index c97cd5a5..de456c0d 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ Archify is an agent skill for Claude, Codex CLI, and opencode. It produces a sel
- **Explore real topology** — find nodes, inspect relationships, trace routes, compare roles, and play guided stories
- **Motion is optional** — output stays static unless `meta.animation: "trace"` is explicitly enabled
- **Portable exports** — copy PNG or download PNG, JPEG, WebP, dual-theme SVG, and trace-enabled WebM
-- **Typed and checked** — JSON IR, bundled schema validation, layout checks, and opt-in quality profiles
+- **Typed and checked** — JSON IR, bundled schema validation, default semantic safety gates, and opt-in composition profiles
- **Self-contained output** — one shareable HTML file with no viewer runtime dependency
- **Built for agent workflows** — install once, then create and refine diagrams through conversation
diff --git a/README_EN.md b/README_EN.md
index c97cd5a5..de456c0d 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -19,7 +19,7 @@ Archify is an agent skill for Claude, Codex CLI, and opencode. It produces a sel
- **Explore real topology** — find nodes, inspect relationships, trace routes, compare roles, and play guided stories
- **Motion is optional** — output stays static unless `meta.animation: "trace"` is explicitly enabled
- **Portable exports** — copy PNG or download PNG, JPEG, WebP, dual-theme SVG, and trace-enabled WebM
-- **Typed and checked** — JSON IR, bundled schema validation, layout checks, and opt-in quality profiles
+- **Typed and checked** — JSON IR, bundled schema validation, default semantic safety gates, and opt-in composition profiles
- **Self-contained output** — one shareable HTML file with no viewer runtime dependency
- **Built for agent workflows** — install once, then create and refine diagrams through conversation
diff --git a/README_ZH.md b/README_ZH.md
index b68da424..977b2961 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -15,7 +15,7 @@ Archify 是一个可用于 Claude、Codex CLI 和 opencode 的 Agent Skill。它
- **探索真实拓扑** —— 查找节点、检查关系、探查路径、对比角色、播放引导故事
- **动态默认关闭** —— 只有显式设置 `meta.animation: "trace"` 才启用动态
- **便携导出** —— 复制 PNG,下载 PNG / JPEG / WebP / 双主题 SVG / WebM
-- **Typed + Checked** —— Typed JSON IR、内置 Schema 校验、布局检查和可选质量门禁
+- **Typed + Checked** —— Typed JSON IR、内置 Schema 校验、默认语义安全门禁和可选构图档位
- **结果完全独立** —— 一个 HTML 文件即可查看和分享,不依赖 Viewer 服务
- **适合 Agent 工作流** —— 安装一次,通过对话持续生成和细调
diff --git a/archify.zip b/archify.zip
index a55a7913..3c74b79d 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index e5f42b6f..1ffba020 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -78,7 +78,7 @@ All five modes follow the same loop:
4. Validate the generated artifact: `node bin/archify.mjs validate <type> <input>.json --json`, explicitly add `--quality standard` for dense engineering diagrams or `--quality showcase` for polished delivery, or check an existing HTML file with `node bin/archify.mjs check <output>.html`. This catches malformed SVG output, non-finite SVG values, two-point diagonal arrows, arrows crossing the legend, and profile-aware relationship crossings.
5. If either step fails, the error names the JSON path or the fix (thresholds, valid ranges, which knob to change). Fix the JSON and re-run; never edit the renderer.
-Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/label: "router") must NOT have additional properties`. The renderers additionally fail fast on established layout problems: node/state overlap (including cross-lane), labels colliding with nodes or other labels, labels wider than their node, out-of-range columns/rows, too-short edges, and legends outside the viewBox. New composition gates are deliberately opt-in for v1 stability: if neither `meta.quality_profile` nor CLI `--quality` is present, an older schema-v1 document stays renderable and detectable composition findings do not become new hard failures. For new or edited work, choose `standard` or `showcase` explicitly. Both profiles enforce unrelated-node Clean Flow and structural container-border rules; the shared Clean Flow Gate reports `clean-flow/edge-through-node`, the exact collection/index and optional relationship ID, obstacle ID, first intersecting segment, 2px clearance, and supported routing/placement knobs before output is written. The composition receipt separately reports final visible paths: unrelated proper X crossings warn in `standard` and fail in `showcase`; showcase also fails any sub-8px route segment and sub-16px interior turn while preserving ordinary 8–15px endpoint stubs. Shared semantic endpoints, endpoint touches, and collinear relationship corridors are not proper crossings. Source/target boxes are endpoints; boundaries, lanes, stages, lifecycle bands, sequence segments/lifelines/activations, and other containers remain intentional pass-through geometry. CJK text is measured at double width automatically.
+Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/label: "router") must NOT have additional properties`. The renderers additionally fail fast on established layout problems: node/state overlap (including cross-lane), labels colliding with nodes or other labels, labels wider than their node, out-of-range columns/rows, too-short edges, and legends outside the viewBox. A relationship passing through an unrelated opaque semantic node is always a hard correctness failure, even when neither `meta.quality_profile` nor CLI `--quality` is present: paint order must never make one authored relationship look like a different topology. The shared Clean Flow Gate reports `clean-flow/edge-through-node`, the exact collection/index and optional relationship ID, obstacle ID, first intersecting segment, 2px clearance, and supported routing/placement knobs before output is written. Stricter composition preferences remain profile-aware. For new or edited work, choose `standard` or `showcase` explicitly; structural container-border rules apply to both explicit profiles, unrelated proper X crossings warn in `standard` and fail in `showcase`, and showcase also fails any sub-8px route segment and sub-16px interior turn while preserving ordinary 8–15px endpoint stubs. Shared semantic endpoints, endpoint touches, and collinear relationship corridors are not proper crossings. Source/target boxes are endpoints; boundaries, lanes, stages, lifecycle bands, sequence segments/lifelines/activations, and other containers remain intentional pass-through geometry. CJK text is measured at double width automatically.
Set `meta.animation: "trace"` only when the user asks for motion or a presentation/demo view. It adds lightweight SVG/CSS trace animation to renderer-marked arrows and nodes plus one explicit 44px `Live` / `Still` Motion Governor. Ambient scan, edge, and node motion must run one finite pass, permanently settle for that document generation, and restore every authored solid/security/async dash style; switching `Still` back to `Live` must not replay it. Story, Chapter, Route, Lens, Relationship Preview, Intent Trace, Focus, and Legend remain stronger semantic owners. `Still` must reset every effect to complete static meaning, pause active Story playback at its exact beat, persist the reader choice when storage is available, and never auto-resume playback. Dynamic `prefers-reduced-motion` and page hiding use the same stop path. Static artifacts must never start decorative motion or show the control; embed remains calm unless `?play=1` explicitly requests one bounded chapter. Route Probe uses one finite signal and then leaves the exact route static. Canonical SVG and raster exports remain still; only the isolated WebM clone may explicitly opt into the repeatable finite trace timeline. Motion ownership is viewer-only, tokenized for stale-safe cleanup, and never enters schema, IR, renderer layout, or authored geometry.
@@ -327,8 +327,8 @@ Typography inherits JetBrains Mono from the SVG root. Sizes: 11–12px component
- **Two-rect pattern everywhere**: opaque `c-mask` rect first, styled `c-<type>` rect on top — semi-transparent fills otherwise let arrows bleed through.
- **Arrows before components** in document order (SVG paints in order; arrows must sit behind boxes).
-- **Clean flow before delivery**: after explicitly choosing `standard` or `showcase`, a relationship may touch its own source/target boxes but must not pass through any unrelated semantic node. Fix `clean-flow/edge-through-node` with `fromSide`/`toSide`, a route/channel, explicit `via`, or node placement; do not hide the defect with paint order. Profile-less schema-v1 inputs remain compatibility-mode inputs and must not acquire a new hard failure during a 2.x upgrade.
-- **Choose a composition profile deliberately with the user**: `standard` keeps dense engineering topologies renderable and records route-rhythm/proper-X findings as warnings; `showcase` fails unrelated proper X crossings, any segment below 8px, and interior turn segments below 16px. Both explicit profiles enforce Clean Flow and structural border-run checks. Endpoint stubs from 8–15px remain valid because fixed lane gaps can require them. Use `meta.quality_profile` or CLI `--quality`, then repair with route/channel/via/side or placement controls. Do not silently add a profile to an existing v1 file.
+- **Clean flow before delivery**: with or without a quality profile, a relationship may touch its own source/target boxes but must not pass through any unrelated semantic node. Fix `clean-flow/edge-through-node` with `fromSide`/`toSide`, a route/channel, explicit `via`, or node placement; do not hide the defect with paint order. This semantic correctness rule is universal, while older profile-less schema-v1 inputs retain advisory handling for stricter composition preferences.
+- **Choose a composition profile deliberately with the user**: `standard` keeps dense engineering topologies renderable and records route-rhythm/proper-X findings as warnings; `showcase` fails unrelated proper X crossings, any segment below 8px, and interior turn segments below 16px. Both explicit profiles enforce structural border-run checks; universal Clean Flow applies before profile selection. Endpoint stubs from 8–15px remain valid because fixed lane gaps can require them. Use `meta.quality_profile` or CLI `--quality`, then repair with route/channel/via/side or placement controls. Do not silently add a profile to an existing v1 file.
- **Vertical stacking**: ≥40px gap between components; inline connectors (message buses, 20px tall) live inside the gap, never overlapping boxes.
- **Boundary padding**: boundary `y` = inner `y` − 30, boundary `height` = inner `height` + 50, label baseline 18px below the boundary top.
- **Legend placement**: outside ALL boundary boxes, ≥20px below the lowest one; grow the viewBox if needed.
@@ -342,6 +342,20 @@ Typography inherits JetBrains Mono from the SVG root. Sizes: 11–12px component
5. Legend y is below every boundary's y + height.
6. The `.toolbar`, `.diagram-nav`, `.overview-map`, `.semantic-lens`, `.route-probe`, `.intent-trace-status`, `<script>` blocks, and `:root` / `[data-theme]` CSS are untouched — they ARE the theme, Semantic Lens, Intent Trace, Route Probe, Node Finder, Semantic Radar, Presentation Stage, interaction, and export runtime.
+### Perceptual delivery gate
+
+Treat the first render as a candidate, not an automatic final result. After deterministic render, validate, and artifact checks pass, inspect the final browser artifact and a canonical raster export when an image reader is available. Check clipping, text fit, hierarchy, whitespace, misleading routes, label placement, and dark/light readability. Make a maximum of two focused correction rounds; change only the diagnosed coordinates, labels, routes, spacing, or viewBox, then rerun render, validate, and check after every round.
+
+Finish with a truthful receipt:
+
+```text
+validation: passed
+visual_review: passed
+correction_rounds: 0
+```
+
+When no browser or image reader is available, report `visual_review: skipped (image reader unavailable)` and still report the real correction count. Never report `visual_review: passed` without inspecting the final rendered pixels. Do not start an unbounded aesthetic loop, and do not use visual judgment to override a deterministic failure.
+
## Output
A single self-contained `.html`: embedded CSS (Google Fonts loads async and degrades to system monospace offline), one canonical inline SVG, and embedded JS for Intent Trace, Route Probe, Node Finder, Semantic Passport, runtime-built Semantic Radar, Presentation Stage, Story Trail playback, semantic focus, pan/zoom, theme, and export. It renders directly in any modern browser. Every semantic node has a deterministic DOM ID, accessible keyboard control, renderer-owned kind/responsibility/context attributes, and a compact native `<title>` tooltip; the SVG root includes its own `<title>` and `<desc>`. Raster exports render natively at up to 4× the viewBox (large diagrams step down to 3×/2× to stay under canvas limits); the SVG download is dual-theme self-contained and follows the host's `prefers-color-scheme` (manual override via `svg[data-theme="..."]`); trace-enabled diagrams can be recorded to WebM without external tooling.
diff --git a/archify/renderers/shared/geometry.mjs b/archify/renderers/shared/geometry.mjs
index 8388dc88..fc4a4d19 100644
--- a/archify/renderers/shared/geometry.mjs
+++ b/archify/renderers/shared/geometry.mjs
@@ -57,7 +57,10 @@ export function cleanFlowProblems({
clearance = 2,
routeHint = 'adjust fromSide/toSide, set route/via or channel coordinates, or move the obstacle'
}) {
- if (!process.env.ARCHIFY_QUALITY_PROFILE && !profile) return [];
+ // A relationship hidden behind an unrelated opaque node changes the
+ // diagram's meaning, so this is a correctness invariant rather than an
+ // opt-in composition preference. Keep it active even when the author omits
+ // quality_profile; standard/showcase still control stricter visual budgets.
const problems = [];
const obstacleList = [...obstacles];
const obstacleIds = new Set(obstacleList.map((obstacle) => obstacle?.id));
diff --git a/archify/renderers/shared/utils.mjs b/archify/renderers/shared/utils.mjs
index a67cc320..8b1d5164 100644
--- a/archify/renderers/shared/utils.mjs
+++ b/archify/renderers/shared/utils.mjs
@@ -142,10 +142,12 @@ export function applyTemplate(template, { title, subtitle, footer, svg, cards, v
.replace(GUIDED_VIEWS_PLACEHOLDER, () => `<script id="archify-guided-views-data" type="application/json">${guidedViewsJson}</script>`);
}
-// CJK and other fullwidth glyphs render at roughly twice the advance width of
-// ASCII in the monospace stacks the template uses. Includes the supplementary
-// CJK extensions and emoji, which also render double-width.
-const FULLWIDTH_RE = /[ᄀ-ᅟ⺀-꓏가-힣豈-﫿︰-﹏＀-⦆¢-₩ -〿\u{1F000}-\u{1FAFF}\u{20000}-\u{3FFFD}]/u;
+// CJK and other wide/fullwidth glyphs render at roughly twice the advance
+// width of ASCII in the monospace stacks the template uses. Keep halfwidth
+// forms (notably U+FF61–U+FF9F Katakana) out of this set. The explicit ranges
+// also cover vertical punctuation and supplementary East Asian scripts that
+// literal glyph ranges made difficult to audit.
+const FULLWIDTH_RE = /[\u1100-\u115F\u2329-\u232A\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE10-\uFE19\uFE30-\uFE6F\uFF01-\uFF60\uFFE0-\uFFE6\u{16FE0}-\u{18DFF}\u{1AFF0}-\u{1AFFF}\u{1B000}-\u{1B2FF}\u{1F000}-\u{1FAFF}\u{20000}-\u{3FFFD}]/u;
export function textUnits(text) {
let units = 0;
diff --git a/archify/test/delivery-contract.test.mjs b/archify/test/delivery-contract.test.mjs
new file mode 100644
index 00000000..954d9a9e
--- /dev/null
+++ b/archify/test/delivery-contract.test.mjs
@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const skill = readFileSync(path.join(here, '..', 'SKILL.md'), 'utf8');
+
+test('skill requires a bounded and truthful perceptual delivery receipt', () => {
+ assert.match(skill, /visual_review: passed/);
+ assert.match(skill, /visual_review: skipped \(image reader unavailable\)/);
+ assert.match(skill, /correction_rounds: [0-2]/);
+ assert.match(skill, /maximum of two focused correction rounds/i);
+ assert.match(skill, /never report `visual_review: passed` without inspecting/i);
+});
diff --git a/archify/test/fixtures/v1-baseline/agent-run.lifecycle.json b/archify/test/fixtures/v1-baseline/agent-run.lifecycle.json
index 74c7d329..eb09b78f 100644
--- a/archify/test/fixtures/v1-baseline/agent-run.lifecycle.json
+++ b/archify/test/fixtures/v1-baseline/agent-run.lifecycle.json
@@ -28,9 +28,9 @@
"transitions": [
{ "from": "executing", "to": "approval", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" },
{ "from": "reviewing", "to": "blocked", "variant": "default", "route": "drop" },
- { "from": "executing", "to": "failed", "variant": "security", "fromSide": "left", "toSide": "top", "via": [[340, 342], [402, 342]] },
+ { "from": "executing", "to": "failed", "variant": "security", "fromSide": "left", "toSide": "top", "via": [[320, 157], [320, 342], [402, 342]] },
{ "from": "blocked", "to": "expired", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" },
- { "from": "approval", "to": "cancelled", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "straight" }
+ { "from": "approval", "to": "cancelled", "variant": "security", "fromSide": "bottom", "toSide": "top", "via": [[320, 336], [320, 430], [402, 430]] }
],
"cards": [
{
diff --git a/archify/test/fixtures/v1-baseline/web-app.architecture.json b/archify/test/fixtures/v1-baseline/web-app.architecture.json
index 208c3983..87df60af 100644
--- a/archify/test/fixtures/v1-baseline/web-app.architecture.json
+++ b/archify/test/fixtures/v1-baseline/web-app.architecture.json
@@ -24,7 +24,7 @@
],
"connections": [
{ "from": "users", "to": "cdn", "label": "HTTPS", "variant": "emphasis" },
- { "from": "auth", "to": "api", "label": "verify JWT", "variant": "security", "fromSide": "right", "toSide": "top" },
+ { "from": "auth", "to": "api", "label": "verify JWT", "variant": "security", "fromSide": "right", "toSide": "left", "via": [[620, 142], [620, 330]] },
{ "from": "cdn", "to": "lb" },
{ "from": "cdn", "to": "s3", "label": "static", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "labelDy": 58 },
{ "from": "lb", "to": "api" },
diff --git a/archify/test/geometry.test.mjs b/archify/test/geometry.test.mjs
index 0d284997..edf7baa2 100644
--- a/archify/test/geometry.test.mjs
+++ b/archify/test/geometry.test.mjs
@@ -78,7 +78,6 @@ test('cleanFlowProblems reports collection index, ids, segment, clearance, and f
diagramType: 'architecture',
relationCollection: 'connections',
obstacleKind: 'component',
- profile: 'standard',
routeHint: 'set route/via'
});
assert.equal(problems.length, 1);
@@ -405,6 +404,16 @@ test('textUnits: ASCII=1, CJK=2, mixed sums, fullwidth supplementary=2', () => {
assert.equal(textUnits(null), 0);
assert.equal(textUnits('𠀀'), 2); // CJK Ext-B (supplementary plane)
assert.equal(textUnits('🚀'), 2); // emoji
+ assert.equal(textUnits('注入提示词'), 10); // issue #14 original label
+ assert.equal(textUnits('!@#012'), 12); // fullwidth punctuation + digits
+});
+
+test('textUnits follows wide and halfwidth East Asian presentation boundaries', () => {
+ assert.equal(textUnits('あカ'), 4); // Hiragana + Katakana are wide
+ assert.equal(textUnits('ㄅㆠ'), 4); // Bopomofo + extended Bopomofo are wide
+ assert.equal(textUnits('ㄱ'), 2); // Hangul compatibility letter is wide
+ assert.equal(textUnits('︐︙'), 4); // vertical punctuation forms are wide
+ assert.equal(textUnits('カタカナ'), 4); // halfwidth Katakana stays one unit per glyph
});
test('semantic sigils cover every component and lifecycle kind without literal color', () => {
diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjs
index d8237a67..d6430dcc 100644
--- a/archify/test/layout-rules.test.mjs
+++ b/archify/test/layout-rules.test.mjs
@@ -209,6 +209,42 @@ test('architecture: Clean Flow Gate rejects a connection through a component', (
assert.match(stderr, /segment 0 .*2px clearance/);
});
+function autoRoutePassThroughDocument(connection) {
+ return {
+ schema_version: 1,
+ diagram_type: 'architecture',
+ meta: { title: 'Auto-route pass-through regression' },
+ components: [
+ { id: 'api', type: 'backend', label: 'API', pos: [400, 280], size: [160, 76] },
+ { id: 'cache', type: 'database', label: 'Cache', pos: [645, 130], size: [130, 60] },
+ { id: 'queue', type: 'cloud', label: 'Queue', pos: [880, 130] },
+ ],
+ connections: [connection],
+ };
+}
+
+test('architecture: default delivery rejects an auto-routed connection through an unrelated component', () => {
+ const d = autoRoutePassThroughDocument({ from: 'api', to: 'queue', variant: 'dashed' });
+ const { code, stderr } = render('architecture', d);
+ assert.notEqual(code, 0, `expected non-zero exit; stderr:\n${stderr}`);
+ assert.match(stderr, /\[clean-flow\/edge-through-node\] architecture connections\[0\] "api" -> "queue"/);
+ assert.match(stderr, /crosses component "cache"/);
+ assert.match(stderr, /fromSide\/toSide/);
+});
+
+test('architecture: explicit waypoints around an obstacle remain valid by default', () => {
+ const d = autoRoutePassThroughDocument({
+ from: 'api',
+ to: 'queue',
+ variant: 'dashed',
+ fromSide: 'right',
+ toSide: 'top',
+ via: [[620, 318], [620, 100], [940, 100]],
+ });
+ const { code, stderr } = render('architecture', d);
+ assert.equal(code, 0, stderr);
+});
+
test('architecture: showcase rejects an unrelated proper edge crossing', () => {
const d = {
schema_version: 1,
diff --git a/archify/test/v1-compatibility.test.mjs b/archify/test/v1-compatibility.test.mjs
index 6ef85344..59fab395 100644
--- a/archify/test/v1-compatibility.test.mjs
+++ b/archify/test/v1-compatibility.test.mjs
@@ -107,7 +107,14 @@ test('legacy v1 architecture geometry remains renderable without an explicit qua
{ id: 'api', type: 'backend', label: 'API Server', pos: [670, 300], size: [130, 60] },
],
connections: [
- { from: 'auth', to: 'api', label: 'verify JWT', fromSide: 'right', toSide: 'top' },
+ {
+ from: 'auth',
+ to: 'api',
+ label: 'verify JWT',
+ fromSide: 'right',
+ toSide: 'left',
+ via: [[620, 142], [620, 330]],
+ },
],
};
@@ -155,8 +162,8 @@ test('legacy v1 lifecycle geometry remains renderable without an explicit qualit
{ id: 'cancelled', type: 'failure', label: 'Cancelled', lane: 'terminal', col: 0 },
],
transitions: [
- { from: 'executing', to: 'failed', fromSide: 'left', toSide: 'top', via: [[340, 342], [402, 342]] },
- { from: 'approval', to: 'cancelled', fromSide: 'bottom', toSide: 'top', route: 'straight' },
+ { from: 'executing', to: 'failed', fromSide: 'left', toSide: 'top', via: [[320, 157], [320, 342], [402, 342]] },
+ { from: 'approval', to: 'cancelled', fromSide: 'bottom', toSide: 'top', via: [[320, 336], [320, 430], [402, 430]] },
],
};
diff --git a/docs/research-trustworthy-first-diagram-slice.md b/docs/research-trustworthy-first-diagram-slice.md
new file mode 100644
index 00000000..30b22bff
--- /dev/null
+++ b/docs/research-trustworthy-first-diagram-slice.md
@@ -0,0 +1,204 @@
+# Archify:可信首次交付的最小实现切片
+
+> 调研日期:2026-07-22(Asia/Shanghai)
+>
+> 口径:只对一手资料与当前源码作结论;`事实`、`推断`、`建议`分开书写。
+>
+> 目标边界:同时改善首次交付的语义正确性、视觉质量和可验证性;不增加图类型、视觉预设、移动端产品面或托管平台。
+
+## 结论
+
+**建议只做一个纵向切片:`Trustworthy First Delivery v1`。**
+
+它包含同一条交付链上的两个不可拆开的门:
+
+1. **无条件语义安全门**:任何 renderer-owned relationship 穿过无关的、不透明语义节点时,都必须 hard fail;不能再因为输入没有 `meta.quality_profile` 或 CLI `--quality` 而静默放行。更严格的 X 交叉、短段、节奏等审美预算仍保持 profile-aware。
+2. **有上限的最终像素复核**:确定性 `render -> validate --json -> check` 全部通过后,若运行时能读图,则检查最终浏览器成品与 canonical raster;最多做两轮只针对已诊断问题的修正,每轮之后重跑全部确定性门。交付时明确报告:
+
+ ```text
+ validation: passed
+ visual_review: passed
+ correction_rounds: 0
+ ```
+
+ 没有图像读取能力时必须报告 `visual_review: skipped (image reader unavailable)`,不能猜测为 passed。
+
+这仍是一个切片,而不是两个功能:**第一张 renderer 草稿只是 candidate;第一张交给用户的图必须同时有语义安全、机器检查和真实像素复核的证据。** 它不需要新 schema、图类型、preset、布局引擎、移动端状态、服务端或运行时依赖。
+
+## 为什么是这一刀
+
+| 目标 | 当前证据 | 这一个切片的直接作用 |
+|---|---|---|
+| 首次出图正确性 | #24 证明 `api -> queue` 可因路径藏在 `cache` 后而读成 `cache -> queue`,且无 profile 的 `render` / `validate` / `check` 全部成功;维护者明确把它定性为 correctness issue,倾向 hard error | 无 profile 也执行 Clean Flow;错误不能再进入交付物 |
+| 视觉质量 | #6 的核心反馈是箭头混乱、不美观;维护者也承认能力较弱的模型在复杂仓库上不应明显掉队 | 机器门先挡住可判定的错误,最终像素复核补足 clipping、层级、留白、标签和暗/亮主题等机器尚未覆盖的问题 |
+| 降低返工与 token | #22 的报告明确说成本来自“沟通调整很多版”;维护者判断不是 renderer 自身异常,而是代码探索、模型/客户端和迭代次数 | 只允许最多两轮、只改已诊断位置;不把审美修正变成无上限自编辑循环 |
+| 可验证交付 | 当前 `validate --json` 已把临时 render 与 artifact check 合并,返回 `checks` 和 `composition`;但视觉复核没有真实状态 | 复用现有 JSON receipt,再补 `visual_review` 与真实 correction count,不引入新平台 |
+
+上述 issue 证据分别见 [#6](https://github.com/tt-a1i/archify/issues/6)、[#22](https://github.com/tt-a1i/archify/issues/22)、[#24](https://github.com/tt-a1i/archify/issues/24);#24 的维护者定性与 hard-error 选择见[该回复](https://github.com/tt-a1i/archify/issues/24#issuecomment-5029635230)。
+
+## Archify 当前事实基线
+
+### main 与已有能力
+
+- **事实**:调研时远端 `main` 是 [`6d5204d`](https://github.com/tt-a1i/archify/commit/6d5204d23dfa2cbf3dfff423beeb32250a3dc727),最新 release / package 版本仍为 `v2.11.0`。
+- **事实**:main 已有共享 `cleanFlowProblems()`,会报告关系集合索引、可选关系 ID、障碍 ID、首个相交 segment、2px clearance 与修复旋钮;但函数在既无环境 profile、又无 IR profile 时立即返回空数组。因此这是**已实现但默认可绕过**的 correctness guard。见 [`geometry.mjs`](https://github.com/tt-a1i/archify/blob/6d5204d23dfa2cbf3dfff423beeb32250a3dc727/archify/renderers/shared/geometry.mjs#L44-L91)。
+- **事实**:architecture renderer 已把 components 作为障碍集合传入 Clean Flow,并有完整 `fromSide` / `toSide` / `route` / `via` 修复提示。见 [`render-architecture.mjs`](https://github.com/tt-a1i/archify/blob/6d5204d23dfa2cbf3dfff423beeb32250a3dc727/archify/renderers/architecture/render-architecture.mjs#L189-L238)。
+- **事实**:architecture `auto` 当前固定选择一个中点 X 的 H-V-H dogleg;它没有比较另一种 dogleg,也没有避障搜索。见 [`render-architecture.mjs`](https://github.com/tt-a1i/archify/blob/6d5204d23dfa2cbf3dfff423beeb32250a3dc727/archify/renderers/architecture/render-architecture.mjs#L294-L329)。
+- **事实**:`validate` 会在临时目录 render,再运行 final HTML checker;成功的 `--json` 返回 `ok`、`checks` 和 `composition`。见 [`bin/archify.mjs`](https://github.com/tt-a1i/archify/blob/6d5204d23dfa2cbf3dfff423beeb32250a3dc727/archify/bin/archify.mjs#L267-L333)。
+- **事实**:当前 SKILL 要求 read-schema -> author IR -> render -> validate -> targeted fix,也明确说明 composition gate 在无 profile 时保持 opt-in;现有 self-review checklist 主要检查 DOM/几何约束,并没有最终像素 readback 状态。见 [`SKILL.md`](https://github.com/tt-a1i/archify/blob/6d5204d23dfa2cbf3dfff423beeb32250a3dc727/archify/SKILL.md#L73-L81) 与 [`SKILL.md`](https://github.com/tt-a1i/archify/blob/6d5204d23dfa2cbf3dfff423beeb32250a3dc727/archify/SKILL.md#L326-L343)。
+- **推断**:因为隐藏在无关节点后会改变读者看到的拓扑,这一条不是“审美偏好”。把它留在 opt-in profile 后面,和其他 profile-less 兼容策略混为一谈了。
+
+### issues 与 PR 的当前状态
+
+#### #6:箭头混乱
+
+- **事实**:[#6](https://github.com/tt-a1i/archify/issues/6) 仍 open,报告来自真实仓库与真实 agent 生成图;维护者回复称强模型能生成效果好的图,但也明确说复杂仓库中不应让能力较弱的模型表现不足。
+- **推断**:继续只增强 prompt 或展示强模型样例,不能给低能力模型提供确定性下限。机械安全门与最终像素门更接近问题本体。
+
+#### #14 与 PR #28:CJK 宽度
+
+- **事实**:[#14](https://github.com/tt-a1i/archify/issues/14) 的措辞是 “may be inaccurate” / “likely contributed”;报告者也承认部分 overlap 可能来自坐标放置。它是值得修的 P2,但当前证据没有证明它是 #6 / #22 / #24 的共同根因。
+- **事实**:main 的 `FULLWIDTH_RE` 用一个宽区间覆盖 U+2E80–U+A4CF,并已有 ASCII、Han、混排、补充平面汉字和 emoji 测试。见 [`utils.mjs`](https://github.com/tt-a1i/archify/blob/6d5204d23dfa2cbf3dfff423beeb32250a3dc727/archify/renderers/shared/utils.mjs#L145-L153) 与 [`geometry.test.mjs`](https://github.com/tt-a1i/archify/blob/6d5204d23dfa2cbf3dfff423beeb32250a3dc727/archify/test/geometry.test.mjs#L400-L408)。
+- **事实**:open 的 [PR #28](https://github.com/tt-a1i/archify/pull/28) 把该宽区间拆成显式 Unicode ranges,并新增 Han、CJK punctuation、fullwidth、Hangul 与混排单测;head `22eb5c8` 当时没有任何 GitHub check run。
+- **事实**:PR #28 的新 ranges 不等价于 main:它漏掉 main 会按双宽处理的 Hiragana `あ` (U+3042)、Katakana `ア` (U+30A2)、Hangul Compatibility Jamo `ㄱ` (U+3131) 和 Katakana Phonetic Extension `ㇰ` (U+31F0)。因此 “all CJK blocks” 的 PR 描述并不成立。改动见 [`utils.mjs@22eb5c8`](https://github.com/tt-a1i/archify/blob/22eb5c84e917c677c17e1d3c22bee63a811225ce/archify/renderers/shared/utils.mjs#L145-L155),新增测试见 [`geometry.test.mjs@22eb5c8`](https://github.com/tt-a1i/archify/blob/22eb5c84e917c677c17e1d3c22bee63a811225ce/archify/test/geometry.test.mjs#L400-L418)。
+- **建议**:PR #28 不要原样并入本切片。先补 Kana、Bopomofo / compatibility Jamo 等回归矩阵,并用真实浏览器字体栈的 measured-vs-estimated fixture 证明问题;它应作为独立、可回滚的小修复。
+
+#### #22:多轮打磨消耗 token
+
+- **事实**:[#22](https://github.com/tt-a1i/archify/issues/22) 已按“未发现 Archify renderer / validator 异常 token 消耗”关闭;用户明确说消耗发生在多轮沟通与细节打磨,维护者把主要成本定位到代码探索、模型/客户端与迭代次数。
+- **推断**:Archify 不应该承诺控制模型探索成本,但可以控制自身交付循环不无限扩张:确定性检查优先、针对性修正、两轮上限、无法看图则如实 skipped。
+
+#### #24 与 PR #30:静默错误拓扑
+
+- **事实**:[#24](https://github.com/tt-a1i/archify/issues/24) 给出 3 个组件、1 条 connection 的最小复现;`api -> queue` 的 auto route 穿过 `cache`,由于箭头先画、opaque component 后画,成品视觉上像 `cache -> queue`。报告中的无 profile `render`、`validate`、`check` 全部成功。
+- **事实**:维护者明确回复“correctness issue rather than cosmetic one”,并选择 hard render / validate error,而不是 warning。见[维护者回复](https://github.com/tt-a1i/archify/issues/24#issuecomment-5029635230)。
+- **事实**:open 的 [PR #30](https://github.com/tt-a1i/archify/pull/30) 是 test-only;reject case 主动加了 `quality_profile: standard`,PR 描述还明确记录:省略 profile 时同一文档当前仍能成功 render。它证明 main 上的 gate 能识别路径,但默认交付仍可绕过。
+- **建议**:本切片应吸收 #24 的 exact auto-route repro 与安全 `via` workaround,但测试必须省略 profile,锁定“默认也 hard fail”的新语义。
+
+## 三个官方仓库的一手机制对照
+
+对照快照:
+
+- [`yizhiyanhua-ai/fireworks-tech-graph@50c819d`](https://github.com/yizhiyanhua-ai/fireworks-tech-graph/tree/50c819d68fd4fee330b3010988cd13e98b678d44)
+- [`Agents365-ai/drawio-skill@6f33563`](https://github.com/Agents365-ai/drawio-skill/tree/6f33563adce24450003d1cb61111ebbcc5579f28)
+- [`ahmedkhaleel2004/gitdiagram@20eea55`](https://github.com/ahmedkhaleel2004/gitdiagram/tree/20eea559377fe3f110ac630856351382c4b5fcab)
+
+### fireworks-tech-graph
+
+**事实**
+
+- 它把 geometry / composition 约束做成所有 style 共用的 executable contract,而不是靠 style 文档宣称;showcase 明确约束零 crossing / bridge、每边最多两 bend、stretch <= 1.35、segment >= 16px、node gap >= 40px、container gutter >= 20px、label clearance >= 4px。见 [`composition-quality-contract.md`](https://github.com/yizhiyanhua-ai/fireworks-tech-graph/blob/50c819d68fd4fee330b3010988cd13e98b678d44/references/composition-quality-contract.md#L7-L26)。
+- 它明确规定:成功 render 但没有通过 geometry + composition 两个 gate 仍只是 draft。见[同一 contract 的 validation 段](https://github.com/yizhiyanhua-ai/fireworks-tech-graph/blob/50c819d68fd4fee330b3010988cd13e98b678d44/references/composition-quality-contract.md#L75-L85)。
+- 它把第一张 render 当 candidate:先确定性检查,再读回 PNG,最多两轮针对性修正;无法读图时明确报告 skipped。见 [`README.md`](https://github.com/yizhiyanhua-ai/fireworks-tech-graph/blob/50c819d68fd4fee330b3010988cd13e98b678d44/README.md#L157-L189) 与 [`SKILL.md`](https://github.com/yizhiyanhua-ai/fireworks-tech-graph/blob/50c819d68fd4fee330b3010988cd13e98b678d44/SKILL.md#L77-L98)。
+- 它用真实 validator tests 覆盖 path-vs-rect、edge crossing、reserved region、clipping、label clearance 与 composition budgets,而不是只测 XML parse。见 [`test_validate_svg.py`](https://github.com/yizhiyanhua-ai/fireworks-tech-graph/blob/50c819d68fd4fee330b3010988cd13e98b678d44/tests/test_validate_svg.py#L49-L104) 与 [`test_geometry_contracts.py`](https://github.com/yizhiyanhua-ai/fireworks-tech-graph/blob/50c819d68fd4fee330b3010988cd13e98b678d44/tests/test_geometry_contracts.py#L160-L192)。
+
+**可借鉴**
+
+- “第一张 render 是 candidate”以及 deterministic-first、perceptual-second 的顺序。
+- 最大两轮 targeted correction 与 truthful `passed` / `skipped` receipt。
+- 同 topology fixture 锁定 geometry metrics,避免把 style 变化误当结构进步。
+
+**明确不借鉴**
+
+- 不扩成 12 styles、14 UML types、vendor icon catalogue 或 GIF contract。
+- 不引入 CairoSVG / Puppeteer 到 zero-install core。
+- 不把所有质量压成一个不透明分数;保留具体 violation、关系、segment 与坐标。
+
+### Agents365-ai/drawio-skill
+
+**事实**
+
+- 它先用 `validate.py` 检查 duplicate/reserved IDs、broken parents、dangling endpoints、invalid geometry、sibling overlap、waypointed edge-through-node 与 edge crossing;`--strict` 可把 warnings 升为失败,`--score` 只用于比较同一 graph 的 layout variants。见 [`validate.py`](https://github.com/Agents365-ai/drawio-skill/blob/6f33563adce24450003d1cb61111ebbcc5579f28/skills/drawio-skill/scripts/validate.py#L212-L238) 与 [`validate.py`](https://github.com/Agents365-ai/drawio-skill/blob/6f33563adce24450003d1cb61111ebbcc5579f28/skills/drawio-skill/scripts/validate.py#L241-L336)。
+- 它在确定性 lint 后导出 draft PNG,视觉自检 edge-shape overlap、stacked edges、clipped labels、off-canvas、missing connections 与 label overlap;每次修复都重导出、重读,最多两轮。见 [`SKILL.md`](https://github.com/Agents365-ai/drawio-skill/blob/6f33563adce24450003d1cb61111ebbcc5579f28/skills/drawio-skill/SKILL.md#L125-L161)。
+- 它对单元素问题做 targeted edit,保留此前 layout tuning;到用户 review loop 才允许更长互动,并有五轮 safety valve。见 [`SKILL.md`](https://github.com/Agents365-ai/drawio-skill/blob/6f33563adce24450003d1cb61111ebbcc5579f28/skills/drawio-skill/SKILL.md#L163-L187)。
+
+**可借鉴**
+
+- 把视觉缺陷分成明确 taxonomy,而不是笼统说“看看好不好看”。
+- 确定性 lint 必须早于、且优先于 vision。
+- 每轮只修已诊断的坐标、尺寸、label、route、spacing 或 viewBox。
+
+**明确不借鉴**
+
+- 不切换到 `mxCell` XML,不依赖 draw.io desktop / Electron 或 Graphviz。
+- 不照搬 5 轮用户 feedback loop 到自动交付环;本切片上限仍是两轮。
+- 不照搬其 score 为跨图质量指标;该仓库自己也限定它只能比较同一 graph。
+
+### GitDiagram
+
+**事实**
+
+- 它先从 repo tree + README 生成不超过 650 词、带 exact repo-relative paths 的 architecture brief,再让第二阶段只返回 bounded graph schema。见 [`prompts.ts`](https://github.com/ahmedkhaleel2004/gitdiagram/blob/20eea559377fe3f110ac630856351382c4b5fcab/src/server/generate/prompts.ts#L1-L50)。
+- graph IR 上限为 10 groups / 34 nodes / 48 edges,graph planning 最多 3 次;schema 限制 ID、文本、shape、edge style 与 path。见 [`graph.ts`](https://github.com/ahmedkhaleel2004/gitdiagram/blob/20eea559377fe3f110ac630856351382c4b5fcab/src/features/diagram/graph.ts#L7-L90)。
+- 每次 model graph 都会验证 duplicate IDs、group membership、真实 repo path 与 edge endpoints;失败时把 previous graph、file tree 与精确 validation feedback 送回下一次,最多三次。见 [`server/generate/graph.ts`](https://github.com/ahmedkhaleel2004/gitdiagram/blob/20eea559377fe3f110ac630856351382c4b5fcab/src/server/generate/graph.ts#L90-L175) 与 [`graph-planner.ts`](https://github.com/ahmedkhaleel2004/gitdiagram/blob/20eea559377fe3f110ac630856351382c4b5fcab/src/server/generate/graph-planner.ts#L72-L225)。
+- 通过的 IR 再由 deterministic compiler 转 Mermaid;成功 artifact 与 terminal audit 被持久化。README 对整条 pipeline 有一致描述。见 [`README.md`](https://github.com/ahmedkhaleel2004/gitdiagram/blob/20eea559377fe3f110ac630856351382c4b5fcab/README.md#L49-L59)。
+
+**可借鉴**
+
+- validator 的精确 feedback 进入下一轮,而不是整图重新猜。
+- retry 必须 bounded,receipt 应记录实际 attempts / corrections。
+- 对“从仓库画图”的更高阶后续,可把节点与关系绑定到真实 source path;但这是 semantic provenance 的下一切片,不应塞进本轮 geometry / perceptual gate。
+
+**明确不借鉴**
+
+- 不用 Mermaid / ELK 替换 Archify 的 typed renderer 与 exact geometry。
+- 不引入 R2、Redis、quota、provider、SSE 或 web persistence。
+- 不原样照搬 34-node / 48-edge 上限;Archify 的复杂度预算应按 diagram type / profile 校准。
+- 不在本轮给所有 Archify schema 新增 source-path 字段;这会把一个可小步验证的交付门扩大为跨五类 IR 的 provenance 迁移。
+
+## 建议实现边界
+
+### 代码与契约
+
+1. 在共享 `cleanFlowProblems()` 中移除“没有 profile 就跳过”的 early return;source / target exemption、container / lifeline intentional pass-through 语义保持不变。
+2. profile 仍只控制审美更强的规则:proper X crossing、short / micro segment、route rhythm 等。不要借机把所有 profile-less legacy artifact 变成 hard failure。
+3. 在 `SKILL.md` 增加 perceptual delivery gate:最终 HTML + canonical raster、明确 defect taxonomy、最多两轮、每轮重跑确定性门、如实 receipt。
+4. 不增加新 CLI command 或 receipt sidecar。v1 复用现有 `validate --json` 作为机器证据;handoff receipt 只补图像复核状态与轮次。
+
+### 不在本轮实现
+
+- obstacle-aware A* / ELK / Graphviz auto-router;hard fail + 现有 `via` / side hints 先建立正确性下限。将来如果要做,应该只在当前 `auto` 路径确实撞障碍时比较少量 deterministic dogleg candidates,避免无谓改动 golden geometry。
+- 自动审美打分、跨图排行榜或“100 分”声明。
+- repo path provenance / explanation planner;它很有价值,但应独立设计 schema 与 evidence contract。
+- PR #28 的当前 regex patch;先补完字符覆盖与真实字体测量证据。
+- 新 preset、图类型、vendor icon、mobile UI、托管服务、浏览器依赖或后台 daemon。
+
+## 测试与验收
+
+### 必须自动化
+
+1. **共享单测**:无 `profile`、无 `ARCHIFY_QUALITY_PROFILE` 时,relationship 穿过无关节点仍返回一条 `clean-flow/edge-through-node`;source / target boxes 仍豁免。
+2. **#24 exact regression**:使用 issue 中 3 components / 1 auto connection,省略 `quality_profile`:
+ - `render` 与 `validate` 必须 non-zero;
+ - stderr 必须包含 diagram type、`connections[0]`、`api -> queue`、`cache`、首个 segment、2px clearance 与 `fromSide` / `toSide` / `via` 修复提示;
+ - issue 给出的安全 `via` workaround 必须通过。
+3. **边界保护**:profile-less 的 unrelated proper X crossing、route rhythm 等仍按原 compatibility 语义处理;本轮只能把 edge-through-node 升为 universal correctness failure。
+4. **五 renderer 语义保护**:现有 workflow / architecture / dataflow / lifecycle Clean Flow fixtures 全绿;sequence lifeline、activation、segment 与各种 container 仍保持 intentional pass-through。
+5. **交付契约测试**:锁定 SKILL 中 deterministic-first、最终像素检查、最多 2 轮、每轮重跑、`passed` / `skipped`、真实 correction count,以及“vision 不得覆盖 deterministic failure”。
+6. 在 `archify/` 运行 `npm test`。
+7. 因 `SKILL.md` 是发布物,运行 `scripts/build-zip.sh /tmp/fresh.zip`,将解压内容与 `archify.zip` 比较;准备发布时重建并提交 archive,不能只改源码树。
+
+### 必须人工 / agent 视觉验收
+
+用最终 browser artifact 和 canonical PNG 检查至少一个 architecture 成品:
+
+- 无隐藏在 component 后、会改变 topology 读法的路径;
+- 无 clipping、node / label overlap、stacked edges、legend 遮挡;
+- 主路径、次要路径与 boundaries 层级清楚,留白均衡;
+- CJK 与 ASCII 混排的 label 可读;
+- light / dark 都可辨识;
+- 若做过修正,最多两轮且每轮后 `validate --json` 仍通过。
+
+### 完成标准
+
+- #24 profile-less repro 从“静默成功”变为“可操作的 hard failure”;安全 route 通过。
+- `npm test` 与 ZIP freshness gate 通过。
+- 最终 handoff 同时给出机器 validation receipt、`visual_review` 真实状态和 correction count。
+- 无 schema / preset / diagram type / mobile / hosted surface / runtime dependency 增量。
+
+## 风险与后续
+
+- **兼容性风险(已知且有意)**:过去靠 paint order 隐藏错误路径的 profile-less v1 文件会开始失败。建议在 release notes 中明确标为 semantic correctness fix,而不是普通 composition tightening。
+- **误报风险**:共享 obstacle 集合必须继续只包含 opaque semantic nodes;container、lane、stage、lifeline、activation 等 intentional pass-through geometry 不得误塞进来。
+- **视觉复核不可机器证明**:v1 的 `visual_review` 是真实执行状态,不是假装客观的视觉分数;无 image reader 必须 skipped。后续若需要可审计 artifact,可单独设计截图 hash / evidence path,而不是把服务端存储带入本轮。
+- **下一优先级**:本切片稳定后,再评估“只在当前 auto dogleg 撞障碍时比较 H-V-H / V-H-V 两个候选”的 renderer-owned 小路由优化;它可减少一次人工 `via` 修正,但不应抢在 universal correctness gate 之前。