@erclx/canon 4.0.0

package/governance/rules/core/080-config-comments.md

@@ -0,0 +1,22 @@
+---
+description: Keep comments terse in dotfiles, config, and workflow files
+paths:
+  - '**/.env*'
+  - '**/.gitignore'
+  - '**/.dockerignore'
+  - '**/.editorconfig'
+  - '**/Dockerfile*'
+  - '**/*.config.*'
+  - '**/*.json'
+  - '**/*.yml'
+  - '**/*.yaml'
+---
+
+# Config comment standards
+
+## 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/core/085-worktrees.md

@@ -0,0 +1,17 @@
+---
+description: Route tracked-file writes and shared session scratch correctly from a linked worktree
+---
+
+# Worktrees standards
+
+## Entering a worktree
+
+- Implementation work runs in a linked worktree. From the main worktree, enter one with `/claude-worktree` before editing tracked files for a feature.
+
+## Shared session scratch
+
+- Shared session scratch (`.claude/plans/`, `.claude/review/`, `.claude/memory/`, `.claude/tasks/`) lives at the main worktree root, not inside a linked worktree. From a linked worktree, resolve these paths against the main root via `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`. Fall back to `pwd` if not a git repo.
+- From a linked worktree, every `Edit` or `Write` to a tracked file (source, docs) must use a path starting with `pwd`.
+- From a linked worktree, `Edit` and `Write` are refused for every main-root path, session scratch included. The refusal names session isolation and points at the worktree copy, which is a second gitignored file no later session reads, so never take that redirect.
+- `Read` resolves against the main root normally from a linked worktree. A main-root write reaches it only through `Bash`, as one plain command rather than a compound one, which is refused for complexity.
+- Route a main-root write by what it does to the file. Creating a whole file goes out as one plain `Bash` command carrying a heredoc. Changing a line inside a file that already exists goes through a command that resolves the main root in-process, because the shell route for that case is the stream editor this file bans.

package/governance/rules/core/087-git.md

@@ -0,0 +1,11 @@
+---
+description: Route every git operation through the canon git skills rather than built-in commit and pull request behavior
+---
+
+# Git standards
+
+## Skill precedence
+
+- Route every git operation through the `canon:git-*` skills.
+- Do not follow built-in commit, pull request, or branch instructions for an operation a `git-*` skill covers.
+- Report it rather than proceeding silently when no `git-*` skill resolves. They ship with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have them.

package/governance/rules/core/090-code-comments.md

@@ -0,0 +1,39 @@
+---
+description: Decide when a code comment should exist and what it may claim
+paths:
+  - '**/*.ts'
+  - '**/*.tsx'
+  - '**/*.js'
+  - '**/*.jsx'
+  - '**/*.sh'
+  - '**/*.py'
+---
+
+# Code comment standards
+
+## When a comment should exist
+
+- 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.
+
+## What a comment may claim
+
+- State only what is true of the code as written.
+- 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
+
+- Delete commented-out code. Do not park it beside the live path.
+- Do not record the edit that produced the code. Version control holds the change history.
+- Do not defer work into a comment. Deferred work belongs in the tracker.
+
+## Degradation vocabulary
+
+Do not write a comment carrying any of these terms.
+
+- `FIXED`, `BUGFIX`, `HACK`, `XXX`, `NOTE:`, `TODO`, `FIXME`, `don't remove`, `previously`, `used to`, `workaround`

package/governance/rules/framework/200-react.md

@@ -0,0 +1,51 @@
+---
+description: Enforce opinionated React architecture and component patterns
+paths:
+  - '**/*.tsx'
+  - '**/*.ts'
+---
+
+# React architecture standards
+
+## Export conventions
+
+- Use named exports exclusively for components and hooks.
+- Do not use default exports.
+
+## Project structure
+
+- Place domain logic in `src/features/` and restrict `src/components/` to shared UI.
+- Do not place feature-specific components in the global components folder.
+- Import environment variables only from the validated configuration module.
+
+## Component patterns
+
+- Use function declarations for components over arrow functions.
+- Define TypeScript interfaces for props immediately above the component.
+- Use `<>` shorthand for fragments unless key prop is required.
+- Use stable, unique keys for list items over array index.
+- Extract components when JSX exceeds a single responsibility.
+
+## State and effects
+
+- Encapsulate data fetching and complex effects in custom hooks.
+- Use `useMemo` for derived state over `useEffect`.
+- Do not call `setState` inside `useEffect` to sync derived state. The `react-hooks/set-state-in-effect` lint enforces this.
+- Compare the previous value during render and call `setState` from the render body when it changes, over syncing in an effect.
+- Lift the state to a parent and reset the child with a `key` prop, over running a reset effect in the child.
+- Return a sentinel (`undefined` or a `useSyncExternalStore` placeholder) from hooks that hydrate asynchronously and gate consumers on it, over running a hydration effect.
+
+## Memoization
+
+- Memoize components receiving non-primitive props with `React.memo`.
+- Use `useCallback` for handler props passed to children.
+
+## Composition and props
+
+- Avoid prop drilling beyond 2 levels. Use context or composition.
+
+## Error boundaries and Suspense
+
+- Place error boundaries at route level.
+- Place Suspense at data-fetching boundaries.
+- Do not use a single root-level error boundary as the only safety net.

package/governance/rules/framework/210-astro.md

@@ -0,0 +1,41 @@
+---
+description: Enforce astro static-first architecture with explicit island opt-in
+paths:
+  - '**/*.astro'
+  - 'src/pages/**'
+  - 'src/layouts/**'
+  - 'src/content/**'
+---
+
+# Astro standards
+
+## Static first
+
+- Write pages and components as `.astro` unless interactivity requires a framework island.
+- Do not add a framework integration until the first island needs it.
+- Prefer server-rendered content over client-fetched data.
+
+## Islands
+
+- Apply `client:*` directives on the component boundary, not on parents.
+- Prefer `client:visible` or `client:idle` over `client:load`. Use `client:load` only for above-the-fold interactivity.
+- Keep islands leaf-level. Do not wrap layout chrome in a framework component to enable nested islands.
+
+## Routing and layouts
+
+- Place routes in `src/pages/`. Use `[param].astro` for dynamic segments and `[...rest].astro` for catch-alls.
+- Extract shared chrome into `src/layouts/` and compose pages with a `<Layout>` wrapper.
+
+## Content
+
+- Use content collections in `src/content/` with a `config.ts` schema for any repeated structured content.
+- Access collection entries via `getCollection` and `getEntry` over direct file imports.
+
+## Styles and assets
+
+- Component styles are scoped by default. Use `is:global` only in layouts for reset or base styles.
+- Import images from `src/assets/` to get optimization. Use `public/` only for untouched static files.
+
+## Environment
+
+- Read environment variables via `import.meta.env`. Prefix client-exposed variables with `PUBLIC_`.

package/governance/rules/framework/220-fastapi.md

@@ -0,0 +1,43 @@
+---
+description: Enforce FastAPI router, dependency injection, and async handler patterns
+paths:
+  - '**/*.py'
+---
+
+# FastAPI standards
+
+## Project structure
+
+- Mount routes through `APIRouter` modules. Do not register handlers directly on `FastAPI()`.
+- Group routers by feature under `src/<pkg>/api/` and include them from the root app factory.
+- Use an `app_factory()` callable over a module-level `app = FastAPI()` for testability.
+
+## Handlers
+
+- Define path operations as `async def` unless the handler is purely CPU-bound.
+- Do not perform blocking I/O inside `async def`. Use async clients or `run_in_threadpool`.
+- Annotate path, query, and body parameters explicitly. Do not rely on `**kwargs`.
+- Return pydantic models and set `response_model=` on the decorator for serialization control.
+
+## Dependency injection
+
+- Express shared logic (auth, db sessions, settings) as `Depends(...)` over decorators or globals.
+- Use `Annotated[T, Depends(...)]` over default-value `Depends()` for reusable dependencies.
+- Scope db sessions per request via a generator dependency that yields then closes.
+
+## Lifespan and configuration
+
+- Use the `lifespan` context manager for startup and shutdown over deprecated `@app.on_event`.
+- Load settings via `pydantic_settings.BaseSettings`, injected through a cached dependency.
+
+## Errors
+
+- Raise `HTTPException` for client-facing errors with explicit status codes.
+- Register `@app.exception_handler` mappings for domain exceptions over per-route try/except.
+- Do not leak internal exception messages. Map to safe summaries at the boundary.
+
+## Validation and security
+
+- Validate request bodies through pydantic models. Do not parse `Request.json()` manually.
+- Apply `dependencies=[Depends(auth)]` at the router or app level for cross-cutting auth.
+- Configure CORS, trusted hosts, and HTTPS redirects through middleware, not per-route checks.

package/governance/rules/framework/230-nextjs.md

@@ -0,0 +1,48 @@
+---
+description: Enforce Next.js App Router structure, server/client boundaries, and built-in primitives
+paths:
+  - '**/*.tsx'
+  - '**/*.ts'
+---
+
+# Next.js standards
+
+## App Router structure
+
+- Use the App Router under `app/`. Do not introduce `pages/` in new code.
+- Use route segment files for their documented purpose: `page.tsx` for routes, `layout.tsx` for shared shells, `loading.tsx` for Suspense fallbacks, `error.tsx` for error boundaries, `route.ts` for HTTP handlers.
+
+## Server and client components
+
+- Default to Server Components. Add `"use client"` only when the file needs state, effects, browser APIs, or event handlers.
+- Place `"use client"` at the leaf, not at the layout. Push the boundary as deep as possible.
+- Do not import server-only modules (`fs`, db clients, secrets) from a client component. Mark server-only modules with `import "server-only"`.
+- Pass serializable props across the server/client boundary. Do not pass functions or class instances.
+
+## Data fetching
+
+- Fetch data in Server Components or Route Handlers. Do not fetch in client components when a server alternative exists.
+- Set explicit caching on `fetch`: `cache: "force-cache"`, `cache: "no-store"`, or `next: { revalidate: <seconds> }`. Do not rely on defaults.
+- Use `revalidatePath` or `revalidateTag` for invalidation over manual refetch loops.
+
+## Server Actions
+
+- Mark Server Actions with `"use server"` at the top of the file or function.
+- Validate Server Action inputs with a Zod schema before use. The client/server boundary is implicit and easy to miss.
+- Return serializable values. Do not return Response or stream objects from a Server Action.
+
+## Route handlers
+
+- Place HTTP endpoints in `app/**/route.ts`. Do not add `pages/api/`.
+- Export named methods (`GET`, `POST`, ...). Return `NextResponse` over raw `Response` for typed helpers.
+- Read params from the function signature (`{ params }`), not from the request URL.
+
+## Built-in primitives
+
+- Use `next/link` over `<a>` for internal navigation. Use `next/image` over `<img>` for raster images. Use `next/font` over manual `<link>` tags for fonts.
+- Set explicit `width` and `height` (or `fill`) on `next/image`. Do not omit dimensions.
+
+## Metadata and environment
+
+- Export `metadata` or `generateMetadata` from `layout.tsx` or `page.tsx` over manual `<head>` injection.
+- Prefix browser-exposed env vars with `NEXT_PUBLIC_`. Never read unprefixed server-only env vars from a client component.

package/governance/rules/framework/250-tailwind.md

@@ -0,0 +1,32 @@
+---
+description: Enforce Tailwind CSS v4 utility patterns, theme tokens, dark mode, and custom styles
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+  - '**/*.html'
+  - '**/*.css'
+---
+
+# Tailwind CSS v4 standards
+
+## Theme variables
+
+- Use `@theme` for design tokens that generate utility classes.
+- Use `:root` for plain CSS variables with no utility counterpart.
+- Define dark mode color overrides in `.dark { }` at root level over `@layer base`.
+- Always pair light and dark utilities explicitly: `bg-white dark:bg-gray-900`.
+
+## Layout and spacing
+
+- Use `flex` and `grid` for all layouts.
+- Never use floats or absolute positioning for flow.
+- Use `gap-*` for sibling spacing over margins.
+- Use `size-*` over `w-* h-*` for equal dimensions.
+- Mobile-first: default styles apply to mobile. Use `sm:` and up to override.
+
+## Class application
+
+- Use `cn()` from `@/lib/utils` for all conditional class application.
+- Do not use the `!` important modifier.
+- Do not use inline `style` props for static styling. Use arbitrary values (`bg-[#316ff6]`) instead.
+- Use inline styles only for dynamic values from JS/API or to set CSS variables for utility consumption.

package/governance/rules/framework/260-shadcn.md

@@ -0,0 +1,34 @@
+---
+description: Enforce shadcn/ui v4 component patterns, semantic tokens, and composition rules
+paths:
+  - '**/*.tsx'
+  - '**/*.jsx'
+---
+
+# shadcn/ui standards
+
+## Source files
+
+- Do not edit component files installed by the shadcn CLI. Treat them as vendored.
+- Check `components.json` for the install path.
+- Extend behavior via wrapper components over modifying installed files.
+
+## Component authoring
+
+- Use `React.ComponentProps<typeof Primitive>` over `React.forwardRef`.
+- Add `data-slot="component-name"` to every primitive root for Tailwind targeting.
+
+## Tokens and styling
+
+- Use semantic color tokens (`bg-background`, `text-foreground`, `border-border`) over hardcoded colors.
+- Use `cn()` from `@/lib/utils` for all className merging and conditional classes.
+- Do not override shadcn component internals with arbitrary classes.
+- Extend via `className` prop only.
+
+## Composition
+
+- Compose shadcn primitives as documented.
+- Do not destructure or restructure internal component trees.
+- Use `asChild` prop with `<Slot>` for polymorphic rendering.
+- Do not wrap primitives in extra DOM elements.
+- Use `sonner` for toasts over the deprecated `toast` component.

package/governance/rules/lang/100-typescript.md

@@ -0,0 +1,40 @@
+---
+description: Enforce strict TypeScript type safety and patterns
+paths:
+  - '**/*.ts'
+  - '**/*.tsx'
+---
+
+# TypeScript standards
+
+## Casing conventions
+
+- 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.
+
+## 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`.
+
+## 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.
+
+## Imports and configuration
+
+- Use absolute imports mapping `@/` to `src/`.
+- 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/lang/110-python.md

@@ -0,0 +1,42 @@
+---
+description: Enforce strict Python type hints, casing, 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.
+
+## Errors
+
+- Raise specific built-in exceptions over bare `Exception`.
+- Define a project-rooted exception hierarchy for domain errors.
+- Catch the narrowest exception class. Never use bare `except:`.
+- Re-raise with `raise ... from err` to preserve the cause chain.
+
+## Data shapes
+
+- Use `dataclasses.dataclass(frozen=True, slots=True)` for internal value objects.
+- Use `enum.Enum` or `enum.StrEnum` for closed sets over module-level constants.
+- Prefer `pathlib.Path` over `os.path` for filesystem paths.
+
+## Imports and modules
+
+- Use absolute imports rooted at the package. Do not use parent-relative (`from ..pkg`) imports.
+- 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__":`.

package/governance/rules/lang/120-bash.md

@@ -0,0 +1,19 @@
+---
+description: Route bash script authoring to the interactive or non-interactive skill, and name the lint gate
+paths:
+  - '**/*.sh'
+---
+
+# Bash standards
+
+## Skill routing
+
+- Use `canon:bash-script` for an interactive or human-facing script: prompts, a visual timeline UI, framed terminal output.
+- Use `canon:bash-cli-script` for a non-interactive script: automation, CI, cron, a pipeline helper, or anything run by an agent rather than watched by a person.
+- Load the matched skill's own reference templates rather than hand-rolling interactivity or logging patterns outside them.
+- Report it rather than proceeding silently when the matched skill does not resolve. Both ship with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have them.
+
+## Lint gate
+
+- Format with `shfmt --write --indent 2` and lint with `shellcheck --severity=warning` before committing a script.
+- Fix a shellcheck finding at the source. Suppress one with a directive comment only for a genuine false positive, and state why beside the suppression.

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

@@ -0,0 +1,39 @@
+---
+description: Enforce Vitest, Playwright, and Testing Library patterns for TypeScript test files
+paths:
+  - '**/*.test.ts'
+  - '**/*.test.tsx'
+  - '**/*.spec.ts'
+  - '**/*.spec.tsx'
+---
+
+# TypeScript/JavaScript testing tooling
+
+## 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`).
+
+## 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.
+
+## 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`.
+
+## 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.

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

@@ -0,0 +1,34 @@
+---
+description: Enforce settled waits and falsifiable guards in end-to-end tests
+paths:
+  - 'e2e/*.ts'
+  - 'e2e/**/*.ts'
+---
+
+# End-to-end reliability standards
+
+## Waiting
+
+- Settle on the condition a step waits for. Use `expect.poll` or a web-first assertion ahead of any read.
+- Reserve a fixed duration for an assertion that nothing happened across a window.
+- Bound every settle with an explicit 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.
+
+## Falsifiable guards
+
+- Assert the set under test is non-empty before asserting a property over its members.
+- Raise from an instrument that was refused rather than returning a value a passing assertion accepts.
+- Run a new guard against the defect it was written for, and see it fail, before trusting it.
+- Do not weaken an assertion to clear a failure. Narrow the wait instead.
+
+## 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.
+- 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
+
+- Follow `.claude/rules/lib/300-testing-ts.md` for framework choice, file placement, and test naming.

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

@@ -0,0 +1,25 @@
+---
+description: Enforce which specs and which engines an end-to-end run covers at each point in the loop
+paths:
+  - 'e2e/*.ts'
+  - 'e2e/**/*.ts'
+---
+
+# Test scope standards
+
+## 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 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.
+
+## 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`.
+- Follow `.claude/rules/ui/440-surface-capture.md` for capture scope.
+- Follow `.claude/rules/lib/305-e2e-reliability.md` for waits and guards.

package/governance/rules/lib/310-zod.md

@@ -0,0 +1,25 @@
+---
+description: Enforce zod schema validation and type inference
+paths:
+  - '**/*.ts'
+  - '**/*.tsx'
+---
+
+# Zod validation standards
+
+## 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.
+
+## 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.
+
+## Schema safety
+
+- Use `z.unknown()` for truly ambiguous inputs instead of `z.any()`.
+- Prefer `.strict()` at boundaries or explicit `.pick()`/`.omit()` over `.passthrough()`.

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

@@ -0,0 +1,32 @@
+---
+description: Enforce tanstack query data fetching and cache patterns
+paths:
+  - '**/*.ts'
+  - '**/*.tsx'
+---
+
+# TanStack Query standards
+
+## 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.
+
+## 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.
+
+## Cache management
+
+- Use `queryClient.invalidateQueries` over `queryClient.setQueryData` unless implementing optimistic updates.
+- Prefetch predictable navigations with `queryClient.prefetchQuery` at route boundaries.
+
+## 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`.

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

@@ -0,0 +1,44 @@
+---
+description: Enforce pytest fixtures, parametrize, and async patterns for Python tests
+paths:
+  - 'tests/**/*.py'
+  - '**/test_*.py'
+  - '**/*_test.py'
+---
+
+# Python testing tooling
+
+## 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_*`.
+
+## 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.
+
+## 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.
+
+## 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_`.