@erclx/canon 5.44.0 → 5.46.0

package/governance/ledger/lib/testing-ts.md

@@ -0,0 +1,63 @@
+---
+title: TypeScript testing rule ledger
+description: Sources for governance/rules/lib/testing-ts.md, one row per bullet
+---
+
+# TypeScript testing rule ledger
+
+The field is JavaScript and TypeScript testing. The authorities are the Vitest documentation at vitest.dev, the Testing Library documentation at testing-library.com, and the Playwright documentation at playwright.dev. None of the pages read names a major, so the rows record the read date alone.
+
+## Unit and integration
+
+| Bullet                           | Source                                                                                                                                                                                                                                | Read       |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Vitest as the runner             | House choice: the toolkit's web stacks install and configure Vitest, so a test written for a second runner never runs in the gate                                                                                                     | 2026-10-18 |
+| `userEvent` over `fireEvent`     | [user-event](https://testing-library.com/docs/user-event/intro): it "factors in that the browser e.g. wouldn't let a user click a hidden element or type in a disabled text box"                                                      | 2026-10-18 |
+| MSW, no hand mocks or real calls | [Vitest, mocking requests](https://vitest.dev/guide/mocking/requests): "We recommend Mock Service Worker to accomplish this", since it mocks "http, WebSocket and GraphQL network requests"                                           | 2026-10-18 |
+| Role or label first              | [Testing Library queries](https://testing-library.com/docs/queries/about): `getByRole` "should be your top preference for just about everything", and a test ID "is only recommended for cases where you can't match by role or text" | 2026-10-18 |
+
+## End-to-end
+
+| Bullet                        | Source                                                                                                                                                                            | Read       |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Playwright for end-to-end     | House choice: the toolkit's web stack configures Playwright, so a second browser runner's tests never run in the gate                                                             | 2026-10-18 |
+| Playwright tests under `e2e/` | [Vitest include](https://vitest.dev/config/include) defaults to `**/*.{test,spec}.?(c\|m)[jt]s?(x)`, so a Playwright spec under `src/` is collected by Vitest too, where it fails | 2026-10-18 |
+
+## Timers and async
+
+| Bullet                           | Source                                                                                                                                                                                                               | Read       |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `advanceTimers` with fake timers | [user-event options](https://testing-library.com/docs/user-event/options): "When using fake timers it is necessary to set this option to your test runner's time advancement function"                               | 2026-10-18 |
+| Restore after pending timers     | [Using fake timers](https://testing-library.com/docs/using-fake-timers): "you usually call `useRealTimers` in `afterEach`", and "It's important to also call `runOnlyPendingTimers` before switching to real timers" | 2026-10-18 |
+
+## Conventions
+
+| Bullet                              | Source                                                                                                                                                                                                                   | Read       |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| `.test` for unit, `.spec` otherwise | House choice: [Playwright](https://playwright.dev/docs/test-configuration) runs "`**/*.@(spec\|test).?(c\|m)[jt]s?(x)` files" and Vitest matches the same pair, so the suffix is what a config separates the two runs on | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Cut "never use `vi.useFakeTimers()` in `beforeEach` when tests use `waitFor`, `act`, or `userEvent`". [Using fake timers](https://testing-library.com/docs/using-fake-timers) shows `beforeEach` as the usual setup, and names `advanceTimers` as the fix for the `userEvent` timeout, which the kept bullet carries.
+- Cut "scope fake timers to the individual test that needs them" with it, since no page read scopes them below the file.
+
+### Cut without a source or a bug class
+
+- Cut "`it()` descriptions use "should" + sentence case". The rule-standard audit flagged it as contested style naming no bug class.
+- Cut "`describe()` labels use the exact identifier of the subject" as naming style naming no failure.
+
+### Owned elsewhere
+
+- Cut "co-locate unit tests with their respective components". The `codebase-layout` skill's test reference places a unit test beside its module.
+- Cut "keep specs apart from their fixtures, page objects, and helpers inside `e2e/`", which the same reference owns.
+
+### Merged or reworded
+
+- Folded "place all Playwright tests within `e2e/`", "never place Playwright tests inside `src/`", and the scope bullet for a Vitest test driving a browser into one placement bullet.
+- Merged "do not make real network calls in unit tests" into the MSW bullet.
+- Merged the two suffix bullets into one.
+- Reworded "use `userEvent` over synthetic events" and the accessible-query bullet to name what each source says the choice prevents.

package/governance/ledger/lib/zod.md

@@ -0,0 +1,47 @@
+---
+title: Zod rule ledger
+description: Sources for governance/rules/lib/zod.md, one row per bullet
+---
+
+# Zod rule ledger
+
+The field is TypeScript runtime validation, and the authority is the Zod documentation at zod.dev with its changelog in the colinhacks/zod repository. The rule assumes Zod 4, since the methods it replaces stay available as legacy and a Zod 3 target keeps `z.strictObject()`.
+
+## Type inference
+
+| Bullet                       | Source                                                                                                                                                 | Read              |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- |
+| `z.infer`, no twin interface | [Basic usage](https://zod.dev/basics): "Zod infers a static type from your schema definitions. You can extract this type with the `z.infer<>` utility" | 2026-10-18, Zod 4 |
+
+## Boundary validation
+
+| Bullet                                | Source                                                                                                                                                                                                                                       | Read              |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
+| `z.strictObject()` on untrusted input | [Zod 4 changelog](https://raw.githubusercontent.com/colinhacks/zod/main/packages/docs/content/v4/changelog.mdx): "Instead use the top-level `z.strictObject()` and `z.looseObject()` functions", and the old methods "are considered legacy" | 2026-10-18, Zod 4 |
+| `.pick()` or `.omit()`, not loose     | [Defining schemas](https://zod.dev/api): "Zod provides dedicated APIs for picking and omitting certain keys from an object schema", and a loose schema "allows unknown keys to pass through"                                                 | 2026-10-18, Zod 4 |
+| `.parse()` or `.safeParse()`          | [Basic usage](https://zod.dev/basics): `.parse()` "will throw a `ZodError`", and `.safeParse()` returns "a plain result object containing either the successfully parsed data or a `ZodError`"                                               | 2026-10-18, Zod 4 |
+| `z.coerce` at string boundaries       | [Defining schemas](https://zod.dev/api): "The coerced variant of these schemas attempts to convert the input value to the appropriate type", applying `String(input)` for `z.coerce.string()`                                                | 2026-10-18, Zod 4 |
+
+## Schema safety
+
+| Bullet                       | Source                                                                                              | Read              |
+| ---------------------------- | --------------------------------------------------------------------------------------------------- | ----------------- |
+| `z.unknown()`, not `z.any()` | [Defining schemas](https://zod.dev/api): `z.any()` infers `any`, and `z.unknown()` infers `unknown` | 2026-10-18, Zod 4 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Replaced "use `.strict()` for untrusted external API boundaries". The [Zod 4 changelog](https://raw.githubusercontent.com/colinhacks/zod/main/packages/docs/content/v4/changelog.mdx) marks `.strict()` legacy and names `z.strictObject()`.
+- Replaced "prefer `.strict()` at boundaries or explicit `.pick()`/`.omit()` over `.passthrough()`", which recommended the legacy method and read as a preference. The kept bullet names `z.looseObject()` beside it.
+
+### Cut without a source or a bug class
+
+- Cut "do not export the runtime Schema if only the inferred Type is required by consumers" as an export taste naming no failure.
+
+### Merged or reworded
+
+- Merged "do not manually declare interfaces that duplicate Zod schemas" into the `z.infer` bullet.
+- Narrowed "restrict `z.coerce` to I/O boundaries" to string input and named the conversion, which is why `z.coerce.boolean()` reads `"false"` as `true`.

package/governance/ledger/tooling/ci-workflow.md

@@ -0,0 +1,33 @@
+---
+title: CI workflow rule ledger
+description: Sources for governance/rules/tooling/ci-workflow.md, one row per bullet
+---
+
+# CI workflow rule ledger
+
+The field is continuous integration on GitHub Actions, and the authority is GitHub's own Actions documentation at docs.github.com. The rule is the second half of a pair with the `ci-workflow` skill, which owns triggers, pinning, job shape, and the top-level read-only default, so this ledger covers only what the rule itself states.
+
+## Authority
+
+| Bullet                  | Source                                                                                                                                         | Read       |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Load the skill, routing | Routing only: it sends workflow authoring to the `canon:ci-workflow` skill, which carries the sourced directives, and claims no outside source | 2026-10-18 |
+
+## Commit-back
+
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                                                                                                                              | Read       |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Commit back only what the branch moved | House choice: a refresh an outside input moved, such as a font or a build-time count, lands a diff on a pull request whose change did not cause it, so the reviewer reads churn the author cannot explain                                                                                                                                                                                           | 2026-10-18 |
+| Deterministic output, diff check first | House choice: a step that regenerates differently on each run commits noise on every push, and a commit step with no diff check ahead of it pushes a capture that did not change                                                                                                                                                                                                                    | 2026-10-18 |
+| Skip a fork's pull request             | [Workflow syntax, permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax): "if the workflow was triggered by a pull request event other than `pull_request_target` from a forked repository, and the Send write tokens to workflows from pull requests setting is not selected, the permissions are adjusted to change any write permissions to read only" | 2026-10-18 |
+| Never commit back to the trunk         | House choice: a workflow pushing onto the trunk lands a change no pull request carried and no reviewer read                                                                                                                                                                                                                                                                                         | 2026-10-18 |
+
+## Token scopes
+
+| Bullet                      | Source                                                                                                                                                                                                                                                                                                                                       | Read       |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Write scope on the job only | [Workflow syntax, permissions](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax): "For a specific job, you can use `jobs.<job_id>.permissions` to modify the default permissions granted to the `GITHUB_TOKEN`, adding or removing access as required, so that you only allow the minimum required access" | 2026-10-18 |
+
+## Declined
+
+Nothing was cut. Every bullet already sat inside the shape limits, and the rule keeps its split with the skill, a pointer plus at most five directives.

package/governance/ledger/tooling/code-comments.md

@@ -0,0 +1,48 @@
+---
+title: Code comments rule ledger
+description: Sources for governance/rules/tooling/code-comments.md, one row per bullet
+---
+
+# Code comments rule ledger
+
+The field is software engineering practice for source comments, which has no spec. The authorities are the published style guides of large codebases, here Google's guides for Python, C++, TypeScript, JavaScript, and shell, read as practice from one large codebase rather than as a settlement of the field.
+
+## When a comment should exist
+
+| Bullet                                   | Source                                                                                                                                                                                                                                             | Read       |
+| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Only a fact the code cannot carry        | [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html): "The final place to have comments is in tricky parts of the code. If you're going to have to explain it at the next code review, you should comment it now."        | 2026-10-18 |
+| Do not restate the line                  | [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html): "never describe the code. Assume the person reading the code knows Python (though not what you're trying to do) better than you do."                                | 2026-10-18 |
+| No comment on a self-describing function | [Google TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html): "Method, parameter, and return descriptions may be omitted if they are obvious from the rest of the method's JSDoc or from the method name and type signature." | 2026-10-18 |
+| No comment moved to hit a density figure | House choice: a comment added to reach a figure restates the line beside it, and one deleted to reach it drops a contract the code cannot carry. No style guide states a density target to depart from.                                            | 2026-10-18 |
+
+## What a comment may claim
+
+| Bullet                                  | Source                                                                                                                                                                                                                                                                                                                        | Read       |
+| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| True as written, updated in the change  | House choice: a comment describing behavior the code does not have, whether planned or since changed, reads as authoritative and misleads the next reader. Updating it in the same change puts both sides in front of one reviewer.                                                                                           | 2026-10-18 |
+| Contract, not steps                     | [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html): "The docstring should describe the function's calling syntax and its semantics, but generally not its implementation details, unless those details are relevant to how the function is to be used."                                            | 2026-10-18 |
+| No person, ticket, or date in its place | House choice: a comment that only points at a person, a ticket, or a date tells the reader nothing once the person leaves or the ticket closes. Google's guides attach a bug or a name to a `TODO` beside its description, and the Python guide adds "Avoid adding TODOs that refer to an individual or team as the context". | 2026-10-18 |
+
+## What never goes in a comment
+
+| Bullet                    | Source                                                                                                                                                                                                                                                                                                                 | Read       |
+| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Delete commented-out code | House choice: commented-out code escapes the type checker and the tests, so it rots while reading as an option still open, and version control already keeps it                                                                                                                                                        | 2026-10-18 |
+| No edit history           | House choice: a comment recording the edit that made the code goes stale at the next edit and duplicates what `git log` and `git blame` hold                                                                                                                                                                           | 2026-10-18 |
+| No deferred work          | House choice: deferred work in a comment is work no tracker query finds, so nobody schedules it. [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html) asks for `TODO` comments carrying "the bug ID, name, e-mail address, or other identifier", which is Google's convention for its own code. | 2026-10-18 |
+
+## Degradation vocabulary
+
+| Bullet                         | Source                                                                                                                                                                                                                                                                                                                                                                                    | Read       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `TODO`, `FIXME`, `HACK`, `XXX` | House choice: each term marks deferred work or a known defect in a place no tracker query reaches. Google's guides depart, asking for a `TODO` with an owner or a bug link so it "can be searched to find out how to get more details" (Python guide). Google's guide governs Google's code rather than settling the field, so this rule keeps the ban and sends the work to the tracker. | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Merged or reworded
+
+- Merged "Let comment density follow how much of a file's behavior is decided outside that file" into the density bullet as its reason. On its own it named no line a reviewer could check.
+- Merged "State only what is true of the code as written" into the update bullet, which states the same requirement and adds when to meet it

package/governance/ledger/tooling/config-comments.md

@@ -0,0 +1,27 @@
+---
+title: Config comments rule ledger
+description: Sources for governance/rules/tooling/config-comments.md, one row per bullet
+---
+
+# Config comments rule ledger
+
+The field is comment style in configuration files. Neither the YAML spec nor the JSON-with-comments convention takes a side on what a comment says, and no published style guide covers config files the way Google's guides cover source. So every kept bullet stands on a house-choice row naming its bug class.
+
+## Comments
+
+| Bullet                                   | Source                                                                                                                                                                                                             | Read       |
+| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| What a key does or accepts, not its name | House choice: the allowed values are set by the tool reading the file, a fact the key name does not carry, while a comment restating the name adds a line that tells the reader nothing and can drift from the key | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed, grouped by why.
+
+### A convention Claude follows unprompted
+
+- Cut "Match the comment density of the surrounding file", since the Claude Code system prompt already tells the model to match the surrounding code's comment density
+
+### Cut without a source or a bug class
+
+- Cut "Keep each comment to one short line", since comment length is taste and no reviewer could point at a defect a two-line comment causes
+- Cut "Prefer a one-word category label over a sentence for a group header", as taste with no bug class

package/governance/ledger/tooling/dependencies.md

@@ -0,0 +1,38 @@
+---
+title: Dependencies rule ledger
+description: Sources for governance/rules/tooling/dependencies.md, one row per bullet
+---
+
+# Dependencies rule ledger
+
+The field is package management for JavaScript and Python projects. The authorities are each package manager's own documentation, being Bun at bun.com, npm at docs.npmjs.com, uv at docs.astral.sh, and pnpm at pnpm.io for the hoisting behavior it was built to remove.
+
+Bun's docs moved from bun.sh to bun.com, where the old paths now return a not-found page.
+
+## Declaration
+
+| Bullet                               | Source                                                                                                                                                                                                                                                                                                                                                                                                                                      | Read                        |
+| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
+| Declare before importing             | [Isolated installs](https://bun.com/docs/pm/isolated-installs): under isolated installs "packages can only access their explicitly declared dependencies", the default for new workspaces, so an undeclared import fails to resolve there                                                                                                                                                                                                   | 2026-10-18, Bun 1.3         |
+| Add through the package manager      | [uv, managing dependencies](https://docs.astral.sh/uv/concepts/projects/dependencies/): "uv supports modifying the project's dependencies with `uv add` and `uv remove`, but dependency metadata can also be updated by editing the `pyproject.toml` directly", and [uv, locking](https://docs.astral.sh/uv/concepts/projects/sync/): "if you add a dependency to your `pyproject.toml`, the lockfile will be considered outdated"          | 2026-10-18                  |
+| Commit the lockfile with the change  | [Bun lockfile](https://bun.com/docs/pm/lockfile): "Should it be committed to git? Yes". [package-lock.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-lock-json): "This file is intended to be committed into source repositories". [bun install](https://bun.com/docs/pm/cli/install): a frozen install fails when the manifest and lockfile disagree, so "Run `bun install` and commit the updated `bun.lock`"               | 2026-10-18, Bun 1.3, npm 11 |
+| Development-only as a dev dependency | [package.json](https://docs.npmjs.com/cli/v11/configuring-npm/package-json): a module's users "probably don't want or need to download and build the external test or documentation framework that you use. In this case, it's best to map these additional items in a `devDependencies` object". [bun add](https://bun.com/docs/pm/cli/add): "Bun writes the package to `dependencies` unless you pass `--dev`, `--optional`, or `--peer`" | 2026-10-18, Bun 1.3, npm 11 |
+| No transitive-only imports           | [pnpm motivation](https://pnpm.io/motivation): under npm or Yarn Classic hoisting, "source code has access to dependencies that are not added as dependencies to the project". The import works until the parent package drops or bumps the dependency, then breaks with no change to this project's manifest                                                                                                                               | 2026-10-18                  |
+
+## Removal
+
+| Bullet                      | Source                                                                                                                                                                               | Read       |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Remove with the last import | House choice: an entry nothing imports keeps installing on every machine and in every build, and nothing fails to point at it, so it stays until someone audits the manifest by hand | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Rewrote "Never hand-edit the manifest" to re-locking after a hand edit, since uv documents editing `pyproject.toml` directly. The bug the ban guarded against is a stale lockfile.
+
+### Merged or reworded
+
+- Cut "never install without recording the result", which the declare bullet already covers, and which brought the line to 206 characters against the 200 limit

package/governance/ledger/ui/a11y.md

@@ -0,0 +1,55 @@
+---
+title: Accessibility rule ledger
+description: Sources for governance/rules/ui/a11y.md, one row per bullet
+---
+
+# Accessibility rule ledger
+
+The field is web accessibility, and the authority is the W3C, through WCAG 2.2 and its Understanding documents, the WAI tutorials, and the ARIA notes. The keyboard and focus half of the old rule moved to `keyboard.md`, whose ledger records those bullets.
+
+## Semantics
+
+| Bullet                                    | Source                                                                                                                                                                                                                                             | Read                 |
+| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Native `<button>` or `<a>` over a `<div>` | [Using ARIA, first rule](https://www.w3.org/TR/using-aria/): "If you can use a native HTML element or attribute with the semantics and behavior you require already built in", use it "instead of re-purposing an element and adding an ARIA role" | 2026-10-18           |
+| Attribute spelling per syntax             | [React common components](https://react.dev/reference/react-dom/components/common): the DOM prop is `tabIndex`, "A number. Overrides the default Tab button behavior", where HTML spells it `tabindex`                                             | 2026-10-18, React 19 |
+| Role and synchronized state               | [Understanding Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html): "the name and role can be programmatically determined" and "notification of changes to these items is available to user agents"               | 2026-10-18, WCAG 2.2 |
+| Name for a control with no visible text   | [Understanding Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html): every user interface component's "name and role can be programmatically determined"                                                           | 2026-10-18, WCAG 2.2 |
+
+## Text alternatives
+
+| Bullet                                     | Source                                                                                                                                                                                                                                                           | Read       |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `alt` on every image, empty for decoration | [Decorative images](https://www.w3.org/WAI/tutorials/images/decorative/): "a null (empty) alt text should be provided ( alt="" ) so that they can be ignored by assistive technologies"                                                                          | 2026-10-18 |
+| Meaning or action, not appearance          | [Functional images](https://www.w3.org/WAI/tutorials/images/functional/): the text "should convey the action that will be initiated (the purpose of the image), rather than a description of the image", so "print this page" rather than "(image of a) printer" | 2026-10-18 |
+
+## Contrast and color
+
+| Bullet                          | Source                                                                                                                                                                                                                                             | Read                 |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| 3:1 for boundaries and graphics | [Understanding Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html): "Ensure meaningful visual cues achieve 3:1 against the background"                                                                          | 2026-10-18, WCAG 2.2 |
+| Color never the only carrier    | [Understanding Use of Color](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html): "Color is not used as the only visual means of conveying information, indicating an action, prompting a response, or distinguishing a visual element" | 2026-10-18, WCAG 2.2 |
+
+## Reflow
+
+| Bullet                                 | Source                                                                                                                                                                                                                                                                                            | Read                 |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Reflow at 320                          | [Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html): "without requiring scrolling in two dimensions" at "a width equivalent to 320 CSS pixels", "Except for parts of the content which require two-dimensional layout", such as "maps and diagrams" and "data tables" | 2026-10-18, WCAG 2.2 |
+| 320 is 1280 at 400 percent             | [Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html): "320 CSS pixels is equivalent to a starting viewport width of 1280 CSS pixels wide at 400% zoom"                                                                                                                 | 2026-10-18, WCAG 2.2 |
+| The same floor beside resizable chrome | House choice: a panel widened to 480 in a 768 window leaves 288 for the content, under the floor at a window width the criterion passes                                                                                                                                                           | 2026-10-18           |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Moved to `keyboard.md`
+
+- Moved the focus styles, keyboard model, pointer targets, composite widgets, and focus management H2s to `keyboard.md`, whose ledger records each of those bullets.
+
+### Merged or reworded
+
+- Merged "a `<div>` with a click handler requires a role, a tab index, and keyboard handlers" into the native element bullet, which states the same choice from the other side.
+- Merged "set role on custom controls" and "synchronize state attributes with visual state" into one bullet, since both rest on the same success criterion.
+- Merged "describe the content or function, not its appearance" and "alt text for functional images should describe the action" into one bullet.
+- Shortened the reflow criterion bullet and its 1280 equivalence to fit the 200 character limit, keeping the criterion's exceptions.
+- Shortened the resizable chrome bullet and moved its worked example into this ledger's row, since it explained rather than directed.

package/governance/ledger/ui/copy.md

@@ -0,0 +1,49 @@
+---
+title: UI copy rule ledger
+description: Sources for governance/rules/ui/copy.md, one row per bullet
+---
+
+# UI copy rule ledger
+
+The field is content design, and the authority for researched interface copy is the GOV.UK Design System and its style guide.
+
+## Punctuation
+
+| Bullet                        | Source                                                                                                                                                                  | Read       |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| No em dash or semicolon       | House choice: both read as generated copy in an interface, and a comma, a period, or a split sentence carries the same meaning in a shorter line                        | 2026-10-18 |
+| No trailing label punctuation | [Button](https://design-system.service.gov.uk/components/button/): every example label, such as "Start now", "Sign in", and "Continue", carries no trailing punctuation | 2026-10-18 |
+
+## Button copy
+
+| Bullet            | Source                                                                                                                                     | Read       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| The action's verb | [Button](https://design-system.service.gov.uk/components/button/): "Write button text in sentence case, describing the action it performs" | 2026-10-18 |
+
+## Error messages
+
+| Bullet            | Source                                                                                                                                                                                                                                            | Read       |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Say how to fix it | [Error message](https://design-system.service.gov.uk/components/error-message/): "Describe what has happened and tell them how to fix it", and "'Enter your first name' is clearer, more direct and natural than 'First name must have an entry'" | 2026-10-18 |
+| Short and plain   | [Error message](https://design-system.service.gov.uk/components/error-message/): "The message must be in plain English, use positive language and get to the point", with no "technical jargon like 'form post error'"                            | 2026-10-18 |
+
+## Placeholder text
+
+| Bullet                         | Source                                                                                                                                                                                                                                           | Read       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| No placeholder, a hint instead | [Text input](https://design-system.service.gov.uk/components/text-input/): "Do not use placeholder text in place of a label, or for hints or examples", since "it vanishes when the user starts typing" and "not all screen readers read it out" | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the source
+
+- Replaced "show format examples over instructions in placeholder text" with the hint text bullet, since GOV.UK says not to use a placeholder "for hints or examples".
+- Cut "reserve instructions for labels or helper text", which the new placeholder bullet now carries.
+
+### Merged or reworded
+
+- Merged the imperative verb and padded phrasing bullets. The `Save` over `Save changes` example went, since GOV.UK adds words "to better describe the action".
+- Merged "keep messages short and actionable" and "one sentence maximum" into the plain language bullet.
+- Reworded the error example to `Enter an email address`, the instruction form GOV.UK prefers over a description.

package/governance/ledger/ui/design-reference.md

@@ -0,0 +1,42 @@
+---
+title: Design reference rule ledger
+description: Sources for governance/rules/ui/design-reference.md, one row per bullet
+---
+
+# Design reference rule ledger
+
+The rule states canon's own design handoff, generalized from Frameboard's project rule, so every row is a house choice naming the bug the bullet prevents.
+
+## Where the design lives
+
+| Bullet                         | Source                                                                                                                                                              | Read       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Build against the tracked copy | House choice: a canvas changes under the build with no history, so a reviewer cannot tell which version a surface was built against                                 | 2026-10-18 |
+| Land a design first            | House choice: a design landing inside a feature pull request is reviewed as code, and a second feature building against it meanwhile reads a design nobody accepted | 2026-10-18 |
+| No hand edits                  | House choice: a reference edited by hand drifts from its canvas source, and the next sync overwrites the edit or reports it as a change nobody made                 | 2026-10-18 |
+| Index row before the sync      | House choice: the sync writes only the surfaces the index names, so a missing row drops the new surface's reference, and a stale row keeps a removed surface's      | 2026-10-18 |
+
+## Building against a reference
+
+| Bullet                     | Source                                                                                                                     | Read       |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Open both themes first     | House choice: a build read from the dark image alone ships a light theme nobody saw                                        | 2026-10-18 |
+| Values from the frame HTML | House choice: sizes and colors read off an image are estimates, and the frame HTML carries the exact values the design set | 2026-10-18 |
+
+## Showing the comparison
+
+| Bullet                             | Source                                                                                                                       | Read       |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Reference beside capture           | House choice: a reviewer shown the build alone has nothing to compare it to, and approves a departure without seeing it      | 2026-10-18 |
+| Name each departure                | House choice: an unnamed departure reads as an accident, and the next build against the same reference repeats or reverts it | 2026-10-18 |
+| Unexplained departure is a finding | House choice: without the finding, an unexplained departure merges as the new design with no one having chosen it            | 2026-10-18 |
+
+## Naming
+
+| Bullet                  | Source                                                                                                                                 | Read       |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One folder per app part | House choice: a fixed folder and theme suffix let the sync and a reviewer find a surface's pair of references without reading an index | 2026-10-18 |
+
+## Declined
+
+The rewrite kept every bullet. Each was already under 200 characters and states a step a reviewer can check against the pull request.

package/governance/ledger/ui/design-taste.md

@@ -0,0 +1,19 @@
+---
+title: Design taste rule ledger
+description: Sources for governance/rules/ui/design-taste.md, one row per bullet
+---
+
+# Design taste rule ledger
+
+The rule is a pointer to the `design-taste` skill, which carries its own sources, so both rows are house choices naming the bug the pointer prevents.
+
+## Authority
+
+| Bullet                     | Source                                                                                                                                                                     | Read       |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Load the skill             | House choice: a style edit made without the layer order or the coherence locks reaches for a model's defaults, and a second copy of them in the rule drifts from the skill | 2026-10-18 |
+| Report an unresolved skill | House choice: the rule ships with the CLI and the skill with the plugin, so a project holding governance alone would otherwise proceed silently without it                 | 2026-10-18 |
+
+## Declined
+
+The rewrite kept both bullets unchanged.

package/governance/ledger/ui/forms.md

@@ -0,0 +1,71 @@
+---
+title: Forms rule ledger
+description: Sources for governance/rules/ui/forms.md, one row per bullet
+---
+
+# Forms rule ledger
+
+The field is form design inside interaction design, and the authority for researched form patterns is the GOV.UK Design System, with WCAG 2.2 for the two authentication criteria. NN/g was read beside it and disagrees on validation timing, recorded under `## Declined`.
+
+## Validation timing
+
+| Bullet                     | Source                                                                                                                                                                                                            | Read       |
+| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Validate on submit         | [Recover from validation errors](https://design-system.service.gov.uk/patterns/validation/): "Do not validate when the user moves away from a field. Wait until they try to move to the next part of the service" | 2026-10-18 |
+| Re-validate after an error | House choice: an error left in place after the input turns valid tells the person their correct answer is still wrong, and they edit a field that needed nothing                                                  | 2026-10-18 |
+
+## Submission
+
+| Bullet                            | Source                                                                                                                                                                                                                                                                                                    | Read       |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Refuse with errors, never disable | [Button](https://design-system.service.gov.uk/components/button/): "Disabled buttons have poor contrast and can confuse some users, so avoid them if possible", and [validation](https://design-system.service.gov.uk/patterns/validation/) refuses "missing information, if the information is required" | 2026-10-18 |
+
+## Error placement
+
+| Bullet                                | Source                                                                                                                                                                                         | Read       |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Error next to its field               | [Error message](https://design-system.service.gov.uk/components/error-message/): "Show an error message next to the field and in the Error summary component when there is a validation error" | 2026-10-18 |
+| Cross-field error on the edited field | House choice: an error under the field the person did not touch sends them to change a value they meant, rather than the one they just entered                                                 | 2026-10-18 |
+| Focus to a linked summary             | [Error summary](https://design-system.service.gov.uk/components/error-summary/): "move keyboard focus to the error summary" and "link to each of the answers that have validation errors"      | 2026-10-18 |
+
+## Authentication and re-entry
+
+| Bullet                   | Source                                                                                                                                                                                                                                                                                         | Read                 |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Allow paste and autofill | [Understanding Accessible Authentication (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/accessible-authentication-minimum.html): mechanisms that satisfy it include "support for password entry by password managers" and "copy and paste to reduce the cognitive burden of re-typing" | 2026-10-18, WCAG 2.2 |
+| No redundant entry       | [Understanding Redundant Entry](https://www.w3.org/WAI/WCAG22/Understanding/redundant-entry.html): information previously entered in the same process is "either auto-populated, or available for the user to select"                                                                          | 2026-10-18, WCAG 2.2 |
+
+## Input sanitization
+
+| Bullet                        | Source                                                                                                                                                                                                                                                                    | Read       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Trim on submit                | [Recover from validation errors](https://design-system.service.gov.uk/patterns/validation/): "Use validation to ignore unwanted characters", such as spaces entered "before or after" an answer, since an error over one "would be difficult for the user to see and fix" | 2026-10-18 |
+| Say a field is case-sensitive | House choice: a value rejected or duplicated on case alone fails with no visible reason, since `Foo` and `foo` read as the same answer                                                                                                                                    | 2026-10-18 |
+
+## Derived display state
+
+| Bullet                        | Source                                                                                                                                                       | Read       |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Reset derived state on change | House choice: a status, count, or result left from the previous input reports on a value the field no longer holds, such as a "connected" dot for an old URL | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the source
+
+- Replaced "validate on blur" with validation on submit, since GOV.UK says "Do not validate when the user moves away from a field".
+- Kept GOV.UK over NN/g's [form errors guidelines](https://www.nngroup.com/articles/errors-forms-design-guidelines/), which favor validation "as soon as the user has finished filling in a field".
+- Replaced "block save when a required field is empty or invalid" with the submission bullet. Read as a disabled button, it contradicts GOV.UK.
+
+### Made redundant by the rewrite
+
+- Cut "apply the same validation timing to all fields in a form", since validating on submit gives every field one timing.
+- Cut "do not show an error on a field the user has never touched", since no error shows before a submit.
+
+### Merged or reworded
+
+- Merged "treat whitespace-only values as empty for required fields" into the submission bullet.
+- Merged the `## Submission errors` H2 into `## Error placement`, which took the form to 6 H2s.
+- Reworded "under the field" to "next to the field", since GOV.UK places the message between the label and the input.
+- Took in the status indicator reset from `ux-completeness.md`, so the reset has one copy.

package/governance/ledger/ui/interface-casing.md

@@ -0,0 +1,47 @@
+---
+title: Interface casing rule ledger
+description: Sources for governance/rules/ui/interface-casing.md, one row per bullet
+---
+
+# Interface casing rule ledger
+
+The field is content design, and the authority is the GOV.UK style guide, which sets sentence case for every heading and title. The label count and the scope bullets are canon's own.
+
+## Sentence case
+
+| Bullet                   | Source                                                                                                                                                      | Read       |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Sentence case            | [A to Z of GOV.UK style](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style): "Always use sentence case, even in page titles and service names" | 2026-10-18 |
+| Proper nouns keep casing | [A to Z of GOV.UK style](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style): "The exceptions to this are proper nouns"                         | 2026-10-18 |
+
+## Uppercase labels
+
+| Bullet      | Source                                                                                                                                                       | Read       |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Label count | House choice: an uppercase eyebrow over every section is the template tell `design-taste` reaches past, and the count makes the cap checkable against a page | 2026-10-18 |
+
+## Where it applies
+
+| Bullet                 | Source                                                                                                           | Read       |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- |
+| Copy outside the globs | House choice: a locale file holds the same rendered strings, so title case there ships with no rule firing on it | 2026-10-18 |
+
+## Overriding
+
+| Bullet              | Source                                                                                                                                        | Read       |
+| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Depart where needed | House choice: an acronym or brand mark lowered to sentence case misnames it, the same reason GOV.UK keeps "proper nouns" as its one exception | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Cut without a check
+
+- Cut "treat the count as a judgment, since a glob cannot check it", which tells a session nothing it can verify against a line.
+
+### Merged or reworded
+
+- Folded "treat title case on every heading as a template tell" into the sentence case bullet as its reason.
+- Shortened the uppercase label bullet under 200 characters, keeping the `ceil(sections / 3)` count and the delete remedy.
+- Reworded the scope bullet from a statement of what the rule covers to the directive a session can act on.