Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
Improve natural authoring guidance and optional visual evidence summaries
tt-a1i58d09fb1bc1a
diff --git a/archify.zip b/archify.zipindex c9e7c3b2..d4d0e49e 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 7035ece2..196f73ab 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -28,7 +28,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer R1. Choose `architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle` from the question.2. Use the exact paths in the Type router; do not list `schemas/` or `examples/` first. For Architecture, select the matching showcase example in the Type router before loading it with `references/authoring-defaults.md` in one parallel batch; it includes boundaries, guided views, and conclusion cards. For Workflow, read defaults and its starter together. Read the relevant schema definition for any new field, enum choice, or constrained text; an example shows shape, not every allowed value or length. Boundary kinds and guided-view notes need their schema constraints before writing. For Sequence, Dataflow, and Lifecycle, read defaults, schema, common schema, and example together. Fresh authorship means new IDs, domain wording, and layout; examples provide shape, not facts. Do not run help, doctor, validate a starter, create a temporary diagram, pre-create/list output paths, or query brands. Only for explicitly requested branded marks may you 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: once requested scope and source evidence are covered, write the candidate directly; do not plan coordinates in prose. For Architecture, default to a system overview: one clear main path, short side branches, and sparse labels. Choose abstraction for the reader's question using [Composition and meaning](references/authoring-defaults.md#composition-and-meaning). Split an overview node only when combining it would mislead the reader about a requested interaction or important boundary; expand internals when the user asks for that mechanism. Keep source evidence for every claim. Never use node, relationship, source-reference, view, card, or boundary counts as an authoring target, ceiling, or performance lever. Add guided views and conclusion cards only when they answer an additional reader question. Set `meta.quality_profile` to `"showcase"` unless the user requests dense `standard`. Place nodes by their actual connections using Layout and routing in the defaults: main-path neighbors stay adjacent, branches sit beside their owner, and return paths have an outside corridor. Check every relationship against that placement before writing positions; automatic routing cannot rearrange nodes. Leave clear gaps for actual relationship labels. Start with automatic routes; use simple endpoint sides when the composition needs a main rail and a distinct branch. Do not guess `via`, `channelX`, `channelY`, or label coordinates before measured geometry. Use the smallest control that expresses the intended route.+3. Artifact first: once requested scope and source evidence are covered, write the candidate directly; do not plan coordinates in prose. For Architecture, default to a system overview: one clear main path, short side branches, and sparse labels. Choose abstraction for the reader's question using [Composition and meaning](references/authoring-defaults.md#composition-and-meaning). Split an overview node only when combining it would mislead the reader about a requested interaction or important boundary; expand internals when the user asks for that mechanism. Keep source evidence for every claim. Never use node, relationship, source-reference, view, card, or boundary counts as an authoring target, ceiling, or performance lever. Add guided views and conclusion cards only when they answer an additional reader question. Set `meta.quality_profile` to `"showcase"` unless the user requests dense `standard`. Place nodes by their actual connections using Layout and routing in the defaults: main-path neighbors stay adjacent, branches sit beside their owner, and return paths have an outside corridor. Check every relationship against that placement before writing positions; automatic routing cannot rearrange nodes. Leave clear gaps for actual relationship labels. Start with automatic routes and let them align main-path endpoints. Pin an endpoint side only for a necessary branch/return constraint or user-supplied geometry; facing-side pins can introduce doglegs between unequal-height nodes. Do not guess `via`, `channelX`, `channelY`, or label coordinates before measured geometry. Use the smallest control that expresses the intended route.4. Once the complete first candidate is written, run `finalize` directly. Its first gate is showcase validation; successful first drafts need no separate pre-validation. Keep the candidate unchanged while the command runs:```bash@@ -39,7 +39,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer RA 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 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.+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. Preserve the requested meaning and its evidence during repair. For an authored overview that chose the wrong abstraction, follow Composition and meaning before regrouping; user-supplied or agreed topology stays fixed. For geometry defects, reroute, reposition, or add readable canvas space. 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@@ -76,7 +76,7 @@ Use the `finalize` command above for the first candidate and after a repair.`finalize` stops at the first non-passing gate. Its compact stdout and `<output-stem>.finalize-summary.json` are the normal evidence; `<output-stem>.finalize.json` is full audit detail, not ordinary repair context. A passing `finalize` receipt reports `visualReview: "not-requested"` and creates no screenshots; report the subsequent perceptual review separately.-For every newly authored or repositioned Architecture, run `visual-check` and inspect its desktop captures before handoff. Check that the main interaction and each secondary chain read in order, branches stay near their owner, and labels visibly belong to their lines. A low crossing count does not establish this. For other artifacts, escalate to perceptual review when the summary includes `visualReviewRecommendation`, the user requests an aesthetic review, a template/renderer/viewer change needs visual regression evidence, a novel layout or browser diagnostic leaves low confidence, or the run is a sampled audit. Run `visual-check` on the finalized artifact, open its HTML contact sheet in a browser or inspect the viewport PNGs with a capable image reader, and trace the affected routes at the common desktop viewport. Each arrow must remain distinct and each relationship traceable through crossings and bends. When several routes remain tangled, follow [Architecture layout repair](references/architecture-layout-repair.md) before editing, even if all automated gates passed. Repair unreadable placement or routes while preserving semantic coverage, then finalize the new candidate. The recommendation's counts trigger inspection; they are not content budgets or proof of a defect. If perceptual review is unavailable, report that quality remains unverified rather than treating automated success as visual approval.+Perceptual review is optional in ordinary generation: a new or repositioned Architecture does not by itself require screenshots or an image-reading step. Use it when the user requests a visual review, during development audits, or when a concrete route/browser concern needs visual diagnosis. `visualReviewRecommendation` is advisory, not a delivery gate or proof of a defect. Run `visual-check` on the finalized artifact with `--summary --require-provenance` and the same `--out-dir` as finalize, if used; compact JSON links all captures and the full receipt. If you choose to review, inspect the relevant viewport/theme captures and trace the affected relationships. For tangled routes, follow [Architecture layout repair](references/architecture-layout-repair.md); preserve meaning and evidence, then finalize the revised candidate. Without image inspection, report automated checks only and leave perceptual review unclaimed. If perceptual review is unavailable, report that quality remains unverified for that requested review.For recovery, the required order stays `deliver` → strict provenance `check` → `browser-check`. Run `visual-check` only against a strict-provenance artifact. Read `references/delivery-contract.md` for standalone syntax, any failed gate, stale provenance, recovery metadata, repeated delivery to one path, export evidence, or post-delivery opening.diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex ac785d62..9d788700 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -2184,8 +2184,8 @@ function usage() {archify migrate workflow <old.json> <new.json> --to-schema 2 [--output portable.html] [--json] [--repo-root path]archify inspect <type> <input.json>archify check <output.html> [--json] [--require-provenance]- archify browser-check <output.html> [--json] [--require-provenance] [--out-dir <dir>]- archify visual-check <output.html> [--json] [--require-provenance] [--out-dir <dir>]+ archify browser-check <output.html> [--json|--summary] [--require-provenance] [--out-dir <dir>]+ archify visual-check <output.html> [--json|--summary] [--require-provenance] [--out-dir <dir>]archify guide [scenario or question] [--json] [--lang en|zh]archify brands [name, alias, domain, or category] [--json]archify brands capture <url> [--json]@@ -5482,9 +5482,16 @@ async function executeBrowserEvidence({async function commandBrowserEvidence(rawArgs, { command, capture }) {const { rest: args, outDir: rawOutDir } = extractOutDirArgs(rawArgs);- const json = args.includes('--json');+ const summary = args.includes('--summary');+ const json = args.includes('--json') || summary;+ const printJson = async (receipt) => {+ const value = summary+ ? (await import('./visual-check.mjs')).summarizeBrowserEvidence(receipt)+ : receipt;+ console.log(JSON.stringify(value, null, summary ? undefined : 2));+ };const requireProvenance = args.includes('--require-provenance');- const knownOptions = new Set(['--json', '--require-provenance']);+ const knownOptions = new Set(['--json', '--summary', '--require-provenance']);const unknown = args.filter((arg) => arg.startsWith('--') && !knownOptions.has(arg));if (unknown.length) fail(`Unknown ${command} option "${unknown[0]}".`, 1);const positional = args.filter((arg) => !knownOptions.has(arg));@@ -5515,7 +5522,7 @@ async function commandBrowserEvidence(rawArgs, { command, capture }) {error: error.message,diagnostics: [outputDiagnostic],};- if (json) console.log(JSON.stringify(failure, null, 2));+ if (json) await printJson(failure);else {console.error(formatDiagnostics(`automated browser evidence failed: ${failure.error}`, failure.diagnostics));console.error('perceptual visual review pending');@@ -5527,7 +5534,7 @@ async function commandBrowserEvidence(rawArgs, { command, capture }) {const result = await executeBrowserEvidence({ artifactPath, outDir, requireProvenance, command, capture });if (result.inputFailure) {- if (json) console.log(JSON.stringify(result.receipt, null, 2));+ if (json) await printJson(result.receipt);else {console.error(formatDiagnostics(`automated browser evidence failed: ${result.receipt.error}`, result.receipt.diagnostics));console.error(capture ? 'perceptual visual review pending' : 'perceptual visual review not requested');@@ -5537,7 +5544,7 @@ async function commandBrowserEvidence(rawArgs, { command, capture }) {}if (json) {- console.log(JSON.stringify(result.receipt, null, 2));+ await printJson(result.receipt);} else {const sidecarDirectory = outDir || path.dirname(result.receipt.artifact.path);console.log(`automated browser evidence ${result.receipt.status}: ${result.receipt.artifact.path}`);diff --git a/archify/bin/visual-check.mjs b/archify/bin/visual-check.mjsindex 18b90e26..7549e8c9 100644--- a/archify/bin/visual-check.mjs+++ b/archify/bin/visual-check.mjs@@ -1963,6 +1963,46 @@ function contactSheetHtml({ artifactPath, receipt, screenshots }) {`;}+const publishedBrowserEvidenceReceipts = new WeakSet();++// Keep detailed observations in the bound receipt; expose every review image and+// every failure without repeating the same viewport metrics in CLI context.+export function summarizeBrowserEvidence(receipt) {+ const directory = receipt.sidecars?.directory || path.dirname(receipt.artifact.path);+ const evidencePath = (file) => file ? path.resolve(directory, file) : undefined;+ const published = publishedBrowserEvidenceReceipts.has(receipt);+ return {+ schemaVersion: receipt.schemaVersion,+ command: receipt.command,+ ok: receipt.ok,+ status: receipt.status,+ evidenceKind: receipt.evidenceKind,+ visualReview: receipt.visualReview,+ artifact: receipt.artifact,+ provenance: receipt.provenance,+ deliveryReceiptId: receipt.deliveryReceiptId,+ state: receipt.state,+ chrome: receipt.chrome,+ checks: Object.fromEntries(['containment', 'readability', 'viewerChrome', 'themeStates', 'captures']+ .filter((key) => receipt[key])+ .map((key) => [key, receipt[key].status])),+ error: receipt.error,+ publication: receipt.publication,+ diagnostics: receipt.diagnostics || [],+ evidence: {+ receipt: published ? evidencePath(receipt.sidecars?.receipt) : undefined,+ contactSheet: published ? evidencePath(receipt.captures?.contactSheet) : undefined,+ screenshots: (published ? receipt.captures?.screenshots || [] : []).map((entry) => ({+ path: evidencePath(entry.file),+ width: entry.width,+ height: entry.height,+ theme: entry.theme,+ resolvedTheme: entry.resolvedTheme,+ })),+ },+ };+}+function viewportSubject(artifact, entry) {return {artifact,@@ -2302,6 +2342,7 @@ function persistBrowserEvidenceFailure(activeOwnership = preflight.ownership;}const publication = publishReceiptOnly(artifactPath, outputs, receipt, activeOwnership);+ if (publication.ok) publishedBrowserEvidenceReceipts.add(receipt);appendEvidencePublicationFailure(receipt, publication);appendEvidenceCleanupWarning(receipt, publication);return receipt;@@ -2421,6 +2462,7 @@ async function runBrowserEvidence({supportedFixes: [`set ARCHIFY_CHROME to a Chrome or Chromium executable and rerun ${command}`],})];const publication = publishReceiptOnly(artifact, outputs, receipt, ownership);+ if (publication.ok) publishedBrowserEvidenceReceipts.add(receipt);if (!publication.ok) {appendEvidencePublicationFailure(receipt, publication);return { exitCode: EXIT.fail, receipt };@@ -2554,6 +2596,7 @@ async function runBrowserEvidence({receipt.status = 'fail';return { exitCode: EXIT.fail, receipt };}+ publishedBrowserEvidenceReceipts.add(receipt);if (appendEvidenceCleanupWarning(receipt, publication)) {return { exitCode: EXIT.fail, receipt };}diff --git a/archify/references/authoring-defaults.md b/archify/references/authoring-defaults.mdindex 586a0f3d..476289b2 100644--- a/archify/references/authoring-defaults.md+++ b/archify/references/authoring-defaults.md@@ -27,6 +27,7 @@ Examples demonstrate valid field shape. Before choosing a different boundary kin- Choose abstraction by the reader's question: would combining these responsibilities mislead the reader about the requested behavior, control ownership, trust, lifecycle, or persistence? If so, keep them separate; otherwise use an accurately named overview node with supporting labels and source references. Separate source files, classes, protocols, or internal services do not by themselves require separate nodes. For example, an overview may show one local HTTP / WebSocket service; a transport-mechanism diagram may expand it. A cloud relay and a local decrypting bridge stay distinct when the remote trust boundary matters.- Cover the requested meaning, with evidence for every claim. An overview need not enumerate every implementation role discovered during source reading. Put useful supporting facts in sublabels or concise cards; expand a subsystem in a focused diagram when its mechanism is requested. Guided views focus existing topology and do not collapse a crowded default overview. Add `meta.views` or cards only for a real reader question, with no quota.- Let the requested question and source facts determine node and relationship counts; never target a number. Choose scope and abstraction before routing. Once authoring or repairing an agreed detailed graph, preserve its required roles, relationships, meaningful labels, and evidence; geometry failures do not authorize silently reducing that scope.+- When correcting an authored overview's abstraction, map every affected role, relationship direction, protocol, boundary, and source reference to its surviving node or relationship before regrouping. Carry the inspected references for each retained claim onto the relevant surviving component; a citation proving process startup does not also prove its message protocol. Check that requested meaning and evidence still have a home. User-supplied or agreed topology stays fixed; fewer routes alone do not justify merging.- A boundary is evidence, not decoration. Use it when it communicates a real trust, runtime, process, ownership, or persistence boundary; a boundary around one node needs an explicit isolation fact. Do not box every concern or duplicate the node label as a boundary title.- Omit `meta.visual_preset` by default so every diagram opens in `classic`, regardless of whether its resolved color mode is light or dark. Switching Light / Dark preserves the current preset. Set `signal-flow`, `blueprint`, or `editorial` only when the user explicitly requests that visual style.- Omit `meta.subtitle` by default. Never invent a subtitle that restates the title, nodes, or cards; include one short supporting line only when the user explicitly asks for it.@@ -54,7 +55,7 @@ Set required `meta.output` to a portable POSIX-relative `.html` path, such as `r- If the largest viewport still has a conspicuous empty lower band at the viewer's width cap, redistribute authored Y positions and increase the viewBox height proportionally; do not add filler copy or decorative cards.- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; follow the label-preserving repair order.- Place Architecture nodes from connectivity before assigning coordinates: lay the main interaction path in order, place a branch beside the node it actually connects to, and place a shared store beside its main readers/writers. A category row (all runtimes, then all workers, then all stores) is useful only when the actual edges also follow it. Keep each tightly connected neighborhood together; give real return paths a clear outside corridor. Mentally trace every relationship across the proposed boxes before writing: if an unrelated node or another neighborhood blocks it, move the connected neighborhood now. The router chooses paths around fixed boxes; it does not rearrange a poor node layout. Choose the main path by the reader’s task, not by component category or the longest graph path. Keep a second data-processing chain in its own consistent reading order; place its scheduler beside the stage it drives. Do not move the main actor to a distant row to make room for a background worker. This is part of writing the first JSON, not an extra planning document or tool pass.-- For a medium Architecture, encode one obvious main path, but let it step across multiple rows when one horizontal rail would create a shallow strip, long empty corridors, or force semantic compression. Put short branches above or below their nearest hub. Start with automatic routes. Simple `fromSide` / `toSide` choices may express a deliberate composition on the first draft; reserve `via`, `channelX`, `channelY`, and label-position controls for measured geometry. For example, at a crowded hub reserve facing sides for the main path and other sides for branches, or give a real return edge one compact outer side pair or perimeter corridor. Never make unrelated orthogonal segments share the same axis for 8px or more; keep nonzero segments at least 8px and interior turns at least 16px.+- For a medium Architecture, encode one obvious main path, but let it step across multiple rows when one horizontal rail would create a shallow strip, long empty corridors, or force semantic compression. Put short branches above or below their nearest hub. Start with automatic routes. Leave main-path `fromSide` / `toSide` unset so the router can align endpoints across different node heights. Pin a side only for a necessary branch or return constraint, such as a return edge on the outer side of a hub. Reserve `via`, `channelX`, `channelY`, and label-position controls for measured geometry. Never make unrelated orthogonal segments share the same axis for 8px or more; keep nonzero segments at least 8px and interior turns at least 16px.- Before writing, apply `6.5px × ASCII units + 21px`, counting each CJK character as two units, to every labeled connection on the main path. Treat the result as that edge's minimum clear gap, never as one fixed gap shared across the row. Increase the gap or choose a clear segment when the budget does not fit; do not wait for a predictable label-route collision.- Automatic routes own their endpoint sides. A relationship does not accept a `side` field; use `fromSide` or `toSide` when a deliberate branch or return direction is needed. Each endpoint side is a direction contract: the first and final segment must leave/enter perpendicular to that side.- Estimate the resolved Architecture content width before the first write. At 1440px, legacy, unknown, and authored-viewBox artifacts use the conservative 930px diagram budget. A fresh automatic wide Architecture with the recognized Reader contract instead reports its declared budget and cap in `composition.desktopReadability`; use that evidence before changing a semantic node or relationship label. Keep ordinary context text comfortably above the 6px hard floor by adding meaningful rows or using intrinsic-height layout, not by dropping meaning or designing to a fixed viewBox width.diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex 9a6b8195..3dcde663 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -406,9 +406,11 @@ Both browser commands inspect the exact delivered HTML without modifying or rereperceptual review:```bash-node bin/archify.mjs visual-check <output.html> --json --require-provenance+node bin/archify.mjs visual-check <output.html> --summary --require-provenance```+`--summary` returns compact JSON with all diagnostics and absolute paths to the complete receipt, contact sheet, and every screenshot. For a chosen visual review, inspect the relevant captures; capture success is not perceptual approval. `--json` retains the full receipt output for existing consumers. Both modes run the same checks and keep the same exit status. If cleanup fails after publication, the summary retains the final failure diagnostics and `publication` recovery details; the linked receipt records the earlier committed evidence.+It performs the same automated browser measurements, captures light/darkscreenshots at 1440×900 and 2048×1320, and writes four viewport PNG sidecars,one relative-path HTML contact sheet, and one JSON receipt. `--out-dir <dir>` moves all of these sidecars together.@@ -468,7 +470,7 @@ Browser evidence belongs to exact artifact bytes. After editing a candidate whos```bashnode bin/archify.mjs finalize architecture candidate.json diagram.html --quality showcase --repo-root <root> --out-dir diagram.review-2 --json-node bin/archify.mjs visual-check diagram.html --out-dir diagram.review-2 --json --require-provenance+node bin/archify.mjs visual-check diagram.html --out-dir diagram.review-2 --summary --require-provenance```Keep the requested HTML path stable. Use a new revision directory for each changed candidate, and retain the same directory for retries of unchanged bytes. For a diagram without repository evidence, omit `--repo-root`. Let the commands create their output directory. A prior validation failure that produced no HTML or browser evidence needs no new directory. Never remove unknown evidence to make a retry pass.@@ -502,11 +504,12 @@ Never start it by default. Do not use it for CI, unattended agents, remote shari## Perceptual reviewThe automated path ends with the deterministic browser gate and reports-`visual_review: not_requested`. Escalate to perceptual review when any of these-conditions applies:+`visual_review: not_requested`. Ordinary generation does not require screenshots+or an image-reading step, including newly authored or repositioned Architecture.+Perceptual review is optional; use it for an explicit request or a concrete visual+investigation. Possible reasons include:-- an Architecture is newly authored or its nodes have been repositioned;-- the compact finalizer includes `visualReviewRecommendation` for crossings or detours;+- the compact finalizer includes `visualReviewRecommendation` for crossings or detours (advisory, not a delivery gate);- the user explicitly requests an aesthetic or visual review;- a template, renderer, or Viewer change needs visual regression evidence;- a novel layout or browser diagnostic leaves low confidence;diff --git a/archify/test/authoring-safety-contract.test.mjs b/archify/test/authoring-safety-contract.test.mjsindex ffa0f9cf..f2df1e04 100644--- a/archify/test/authoring-safety-contract.test.mjs+++ b/archify/test/authoring-safety-contract.test.mjs@@ -48,7 +48,7 @@ test('visual-check stays a pending sidecar receipt instead of a polish claim', (assert.match(skill, /references\/delivery-contract\.md/);assert.match(skill, /without (?:rerendering or )?modifying/i);- assert.match(deliveryContract, /visual-check <output\.html> --json/);+ assert.match(deliveryContract, /visual-check <output\.html> --summary/);assert.match(deliveryContract, /1440×900[\s\S]*1600×1000[\s\S]*1920×1080[\s\S]*2048×1320/);assert.match(deliveryContract, /visualReview: "pending"/);assert.match(deliveryContract, /never changes.*delivered|without (?:rerendering or )?modifying/i);diff --git a/archify/test/cli.test.mjs b/archify/test/cli.test.mjsindex d270b633..ec066a2a 100644--- a/archify/test/cli.test.mjs+++ b/archify/test/cli.test.mjs@@ -462,6 +462,35 @@ test('cli: finalize emits one compact receipt and keeps complete stage evidenceassert.equal(fs.existsSync(out), true, 'verified delivery remains available when browser evidence is skipped');});+test('cli: visual-check summary preserves skipped and failed evidence without claiming image review', () => {+ const out = path.join(tmp, 'visual-summary.html');+ fs.writeFileSync(out, '<!doctype html><html><body>delivered</body></html>');+ const outDir = path.join(tmp, 'visual-summary-evidence');+ const result = run(['visual-check', out, '--summary', '--out-dir', outDir], {+ env: { ...process.env, ARCHIFY_CHROME: path.join(tmp, 'summary-missing-chrome') },+ });+ assert.equal(result.status, 2, result.stderr || result.stdout);+ assert.equal(result.stdout.trim().split('\n').length, 1);+ const summary = JSON.parse(result.stdout);+ assert.equal(summary.status, 'skipped');+ assert.equal(summary.visualReview, 'pending');+ assert.deepEqual(summary.evidence.screenshots, []);+ const full = JSON.parse(fs.readFileSync(summary.evidence.receipt, 'utf8'));+ assert.deepEqual(summary.artifact, full.artifact);+ assert.deepEqual(summary.diagnostics, full.diagnostics);+ assert.equal(summary.checks.containment, full.containment.status);+ assert.equal(summary.evidence.receipt, path.join(outDir, 'visual-summary.visual-check.json'));++ const failure = run(['visual-check', path.join(tmp, 'summary-missing.html'), '--summary']);+ assert.equal(failure.status, 1);+ const failedSummary = JSON.parse(failure.stdout);+ assert.equal(failedSummary.status, 'fail');+ assert.equal(failedSummary.visualReview, 'pending');+ assert.ok(failedSummary.diagnostics.length > 0);+ assert.deepEqual(failedSummary.evidence.screenshots, []);+ assert.equal(failedSummary.evidence.receipt, undefined, 'an unpublished receipt must not be linked');+});+test('cli: visual-check --out-dir writes the receipt into that directory, not beside the artifact', () => {const out = path.join(tmp, 'visual-check-outdir.html');fs.writeFileSync(out, '<!doctype html><html><body>delivered</body></html>');diff --git a/archify/test/delivery-contract.test.mjs b/archify/test/delivery-contract.test.mjsindex 8d1b0ed6..a6c5c443 100644--- a/archify/test/delivery-contract.test.mjs+++ b/archify/test/delivery-contract.test.mjs@@ -78,9 +78,10 @@ test('strict provenance succeeds before either browser command', () => {assert.match(skill, /Run `visual-check` only against a strict-provenance artifact/);});-test('perceptual review covers fresh architectures and risk escalation with a bounded correction loop', () => {+test('perceptual review is optional for fresh architectures and available for visual diagnosis', () => {assert.match(perceptualReviewSection, /visual_review: not_requested/);- assert.match(perceptualReviewSection, /Architecture is newly authored or its nodes have been repositioned/);+ assert.match(perceptualReviewSection, /Ordinary generation does not require screenshots/);+ assert.match(skill, /Perceptual review is optional in ordinary generation/);assert.match(perceptualReviewSection, /user explicitly requests an aesthetic or visual review/i);assert.match(perceptualReviewSection, /template, renderer, or Viewer change/i);assert.match(perceptualReviewSection, /novel layout or browser diagnostic leaves low confidence/i);diff --git a/archify/test/visual-check.test.mjs b/archify/test/visual-check.test.mjsindex ef33381c..48b7b14a 100644--- a/archify/test/visual-check.test.mjs+++ b/archify/test/visual-check.test.mjs@@ -21,6 +21,7 @@ import {runBrowserCheck,browserCheckSidecarPaths,sidecarPaths,+ summarizeBrowserEvidence,} from '../bin/visual-check.mjs';import { sameLocation } from '../renderers/shared/path-semantics.mjs';@@ -29,6 +30,33 @@ const skillRoot = path.resolve(__dirname, '..');const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-visual-check-'));const png = Buffer.from('89504e470d0a1a0a', 'hex');+test('summary indexes every captured viewport/theme and preserves failed diagnostics', async () => {+ const input = artifact('summary-captures.html');+ const result = await runVisualCheck({ artifactPath: input, browserFactory: () => fakeBrowser() });+ const receipt = result.receipt;+ const summary = summarizeBrowserEvidence(receipt);+ assert.equal(summary.visualReview, 'pending');+ assert.equal(summary.evidence.screenshots.length, 4);+ for (const capture of summary.evidence.screenshots) {+ assert.ok(path.isAbsolute(capture.path));+ assert.ok(fs.existsSync(capture.path));+ assert.ok(['light', 'dark'].includes(capture.theme));+ }+ assert.deepEqual(summary.evidence.screenshots.map(({ width, height, theme }) => [width, height, theme]),+ receipt.captures.screenshots.map(({ width, height, theme }) => [width, height, theme]));+ assert.ok(fs.existsSync(summary.evidence.receipt));+ assert.ok(fs.existsSync(summary.evidence.contactSheet));+ assert.ok(JSON.stringify(summary).length < JSON.stringify(receipt).length / 2);+ const diagnostic = { code: 'viewer/example', severity: 'error', evidence: { gap: 3 }, supportedFixes: ['reposition'] };+ const failed = summarizeBrowserEvidence({ ...receipt, ok: false, status: 'fail', diagnostics: [diagnostic] });+ assert.equal(failed.ok, false);+ assert.equal(failed.status, 'fail');+ assert.deepEqual(failed.diagnostics, [diagnostic]);+ assert.equal(failed.evidence.receipt, undefined);+ assert.equal(failed.evidence.contactSheet, undefined);+ assert.deepEqual(failed.evidence.screenshots, [], 'unpublished capture metadata is not an evidence link');+});+function artifact(name = 'diagram.html') {const file = path.join(tmp, name);fs.writeFileSync(file, '<!doctype html><html><body>checked artifact</body></html>');@@ -2209,6 +2237,12 @@ for (const scenario of [scenario.fault === 'unlink' ? oldContactSheet : claimantBytes,);assert.equal(JSON.parse(fs.readFileSync(outputs.receipt, 'utf8')).status, 'pass');+ const summary = summarizeBrowserEvidence(result.receipt);+ assert.equal(summary.status, 'fail', 'cleanup failure stays visible after evidence was committed');+ assert.equal(fs.realpathSync(summary.evidence.receipt), fs.realpathSync(outputs.receipt));+ assert.deepEqual(summary.publication, result.receipt.publication);+ assert.equal(summary.publication.recoveryDirectory, expectedRecovery);+ assert.deepEqual(summary.diagnostics, result.receipt.diagnostics);assert.equal(fs.existsSync(outputs.contactSheet), true);assert.equal(outputs.screenshots.every((entry) => fs.existsSync(entry.path)), true);});