trunative 1.0.0

package/src/skills/flow/review.md

@@ -0,0 +1,186 @@
+# Review
+
+Runs after every build, on the code that was just written, and again on request over a finished screen. Reviewing your own output is the point: the build step optimizes for getting the screen working, and this step optimizes for finding where it fails in a hand.
+
+One grader, one scale, one set of rule ids. What changes between a run on a diff and a run on a screen is not the standard, it is how much of the screen was actually seen, and the report says so.
+
+## The scale
+
+Every rule in scope gets a number from 1 to 5. The same words on every rule, on every run, because a rule that invents its own wording for a 3 makes two runs incomparable.
+
+- **1**: broken. What the rule exists to prevent is on the screen and the person using the app meets it.
+- **3**: met on the ordinary path, and nothing beyond it was asked.
+- **5**: met on the ordinary path and on the edges the rule itself names, with the evidence to say so.
+- **2** and **4** are the gaps. A 2 is something in place that does not hold: met on one screen and dropped on the next, or met for the default case while the rule's own case is the exception. A 4 is a 5 with one thing outstanding.
+
+A **violation** is a 1 or a 2, and that is the whole of the gate: the build loop continues while any rule is at 1 or 2. Nothing at 3 or above blocks a build, which does not make it finished.
+
+Two answers that are not scores:
+
+- **`n/a`**, with the reason in the row: the feature does not exist here, the platform does not have it, or `STACK.md` records the exception. Not available for the nine rules under **Always in scope** in `SKILL.md`. An `n/a` written in a screen brief is a claim the brief's author made before the code existed, so it is checked here like any other claim, and it never arrives as an exemption. Exceptions accepted on purpose live in `STACK.md`, which is the only file that grants one.
+- **`unrun`**: the rule applied, nothing was checked, and the run knows it. A rule you did not check is never a pass.
+
+Anchors are not a curve. Most rules on a screen built with this skill land at 3 and 4, a 5 is earned by evidence rather than by the absence of a complaint, and a screen with no 1s and no 2s is a screen that ships, which is a lower bar than a good screen.
+
+## 1. Re-read the code
+
+Review the actual code, not your memory of writing it. Open the files that changed.
+
+After a build that is the diff. On request it is the screen: the widget, view or composable that renders it plus whatever it pushes and presents, opened on a device or a simulator.
+
+## 2. Scope and checklist
+
+The scope is every base file plus the extra files this screen touches, settled by your own pass over the Extra table in `SKILL.md` rather than by what the build says it opened. The nine always-in-scope rules sit inside the base files and are never `n/a`. Write the scope down before grading. A scope chosen once the scores are in is a scope chosen to flatter them.
+
+An identity the build had to settle because `DESIGN.md` did not carry one is part of the scope, not a note beside it. It is graded by `color-derived`, `type-face`, `layout-shape` and `icon-depicts`, against the five lines the build wrote, and a screen whose identity would fit any other product in the category scores a 1 on the first of them however clean the rest of the code is.
+
+Name the screen first, the same way build does, and derive the scope from the name. A build that named it wrong took the wrong files with it, and a review that inherits the build's list inherits the mistake. Where your pass reaches a file the build never opened, its rules are in scope all the same and every one of them is `unrun` until it is checked: a rule nobody looked at is not a rule that passed.
+
+A screen brief at `.trunative/screens/<name>.md` does not change that. Its `scope` is what the spec step decided and what the rubric was generated from, and it may widen your scope and never shrink it. Where your own pass reaches a file the brief left out, grade it and report the difference as drift.
+
+```sh
+npx trunative rubric --only forms --only search
+```
+
+Base is in every rubric. `--only` adds extras, by file stem, by rule prefix such as `form-`, or by a single rule id, and repeats. `--format=ids` prints the ids alone, which is what a diff against the previous run reads to catch a rename.
+
+The checklist is generated, never written by hand:
+
+- Do not add a row. A rule that should exist belongs in `heuristics/`, and the next run picks it up with no second edit.
+- Do not delete a row. A rule that does not apply is `n/a` with a reason, which is a different fact from a rule nobody looked at.
+- Do not grade a rule that is not on the checklist. An id that is not there was renamed or removed, and a score for it is a score for nothing.
+
+Each row carries the rule's own Check line, which is the criterion. Grade against that sentence, not against a memory of the heuristic. A row marked `[device]` is a rule the file cannot settle from the source, which decides the evidence in step 3.
+
+## 3. Grade
+
+Every row gets a score, one line of finding, and its evidence:
+
+- `source`: the code was read. The claim is about intent.
+- `device`: the screen was driven. The claim is about the app.
+- `source+device`: both, and they agreed. Where they disagree the device wins, and the disagreement is a finding.
+
+A rule the checklist prints `[device]` on may not take `source`: its own file has already said a diff cannot settle it, so a number from the source alone is a guess wearing a score. The paragraph that file closes its Check section with, printed under the group as `Not from a diff`, says why. Those rules are `device`, `source+device`, or `unrun`. A rule without the mark can be graded from the source, and is still worth seeing on a device.
+
+A screen is never closed on `source` alone. Render it, look at it, and keep the capture beside the report. What the file hides and the picture shows in a second: the last row of content sitting under a pinned bar, the primary action stranded in the middle of an empty frame, a hero occupying a third of the height and depicting nothing, placeholder text standing in as the content. None of that is arguable from code, and all of it is what a person sees first.
+
+<If stack="web">
+```sh
+chrome --headless --window-size=402,874 --screenshot=screen.png file:///absolute/path/screen.html
+```
+</If>
+
+<If stack="flutter,react-native,swiftui,compose">
+```sh
+xcrun simctl io booted screenshot screen.png   # iOS simulator
+adb exec-out screencap -p > screen.png         # Android emulator or device
+```
+</If>
+
+<If stack="other">
+Capture the running screen the way this platform captures one, and scroll to the end of the content before the capture.
+</If>
+
+Scroll to the end of the content before capturing, or the collision `layout-chrome` exists to catch stays hidden.
+
+When the app is running on a device, split the work in two and keep the halves apart, because a grader who has already read the measurements grades the measurements:
+
+**Judging.** Reads the source, drives the screen, and fills in every row.
+
+**Measuring.** Produces numbers and captures, no scores at all, each keyed to a rule id. Start with the one measurement that needs no device:
+
+```sh
+npx trunative detect lib/screens/checkout_screen.dart
+```
+
+It reads the files and answers the part of a `Check` line a file can settle, reporting per rule id. Three things follow from that and none of them is optional: every finding is `source` evidence, so it never settles a rule marked `[device]`; a finding is a place to look rather than a score; and its silence proves nothing, so a rule it did not answer stays with the grader. It exits 2 when it finds something, which is not a failure.
+
+Then the measurements that do need a device: both appearances on the narrowest and widest device class, the largest accessibility text step on the narrowest, hit area bounds read from the inspector rather than estimated from a screenshot, the primary flow completed with the screen reader on, the screen with the network off and after a process kill the system would have made itself, and real records rather than seed data, meaning a null, a zero, a long string, an old timestamp and an empty list.
+
+How the two are kept apart depends on the harness you are running in:
+
+<If agent="claude">
+Run them as sub-agents, spawned in one message so they work at the same time and neither reads the other's output.
+</If>
+
+<If agent="other">
+Run them as sub-agents when this harness has them, spawned so that neither reads the other's output. When it does not, finish the judging pass and record it, then measure.
+</If>
+
+Then reconcile: the judged score stands unless a measurement contradicts it, and every score a measurement moved is printed with both numbers. The report is one table, not one pass after the other. When they could not be kept apart, the report says so on its first line.
+
+## 4. The numbers
+
+The maximum is 5 times the number of rules actually scored from 1 to 5. Nothing else is in it.
+
+- The denominator is never the size of the scope. A scope of 74 rules with 9 `n/a` and 5 `unrun` scores out of 300, not out of 440.
+- Report coverage beside the total: scored, `n/a` and `unrun`, out of the scope. A run that skipped the device work does not come out ahead of one that did it.
+- Record which ids were `n/a` and which were `unrun`. A later comparison against a run that hid them is a comparison of two different measurements.
+
+Bands read off the percentage, since the maximum moves with the scope:
+
+| Percentage | Band |
+|---|---|
+| 90 and above | Nothing structural left. |
+| 75 to 89 | Solid, with named gaps. |
+| 60 to 74 | It works, and the edges do not. |
+| 40 to 59 | Structural work before polish. |
+| Under 40 | Not designed for a phone yet. |
+
+## 5. Report
+
+The report goes in the response, in this order:
+
+1. **Header.** What was reviewed, the scope, the total, the percentage, the band and the coverage.
+2. **The table.** Columns: rule, score, evidence, finding. Print every rule at 4 or below and every one of the always-in-scope nine, then one line per file for the rest: file, rules scored, average, lowest.
+3. **Violations.** Every rule at 1 or 2, ordered by what it costs the person using the app and not by how easy it is to fix. Each names the rule id, the file and line, what the user meets, and the fix. Say plainly when the screen is unusable one-handed, loses work on interruption, or has no failure state, and do not bury it under smaller findings.
+4. **Spec drift.** Only when the screen has a brief, and unscored. Each entry quotes what the brief says and what the code does: a hierarchy in a different order, a `primary_action` whose label is not the one on screen, a state declared and not implemented, a scope the brief left out. Where the divergence also breaks a rule, name the id that already scores it, such as `state-offline` for a declared state that is not there, and do not score it twice. Drift is a fact about two files disagreeing, and the moment it carries a number this file has two graders in it.
+5. **What moved.** Scores a measurement changed, with both numbers.
+
+If a violation is a deliberate exception recorded in `STACK.md`, it is `n/a` with that exception as the reason, not a 1 defended in prose.
+
+Name the element, say what it costs, give the fix. Nothing in the report is an invitation to look into something later.
+
+## 6. Record
+
+A run with nothing `unrun` is a complete measurement and gets archived. A run that left rules unchecked prints its table and stops here, naming the rules that blocked the archive, because a partial run in the history makes every later comparison lie.
+
+Write the report to `.trunative/review/<slug>-<YYYY-MM-DD-HHmm>.md`, one file per run, kept in version control. The slug comes from the primary file's project-relative path: lowercase it, replace every run of characters that is not a letter or a digit with a single hyphen, and drop a leading and trailing one, so `lib/screens/checkout_screen.dart` becomes `lib-screens-checkout-screen-dart`. It is computed the same way on every run and never invented, because the trend reads it.
+
+Frontmatter, machine readable:
+
+```yaml
+---
+target: lib/screens/checkout_screen.dart
+slug: lib-screens-checkout-screen-dart
+spec: .trunative/screens/checkout.md
+date: 2026-09-08T14:22
+skill: sha256:6f0a...
+scope: [touch, forms, states, layout, typography, colors, motion, accessibility]
+total: 236
+max: 300
+percent: 79
+scored: 60
+na: [pay-restore: no purchases on this screen, ads-report: no Android build]
+---
+```
+
+`skill` is the hash in `.trunative/skill.lock`. It says which set of rules produced the numbers, which is how a later run knows the rulebook moved under it. `spec` is the screen brief this run graded against, omitted when the screen has none, so a later comparison can tell a screen that changed from a screen whose declared intent changed.
+
+Then read the newest five archived runs with the same slug and print one line:
+
+> Trend for `lib-screens-checkout-screen-dart`: 61%, 74%, 79% (236/300 this run).
+
+The comparison is only honest when the measurement is the same, so name any of these that changed since the previous run, on the same line: the skill hash moved, so some of the difference is rules rather than the screen; the scope changed, and which files joined or left; or the `n/a` set changed, since a rule that was excused last time and scored now moved the total on its own. The scope may grow between runs and may not silently shrink: a later run covering fewer files is not a better run.
+
+First run: there is nothing to compare against. Say so in one line, name it the baseline, and name the file the next run will read.
+
+## 7. Loop
+
+- Any rule at 1 or 2: go back to `flow/build.md` with this report and fix them, then review again.
+- Drift where the code is right and the brief is stale: correct the brief and carry on. Drift where the brief is right and the code left the approved structure: that is hierarchy, actions, states or navigation moving without anyone deciding it, so go back to `flow/spec.md`, not to build.
+- Nothing below 3: stop. Report what was built, what was checked, what was excused and what was not seen.
+
+Two consecutive reviews finding the same violation means the fix is not working. Say so and ask the user, instead of looping a third time.
+
+Do not fix and grade in the same pass. A grader that edits the code it just graded has no second opinion left for the next run.

package/src/skills/flow/spec.md

@@ -0,0 +1,149 @@
+# Spec
+
+Settles what is on the screen before anything draws it. Runs between init and build, whenever the task establishes or changes structure.
+
+Structure is four things: hierarchy, actions, states, navigation. A new screen, a new component with state of its own, or a new flow settles all four at once, so it always comes through here: nothing is being changed because everything is being decided, and that is the maximum case rather than an exemption. An existing screen comes through when the task moves any of the four.
+
+The step ends with two things, and neither is optional: a wireframe rendered and looked at, and a question the user answered. A spec step that wrote a brief and went on to code did not run.
+
+```text
+"Build the login screen."             spec, new screen
+"Add a settings screen to the app."   spec, new screen
+"Move People above Recently Viewed."  spec
+"Add Google sign-in."                 spec
+"This screen has no empty state."     spec
+"Send the row to a detail screen."    spec
+
+"Make the button blue."               build
+"Four more points of padding."        build
+"The transition is too slow."         build
+"Rename the view model."              build
+```
+
+Write the verdict in one line before anything else, naming which of the four the task touches or naming that it touches none. A verdict nobody wrote is a step nobody ran, and it fails in one direction only: writing code is the attractor, so the unwritten answer is always "straight to build".
+
+The distinction is the whole economy of this step. A brief demanded for every cosmetic edit is ceremony people route around, and a brief skipped on a structural edit is a decision that dies with the session.
+
+## 1. The screen brief
+
+One file per screen, at `.trunative/screens/<name>.md`. It is the fourth brief: `PRODUCT.md` is the product, `DESIGN.md` is the identity, `STACK.md` is the codebase, and this is one screen.
+
+### Frontmatter
+
+```yaml
+---
+target: lib/screens/memories_screen.dart
+primary_action: "Explore Memories"
+states:
+  loading: skeleton cards in the rail, same row height as the real ones
+  empty: no memories yet, offers creating the first
+  error: retry without losing the active filter
+  offline: cached memories, carrying their age
+  partial: n/a, the rail loads whole or fails
+  permission: n/a, nothing here is behind a grant
+scope:
+  open: [lists, navigation, media, scrolling, offline]
+  closed:
+    forms: there is no input field, the filter is a chip
+    search: filtering by person is not a text query
+---
+```
+
+Four fields. Nothing joins them without a consumer already reading it.
+
+**`target`** is the file that implements the screen, relative to the project root. It is what links the brief to everything else: `flow/review.md` computes its archive slug from that path, and `npx trunative detect` reads it. There is no `id` field, because the target is the identity and the filename is a convenience.
+
+**`primary_action`** is the label the user reads, in quotes, not an identifier. `button-label`, `copy-first-word` and `copy-case` all judge the visible string, and the comparison against the code only works on the string. Exactly one: a screen with two primary actions is two screens, and `button-one-primary` is what says so.
+
+**`states`** carries the six keys `state-set` names, always all six: `loading`, `empty`, `error`, `offline`, `partial`, `permission`. Each value is one line saying what the screen shows, or `n/a` followed by the reason. A missing key, an empty value, or an `n/a` with no reason is a defect in the brief.
+
+The keys are fixed because a free list is a loophole. A screen that picks its own five states declares five, ships five and reads as complete, while the rule asks for six. Fixed keys make the absence something somebody had to write down and sign.
+
+A screen driving a camera, a microphone, location, a motion sensor or a radio owes the five further states in `sense-states` on top of these, in the body.
+
+**`scope`** names files from the Extra table in `SKILL.md`, by the stem or by the rule prefix beside it, whichever the row put in front of you: `localization` and `l10n` are the same row. Never a rule id, and never one of the nine always in scope, which are not optional and so are never declared. `open` is what build reads and what `npx trunative rubric --only` takes. `closed` carries the rows a reader would expect to be open, each with the sentence `SKILL.md` requires. Not the whole table: the near misses, which are the only ones anybody argues about later.
+
+### Body
+
+In this order, and nothing else:
+
+1. **Purpose.** One sentence, the job the screen does, from `PRODUCT.md`.
+2. **Hierarchy.** Numbered, top to bottom, in reading order.
+3. **Components.** What is on the screen, named as the thing it is.
+4. **Primary action.** The action and where the thumb reaches it.
+5. **Interactions.** One line per gesture, as target then result.
+6. **Navigation.** Where this screen leads and how it is reached, when either changed.
+7. **States.** A subsection per state that needs more than its frontmatter line.
+
+### The ceiling
+
+Two tests, and the brief fails on either:
+
+- If every line of this screen's code were deleted, could the intent and the structure be rebuilt from this file?
+- Does the file contain a number with a unit? Padding, radius, font size, width, a hex colour and a shadow belong in `DESIGN.md`. A brief that starts carrying them is a layout format wearing a brief's name.
+
+## 2. A screen that already exists
+
+Nobody reconstructs a codebase by hand. When a screen has no brief and a structural change arrives, derive the brief from the implementation first, the same way init derives the project briefs from the code, then make the change against it.
+
+Derive what the code shows and nothing more. A state the code does not implement is not written as implemented: it is the `n/a` that has no reason, which is exactly the finding that sends the screen back to build.
+
+## 3. The wireframe
+
+The brief preserves the decision. It does not let anyone see it. A hierarchy list reads in thirty seconds and hides what an image gives away at once: the primary action stranded in an empty frame, the last row of content under the pinned bar, a hero eating a third of the height, a density that does not fit. `flow/review.md` says the same thing when it refuses to close a screen on source evidence alone.
+
+So the brief gets rendered before it gets approved, and the rendering is a page the agent writes.
+
+Write `.trunative/screens/<name>.wireframe.html` from the brief. The frame, the greyscale palette and the placeholder conventions are in `references/wireframe-frame.md`, which is a skeleton to copy rather than a thing to reinvent per screen.
+
+- Greyscale, outlines, placeholders, a cross for an image, one system typeface, hierarchy by size.
+- Never a brand colour, a gradient, a shadow, a real photograph, an icon set, or any token from `DESIGN.md`. The wireframe settles structure, and a wireframe carrying identity collects an approval nobody asked for.
+- HTML even when the project ships Flutter, Compose or SwiftUI. Writing the wireframe in the project's stack is writing the screen twice, which is the cost this step exists to avoid.
+- The default state always. One more frame per state whose composition is genuinely different, which in practice is the empty one. Never all six: six frames cost more than the screen.
+
+Then render it and look at it yourself, before anyone else does:
+
+```sh
+chrome --headless --window-size=393,852 --screenshot=wireframe.png .trunative/screens/<name>.wireframe.html
+```
+
+<If agent="claude">
+Open the PNG with the Read tool and read it as a picture. That pass is the cheap half of this step: the collisions `flow/review.md` can only catch on a device show up here for the price of one HTML file.
+</If>
+
+<If agent="codex,antigravity,opencode,other">
+Open the PNG however this harness shows an image, and read it as a picture. That pass is the cheap half of this step: the collisions `flow/review.md` can only catch on a device show up here for the price of one HTML file. When the harness cannot show you an image at all, say so in the hand-off and leave the judgement to the user rather than claiming the frame was checked.
+</If>
+
+What the wireframe settles: the first screenful (`layout-fold`), content colliding with fixed chrome (`layout-chrome`), grouping and density (`layout-grouping`), reach for the primary action (`touch-reach`), and whether the real words fit (`copy-budget`).
+
+What it does not settle, and does not try: contrast, the dark appearance, text at the accessibility steps, measured hit areas, the screen reader, motion. Those are the nine always in scope, they are answered on a device in `flow/review.md`, and they are why the gate below approves structure rather than a finished screen.
+
+The wireframe is scaffolding, not a second contract. After approval nothing reads it: review does not open it, drift does not consult it, and no check validates it. It stays in the repository as the record of what was approved, and a later structural change rewrites it from the brief instead of patching it. One contract, brief against code, and no second surface to diverge.
+
+## 4. The gate
+
+Show the frame and four lines, and ask once:
+
+```text
+Memories
+
+Hierarchy      title, filters, recent memories, people, navigation
+Primary        "Explore Memories", bottom third
+States         loading, empty, error, offline; partial and permission n/a
+Scope          lists, navigation, media, scrolling, offline
+
+Approve?
+```
+
+The approval is about hierarchy, actions, states and navigation. It is not about colour, typeface, spacing or polish, and an answer about those goes to `DESIGN.md` rather than into the brief.
+
+Ask the user, and never grant it yourself. Writing the brief, drawing the frame and deciding it looks right is this step doing its own homework, not the gate: the gate is the one part of the step the user sees, and a step reporting "approved" with no question asked has skipped exactly that part.
+
+One question per session, which is not none. The first structural task of a session always asks. After it, the brief is still written and the frame still drawn, and the question comes back when a new structure contradicts one already approved.
+
+When the harness cannot show the user a picture, say so and put the four lines in front of them anyway. A gate answered on the text alone is weaker than one answered on the frame, and it is still the user answering.
+
+## 5. Hand off
+
+Say what the brief settled, which extra files its scope opened and which near misses it closed, and what the wireframe pass caught. Then run `flow/build.md`.

package/src/skills/heuristics/accessibility.md

@@ -0,0 +1,124 @@
+# Accessibility
+
+Everything else in this repository describes what the screen looks like. This file describes what is underneath it: the name of each control, the order they are reached in, and what the app says when something changes. That layer is the whole interface for someone using a screen reader, a switch, or their voice, and it is invisible in a screenshot, so it is the layer that gets shipped empty.
+
+A phone sharpens every part of it. There is no width for labels, so controls become icons with no text at all. There is no keyboard, so actions become gestures that a reader user cannot perform. One screen shows at a time, so content is swapped in place rather than loaded as a new page, and nothing announces the swap. And the settings that change the interface live in the operating system, apply to every app at once, and are already on when the app launches.
+
+Four neighbours carry pieces of this and are not repeated here: `color-not-alone`, `touch-floor`, `touch-spacing` and `type-scaling`. `list-a11y` is a fifth of a different kind: it is these rules applied to a list row, so the two are read together.
+
+## <Rule id="a11y-name" description="Every control carries a name, a role and a value" />
+
+Three separate things, and the last two are the ones that go missing.
+
+The **name** says the action and its object, in the words the user would use. It is not the icon, not the asset, not the glyph identifier. A control announced as `ic_chevron_right` or `star.fill` is not a poorly named control, it is an unusable one. `button-label` governs the visible label; this is what gets read when there is no visible label at all, which on a phone is most of the toolbar.
+
+- Leave the control type out of the name. The role already carries it, so "Add button" is announced as "Add button button".
+- Leave the surrounding context out too. Inside a player, "Play", not "Play song".
+- No two controls a voice user could address carry the same name. Three buttons all called "More" give a voice user nothing to say and a switch user nothing to aim at. Two rows that genuinely hold the same words are not that failure.
+
+The **role** arrives free with a real control and has to be declared on anything built from a container plus a tap handler: `Role` in Compose, a trait in SwiftUI, the `button`/`header`/`slider` flags in Flutter, `accessibilityRole` in React Native.
+
+The **value** is the current state, and it changes while the name does not: `stateDescription` in Compose, `accessibilityValue` in SwiftUI, `Semantics(value:)` in Flutter. A real control brings its own: a `Switch` reports checked or not checked and a `Toggle` reports on or off with nobody writing a line, so declaring a value over that is noise. Two cases are not covered. A container plus a tap handler standing in for a control reports no state at all. And a default can be right and still misleading, which is what an override is for: a mute button announced as "selected" is describing the widget rather than the sound. The same trap catches any control whose name should change with its state: a play control that keeps the name it was built with is lying half the time.
+
+Anything drawn onto a canvas (a chart, a custom picker, a signature field) has no child elements and is a single blank node until semantics are written for it by hand, with `ExploreByTouchHelper` on Android views or a semantics tree in the declarative kits.
+
+## <Rule id="a11y-hidden" description="Decoration is hidden, not described" />
+
+Every node in the tree is a stop the user has to step through. An icon sitting beside the label it duplicates, a divider, a background image, a chevron that only says the row opens: hide each one rather than naming it. `contentDescription = null` in Compose, `.accessibilityHidden(true)` in SwiftUI, `ExcludeSemantics` in Flutter. What matters is the outcome: a node that produces no semantics of its own, a spacer, a divider drawn as a background, already costs nothing and needs no declaration written over it.
+
+The opposite failure is just as common and reads worse: decoration given a description of its own picture, so the reader says "grey rounded rectangle with a blue circle". Text needs nothing, because it announces itself. And a loading placeholder is decoration until real content replaces it, so the shimmer blocks are hidden and the arrival is announced once (`state-loading`, `a11y-announce`).
+
+## <Rule id="a11y-order" evidence="device" description="Reading order is the order, and grouping decides how many stops" />
+
+Traversal order comes from the layout tree, walked in the reading direction of the content. It breaks wherever drawing order and layout order disagree: an absolutely positioned element, a bar drawn after the content it sits above, a floating button declared last in the file, an overlay stacked on top of the screen it belongs to.
+
+Fix it by fixing the declaration order. An override is the second answer: in Compose that is `isTraversalGroup` on the parent with `traversalIndex` on the children, and `traversalIndex` alone does nothing without the group flag on the parent.
+
+Grouping is the other half of the same rule. A card holding an image, a title, two lines of body and a badge is one thing to the user and six stops to a reader. Merge it so it reads as one sentence. `list-a11y` covers list rows; the identical problem appears in a card, a stat block, a labelled value pair, and a field with its helper text and its error.
+
+The screen title is announced first on arrival, so a screen whose title exists only inside a custom header view arrives in silence. Give it a title the system knows about: the navigation title where the stack has one, and `paneTitle` in Compose on a screen whose header is a composable of your own. Headings are what a reader jumps between instead of walking every element, and the trait that makes one is `list-a11y`.
+
+## <Rule id="a11y-collection" evidence="device" description="A collection says how long it is and where in it you are" />
+
+A phone has no scrollbar, and a recycling list keeps roughly a screenful of nodes alive at a time (`list-virtualise`). So a reader user walking it is told neither how many items exist nor which one this is, and there is nothing on screen to answer either question.
+
+A list, a grid or a carousel declares itself as a collection and each child declares its position in it, so the reader announces item three of two hundred. The platform list primitives do it on their own; anything assembled by hand does it explicitly, with `collectionInfo = CollectionInfo(rowCount, columnCount)` on the container and `collectionItemInfo = CollectionItemInfo(...)` on each child in Compose, and `IndexedSemantics` in Flutter. The total is how many items the data holds, not how many rows are realised: a count that follows the recycler tells the user the list is shrinking while they walk it.
+
+## <Rule id="a11y-announce" evidence="device" description="Content that changes without a navigation has to say so" />
+
+Almost nothing on a phone is a page load. A filter narrows the list in place, a total recalculates, a field turns red, a banner slides in at the top. A sighted user catches all of it in peripheral vision. A reader user is three stops away and is told nothing at all.
+
+- Mark the region that changes and let the platform speak it: `liveRegion = LiveRegionMode.Polite` in Compose, an announcement notification on iOS, `Semantics(liveRegion: true)` in Flutter.
+- Polite by default. Assertive cuts off whatever the user is listening to, so it is reserved for the thing that stops them: a failure, a payment result, a session ending.
+- Four that must never fire: one per keystroke inside a field, one per frame of a progress bar, one per row of an incoming page, one per tick of a countdown. Announce the outcome, never the process.
+- The announcement is the same sentence the screen shows, which means it is a translated string (`l10n-strings`) and, for a failed field, the message `form-error` already placed beside it.
+- An announcement is heard once, and the field keeps failing after it. So the field declares the failure on its own node, in those same words, and somebody who reaches it a minute later hears why instead of hearing the label alone: `error("...")` in the Compose semantics, the value and the traits on iOS.
+
+## <Rule id="a11y-focus" evidence="device" description="Focus moves where the screen moved, and comes back" />
+
+- When a sheet, dialog or cover opens, focus moves into it and cannot leave. On a phone the new surface covers the whole screen, so a reader that can still walk the layer beneath is reading a screen the user cannot see. The platform primitives settle it by presenting in their own context or window: `.sheet` and `.fullScreenCover` in SwiftUI, `Dialog` and `ModalBottomSheet` in Compose. An overlay stacked by hand inside a `ZStack` or a `Box` does not, so there the layer beneath is made inert by hand: `.accessibilityHidden(true)` in SwiftUI, `Modifier.clearAndSetSemantics {}` in Compose, `ExcludeSemantics` in Flutter, `accessibilityViewIsModal` on iOS with `importantForAccessibility="no-hide-descendants"` on Android in React Native.
+- On dismissal, focus returns to the control that opened it. Dropping the user at the top of the screen makes them traverse the whole thing again to get back to where they were.
+- The way out has to be reachable from inside the surface, which is `nav-modal` stated for a user who cannot perform the dismissing gesture.
+- Focus never moves unless the user asked it to. Taking it on load talks over the screen title, and taking it on every state change makes the screen impossible to read. Two moves are asked for and stay: onto the single field a screen exists for, such as search or a code (`form-input`), and onto the first failing field after a submit (`form-error`).
+
+## <Rule id="a11y-gesture" description="A gesture is never the only route" />
+
+A swipe, a long press, a drag to reorder, a pinch, anything with two fingers: none of these can be performed by someone using a reader, a switch, or a keyboard. Each one needs a named route to the same result, and where that route comes from depends on what drew the gesture.
+
+- Where the primitive already projects the gesture into the tree, the work is naming it. `Modifier.combinedClickable(onLongClickLabel = "Pin conversation")` puts the verb into the long press the platform is already offering, and a platform swipe row carries its actions with whatever labels they were given. An action left unnamed is announced as a generic one, and that is the defect rather than a missing declaration.
+- Where nothing projects it, a swipe layer assembled by hand, a drag to reorder, a pinch, the route is a custom action on the same node, named with the verb: `customActions` in Compose, `.accessibilityAction(named:)` in SwiftUI, `CustomSemanticsAction` in Flutter, `accessibilityActions` in React Native. `list-a11y` is this rule applied to a row.
+- A value that is dragged (a slider, a reorder handle, a rating) gets the adjustable action instead, so it moves one step at a time.
+- Custom multi-finger gestures have no route at all. Use the simplest gesture that works, and keep the visible equivalent that `list-swipe` and `list-refresh` already require.
+
+## <Rule id="a11y-alt-input" description="Switch and voice reach the app through names and targets" />
+
+A switch moves one highlight through everything focusable, in order, one press per step. Voice control acts on whatever the user can read out loud off the screen.
+
+- The spoken name matches the visible words. A button reading "Send" whose name is "Submit your message" cannot be spoken to. Where the two genuinely have to differ, the visible words are added rather than swapped in: `accessibilityInputLabels(_:)` is the iOS hook, and on Android there is no separate field, so the visible words go inside the description itself.
+- Anything that takes the highlight is something the user can act on. Decoration left in the tree (`a11y-hidden`) turns a five-step screen into a twenty-step one, and each of those steps is a physical press.
+- The highlight has to be visible, and it is the one piece of this that gets deleted on purpose. `outline: none` on mobile web, and any focus style suppressed because it looked wrong under a finger, leaves the switch and keyboard user pressing forward with nothing on screen saying where they are. Replace the default indicator with a better one; never remove it and leave nothing.
+- Every action is reachable by stepping, in a finite number of steps. A control that only appears mid-drag, or only under a long press with no custom action, does not exist for this user.
+- Nothing that carries the only copy of something dismisses itself on a timer: a toast holding an error message, a snackbar holding the only undo, a code that expires while the highlight is still walking toward the field. Stepping across a screen takes several times as long as tapping it. Prefer an explicit dismissal.
+
+## <Rule id="a11y-settings" description="The system settings are people, not options" />
+
+Larger text, bold text, increased contrast, reduced motion, reduced transparency. Each one is switched on by a user who needed it, and each one is already on before the app launches.
+
+- Larger text and bold text are `type-scaling` and `type-weight`. Both are honoured by taking every style from the theme rather than typing a size or a weight into a component, and the size the interface has to survive is the largest step `type-scaling` names.
+- Reduced motion belongs to `motion.md` in full. Read the setting, honour it, and do not restate it here.
+- Increased contrast is read as `colorSchemeContrast` in SwiftUI or `isDarkerSystemColorsEnabled` in UIKit, where the symbol name does not contain the word, and as `UiModeManager.getContrast()` from API 34 on Android. On iOS the semantic system colors answer it on their own; on Android the response has to be written, and either way a hex typed into a component cannot follow it (`color-roles`).
+- Reduced transparency is an iOS setting with no Android counterpart, so an Android-only build answers it as not applicable. On iOS it is honoured by the platform's own material and ignored by a blur rebuilt by hand, which is one more reason `color-gradient` sends you to the system one.
+- All of these are live values, not launch-time facts. Somebody will change one while the app is open, from the accessibility shortcut, and the screen has to follow: `addContrastChangeListener` on Android, the matching change notification on iOS.
+
+## <Rule id="a11y-media" description="Nothing is carried by audio alone" />
+
+Phones are used muted, in public, and by people who cannot hear them.
+
+- One of these the system already answers, which is the half a diff can be checked against: `isClosedCaptioningEnabled` on iOS and `CaptioningManager.isEnabled()` on Android say captions are wanted. Read it at launch and on its change notification, and start the player the way it says. Whether video may start by itself is `motion-autoplay`.
+- The rest is designed rather than read. Video carrying speech or meaningful sound carries captions, with the control to turn them on inside the player rather than buried in settings.
+- Sound is never the only signal. A success chime, an error beep, a haptic with no visible change: pair every one with something the screen shows (`touch-feedback`).
+- Audio that starts on its own is gated by `motion-autoplay` and `sound-unasked`, and the control to stop it is reachable in one step.
+
+## <Rule id="a11y-test" evidence="device" description="Drive one whole flow with the reader on" />
+
+- Run the platform scanner first, on every screen that changed. It catches the missing name, the small target and the low contrast, and it catches none of the four things above it: wrong order, wrong name, missing announcement, missing route.
+- Then use the app without looking at it. One complete flow, start to finish, stepping forward through every element with the screen reader on. Count the stops on the busiest screen: a card or a row costs one stop plus one for each separately tappable control it carries, which `list-row` caps at two. Above that, the merge `a11y-order` and `list-a11y` ask for did not happen.
+- Run it once more at the largest text size, and once with the reader off using a switch or a hardware keyboard.
+
+<Check>
+
+<Verify rule="a11y-name">Every interactive element has a name that is not its icon or asset, a declared role, and a declared value wherever the platform's own is missing or misleading, and no two controls a voice user could address share a name.</Verify>
+<Verify rule="a11y-hidden">No decorative element produces a stop, and nothing decorative carries a description of its own appearance.</Verify>
+<Verify rule="a11y-order">Traversal follows declaration order, any `traversalIndex` sits under an `isTraversalGroup` and carries the reason the order itself could not be fixed, each composite reads as one stop, and the screen has a title the system knows about.</Verify>
+<Verify rule="a11y-collection">Every list, grid and carousel declares its collection and each child its position, with a total taken from the data rather than from the realised rows.</Verify>
+<Verify rule="a11y-announce">Every in-place content change has a live region or an announcement, polite unless it stops the user, none fires per keystroke, per frame, per row or per tick, and a failed field declares the failure on its own node.</Verify>
+<Verify rule="a11y-focus">Modals contain focus and return it to the opening control on dismissal, a hand-built overlay makes the layer beneath inert, and focus moves nowhere else except onto a single-field screen or the first failure after a submit.</Verify>
+<Verify rule="a11y-gesture">Every swipe, long press, drag and multi-finger gesture reaches the same result through a named action: the primitive's own label where it projects one, a custom action where nothing does.</Verify>
+<Verify rule="a11y-alt-input">Spoken names match visible labels, nothing decorative takes the highlight, the focus indicator is visible and was never merely removed, every action is reachable by stepping, and nothing holding the only copy of something dismisses on a timer.</Verify>
+<Verify rule="a11y-settings">Increased contrast is read and honoured on each platform it exists on, reduced transparency on iOS is left to the system material, and every setting is read live rather than cached at launch.</Verify>
+<Verify rule="a11y-media">The system captions preference is read, video with speech has captions, no signal is audio or haptic only, and anything that starts on its own can be stopped in one step.</Verify>
+<Verify rule="a11y-test">The scanner was run on the changed screens and one full flow was completed with the screen reader on.</Verify>
+
+<Device>The last line is not answerable from a diff. `a11y-order`, `a11y-collection`, `a11y-announce` and `a11y-focus` are only half answerable from one: the tree they describe exists at runtime, so a file can show the intent and only a running screen shows the result.</Device>
+
+</Check>