@erclx/canon 5.43.0 → 5.44.0

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/writing/markdown.md

@@ -21,4 +21,4 @@ paths:
 
 ## Figures
 
-- Load the `canon:draft-figure` skill before drafting or revising a Mermaid fence or a figure, and report it rather than proceeding silently when it does not resolve.
+- Load the `canon:draw-figure` skill before drafting or revising a Mermaid fence or a figure, and report it rather than proceeding silently when it does not resolve.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "5.43.0",
+  "version": "5.44.0",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
   "license": "MIT",
   "bin": {

package/src/claude/cases/authoring.ts

@@ -22,26 +22,38 @@ export const AUTHORING_CASES: readonly SkillCase[] = [
   {
     prompt:
       'Write a brand-new docs page for the capture command, nothing under docs/ covers it yet.',
+    expect: 'write-doc',
+  },
+  {
+    prompt:
+      'I typed draft-doc and it said the doc skill was renamed to write-doc.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-doc',
   },
   {
     prompt:
       'I already wrote the finished skill files, package them as a ready folder with a plan and a task for a worker to copy.',
+    expect: 'plan-ready',
+  },
+  {
+    prompt:
+      'I typed draft-ready and it said the ready skill was renamed to plan-ready.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-ready',
   },
   {
     prompt: 'This project has no README.md at all, write one from scratch.',
-    expect: 'draft-doc',
+    expect: 'write-doc',
   },
   {
     prompt:
       'Write a context entry for the payments domain, there is no canon/context page for it yet.',
-    expect: 'draft-doc',
+    expect: 'write-doc',
   },
   {
     prompt:
       'Write a wiki reference page for Claude Code output styles, no page covers that subject yet.',
-    expect: 'draft-doc',
+    expect: 'write-doc',
   },
   {
     prompt: 'This passage reads flat and robotic, give it some real cadence.',

package/src/claude/cases/misc.ts

@@ -10,6 +10,12 @@ export const MISC_CASES: readonly SkillCase[] = [
   {
     prompt:
       'Show me a few different treatments for this callout so I can pick one by looking.',
+    expect: 'pick-by-eye',
+  },
+  {
+    prompt:
+      'I typed draft-and-pick and it said the pick skill was renamed to pick-by-eye.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-and-pick',
   },
   {
@@ -20,6 +26,12 @@ export const MISC_CASES: readonly SkillCase[] = [
   {
     prompt:
       'This project has no logo yet. Draft one and give me a social card to go with it.',
+    expect: 'design-identity',
+  },
+  {
+    prompt:
+      'I typed draft-identity and it said the identity skill was renamed to design-identity.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-identity',
   },
   {

package/src/claude/cases/workflow.ts

@@ -22,12 +22,18 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Draw me a diagram of how the pieces of this system connect.',
+    expect: 'draw-figure',
+  },
+  {
+    prompt:
+      'I typed draft-figure and it said the figure skill was renamed to draw-figure.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-figure',
   },
   {
     prompt:
       'This onboarding doc needs a hand-drawn picture of the signup-to-active path, sketch it in and make sure it actually renders correctly.',
-    expect: 'draft-figure',
+    expect: 'draw-figure',
   },
   {
     prompt:
@@ -108,10 +114,22 @@ export const WORKFLOW_CASES: readonly SkillCase[] = [
   },
   {
     prompt: 'Draft me a script with beats for a screencast recording.',
+    expect: 'script-screencast',
+  },
+  {
+    prompt:
+      'I typed draft-screencast and it said the screencast skill was renamed to script-screencast.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-screencast',
   },
   {
     prompt: 'Turn this topic into a slide deck I can render.',
+    expect: 'make-deck',
+  },
+  {
+    prompt:
+      'I typed draft-slides and it said the slides skill was renamed to make-deck.', // canon-keep-retired
+    // The pointer answers under its old name on purpose. canon-keep-retired
     expect: 'draft-slides',
   },
   // Rot across documents nobody changed is what this reads, rather than a