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
docs: distinguish machine receipts from visual acceptance
tt-a1i68d55002086f
diff --git a/archify.zip b/archify.zipindex 8cd14287..f7f4054b 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex dad24458..bf6a46fd 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -74,11 +74,11 @@ Read Mermaid for topology and meaning, then author fresh Archify JSON; do not meUse 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 handoff reports `visualReview: "not-requested"` and creates no screenshots.+`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. 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.-For recovery, the required order stays `deliver` → strict provenance `check` → `browser-check`. Run optional `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.+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.For workflow viewport overflow, read [Workflow viewport repair](references/authoring-contract.md#workflow-viewport-repair) before the next layout edit.diff --git a/archify/test/delivery-contract.test.mjs b/archify/test/delivery-contract.test.mjsindex 302e1475..eb59bc8d 100644--- a/archify/test/delivery-contract.test.mjs+++ b/archify/test/delivery-contract.test.mjs@@ -31,7 +31,7 @@ test('delivery contract describes the directory-wide physical delivery lock', ()const finalizeSection = delivery.match(/For the ordinary agent handoff path[\s\S]*?The individual commands remain authoritative/)?.[0] ?? '';const browserSection = delivery.match(/## Automated browser evidence[\s\S]*?## Optional capture evidence/)?.[0] ?? '';-const optionalReviewSection = delivery.match(/## Optional perceptual review[\s\S]*?## Handoff receipt/)?.[0] ?? '';+const perceptualReviewSection = delivery.match(/## Perceptual review[\s\S]*?## Handoff receipt/)?.[0] ?? '';test('ordinary handoff uses one deterministic finalizer without image capability', () => {assert.ok(skill.indexOf('## Existing candidate handoff') < skill.indexOf('## Fast authoring path'));@@ -73,20 +73,21 @@ test('strict provenance succeeds before either browser command', () => {const ordering = delivery.match(/Run strict `check` after `deliver` exits zero\.[\s\S]*?collecting new browser evidence\./)?.[0] ?? '';assert.match(ordering, /Run `browser-check` or optional\s+`visual-check` only after that strict check exits zero/i);assert.match(skill, /required order stays `deliver` → strict provenance `check` → `browser-check`/);- assert.match(skill, /Run optional `visual-check` only against a strict-provenance artifact/);+ assert.match(skill, /Run `visual-check` only against a strict-provenance artifact/);});-test('perceptual review is an explicit risk escalation with a bounded correction loop', () => {- assert.match(optionalReviewSection, /visual_review: not_requested/);- assert.match(optionalReviewSection, /user explicitly requests an aesthetic or visual review/i);- assert.match(optionalReviewSection, /template, renderer, or Viewer change/i);- assert.match(optionalReviewSection, /novel layout or browser diagnostic leaves low confidence/i);- assert.match(optionalReviewSection, /sampled audit or dogfood/i);- assert.match(optionalReviewSection, /run `visual-check`[\s\S]*contact sheet/i);- assert.match(optionalReviewSection, /never exceed two focused correction rounds/i);- assert.match(optionalReviewSection, /Never report\s+`visual_review: passed` without inspecting/i);+test('perceptual review covers fresh architectures and risk escalation with a bounded correction loop', () => {+ assert.match(perceptualReviewSection, /visual_review: not_requested/);+ assert.match(perceptualReviewSection, /Architecture is newly authored or its nodes have been repositioned/);+ 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);+ assert.match(perceptualReviewSection, /sampled audit or dogfood/i);+ assert.match(perceptualReviewSection, /run `visual-check`[\s\S]*contact sheet/i);+ assert.match(perceptualReviewSection, /never exceed two focused correction rounds/i);+ assert.match(perceptualReviewSection, /Never report\s+`visual_review: passed` without inspecting/i);assert.match(skill, /If perceptual review is unavailable, report that quality remains unverified/i);- assert.match(optionalReviewSection, /visualReviewRecommendation/);+ assert.match(perceptualReviewSection, /visualReviewRecommendation/);assert.match(delivery, /Open the HTML contact sheet in a browser or inspect the viewport PNGs/i);});