@bonesofspring/ai-rules 0.2.30 → 0.2.32

package/presets/opencode/next/ai-local/rules-library/agent-artifacts-no-local-paths.md

@@ -6,7 +6,18 @@ glob: always
 
 When this rule applies, acknowledge: `Using .ai.local: agent-artifacts-no-local-paths(, …)*`.
 
-Committed agent artifacts leak into git history. Absolute host paths expose the developer machine layout even if the file is deleted in a later MR.
+Committed agent artifacts leak into git history. Absolute host paths (`/Users/<username>/…`) expose the developer machine layout even if the file is deleted in a later MR.
+
+## Scope (mandatory)
+
+Every agent-written file that may be committed, especially:
+
+- `.ai.local/team/tasks/<slug>/pipeline.json`
+- `.ai.local/team/tasks/<slug>/artifact-manifest.json` (`authoritativePaths`, `evidencePaths`, any path array)
+- `.ai.local/team/**` markdown (`brief.md`, `decomposition.md`, `implementation.md`, `review.md`, `validation-report.md`, …)
+- `.ai.local/team/active-task.json` and other team JSON
+
+Same ban for any other agent-authored committed path (`openspec/**`, `docs/**`).
 
 ## Forbidden
 
@@ -14,20 +25,42 @@ Do **not** write host-absolute paths, including:
 
 - `/Users/<username>/…` (macOS)
 - `/home/<username>/…` (Linux)
-- `C:\Users\<username>\…` and `C:/Users/<username>/…` (Windows)
-- Any other absolute checkout root.
+- `C:\Users\<username>\…` and `C:/Users/<username>\…` (Windows)
+- Any other absolute checkout root (`/Users/…/<workspace>/<repo>`, `~/…` expanded)
 
-Do **not** put those strings in `productionTarget.root`, `instructions[]`, summaries, or evidence lists.
+Do **not** put those strings in `instructions[]`, config values, summaries, or `authoritativePaths` / `evidencePaths`.
 
 ## Required instead
 
-- This repo: path from workspace root (`src/…`, `.ai.local/team/tasks/<slug>/pipeline.json`).
-- Task-local artifacts: basename is enough (`pipeline.json`, `brief.md`) when the file lives in the same task directory.
+- This repo: repo-relative path from the repo root (`app/src/…`, `.ai.local/team/tasks/<slug>/pipeline.json`).
+- Task-local artifacts: basename is enough (`pipeline.json`, `brief.md`) when the file lives in the same task directory — match `.ai.local/team/fixtures/artifact-manifest.example.json`.
 - Sibling / other repo: **repo name** + repo-relative path. Never the filesystem location of that checkout.
 
+```jsonc
+// ❌ BAD — a receipt in artifact-manifest.json leaking the host path
+{
+  "receipt": {
+    "evidencePaths": [
+      "/Users/<username>/<workspace>/other-repo/app/src/modules/health-tracking/"
+    ]
+  }
+}
+
+// ✅ GOOD — repo-relative; another repo is prefixed by its name
+{
+  "receipt": {
+    "evidencePaths": [
+      "other-repo:app/src/modules/health-tracking/"
+    ]
+  }
+}
+```
+
+Prose: `other-repo` `app/src/modules/health-tracking/` — not a `/Users/…` prefix.
+
 ## Gate before finishing a write
 
-After writing or editing a team artifact, scan the file (and any JSON you are about to write) for `/Users/`, `/home/`, `C:\Users`, `C:/Users`. If any match, rewrite to repo-relative **before** considering the step done.
+After writing or editing a team artifact, scan the file (and the JSON you are about to write) for `/Users/`, `/home/`, `C:\Users`, `C:/Users`. If any match, rewrite to repo-relative **before** considering the step done. Do not `git add` until clean.
 
 Deleting a leaked file later does **not** remove it from git history — prevention is the only fix.
 
@@ -35,4 +68,4 @@ Deleting a leaked file later does **not** remove it from git history — prevent
 
 - Repo-relative paths, `@/` aliases, URL paths (`/api/…`).
 - Public URLs (`https://…`, `figma.com/…`).
-- Ephemeral local logs that are **not** committed.
+- Ephemeral local logs that are **not** committed (e.g. `/tmp/….log`). Do not copy those absolute paths into committed artifacts; cite the command or a repo-relative copy instead.

package/presets/opencode/next/ai-local/rules-library/agent-pipeline-gates.md

@@ -0,0 +1,19 @@
+glob: always
+
+## Body
+
+# Agent pipeline gates (local overlay)
+
+These gates are **agent-enforced** (local rules; the preset hook/router is not edited). Treat them as MUST, not advisory. Acknowledge: `Using .ai.local: agent-pipeline-gates(, …)*`.
+
+## Gates
+
+- **UI scope** (`app/src/ui/**`): the pipeline MUST include `mockup-reviewer` — not only when a `figma.com` URL is present. A terminal `mockup-review.md` with verdict `PASS`/`PASS_WITH_NOTES` is required before the task is complete. Missing artifact = **blocked**, not a warning. (See `ui-change-review-gate`.)
+- **DTO/type scope**: `api-contract-reviewer` is blocking per `api-contract-source`.
+- **build-verifier**: when `storybook/**` or `app/src/ui/**` changed, run targeted storybook tests and require green **without** `--update`.
+- **code-reviewer**: (a) a behaviour change under `app/src/**` without a matching `docs/qa/**` or `*.cases.md` update → WARN (REQUEST_CHANGES when AC names the case); (b) a production behaviour change made to satisfy a test → **blocker**; (c) every review artifact states the reviewed revision (sha or `working tree @ <date>`).
+- **single writer**: do not rewrite a block shipped the same day without a new review artifact and an owner.
+
+## Why local, not preset
+
+The mechanical hook/router gate would live in the preset-managed hook + router, which `init` overwrites. Per project decision, all gate changes stay in `.ai.local` (agent-enforced).

package/presets/opencode/next/ai-local/rules-library/analytics-events.md

@@ -0,0 +1,18 @@
+globs: app/src/analytics/**/*.{ts,tsx},app/src/ui/**/*.{ts,tsx}
+
+## Body
+
+# Analytics / telemetry events (team conventions template)
+
+When emitting or changing an analytics/telemetry event, acknowledge: `Using .ai.local: analytics-events(, …)*`.
+
+Events go through one owned module per domain — not scattered `pushEvent` / `track` calls in components.
+
+## Rules
+
+- Event modules live under `app/src/analytics/events/<domain>/` and expose `logX(...)` functions wrapping the analytics client (`pushEvent` or repo equivalent); payload types live in a sibling `*.types.ts`.
+- Components emit events via a hook or store slice (`_complexSlices/Analytics` analog), not by importing the analytics client directly.
+- Respect the repo's gating flag (e.g. `NEXT_PUBLIC_*_ANALYTICS_DISABLED`) and the init in the app root; do not initialize adapters twice.
+- Deduplicate repeated events with the repo's cache idiom when it exists.
+- **Never** put PD, medical/record text, raw auth tokens, or full URL search params into a payload. See the security rule's compliance section.
+- Analytics is a side effect: cross-slice event emission belongs in listener middleware, not in a reducer (see `store-rtk`).

package/presets/opencode/next/ai-local/rules-library/api-contract-source.md

@@ -0,0 +1,14 @@
+globs: app/src/api/**/*.{ts,tsx},app/src/types/**/*.{ts,tsx},app/src/mocks/**/*.{ts,tsx}
+
+## Body
+
+# API contract source is mandatory (no invented DTOs)
+
+When changing DTOs, response types, mappers, or mocks, acknowledge: `Using .ai.local: api-contract-source(, …)*`.
+
+## Rules
+
+- Any new/changed DTO, response type, response mapper, or shared type **names its contract source** in the task brief: an OpenAPI path + schema (or the project's equivalent contract), or an explicit `no in-repo contract — capture is provisional` risk.
+- The API-contract reviewer is **blocking** when the contract source is a capture and the DTO is new/changed → emit `changes_requested`, not advisory notes.
+- Map only fields present in the contract source. Do not add a field that exists only in mockup copy or a guessed payload.
+- Watch nullability / object-vs-scalar: verify against the contract schema, not a single capture (a capture cannot show absent/empty cases).

package/presets/opencode/next/ai-local/rules-library/artifact-lifecycle.md

@@ -0,0 +1,17 @@
+glob: always
+
+## Body
+
+# Agent artifact lifecycle
+
+When writing team artifacts, acknowledge: `Using .ai.local: artifact-lifecycle(, …)*`.
+
+Task-folder artifacts (`.ai.local/team/tasks/<slug>/**`) are an **audit trail**, not a second source of truth. Durable knowledge (decisions, contracts, product behaviour) belongs in `docs/specs/**` or `openspec/**`.
+
+## Rules
+
+- `.ai.local/team/tasks/**` stays **tracked in git** by default; do not add a gitignore entry. Committing task artifacts is the human's choice at the commit step.
+- Keep artifacts **small**: no host paths (see `agent-artifacts-no-local-paths`), no raw diff dumps, no duplicate copies (`* (1).*`), no screenshots beyond intentional baselines.
+- **Never bulk-purge** committed artifacts to "clean up". Deleting does not remove git history. Prevention only.
+- Durable output (approved spec, ADR, contract, QA cases) is copied into `docs/specs/**` / `openspec/**`; the task folder is not the SoT.
+- Follow `commit-hygiene`: artifact/doc churn does not share a commit with `app/src/**`.

package/presets/opencode/next/ai-local/rules-library/code-style.md

@@ -0,0 +1,68 @@
+globs: app/src/**/*.{ts,tsx},app/__tests__/**/*.{ts,tsx}
+
+## Body
+
+# Code style (team conventions template)
+
+When editing TS/TSX, acknowledge: `Using .ai.local: code-style(, …)*`.
+
+The preset is generic. This repo has its own naming and file shapes — **open the nearest analog in the same layer and mirror it**. Where a preset example differs, this rule wins.
+
+## Reference analogs (mirror these)
+
+| Layer | Analog |
+|-------|--------|
+| UI page | `app/src/ui/pages/<Domain>/` |
+| UI component | `app/src/ui/components/<Name>/` |
+| Store slice | `app/src/store/slices/<Domain>/` |
+| API service | `app/src/api/services/<Service>/<Domain>/` |
+| Types | `app/src/types/<Entity>.types.ts` |
+| Unit tests | `app/__tests__/unit/<mirrored path>/` |
+
+## Naming
+
+- Domain types — `T` prefix: `TAnalysis`, `TUserProfile`. Transport/response types — `T…Response` (`TAnalysisResponse`).
+- Interfaces / props — `I` prefix: `interface IProps`, `IRootState`.
+- DTO → domain mappers — verb `format`: `formatAnalysis`, `formatBiomarkers`. Not `map…`.
+- Endpoint constants — `SCREAMING_SNAKE` + `_ENDPOINT` (`DOMAIN_ANALYSIS_ENDPOINT`); dynamic — `prepare…Endpoint`.
+- No `FC` / `React.FC` (see `no-react-fc`).
+
+## Components
+
+- `export const X = ({ ... }: IProps) => (...)`; no `FC`.
+- Styles: a sibling styles module; root export `Root`.
+- Local children in `./components/<Name>/`: `Name.tsx` + `styles.ts` (or `Name.styles.ts` when the parent already has a `styles.ts`) + optional `Name.data.ts` / `Name.utils.ts` / `Name.hooks.ts` + `index.ts`. **Strictly forbidden:** declaring a subcomponent in the same file as the parent — see `component-child-decomposition`.
+- Layout sizes of one component (skeleton `height` / `width` / `maxWidth`, one-off `px`) stay as literals in the JSX prop or in `styles.ts`. Do not hoist them into `SCREAMING_SNAKE` constants or a `*.data.ts`.
+- `*.data.ts` is for copy, labels, lookup maps, and values imported by another module. A file that only names pixels is overhead — delete it and inline.
+
+## API layer (`app/src/api/services/<Service>/<Domain>/`)
+
+- `<Domain>.apiMethods.ts` — `export const XxxApiMethods = { fetchX, createX, saveX, deleteX: async (...) => { … } }`.
+- `<Domain>.endpoints.ts` — path constants.
+- `<Domain>.responseTypes.ts` — `T…Response` (DTO).
+- `<Domain>.responseMappers.ts` — `formatXxx(data: T…Response): T…`.
+- `index.ts` — re-export the four above.
+- Cross-entity mappers — `_shared/<Entity>/<Entity>.responseMappers.ts`.
+- Outside the layer, import only from the `@/api` barrel.
+
+## Store (`app/src/store/slices/<Domain>/`)
+
+- Folder: `<Domain>.ts` (slice + thunks + selectors), `types.ts`, `utils.ts`, `index.ts` barrel.
+- Slice named `xxxSlice`, re-exported via the barrel; not a default export.
+- Thunks: `fetchX` / `createX` / `saveX` / `deleteX`; error typing via `rejectWithValue`.
+- Selectors: curried `xxxSelector = (args) => (state: IRootState) => …`; memoize derived values with `createSelector`.
+- Local `interface IRootState { <sliceName>: TState }` in the slice file; state shape typed in `types.ts`.
+- Errors: follow the existing slice pattern; do not rewrite the error model in a point task.
+- Domain comments — in the project language.
+
+## Types (`app/src/types`)
+
+- Project-language JSDoc; `[computed]` prefix on frontend-derived fields; `Xxx.types.ts` or a folder + barrel `index.ts`.
+
+## Tests
+
+- Mirrored path `app/__tests__/unit/<rel>`, `*.spec.ts(x)`; project-language `describe` / `it`.
+
+## Format
+
+- Prettier: no semicolons, single quotes, trailing commas, width 100. The linter enforces it — run the post-change gate.

package/presets/opencode/next/ai-local/rules-library/component-child-decomposition.md

@@ -0,0 +1,81 @@
+globs: app/src/**/*.{ts,tsx},storybook/stories/**/*.stories.tsx
+
+## Body
+
+# Component child decomposition (strict)
+
+When this rule applies, acknowledge: `Using .ai.local: component-child-decomposition(, …)*`.
+
+A subcomponent of a parent UI component **must** live in a dedicated `components/<Name>/` subfolder of the parent. Defining a subcomponent in the same file as the parent is a **forbidden** shortcut — it breaks the convention used by every other modal/card in the repo, makes the parent file mix orchestration with detail rendering, and prevents re-use of the child from sibling features.
+
+This is enforced by the file structure visible in the working tree. A reviewer or `code-reviewer` agent who finds a subcomponent declared alongside the parent's main export must request changes with reference to this rule.
+
+## File structure
+
+```
+Parent/
+├── Parent.tsx                 ← public export, thin composition only
+├── Parent.styles.ts           ← only styles used directly by Parent (Root, Title, layout shell, list)
+├── index.ts                   ← re-export of Parent
+└── components/
+    └── Child/
+        ├── Child.tsx          ← public export of the subcomponent
+        ├── Child.styles.ts    ← styles specific to the child (its own Card, Icon, Title, etc.)
+        ├── Child.utils.ts     ← OPTIONAL: pure helpers
+        ├── Child.data.ts      ← OPTIONAL: lookup maps / constants
+        └── index.ts           ← re-export of Child
+```
+
+- Child file name: `Child.tsx` (PascalCase, same as folder name). Styles: `Child.styles.ts` (prefixed with child name) to avoid collision when the parent also has a `styles.ts`.
+- Parent uses `import { Child } from './components/Child'` (or `./components/Child/index`); never imports from `../Child.tsx` or `../../Child`.
+- The child does not import from the parent's `styles.ts`. If both share a token, they each import it from the design-token source directly.
+- `Child.utils.ts` / `Child.data.ts` are optional and only added when there are real helpers/maps. Do not create empty files.
+
+## Subcomponents
+
+A **subcomponent** is any JSX `<X .../>` (a) the parent repeats, (b) the parent passes resolved props to (instead of letting the child compute them), or (c) that owns its own layout/typography/visual contract. Inline JSX like `<s.Icon><img/></s.Icon>` is a styled element, not a subcomponent.
+
+When the parent has more than one or two branches, several repeated JSX subtrees, or any non-trivial rendering block, that block **must** be extracted to a subcomponent in `./components/<Name>/`. The parent then becomes a thin switch — it owns the wiring, the wrapper, and the iteration that maps data into `<Child>` instances.
+
+## Forbidden
+
+```tsx
+// ❌ Parent file with a co-located subcomponent
+export const ItemsModal = () => (
+  <Modal>
+    {items.map((item) => (
+      <s.Card key={item.id}>
+        <s.Icon><s.IconImage src={...} /></s.Icon>
+        <s.Body><s.Title>{item.title}</s.Title>...</s.Body>
+      </s.Card>
+    ))}
+  </Modal>
+)
+
+// Declared in the same file — file structure is wrong
+const CardItem = ({ item }) => <s.Card>...</s.Card>
+```
+
+## Correct
+
+```tsx
+// ItemsModal/ItemsModal.tsx
+import { CardItem } from './components/CardItem'
+
+export const ItemsModal = () => (
+  <Modal>{items.map((i) => <CardItem key={i.id} item={i} />)}</Modal>
+)
+
+// ItemsModal/components/CardItem/CardItem.tsx
+import * as s from './CardItem.styles'
+
+export const CardItem = ({ item }: { item: TItem }) => <s.Card>...</s.Card>
+```
+
+## Why the rule is strict, not a preference
+
+- **Diffability:** a change to the child shows up in `components/Child/Child.tsx`, not as noise in the parent file.
+- **Reviewability:** the parent file stays short (~50 lines) and the reviewer reads orchestration without scrolling past detail rendering.
+- **Re-use:** the child can be imported by other stories, modals, or pages without copy-paste.
+- **Tests:** a child-only story (visual regression of the card alone) is possible without re-rendering the whole modal.
+- **Lint / IDE:** per-folder patterns scale better than 200-line parent files mixing styles + helpers + subcomponents + data.

package/presets/opencode/next/ai-local/rules-library/feature-flags-experiments.md

@@ -0,0 +1,15 @@
+globs: app/src/constants/**/*.{ts,tsx},app/src/ui/**/*.{ts,tsx}
+
+## Body
+
+# Feature flags & experiments (team conventions template)
+
+When gating UI/behaviour by a flag or A/B experiment, acknowledge: `Using .ai.local: feature-flags-experiments(, …)*`.
+
+## Rules
+
+- Local flags live in one module (e.g. `app/src/constants/localFeatureFlags.ts`) as `isFeature…Enabled`; remote experiments come from the experiments client (`@sh/experiments` analog).
+- Read a flag through the repo's access path — a store slice / provider / singleton mounted at the app root — not by scattering `process.env` checks or ad-hoc constants.
+- Experiment-gated routes are registered in the repo's allowlist (e.g. `EXPERIMENT_PAGES`); do not invent a parallel mechanism.
+- Experimental / legacy page variants are **non-canonical** — do not copy them as the reference for new work, and do not delete a flag without the paired spec / story / e2e sync (flag removal is a cross-cutting change).
+- A flag that flips layout or visual identity is still one purpose per component after the flag is removed — do not bake the flag into a universal branchy component (`react-ui`).

package/presets/opencode/next/ai-local/rules-library/mcp-required-for-ui-layout.md

@@ -1,4 +1,4 @@
-globs: src/ui/**
+globs: app/src/ui/**
 
 ## Body
 

package/presets/opencode/next/ai-local/rules-library/no-react-fc.md

@@ -0,0 +1,46 @@
+globs: **/*.{tsx,ts}
+
+## Body
+
+# No `FC` / `React.FC`
+
+When this rule applies, acknowledge: `Using .ai.local: no-react-fc(, …)*`.
+
+Do **not** type React components as `FC`, `React.FC`, `FunctionComponent`, or `React.FunctionComponent`.
+
+`FC` adds implicit `children`, is outdated for React 18+, and the rest of a typical repo already uses a plain arrow + props type.
+
+## Required shape
+
+```tsx
+interface IProps {
+  title: string
+}
+
+export const Example = ({ title }: IProps) => {
+  return <s.Root>{title}</s.Root>
+}
+```
+
+If there are no props:
+
+```tsx
+export const Example = () => <s.Root />
+```
+
+## Forbidden
+
+```tsx
+import { type FC } from 'react'
+
+export const Example: FC<IProps> = ({ title }) => { /* … */ }
+```
+
+```tsx
+export const Example: React.FC<IProps> = ({ title }) => { /* … */ }
+```
+
+## Notes
+
+- Type props with `interface IProps` / `type TProps` (match the neighboring file).
+- If the component accepts `children`, declare `children` explicitly on the props type — do not get it from `FC`.

package/presets/opencode/next/ai-local/rules-library/no-test-driven-behavior-change.md

@@ -1,4 +1,4 @@
-globs: src/**/*.{ts,tsx}
+globs: app/src/**/*.{ts,tsx},app/__tests__/**/*.{ts,tsx},storybook/**/*.stories.tsx
 
 ## Body
 

package/presets/opencode/next/ai-local/rules-library/pwa-service-worker.md

@@ -0,0 +1,15 @@
+globs: app/src/lib/pwa/**/*.{ts,tsx},app/public/**
+
+## Body
+
+# PWA / service worker (team conventions template)
+
+When touching the service worker, manifest, or offline behaviour, acknowledge: `Using .ai.local: pwa-service-worker(, …)*`.
+
+## Rules
+
+- Service worker and web manifest are wired through the app root / document head via one init hook; do not register a second service worker or add a competing `<link rel="manifest">`.
+- Service-worker scope and asset paths are derived from `basePath` / `assetPrefix` — a hardcoded `/` breaks scoped deployments.
+- A dev-only `Service-Worker-Allowed` header (or equivalent) is a dev concern; do not assume it exists in production.
+- Do not introduce `next-pwa`-style tooling unless the repo already uses it; follow the existing registration path.
+- Offline/caching changes are behaviour changes: update the spec / e2e / QA case that covers offline flows.

package/presets/opencode/next/ai-local/rules-library/qa-test-cases.md

@@ -0,0 +1,14 @@
+globs: docs/qa/**/*.md,app/__tests__/e2e/**/*.cases.md
+
+## Body
+
+# Consolidated QA test cases (`docs/qa/**`)
+
+When editing QA case docs or the matching e2e plan, acknowledge: `Using .ai.local: qa-test-cases(, …)*`.
+
+## Rules
+
+- A consolidated QA doc (`docs/qa/<area>-test-cases.md`) is a **derived view** of the spec + `*.cases.md` — not a second source of truth. Cite the source (spec path / scenario id) per case.
+- Keep the route table, PREFIX map, and grouping in sync with the executable plan; mark each case `as-is` (characterization) or `target` (planned).
+- On a behaviour change, update the QA doc in the same changeset as the `*.cases.md` / spec.
+- Do not weaken or delete cases to match an unintended behaviour change — fix the implementation or file a task (`no-test-driven-behavior-change`).

package/presets/opencode/next/ai-local/rules-library/router-pages.md

@@ -1,5 +1,5 @@
 override: kill next-app-router
-globs: src/pages/**/*.{ts,tsx},src/ui/**/*.{ts,tsx},next.config.ts
+globs: app/src/pages/**/*.{ts,tsx},app/src/ui/**/*.{ts,tsx},app/next.config.ts
 
 ## Body
 
@@ -15,9 +15,11 @@ This rule drops the preset's `next-app-router` rule from context for repos using
 - Domain UI lives in `src/ui/pages/<Name>Page`; route files do not contain layout/business logic.
 - Navigation: `next/router` (`useRouter`) and `next/link`. **Never** `next/navigation`.
 - `_app.tsx` / `_document.tsx` stay in `src/pages/`.
+- Dynamic routes: the dynamic segment is **last**, `[id].tsx` → `[id].html`; do **not** add catch-all `[...slug]` routes. Read a dynamic param only after the router is ready (`useRouterReady()` analog) and parse it with the repo's slug helper; push `/404` when it is invalid.
 
 ## Forbidden
 
 - Creating App Router files (`src/app/**`, `page.tsx`, `layout.tsx`, `loading.tsx`, `error.tsx`, `route.ts`).
 - Importing `next/navigation` or App Router server APIs (`cookies()`, `headers()`, `redirect()`).
-- `getServerSideProps` / `getStaticProps` — the app is a client-rendered static export; data goes through the store/`@/api`.
+- `getServerSideProps` / `getStaticProps` — the app is a client-rendered static export; data goes through the store/`@/api`.
+- Reading `router.query` before `router.isReady` (cold-load crash); non-integer / non-final dynamic segments (nginx serves only integer slugs at the end).

package/presets/opencode/next/ai-local/rules-library/single-source-copy-constants.md

@@ -1,4 +1,4 @@
-globs: src/**/*.{ts,tsx}
+globs: app/src/**/*.{ts,tsx}
 
 ## Body
 
@@ -11,6 +11,8 @@ Copy (button labels, headings, alt text, aria-labels), constants, enums, and rou
 ## Rules
 
 - User-visible copy: inline unless the same string is used in ≥2 distinct places OR is consumed by tests/stories that need a shared reference. Multi-instance refactors belong to a dedicated task.
+- A new inline data table (dictionary/map) larger than ~50 entries requires a cited source (spec, mockup node, or contract) in the task artifact — otherwise it is invented content.
+- Copy changes cite a spec or mockup node.
 - Numeric / pixel / token aliases: inline directly; do not re-wrap into a named constant when used exactly once in the same file.
 - Counters and derived single-use values: inline (`array.length`, computed expressions).
 - Layout sizes of one component (skeleton `height`/`width`/`maxWidth`, one-off `px`) stay as literals in the JSX prop or in `styles.ts`. Do not hoist them into named constants or a `*.data.ts`, even when the same number is repeated in that component's JSX and its styles.

package/presets/opencode/next/ai-local/rules-library/storybook-catalog-structure.md

@@ -0,0 +1,62 @@
+globs: storybook/stories/**/*.stories.tsx, storybook/stories/**/README.md, storybook/stories/**/*
+
+## Body
+
+# Storybook catalog structure
+
+When editing Storybook catalog files, acknowledge: `Using .ai.local: storybook-catalog-structure(, …)*`.
+
+## Before you add a story
+
+- UI develop/refactor starts with **`storybook-ui-quality-gate`** (preview vs mockup + story tests) — stories are not post-hoc docs.
+- Read the folder README: `storybook/stories/pages/README.md`, `components/README.md`, `modals/README.md`.
+- Copy the nearest analog file; do not invent a new sidebar branch.
+- After add/edit (and after UI refactors that stories cover): **`storybook-keep-tests-current`** — tests + baselines green.
+
+## Sidebar roots (fixed)
+
+| Title pattern | Path | Notes |
+|---------------|------|-------|
+| `UI/Pages/<ShortName>` | `pages/<Page>/<Page>.stories.tsx` | Full page; `layout: 'fullscreen'`, `defaultViewport: 'desktop'`. |
+| `UI/Pages/<Page>/Components/<Block>` | `pages/<Page>/Components/<Block>.stories.tsx` | **Required** for page-level blocks. |
+| `UI/Pages/<Page>/Cards/<Card>` | `pages/<Page>/Cards/` | List cards only. |
+| `UI/Components/<Name>` | `components/` | Reusable `app/src/ui/components/**`. |
+| `UI/Modals/<Domain>/<Modal>` | `modals/<Domain>/` | Isolated dialogs only. |
+
+## Page Components section (required)
+
+When a page has distinct blocks (summary, side panel, files, skeletons, etc.):
+
+- Add `storybook/stories/pages/<Page>/Components/<BlockName>.stories.tsx`.
+- Title: `UI/Pages/<ShortName>/Components/<BlockName>`.
+- Cover **every code-implemented visual state** (loading skeleton, empty, error, feature-flag variants).
+- Document in page `README.md`: block × state → export name → fixture/mock id.
+- Nested modals inside blocks: story the **block** or use existing `UI/Modals/*` — not a separate modal story.
+- Pure skeleton/presentational blocks: single default export is OK.
+- White-card blocks: apply the grey-canvas decorator so the card edge is visible. Skip grey/primary/secondary roots (see `storybook-csf-authoring`).
+- If the page CSF grows: extract a block into `Components/` — **never** `PageName.p1.stories.tsx`.
+
+## Placement rules
+
+- Reusable across pages → `storybook/stories/components/` (see components README out-of-scope table).
+- Modal/dialog → `storybook/stories/modals/` only.
+- Page-only block → page `Components/` (not `UI/Components/`).
+- List cards → `pages/<Page>/Cards/` (not modal wrappers).
+
+## README requirement
+
+Each page folder keeps `README.md`: mock id map, state vocabulary, vitest validation path, Components catalog when present.
+
+Example validation (from `storybook/`):
+
+```bash
+yarn vitest run --project=storybook stories/pages/<Page>/Components/<Block>.stories.tsx
+```
+
+## Forbidden
+
+- Duplicating a modal under page/Components when `UI/Modals/...` already exists.
+- New `*Modal*` titles under `UI/Components/`.
+- New flat page-block files at page root — use `Components/`.
+- **No** `*.p1.stories.tsx`, `*.p2.stories.tsx`, or any `*.pN.stories.tsx` — one CSF per `title`.
+- **No** viewport-duplicate stories: `Mobile*`, `Mobile_*`, `defaultViewport: 'mobile*'`, `isMobile` preloads.

package/presets/opencode/next/ai-local/rules-library/storybook-cleanup-temp-screenshots.md

@@ -0,0 +1,40 @@
+glob: always
+
+## Body
+
+# Storybook temp screenshot cleanup
+
+When this rule applies, acknowledge: `Using .ai.local: storybook-cleanup-temp-screenshots(, …)*`.
+
+## When (mandatory)
+
+Before declaring Storybook or UI work complete, and after any browser / Figma / Playwright / Storybook MCP screenshot: delete files **this turn created** that are not product assets or vis baselines.
+
+Leaving dump PNGs in the repo is incomplete work — same severity as red Storybook tests.
+
+## Delete
+
+Typical dumps (names vary):
+
+- Repo-root images: `*-after.png`, `*-before.png`, `positive-story.png`, and any other untracked `*.png` / `*.jpg` / `*.webp` at the workspace root that you created.
+- `/tmp/**` review dumps.
+- Workspace copies of Figma screenshots, browser screenshots, or Playwright traces/screenshots written **into the git worktree** (not CI artifacts).
+
+## Keep
+
+- `storybook/__vis__/<platform>/__baselines__` — CI vis; refresh via `--update`, never `rm` to hide drift.
+- `storybook/__vis__/local` — gitignored local baselines; still refresh, do not wipe.
+- Product assets: `app/public/**`, component `images/`, committed mocks.
+- Files the user explicitly asked to keep.
+
+## How
+
+1. `git status --short` (and `ls` repo root) for untracked/modified images from this turn.
+2. Delete **only those paths**. No `git clean -fd`, no `git checkout` of vis baselines.
+3. Confirm gone. Do not `git add` temp screenshots.
+
+## Forbidden
+
+- Committing verification / MCP / Playwright dump images.
+- Leaving repo-root PNGs "for the user to review" unless they asked.
+- Deleting vis baselines instead of `--update`.