@mmerterden/multi-agent-pipeline 16.23.0 → 16.25.0

package/CHANGELOG.md

@@ -16,6 +16,52 @@ Internal file-layout changes that don't affect the slash-command surface are sti
 
 ## [Unreleased]
 
+## [16.25.0] - 2026-09-09
+
+### Added
+
+- **`features/design-conformance.md` - the component walk, ported as doctrine rather than as a tool.** An upstream corporate screen-QA skill landed with a catalog worth having, and the pipeline already owns this problem in `/multi-agent:design-check`. Copying the skill would have produced a second design auditor that drifts from the first, so what came across is the part that is portable: the catalog and the three mechanisms that turn "I looked at it" into a countable result.
+
+  **Enumerate first.** Build the component inventory once, before any comparison, with elements nested inside buttons, fields and cards exploded into their own rows - an inventory built by kind drops a button silently, and with it the button height and its label. Then fill every cell: a blank one is a fail-to-verify, never a pass.
+
+  **Measure, never read the token.** A `[MEASURE]` item compares the design against measured pixels or the resolved code value, never against the design tool's node box or the implementation's own layout token. The token is the thing under test; comparing it against itself is how a 48pt field ships against a 56pt design with every check green.
+
+  **Converge per component.** One pass catches roughly one defect on a component - the wrong font, and not that same label's wrong colour and inset. Each component is re-checked until two consecutive attempts find nothing new, capped at attempt 8 with a `did-not-converge` warning. The screen is done when every component converged, not when the walk reached the bottom.
+
+  Plus the four scope tags (`[MEASURE]` / `[CAPTURE+]` / `[A11Y]` / `[DYNAMIC]`, and a `[DYNAMIC]` item may never be silently passed), the 30 rule groups, and the bidirectional presence gate - which finds not only what the design has and the implementation lacks, but the neutral decoration the implementation adds that a one-directional colour comparison cannot see.
+
+### Changed
+
+- **`design-check` no longer halts on a module without mock support.** The mock gate gains a snapshot lane: a screen that can be rendered from its own view model is auditable even when nothing can toggle a variant at runtime. The trade is stated rather than hidden - snapshots reach modules mocks cannot, and cannot flip an in-app variant - and a declined or impossible snapshot still halts rather than fabricating a comparison.
+
+- **The report says what it did not check.** The per-variant record gains `walk`: how many components were inventoried, how many converged, which ones hit the cap, and every `[DYNAMIC]` / `[CAPTURE+]` item that was not run, with its reason. An empty not-verified list on a run that never captured a dark or mirrored pass is a false clean, so the skip is listed instead.
+
+- **`derivedSkillSources` records what was reviewed and refused, not only what was taken.** New `derivationNote`, `excluded` and `notDerived` fields. `tools/openapi-regen` is marked deliberately-not-derived at 0.45.0 with its reason: the skill's value is being a driver around three named scripts in one repo, so renaming its brand words leaves a skill pointing at scripts nobody else has. Without that record, every drift review rediscovers the same candidate and re-argues it.
+
+- **`smoke-design-conformance.sh`** - 26 checks. Half of them guard the doctrine against being trimmed back into a glance; the other half name the project assets that must never arrive: a vendored colour catalog carrying cabin-class names, a typography catalog carrying licensed font families, product screen names, upstream script names. Those leak by content and carry no brand word, so a gate that greps for a company name would pass them.
+
+## [16.24.0] - 2026-09-09
+
+### Added
+
+- **A UI fix now carries its picture.** Three changed files in a diff do not tell a reviewer what was wrong, and they do not tell a tester what to look for. When `taskType` is `bugfix` and a UI file changed, the run produces a before/after pair; when the work is design (a `component` task, a Figma reference, or a UI file that did not exist before), it produces the after. The verdict comes from `taskType` plus the changed-file list, mechanically, not from the model's reading of the task - the UI-file test is per stack and written down.
+
+  **Before is the reporter's screenshot, or nothing.** Rebuilding the pre-fix state to photograph it costs a second build and a second launch on every UI bug, to recreate evidence the reporter usually attached already. So Phase 0 keeps the issue's own image attachments and that is the whole of it; no image on the ticket is a recorded gap, not a search.
+
+  **After is captured in Phase 3, not Phase 5.** Phase 5 is the natural home - the simulator is already up - and it is dropped by every `autopilot` and `--local` entry, so a capture living only there produces nothing for exactly the runs nobody watched. It happens instead right after the build+test gate goes green, which is in every mode's phase set. `capture-evidence.sh` owns the naming, cleans the status bar (two shots of one screen otherwise differ by the clock, which makes every "after" look like a change) and downscales to 1242px.
+
+- **The flow video, in three tiers, so no repo is excluded by not having a test target.** Tier 1 runs the repo's own XCUITest/Espresso target when it can be seeded with test data - the most faithful record, and it is a test that already runs in CI. Tier 2 drives the flow with `agent_run_steps` and records with `ios_record_video` / `android_record_screen`, needing nothing but a launchable build. Tier 3 is the honest skip for a library or a backend, with the reason recorded. The flow itself comes from the ticket when someone wrote one there, and from the Phase 5 test scenarios otherwise: human-written beats generated, the same rule the before follows.
+
+- **Where they land.** The artefacts are Jira attachments. The Phase 7 comment renders them _inside_ its existing sections rather than adding a fourth - the section order is fixed and the contract says so - with the before/after thumbnails under the work summary and the flow video under the scenario it demonstrates. The PR body gains a `visuals` section that names the filenames and the ticket, deliberately not the URLs: a Jira attachment URL is auth-gated and renders as a broken image for anyone reading the PR outside a Jira session.
+
+- **Degrading quality is allowed; dropping the artefact is not.** Jira's ceiling is an instance setting, so it is a preference (`visualEvidence.maxAttachmentMb`, default 10). Over it, a video re-encodes to 720p and a screenshot to JPEG q80; still over, the video becomes a four-frame contact sheet that says why. Phase 6 Step 3 blocks when a required artefact is neither attached nor explained - the gate is against silence, not against an honest "the ticket carries no image".
+
+- **`smoke-visual-evidence.sh`** - 32 checks, most of them about stated absence being as required as stated presence: both scripts refuse bad input rather than guessing, the size ladder never returns an empty path, all four phases act, both renderers know where pictures go, the schemas declare the fields, and no ref re-implements the attachment POST.
+
+### Changed
+
+- **One Jira uploader instead of two.** `generate-issue.md` carried its own attachment `curl`; visual evidence would have been the second copy, and two copies is two places for `X-Atlassian-Token: no-check` to go missing - which fails as a 403 that reads like an auth problem. Both now call `jira-attach.sh`, which resolves host and token from prefs, keeps the token out of argv, and prints `<filename>\t<url>` per file.
+
 ## [16.23.0] - 2026-09-09
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmerterden/multi-agent-pipeline",
-  "version": "16.23.0",
+  "version": "16.25.0",
   "description": "8-phase AI development pipeline with full orchestration on Claude Code, Copilot CLI and Codex CLI. Analysis, planning, TDD, CLI-aware parallel review with consensus surfacing + Fable triage, default-FAIL evidence gates, secret + intent guards, per-phase cost ledger, persistent learnings memory, wiki generation, commit automation. Token-preserving uninstall.",
   "type": "module",
   "main": "index.js",

package/pipeline/commands/multi-agent/design-check/SKILL.md

@@ -50,7 +50,7 @@ Phase 4: Report         → coverage gate + assemble + export HTML + PDF (+ Conf
 
 - **iOS**: Xcode + an available Simulator. **Android**: Android SDK + a running emulator / device.
 - **MCP**: the `multi-agent-toolkit` MCP server (>= 2.8.0, for `design_scenario_inventory`, the `design_report` coverage gate, and `design_visual_compare` region alignment). The Figma MCP (`mcp__claude_ai_Figma__*`) must be authenticated - the user supplies the Figma URL.
-- The selected module must support a **mock mode** (Phase 0 gate decides this). No mock support → the command halts.
+- The selected module must be auditable: a **mock mode** (preferred - it can toggle variants) or a **snapshot capture** of the screen's view model. Phase 0 decides which. Neither → the command halts.
 
 ## Phase Tracker Contract (mandatory)
 
@@ -112,7 +112,7 @@ for l in sys.stdin:
      extra_keys: <design-check-config mock.keys, if any> })
    ```
    Branch on `supported`:
-   - **`false`** → **HALT**. Show `reason` + that no runtime mock switch / launchable app / mock fixtures were found. Tell the user this module cannot be audited by design-check and stop. Do not fabricate a comparison.
+   - **`false`** → try the **snapshot lane** before halting: a screen renderable from its own view model (filled, flow-advanced, no backend) is auditable without a runtime mock switch. Ask via `AskUserQuestion`, persist `state.designCheck.captureLane = "snapshot"`. State the trade: snapshots reach modules mocks cannot and cannot flip an in-app variant, so the target set is whatever the view model can be built into. Declined or not renderable → **HALT** with `reason`. Never fabricate a comparison.
    - **`"debug-only"`** → surface an `AskUserQuestion` warning: mocks are compiled into the Debug build via `#if DEBUG` DI, so **variants cannot be toggled at launch** - only the default Debug state is comparable. Options (label + description in `outputLanguage`): option 1 semantically "Continue"  -  audit the single default Debug state only; option 2 semantically "Cancel"  -  stop.
    - **`true`** → continue. Persist `state.designCheck.mock = <detect result>` (mechanism, activation, variantsHint, evidence).
 5. **SCENARIO INVENTORY (this is the audit's target set)**:
@@ -170,6 +170,10 @@ Persist the variant list + spec + PNG paths to `state.designCheck.variants[]`.
 
 **This phase iterates `state.designCheck.scope.targetIds`  -  a finite list decided in Phase 0. It ends when every id is resolved, not when the UI stops offering new taps.** Tap-walking alone cannot reach a state that needs a different launch argument, a different scenario case, or a typed scenario code, which is exactly how a module's error / edge states go missing.
 
+### 3.0 What every capture is compared against
+
+**Read `$HOME/.claude/multi-agent-refs/features/design-conformance.md` before the first compare.** It owns the per-component catalog (30 groups), the scope tags, and the three rules that decide whether this phase produced a result or an impression: enumerate first (a blank cell is a fail-to-verify), measure never the token, and converge per component (two consecutive clean attempts, cap 8). The screen is done when every component converged - not when the walk reached the bottom.
+
 ### 3.1 Drive the inventory's plan, batch by batch
 
 **Follow `inventory.plan`, filtered to the scoped ids.** Each batch is one launch: the batch's relaunch target opens a screen, and every in-app target for that same screen is then flipped while the app is already sitting there. Driving the plan is what makes full coverage affordable - target-by-target relaunching is what made earlier runs give up a third of the way in.
@@ -260,8 +264,13 @@ Before leaving this phase, compare `covered.length + skipped.length` against `sc
                  truncatedInventory: <inventory.truncated>,
                  floor: <config coverage.floor, optional> },
      variants: [ { name, figmaNodeId, perceptualPct, passed, compareSize, liveSize,
-                   images, findings, fixPrompt, componentRefs } ] }
+                   images, findings, fixPrompt, componentRefs,
+                   walk: { components: <inventoried>, converged: <count>,
+                           didNotConverge: [ { component, attempts } ],
+                           notVerified: [ { item, tag, reason } ] } } ] }
    ```
+
+   `walk` separates a checked screen from a viewed one. An empty `notVerified` on a run that never captured a dark or mirrored pass is a false clean - list the skip. Field definitions: `features/design-conformance.md`.
    Pass **ids**, not counts: the engine then names each unaccounted target in the report instead of printing an anonymous tally. `compareSize` and `liveSize` come straight from the `design_visual_compare` result.
 3. **Render + export**:
    ```

package/pipeline/multi-agent-refs/channels/jira.md

@@ -20,6 +20,13 @@ Every Jira comment posted by this adapter follows the same section order. Sectio
 
 **`summary`**  -  2-5 sentences in `outputLanguage`. What changed, why, and the user-visible impact. No "we", no marketing tone. Past tense (the work is done at the time the comment goes up).
 
+**Visual evidence inside these two sections.** When `state.visualEvidence` carries artefacts, they render INSIDE `summary` and `test_scenarios` - never as a fourth section, which the fixed section order forbids. Upload first (`jira-attach.sh <issue> <file>...`), then reference by the returned filename:
+
+- `summary`, after its sentences: one line naming the pair in `outputLanguage` (`Düzeltme öncesi / Düzeltme sonrası`), then the thumbnails on the next line - `!<file>-before.png|thumbnail! !<file>-after.png|thumbnail!`.
+- `test_scenarios`, under the scenario the recording demonstrates: `!<file>-flow.mp4!` plus one line stating the tier used.
+
+A `gaps[]` entry prints its reason on the line where the artefact would have been (`Düzeltme öncesi: ticket'ta görsel yok`). Never an empty thumbnail, never a silent omission. Contract: `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
+
 **`test_scenarios`**  -  Given/When/Then numbered list. One scenario per acceptance criterion. The heading and scenario text are rendered in `outputLanguage` at write-time; the template itself (this file) shows the English skeleton:
 
 ```markdown

package/pipeline/multi-agent-refs/channels/pr.md

@@ -14,9 +14,10 @@ The PR description targets code reviewers  -  it stays technical. Every adapter
 | 2 | `changes` | `## Değişiklikler` | `## Changes` | always |
 | 3 | `architecture` | `## Mimari Kararlar` | `## Architecture Decisions` | when a non-trivial design choice was made |
 | 4 | `verification` | `## Doğrulama` | `## Verification` | always |
-| 5 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
-| 6 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
-| 7 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
+| 5 | `visuals` | `## Görsel Kanıt` | `## Visual Evidence` | when `state.visualEvidence.required` |
+| 6 | `risk` | `## Risk ve Güvenlik` | `## Risk and Security` | when `state.diffRisk.signals` carries a high-stakes signal (`security_path`, `migration`, `public_api`, `no_test_change`, `test_lines_removed`) |
+| 7 | `dependencies` | `## Bağımlılıklar` | `## Dependencies` | when deps added/removed/bumped |
+| 8 | `related` | `## İlgili` | `## Related` | always (Jira/issue ref; never `Closes/Fixes`) |
 
 ### Section content rules
 
@@ -62,6 +63,18 @@ Multi-repo PRs (one PR per repo) emit verification commands for that repo's stac
 - Rollback: feature flag <name> | git revert <sha> | none, and why
 ```
 
+**`visuals`**  -  only when `state.visualEvidence.required`. The images live on the Jira issue as attachments; this section exists so a reviewer opening the PR knows they are there and what each one shows. Filenames, not raw URLs - a Jira attachment URL is auth-gated and renders as a broken image for anyone reading the PR outside a Jira session.
+
+```markdown
+## Visual Evidence
+
+- Before: `<before-filename>` (attached to PROJ-XXXXX)
+- After: `<after-filename>` (attached to PROJ-XXXXX)
+- Flow video: `<flow-filename>`, tier <N> (attached to PROJ-XXXXX)
+```
+
+Every `state.visualEvidence.gaps[]` entry becomes its own line with the reason instead of a filename (`- Before: none  -  the ticket carries no image attachment`). Phase 6 Step 3 blocks on a required artefact that is neither listed nor explained. Contract: `$HOME/.claude/multi-agent-refs/features/visual-evidence.md`.
+
 **`dependencies`**  -  only when `Package.swift` / `Podfile` / `build.gradle` / `package.json` changed. Each entry: `package@old → new  -  reason`.
 
 **`related`**  -  flat list, plain text. Examples:

package/pipeline/multi-agent-refs/features/design-conformance.md

@@ -0,0 +1,312 @@
+# Design conformance  -  the component walk, and why a glance is not a pass
+
+A design audit that reads a screen top to bottom and reports what looks wrong
+finds about one defect per element: the wrong font on a label, and not that same
+label's wrong colour and wrong inset. This file is the catalog, and the three
+mechanisms that turn "I looked at it" into a countable result.
+
+Derived generically from an upstream corporate screen-QA tool (recorded in
+`derivedSkillSources`). The doctrine is portable. Its vendored design-token
+catalogs and product examples are not, and were not taken - section 7 says what
+replaces them.
+
+Consumers: `/multi-agent:design-check` (the runner), Phase 4 review when a UI
+diff is under review, and `features/visual-evidence.md` when a capture has to
+prove a fix. Gate: `smoke-design-conformance.sh`.
+
+## 1. Enumerate first, then fill every cell
+
+Do **not** walk by finding, and do not walk by headline. Build the inventory
+once, before any comparison:
+
+1. Enumerate every visible element of the design frame - every text, icon,
+   image, field, **button**, container. An element nested inside a button, field
+   or card is **its own row**, marked as nested (`> in <Button>`), never folded
+   into its parent.
+2. For each row, pre-fill the design side of every rule that applies and leave
+   the implementation side blank.
+3. Fill every blank. **A blank cell is a fail-to-verify, not a pass**, and it is
+   reported as one.
+
+The inventory is the coverage guarantee; the rule groups in section 5 are the
+per-cell recipe. A truncated inventory makes the denominator wrong, so it is
+reported as incomplete rather than as a clean percentage of a partial set.
+
+## 2. Measure, never read the token
+
+Every `[MEASURE]` item compares the design value against **measured pixels** in
+the render, or against the implementation's resolved value in code. Never
+against:
+
+- the design tool's node box, which includes invisible padding, or
+- the implementation's own layout token (a spacing or size constant, a
+  `.frame(height:)`, a Compose `Modifier.height`).
+
+The token is the thing under test. Measuring it against itself is how a 48pt
+field ships against a 56pt design with every check green. Button and field
+**height** are the two a token lies about most often, because internal padding
+and safe-area insets are not in it.
+
+## 3. Adaptive per-component convergence
+
+One pass over a component catches roughly one defect on it. So each component is
+re-checked until **two consecutive attempts find nothing new on it**.
+
+- Soft cap: reaching attempt 8 without two consecutive clean attempts stops that
+  component with a `did-not-converge` warning. There is never a ninth attempt.
+- A component with a font, a margin and a colour defect needs about three
+  finding attempts plus two clean ones. A correct component needs the two clean
+  attempts and nothing more.
+- The screen is done when **every** inventoried component has reached two
+  consecutive clean attempts or its cap with a warning. Not when the walk
+  reached the bottom.
+
+On a fixing run, each attempt that found something is fixed, re-captured, and
+its changes appended to one accumulating record, so the final artefact shows
+what each attempt changed rather than one undifferentiated diff.
+
+## 4. Scope tags  -  how an item is verified
+
+| Tag | Meaning |
+|---|---|
+| `[MEASURE]` | Verified in the primary capture: design value against measured pixels or resolved code value (section 2) |
+| `[CAPTURE+]` | Needs an extra capture pass - a second appearance, a mirrored layout, another width, another state. Skipping one is allowed only if the skip is logged |
+| `[A11Y]` | Accessibility lane: the platform accessibility tree (labels, element frames) plus contrast math |
+| `[DYNAMIC]` | Behavioural or temporal; a static capture cannot show it. Verify by driving the device, or report `not verified (dynamic)`. **Never silently pass a `[DYNAMIC]` item** |
+
+## 5. The catalog
+
+Run every applicable item for **every** component, then every gap through
+group 2, then the whole-screen passes (17, 21, 22, 24, 25). A check that was not
+run is a fail-to-verify.
+
+**1. Layout** `[MEASURE]` - x relative to container (never absolute y: the status
+bar offsets it), y relative to an in-content span, L/R/T/B margin to parent,
+centring, baseline alignment across a row, shared leading edge for siblings,
+label-left/value-right rows aligned at both ends, safe-area and system-bar
+clearance.
+
+> **Horizontal-inset lane** - the most-skipped one. For every element record
+> **both** sides of the leading inset: the design value and the measured
+> implementation value. One side filled is a fail-to-verify. Then two cheap
+> catches that need no per-element math: (a) **leading rail** - every loose,
+> non-carded text in a vertical group must share one leading x; if the
+> implementation puts a subtitle at the card's outer edge while the design insets
+> it, the rail is broken; (b) **sibling consistency** - when sibling screens
+> exist, diff the same element's inset across them; the outlier is usually the
+> bug. A different text-wrap point is a symptom of a different margin, not only
+> of a different font.
+
+**2. Spacing** `[MEASURE]` - outer margins, inner padding, screen edge margin
+(L=R symmetric), text-to-icon and icon-to-button and card-to-card and
+section-to-section gaps, list/grid/row spacing, the vertical gap **between**
+adjacent components (`next.y - (prev.y + prev.h)` against the stack spacing), and
+every gap resolving to a spacing token - an off-scale value is a deviation.
+
+**3. Size** `[MEASURE]` - width and height against the design (measured), min and
+max honoured, `[CAPTURE+]` responsive widths (group 17), `[A11Y]` interactive tap
+target at least 44x44pt on iOS / 48x48dp on Android, read from the accessibility
+tree rather than assumed.
+
+**4. Typography** `[MEASURE]` - family, size, weight, style, letter spacing, line
+height, paragraph spacing, alignment, text transform, text decoration, foreground
+colour, and truncation: ellipsis position, wrap and line limit matching the
+design.
+
+**5. Colours** `[MEASURE]` - background colour and opacity, gradient direction and
+stops, blur effects, foreground and secondary text, disabled and placeholder,
+border and divider and icon tint, brand accent and the status set
+(success/error/warning/info), field prefix or affix colour, and no hardcoded
+value: every colour resolves to a design token.
+
+**6. Border** `[MEASURE]` - width, corner radius (scalar and per-corner), style
+(solid vs dashed) and stroke alignment, colour and opacity.
+
+**7. Shadow / elevation** `[MEASURE]` - present or not, colour and opacity, blur
+radius, spread, x/y offset, and parity between the iOS shadow and the Android
+elevation for the same surface.
+
+**8. Shape** `[MEASURE]` - the drawn shape matches: radius about half the height
+means a pill; radius about half the smaller side with a square box means a
+circle.
+
+**9. Icons** `[MEASURE]` - correct icon and variant, **size measured from the
+rendered bounding box in both images**, never the node box or a size token,
+weight (line vs filled), colour and tint, padding and alignment and icon-to-text
+spacing, rotation and mirroring, rendering mode (a multicolour icon rendered as a
+single-tint template is a defect), and vector crispness.
+
+**10. Images** `[MEASURE]` - width and height, aspect ratio preserved, crop mode
+(fill vs fit), no distortion, no unintended blur and sufficient resolution,
+`[CAPTURE+]` placeholder and loading state.
+
+**11. Buttons** `[MEASURE]` - width and **measured height** (from the rendered
+fill rect, never a frame token), L/R/T/B spacing with L=R symmetry, the inner
+label's font/weight/colour/alignment **as its own row**, the inner icon
+(presence, size, colour, side, spacing), centring, fill and border and text
+colour for the current state, `[CAPTURE+]` the state set (group 21).
+
+> A button instance matches no text, icon or field kind, so an inventory built by
+> kind drops it silently - and with it the button height and its nested label.
+> The button is its own row and its children are exploded into their own rows.
+
+**12. Input fields** `[MEASURE]` - **measured height** (the rendered field box,
+never a frame or size token, because internal padding is not in the token),
+width, border, radius, placeholder text and its colour and alignment, background
+shade (read-only vs editable), prefix or affix and its colour, cursor and
+selection colour, character counter behaviour, `[CAPTURE+]` focus/error/disabled/
+filled states with the error message's colour, position and icon, `[DYNAMIC]`
+keyboard type.
+
+**13. Card** `[MEASURE]` - padding, radius, background, border, shadow, and
+content grouping: **sample the pixel behind every text block** - is it inside a
+card or bare on the page background? A design block in a card that the
+implementation renders bare (or the reverse) is a wrong-container finding
+(group 27) and is invisible to the text checks alone. Diff the design's container
+list one-to-one against the implementation's card wrappers; the implementation
+side is code-verifiable (inside a card helper vs placed bare in a stack with
+padding). Never infer this from a glance.
+
+**14. Lists** `[MEASURE]` - item height and internal padding, divider colour and
+thickness and insets, inter-item spacing, section header grouping and order,
+`[DYNAMIC]` scroll behaviour and lazy loading.
+
+**15. Navigation / header** `[MEASURE]` - bar height, title text and alignment,
+back affordance present and correct and mirrored under RTL, right-side actions
+present and ordered, bottom navigation items with icons, labels and selected
+state, `[DYNAMIC]` transition style.
+
+**16. Scroll** - `[DYNAMIC]` smooth scroll, bounce, overscroll, sticky header,
+scroll indicator; `[MEASURE]` the pinned header or footer position, which is the
+static part a capture can check.
+
+**17. Responsive** `[CAPTURE+]` - small, medium and large phone widths, tablet,
+landscape. No overflow, clipping or distortion at any of them. Re-capture per
+width rather than reasoning about it.
+
+**18. Alignment** `[MEASURE]` - horizontal, vertical, and baseline across a row.
+
+**19. Animation and motion** `[DYNAMIC]` - duration, curve, delay,
+fade/scale/slide/rotation, loading and skeleton animation, haptics. Verify by
+recording the device or report `not verified (dynamic)`.
+
+**20. Visibility** `[CAPTURE+]` - hidden vs visible renders correctly; collapse
+and expand states captured separately.
+
+**21. States** `[CAPTURE+]` per interactive component - default, pressed, focus,
+selected, active, disabled (colour, opacity, and genuinely not tappable),
+loading, empty, error, success.
+
+> **State fidelity gate**: the captured implementation must be in the exact state
+> the design frame depicts - the same toggle position, the same filled or empty
+> content, the same validation result. A capture in the wrong state is redone,
+> not compared.
+
+**22. Accessibility** `[A11Y]` - contrast at least 4.5:1 computed from sampled
+colours, tap target at least 44x44pt / 48x48dp from the accessibility tree,
+screen-reader label present and meaningful plus a meaningful hint, correct
+traits, an accessibility identifier on every interactive element, and a logical
+focus order. Whether to also audit scaled text sizes depends on the project: a
+design system with fixed, non-scaling typography makes a forced-scale render
+meaningless noise, so state which of the two the project is instead of assuming.
+
+**23. Platform** - iOS: safe area, notch and Dynamic Island clearance, home
+indicator, native navigation behaviour. Android: Material compliance, status and
+navigation bar treatment, ripple.
+
+**24. Dark appearance** `[CAPTURE+]` - capture a second image in the dark
+appearance and re-run groups 3 to 9 against the dark design frame. Background,
+text, icon, border, shadow, divider and gradient all adapt; no colour stuck at
+its light value; contrast preserved.
+
+**25. RTL and localization** - `[CAPTURE+]` a mirrored-locale capture: layout
+mirrored, leading and trailing swapped, directional icons flipped; `[MEASURE]` no
+hardcoded strings, every user-visible string from a localization key; a raw or
+undefined key rendered on screen (the design shows copy, the implementation shows
+`Screen.SomeKey`) reported in its own localization section; `[CAPTURE+]` a
+long-language pass with no clipping. Compare the string's *presence and shape*,
+not a translation of the same phrase against itself.
+
+**26. Content and data formatting** `[MEASURE]` - number grouping, currency symbol
+and position, date format, pluralization, and a long dynamic value that does not
+overflow. The value itself (a name, a number, a masked field) is not under test.
+
+**27. Component presence and order  -  hard gate** - the group the whole walk
+exists for.
+
+> Mechanical, not a glance. Number every element of the design list - text **and**
+> every icon, avatar, badge, **and every button** - and for each write its
+> implementation counterpart or `MISSING`. Report the count explicitly: "N design
+> components -> N implementation counterparts". "Complete" may not be concluded
+> without that list. A button and the label nested inside it are two presence
+> checks, not one.
+>
+> - **Icons are the most-missed presence class.** For every icon in the design
+>   list, locate it in the render by measuring its coloured bounding box. A design
+>   icon with roughly no matching pixels is a missing-element finding.
+> - **Recurse into nested blocks.** The gate applies to rows inside cards - masked
+>   rows, list rows, key/value rows - not only to top-level sections. "That card
+>   looks right" is not a pass.
+> - **Bidirectional, and code-side too.** Diff design-to-implementation
+>   (`MISSING`) *and* implementation-to-design (`EXTRA`). The most-missed extra is
+>   a neutral decoration the implementation adds - a trailing chevron, an
+>   underline, a strikethrough - which a colour-based, one-directional comparison
+>   cannot see. Diff the implementation's explicit decoration modifiers against
+>   the design's own decoration nodes, independently of the string.
+> - **A localization gap does not short-circuit this gate.** Raw keys are one
+>   finding; presence, icon, decoration and structure checks still run, because
+>   they read code and spec rather than the rendered string.
+
+Findings: `MISSING` · `EXTRA` · `MISSING-BETWEEN` (dropped from the middle of the
+sequence) · `REORDERED` · `WRONG-STATE` · `WRONG-CONTAINER` (present but grouped
+differently, loose vs carded).
+
+**28. Keyboard and input behaviour** `[DYNAMIC]` - keyboard avoidance with the
+active field not covered, dismiss behaviour, and return/next moving to the
+correct field.
+
+**29. Analytics** - out of visual scope; checked only when the spec requires it.
+
+**30. Cross-check matrix** - per component confirm x, y, w, h, the four margins,
+the four paddings, font family/size/weight, line height, letter spacing, text
+colour, background colour, border width/radius/colour, shadow, opacity, icon
+size/colour/position, image size/crop, divider, alignment, responsive, state,
+animation, safe area, and overflow. **Mark only deviations** on the image;
+matches belong in the report text.
+
+## 6. Output
+
+Mark only problems on the image, with thin lines. Everything else goes in the
+report, whose section keys are stable and whose prose follows `outputLanguage`:
+
+| Key | Content |
+|---|---|
+| `deviations` | Numbered, each one a design value against the measured or coded implementation value |
+| `localization` | Raw keys, missing keys, hardcoded strings |
+| `matches` | What was checked and agreed |
+| `ignored` | What was deliberately out of scope, with the reason |
+| `not_verified` | **Every** `[DYNAMIC]` and `[CAPTURE+]` item that was not run, so the coverage gap is explicit rather than absent |
+
+Each finding is `[what] + [why] + [how]` with `file:line` wherever the
+implementation side is code-resolvable. A finding without a file reference is
+still a finding; a finding without a "how" is a complaint.
+
+## 7. What a token catalog is, and why none ships here
+
+Comparing typography and colour exactly needs the project's own catalogs - the
+resolved name, size, weight and line height of each typography style, and the
+resolved value of each colour token. Those are **project assets**, not pipeline
+content: they carry brand colours, licensed font names and product vocabulary.
+
+So this contract defines the *interface*, never the data. The runner resolves
+catalogs in this order and states which one it used:
+
+1. A path in preferences (`designCheck.tokenCatalogs`), when the project exports
+   them.
+2. Generated from the repo's own token definitions at run time.
+3. Neither available -> typography and colour items degrade from `[MEASURE]` to
+   sampled-pixel comparison, and the report says so. They are not silently
+   passed.
+
+A vendored catalog inside the pipeline would be one project's design system
+shipped to every other project: wrong for all of them, and stale for its owner.

package/pipeline/multi-agent-refs/features/visual-evidence.md

@@ -0,0 +1,172 @@
+# Visual evidence  -  before/after screenshots and the UI flow video
+
+A UI fix that reads as three changed files in a diff is not reviewable. The
+reviewer cannot see what was wrong, and the tester cannot see what to look for.
+This contract makes the pipeline carry the picture: the state the reporter saw,
+the state the fix produces, and where possible a recording of the flow running.
+
+The artefacts live as **Jira attachments** and are referenced from two places -
+the Phase 7 Jira comment, where the picture belongs next to the work summary and
+the test scenarios, and the PR body, which tells the reviewer they exist.
+
+Consumers: Phase 3 (capture), Phase 5 (video, preferred host), Phase 6 (blocker),
+`channels/jira.md` and `channels/pr.md` (render). Gate: `smoke-visual-evidence.sh`.
+
+## 1. When it is required
+
+Decided mechanically from `taskType` plus the changed-file list, never from the
+model's reading of the task. A file counts as UI by stack:
+
+| Stack | UI file test |
+|---|---|
+| iOS | `.swift` declaring `: View`, `: ViewController`, or under a `Views/` path |
+| Android | `.kt` with `@Composable`, or declaring `: Activity` / `: Fragment` |
+| Web | `.tsx` / `.jsx` / `.vue` / `.svelte` |
+
+| Case | Before | After | Video |
+|---|---|---|---|
+| `taskType` is `bugfix` AND a UI file changed | required | required | when a tier allows |
+| Design work: `taskType` is `component`, or Figma was referenced, or a UI file was **added** | not applicable | required | when a tier allows |
+| Anything else | - | - | - |
+
+`state.visualEvidence.required` records the verdict and which rule produced it.
+Nothing about this section is optional-by-omission: when it is required and an
+artefact is absent, the absence is written down with its reason (section 5).
+
+## 2. Before  -  the reporter's screenshot, or nothing
+
+**The pipeline does not build the old state to photograph it.** Reproducing a
+pre-fix screen costs a second build and a second launch on every UI bug, to
+recreate evidence the reporter has usually already attached.
+
+So: Phase 0 already fetches the issue. Any image attachment on it (`.png`,
+`.jpg`, `.jpeg`, `.gif`, `.heic`) is downloaded to `$WORKTREE/.pipeline/evidence/`
+and recorded as `state.visualEvidence.before[]`. More than one is kept - a bug
+reported on two platforms has two.
+
+No image on the ticket means no "before". Record the gap
+(`before_missing: "ticket carries no image attachment"`) and continue. The
+section still renders, saying so.
+
+## 3. After  -  Phase 3, not Phase 5
+
+Phase 5 is the natural home: the simulator is already up. It is also **dropped by
+every `autopilot` and `--local` entry** (`phase-5-test.md` TLDR), so a capture
+that lives only there produces nothing for unattended runs - which are exactly
+the runs where nobody watched the screen.
+
+The capture therefore happens in **Phase 3, after the build+test gate passes**,
+which is in every mode's phase set. Phase 5 may add richer evidence on top; it is
+never the only source.
+
+```bash
+bash $HOME/.claude/scripts/capture-evidence.sh after \
+  --task "$TASK_ID" --platform "$PLATFORM" --label "<screen-slug>"
+```
+
+The script boots the device if needed, launches the built app, cleans the status
+bar (`ios_status_bar preset:clean` / the Android equivalent) so the frame carries
+no clock, carrier or battery noise, captures at device resolution, downscales to
+at most 1242px wide, and writes
+`$WORKTREE/.pipeline/evidence/<TASK_ID>-<label>-after.png`.
+
+A clean status bar is not cosmetic: without it two captures of the same screen
+differ by the clock, which makes every "after" look like a change.
+
+## 4. Video  -  three tiers, resolved once per repo
+
+The flow source, in order: a UI test flow written on the ticket wins; otherwise
+the Phase 5 test scenarios are the flow. Human-written beats generated, the same
+rule the "before" follows.
+
+The tier is probed once and stored in `state.visualEvidence.videoTier`:
+
+| Tier | Condition | Mechanism |
+|---|---|---|
+| 1 | The repo has a UI test target (XCUITest / Espresso) **and** it can be seeded with test data | Run that test, record the screen for its duration. Most faithful, and it is a test that already runs in CI |
+| 2 | A runnable build exists | Drive the flow with `mcp__multi-agent-toolkit__agent_run_steps` and record with `ios_record_video` / `android_record_screen`. **No test target needed** |
+| 3 | No runnable build (library / SPM package / backend) | Skip, with the reason recorded |
+
+Tier 2 is why "can every repo do this" answers yes in practice: any app that can
+be launched can be driven. A repo without a UI test target loses fidelity, not
+the recording.
+
+Preferred host is **Phase 5** - the device is already up and a human is present
+to confirm the flow is the right one. In a mode without Phase 5, tier 2 runs at
+the end of Phase 3 instead. Tier 1 always runs where the test runs.
+
+Duration is capped by `visualEvidence.maxVideoSeconds` (default 60), read via
+`capture-evidence.sh limits` so the number lives in one place rather than in two
+documents. A flow that needs longer is not a review artefact, it is a debugging
+session.
+
+`visualEvidence.enabled` turns the whole feature off - capture, upload, both
+render sections and the Phase 6 blocker with it.
+
+## 5. Size, and what happens when it does not fit
+
+Jira's attachment ceiling is an instance setting, so it is a preference:
+`visualEvidence.maxAttachmentMb` (default `10`).
+
+Order of attempts, each one recorded:
+
+1. Upload as captured.
+2. On `413` or a local size overrun: re-encode. Video drops to 720p and a lower
+   bitrate; PNG converts to JPEG at quality 80. **Reducing quality is allowed;
+   dropping the artefact is not.**
+3. Still over: replace the video with a four-frame contact sheet (start, two
+   midpoints, end) as a single PNG, and say in the caption that the recording
+   exceeded the limit.
+
+Never silently attach nothing.
+
+## 6. Rendering
+
+### Jira comment (`channels/jira.md`)
+
+The comment's section order is fixed and nothing may be inserted between the
+three sections. The evidence goes **inside** two of them:
+
+- `summary`  -  after the summary sentences, the before/after pair as a Jira wiki
+  thumbnail row: `!<TASK>-<label>-before.png|thumbnail! !<TASK>-<label>-after.png|thumbnail!`
+  preceded by one line naming which is which in `outputLanguage`
+  (`Düzeltme öncesi / Düzeltme sonrası`).
+- `test_scenarios`  -  the flow video attached under the scenario it demonstrates:
+  `!<TASK>-flow.mp4!`, one line stating the tier used.
+
+Missing artefacts print their reason on the same line, never an empty frame.
+
+### PR body (`channels/pr.md`)
+
+A `visuals` section whose job is to tell the reviewer the evidence exists and
+where it lives - the images themselves stay on the ticket:
+
+```markdown
+## Görsel Kanıt
+
+- Düzeltme öncesi: <before-filename> (PROJ-123 ekinde)
+- Düzeltme sonrası: <after-filename> (PROJ-123 ekinde)
+- Akış videosu: <flow-filename>, tier <N> (PROJ-123 ekinde)
+```
+
+## 7. Blocker
+
+When section 1 says required and `state.visualEvidence` carries neither an
+artefact nor a recorded reason for its absence, **Phase 6 Step 3 blocks** - the
+same shape as the `risk` section blocker. A recorded reason is enough to pass:
+the gate is against silence, not against an honest "no image on the ticket".
+
+## 8. State
+
+```json
+"visualEvidence": {
+  "required": true,
+  "requiredBy": "bugfix + ui-file-changed",
+  "platform": "ios",
+  "before": [{"file": "...", "source": "ticket", "jiraFilename": "...", "url": "..."}],
+  "after":  [{"file": "...", "capturedAt": "phase-3", "jiraFilename": "...", "url": "..."}],
+  "videoTier": 2,
+  "video": {"file": "...", "seconds": 41, "jiraFilename": "...", "url": "..."},
+  "gaps": [{"what": "before", "reason": "ticket carries no image attachment"}]
+}
+```