@erclx/canon 5.43.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/framework/astro.md

@@ -1,5 +1,5 @@
 ---
-description: Enforce astro static-first architecture with explicit island opt-in
+description: Enforce Astro static-first rendering, explicit island hydration, content collections, and asset placement
 paths:
   - '**/*.astro'
   - 'src/pages/**'
@@ -11,31 +11,29 @@ paths:
 
 ## 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.
+- Write a component as `.astro` when it has no client-side state or event handlers, since it renders to HTML with no client JS.
+- Fetch page data in the component frontmatter, which runs at build or request time, not in a client island.
 
 ## 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.
+- Put a `client:*` directive on the framework component itself, imported directly into a `.astro` file.
+- Use `client:visible` for a component below the fold and `client:idle` for a low-priority one. Keep `client:load` for interactive UI above the fold.
 
 ## 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.
+- Give a dynamic `[param].astro` route a `getStaticPaths()` in static output, which builds only the paths it returns.
+- Wrap pages in a layout from `src/layouts/` that renders the page through `<slot />`.
 
 ## 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.
+- Define collections in `content.config.ts` at the root of `src/`, each with a `glob()` or `file()` loader and a Zod schema.
+- Read entries through `getCollection()` and `getEntry()`, never by importing content files directly.
 
 ## 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.
+- Keep component styles scoped. Use `is:global` or `:global()` only for a reset or base style in a layout.
+- Keep local images in `src/` so Astro optimizes them. Use `public/` only for files served as-is.
 
 ## Environment
 
-- Read environment variables via `import.meta.env`. Prefix client-exposed variables with `PUBLIC_`.
+- Read variables through `astro:env` with a schema, or `import.meta.env`, and prefix client-exposed ones with `PUBLIC_`.

package/governance/rules/framework/fastapi.md

@@ -1,43 +1,39 @@
 ---
-description: Enforce FastAPI router, dependency injection, and async handler patterns
+description: Enforce FastAPI routers, sync and async handlers, dependency injection, lifespan, and error mapping
 paths:
   - '**/*.py'
 ---
 
 # FastAPI standards
 
-## Project structure
+## Routers
 
-- 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.
+- Declare path operations on one `APIRouter` per feature and add each with `app.include_router()`, not on `FastAPI()` directly.
+- Put a dependency every route in a group needs, such as auth, in the router's `dependencies=[...]`.
 
-## Handlers
+## Path operations
 
-- 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.
+- Declare a path operation `async def` only when every I/O call in it is awaited. Use plain `def` for a blocking library, which FastAPI runs in a threadpool.
+- Declare the return type or `response_model` as a model that omits secrets, since FastAPI filters the output to it.
+- Take a request body as a Pydantic model parameter, never by parsing `await request.json()` by hand.
 
-## Dependency injection
+## Dependencies
 
-- 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.
+- Declare a dependency as `Annotated[T, Depends(fn)]`, and share a repeated one as a type alias.
+- Open a database session in a `yield` dependency and close it after the `yield`, so each request gets its own.
+- Replace a dependency in tests through `app.dependency_overrides`, never by patching the module.
 
-## Lifespan and configuration
+## Lifespan and settings
 
-- 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.
+- Run startup and shutdown in a `lifespan` context manager, never `@app.on_event`, which stops running once `lifespan` is set.
+- Load settings through `pydantic_settings.BaseSettings` behind an `@lru_cache` dependency, so `.env` is read once and tests can override it.
 
 ## 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.
+- Raise `HTTPException` with an explicit status code for a client error.
+- Map a domain exception to a response in one `@app.exception_handler`, over a try and except in each route.
+- Return a safe summary from a handler, never the exception's message or traceback.
 
-## Validation and security
+## Middleware
 
-- 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.
+- Configure CORS through `CORSMiddleware`, listing origins explicitly when `allow_credentials=True`, since a wildcard is refused then.

package/governance/rules/framework/nextjs.md

@@ -1,5 +1,5 @@
 ---
-description: Enforce Next.js App Router structure, server/client boundaries, and built-in primitives
+description: Enforce Next.js App Router boundaries, caching, Server Action security, and built-in primitives
 paths:
   - '**/*.tsx'
   - '**/*.ts'
@@ -7,42 +7,34 @@ paths:
 
 # Next.js standards
 
-## App Router structure
+## Routing
 
-- 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.
+- Add routes under `app/` with the App Router, never under `pages/`.
+- Await `params` and `searchParams`, which are Promises in a page, a layout, and a route handler.
 
 ## 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.
+- Default to Server Components. Add `'use client'` only to a file needing state, event handlers, effects, or browser APIs.
+- Put `'use client'` on the interactive leaf, not a layout, since every module it imports joins the client bundle.
+- Pass a Client Component only serializable props holding the fields it renders, never a whole database record.
+- Add `import 'server-only'` to a module that reads secrets or the database.
 
-## Data fetching
+## Data and caching
 
-- 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.
+- Cache with `'use cache'` and a `cacheLife` call where Cache Components is on, the default for new apps. A `fetch` is not cached by default.
+- Wrap a component reading `cookies()`, `headers()`, or uncached data in `<Suspense>` with a fallback.
+- Call `revalidatePath` or `revalidateTag` in the Server Action after a mutation.
 
-## Server Actions
+## Mutations
 
-- 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.
+- Verify authentication and resource ownership inside every Server Action, since each is reachable by a direct POST.
+- Validate every Server Action argument before use, and return only the fields the UI needs.
 
 ## 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.
+- Use `next/link` for internal navigation and `next/image` for raster images.
+- Give `next/image` a `width` and `height` for a remote source, or `fill` inside a positioned parent.
 
-## Metadata and environment
+## 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.
+- Prefix a variable with `NEXT_PUBLIC_` only when the browser needs it, since its value is inlined at build time.

package/governance/rules/framework/react.md

@@ -1,51 +1,40 @@
 ---
-description: Enforce opinionated React architecture and component patterns
+description: Enforce React render purity, state derivation, memoization, and boundary placement
 paths:
   - '**/*.tsx'
   - '**/*.ts'
 ---
 
-# React architecture standards
+# React standards
 
-## Export conventions
+## Rendering
 
-- 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.
+- Keep components and hooks pure during render. Move side effects and `Math.random()` into an event handler or an effect.
+- Never mutate props or state. Build a new value and pass it to the `useState` setter.
+- Key list items by a stable ID from the data, never by array index or a value generated during render.
 
 ## 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.
+- Calculate a value derivable from props or state during render, never in an effect that syncs it into state.
+- Reset a child's state by passing it a new `key`, over a reset effect in the child.
+- Read a browser or external store with `useSyncExternalStore` and a `getServerSnapshot` matching the server output.
+- Wrap a data-fetching effect in a custom hook whose cleanup ignores stale responses, when the framework has no fetching primitive.
 
 ## Memoization
 
-- Memoize components receiving non-primitive props with `React.memo`.
-- Use `useCallback` for handler props passed to children.
+- Leave memoization to React Compiler where it is enabled, as React recommends for new code. Add `useMemo` only for precise control.
+- Without the compiler, memoize only a calculation measured at 1ms or more, or a value a `memo` child or a Hook dependency reads.
+
+## Composition
+
+- Pass props first, then extract components and pass JSX as `children`. Reach for context only when neither works.
 
-## Composition and props
+## Error and loading boundaries
 
-- Avoid prop drilling beyond 2 levels. Use context or composition.
+- Place an error boundary where an error message makes sense, such as around a list and each item, never around every component.
+- Expect Suspense to catch `lazy`, `use` on a cached Promise, or a framework loader, never a fetch inside an effect.
+- Place Suspense boundaries to match the loading sequence the user should see.
 
-## Error boundaries and Suspense
+## Exports
 
-- 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.
+- Use named exports for components and hooks, since a default export renamed at import drifts from its name in a search.

package/governance/rules/framework/shadcn.md

@@ -1,5 +1,5 @@
 ---
-description: Enforce shadcn/ui v4 component patterns, semantic tokens, and composition rules
+description: Enforce shadcn/ui component ownership, typed primitives, semantic tokens, and composition props
 paths:
   - '**/*.tsx'
   - '**/*.jsx'
@@ -9,26 +9,22 @@ paths:
 
 ## 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.
+- Edit an installed component in place when the design needs it, since the code is the project's own.
+- Read `shadcn add --diff` before running `--overwrite` on a component, since overwriting discards local edits.
+- Import components and `cn` through the aliases in `components.json`, which the CLI uses to place files and rewrite imports.
 
 ## Component authoring
 
-- Use `React.ComponentProps<typeof Primitive>` over `React.forwardRef`.
-- Add `data-slot="component-name"` to every primitive root for Tailwind targeting.
+- Type a component's props as `React.ComponentProps<typeof Primitive>`, not `React.forwardRef`.
+- Add `data-slot="<name>"` to the root of a new primitive, matching the installed components.
 
 ## 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.
+- Use semantic tokens such as `bg-background`, `text-foreground`, and `border-border` over hardcoded colors.
+- Merge classes with `cn()` from `@/lib/utils`, so a caller's `className` overrides the component's defaults.
 
 ## 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.
+- Compose through `render` in a Base UI project, the default for new ones, and through `asChild` in a Radix one.
+- Style a link as a button with `buttonVariants()`, never a Base UI `Button` rendering an `<a>`, which forces `role="button"`.
+- Use `sonner` for toasts, since the `toast` component is deprecated.

package/governance/rules/framework/tailwind.md

@@ -1,5 +1,5 @@
 ---
-description: Enforce Tailwind CSS v4 utility patterns, theme tokens, dark mode, and custom styles
+description: Enforce Tailwind CSS v4 theme variables, dark mode, layout spacing, and class application
 paths:
   - '**/*.tsx'
   - '**/*.jsx'
@@ -11,22 +11,20 @@ paths:
 
 ## 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`.
+- Define a token in a top-level `@theme` block when it needs a utility class, and in `:root` when it does not.
+- Add `@custom-variant dark (&:where(.dark, .dark *))` when a `.dark` class toggles dark mode, since `dark:` follows `prefers-color-scheme` by default.
 
 ## 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.
+- Lay out flow content with `flex` or `grid`, never `float` or `absolute`, which pulls an element out of flow so it overlaps at other widths.
+- Space siblings with `gap-*` on the parent over margins on the children, which leave a stray edge when an item wraps or hides.
+- Use `size-*` over a matching `w-*` and `h-*` pair.
+- Write unprefixed utilities for mobile and add `sm:` and up for wider screens, since `sm:` means that breakpoint and above.
 
 ## 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.
+- Write every class name in full, mapping a prop to a complete class, since Tailwind cannot detect a class built by concatenation.
+- Never put two conflicting utilities on one element. Merge a caller's override through `cn()`, which drops the losing class.
+- Add the trailing `!` modifier only when no other way to manage specificity exists.
+- Use an arbitrary value such as `bg-[#316ff6]` for a static one-off, never an inline `style`.
+- Keep inline `style` for a value from a dynamic source, or to set a CSS variable a utility reads.

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.