@erclx/canon 5.44.0 → 5.45.0

package/governance/ledger/ui/surface-capture.md

@@ -0,0 +1,69 @@
+---
+title: Surface capture rule ledger
+description: Sources for governance/rules/ui/surface-capture.md, one row per bullet
+---
+
+# Surface capture rule ledger
+
+The rule states canon's own evidence procedure for a rendered change, so most rows are house choices naming the bug the bullet prevents. The 320 floor rests on WCAG 2.2, and each explanation the old rule carried moved into a row here.
+
+## What a surface is
+
+| Bullet                         | Source                                                                                                                                    | Read       |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Generated pages are surfaces   | House choice: reading a generated page's markup reports nothing about how it composes, so a page nobody captured ships its layout unseen  | 2026-10-18 |
+| Skip build-stripped components | House choice: the production build removes a dev-only switcher before anything renders, so a capture of it compares nothing a person sees | 2026-10-18 |
+
+## When to capture
+
+| Bullet                  | Source                                                                                                                                                           | Read       |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Preview, not dev server | House choice: a dev server injects overlays and skips the production build's transforms, so its frame differs from what ships                                    | 2026-10-18 |
+| Every theme, and again  | House choice: a defect in the dark theme passes a light-only capture, and a repair inside a shared stylesheet can cancel a rule written earlier in the same file | 2026-10-18 |
+
+## What a capture covers
+
+| Bullet                      | Source                                                                                                                                                                                                                                        | Read                 |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Full page                   | House choice: a component captured alone shows none of the spacing, overflow, or stacking its page imposes on it                                                                                                                              | 2026-10-18           |
+| 320 plus breakpoints        | [Understanding Reflow](https://www.w3.org/WAI/WCAG22/Understanding/reflow.html): the criterion tests "a width equivalent to 320 CSS pixels". A 320 frame proves a frame was taken there, never that the page reflows, which `a11y.md` states. | 2026-10-18, WCAG 2.2 |
+| Chrome at both clamps       | House choice: a sidebar widened to its clamp leaves the content under the floor at a window width the criterion passes, and a frame where the chrome turned into an overlay shows none of the width it takes                                  | 2026-10-18           |
+| State case at one width     | House choice: a case driving a menu open tests the state, and repeating it at every layout width multiplies the evidence with no layout to compare                                                                                            | 2026-10-18           |
+| Drive unreachable states    | House choice: an initial render reports nothing about a menu that opens, an answer that is chosen, or a rail that tracks scrolling                                                                                                            | 2026-10-18           |
+| Case lives with the surface | House choice: a surface with no case ships uncaptured, and a case left after its surface goes fails every later capture run                                                                                                                   | 2026-10-18           |
+
+## Sharing a capture
+
+| Bullet                    | Source                                                                                                                                                                                                        | Read       |
+| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| An `evidence` folder      | House choice: the pull request comment collects an image only when a path segment is literally `evidence`, so any other name drops the capture. Several such folders, one per surface, is the ordinary shape. | 2026-10-18 |
+| Commit flagged cases only | House choice: recommitting an unbounded sweep on every run reaches a gigabyte of history inside a hundred merges, while a small committed set lets GitHub draw its own before and after comparison            | 2026-10-18 |
+| Byte-identical twice      | House choice: a case whose output varies between runs shows a diff on every pull request, so the comparison stops meaning a change                                                                            | 2026-10-18 |
+| Mask the moving value     | House choice: an elapsed-time counter or a relative date differs on every run, and masking the smallest element keeps the check running on the rest of the frame                                              | 2026-10-18 |
+| Name the variance         | House choice: a value whose width reflows its neighbors survives the mask, and re-running until two frames match hides the variance rather than removing it                                                   | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Moved into a row as the reason
+
+- Moved "judge a generated page by the same rule as a route, since reading its markup reports nothing" into the generated pages row.
+- Moved "read a capture at 320 as proof that a frame was taken there, not that the page reflows" into the 320 row.
+- Moved "several `evidence/` folders in one project is the ordinary shape" into the folder row.
+- Moved "recommitting an unbounded sweep reaches a gigabyte of repository history" into the commit row.
+- Moved "do not commit the state as evidence when the masked outputs still differ" into the variance bullet and its row.
+
+### Cut as stated elsewhere
+
+- Cut "`git-pr` and `git-followup` maintain a comparison comment automatically", which those skills own and which directs nothing at the edit.
+- Cut "fall back to the 320 floor alone when the project has no `DESIGN.md`", merged into the 320 bullet's "or at 320 alone".
+- Cut "read those bounds from the code that clamps the chrome", merged into the chrome bullet's "clamp".
+- Cut "do not impose another project's breakpoints", which the bullet reading `## Layout` already prevents.
+
+### Merged or reworded
+
+- Merged "run the capture command", "against a running preview", "every theme", and "capture again" into two bullets.
+- Merged "do not commit the sweep" with "commit a flagged case's evidence" and the established convention exception.
+- Merged "add a case" and "remove a surface's case" into one bullet.
+- Shortened every bullet past 200 characters, cutting the rule from 27 bullets and 840 words to 15 and under 300.

package/governance/ledger/ui/ux-completeness.md

@@ -0,0 +1,79 @@
+---
+title: UX completeness rule ledger
+description: Sources for governance/rules/ui/ux-completeness.md, one row per bullet
+---
+
+# UX completeness rule ledger
+
+The field is interaction design, and the authorities are the Nielsen Norman Group's research articles, WCAG 2.2 for timing, MDN for the `title` attribute and CSS truncation, and web.dev for layout shift.
+
+## Feedback
+
+| Bullet                                | Source                                                                                                                                                                                                                                                                     | Read                 |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Confirm success and failure           | [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/): "Whenever users interact with a system, they need to know whether the interaction was successful"                                                                               | 2026-10-18           |
+| Auto-dismiss only a redundant message | [Understanding Timing Adjustable](https://www.w3.org/WAI/WCAG22/Understanding/timing-adjustable.html): "If the user has no other means of discovering the same information (or performing the same function), then each message would need to meet this success criterion" | 2026-10-18, WCAG 2.2 |
+| No optimistic status                  | House choice: a "connected" dot shown over unsaved edits reports a state the system has not reached, and the person leaves believing their change took                                                                                                                     | 2026-10-18           |
+
+## Empty states
+
+| Bullet                         | Source                                                                                                                                                                                                                                               | Read       |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Empty state with a next action | [Designing empty states](https://www.nngroup.com/articles/empty-state-interface-design/): designed empty states "Provide direct pathways for getting started with key tasks"                                                                         | 2026-10-18 |
+| Distinguish new from filtered  | [Designing empty states](https://www.nngroup.com/articles/empty-state-interface-design/): after a filter returns nothing, people wonder "Did an error occur? Did I set the wrong filters or parameters?", and "Totally empty states cause confusion" | 2026-10-18 |
+
+## Loading states
+
+| Bullet                         | Source                                                                                                                                                                                                  | Read       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Indicator past one second      | [Progress indicators](https://www.nngroup.com/articles/progress-indicators/): "Use a progress indicator for any action that takes longer than about 1.0 second"                                         | 2026-10-18 |
+| Mark stale content as updating | [Progress indicators](https://www.nngroup.com/articles/progress-indicators/): "Without any visual change from the system, most users will assume the action was not registered and they will try again" | 2026-10-18 |
+
+## Destructive actions
+
+| Bullet                  | Source                                                                                                                                                                                     | Read       |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- |
+| Confirm unless undoable | [Confirmation dialogs](https://www.nngroup.com/articles/confirmation-dialog/): "consider a confirmation dialog before actions that cannot be undone", and "do try your best to offer undo" | 2026-10-18 |
+
+## Element states
+
+| Bullet                      | Source                                                                                                                                                                                                                          | Read       |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Distinct interaction states | [Visibility of system status](https://www.nngroup.com/articles/visibility-system-status/): "Did the system actually catch that button press", and an element with no pressed or hover response leaves the person unable to tell | 2026-10-18 |
+| No intermediate flash       | [Cumulative Layout Shift](https://web.dev/articles/cls): "Unexpected layout shifts can disrupt the user experience", caused by content "dynamically added to the page before existing content"                                  | 2026-10-18 |
+
+## Overflow
+
+| Bullet                        | Source                                                                                                                                                                                                                                  | Read       |
+| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Ellipsis over overflow        | [text-overflow](https://developer.mozilla.org/en-US/docs/Web/CSS/text-overflow): `text-overflow: ellipsis` with `overflow: hidden` and `white-space: nowrap` clips text at the box with a visible marker                                | 2026-10-18 |
+| Never `title` alone           | [The title attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/title): "Use of the title attribute is highly problematic for" people using touch-only devices, keyboards, and assistive technology | 2026-10-18 |
+| Focus rings clear of clipping | House choice: a ring cut off by a parent's `overflow` shows on the middle items of a list and vanishes on the first and last, so the focus indicator fails exactly where the list ends                                                  | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the source
+
+- Replaced the `title`-or-expand truncation bullet with the never-`title`-alone bullet, since MDN calls the attribute "highly problematic" for touch and keyboard users.
+- Qualified "feedback must auto-dismiss after 2 to 3 seconds" against WCAG 2.2.1, since a message carrying the only copy of its information sets a time limit on reading it.
+- Rewrote "do not show stale content while new content is loading", which offered keeping the previous content as its own alternative, to the marking bullet.
+
+### Moved to a sibling rule
+
+- Moved "confirmation UI must be dismissible via Escape" and "inline confirmation rows must be dismissible via Escape" to the Escape bullet in `keyboard.md`.
+- Moved "status indicators must reset to a neutral state when their source input changes" to `forms.md`, which held the same bullet for derived values.
+- Cut "confirmation labels and destructive buttons must have sufficient contrast", which `a11y.md` holds for every control.
+
+### Cut without a source or a bug class
+
+- Cut "disabled elements must use muted colors and `cursor: not-allowed`", a convention Claude already follows that no source sets.
+- Cut "use CSS transitions or deferred rendering to prevent visible flicker", merged into the intermediate flash bullet as its remedy.
+
+### Merged or reworded
+
+- Merged the `## Inline confirmations`, `## Status indicators`, `## State transitions`, `## Interactive element states`, and `## Scroll and clipping` H2s into six, the merge the plan suggested.
+- Merged "every list must handle the empty state" with "empty states must include a next action", and the two filter bullets into one.
+- Merged "do not rely on a single state to communicate interactivity" into the distinct states bullet.
+- Reworded "every async operation must show a loading indicator" to NN/g's one second threshold, since a shorter spinner distracts.

package/governance/rules/lang/go.md

@@ -1,40 +1,31 @@
 ---
-description: Enforce Go naming, error wrapping, context passing, and package boundaries
+description: Enforce Go error wrapping, context passing, interface placement, and package boundaries
 paths:
   - '**/*.go'
 ---
 
 # Go standards
 
-## Casing conventions
-
-- Use `MixedCaps` for exported names and `mixedCaps` for unexported ones. Never use underscores in a Go identifier.
-- Name packages with one short lowercase word. Do not use `util`, `common`, or `helpers` as a package name.
-- Do not repeat the package name in an exported identifier (`user.New`, not `user.NewUser`).
-- Keep initialisms in one case (`userID`, `HTTPClient`), never `userId` or `HttpClient`.
-
 ## Errors
 
-- Return an error as the last result value.
 - Wrap an error with `fmt.Errorf("...: %w", err)` when adding context.
-- Match an error with `errors.Is` or `errors.As`. Never compare `err.Error()` strings.
-- Never discard an error with `_`.
-- Do not `panic` for a failure a caller can expect. Reserve it for a broken invariant.
+- Match an error with `errors.Is` or `errors.As`. Never compare with `==` or on `err.Error()` strings, which miss a wrapped error.
+- Never discard an error with `_`. Handle it, return it, or panic on a broken invariant.
+- Return an `error` for a failure a caller can expect. Reserve `panic` for a broken invariant.
 
 ## Context
 
 - Pass `context.Context` as the first parameter, named `ctx`.
-- Never store a `context.Context` in a struct field.
+- Never store a `context.Context` in a struct field. Pass it to each function that needs it.
 - Do not pass a `nil` context. Use `context.TODO()` where none is available yet.
 
 ## Interfaces
 
-- Declare an interface in the package that consumes it, not the one that implements it.
-- Keep an interface to the methods its consumer calls.
+- Declare an interface in the package that consumes it, holding only the methods that consumer calls.
 - Accept interfaces and return concrete types.
 
 ## Packages
 
 - Place code no other module may import under `internal/`.
 - Do not perform side effects in `init`. Wire dependencies explicitly from `main`.
-- Do not hold mutable state in a package-level variable.
+- Do not hold mutable state in a package-level variable. Pass it through a struct the caller owns.

package/governance/rules/lang/php.md

@@ -19,7 +19,7 @@ paths:
 
 ## Data shapes
 
-- Use a backed `enum` for a closed set over class constants.
+- Use an `enum` for a closed set over class constants, backed by a string or int when the value is stored or serialized.
 - Use `readonly` properties or a `readonly` class for value objects.
 - Declare classes `final` unless they are designed for extension.
 - Do not pass an associative array across a public boundary where a typed object fits.
@@ -27,5 +27,5 @@ paths:
 ## Errors
 
 - Throw a domain exception for a failure. Do not return `false` or `null` to signal one.
-- Never suppress an error with the `@` operator.
-- Do not use `extract`, variable variables, or `eval`.
+- Never suppress an error with the `@` operator. Check the condition first or catch the exception.
+- Do not use `extract`, variable variables, or `eval`. Name each variable and call each function directly.

package/governance/rules/lang/python.md

@@ -1,31 +1,22 @@
 ---
-description: Enforce strict Python type hints, casing, and import patterns
+description: Enforce strict Python type hints, exception handling, data shapes, and import patterns
 paths:
   - '**/*.py'
 ---
 
 # Python standards
 
-## Casing conventions
-
-- Use `snake_case` for modules, functions, variables, and methods.
-- Use `PascalCase` for classes, type aliases, `TypeVar`, and `ParamSpec`.
-- Use `UPPER_SNAKE_CASE` for module-level constants and environment variables.
-- Use `_leading_underscore` for module-private names. Reserve `__dunder__` for the standard protocol.
-
 ## Type hints
 
-- Annotate all public functions, methods, and class attributes.
-- Use `X | None` over `Optional[X]` and `X | Y` over `Union[X, Y]`.
-- Use built-in generics (`list[str]`, `dict[str, int]`) over `typing.List` and `typing.Dict`.
-- Avoid `from __future__ import annotations` in modules that pydantic, FastAPI, or other libraries introspect at runtime.
-- Use `typing.Protocol` for structural typing over abstract base classes for interfaces.
-- Do not use `Any`. Reach for `object` or `typing.cast` at boundaries instead.
+- Annotate every public function and method, since a type checker skips the body of an unannotated function.
+- Use `X | None`, `X | Y`, and built-in generics such as `list[str]` over `Optional`, `Union`, and `typing.List`.
+- Do not add `from __future__ import annotations`. Python plans to deprecate and remove it.
+- Use `typing.Protocol` for an interface a class satisfies by shape, over an abstract base class it must subclass.
+- Type a value that can be anything as `object` and narrow it. Never use `Any`, which turns checking off.
 
 ## Errors
 
-- Raise specific built-in exceptions over bare `Exception`.
-- Define a project-rooted exception hierarchy for domain errors.
+- Raise a specific built-in exception or one from a project-rooted hierarchy, never bare `Exception`.
 - Catch the narrowest exception class. Never use bare `except:`.
 - Re-raise with `raise ... from err` to preserve the cause chain.
 
@@ -37,6 +28,6 @@ paths:
 
 ## Imports and modules
 
-- Use absolute imports rooted at the package. Do not use parent-relative (`from ..pkg`) imports.
+- Use absolute imports rooted at the package over relative ones.
 - Do not alias imports to shorten internal names. Ecosystem conventions (`numpy as np`, `pandas as pd`) are exceptions.
-- Do not place executable code at module scope. Guard with `if __name__ == "__main__":`.
+- Do not place executable code at module scope. Guard it with `if __name__ == "__main__":` and call a `main` function.

package/governance/rules/lang/typescript.md

@@ -1,5 +1,5 @@
 ---
-description: Enforce strict TypeScript type safety and patterns
+description: Enforce strict TypeScript type safety, declarations, and import patterns
 paths:
   - '**/*.ts'
   - '**/*.tsx'
@@ -7,34 +7,24 @@ paths:
 
 # TypeScript standards
 
-## Casing conventions
+## File names
 
-- Use `kebab-case` for filenames and directories.
-- Use `camelCase` for variables, functions, and methods.
-- Use `PascalCase` for types, interfaces, classes, and components.
-- Use `UPPER_SNAKE_CASE` for constants and environment variables.
+- Use `kebab-case` for filenames and directories, since a case-only difference resolves on macOS and fails on Linux.
 
 ## Type declarations
 
-- Enforce explicit types or strict inference.
-- Use `unknown` over `any`.
-- Use `interface` for object shapes and component props.
-- Use `type` for unions, intersections, and utility types.
-- Do not prefix interfaces with `I`.
-- Use constant objects or union types instead of `enum`.
+- Use `unknown` over `any`, and narrow it before use.
+- Use `interface` for an object shape until it needs a feature only `type` has, such as a union or a mapped type.
+- Use a constant object with `as const` or a union of literals instead of `enum`.
 
 ## Type safety
 
-- Use type guards and narrowing over type assertions.
-- Use discriminated unions for error handling over throwing exceptions.
-- Use built-in utility types (`Partial`, `Pick`, `Omit`) over manual type manipulation.
-- Prefer `readonly` properties for data objects.
-- Do not use non-null assertions.
-- Use `Promise.all()` for independent async operations.
+- Narrow with a type guard or a runtime check over a type assertion or a non-null `!`, neither of which checks at runtime.
+- Run independent async operations through `Promise.all()` rather than awaiting each in turn.
 
 ## Imports and configuration
 
-- Use absolute imports mapping `@/` to `src/`.
+- Import through the `@/` alias where tsconfig.json and the bundler both map it to `src/`, over a `../../` chain.
 - Import from the module's source file directly over barrel `index` re-exports.
 - Use `import type` for type-only imports.
 - Enable `strict: true` in tsconfig.json with no exceptions.

package/governance/rules/lib/database.md

@@ -14,22 +14,22 @@ paths:
 ## Schema changes
 
 - Express every schema change as a migration file committed to version control.
-- Ship a tested rollback path with every migration that changes a schema.
+- Ship a way back with every schema migration, as a down step or a forward migration that reverses it.
 - Never alter a deployed schema outside a migration.
 - Never edit a migration that has run in a shared environment. Add a new one.
-- Separate a destructive migration from the deploy that stops reading the dropped column.
+- Drop a column or table only after a deploy that stops reading and writing it.
 
 ## Query construction
 
 - Pass every runtime value as a bound parameter.
 - Never interpolate, concatenate, or format a value into a statement string.
-- Name the columns a read needs. Do not select every column by wildcard.
+- Map a table name, column, or sort direction through an allow-list, since none of them can be bound.
 
 ## Transactions
 
 - Give each transaction one owner that opens it, commits it, and rolls it back.
-- Never open a transaction inside a function that was handed one.
-- Keep network calls, queue publishes, and filesystem writes outside an open transaction.
+- Never commit a transaction a function was handed. Take a savepoint, such as a nested `atomic`, for a partial rollback.
+- Keep network calls, queue publishes, and filesystem writes outside an open transaction, running them after commit.
 
 ## Access patterns
 

package/governance/rules/lib/e2e-reliability.md

@@ -8,13 +8,12 @@ paths:
 
 ## Waiting
 
-- Settle on the condition a step waits for. Use `expect.poll` or a web-first assertion ahead of any read.
+- Settle on the condition a step waits for with a web-first assertion or `expect.poll`, never `page.waitForTimeout`.
 - Reserve a fixed duration for an assertion that nothing happened across a window.
-- Bound every settle with an explicit timeout.
+- Bound every settle with an explicit timeout. `toPass` defaults to none and ignores the expect timeout.
 - Do not raise a timeout to clear a failure that reproduces under load. Replace the wait with a settle.
-- Do not read a value once after a pause. Poll it.
 - Settle a smooth scroll on the `scrollend` event. Fall back to a stillness window only when the target was already in view.
-- Run with motion reduced unless the test asserts motion, and opt back in per test.
+- Run with `reducedMotion: 'reduce'` unless the test asserts motion, and opt back in per test.
 
 ## Falsifiable guards
 
@@ -26,9 +25,8 @@ paths:
 ## Reproducing a failure that only appears in CI
 
 - Reproduce under `Emulation.setCPUThrottlingRate` rather than by rerunning the gate.
-- Read the state the assertion does not: which markers were set, which listeners fired, how far a transition ran.
+- Read the failure's trace for the state the assertion does not read, such as which markers were set and which listeners fired.
 - Vary the condition under suspicion deliberately. Do not compare counts across runs that differed in something uncontrolled.
-- Read the check conclusion as its own act. A green diff review reports nothing about the gate.
 
 ## Authority
 

package/governance/rules/lib/pydantic.md

@@ -8,31 +8,29 @@ paths:
 
 ## Models
 
-- Use `pydantic.BaseModel` over `dataclass` at I/O and API boundaries.
-- Use `model_config = ConfigDict(...)` over the legacy nested `Config` class.
-- Set `extra="forbid"` on models receiving external input to prevent data pollution.
-- Use `Field(...)` for defaults, descriptions, and constraints over docstring conventions.
+- Use `pydantic.BaseModel` over a standard library `dataclass` at I/O and API boundaries, since a `dataclass` validates nothing.
+- On Pydantic 2, configure a model with `model_config = ConfigDict(...)`, never the deprecated nested `Config` class.
+- Set `extra="forbid"` on a model receiving external input, since the default ignores an unknown key silently.
+- Declare a constraint with `Field(...)`, such as `gt=0`, so validation enforces it rather than a docstring.
 
 ## Validation
 
-- Use `Model.model_validate(data)` over `Model(**data)` for untrusted dict input.
-- Use `Model.model_validate_json(s)` over `json.loads` followed by validation.
-- Use `@field_validator` over the legacy `@validator`.
-- Use `@model_validator(mode="after")` for cross-field invariants.
+- Validate an untrusted dict with `Model.model_validate(data)`, and a JSON string with `Model.model_validate_json(s)` rather than `json.loads` first.
+- On Pydantic 2, write `@field_validator` and `@model_validator`, never the deprecated `@validator` or `@root_validator`.
+- Check a cross-field invariant in `@model_validator(mode="after")`.
 
 ## Types
 
-- Use `AnyUrl`, `EmailStr`, `SecretStr`, and `PositiveInt` over hand-rolled regex constraints.
-- Use `Annotated[T, Field(...)]` over default-value `Field(...)` for reusable constrained types.
-- Do not use `Any` in fields. Reach for `JsonValue` or a `Union` of concrete types.
+- Use `SecretStr` for a credential, so its value stays out of logs and tracebacks.
+- Use a constrained type such as `PositiveInt` or `EmailStr` over a hand-rolled regex.
+- Share a constrained type as `Annotated[T, Field(...)]`.
+- Never type a field `Any`, which allows any value including `None`. Use `JsonValue` or a union of concrete types.
 
 ## Settings
 
-- Use `pydantic_settings.BaseSettings` for env-driven configuration.
-- Load environment through a single `Settings` model. Do not read `os.environ` directly elsewhere.
+- Load environment through one `pydantic_settings.BaseSettings` model. Never read `os.environ` directly elsewhere.
 
 ## Serialization
 
-- Use `model.model_dump(mode="json")` over the legacy `.dict()`.
-- Use `model.model_dump_json()` over `json.dumps(model.dict())`.
-- Use `by_alias=True` when serializing to external schemas with non-Python field names.
+- On Pydantic 2, serialize with `model_dump(mode="json")` or `model_dump_json()`, never the deprecated `.dict()` or `.json()`.
+- Pass `by_alias=True` when serializing to an external schema, since a dump ignores aliases by default.

package/governance/rules/lib/security-server.md

@@ -19,7 +19,7 @@ paths:
 
 ## Credentials
 
-- Hash passwords with a memory-hard algorithm and a per-record salt. Never store a reversible password.
+- Hash passwords with Argon2id, or scrypt or bcrypt where it is missing, and a per-password salt. Never store a reversible password.
 - Compare tokens, signatures, and password hashes with a constant-time function.
 - Expire and revoke sessions and refresh tokens on the server. Do not rely on client-side deletion.
 
@@ -27,7 +27,7 @@ paths:
 
 - Read every secret from the environment or a secret manager at runtime.
 - Never commit a secret, connection string, or private key to the repository.
-- Never return a secret, connection string, or internal hostname in a response body.
+- Never return a secret, connection string, stack trace, or internal hostname in a response body.
 
 ## Abuse limits
 
@@ -37,5 +37,5 @@ paths:
 
 ## Transport
 
-- Serve every route over TLS and reject plaintext requests.
-- Restrict CORS to an explicit origin list. Never reflect the request origin or pair a wildcard with credentials.
+- Serve every route over TLS. Fail a plaintext API request rather than redirecting it.
+- List CORS origins explicitly whenever credentials are allowed, since a wildcard is refused then. Never reflect the request origin.

package/governance/rules/lib/security-web.md

@@ -9,24 +9,20 @@ paths:
 
 # Web security standards
 
-## Link safety
-
-- Add `rel="noopener noreferrer"` to all external links with `target="_blank"`.
-
 ## Content sanitization
 
-- Sanitize all user-generated content rendered via `dangerouslySetInnerHTML` using DOMPurify or equivalent.
-- Never use `dangerouslySetInnerHTML` without sanitization.
+- Sanitize HTML with DOMPurify before passing it to `dangerouslySetInnerHTML`, `innerHTML`, or `set:html`. Never render it raw.
+- Allow only `http:` and `https:` in a user-supplied URL before rendering it in `href` or `src`.
 
 ## Input validation
 
-- Validate all URL parameters and query strings using schema validation before use.
+- Parse URL parameters and query strings through a schema before use.
 
 ## Storage and tokens
 
-- Do not store sensitive data (tokens, passwords, PII) in `localStorage` or `sessionStorage`.
-- Store authentication tokens in httpOnly cookies over exposing them to JavaScript.
+- Never store a session token, password, or personal data in `localStorage` or `sessionStorage`, which any script on the page can read.
+- Keep an authentication token in an `HttpOnly` cookie, out of reach of JavaScript.
 
 ## Third-party scripts
 
-- Audit and pin versions for all third-party scripts loaded in the browser.
+- Pin a third-party script to a version and load it with an `integrity` hash.

package/governance/rules/lib/tanstack-query.md

@@ -9,24 +9,22 @@ paths:
 
 ## Query conventions
 
-- Define query keys as `readonly` tuple constants.
-- Co-locate query keys with their query functions.
-- Encapsulate each query in a custom `use*Query` hook over calling `useQuery` inline in components.
-- Set explicit `staleTime` per query based on data volatility over relying on the default.
+- Define a query's key and function together with `queryOptions()`, and reuse that object at every call site.
+- Include every variable the query function reads in its query key.
+- Set `staleTime` per query from how often its data changes, since the default treats cached data as stale at once.
+- Throw from a query function on a response that is not `ok`, since `fetch` does not reject on an HTTP error.
 
 ## Mutations
 
-- Use `useMutation` for all write operations.
-- Never mutate data outside the mutation lifecycle.
-- Invalidate related query keys in `onSuccess` over manual cache updates unless optimistic UI is required.
-- Handle `onError` at the mutation site with user-facing feedback.
+- Write data through `useMutation`, never by calling the API from an event handler and patching the cache.
+- Invalidate the related query keys in `onSuccess` and return that promise. Reserve `setQueryData` for an optimistic update.
+- Handle `onError` at the mutation site with feedback the user sees.
 
 ## Cache management
 
-- Use `queryClient.invalidateQueries` over `queryClient.setQueryData` unless implementing optimistic updates.
-- Prefetch predictable navigations with `queryClient.prefetchQuery` at route boundaries.
+- Prefetch a predictable navigation's data in its route loader.
 
 ## Separation of concerns
 
-- Keep query functions as pure async data fetchers with no UI logic or side effects.
-- Use the query `enabled` option for conditional fetching over `useEffect`.
+- Keep a query function a pure data fetcher with no UI logic or side effects, since a background refetch runs it again.
+- Use the query `enabled` option for a conditional or dependent fetch, never `useEffect`.

package/governance/rules/lib/test-scope.md

@@ -9,9 +9,9 @@ paths:
 ## Selecting a run
 
 - Narrow an end-to-end run by spec path or by test name. Never narrow it by engine.
-- Run one named test while iterating on a behavior: `bun run test:e2e -- -g '<name>'`.
-- Run one surface while iterating on that surface: `bun run test:e2e -- e2e/<area>.spec.ts`.
-- Run `bun run test:e2e:changed` to select specs from the import graph.
+- Run `playwright test -g '<name>'` for one named test while iterating on a behavior.
+- Run `playwright test e2e/<area>.spec.ts` for one surface while iterating on that surface.
+- Run `playwright test --only-changed` to select the specs a branch changed.
 - Run the whole suite before pushing.
 - Pass `--project` in a local run only to reproduce a failure that engine has already reported. The CI matrix passes it on every job, one engine per leg, which is the gate rather than a narrowed run.
 - Do not add a script that pins a default run to one engine.
@@ -19,6 +19,6 @@ paths:
 ## Instruments
 
 - Answer a question about the running page with a script against the dev server rather than with the suite.
-- Do not enable `fullyParallel` in `playwright.config.ts`.
+- Do not enable `fullyParallel` in the Playwright config.
 - Follow `.claude/rules/canon/ui/surface-capture.md` for capture scope.
 - Follow `.claude/rules/canon/lib/e2e-reliability.md` for waits and guards.

package/governance/rules/lib/testing-go.md

@@ -13,7 +13,6 @@ paths:
 ## Framework
 
 - Use the standard `testing` package. Do not add an assertion library for what `t.Errorf` and `t.Fatalf` already state.
-- Place a test beside the code it tests, in a `_test.go` file of the same package.
 - Use an external `<pkg>_test` package when a test should see only the exported API.
 
 ## Table-driven cases
@@ -24,7 +23,7 @@ paths:
 ## Helpers and setup
 
 - Call `t.Helper()` first in every test helper.
-- Use `t.Cleanup` over `defer` for teardown a helper registers.
+- Use `t.Cleanup` over `defer` for teardown a helper registers, since a `defer` runs when the helper returns.
 - Use `t.TempDir` and `t.Setenv` over hand-rolled temp directories or environment stashes.
 - Use `net/http/httptest` over a real listener.
 

package/governance/rules/lib/testing-php.md

@@ -15,16 +15,15 @@ paths:
 
 - Use PHPUnit for all tests.
 - Declare each test class `final` and extend `PHPUnit\Framework\TestCase`.
-- Place tests under `tests/`, mirroring the `src/` namespace layout, in files named `*Test.php`.
 
 ## Attributes
 
-- Use attributes (`#[Test]`, `#[DataProvider]`, `#[CoversClass]`) over docblock annotations.
-- Use a static data provider method for table-driven cases over per-case test methods.
+- On PHPUnit 10 or later, use attributes (`#[Test]`, `#[DataProvider]`, `#[CoversClass]`) over docblock annotations, which PHPUnit 12 no longer reads.
+- Use a `public static` data provider method for table-driven cases over per-case test methods.
 
 ## Assertions and doubles
 
-- Use `assertSame` over `assertEquals`.
-- Use `expectException` over `try` and `catch` for expected exceptions.
+- Use `assertSame` over `assertEquals`, which compares with `==`.
+- Call `expectException` before the throwing call, over `try` and `catch`, for an expected exception.
 - Use `createStub` where no interaction is asserted. Reserve `createMock` for asserting a call.
 - Do not make real network calls. Use a fake or a stubbed client.