Skip to content

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

fix(diagnostics): close gaps reported by the mobi generations

tt-a1iace72abc9872
diff --git a/archify/bin/finalize.mjs b/archify/bin/finalize.mjs
index 7725f557..254f3cac 100644
--- a/archify/bin/finalize.mjs
+++ b/archify/bin/finalize.mjs
@@ -564,6 +564,9 @@ function placementHints({ crossings = [], detours = [], crowdedSides = [] }) {
return [...new Set(hints)].slice(0, 8);
}
+// Route failures call for a connected-scene repair; size and text failures do not.
+const ROUTE_DIAGNOSTIC = /^(clean-flow\/|composition\/(proper-crossing|ambiguous-corridor|border-run|container-border-run|excessive-route-detour|route-rhythm|arrowhead-collision|pinned-reply-detour))/;
+
export function compactFinalizeReceipt(receipt) {
const gates = {};
for (const stage of FINALIZE_STAGES) gates[stage] = receipt.stages?.[stage]?.status || 'not-run';
@@ -641,6 +644,8 @@ export function compactFinalizeReceipt(receipt) {
if (receipt.ok && Object.keys(reviewSignals).length) {
const routeReview = receipt.stages?.check?.receipt?.composition?.routeReview;
const hints = routeReview ? placementHints(routeReview) : [];
+ // Modes without free node placement cannot act on node-move hints.
+ const advisoryOnly = Boolean(receipt.type) && receipt.type !== 'architecture';
compact.visualReviewRecommendation = {
action: 'inspect-route-readability',
signals: reviewSignals,
@@ -651,8 +656,10 @@ export function compactFinalizeReceipt(receipt) {
detours: routeReview.detours.slice(0, 8),
truncated: routeReview.crossings.length > 8 || routeReview.detours.length > 8,
},
- ...(hints.length ? { hints } : {}),
- 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.',
+ ...(hints.length && !advisoryOnly ? { hints } : {}),
+ repair: !advisoryOnly
+ ? '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.'
+ : 'Advisory only: this mode places or routes these relationships itself. Report them; do not remove relationships or meaning to reduce crossings.',
} : {}),
};
}
@@ -678,9 +685,9 @@ export function compactFinalizeReceipt(receipt) {
compact.nextAction = {
action: 'edit-in-place',
candidate: receipt.specification?.path,
- constraint: receipt.type === 'architecture'
+ constraint: receipt.type === 'architecture' && (receipt.diagnostics || []).some((entry) => ROUTE_DIAGNOSTIC.test(entry.code || ''))
? '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.',
+ : 'Preserve unaffected semantics and geometry; apply each diagnostic\'s own supportedFixes and do not replace the whole candidate.',
then: 'finalize-once',
};
}
diff --git a/archify/references/authoring-defaults.md b/archify/references/authoring-defaults.md
index 7d99f0ca..84f83424 100644
--- a/archify/references/authoring-defaults.md
+++ b/archify/references/authoring-defaults.md
@@ -22,7 +22,7 @@ Place Architecture nodes by their actual connections before assigning coordinate
Before writing positions, trace each non-main relationship: its straight or one-bend corridor must not pass another node or cross another relationship. If it does, move the endpoint that is off the main path. Start the main actor and its first connected step together near the canvas origin; use content rows for vertical rhythm. Omit `meta.viewBox` for a fresh Architecture so the Reader measures intrinsic height. Keep supplied fixed geometry authoritative.
-Start with automatic routes and endpoint sides. Pin a side only for a necessary branch, return, or supplied geometry. A reply between adjacent nodes in one row or column is not a return: leave both directions automatic so they render as two parallel straight lines. Reserve `via`, `channelX`, `channelY`, and label coordinates for measured defects. Before writing positions, budget each labeled main-path edge at `6.5px × ASCII units + 21px` of clear gap, counting CJK as two units; use its own label length, not a row-wide fixed gap. Size Architecture sublabels for their preferred 9px text at `5.4px × text units + 8px`, with CJK counting twice; keep supporting copy concise without dropping required facts. Do not trade readability or meaning for fewer crossings. The [Geometry reference](authoring-contract.md#executable-geometry-rules) has measured spacing, port, canvas, and route rules for a diagnosed layout problem.
+Start with automatic routes and endpoint sides. Pin a side only for a necessary branch, return, or supplied geometry. In Architecture, a reply between adjacent nodes in one row or column is not a return: leave both directions automatic so they render as two parallel straight lines. Reserve `via`, `channelX`, `channelY`, and label coordinates for measured defects. Before writing positions, budget each labeled main-path edge at `6.5px × ASCII units + 21px` of clear gap, counting CJK as two units; use its own label length, not a row-wide fixed gap. Keep an Architecture canvas within 1240px wide, or 1790px when it is at least 1.55 times as wide as tall; past that its 8px relationship labels drop below the desktop floor. Size Architecture sublabels for their preferred 9px text at `5.4px × text units + 8px`, with CJK counting twice; keep supporting copy concise without dropping required facts. Do not trade readability or meaning for fewer crossings. The [Geometry reference](authoring-contract.md#executable-geometry-rules) has measured spacing, port, canvas, and route rules for a diagnosed layout problem.
## Evidence and schema
diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjs
index 85ca8246..6d1b26d2 100644
--- a/archify/renderers/lifecycle/render-lifecycle.mjs
+++ b/archify/renderers/lifecycle/render-lifecycle.mjs
@@ -190,6 +190,8 @@ const isFinal = (state) => !outgoing.has(state.id);
// and keeps the placed layout with the fewest bends and short jogs.
let spacing = { spineGap: 72, rowGap: 44, drop: 58, firstTrack: 34 };
let geometry;
+// Labels that could not be placed at a tighter spacing, which widened every gap.
+const spacingWideners = new Set();
for (let round = 0; round < SPACING_ROUNDS; round += 1) {
const candidates = ['partner', 'even'].map((ports) => ({ ports, ...layout({ ...spacing, ports }) }));
const placed = candidates.filter((candidate) => !candidate.unplacedLabels.length);
@@ -197,6 +199,10 @@ for (let round = 0; round < SPACING_ROUNDS; round += 1) {
// layout() positions the shared states, so the winner is laid out again.
geometry = best === candidates.at(-1) ? best : layout({ ...spacing, ports: best.ports });
if (placed.length) break;
+ if (round === 0) {
+ const closest = [...candidates].sort((a, b) => a.unplacedLabels.length - b.unplacedLabels.length)[0];
+ for (const transition of closest.unplacedLabels) spacingWideners.add(transition);
+ }
spacing = { spineGap: spacing.spineGap + 28, rowGap: spacing.rowGap + 28, drop: spacing.drop + 14, firstTrack: spacing.firstTrack + 6 };
}
@@ -883,12 +889,23 @@ function validateLayout() {
}));
const budget = Math.floor(DESKTOP_READER_DIAGRAM_WIDTH * smallest / MIN_PROJECTED_NODE_TEXT_PX);
if (viewBox[0] > budget) {
- const message = `The lifecycle is ${viewBox[0]}px wide; at ${smallest}px text it stays readable on a desktop only up to ${budget}px.`;
+ // A labelled main-path step widens its gap past the default spacing.
+ const wideStepLabels = mainPath.slice(0, -1).flatMap((id, index) => {
+ const edge = spineEdges.get(index);
+ const excessPx = edge && hasLabel(edge) ? Math.round(labelBox(edge).width + 26 - spacing.spineGap) : 0;
+ return excessPx > 0 ? [{ from: edge.from, to: edge.to, label: edge.label || edge.note, excessPx }] : [];
+ }).sort((a, b) => b.excessPx - a.excessPx);
+ const widenerLabels = [...spacingWideners].map((transition) => `"${transition.label || transition.note}"`);
+ const labelFixes = [
+ ...(widenerLabels.length ? [`relieve the routes crowding ${widenerLabels.join(', ')}: those labels found no clear spot at the base spacing, so every gap widened by 28px; drop labels both endpoints imply, merge exits that share a target, or move a secondary transition elsewhere`] : []),
+ ...(wideStepLabels.length ? [`shorten the main-path transition labels that widen their gaps: ${wideStepLabels.map((step) => `"${step.label}" (+${step.excessPx}px)`).join(', ')}`] : []),
+ ];
+ const message = `The lifecycle is ${viewBox[0]}px wide; at ${smallest}px text it stays readable on a desktop only up to ${budget}px.${labelFixes.length ? ` Transition labels set most of that width.` : ''}`;
diagnostics.push({
code: 'lifecycle/too-wide', severity: 'error', message,
subject: { diagramType: 'lifecycle', path: '/mainPath' },
- evidence: { viewBoxWidth: viewBox[0], budgetPx: budget, mainPathStates: mainPath.length, lowerRowStates: offStates.length },
- supportedFixes: ['shorten state labels and sublabels', 'move secondary phases off mainPath or merge adjacent phases', 'split the lifecycle into two diagrams'],
+ evidence: { viewBoxWidth: viewBox[0], budgetPx: budget, mainPathStates: mainPath.length, lowerRowStates: offStates.length, wideStepLabels, spacingWideners: [...spacingWideners].map((transition) => ({ from: transition.from, to: transition.to, label: transition.label || transition.note })) },
+ supportedFixes: [...labelFixes, 'shorten state labels and sublabels', 'move secondary phases off mainPath or merge adjacent phases', 'split the lifecycle into two diagrams'],
});
problems.push(message);
}
diff --git a/archify/renderers/workflow/workflow-compiler.mjs b/archify/renderers/workflow/workflow-compiler.mjs
index 889ee377..6ccd1055 100644
--- a/archify/renderers/workflow/workflow-compiler.mjs
+++ b/archify/renderers/workflow/workflow-compiler.mjs
@@ -2549,6 +2549,8 @@ function validateReadablePinnedGeometry() {
}
function validateWorkflow() {
+ // Report edges by their authored index; the canonical order is internal.
+ const authoredEdges = asArray(qualityResolvedWorkflow.edges);
const problems = [];
if (workflow.schema_version !== 1 && workflow.schema_version !== 2) {
problems.push('Workflow files must set "schema_version" to 1 or 2.');
@@ -2721,7 +2723,7 @@ function validateWorkflow() {
}
problems.push(...cleanEndpointSideProblems({
- relations: workflow.edges,
+ relations: authoredEdges,
endpointIds: new Set(nodes.keys()),
pathFor,
diagramType: 'workflow',
@@ -2731,7 +2733,7 @@ function validateWorkflow() {
routeHint: 'keep automatic routing, or choose fromSide/toSide and via points whose first and final segments cross node borders perpendicularly',
}));
problems.push(...cleanFlowProblems({
- relations: workflow.edges,
+ relations: authoredEdges,
obstacles: nodes.values(),
pathFor,
diagramType: 'workflow',
@@ -2740,7 +2742,7 @@ function validateWorkflow() {
routeHint: 'adjust fromSide/toSide, set route/via or channel coordinates, or move the node to a clearer lane/column'
}));
problems.push(...cleanCrossingProblems({
- relations: workflow.edges,
+ relations: authoredEdges,
endpointIds: new Set(nodes.keys()),
pathFor,
diagramType: 'workflow',
@@ -2754,7 +2756,7 @@ function validateWorkflow() {
routeHint: 'adjust route/via, bias, or channel coordinates so the edges use separate lane corridors'
}));
problems.push(...cleanAmbiguousCorridorProblems({
- relations: workflow.edges,
+ relations: authoredEdges,
endpointIds: new Set(nodes.keys()),
pathFor,
diagramType: 'workflow',
@@ -2785,7 +2787,7 @@ function validateWorkflow() {
}
}
problems.push(...cleanBorderRunProblems({
- relations: workflow.edges,
+ relations: authoredEdges,
endpointIds: new Set(nodes.keys()),
frames: workflowCompositionFrames(),
pathFor,
@@ -2796,7 +2798,7 @@ function validateWorkflow() {
routeHint: 'adjust route/via, bias, or channel coordinates so the edge crosses the lane or group perpendicularly instead of following its border'
}));
problems.push(...cleanRouteRhythmProblems({
- relations: workflow.edges,
+ relations: authoredEdges,
endpointIds: new Set(nodes.keys()),
pathFor,
diagramType: 'workflow',
@@ -2870,7 +2872,7 @@ function validateWorkflow() {
}
}
problems.push(...cleanLabelRouteClearanceProblems({
- relations: workflow.edges,
+ relations: authoredEdges,
labels: labelRects,
endpointIds: new Set(nodes.keys()),
pathFor,
diff --git a/test/finalize.test.mjs b/test/finalize.test.mjs
index 1b60d487..1b15a337 100644
--- a/test/finalize.test.mjs
+++ b/test/finalize.test.mjs
@@ -234,7 +234,7 @@ test('finalize stops at the failed gate and persists actionable failure evidence
assert.deepEqual(finalized.summary.nextAction, {
action: 'edit-in-place',
candidate: input,
- constraint: 'Preserve unaffected semantics and geometry; do not replace the whole candidate.',
+ constraint: 'Preserve unaffected semantics and geometry; apply each diagnostic\'s own supportedFixes and do not replace the whole candidate.',
then: 'finalize-once',
});
assert.equal(finalized.receipt.diagnostics[0].evidence.intersection[1], 40);
@@ -1304,3 +1304,19 @@ test('runFinalize reads the capture limit from the supplied env, not process.env
assert.equal(overflowed.receipt.stages.validate.status, 'fail');
assert.equal(overflowed.receipt.stages.validate.receipt.diagnostics[0].code, 'artifact/check-output-limit');
});
+
+test('compact review and repair guidance follow the mode and the failing diagnostics', () => {
+ const routeReview = { crossings: [{ left: { from: 'a', to: 'b' }, right: { from: 'c', to: 'd' } }], detours: [] };
+ const lifecycle = compactFinalizeReceipt({ ok: true, type: 'lifecycle', stages: { check: { receipt: { composition: {
+ metrics: { resolvedCrossovers: 1 }, routeReview,
+ } } } } }).visualReviewRecommendation;
+ assert.equal('hints' in lifecycle, false);
+ assert.doesNotMatch(lifecycle.repair, /architecture-layout-repair/);
+
+ const failure = (code) => compactFinalizeReceipt({
+ ok: false, status: 'fail', failedStage: 'validate', type: 'architecture',
+ diagnostics: [{ code, severity: 'error', message: code }],
+ }).nextAction.constraint;
+ assert.doesNotMatch(failure('composition/desktop-readability'), /architecture-layout-repair/);
+ assert.match(failure('composition/proper-crossing'), /architecture-layout-repair/);
+});
diff --git a/test/fixtures/lifecycle-crowded-wide.json b/test/fixtures/lifecycle-crowded-wide.json
new file mode 100644
index 00000000..1d48af12
--- /dev/null
+++ b/test/fixtures/lifecycle-crowded-wide.json
@@ -0,0 +1,237 @@
+{
+ "schema_version": 3,
+ "diagram_type": "lifecycle",
+ "meta": {
+ "title": "Crowded wide lifecycle",
+ "locale": "zh-CN",
+ "output": "lifecycle.html",
+ "quality_profile": "showcase"
+ },
+ "mainPath": [
+ "connecting",
+ "planning",
+ "plan_ready",
+ "executing",
+ "awaiting_acceptance",
+ "completed"
+ ],
+ "states": [
+ {
+ "id": "connecting",
+ "type": "start",
+ "label": "正在连接",
+ "sublabel": "建立 ACP 会话",
+ "tag": "connecting",
+ "step": "01"
+ },
+ {
+ "id": "planning",
+ "type": "active",
+ "label": "规划中",
+ "sublabel": "生成 Plan",
+ "tag": "running·plan",
+ "step": "02"
+ },
+ {
+ "id": "plan_ready",
+ "type": "decision",
+ "label": "待确认计划",
+ "sublabel": "等待确认",
+ "tag": "ready·plan",
+ "step": "03"
+ },
+ {
+ "id": "executing",
+ "type": "active",
+ "label": "执行中",
+ "sublabel": "按 Plan 执行",
+ "tag": "running·process",
+ "step": "04"
+ },
+ {
+ "id": "awaiting_acceptance",
+ "type": "waiting",
+ "label": "待验收",
+ "sublabel": "结果卡片",
+ "tag": "ready·result",
+ "step": "05"
+ },
+ {
+ "id": "completed",
+ "type": "success",
+ "label": "已完成",
+ "sublabel": "结果已验收",
+ "tag": "completed",
+ "step": "06"
+ },
+ {
+ "id": "undelivered",
+ "type": "waiting",
+ "label": "回合结束未交付",
+ "sublabel": "缺少有效 mobi-result",
+ "tag": "ready·process"
+ },
+ {
+ "id": "revision",
+ "type": "waiting",
+ "label": "待返工反馈",
+ "sublabel": "revisionRequested",
+ "tag": "ready·result"
+ },
+ {
+ "id": "paused",
+ "type": "neutral",
+ "label": "已停止",
+ "sublabel": "用户停止或宿主重启",
+ "tag": "paused"
+ },
+ {
+ "id": "error",
+ "type": "failure",
+ "label": "出错了",
+ "sublabel": "ACP 或协议异常",
+ "tag": "error"
+ }
+ ],
+ "transitions": [
+ {
+ "id": "t-connect",
+ "from": "connecting",
+ "to": "planning",
+ "label": "会话就绪"
+ },
+ {
+ "id": "t-plan-done",
+ "from": "planning",
+ "to": "plan_ready",
+ "label": "回合结束"
+ },
+ {
+ "id": "t-confirm",
+ "from": "plan_ready",
+ "to": "executing",
+ "label": "确认计划",
+ "variant": "emphasis"
+ },
+ {
+ "id": "t-deliver",
+ "from": "executing",
+ "to": "awaiting_acceptance",
+ "label": "mobi-result"
+ },
+ {
+ "id": "t-accept",
+ "from": "awaiting_acceptance",
+ "to": "completed",
+ "label": "验收通过",
+ "variant": "emphasis"
+ },
+ {
+ "id": "t-clarify",
+ "from": "plan_ready",
+ "to": "planning",
+ "label": "补充消息"
+ },
+ {
+ "id": "t-native-approve",
+ "from": "planning",
+ "to": "executing",
+ "label": "批准计划权限",
+ "variant": "dashed"
+ },
+ {
+ "id": "t-no-envelope",
+ "from": "executing",
+ "to": "undelivered",
+ "label": "无结果信封"
+ },
+ {
+ "id": "t-continue",
+ "from": "undelivered",
+ "to": "executing",
+ "label": "继续对话"
+ },
+ {
+ "id": "t-request-changes",
+ "from": "awaiting_acceptance",
+ "to": "revision",
+ "label": "提出修改"
+ },
+ {
+ "id": "t-feedback",
+ "from": "revision",
+ "to": "planning",
+ "label": "发送反馈"
+ },
+ {
+ "id": "t-followup",
+ "from": "completed",
+ "to": "planning",
+ "label": "追加消息",
+ "variant": "dashed"
+ },
+ {
+ "id": "t-stop-connect",
+ "from": "connecting",
+ "to": "paused",
+ "label": "停止"
+ },
+ {
+ "id": "t-stop-plan",
+ "from": "planning",
+ "to": "paused",
+ "label": "停止"
+ },
+ {
+ "id": "t-stop-exec",
+ "from": "executing",
+ "to": "paused",
+ "label": "停止"
+ },
+ {
+ "id": "t-resume-plan",
+ "from": "paused",
+ "to": "planning",
+ "label": "继续·计划"
+ },
+ {
+ "id": "t-resume-exec",
+ "from": "paused",
+ "to": "executing",
+ "label": "继续·执行"
+ },
+ {
+ "id": "t-fail-connect",
+ "from": "connecting",
+ "to": "error",
+ "label": "出错",
+ "variant": "security"
+ },
+ {
+ "id": "t-fail-plan",
+ "from": "planning",
+ "to": "error",
+ "label": "出错",
+ "variant": "security"
+ },
+ {
+ "id": "t-fail-exec",
+ "from": "executing",
+ "to": "error",
+ "label": "出错",
+ "variant": "security"
+ },
+ {
+ "id": "t-retry-plan",
+ "from": "error",
+ "to": "planning",
+ "label": "重发·计划"
+ },
+ {
+ "id": "t-retry-exec",
+ "from": "error",
+ "to": "executing",
+ "label": "重发·执行"
+ }
+ ]
+}
diff --git a/test/lifecycle-layout.test.mjs b/test/lifecycle-layout.test.mjs
index 29630a4d..37b3c431 100644
--- a/test/lifecycle-layout.test.mjs
+++ b/test/lifecycle-layout.test.mjs
@@ -356,3 +356,15 @@ test('nodeLabelLayout reserves the source badge footprint on the right rail', ()
const both = nodeLabelLayout({ width: 120, height: 64, rows, brand: true, source: true });
assert.ok(both.ys[0] >= 19 + 2);
});
+
+test('a too-wide lifecycle names the crowded labels that widened every gap', async () => {
+ const { spawnSync } = await import('node:child_process');
+ const { fileURLToPath } = await import('node:url');
+ const cli = fileURLToPath(new URL('../archify/bin/archify.mjs', import.meta.url));
+ const fixture = fileURLToPath(new URL('./fixtures/lifecycle-crowded-wide.json', import.meta.url));
+ const result = spawnSync(process.execPath, [cli, 'validate', 'lifecycle', fixture, '--json'], { encoding: 'utf8' });
+ const diagnostic = JSON.parse(result.stdout).diagnostics.find((entry) => entry.code === 'lifecycle/too-wide');
+ assert.ok(diagnostic, result.stdout);
+ assert.ok(diagnostic.evidence.spacingWideners.length > 0);
+ assert.match(diagnostic.supportedFixes[0], /found no clear spot at the base spacing, so every gap widened by 28px/);
+});
diff --git a/test/workflow-shared-trunks.test.mjs b/test/workflow-shared-trunks.test.mjs
index 73895d68..ab4ed734 100644
--- a/test/workflow-shared-trunks.test.mjs
+++ b/test/workflow-shared-trunks.test.mjs
@@ -250,3 +250,15 @@ test('compiler and artifact checks both report independent shared arrowheads', (
const checked=checkSvg(t,result.svg.replace(/^[\s\S]*?<svg[^>]*>/,'').replace(/<\/svg>\s*$/,''),'standard');
assert.equal(checked.receipt.composition.metrics.arrowheadCollisions,1);
});
+
+test('composition diagnostics name edges by their authored index', () => {
+ const workflow = sharedCrossingWorkflow();
+ workflow.meta.quality_profile = 'showcase';
+ workflow.edges[0].id = 'z-ab';
+ workflow.edges[1].id = 'a-ac';
+ const compiled = compileWorkflow({ workflow, qualityProfile: 'showcase' });
+ const diagnostic = compiled.receipt.diagnostics.find(d => d.code === 'composition/proper-crossing');
+ assert.ok(diagnostic, JSON.stringify(compiled.receipt.diagnostics));
+ const [first, second] = [...diagnostic.message.matchAll(/edges\[(\d+)\] id "([^"]+)"/g)].map(match => [Number(match[1]), match[2]]);
+ for (const [index, id] of [first, second]) assert.equal(workflow.edges[index].id, id);
+});