@erclx/canon 5.43.0 → 5.45.0

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.

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

@@ -10,35 +10,27 @@ paths:
 
 ## Framework
 
-- Use `pytest` for all tests. Do not use `unittest.TestCase`.
-- Place tests under `tests/`, mirroring the `src/` package layout.
-- Name files `test_*.py` and test functions `test_*`.
+- Write tests as plain `pytest` functions, never `unittest.TestCase` subclasses, which lose fixtures and parametrization.
 
 ## Fixtures
 
-- Use `@pytest.fixture` over setup and teardown methods.
-- Place shared fixtures in `conftest.py` at the narrowest scope that needs them.
-- Set `scope=` (`"session"`, `"module"`, `"function"`) explicitly when reuse matters.
-- Use `tmp_path` and `monkeypatch` over hand-rolled temp directories or env stashes.
+- Write setup and teardown as a `@pytest.fixture` that yields, over setup and teardown methods.
+- Place a shared fixture in the `conftest.py` of the narrowest directory whose tests need it.
+- Widen a fixture's `scope=` past the `function` default only for state no test mutates.
+- Use `tmp_path` and `monkeypatch` over hand-rolled temp directories or environment stashes, since both undo themselves.
 
 ## Parametrize
 
 - Use `@pytest.mark.parametrize` for table-driven cases over per-case test functions.
-- Use `ids=` to label parametrized cases when their repr is unclear.
 
 ## Async
 
-- Mark async tests with `@pytest.mark.asyncio` or configure `asyncio_mode = "auto"`.
-- Do not start a fresh event loop inside tests.
+- Mark each async test `@pytest.mark.asyncio`, or set `asyncio_mode = "auto"`, since strict mode runs only marked tests.
+- Run on the event loop `pytest-asyncio` provides. Never call `asyncio.run()` or create a loop inside a test.
 
 ## Assertions and mocks
 
-- Use plain `assert` over `self.assertEqual`. Pytest rewrites assertions for readable diffs.
-- Use `pytest.raises(...)` over `try/except` for expected exceptions.
-- Use `monkeypatch.setattr` or `unittest.mock.patch` over ad hoc module rewrites.
-- Do not make real network calls. Use `responses`, `httpx_mock`, or fakes.
-
-## Conventions
-
-- Arrange, act, assert per test, with one logical assertion group.
-- Use descriptive `test_*` names that read as the assertion. Do not prefix with `should_`.
+- Use plain `assert`, which pytest rewrites to report the values, over `self.assertEqual`.
+- Use `pytest.raises(...)` over `try` and `except` for an expected exception.
+- Patch with `monkeypatch.setattr` or `unittest.mock.patch`, never by assigning a module attribute by hand.
+- Do not make real network calls. Use `responses`, `pytest-httpx`, or a fake.

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

@@ -12,29 +12,20 @@ paths:
 ## Unit and integration
 
 - Use Vitest for unit and integration tests.
-- Co-locate unit tests with their respective components.
-- Use `userEvent` over synthetic events for interaction simulation.
-- Use MSW for network mocking. Do not mock fetch or axios manually.
-- Select elements by accessibility attributes first (`getByRole`, `getByLabelText`).
+- Simulate interaction with `userEvent` over `fireEvent`, since it refuses what a browser would, such as a click on a hidden element.
+- Mock the network with MSW. Never mock `fetch` or axios by hand, and never let a unit test make a real call.
+- Query by role or label first, such as `getByRole` and `getByLabelText`, and by test ID only when neither matches.
 
 ## End-to-end
 
 - Use Playwright for end-to-end tests.
-- Place all Playwright tests within the `e2e/` directory.
-- Never place Playwright tests inside `src/`.
-- Scope the three rules above to tests the Playwright runner executes. A Vitest test importing a browser driver to exercise project code stays beside its module, where Vitest looks for it.
-- Keep specs apart from their fixtures, page objects, and helpers inside `e2e/`. Load the `canon:codebase-layout` skill for the folder shape.
+- Place every test the Playwright runner executes under `e2e/`, never `src/`. A Vitest test that drives a browser stays beside its module.
 
 ## Timers and async
 
-- Never use `vi.useFakeTimers()` in `beforeEach` when tests use `waitFor`, `act`, or `userEvent`.
-- Scope fake timers to the individual test that needs them.
-- Restore real timers with `vi.useRealTimers()` in a matching `afterEach`.
+- Pass `advanceTimers: vi.advanceTimersByTime` to `userEvent.setup()` whenever fake timers are on.
+- Restore real timers with `vi.useRealTimers()` in `afterEach`, after `vi.runOnlyPendingTimers()`.
 
 ## Conventions
 
-- Use `.test.ts` / `.test.tsx` for unit tests.
-- Use `.spec.ts` / `.spec.tsx` for integration tests and for Playwright tests under `e2e/`.
-- Do not make real network calls in unit tests.
-- `describe()` labels use the exact identifier of the subject under test in its natural casing.
-- `it()` descriptions use "should" + sentence case.
+- Name a unit test `.test.ts` or `.test.tsx`, and an integration or Playwright test `.spec.ts` or `.spec.tsx`.

package/governance/rules/lib/zod.md

@@ -9,17 +9,15 @@ paths:
 
 ## Type inference
 
-- Use `z.infer<typeof Schema>` to generate TypeScript types (Single Source of Truth).
-- Do not manually declare interfaces that duplicate Zod schemas.
-- Do not export the runtime Schema if only the inferred Type is required by consumers.
+- Derive a schema's type with `z.infer<typeof Schema>`, never a hand-written interface that duplicates the schema.
 
 ## Boundary validation
 
-- Use `.strict()` for untrusted external API boundaries to prevent data pollution.
-- Use `.parse()` for blocking validation (env vars) and `.safeParse()` for recoverable flows (forms).
-- Restrict `z.coerce` to I/O boundaries (e.g., URL params). Never use it for internal data flow.
+- Parse untrusted input with `z.strictObject()` so an unknown key fails, never with a method the Zod 4 changelog marks legacy.
+- Narrow a schema with `.pick()` or `.omit()`, never by passing unknown keys through with `z.looseObject()`.
+- Call `.parse()` where a failure should throw, and `.safeParse()` where the caller recovers, such as a form.
+- Restrict `z.coerce` to string input at an I/O boundary such as URL params, since it converts with `String()` or `Boolean()`.
 
 ## Schema safety
 
-- Use `z.unknown()` for truly ambiguous inputs instead of `z.any()`.
-- Prefer `.strict()` at boundaries or explicit `.pick()`/`.omit()` over `.passthrough()`.
+- Use `z.unknown()` for an input of unknown shape, never `z.any()`, which infers `any` and switches off checking downstream.

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

@@ -16,14 +16,12 @@ paths:
 - Write a comment only when it records a fact the reader cannot recover from the code: an external contract, a rejected alternative, or the reason a surprising line is correct.
 - Do not restate in prose what the line beside it already says.
 - Do not comment a self-contained function whose signature and body already carry its behavior.
-- Let comment density follow how much of a file's behavior is decided outside that file. Treat density as an outcome, never as a target.
-- Do not add or delete a comment to move a file toward a density figure.
+- Do not add or delete a comment to move a file toward a density figure, since density follows how much of its behavior is decided outside it.
 
 ## What a comment may claim
 
-- State only what is true of the code as written.
+- Keep each comment true of the code as written, and update or delete one a change invalidates in that same change.
 - Describe a function's contract and its constraints, never its steps line by line.
-- Update or delete an invalidated comment in the same change that invalidates it.
 - Do not name a person, a ticket, or a date in place of the fact itself.
 
 ## What never goes in a comment

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

@@ -1,5 +1,5 @@
 ---
-description: Keep comments terse in dotfiles, config, and workflow files
+description: Keep comments in dotfiles, config, and workflow files to what a key does or accepts
 paths:
   - '**/.env*'
   - '**/.gitignore'
@@ -16,7 +16,4 @@ paths:
 
 ## Comments
 
-- Keep each comment to one short line. Do not wrap a single key in a multi-line explanation.
-- Prefer a one-word category label over a sentence for a group header.
-- Match the comment density of the surrounding file. Do not add a verbose comment next to terse ones.
 - Comment what a key does or its allowed values. Do not restate the key name.

package/governance/rules/tooling/dependencies.md

@@ -15,7 +15,7 @@ paths:
 ## Declaration
 
 - Declare a package in the project manifest before importing it anywhere in the source.
-- Add a package with the package manager command that writes the manifest and the lockfile together, such as `bun add` or `uv add`. Never hand-edit the manifest and never install without recording the result.
+- Add a package with the command that writes the manifest and the lockfile together, such as `bun add` or `uv add`. Re-lock in the same change after any hand edit to the manifest.
 - Commit the lockfile with the manifest change in the same commit.
 - Declare a package used only by tests, builds, or tooling as a development dependency.
 - Never import a package that arrives only as a transitive dependency of another package.

package/governance/rules/ui/a11y.md

@@ -1,5 +1,5 @@
 ---
-description: Keyboard interaction, focus management, and ARIA accessibility for rendered UI
+description: Semantics, text alternatives, contrast, and reflow for rendered UI
 paths:
   - '**/*.tsx'
   - '**/*.jsx'
@@ -8,56 +8,27 @@ paths:
   - '**/*.css'
 ---
 
-# Accessibility and keyboard standards
+# Accessibility standards
 
-## Focus styles
+## Semantics
 
-- All interactive elements must use the project focus ring. Do not define per-component focus styles.
-- Never apply `outline-none` without a custom focus ring in the same rule.
-- Focus ring must have 3:1 contrast against its background in both light and dark modes.
+- Use a native `<button>` or `<a>` over a `<div>` or `<span>` carrying a click handler, since the native element brings its role, focus, and keyboard activation.
+- Spell an attribute the way the file's syntax spells it, being `onclick` and `tabindex` in HTML and Astro markup and `onClick` and `tabIndex` in JSX.
+- Give a custom control the role its pattern names, such as `combobox` or `listbox`, and keep `aria-expanded`, `aria-selected`, and `aria-checked` in step with what it shows.
+- Give an interactive element with no visible text label a name through `aria-label` or `aria-labelledby`.
 
-## Keyboard interaction model
+## Text alternatives
 
-- Tab / Shift+Tab: move focus sequentially through interactive elements in DOM order.
-- Enter: activates buttons and links, submits forms.
-- Space: activates buttons and checkboxes, toggles selection in listboxes.
-- Arrow keys: navigate within composite widgets. Do not let them exit the widget.
-- Escape: closes any overlay, popover, dialog, or dropdown. Cancels in-progress edits.
-- Do not introduce non-standard key bindings for common actions.
-- Give every author-defined drag a single-pointer alternative and a keyboard path, such as move buttons or arrow-key reordering (WCAG 2.2 Dragging Movements, 2.5.7).
+- Give every `<img>` an `alt`, and use `alt=""` for a decorative image.
+- Describe what an image means, or the action an icon control takes, never its appearance. Do not prefix it with "Image of" or "Photo of".
 
-## Pointer targets
+## Contrast and color
 
-- Size a web pointer target at least 24 by 24 CSS pixels, or space it so a 24 pixel circle centered on it touches no other target (WCAG 2.2 Target Size Minimum, 2.5.8).
-- Size a native touch target at the platform figure, 44 points on iOS and 48 dp on Android. Do not apply the web figure to native, and do not apply the native figure as the web minimum.
-
-## Composite widgets
-
-- Roving tabindex for interactive collections: one item in the tab sequence at a time.
-- Combobox: arrow keys navigate options, Enter selects, Escape closes, typing filters.
-
-## Focus management
-
-- Move focus into any overlay, popover, or dialog on open. Return focus to the trigger on close.
-- Never move focus on hover. Only on keyboard input or explicit pointer activation.
-- Do not let a sticky header, footer, or overlay fully cover the focused control. Scroll it into view clear of them (WCAG 2.2 Focus Not Obscured, 2.4.11).
-
-## ARIA semantics
-
-- Use semantic HTML over custom elements: `<button>` over a `<div>` carrying a click handler, `<a>` over a `<span>` carrying one.
-- A `<div>` with a click handler requires a role, a tab index, and keyboard handlers. Use `<button>` instead.
-- Spell an attribute the way the file's syntax spells it: `onclick` and `tabindex` in HTML and Astro markup, `onClick` and `tabIndex` in JSX.
-- Set role on custom controls: `role="combobox"`, `role="listbox"`, `role="menu"`, `role="option"`.
-- Synchronize state attributes with visual state: `aria-expanded`, `aria-selected`, `aria-checked`, `aria-disabled`.
-- Add `aria-label` or `aria-labelledby` to interactive elements with no visible text label.
-- Always provide `alt` on `<img>`. Use `alt=""` for decorative images.
-- Describe the content or function of the image, not its appearance. Do not prefix with "Image of" or "Photo of".
-- Alt text for functional images (icons, buttons) should describe the action, not the graphic.
-- Give the visual boundary of a control and every graphic that carries meaning at least 3:1 contrast against adjacent colors (WCAG Non-text Contrast, 1.4.11).
-- Never make color the only carrier of a state, error, or distinction. Pair it with text, an icon, or a pattern (WCAG Use of Color, 1.4.1).
+- Give a control's visual boundary and every graphic that carries meaning at least 3:1 contrast against adjacent colors (WCAG 1.4.11).
+- Never make color the only carrier of a state, error, or distinction. Pair it with text, an icon, or a pattern (WCAG 1.4.1).
 
 ## Reflow
 
-- Let content reflow at a viewport 320 CSS pixels wide with no loss of content or function and no two-dimensional scrolling. Only content whose meaning depends on both axes, such as a data table, a map, or a diagram, may scroll sideways (WCAG Reflow, 1.4.10, Level AA).
-- Treat 320 as the criterion's own test condition rather than a device width. It is equivalent to a 1280 pixel window at 400 percent zoom, so a layout that breaks there breaks for a person who zooms.
-- Hold the same 320 floor for the content region beside persistent chrome a person can resize. The criterion measures the viewport, so this extension is this rule's own rather than the criterion's: a panel widened to 480 in a 768 window leaves 288 for the content, under the floor at a window the criterion passes. `surface-capture` states where the frame for it gets taken.
+- Let content reflow at 320 CSS pixels wide with no loss and no two-dimensional scrolling, except a data table, map, or diagram (WCAG 1.4.10).
+- Treat 320 as a 1280 pixel window at 400 percent zoom rather than a device width, so a layout breaking there breaks for a person who zooms.
+- Hold the same 320 floor for the content region beside persistent chrome a person can resize. This extends the criterion, which measures the viewport alone.