@erclx/canon 5.42.0 → 5.44.0

package/governance/ledger/framework/fastapi.md

@@ -0,0 +1,76 @@
+---
+title: FastAPI rule ledger
+description: Sources for governance/rules/framework/fastapi.md, one row per bullet
+---
+
+# FastAPI rule ledger
+
+The field is back-end Python web engineering, and the authority is the FastAPI documentation at fastapi.tiangolo.com. None of the pages read names a FastAPI major, so the rows record the read date alone.
+
+## Routers
+
+| Bullet                      | Source                                                                                                                                                                                              | Read       |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| One `APIRouter` per feature | [Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/): "You can think of APIRouter as a mini FastAPI class", and "With app.include_router() we can add each APIRouter"  | 2026-10-18 |
+| Router-level dependencies   | [Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/): router `dependencies` "can be used, for example, to require authentication for a whole group of path operations" | 2026-10-18 |
+
+## Path operations
+
+| Bullet                        | Source                                                                                                                                                                                                                                    | Read       |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `async def` only when awaited | [Concurrency and async / await](https://fastapi.tiangolo.com/async/): a plain `def` "is run in an external threadpool that is then awaited", and "use async def unless your path operation functions use code that performs blocking I/O" | 2026-10-18 |
+| Response model omits secrets  | [Response Model](https://fastapi.tiangolo.com/tutorial/response-model/): FastAPI "will limit and filter the output data to what is defined in the return type"                                                                            | 2026-10-18 |
+| Body as a Pydantic model      | [Request Body](https://fastapi.tiangolo.com/tutorial/body/): "To declare a request body, you use Pydantic models", which validate it and return "a nice and clear error" when it is invalid                                               | 2026-10-18 |
+
+## Dependencies
+
+| Bullet                          | Source                                                                                                                                                                                            | Read       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `Annotated` and type aliases    | [Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/): "Prefer to use the Annotated version if possible", and the value can be stored "in a variable and use it in multiple places" | 2026-10-18 |
+| Session per request via `yield` | [Dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/): "you could use this to create a database session and close it after finishing"            | 2026-10-18 |
+| Overrides in tests              | [Testing Dependencies with Overrides](https://fastapi.tiangolo.com/advanced/testing-dependencies/): "your FastAPI application has an attribute app.dependency_overrides"                          | 2026-10-18 |
+
+## Lifespan and settings
+
+| Bullet                     | Source                                                                                                                                                                                                         | Read       |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `lifespan`, not `on_event` | [Lifespan Events](https://fastapi.tiangolo.com/advanced/events/): "If you provide a lifespan parameter, startup and shutdown event handlers will no longer be called"                                          | 2026-10-18 |
+| Cached `BaseSettings`      | [Settings and Environment Variables](https://fastapi.tiangolo.com/advanced/settings/): with `@lru_cache` "the Settings object will be created only once", and a dependency override replaces it during testing | 2026-10-18 |
+
+## Errors
+
+| Bullet                | Source                                                                                                                                                | Read       |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Raise `HTTPException` | [Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/): "To return HTTP responses with errors to the client you use HTTPException" | 2026-10-18 |
+| One exception handler | [Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/): "You could add a custom exception handler with @app.exception_handler()"   | 2026-10-18 |
+| Safe summaries only   | House choice: an exception message or traceback in a response leaks internals such as SQL, file paths, and library versions to the caller             | 2026-10-18 |
+
+## Middleware
+
+| Bullet                | Source                                                                                                                                                                | Read       |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Explicit CORS origins | [CORS](https://fastapi.tiangolo.com/tutorial/cors/): "None of allow_origins, allow_methods and allow_headers can be set to ['*'] if allow_credentials is set to True" | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Reworded "define path operations as `async def` unless purely CPU-bound". The [async page](https://fastapi.tiangolo.com/async/) says "If you just don't know, use normal def", and CPU work in `async def` blocks the loop too.
+- Cut "an `app_factory()` callable over a module-level `app` for testability". Every docs example uses a module-level `app` and tests through `app.dependency_overrides`, which the kept bullet names.
+
+### Cut without a source or a bug class
+
+- Cut "group routers by feature under `src/<pkg>/api/`" as a layout call, which the `codebase-layout` skill owns.
+- Cut "annotate path, query, and body parameters, never `**kwargs`", since FastAPI cannot read `**kwargs` and Claude already annotates them.
+- Cut "configure trusted hosts and HTTPS redirects through middleware" as a deployment choice with no page read taking a side.
+
+### Merged or reworded
+
+- Merged "mount routes through `APIRouter`, never directly on `FastAPI()`" into the router bullet.
+- Reworded "return pydantic models and set `response_model=`" to name the filter, which is the footgun the [Response Model](https://fastapi.tiangolo.com/tutorial/response-model/) page warns about with passwords.
+- Merged "express shared logic as `Depends(...)` over decorators or globals" into the `Annotated` bullet.
+- Merged "do not perform blocking I/O inside `async def`" into the `async def` bullet.
+- Narrowed "configure CORS through middleware, not per-route checks" to the credentials footgun the CORS page states.
+- Moved "apply `dependencies=[Depends(auth)]` at the router or app level" to the routers section.

package/governance/ledger/framework/nextjs.md

@@ -0,0 +1,86 @@
+---
+title: Next.js rule ledger
+description: Sources for governance/rules/framework/nextjs.md, one row per bullet
+---
+
+# Next.js rule ledger
+
+The field is front-end engineering, and the authority is the Next.js documentation at nextjs.org, read against the App Router docs for Next.js 16. The rule loads on every `.ts` and `.tsx` file in a target, so the rewrite cut it from 352 words to under 250.
+
+## Routing
+
+| Bullet                   | Source                                                                                                                                                                                      | Read                   |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| App Router, not `pages/` | House choice: a second router in one app splits layouts, data fetching, and caching across two models, so a change made in one never reaches routes in the other                            | 2026-10-18             |
+| Await `params`           | [route.js](https://nextjs.org/docs/app/api-reference/file-conventions/route): "`context.params` is now a promise" since v15, and every page example types `params: Promise<{ id: string }>` | 2026-10-18, Next.js 16 |
+
+## Server and client components
+
+| Bullet                          | Source                                                                                                                                                                                                                                                      | Read                   |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| Server by default               | [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components): "By default, layouts and pages are Server Components", with Client Components for state, event handlers, lifecycle logic, and browser-only APIs   | 2026-10-18, Next.js 16 |
+| `'use client'` at the leaf      | [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components): "add 'use client' at the top of the files that define your interactive components instead of marking large parts of your UI as Client Components" | 2026-10-18, Next.js 16 |
+| Serializable, minimal props     | [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components): props "need to be serializable", and [Data Security](https://nextjs.org/docs/app/guides/data-security) marks passing a whole row as "EXPOSED"     | 2026-10-18, Next.js 16 |
+| `server-only` on secret modules | [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components): "To prevent accidental usage in Client Components, you can use the server-only package"                                                           | 2026-10-18, Next.js 16 |
+
+## Data and caching
+
+| Bullet                           | Source                                                                                                                                                                                                                                                    | Read                   |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `'use cache'` with `cacheLife`   | [Fetching Data](https://nextjs.org/docs/app/getting-started/fetching-data): "fetch requests are not cached by default", and [Caching](https://nextjs.org/docs/app/getting-started/caching): "We recommend pairing every cache directive with a cacheLife" | 2026-10-18, Next.js 16 |
+| `<Suspense>` around runtime data | [Caching](https://nextjs.org/docs/app/getting-started/caching): "Components that access runtime APIs should be wrapped in Suspense"                                                                                                                       | 2026-10-18, Next.js 16 |
+| Revalidate after a mutation      | [Mutating Data](https://nextjs.org/docs/app/getting-started/mutating-data): "you can revalidate the Next.js cache and show the updated data by calling revalidatePath or revalidateTag within the Server Function"                                        | 2026-10-18, Next.js 16 |
+
+## Mutations
+
+| Bullet                        | Source                                                                                                                                                                                                                                                      | Read                   |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| Verify auth inside the action | [Mutating Data](https://nextjs.org/docs/app/getting-started/mutating-data): "Server Functions are reachable via direct POST requests, not just through your application's UI. Always verify authentication and authorization inside every Server Function." | 2026-10-18, Next.js 16 |
+| Validate input, trim output   | [Data Security](https://nextjs.org/docs/app/guides/data-security): "You should always validate input from client", and "Only return what the UI needs, not raw database records"                                                                            | 2026-10-18, Next.js 16 |
+
+## Built-in primitives
+
+| Bullet                       | Source                                                                                                                                                                                                                                  | Read                   |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| `next/link` and `next/image` | [Linking and Navigating](https://nextjs.org/docs/app/getting-started/linking-and-navigating): "Next.js automatically prefetches routes linked with the Link component", and a plain anchor gets "No prefetching"                        | 2026-10-18, Next.js 16 |
+| Image dimensions or `fill`   | [Image Component](https://nextjs.org/docs/app/api-reference/components/image): "If the source image is a dynamic or a remote URL, you must provide the width and height props", and with `fill` "the parent element must be positioned" | 2026-10-18, Next.js 16 |
+
+## Environment
+
+| Bullet                          | Source                                                                                                                                                                                                                                                 | Read                   |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- |
+| `NEXT_PUBLIC_` only when needed | [Environment Variables](https://nextjs.org/docs/app/guides/environment-variables): Next.js can "inline a value, at build time, into the js bundle that is delivered to the client", and the values are "frozen with the value evaluated at build time" | 2026-10-18, Next.js 16 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Replaced "set explicit caching on every `fetch`" with the `'use cache'` bullet. New apps run Cache Components, which [Caching](https://nextjs.org/docs/app/getting-started/caching) drives through the directive.
+- Cut "return `NextResponse` over raw `Response`", since the [route.js](https://nextjs.org/docs/app/api-reference/file-conventions/route) reference returns the Web `Response` throughout.
+- Cut "read params from the function signature, not the request URL" as stale. The signature form holds, and the kept bullet adds the `await` the current major requires.
+- Cut "return no `Response` or stream from a Server Action". No page read forbids it, and the kept bullet states what the docs do say about return values.
+
+### Cut without a source or a bug class
+
+- Cut "use route segment files for their documented purpose" as a convention Claude already follows.
+- Cut "place HTTP endpoints in `app/**/route.ts`, never `pages/api/`" as covered by the App Router bullet.
+- Cut "export named HTTP methods" as enforced by the framework, which only routes the named exports.
+- Cut "export `metadata` or `generateMetadata` over manual head tags" as a convention Claude already follows.
+
+### Cut for the word budget
+
+A sourced practice cut only because the rule loads on every TypeScript file. A later pass with room can bring it back.
+
+- Cut "use `next/font` over manual link tags", which the docs still recommend.
+
+### Merged or reworded
+
+- Merged "do not fetch in client components when a server alternative exists" into the server-by-default bullet, since the docs list fetching among a Server Component's uses.
+- Merged "do not introduce `pages/` in new code" into the App Router bullet.
+- Merged "push the boundary as deep as possible" into the leaf bullet.
+- Merged "mark Server Actions with `'use server'`", which the build requires, into the mutation bullets.
+- Reworded "validate Server Action inputs with a Zod schema" to any validation, since [Data Security](https://nextjs.org/docs/app/guides/data-security) names no library.
+- Reworded "use `revalidatePath` or `revalidateTag` over manual refetch loops" to the call the mutation page shows.
+- Merged "never read unprefixed env vars in a client component" into the env bullet, since [Server and Client Components](https://nextjs.org/docs/app/getting-started/server-and-client-components) says "If variables are not prefixed, Next.js replaces them with an empty string".

package/governance/ledger/framework/react.md

@@ -0,0 +1,83 @@
+---
+title: React rule ledger
+description: Sources for governance/rules/framework/react.md, one row per bullet
+---
+
+# React rule ledger
+
+The field is front-end engineering, and the authority is the React team's documentation at react.dev. The rewrite started from groundwork spike S2's draft and reads its three unread leads.
+
+## Rendering
+
+| Bullet                      | Source                                                                                                                                                                                           | Read                 |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| Pure during render          | [Components and Hooks must be pure](https://react.dev/reference/rules/components-and-hooks-must-be-pure): side effects "should not run in render, as React can render components multiple times" | 2026-10-18, React 19 |
+| Never mutate props or state | [Components and Hooks must be pure](https://react.dev/reference/rules/components-and-hooks-must-be-pure): "A component's props and state are immutable snapshots. Never mutate them directly."   | 2026-10-18, React 19 |
+| Stable data keys, not index | [Rendering lists](https://react.dev/learn/rendering-lists): "Index as a key often leads to subtle and confusing bugs" and "do not generate keys on the fly"                                      | 2026-10-18, React 19 |
+
+## State and effects
+
+| Bullet                                        | Source                                                                                                                                                                                                                                                                | Read                 |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Derive during render                          | [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect): "When something can be calculated from the existing props or state, don't put it in state. Instead, calculate it during rendering."                                             | 2026-10-18, React 19 |
+| Reset with `key`                              | [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect): "To reset the state of an entire component tree, pass a different key to it."                                                                                                   | 2026-10-18, React 19 |
+| External store through `useSyncExternalStore` | [useSyncExternalStore](https://react.dev/reference/react/useSyncExternalStore): a browser value "can change without React's knowledge, so you should read it with useSyncExternalStore", and the server snapshot "must be the same between the client and the server" | 2026-10-18, React 19 |
+| Fetching effect in a custom hook              | [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect): a race "needs a cleanup function to ignore stale responses", and moving fetching "into a custom Hook will make it easier to adopt an efficient data fetching strategy later"    | 2026-10-18, React 19 |
+
+## Memoization
+
+| Bullet                           | Source                                                                                                                                                                                                                                              | Read                         |
+| -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| Leave it to the compiler         | [React Compiler introduction](https://react.dev/learn/react-compiler/introduction): "For new code, we recommend relying on the compiler for memoization and using useMemo/useCallback where needed to achieve precise control."                     | 2026-10-18, React Compiler 1 |
+| Without it, memoize only by need | [useMemo](https://react.dev/reference/react/useMemo): worth it for a noticeably slow calculation, "say, 1ms or more", a prop to a `memo` child, or a Hook dependency, and "There is no benefit to wrapping a calculation in useMemo in other cases" | 2026-10-18, React 19         |
+
+## Composition
+
+| Bullet                        | Source                                                                                                                                                                                                                                                | Read                 |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| Props, children, then context | [Passing data deeply with context](https://react.dev/learn/passing-data-deeply-with-context): "Start by passing props", then "Extract components and pass JSX as children", and "If neither of these approaches works well for you, consider context" | 2026-10-18, React 19 |
+
+## Error and loading boundaries
+
+| Bullet                                       | Source                                                                                                                                                                                                             | Read                 |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------- |
+| Error boundaries where a message makes sense | [Component](https://react.dev/reference/react/Component): "consider where it makes sense to display an error message", around the conversation list and each message, and "You don't need to wrap every component" | 2026-10-18, React 19 |
+| What activates Suspense                      | [Suspense](https://react.dev/reference/react/Suspense): "Suspense does not detect when data is fetched inside an Effect or event handler"                                                                          | 2026-10-18, React 19 |
+| Boundaries follow the loading sequence       | [Suspense](https://react.dev/reference/react/Suspense): "Suspense boundaries should not be more granular than the loading sequence that you want the user to experience"                                           | 2026-10-18, React 19 |
+
+## Exports
+
+| Bullet        | Source                                                                                                   | Read       |
+| ------------- | -------------------------------------------------------------------------------------------------------- | ---------- |
+| Named exports | House choice: a default export renamed at import drifts from the component's name, so a search misses it | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Replaced "`useMemo` for derived state over `useEffect`" with the derive bullet. The effect page says "calculate it during rendering" and keeps `useMemo` for a slow calculation.
+- Cut "memoize components receiving non-primitive props" as contradicted. [memo](https://react.dev/reference/react/memo) is "completely useless if the props passed to your component are always different, such as if you pass an object".
+- Cut "memoize every handler passed to a child" as contradicted. [useCallback](https://react.dev/reference/react/useCallback) says "There is no benefit to wrapping a function in useCallback in other cases" than a `memo` child or a Hook dependency.
+- Cut "no passing props past two levels" as contradicted, since the context page says "it's not unusual to pass a dozen props down through a dozen components".
+
+### Cut without a source or a bug class
+
+- Cut "domain logic in `src/features/`, shared UI in `src/components/`" as a layout call, which the `codebase-layout` skill owns.
+- Cut "no feature components in the global components folder" as the same layout call.
+- Cut "environment variables only from the validated config module", which is no React practice and which no react.dev page takes a side on.
+- Cut "function declarations over arrow functions" as style with no bug class, and no react.dev page takes a side.
+- Cut "props interface directly above the component" as style with no bug class.
+- Cut "extract components when JSX exceeds one responsibility", which no reviewer can check against a line of code.
+- Cut "compare the previous value and set state during render", since [You Might Not Need an Effect](https://react.dev/learn/you-might-not-need-an-effect) says "most components shouldn't need it either" and ranks it after a key reset.
+- Cut "use `<>` unless a key is needed" as a convention Claude already follows. [Rendering lists](https://react.dev/learn/rendering-lists) says the shorthand "won't let you pass a key".
+
+### Merged or reworded
+
+- Merged "no default exports" into the named-exports bullet, which states the same choice.
+- Narrowed "custom hooks for all fetching and complex effects" to data fetching, since [Reusing logic with custom hooks](https://react.dev/learn/reusing-logic-with-custom-hooks) says "you can (but don't have to) extract custom Hooks".
+- Merged "no `setState` in an effect to sync derived state" into the derive bullet, the same ban. Only the `web` and `nextjs` oxlint configs error on `react/set-state-in-effect`.
+- Reworded "a sentinel from asynchronously hydrating hooks" to `useSyncExternalStore` with a matching server snapshot, the API the reference names for a value React does not own.
+- Reworded "error boundaries at route level", since the reference places a boundary by where a message makes sense rather than at a fixed level.
+- Merged "no single root error boundary as the only net" into the placement bullet.

package/governance/ledger/framework/shadcn.md

@@ -0,0 +1,60 @@
+---
+title: shadcn/ui rule ledger
+description: Sources for governance/rules/framework/shadcn.md, one row per bullet
+---
+
+# shadcn/ui rule ledger
+
+The field is front-end engineering, and the authority is the shadcn/ui documentation and changelog at ui.shadcn.com. The rewrite reads the July 2026 changelog, which made Base UI the default primitive library.
+
+## Source files
+
+| Bullet                       | Source                                                                                                                                                                                                            | Read       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Edit installed code in place | [Introduction](https://ui.shadcn.com/docs): "This is not a component library. It is how you build your component library", and "Modify any part of a component to fit your design and functionality requirements" | 2026-10-18 |
+| Diff before overwrite        | [CLI](https://ui.shadcn.com/docs/cli): `add --overwrite` will "overwrite existing files", and `--diff` will "show diff for a file"                                                                                | 2026-10-18 |
+| Import through the aliases   | [components.json](https://ui.shadcn.com/docs/components-json): "The CLI uses these values to place generated components in the correct location and rewrite imports"                                              | 2026-10-18 |
+
+## Component authoring
+
+| Bullet                    | Source                                                                                                                | Read                       |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| `ComponentProps` typing   | [Tailwind v4](https://ui.shadcn.com/docs/tailwind-v4): "Replace React.forwardRef<...> with React.ComponentProps<...>" | 2026-10-18, React 19       |
+| `data-slot` on primitives | [Tailwind v4](https://ui.shadcn.com/docs/tailwind-v4): "Every primitive now has a data-slot attribute for styling"    | 2026-10-18, Tailwind CSS 4 |
+
+## Tokens and styling
+
+| Bullet          | Source                                                                                                                                                                                      | Read       |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| Semantic tokens | [Theming](https://ui.shadcn.com/docs/theming): "We use semantic background and foreground pairs", mapped "into utilities like bg-background, text-foreground, border-border, and ring-ring" | 2026-10-18 |
+| `cn()` merging  | [Manual installation](https://ui.shadcn.com/docs/installation/manual): re-export `cn` "from lib/utils.ts so your own code has a single place to import helpers from"                        | 2026-10-18 |
+
+## Composition
+
+| Bullet                       | Source                                                                                                                                                                                          | Read       |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `render` or `asChild`        | [Base UI as the default](https://ui.shadcn.com/docs/changelog/2026-07-base-ui-default): "New projects now use Base UI by default", "Radix is not being deprecated", and "asChild is now render" | 2026-10-18 |
+| `buttonVariants()` for links | [Button](https://ui.shadcn.com/docs/components/button): "The Base UI Button component always applies role="button", which overrides the semantic link role on a elements"                       | 2026-10-18 |
+| `sonner` for toasts          | [Tailwind v4](https://ui.shadcn.com/docs/tailwind-v4): "We're deprecating the toast component in favor of sonner"                                                                               | 2026-10-18 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Replaced "do not edit installed component files, treat them as vendored". The [introduction](https://ui.shadcn.com/docs) says "The top layer of your component code is open for modification".
+- Cut "extend behavior via wrapper components over modifying installed files" for the same reason.
+- Cut "do not override component internals with arbitrary classes, extend via `className` only". Editing the variants in the owned file is what the docs describe.
+- Reworded "use `asChild` with `<Slot>` for polymorphic rendering", since Base UI projects use `render` and the scoped and open searches agreed on that split.
+
+### Cut without a source or a bug class
+
+- Cut "compose shadcn primitives as documented", which no reviewer can check against a line of code.
+- Cut "do not destructure or restructure internal component trees" for the same reason.
+- Cut "do not wrap primitives in extra DOM elements" as a style call with no page read taking a side.
+
+### Merged or reworded
+
+- Reworded "check `components.json` for the install path" to the aliases bullet, which names what the file controls.
+- Reworded "use `cn()` for all className merging" to the override it guarantees.

package/governance/ledger/framework/tailwind.md

@@ -0,0 +1,55 @@
+---
+title: Tailwind CSS rule ledger
+description: Sources for governance/rules/framework/tailwind.md, one row per bullet
+---
+
+# Tailwind CSS rule ledger
+
+The field is front-end engineering, and the authority is the Tailwind CSS documentation at tailwindcss.com, read for Tailwind CSS 4.
+
+## Theme variables
+
+| Bullet                          | Source                                                                                                                                                                                                                  | Read                       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| `@theme` or `:root`             | [Theme variables](https://tailwindcss.com/docs/theme): "use :root for defining regular CSS variables that shouldn't have corresponding utility classes", and theme variables must be "defined top-level and not nested" | 2026-10-18, Tailwind CSS 4 |
+| Custom dark variant for a class | [Dark mode](https://tailwindcss.com/docs/dark-mode): "By default this uses the prefers-color-scheme CSS media feature", and a selector-driven theme overrides it with `@custom-variant dark`                            | 2026-10-18, Tailwind CSS 4 |
+
+## Layout and spacing
+
+| Bullet                     | Source                                                                                                                                                                            | Read                       |
+| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
+| `flex` or `grid` for flow  | House choice: a floated or absolutely positioned element leaves the document flow, so its siblings overlap or collapse once the viewport width changes                            | 2026-10-18                 |
+| `gap-*` over child margins | House choice: a margin on each child leaves a stray edge when the last item wraps or a conditional item is hidden, which `gap` never does                                         | 2026-10-18                 |
+| `size-*` for equal sides   | [Width](https://tailwindcss.com/docs/width): "Use utilities like size-px, size-4, and size-full to set both the width and height of an element at the same time"                  | 2026-10-18, Tailwind CSS 4 |
+| Mobile first               | [Responsive design](https://tailwindcss.com/docs/responsive-design): "unprefixed utilities take effect on all screen sizes", and "Don't think of sm: as meaning on small screens" | 2026-10-18, Tailwind CSS 4 |
+
+## Class application
+
+| Bullet                          | Source                                                                                                                                                                                                                                           | Read                       |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
+| Complete class names            | [Detecting classes in source files](https://tailwindcss.com/docs/detecting-classes-in-source-files): Tailwind "has no way of understanding string concatenation or interpolation", so "map props to complete class names"                        | 2026-10-18, Tailwind CSS 4 |
+| No conflicting utilities        | [Styling with utility classes](https://tailwindcss.com/docs/styling-with-utility-classes): "you should just never add two conflicting classes to the same element"                                                                               | 2026-10-18, Tailwind CSS 4 |
+| `!` only as a last resort       | [Styling with utility classes](https://tailwindcss.com/docs/styling-with-utility-classes): "When you really need to force a specific utility class to take effect and have no other means of managing the specificity, you can add ! to the end" | 2026-10-18, Tailwind CSS 4 |
+| Arbitrary values for one-offs   | [Styling with utility classes](https://tailwindcss.com/docs/styling-with-utility-classes): "When you need to use a one-off value outside of your theme, use the special square bracket syntax"                                                   | 2026-10-18, Tailwind CSS 4 |
+| Inline style for dynamic values | [Styling with utility classes](https://tailwindcss.com/docs/styling-with-utility-classes): inline styles are useful "when a value is coming from a dynamic source like a database or API", and for "setting CSS variables"                       | 2026-10-18, Tailwind CSS 4 |
+
+## Declined
+
+Every bullet the rewrite removed or reshaped, grouped by why.
+
+### Contradicted by the docs
+
+- Reworded "do not use the `!` important modifier", since the [utility classes](https://tailwindcss.com/docs/styling-with-utility-classes) page documents the trailing `!` for the case nothing else resolves.
+
+### Cut without a source or a bug class
+
+- Cut "always pair light and dark utilities explicitly". No page read requires it, and a color token redefined for dark mode switches with no `dark:` pair at all.
+- Cut "define dark mode color overrides in `.dark { }` at root level over `@layer base`", which no Tailwind page read takes a side on.
+- Cut "use `cn()` from `@/lib/utils` for all conditional class application" as the import convention the shadcn rule already owns. The kept conflict bullet names `cn()` for the override case.
+
+### Merged or reworded
+
+- Merged "use `flex` and `grid` for all layouts" and "never use floats or absolute positioning for flow" into one bullet naming the bug class.
+- Reworded "use `size-*` over `w-* h-*`" to the matching pair it replaces.
+- Reworded "mobile-first, default styles apply to mobile" to the `sm:` misreading the responsive page warns about.
+- Added "write every class name in full", the footgun the source detection page names and the old rule missed.

package/governance/rules/canon/context.md

@@ -8,6 +8,7 @@ paths:
 
 ## Context entries
 
-- Load the `canon:context-fold` skill before a hand edit under `canon/context/`. It carries the entry shape and the content rules for a domain entry. Report it rather than proceeding silently when the skill does not resolve.
+- Load the `canon:context-fold` skill before a hand edit under `canon/context/`, since it carries the entry shape and the content rules for a domain entry.
+- Report it rather than proceeding silently when `canon:context-fold` does not resolve.
 - Before non-trivial work in a domain, read its `canon/context/<domain>/` entry. Use `canon/context/index.md` to find it.
 - Leave the entry conforming when work in its domain changes what it describes.

package/governance/rules/canon/plan.md

@@ -1,5 +1,5 @@
 ---
-description: Route edits under .canon/plans/ to the plan-feature skill for the plan's sections, the answer contract, and its lifecycle
+description: Route edits under .canon/plans/ to the plan-feature skill, and keep the five hand-edit floors a plan breaks silently
 paths:
   - '.canon/plans/**'
 ---
@@ -8,11 +8,9 @@ paths:
 
 ## Plan files
 
-- Load the `canon:plan-feature` skill before a hand edit under `.canon/plans/`. It carries the filename and slug, the required sections, and the suggested-and-answer contract for a feature plan. Report it rather than proceeding silently when the skill does not resolve.
+- Load the `canon:plan-feature` skill before a hand edit under `.canon/plans/`, whose references own its shape and lifecycle. Report it rather than proceeding silently when it does not resolve.
 - Never fill an `- Answer:` slot on behalf of the person who owns it. A blank slot accepts the suggestion at execution time.
-- Never ship a question without a `- Suggested:` line. Write `- Suggested: needs your call, <why>` where the answer turns on preference.
-- Rewrite the `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when execution deviates from an unanswered question, leaving the slot blank. Put the same deviation in one line under the open task's `## Findings`.
+- Rewrite an unanswered question's `- Suggested:` line as `overridden at execution to <pick>,` plus the measurement when execution deviates, leaving the slot blank.
 - Fetch the source a decision rests on and quote the passage under `**Sources:**`, or mark the entry `unverified`. Never cite an outside source from recall.
 - Move a shipped plan to `.canon/plans/archive/`. Never delete one.
 - Amend a plan in place when a decision changes. Do not append a second passage narrating the change.
-- Follow the lifecycle the `canon:plan-feature` skill carries for when a plan is written, how it is amended, and its move to the archive.

package/governance/rules/canon/scratch.md

@@ -6,4 +6,6 @@ description: Write temporary files to the scratch folder structure
 
 ## Temporary files
 
-- Write temporary files to `.canon/tmp/<slug>/<file>.md` at the current worktree's root, a nested folder with a kebab-slug tied to the topic rather than a flat `<slug>-<file>.md`. The slug must not take one of the five reserved names `runs`, `hooks`, `handoff`, `pr`, and `render`. A skill that resolves a write at the main root instead states so in its own body.
+- Write temporary files to `.canon/tmp/<slug>/<file>.md` at the current worktree's root, with a kebab-slug tied to the topic rather than a flat `<slug>-<file>.md`.
+- Never take one of the reserved slugs `runs`, `hooks`, `handoff`, `pr`, and `render`.
+- Write scratch at the main root instead only when a skill's own body says so.

package/governance/rules/canon/task-scope.md

@@ -8,4 +8,5 @@ description: Scope, size, and link a task file correctly
 
 - Only create a task for work that spans multiple sessions or has real dependencies. Handle small edits immediately without a task entry.
 - Do not add tasks retroactively for work already completed. Completed work is visible in git.
-- When a task needs execution detail beyond its own file, write a plan in `.canon/plans/` in the same session as the task and link to it from the task's intro paragraph. The session that executes the plan later inherits reasoning context it would otherwise have to re-derive.
+- Write a plan in `.canon/plans/` when a task needs execution detail beyond its own file, and link it from the task's intro paragraph.
+- Write that plan in the same session as the task, since the executing session would otherwise re-derive the reasoning behind it.

package/governance/rules/canon/tasks.md

@@ -8,7 +8,8 @@ paths:
 
 ## Task files
 
-- Load the `canon:task-board` skill before a hand edit under `.canon/tasks/`. It carries the folder layout, filename convention, file format, origin lines, and archiving for a task file. Report it rather than proceeding silently when the skill does not resolve.
+- Load the `canon:task-board` skill before a hand edit under `.canon/tasks/`, since it carries the layout, filenames, format, origin lines, and archiving of a task file.
+- Report it rather than proceeding silently when `canon:task-board` does not resolve.
 - Follow the board shape the `canon:task-board` skill carries for `priority.md` and `backlog.md`, their readiness groups, and row order.
 - Never hand-edit `.canon/tasks/index.md`. A hook regenerates it from sibling frontmatter.
 - Follow the decline shape the `canon:task-board` skill carries for a task decided against.

package/governance/rules/canon/worktrees.md

@@ -10,5 +10,8 @@ description: Enter a linked worktree for implementation, resolve shared session
 
 ## Shared session scratch
 
-- Shared session scratch (`.canon/plans/`, `.canon/review/`, `.canon/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, or from a background session that entered none, `Edit` and `Write` refuse a main-root path and redirect to a worktree copy no later session reads. Never take that redirect. Route the write the way the `session-worktree` skill states, and report it rather than proceeding silently when that skill does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
+- Resolve shared session scratch (`.canon/plans/`, `.canon/review/`, `.canon/tasks/`) at the main worktree root, never inside a linked worktree.
+- Read the main root from `git worktree list --porcelain | grep -m 1 '^worktree ' | cut -d' ' -f2-`, and fall back to `pwd` outside a git repo.
+- Never take the worktree copy `Edit` and `Write` redirect a main-root path to, since no later session reads it. Revisit when Edit and Write stop redirecting a main-root path from a linked worktree.
+- Route a main-root write from a linked worktree, or from a background session that entered none, the way the `session-worktree` skill states.
+- Report it rather than proceeding silently when `session-worktree` does not resolve, as in a project that installed governance without the plugin.

package/governance/rules/claude/output.md

@@ -7,10 +7,13 @@ description: Report file paths correctly for the reading surface and group them
 ## Reporting paths
 
 - After creating or modifying a file, include its path on its own line so the reader can open it. Do not paraphrase paths into prose ("the seeds folder", "your CLAUDE.md").
-- Emit a path in the form the surface's own instructions give, such as a markdown link where the harness asks for one, and bare where it gives none. A terminal makes a bare path clickable through its own path detection, and link markup defeats that.
-- That form governs a path emitted in a response. A path written into a markdown file follows the markdown standard instead, which your toolkit resolves by name, and which backticks a file reference and never repeats it as a link label.
-- In a linked worktree (under `.claude/worktrees/<name>/`), emit the absolute path, since the editor is rooted at the main project root and a path relative to the worktree resolves nowhere there. Prefer the form a `PostToolUse` hook hands back after a write where one is installed.
+- Emit a path in the form the surface's own instructions give, such as a markdown link where the harness asks for one, and bare where it gives none.
+- Never add link markup where the surface gives no form, since a terminal makes a bare path clickable through its own path detection and the markup defeats it.
+- Backtick a path written into a markdown file and never repeat it as a link label, per the markdown standard. The response form above governs a response alone.
+- Emit the absolute path from a linked worktree (under `.claude/worktrees/<name>/`), since the editor is rooted at the main root, where a worktree-relative path resolves nowhere.
+- Prefer the form a `PostToolUse` hook hands back after a write where one is installed.
 
 ## Grouping multiple files
 
-- When the response covers multiple files, group paths under headers: `**Created:**`, `**Modified:**`, `**Deleted:**`. Every path under them takes that form, not the first alone. For single-file changes, the path on its own line is enough.
+- Group paths under `**Created:**`, `**Modified:**`, and `**Deleted:**` headers when the response covers multiple files, with every path under them in that form.
+- Put a single-file change's path on its own line, with no header.

package/governance/rules/claude/skill.md

@@ -11,7 +11,9 @@ paths:
 
 ## Skill files
 
-- Load the `canon:create-skill` skill before a hand edit to a `SKILL.md` or a `REQUIREMENT.md`. It carries the skill structure, the requirement shape, and the path rules for a skill body. Report it rather than proceeding silently when the skill does not resolve. It ships with the plugin and this rule ships with the CLI, so a project that installed governance alone does not have it.
-- Confirm `canon:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whether drafted by hand, by another skill, or by `canon:create-skill` itself. Carry the third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
-- Re-read a skill body this session edited before invoking that skill again in the same session.
-- Do not read a resolved file path in a held body as evidence the body is current.
+- Load the `canon:create-skill` skill before a hand edit to a `SKILL.md` or a `REQUIREMENT.md`, since it carries the skill structure, the requirement shape, and the path rules.
+- Report it rather than proceeding silently when `canon:create-skill` does not resolve, as in a project that installed governance without the plugin.
+- Confirm `canon:create-skill`'s two creation-time questions are answered before a new `SKILL.md` lands, whoever drafted it, `canon:create-skill` included.
+- Carry its third question into the sibling `REQUIREMENT.md`'s `Must not` section as a review criterion rather than a gate.
+- Re-read a skill body this session edited before invoking that skill again in the same session. Revisit when Claude Code reloads a skill body edited after the session first invoked it.
+- Do not read a resolved file path in a held body as evidence the body is current. Revisit when Claude Code marks a held skill body stale once its source changes.

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_`.