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
Clarify visual-check as automated browser evidence (#233)
Friend A2bfb47132c05
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex e8cccd56..7f098abe 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -75,7 +75,7 @@ cd archifyARCHIFY_CHROME="/path/to/chrome" node --test test/desktop-reader-browser.test.mjs```-A browser test that was skipped because Chrome was unavailable is **skipped**, not passed. Report that status exactly.+A browser test that was skipped because Chrome was unavailable is **skipped**, not passed. Report automated browser evidence independently from perceptual visual review. Follow the [delivery contract](archify/references/delivery-contract.md) when recording supplementary manual browser work; an unconstrained glance supports only perceptual review.### CLI, receipts, and deliverydiff --git a/archify.zip b/archify.zipindex 9e089631..55b3bbea 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex b130e5cb..7ce2b3fc 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -95,7 +95,7 @@ Read `references/authoring-contract.md` only when you need field enums, spacing## Delivery-Use `validate` during repair and `deliver` once for final acceptance. Delivery freezes the exact specification bytes into a private same-directory snapshot, renders and checks that snapshot, atomically commits the HTML, and reports SHA-256 plus byte counts for both specification and artifact.+Use `validate` during repair and `deliver` once for final acceptance. Delivery freezes the exact specification bytes into a private same-directory snapshot, renders and checks that snapshot, atomically commits the HTML, and reports SHA-256 plus byte counts for both specification and artifact. This is deterministic artifact evidence; it does not exercise the Viewer in a browser.After delivery, collect bounded desktop evidence without modifying or rerendering the trusted HTML:@@ -103,7 +103,9 @@ After delivery, collect bounded desktop evidence without modifying or rerenderinnode bin/archify.mjs visual-check <output.html> --json```-`visual-check` measures containment at 1440×900, 1600×1000, 1920×1080, and 2048×1320; captures light/dark screenshots at the smallest and largest sizes; and writes a relative-path contact sheet plus JSON sidecars beside the artifact. Its automated receipt always reports `visualReview: "pending"`: screenshots are evidence for inspection, never an automatic polish claim. Exit 0 means containment and captures passed, 1 means overflow or capture failure, and 2 means Chrome/Chromium was unavailable and the receipt is `skipped`. The command never changes the delivered HTML.+`visual-check` collects automated browser evidence from the exact delivered HTML without modifying or rerendering it. Its machine-readable measurements and screenshots do not approve perceptual polish. Follow `references/delivery-contract.md` for the canonical receipt fields, coverage, sidecars, exit behavior, and supplementary manual-record requirements.++Keep the three claims separate: `deliver` proves deterministic artifact checks, `visual-check` proves bounded behavior in a real browser, and perceptual visual review requires an actual human or image-capable reviewer. Report browser evidence and perceptual review independently. An unconstrained glance can support only perceptual review; use the canonical delivery contract when recording supplementary manual browser work or handling an environmental failure.Add `--open` only when the user wants an immediate local preview. For an active desktop authoring loop, the optional command is:@@ -132,4 +134,4 @@ When shell access is unavailable, hand-place architecture SVG into `assets/templ## Output-Return the checked HTML path, diagram type, validation summary, specification/artifact receipt, and truthful visual-review status. Do not claim success for a non-zero command or claim visual inspection you did not perform.+Return the checked HTML path, diagram type, validation summary, specification/artifact receipt, browser-evidence status, and truthful visual-review status. Do not claim success for a non-zero command or claim visual inspection you did not perform.diff --git a/archify/bin/archify.mjs b/archify/bin/archify.mjsindex 5fb2cbb9..2b8cc7a7 100755--- a/archify/bin/archify.mjs+++ b/archify/bin/archify.mjs@@ -1177,13 +1177,15 @@ async function commandVisualCheck(args) {schemaVersion: 1,ok: false,command: 'visual-check',+ evidenceKind: 'automated-browser',status: 'fail',visualReview: 'pending',artifact: { path: path.resolve(positional[0]) },error: error.message,}, null, 2));} else {- console.error(`visual-check failed: ${error.message}`);+ console.error(`automated browser evidence failed: ${error.message}`);+ console.error('perceptual visual review pending');}process.exitCode = 1;return;@@ -1192,8 +1194,8 @@ async function commandVisualCheck(args) {if (json) {console.log(JSON.stringify(result.receipt, null, 2));} else {- console.log(`visual-check ${result.receipt.status}: ${result.receipt.artifact.path}`);- console.log(`containment ${result.receipt.containment.status}; captures ${result.receipt.captures.status}; visual review pending`);+ console.log(`automated browser evidence ${result.receipt.status}: ${result.receipt.artifact.path}`);+ console.log(`visual-check containment ${result.receipt.containment.status}; captures ${result.receipt.captures.status}; perceptual visual review pending`);console.log(`receipt ${path.join(path.dirname(result.receipt.artifact.path), result.receipt.sidecars.receipt)}`);if (result.receipt.captures.contactSheet) {console.log(`contact sheet ${path.join(path.dirname(result.receipt.artifact.path), result.receipt.captures.contactSheet)}`);diff --git a/archify/bin/visual-check.mjs b/archify/bin/visual-check.mjsindex 64f48249..8adb154b 100644--- a/archify/bin/visual-check.mjs+++ b/archify/bin/visual-check.mjs@@ -564,13 +564,13 @@ function contactSheetHtml({ artifactPath, receipt, screenshots }) {<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">-<title>Archify visual-check · ${htmlEscape(path.basename(artifactPath))}</title>+<title>Archify automated browser evidence · ${htmlEscape(path.basename(artifactPath))}</title><style>*{box-sizing:border-box}body{margin:0;padding:24px;background:#e9eef5;color:#172033;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}header{max-width:1500px;margin:0 auto 18px}h1{margin:0 0 6px;font-size:20px}p{margin:0;color:#526176}.grid{max-width:1500px;margin:auto;display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:18px}figure{margin:0;padding:10px;background:white;border:1px solid #c9d4e3;border-radius:12px;box-shadow:0 10px 30px rgba(15,23,42,.08)}img{display:block;width:100%;height:auto;border:1px solid #e2e8f0}figcaption{padding:9px 4px 2px;color:#526176}@media(max-width:900px){.grid{grid-template-columns:1fr}}</style></head><body>-<header><h1>Archify visual-check</h1><p>${htmlEscape(path.basename(artifactPath))} · automated containment ${htmlEscape(receipt.containment.status)} · visual review pending</p></header>+<header><h1>Automated browser evidence</h1><p>${htmlEscape(path.basename(artifactPath))} · visual-check containment ${htmlEscape(receipt.containment.status)} · perceptual visual review pending</p></header><main class="grid">${cards}</main></body>@@ -665,6 +665,7 @@ function baseReceipt({ artifactPath, artifact, outputs, chrome }) {schemaVersion: 1,ok: false,command: 'visual-check',+ evidenceKind: 'automated-browser',status: 'fail',visualReview: 'pending',artifact: {diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.mdindex 0181abfc..31f2c1dc 100644--- a/archify/references/delivery-contract.md+++ b/archify/references/delivery-contract.md@@ -16,9 +16,15 @@ previous trusted artifact; running `visual-check` then would measure and capturestale output, not the rejected candidate. Report the delivery diagnostics andrepair the source before collecting new visual evidence.-The deterministic receipt proves byte identity and automated checks. Never claim that the deterministic receipt includes visual review.+The delivery interface exposes three separate claims:-## Automated visual evidence+1. `deliver` proves deterministic artifact checks and byte identity.+2. `visual-check` collects automated browser evidence from the exact artifact.+3. Perceptual visual review records a human or image-capable reviewer's judgment.++Passing one claim never implies either of the others. Never claim that the deterministic receipt includes visual review. It does not include browser evidence either.++## Automated browser evidenceAfter delivery, inspect the exact trusted HTML without rerendering or modifyingit:@@ -32,13 +38,23 @@ measures light-theme containment at 1440×900, 1600×1000, 1920×1080, and2048×1320, then captures light/dark screenshots at 1440×900 and 2048×1320. Itwrites four PNG sidecars, one relative-path HTML contact sheet, and one JSONreceipt beside the artifact. The receipt binds the source artifact SHA-256 and-byte count, records READ plus Still runtime state, and always reports-`visualReview: "pending"`; automated evidence cannot claim perceptual review.+byte count, identifies `evidenceKind: "automated-browser"`, records READ plus+Still runtime state, and always reports `visualReview: "pending"`; automated+browser evidence cannot claim perceptual review.++`browser_evidence` in the handoff records only the outcome of this automated command:-Exit 0 means every containment measurement and capture passed. Exit 1 means an-overflow or capture failure. Exit 2 means Chrome/Chromium was unavailable and-the receipt status is `skipped`. Failed or skipped capture runs remove stale+- `passed` maps from exit 0 and receipt `status: "pass"` only after every required measurement and capture completes and passes.+- `failed` maps from exit 1 and receipt `status: "fail"` when the inspection finds a defect, the command fails, or a runtime/capture error leaves the evidence incomplete.+- `skipped` maps only from exit 2 and receipt `status: "skipped"` when Chrome/Chromium is unavailable and the inspection does not run.++Runtime or capture failures leave incomplete evidence and must not be normalized to `skipped`. Failed or skipped capture runs remove staleimage/contact-sheet sidecars rather than presenting prior evidence as current.+They do not invalidate an already successful deterministic delivery, and they+do not turn a perceptual visual review into passed or failed. Retry an+environmental failure through the supported command in a browser-capable+execution context when practical. Keep the packaged transport unchanged unless+the failure reproduces through that seam in a capable environment.## Optional opening@@ -60,10 +76,12 @@ Never start it by default. Do not use it for CI, unattended agents, remote shari## Perceptual delivery gate-Automated validation cannot prove visual polish. After deterministic delivery, inspect the actual HTML in a capable browser or render a screenshot with an image reader. Check both themes when changed, the default READ view, line crossings/corridors, label masks, node/card fit, focus/search/passport closure, and export cleanliness.+Automated validation and browser evidence cannot prove visual polish. After deterministic delivery, inspect the actual HTML in a capable browser or render the evidence screenshots with an image reader. Check both themes when changed, the default READ view, line crossings/corridors, label masks, node/card fit, focus/search/passport closure, and export cleanliness.For the default standalone desktop viewer, measure 1440×900, 1600×1000, and 1920×1080. When the artifact is intended for a large desktop display, also measure 2048×1320. A first-screen pass requires `document.documentElement.scrollWidth <= window.innerWidth` and `scrollHeight <= window.innerHeight` at every checked size. At the largest checked viewport, inspect the rendered composition for a conspicuous empty lower band: the main panel and necessary conclusion cards should use the available height as a balanced whole, not collapse into a shallow strip. If a desktop viewport overflows, repair the authored composition by removing only genuinely redundant content or compacting spacing before shrinking nodes, labels, or the main panel. Do not hide overflow, clip content, introduce an internal diagram scroller, or reduce node/label typography to make the measurement pass. Narrow/mobile containment may retain vertical page scrolling.+A manual browser record is supplementary to the automated status. Reproducing the same coverage requires all four exact viewport measurements, both endpoint themes, and an artifact-bound record of the inspected SHA-256 and byte count. It never changes `browser_evidence`: when Chrome/Chromium is unavailable, that status remains `skipped` even when the manual browser record is complete and `visual_review: passed`; an automated `failed` result likewise remains `failed`. An unconstrained browser glance can support perceptual review only.+Report exactly one truthful status:- `visual_review: passed` — only after inspecting the rendered artifact.@@ -84,8 +102,11 @@ output: /absolute/path/to/file.htmlspecification_sha256: <receipt value>artifact_sha256: <receipt value>validation: 9/9 showcase, 0 errors, 0 warnings+browser_evidence: passed|failed|skippedvisual_review: passed|skipped (image reader unavailable)|failedcorrection_rounds: 0|1|2```+Derive `browser_evidence` only from the latest artifact-bound `visual-check` receipt. Record any manual browser work separately with its artifact binding, viewport/theme scope, and observations; never use it or `visual_review` to overwrite the automated status.+Opening, preview status, Share Cards, and other viewer exports are not validation claims.diff --git a/archify/test/authoring-safety-contract.test.mjs b/archify/test/authoring-safety-contract.test.mjsindex 07a4fa7b..6c1d8430 100644--- a/archify/test/authoring-safety-contract.test.mjs+++ b/archify/test/authoring-safety-contract.test.mjs@@ -42,10 +42,13 @@ test('visual-check stays a pending sidecar receipt instead of a polish claim', (path.join(skillRoot, 'references', 'delivery-contract.md'),'utf8',);- for (const [name, source] of [['SKILL.md', skill], ['delivery contract', deliveryContract]]) {- assert.match(source, /visual-check <output\.html> --json/, name);- assert.match(source, /1440×900[\s\S]*1600×1000[\s\S]*1920×1080[\s\S]*2048×1320/, name);- assert.match(source, /visualReview: "pending"/, name);- assert.match(source, /never changes.*delivered|without (?:rerendering or )?modifying/i, name);- }+ assert.match(skill, /visual-check <output\.html> --json/);+ assert.match(skill, /automated browser evidence[\s\S]*perceptual visual review/i);+ 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, /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 7e3f5eda..8cf6198e 100644--- a/archify/test/cli.test.mjs+++ b/archify/test/cli.test.mjs@@ -243,11 +243,35 @@ test('cli: visual-check returns a skipped receipt with exit 2 when Chrome is unaassert.equal(result.status, 2, result.stderr);const receipt = JSON.parse(result.stdout);assert.equal(receipt.status, 'skipped');+ assert.equal(receipt.evidenceKind, 'automated-browser');assert.equal(receipt.visualReview, 'pending');assert.equal(receipt.chrome.status, 'unavailable');assert.equal(fs.existsSync(out.replace(/\.html$/, '.visual-check.json')), true);});+test('cli: visual-check describes human output as automated browser evidence, not visual approval', () => {+ const out = path.join(tmp, 'visual-check-browser-evidence.html');+ fs.writeFileSync(out, '<!doctype html><html><body>delivered</body></html>');+ const missingChrome = path.join(tmp, 'missing-browser-evidence-chrome');+ const result = run(['visual-check', out], {+ env: { ...process.env, ARCHIFY_CHROME: missingChrome },+ });++ assert.equal(result.status, 2, result.stderr);+ assert.match(result.stdout, /automated browser evidence skipped:/i);+ assert.match(result.stdout, /perceptual visual review pending/i);+ assert.doesNotMatch(result.stdout, /^visual-check skipped:/m);+});++test('cli: visual-check keeps automated and perceptual claims separate on input failure', () => {+ const result = run(['visual-check', path.join(tmp, 'missing-browser-evidence.html')]);++ assert.equal(result.status, 1);+ assert.match(result.stderr, /automated browser evidence failed:/i);+ assert.match(result.stderr, /perceptual visual review pending/i);+ assert.doesNotMatch(result.stderr, /^visual-check failed:/m);+});+test('cli: deliver atomically writes a checked artifact and structured receipt', () => {const out = path.join(tmp, 'delivered-workflow.html');const input = path.join(skillRoot, 'examples/agent-tool-call.workflow.json');diff --git a/archify/test/delivery-contract.test.mjs b/archify/test/delivery-contract.test.mjsindex f05a9daa..e280d0bf 100644--- a/archify/test/delivery-contract.test.mjs+++ b/archify/test/delivery-contract.test.mjs@@ -9,6 +9,7 @@ const skill = readFileSync(path.join(here, '..', 'SKILL.md'), 'utf8');const delivery = readFileSync(path.join(here, '..', 'references', 'delivery-contract.md'), 'utf8');test('skill requires a bounded and truthful perceptual delivery receipt', () => {+ assert.match(delivery, /browser_evidence: passed\|failed\|skipped/);assert.match(delivery, /visual_review: passed/);assert.match(delivery, /visual_review: skipped \(image reader unavailable\)/);assert.match(delivery, /correction_rounds: [0-2]/);@@ -16,6 +17,25 @@ test('skill requires a bounded and truthful perceptual delivery receipt', () =>assert.match(delivery, /never report `visual_review: passed` without inspecting/i);});+test('skill keeps deterministic delivery, automated browser evidence, and perceptual review distinct', () => {+ for (const [name, source] of [['SKILL.md', skill], ['delivery contract', delivery]]) {+ assert.match(source, /deliver[\s\S]*deterministic/i, name);+ assert.match(source, /visual-check[\s\S]*automated browser evidence/i, name);+ assert.match(source, /human|perceptual visual review/i, name);+ }+ assert.match(delivery, /manual browser record[\s\S]*all four exact viewport measurements, both endpoint themes, and an artifact-bound record/i);+});++test('handoff browser evidence mirrors only the automated visual-check outcome', () => {+ assert.match(delivery, /`browser_evidence`[\s\S]*records only the outcome of this automated command/i);+ assert.match(delivery, /`passed`[\s\S]*exit 0[\s\S]*receipt `status: "pass"`/i);+ assert.match(delivery, /`failed`[\s\S]*exit 1[\s\S]*receipt `status: "fail"`/i);+ assert.match(delivery, /`skipped`[\s\S]*exit 2[\s\S]*receipt `status: "skipped"`/i);+ assert.match(delivery, /runtime or capture failures[\s\S]*must not be normalized to `skipped`/i);+ assert.match(delivery, /remains `skipped` even when[\s\S]*`visual_review: passed`/i);+ assert.match(delivery, /manual browser record[\s\S]*never changes `browser_evidence`/i);+});+test('skill uses atomic verified delivery for the final artifact', () => {assert.match(delivery, /archify\.mjs deliver <type>/);assert.match(delivery, /same-directory candidate/i);diff --git a/archify/test/visual-check.test.mjs b/archify/test/visual-check.test.mjsindex 62127ec6..2f488144 100644--- a/archify/test/visual-check.test.mjs+++ b/archify/test/visual-check.test.mjs@@ -179,6 +179,7 @@ test('visual-check records four containment viewports and four endpoint theme caassert.equal(result.exitCode, 0);assert.equal(result.receipt.status, 'pass');+ assert.equal(result.receipt.evidenceKind, 'automated-browser');assert.deepEqual(result.receipt.diagnostics, []);assert.equal(result.receipt.visualReview, 'pending');assert.equal(result.receipt.viewerChrome.status, 'pass');@@ -201,6 +202,8 @@ test('visual-check records four containment viewports and four endpoint theme caassert.equal(fs.existsSync(outputs.contactSheet), true);assert.equal(outputs.screenshots.every((entry) => fs.existsSync(entry.path)), true);const contactSheet = fs.readFileSync(outputs.contactSheet, 'utf8');+ assert.match(contactSheet, /Automated browser evidence/);+ assert.match(contactSheet, /perceptual visual review pending/);for (const screenshot of outputs.screenshots) {assert.match(contactSheet, new RegExp(path.basename(screenshot.path).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));assert.doesNotMatch(contactSheet, new RegExp(screenshot.path.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));diff --git a/docs/authoring-cookbook.md b/docs/authoring-cookbook.mdindex 71a0495b..c680bf15 100644--- a/docs/authoring-cookbook.md+++ b/docs/authoring-cookbook.md@@ -97,10 +97,12 @@ node bin/archify.mjs compare architecture base.json head.json \## 6. Inspect the exact final file-The deterministic checks do not prove visual polish. Open the exact delivered HTML in a browser, or collect automated containment evidence when Chrome or Chromium is available:+The deterministic checks do not exercise the Viewer in a browser. Collect automated browser evidence from the exact delivered HTML when Chrome or Chromium is available:```bashnode bin/archify.mjs visual-check web-app.html --json```-Use the [delivery contract](../archify/references/delivery-contract.md) for the required visual-review status and handoff fields. The [Skill contract](../archify/SKILL.md) explains the authoring invariants and the bounded repair loop.+This receipt measures bounded runtime behavior; it does not approve perceptual polish. Inspect the HTML or generated screenshots separately. Follow the [delivery contract](../archify/references/delivery-contract.md) when recording supplementary manual browser work; an unconstrained glance supports only perceptual review.++Use the delivery contract for the canonical browser-evidence coverage, artifact binding, visual-review status, and handoff fields. The [Skill contract](../archify/SKILL.md) explains the authoring invariants and the bounded repair loop.diff --git a/docs/authoring-cookbook.zh-CN.md b/docs/authoring-cookbook.zh-CN.mdindex cdef4b32..c9969c13 100644--- a/docs/authoring-cookbook.zh-CN.md+++ b/docs/authoring-cookbook.zh-CN.md@@ -97,10 +97,12 @@ node bin/archify.mjs compare architecture base.json head.json \## 6. 检查最终文件-确定性校验不能证明视觉效果。请在浏览器中打开刚刚交付的 HTML;如果环境有 Chrome 或 Chromium,也可以收集自动化的边界证据:+确定性校验不会在真实浏览器中运行 Viewer。如果环境有 Chrome 或 Chromium,请对刚刚交付的 HTML 收集自动化浏览器证据:```bashnode bin/archify.mjs visual-check web-app.html --json```-视觉复核状态和交付回执字段请参阅 [交付契约](../archify/references/delivery-contract.md)。编图不变量和有上限的修复循环请参阅 [Skill 契约](../archify/SKILL.md)。+这份回执只证明有限范围内的运行时表现,并不批准视觉质量。仍需单独检查 HTML 或生成的截图。记录补充性的手工浏览器工作时必须遵循[交付契约](../archify/references/delivery-contract.md);不受约束的目检只影响视觉复核结论。++自动化浏览器证据的规范覆盖、成品绑定、视觉复核状态和交付回执字段请参阅交付契约。编图不变量和有上限的修复循环请参阅 [Skill 契约](../archify/SKILL.md)。