Skip to main content
Jira progress: loading…

VW-VV

Viroway Visual Verification

1. Purpose​

Prose specifications tolerate contradictions; drawings do not. A pipeline can be described in two different orders in two documents and both read fluently. It can only be drawn in one order. Rendering a specification into a spatial form forces every claim — sequence, ownership, contract, exit, boundary — into a position on a canvas, and positions cannot disagree quietly.

This specification therefore makes visualization a verification step, not an illustration step, in the ZAYAZ documentation lifecycle. A feature specification is not considered fully specified until it has been rendered from its own machine-readable data and the rendering has been reviewed against the prose by a second pair of eyes.

1.1. Evidence​

The requirement is grounded in findings from the first full visual pass over the TrustGate corpus (July 2026), during which rendering — not reading — surfaced:

  1. A pipeline-ordering conflict between the MIB and the Trust Scoring engine spec (Normalizer/Structure-Validation and Scoring/Policy pairs reversed). Both documents read correctly in isolation; the circuit board could only seat the chips in one order. Resolved by CTO ruling and MIB correction; now enforced as lint rule DL-101.
  2. A missing decision exit: the corrected MIB introduced REJECT as a fifth exit; every existing diagram showed four. The gap was visible the moment the exits were drawn as chips.
  3. A structural defect: one engine's Canonical Identity table was embedded inside its output-CSI table — invisible in reading flow, immediately visible when datasheet extraction produced an empty identity block. Now lint rule DL-201.
  4. Convention drift: four heading conventions for the same CSI sections, found because the extractor needed four patterns. Now lint rule DL-202.

None of these were found by reading. All were found by drawing. Each was cheap at spec stage and would have been expensive in a sprint.

2. The Principle: Render From Data, Never From Memory​

The verification power of a visualization comes entirely from where its content originates:

  • A diagram drawn from memory or prose illustrates what the author believes the spec says. It inherits the author's blind spots and verifies nothing.
  • A diagram built from the spec's extracted machine-readable fields (frontmatter, identity tables, CSI tables, pipeline sections) renders what the spec actually says. Every defect in the data becomes a defect in the picture — an empty block, an impossible ordering, a missing chip.

Rule of thumb, normative in §6: if the renderer needed a value that the spec did not provide, that is a spec defect, not a rendering problem. The renderer SHALL NOT invent, assume, or "fix" missing or conflicting values silently.

3. Required Visual Artifact per doc_type​

Each specification type has a canonical visual form, drawn from the shared grammar (§5). The artifact set below reuses the patterns established in the ZAYAZ Architecture Masters and is intended to generalize to every hub — TrustGate/Gatehouse is one subsystem among many; each future hub receives the same treatment with its own prefix.

doc_type / subjectRequired artifactContent extracted from
engine-specEngine datasheet — identity block ("part number"), input/output CSI pinouts with REQUIRED flags, canonical position strip, services consumedfrontmatter, Canonical Identity table, CSI tables, position section
hub / subsystem (MIB)Circuit board — contract buses (signal, config/policy, evidence rail, event), components seated on buses, no component-to-component arrowsMIB pipeline section, engine consumes/produces
pipeline / gated flowGatehouse view — ordered gate cards, all terminal exits drawn as distinct chipscanonical pipeline order, decision-exit enumeration
registry / catalogRegistry grid — one cell per artifact, class-coded, real semantic IDscatalog tables
scoring / metric modelWaterfall / corridor — dimension build-up, modifiers, thresholds as bands; or position/frontier/velocity corridorweight bundle, threshold table
federation / exchangeFederation lens — capability matrix per profile, sealed-package diagram over a consented edgefederation profile tables
conceptual / kernel modelObject graph — objects as nodes, named edges, invariants; interactive detail overlays where the model has per-object depthobject definitions, invariants, edge list

A new doc_type without an assigned visual form SHALL have one assigned (or explicitly waived with rationale) before its first document reaches approved.

4. The Visual Parity Review Protocol​

For every feature specification moving toward approval:

  1. Extract — pull the machine-readable fields from the spec. The corpus SHALL be lint-clean (VW-DL)[/key-zayaz-features/governance/viroway-docs-lint.mdx] before extraction; rendering a drifted corpus produces authoritative-looking pictures of contradictions.
  2. Render — build the required artifact from the extracted data only. Every gap or conflict the renderer hits is logged, not patched.
  3. Second-opinion walk — a reviewer who is not the spec's author (human reviewer or an AI reviewer session) walks the rendering against the prose, item by item: every pipeline position, every pin, every exit, every identity field. The walk asks one question repeatedly: does the drawing and the prose make the same claim?
  4. File — every discrepancy is filed as a spec defect against the document, before any implementation ticket is generated from it.
  5. Rule — conflicts between documents are escalated for an owner ruling (as with the July 2026 pipeline-order ruling), the losing document is corrected in place (VW-DL DL-301), and where the conflict class is general, it is encoded as a new lint rule (VW-DL §5.4).
  6. Record — the spec's frontmatter gains a visual_ref (link to the rendered artifact) and visual_review block (reviewer, date, findings count). Status may then advance.

4.1. Re-Render Triggers​

A completed visual review is invalidated — and the artifact SHALL be re-rendered and re-walked — when any of the following change: canonical pipeline order, decision exits, any CSI added/removed/renamed, identity fields, threshold or weight structure (not values), or federation capabilities. Prose-only edits (clarifications, typos) do not trigger re-render.

5. The Shared Visual Grammar​

All required artifacts use one grammar, so that a reviewer trained on one hub can walk any hub:

  • Solid is real; hollow or dashed is potential. Filled shapes are facts; outlined shapes are capacity, ceilings, or possibilities.
  • A vector is a trajectory. Arrows with direction and magnitude mean movement over time, nothing else.
  • Components meet only at contracts. Buses, ledgers, schedules, and signal contracts are drawn; component-to-component arrows are forbidden. A rendering that cannot be completed without such an arrow has found an architecture defect.
  • Every terminal outcome is drawn. Exits, rejections, and quarantines appear as distinct elements; an enumeration in prose that is not fully drawable is incomplete.
  • Identity is a part number. Every component's identity layers (EID / MEID / CMI or hub equivalents) are shown together and never merged.
  • Trust and tier colorings never share a palette. Distinct semantic families receive distinct color families.

The concrete token set (colors, type) is maintained in the Architecture Masters components page and MAY evolve; the grammar rules above are normative and stable.

6. Normative Rules​

  1. A specification with doc_type listed in §3 SHALL NOT advance to approved status without a completed visual parity review recorded in visual_ref / visual_review frontmatter.
  2. Required artifacts SHALL be built from extracted spec data. Renderers SHALL NOT invent, default, or silently repair missing or conflicting values; every such encounter SHALL be logged as a finding.
  3. The corpus SHALL be lint-clean (VW-DL, ERROR class) before extraction for a visual review.
  4. The parity walk SHALL be performed by a reviewer other than the spec's author. An AI reviewer session satisfies this requirement provided its findings are filed as reviewable records.
  5. Discrepancies found during the walk SHALL be filed as spec defects and resolved (or explicitly waived by the owner) before implementation tickets are generated from the document.
  6. Cross-document conflicts surfaced by rendering SHALL result in an owner ruling, an in-place correction, and — where generalizable — a new VW-DL Class B rule within one release cycle.
  7. The rendering surface (currently Figma) is documentation tooling, not a ZAYAZ component (per VW-DL §4). No runtime behavior SHALL depend on it, and the direction of data flow is one-way: specs → rendering.

NOTE: For best results send the files to cto@viroway.com. We use Claude Fable 5 or later and it is already set up to for this.

6.1. Proposed VW-DL Amendment​

To make the status gate machine-enforced, VW-DL gains:

RuleSeverityCheck
DL-106ERRORA document with status: approved and a §3-listed doc_type SHALL carry non-empty visual_ref and visual_review frontmatter

7. Frontmatter Additions​

# added to any §3-listed doc_type upon review completion
visual_ref: https://www.figma.com/design/<file>/<node>   # rendered artifact
visual_review:
  reviewer: <name or AI-session reference>
  date: 2026-07-10
  findings: 3
  findings_resolved: 3
  waived: 0

8. ZRR Ruleset Entry​

ruleset: ZRR-DOCS-002
invariant: no-approval-without-visual-parity
scope: all doc_types listed in VW-VV §3
enforcement: docs-lint DL-106 (ERROR) + review workflow
amendments: changes to the visual grammar (§5) or artifact mapping (§3)
  require CTO approval

Reading a specification checks that it is plausible. Drawing it checks that it is possible. This document makes the second check mandatory. Source of truth: Docusaurus.



GitHub RepoRequest for Change (RFC)
Last updated on by automation-bot