@bonesofspring/ai-rules 0.2.31 → 0.2.32

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## Unreleased
 
+### Next: runtime-model, catalog, seeds, and generated-tree correctness
+
+- **Generated trees no longer ship dangling `.mdc` pointers.** `generate-mavis` / `generate-opencode` rewrite in-body `.mdc` cross-references to sibling rule `.md` stems (embed-mode bodies previously kept Cursor `## Stack notes` verbatim); author `preset-*` meta-rules keep their intentional Cursor `.mdc` references. `check-generated-drift.mjs` now fails on a dangling sibling-stem `.mdc` in any generated rule tree.
+- **New `next` rules (requestable):** `next-static-export` (static-export/SPA runtime model — no SSR/route handlers/middleware/ISR; `getStaticProps` build-time only; `basePath`; `images.unoptimized`), `component-catalog-gate` (Storybook/catalog is the UI dev + visual-review surface; stories ship with the change; catalog package isolation), `forms-validation` (repo form library + DS fields + shared validators).
+- **`security-next` deployment caveat** + a **Compliance / personal data** section; `next-app-core` gains deployment-model, `.ai/context` discovery, and env-through-config guidance; `react-next-anti-hallucination` and `mcp-usage` point at Next's own bundled docs (`node_modules/next/dist/docs/`).
+- **`react-ui` gains** "one component / one styled element — one purpose", a CSS-in-JS interpolation-function rule (no inline arrows in `styled` `${…}`), and async-UI-state guidance; `store-rtk` gains middleware/cross-slice orchestration (`_complexSlices`, no slice→slice imports); `reference-features` adds scaffold/singletons/layouts/guards/cross-feature-hook/internal-slice rows.
+- **Design-token binding no longer hardcodes `next/image`** — binds to the project image primitive (the optimizer may be off under static export).
+- **Seed library fixes + growth:** 4 seeds had `src/**` globs that never matched the `app/src/**` layout (now fixed); `ai-local-overlay`, root `AGENTS.md`, and `docs/LOCAL-OVERLAY.md` now document `.ai.local/rules-library/**` activation; `scripts/check-local-overlay.sh` fails on a bare-`src/` seed glob. New seeds: `analytics-events`, `feature-flags-experiments`, `pwa-service-worker`, `task-levels`, `qa-test-cases`; `router-pages` gains nginx slug + router-ready guard rules.
+- **Pipeline/agent wiring:** `task-router` and `feature-delivery-workflow` require `mockup-reviewer` for UI scope **without** a Figma URL; `build-verifier` runs the catalog suite; `code-review-mr` adds a spec/docs sync gate; `task-analyst`/`openspec-author` templates gain `## Hard rules applied` and `## Compliance impact`; `feature-developer`/`code-reviewer` return a `## Human commits` plan.
+- **`init` overwrite contract documented** (managed vs preserved) in `ai-local-overlay`, root `AGENTS.md`, and `docs/LOCAL-OVERLAY.md`; `post-change-lint`/`tests-unit` prefer package scripts and cover secondary packages.
+
 ### Claude session-start overlay, settings hooks, and dogfood sync
 
 - Claude `ai-local-overlay` is session-start (no `paths:`) on all 10 stacks, inside the 3–5 budget, with entry-file probe text in `CLAUDE.md` and root `AGENTS.md`.

package/docs/LOCAL-OVERLAY.md

@@ -11,6 +11,7 @@ Put a `.ai.local/` directory in your repo. Write rules as plain markdown. The `a
 ├── rules/
 │   ├── our-stack.md        # applied like a rule
 │   └── testing-policy.md   # applied like a rule
+├── rules-library/          # staged-inactive seeds shipped by `init` (move to activate)
 ├── conventions.md          # living gotchas (highest priority)
 └── team/                   # shared agent-team pipeline artifacts (not rules)
     ├── README.md
@@ -27,6 +28,19 @@ No IDE config, no `@include`, no codegen. Same files work in Cursor, Claude Code
 3. If a local rule conflicts with a preset rule, **the local rule wins**.
 4. **Deeper wins** in monorepos: walk `packages/*/.ai.local/` and apply all levels; the model treats the deepest one as the most recent guidance.
 
+## Seed library (`.ai.local/rules-library/`)
+
+`init` also seeds **staged-inactive** rule templates into `.ai.local/rules-library/`. They ship with every install but **do not apply** until you move a matching file into `.ai.local/rules/`.
+
+Why staged: they encode common repo shapes (Pages Router, no-`FC`, a component-catalog quality gate, commit hygiene) that only matter once you confirm your repo actually needs them. Keeping them inactive avoids spending context on rules that do not apply.
+
+The `ai-local-overlay` rule instructs the model to treat a matching seed as the applicable local rule and to recommend activation. The next-stack seed set (27 files) includes: `router-pages` (`override: kill next-app-router` for Pages Router repos), `no-react-fc`, `component-child-decomposition`, `single-source-copy-constants`, `commit-hygiene`, `pre-pr-checklist`, `api-contract-source`, `agent-pipeline-gates`, `artifact-lifecycle`, `agent-artifacts-no-local-paths`, `no-test-driven-behavior-change`, `mcp-required-for-ui-layout`, `ui-change-review-gate`, `task-levels`, `analytics-events`, `feature-flags-experiments`, `pwa-service-worker`, `qa-test-cases`, `forms-validation`, and the `storybook-*` set.
+
+```bash
+# activate a seed
+git mv .ai.local/rules-library/router-pages.md .ai.local/rules/router-pages.md
+```
+
 ## How to write `.ai.local/rules/*.md`
 
 One file = one rule. Plain markdown. **No YAML frontmatter** — the format is shared across IDEs, so each file uses a tiny markdown header for scoping.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "description": "Presets of Cursor, Claude, Mavis, and OpenCode rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",

package/presets/claude/android-kotlin/rules/tooling-and-review/agent-team-orchestrator.md

@@ -77,8 +77,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/claude/go/rules/tooling-and-review/agent-team-orchestrator.md

@@ -77,8 +77,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/claude/ios-swift/rules/tooling-and-review/agent-team-orchestrator.md

@@ -77,8 +77,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/claude/java/rules/tooling-and-review/agent-team-orchestrator.md

@@ -78,8 +78,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/claude/mcp-ts/rules/tooling-and-review/agent-team-orchestrator.md

@@ -74,8 +74,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/claude/next/REPO_AGENTS.md

@@ -43,6 +43,8 @@ Working directory for app scripts: **`app/`**. Detect the package manager from l
 
 After code edits: invoke **`post-change-lint`** (requestable). Full gate: agent `build-verifier`.
 
+Repositories with more than one package (e.g. `app/` + `storybook/`) run each package's own scripts from its own directory; do not conflate runners.
+
 ## Security basics
 
 - Do not commit secrets (`.env`, tokens, credentials).
@@ -65,10 +67,18 @@ Skills: `.cursor/skills/`, `.claude/skills/`, `.mavis/skills/`, or `.opencode/sk
 
 Gotchas, local patterns, and team decisions: **`.ai.local/conventions.md`** (fill after init; `init` does not overwrite it).
 
+## Seed library (`.ai.local/rules-library/`)
+
+`init` seeds **staged-inactive** rule templates here (Cursor `.mdc` sources analog: `presets/cursor/next/ai-local/rules-library/**`). They are **not** active until moved into `.ai.local/rules/`. When a seed matches the task scope, apply it and tell the owner to move it. Typical seeds: `router-pages` (Pages Router override), `no-react-fc`, `component-child-decomposition`, `single-source-copy-constants`, `commit-hygiene`, `pre-pr-checklist`, `api-contract-source`, `agent-pipeline-gates`, `task-levels`, `analytics-events`, `feature-flags-experiments`, `pwa-service-worker`, `qa-test-cases`, `forms-validation`, and the `storybook-*` set.
+
+## Managed vs preserved
+
+`init` owns `.cursor/**`, `.claude/**`, `.mavis/**`, `.opencode/**`, root `AGENTS.md`, and the tool MCP config; it **overwrites/merges** them. Durable project config and authoritative specs belong **outside** those trees: `.ai.local/**`, `.ai/context/**`, `docs/specs/**`, `openspec/**`, repo-root `.mcp.json`. After a re-init, re-check any consumer-owned block added to a managed file.
+
 ## Local overlay (`.ai.local/`) — MANDATORY
 
 A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in monorepos. **All agents MUST read and apply it on every turn.** Rules there override preset rules; in conflicts, the local rule wins. `override: kill <preset-rule-name>` drops the named preset rule from the agent's context entirely.
 
-Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
+Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`. Staged seeds live in `.ai.local/rules-library/**`; a matching seed must be moved into `.ai.local/rules/` to activate.
 
 On every turn, probe `ls -la .ai.local`, apply `.ai.local/rules/*.md` and `.ai.local/conventions.md`, and acknowledge `Using .ai.local: <rule-name>`. Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule is always-on on Cursor and session-start on Claude (no `paths:`). Mavis and OpenCode have no native `alwaysApply`; this section plus the platform entry's essential-rules list is the reinforcement.

package/presets/claude/next/agents/build-verifier.md

@@ -39,6 +39,7 @@ Use **`rules/tooling-and-review/package-manager.md`** for the repo package manag
 2. **`lint:css`** — full Stylelint.
 3. **`type-check`** — when TypeScript changed.
 4. **Unit tests** — run specs for changed modules (paths from diff); if unclear, run the narrowest parent suite that covers changed mappers/services/store.
+5. **Component catalog** — when the repo ships a catalog (e.g. `storybook/`) and `app/src/ui/**` or catalog files changed, run the catalog's own test/visual-baseline suite from the catalog package and require green **without** `--update` (`component-catalog-gate`). A green app unit run does not cover catalog stories.
 
 Prefer **`lint`** (= js + css + type-check) before handoff on large changes.
 

package/presets/claude/next/agents/code-reviewer.md

@@ -116,5 +116,6 @@ Do not mix this output with retrospective facilitation — keep review and retro
 
 - **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for brief/decomposition, implementation, validation evidence, and the scoped git diff.
 - **Owned outputs:** `review.md`; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `review`) and preserve all foreign items in `manifest.artifacts[]`.
+- **Commit hygiene:** never run `git commit` / `git push`. Reviewer turns end with findings only; when asked for commit guidance, propose an area-split commit plan (source / artifacts / docs) with the owning slug.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `changes_requested`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/claude/next/agents/feature-developer.md

@@ -149,5 +149,6 @@ Shipped browser split: Playwright MCP for e2e specs/selectors; Chrome DevTools M
 
 - **Authoritative inputs:** read `.ai.local/team/tasks/<slug>/artifact-manifest.json` first; consume handoff `artifactInputIds` when supplied, otherwise consume the items in `manifest.artifacts[]` for `brief.md`, `decomposition.md`, current scope, and applicable prior findings.
 - **Owned outputs:** `implementation.md` plus changed implementation/test paths; upsert only the entry in `manifest.artifacts[]` assigned by handoff (`artifactOutputId`; fallback `implementation`) and preserve all foreign items in `manifest.artifacts[]`.
+- **Commit hygiene:** never run `git commit` / `git push`. At the end of the turn return a `## Human commits` block: files touched + a proposed commit message, split by area (source / artifacts / docs) with the owning slug/ticket in the subject. See the consumer `commit-hygiene` local rule.
 - **Terminal receipt:** cover applicable AC/task IDs, list authoritative evidence paths, and emit `completed` or `blocked`. Bind it to the supplied `attemptId` when present.
 - **Shared state:** never create or mutate `status.json` or `metrics.json`; the orchestration runtime/hook owns lifecycle, gates, retries, attempts, and timestamps.

package/presets/claude/next/agents/openspec-author.md

@@ -77,6 +77,8 @@ Hard constraints (read `config.yaml rules.proposal` first — they win):
 
 - `proposal.md` ≤ 500 words.
 - `## Non-goals` section mandatory (omit → `blocked`).
+- `## Compliance impact` block mandatory in `proposal.md` and `design.md` (None | Affected — list PD / medical / analytics / SSR-cookie / third-party surfaces); when unclear, default to `Affected` and block.
+- `## Hard rules applied` block at the top of `proposal.md` / `design.md` / `tasks.md` (applicable rules + how applied; `N/A — reason` for the rest), when the consumer repo maintains hard rules.
 - `## What Changes` lists capability deltas **only**; no implementation steps.
 - `## Capabilities` table groups deltas by capability slug; cite spec paths.
 - Spec deltas use `## MODIFIED Requirements` heading (or `## REMOVED Requirements`); Each `### Requirement:` block carries `SHALL` statements and `#### Scenario:` Given/When/Then. Mirror existing capability voice.

package/presets/claude/next/agents/task-analyst.md

@@ -66,6 +66,13 @@ Create or update files under `.ai.local/team/tasks/<slug>/`:
 ## Slug
 <slug>
 
+## Hard rules applied
+- <applicable preset/local rule> — <how applied>
+- N/A — <reason>   (list non-applicable hard rules explicitly)
+
+## Compliance impact
+None | Affected — <surfaces: PD / medical data / analytics / SSR cookies / error reporting / third-party scripts>
+
 ## Goal
 ...
 

package/presets/claude/next/agents/task-router.md

@@ -117,6 +117,7 @@ Keep top-level `profile` and emit this top-level object in every new `pipeline.j
 - If prompt or `brief.md` contains `figma.com` on `feature` / `refactor` / `spike` / `spec-gen`, insert **mockup-reviewer** after **task-analyst** (when present) and before **solution-architect** and **feature-developer**. Set `model: "strong"` on that step. Do not add static `humanGates: ["after:mockup-reviewer"]` (FAIL-only hook exception). Never put `mockup-reviewer` in a `parallel: true` step (FAIL-only gate is serial).
 - Classify intent `mockup-review` **before** `ux-design` **before** `review-only`. A `figma.com` URL with review-not-implement language is `mockup-review` even without the word «макет», including when the user said «ревью UX». <!-- i18n-keep: E4 -->
 - If UI stack and (required-signal or advisory UI AC), instruct **task-analyst** to load skill `ux-design` (no new pipeline step; analyst default model, not `strong`). Required-signal: user asked UX, or AC require flows/states, or spec-gen page/feature.
+- If the resolved scope touches UI paths (`app/src/ui/**`, or the repo's component-catalog root) on `feature` / `refactor`, insert **mockup-reviewer** even **without** a `figma.com` URL — it reviews against the AC / `ux-design.md` instead of Figma. Pair it with a **`mockup-review.md`** terminal artifact requirement (the UI change is not complete without it) and, where the repo ships a component catalog, a catalog-test note on `build-verifier` (`component-catalog-gate`).
 - Skip **task-analyst** if AC/scope fully specified → document in `skipped`.
 - Add **solution-architect** for cross-layer / new public APIs — after analyst, before developer.
 - Add **api-contract-reviewer** for new/changed backend contracts — before developer.

package/presets/claude/next/rules/README.md

@@ -44,6 +44,7 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads:
 | `design-guidance.mdc` | `tooling-and-review/design-guidance.md` |
 | `mcp-usage.mdc` | `tooling-and-review/mcp-usage.md` |
 | `next-app-router.mdc` | `stack/next-app-router.md` |
+| `next-static-export.mdc` | `stack/next-static-export.md` |
 | `arrow-functions.mdc` | `stack/arrow-functions.md` |
 | `types-jsdoc.mdc` | `stack/types-jsdoc.md` |
 | `no-type-assertion-as-import-export.mdc` | `stack/no-type-assertion.md` |
@@ -62,6 +63,8 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads:
 | `store-rtk.mdc` | `api-and-data/store-rtk.md` |
 | `react-ui.mdc` | `ui-and-accessibility/react-ui.md` |
 | `design-tokens-binding.mdc` | `ui-and-accessibility/design-tokens-binding.md` | Figma → repo token binding (typography/color/spacing/imagery); per-element parity + self-check |
+| `component-catalog-gate.mdc` | `ui-and-accessibility/component-catalog-gate.md` | Storybook/catalog is the UI dev + visual-review surface; stories ship with the change |
+| `forms-validation.mdc` | `ui-and-accessibility/forms-validation.md` | Forms via the repo form library + DS fields + shared validators |
 | `react-a11y-coding.mdc` | `ui-and-accessibility/react-a11y-coding.md` |
 | `no-props-spread.mdc` | `ui-and-accessibility/no-props-spread.md` |
 | `css-property-order-stylelint.mdc` | `ui-and-accessibility/css-property-order.md` |

package/presets/claude/next/rules/anti-hallucination/react-next-anti-hallucination.md

@@ -11,6 +11,13 @@ These rows **OVERRIDE** generation for the listed patterns. Before inventing an
 
 App Router–specific rows (async `params` / `cookies()`, invented auth helpers, etc.) stay in **`stack/next-app-router.md`**. This rule covers broader React / RTK / Next phantom imports and boundary mistakes across `app/**`.
 
+## 0. Installed Next ships its own docs (read them first)
+
+The installed `next` may bundle version-pinned agent docs and a managed `AGENTS.md` block written by `next dev`:
+
+- Docs: `node_modules/next/dist/docs/` (`01-app`, `02-pages`, `03-architecture`, …). Prefer these over blog posts and over training data for framework APIs — they match the installed major.
+- Managed block: `<!-- BEGIN:nextjs-agent-rules -->` in `AGENTS.md` (see `node_modules/next/dist/server/lib/generate-agent-files.js`). **Do not delete it** — `next dev` re-creates it; commit it with your change to keep the tree clean.
+
 ## 1. Phantom / wrong Next imports
 
 | ❌ Avoid | ✅ Prefer |
@@ -56,6 +63,9 @@ App Router–specific rows (async `params` / `cookies()`, invented auth helpers,
 | `Router.push` / Pages `withRouter` patterns in `app/` UI | App Router navigation helpers already used in `app/src/ui/**` |
 | Client `fetch` / raw HTTP from UI or `page.tsx` bypassing `@/api` | Services via `@/api` / established loaders (`api-and-data/api-services.md`, `api-and-data/http-client.md`) |
 | Invented `next/link` props that siblings never use (e.g. fake prefetch enums) | Match existing `<Link>` usage; verify against installed Next |
+| `getServerSideProps` / `getInitialProps`, `pages/api/**`, `route.ts`, `middleware.ts` in an `output: 'export'` repo | build-time `getStaticProps` / `getStaticPaths` or client store/thunk fetch (`stack/next-static-export.md`) |
+| Hardcoded `/` root for links / assets when the repo uses `basePath` / `assetPrefix` | Derive from `basePath` / `assetPrefix` |
+| `next/image` `loader` / `sizes` / `quality` expecting the optimizer in a repo with `images.unoptimized: true` | The repo's image primitive; no optimizer assumptions |
 
 ## 6. Version drift
 

package/presets/claude/next/rules/api-and-data/store-rtk.md

@@ -49,6 +49,12 @@ impact: HIGH
   - avoid duplicating entity descriptions in multiple places.
 - **Domain boundary**: in **state**, store domain models; the client **response wrapper** type is acceptable as a thunk **return type** or interim before mapping — without duplicating DTOs in state fields unnecessarily (aligned with `api-and-data/api-services.md` and `api-and-data/http-client.md`).
 
+# Middleware and cross-slice orchestration
+
+- Cross-cutting side effects (analytics, captcha, file lifecycle, cross-slice sync) live in **listener middleware** at `app/src/store/middleware/<Domain>Middleware/`, registered in the store factory — follow the repo's `prepend`/`concat` order.
+- A slice **must not import another slice**. When two domains must react to each other, orchestrate in middleware or a dedicated `_complexSlices/<Domain>` module (`_utilsSlices` for pure helpers) — never a direct slice→slice import.
+- Prefer a thunk for a single request/response; prefer middleware for reactions that span slices or emit analytics.
+
 # Slice testing
 
 - For important slices:

package/presets/claude/next/rules/architecture/feature-delivery-workflow.md

@@ -8,6 +8,10 @@ paths:
 
 When the prompt or `brief.md` contains a `figma.com` URL, **mockup review** (`mockup-reviewer` / skill `mockup-review`) must complete — or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue` — **before UI implementation**. Non-UI tasks no-op this gate. When required-signal and **no** `figma.com`, **`ux-design.md`** (on the analysis manifest entry) must exist and not be `INCOMPLETE` before UI work — else **blocked**, hand back to `task-analyst`. Parallel to the mockup gate.
 
+**UI-scope gate (no Figma).** When the scope touches `app/src/ui/**` or the component-catalog root on `feature` / `refactor`, a terminal `mockup-review.md` is required **even without** a `figma.com` URL — reviewed against the AC / `ux-design.md`. Where the repo ships a component catalog, stories ship with the UI and `build-verifier` runs the catalog suite green (`ui-and-accessibility/component-catalog-gate.md`).
+
+**Consumer context.** When `.ai/context/**` exists, read it before deriving architecture, domain vocabulary, or test placement.
+
 ## Style discovery (mandatory)
 
 Before writing a new file in a layer, open **1–2 analog files** in the same layer and mirror: export shape, name prefixes (`T` / `I` where the repo uses them), file suffixes (`.apiMethods.ts`, `.endpoints.ts`, `.data.ts`, `.hooks.ts`, `styles.ts`), mapper / selector / thunk naming, and barrel shape. Record the analogs in the handoff. Where this preset's examples differ from the repo, **the repo wins**.
@@ -16,7 +20,7 @@ Before writing a new file in a layer, open **1–2 analog files** in the same la
 
 When the prompt or `brief.md` contains a Figma URL with a node id (`?node-id=…`), `mockup-reviewer` must walk the node subtree via Figma MCP and emit **two sections** in `mockup-review.md`:
 
-- `## Design contract` — Figma variables, text styles, components/assets used by the subtree, with the repo mapping (`@sds/tokens-colors` / `@sds/brand-colors` / `@sds/tokens-typography` / `@sds/tokens` / DS components / `next/image` with Figma-derived `src/width/height`). This is the binding table the developer uses for typography, color, spacing, and imagery.
+- `## Design contract` — Figma variables, text styles, components/assets used by the subtree, with the repo mapping (`@sds/tokens-colors` / `@sds/brand-colors` / `@sds/tokens-typography` / `@sds/tokens` / DS components / the project image primitive with Figma-derived `src/width/height`). This is the binding table the developer uses for typography, color, spacing, and imagery.
 - `## Node decomposition (AC-2)` — the child→component map (with a `Bindings` column for the Figma design bindings).
 
 `feature-developer` must **not** start UI implementation until both sections are present, and must load requestable `ui-and-accessibility/design-tokens-binding.md` to bind every value to a Figma variable / text style / repo token (raw `#…` / `px` are a finding). The full procedure and verdict rule live in the `mockup-reviewer` agent prompt and the `mockup-review` Stack notes.

package/presets/claude/next/rules/architecture/product-specs-authoring.md

@@ -119,5 +119,6 @@ Block handoff via `open_questions` until fixed:
 ## Stack notes
 
 - Author via skill `spec-authoring`; templates from package assets / consumer `docs/specs/_templates/`.
+- **Glossary & contrast (mandatory):** before authoring, read the repo glossary (`openspec/config.yaml` `context:`, `.ai/context/**`, domain README). Each generated spec maps product terms to code symbols + record types and adds one **contrast** requirement/scenario against the nearest confusable symbol. Declare **compliance impact** (None | Affected) for any spec touching medical/personal data or analytics.
 - Field semantics match discovery stem (`routes` = URL paths; `e2e` = Playwright).
 - Requestable — not always-on / session-start.

package/presets/claude/next/rules/architecture/product-specs.md

@@ -63,5 +63,6 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 ## Stack notes
 
 - `routes`: app URL paths. `ui` / `store`: presentation + RTK/store paths (e.g. `app/src/ui/pages/...`). `e2e`: Playwright paths under `app/__tests__/e2e/**` (or repo equivalent).
+- **Domain glossary & contrast:** read the repo glossary first (e.g. `openspec/config.yaml` `context:`). Every spec that names a domain states a **term → code symbol + record type** mapping and includes one **contrast** scenario naming the nearest confusable symbol/page (e.g. an in-person-consultation spec contrasts `OfflineConsultation*` with `OnlineConsultationPage`). This prevents the highest-frequency domain-confusion bug in these repos.
 - Dogfood example (emedcard-web AnalysisPage): `docs/specs/domains/analysis/analysis-page.md`.
 - Requestable / `docs/specs/**` globs — not always-on / session-start.

package/presets/claude/next/rules/architecture/reference-features.md

@@ -27,6 +27,11 @@ Replace **TBD** with real paths after team agreement (or on `ai-rules init` in t
 | Types module | **TBD** `app/src/types/<example>/` | domain types, JSDoc, barrel export |
 | Unit tests | **TBD** mirrored under `app/__tests__/unit/<rel>` | `*.spec.ts`, describe/it naming |
 | E2E area | **TBD** `app/__tests__/e2e/<Area>/` | `*.cases.md`, page objects, `_shared/` |
+| Scaffold | **TBD** `app/src/boilerplate/**` | new-component skeleton (copy, then rename) |
+| Global singletons | **TBD** `app/src/ui/components/_singletons/**` | app-root-mounted containers (modals, sync, flags) |
+| Layout / guard | **TBD** `app/src/ui/layouts/**`, `app/src/ui/guards/**` | route wrapping (auth, chrome) |
+| Cross-feature hooks | **TBD** `app/src/core/**` | reusable feature hooks used across pages |
+| Internal slices | **TBD** `app/src/store/slices/_complexSlices/**`, `_utilsSlices/**` | cross-slice orchestration / pure helpers — **no** direct slice→slice imports |
 
 ## How to use
 

package/presets/claude/next/rules/stack/next-app-core.md

@@ -8,6 +8,9 @@ Concrete versions come **from `package.json` and configs of the target repositor
 - `app/tsconfig.json`: `paths: { "@/*": ["./src/*"] }` (`baseUrl` may be absent with TS ≥5 / `moduleResolution: bundler` — check the file, do not add it blindly).
 - **Requirement:** `@/*` instead of relative imports that climb the tree.
 - **Router mode:** detect from the repo before adding routes — App Router (`app/src/app/**`, `page.tsx`) vs Pages Router (`app/src/pages/**`, `_app.tsx`). Do **not** assume App Router; follow the mode already in use (`stack/next-app-router.md`, `stack/navigation-router.md`).
+- **Deployment model:** read `output` in `next.config.*`. With `output: 'export'` the app is a static SPA — no server runtime, no API routes / middleware / SSR (`stack/next-static-export.md`).
+- **Consumer context:** when `.ai/context/**` exists, read it for the repo's compressed architecture, domain glossary, and test-placement conventions before deriving them yourself.
+- **Env access:** read `NEXT_PUBLIC_*` through the repo's config module (e.g. `@/config`); new public keys must also be listed in `next.config.*` `env`. Never read `process.env` inside components.
 
 # Architectural layers
 

package/presets/claude/next/rules/stack/next-static-export.md

@@ -0,0 +1,36 @@
+---
+description: Static-export / SPA Next.js (output 'export') — no server runtime; what is unavailable and what to use instead
+impact: HIGH
+paths:
+  - app/next.config.*
+  - app/src/pages/**/*
+---
+
+# Static export (Next.js `output: 'export'`)
+
+Detect the deployment model **before** writing data-fetching or routing code: read `output` in `next.config.*`. With `output: 'export'` the build produces a static SPA — there is no server runtime at request time.
+
+## Unavailable
+
+- `getServerSideProps`, `getInitialProps`.
+- API routes (`pages/api/**`, App Router `route.ts`) and `middleware.ts`.
+- Server Actions; server `cookies()` / `headers()`.
+- ISR / `revalidate` / `dynamic = 'force-dynamic'`.
+- The image optimizer when `images.unoptimized: true` (`next/image` `loader` / `sizes` buy nothing).
+
+## Available / preferred
+
+- `getStaticProps` / `getStaticPaths` run at **build** time only.
+- Runtime data comes from the browser: store thunk → `@/api` service (`store-rtk.md`, `api-services.md`).
+- Auth / session are enforced by the BFF plus a client route guard — not by a Next server.
+- `basePath` / `assetPrefix`: build local links and asset URLs from those values; never hardcode `/`.
+
+## Agent requirement
+
+- Copy the data-fetch and navigation pattern from a sibling page under `app/src/pages/**`; do not port SSR/RSC examples from docs or blogs into a static-export repo.
+- If a requested feature implies a server runtime, mark it **N/A — static export** and propose the client/BFF alternative instead of writing server code.
+
+## Related
+
+- `react-next-anti-hallucination.md` — phantom-import banlist for this deployment model.
+- `navigation-router-stack.md` — Pages Router vs App Router.

package/presets/claude/next/rules/testing/tests-e2e-structure.md

@@ -77,6 +77,7 @@ Bad (no capital after period; or wrong locale for configured ESLint):
 ## Stack notes
 
 - Runner: Playwright (`@playwright/test`).
+- Consolidated QA docs (`docs/qa/**`): when present they are a derived view of the spec + `*.cases.md` (route table, `as-is`/`target` marking, PREFIX map). Cite the source per case and keep them in sync on behaviour change — do not treat them as a second SoT.
 - E2E folder: `app/__tests__/e2e/**`.
 - Placement mirrors source paths: `app/src/<rel>` → `app/__tests__/e2e/<rel>`. Use the deepest folder of the source under test; page-wide scenarios mirror the page folder.
 - Scenario plans: `*.cases.md` files — canonical source of scenarios.

package/presets/claude/next/rules/testing/tests-unit.md

@@ -87,6 +87,7 @@ Bad (no capital after period; or wrong locale for configured ESLint):
 - `app/src/mocks/**` — shared fixtures and MSW handlers live here (or repo equivalent).
 - Unit-test placement mirrors source paths: `app/src/<rel>` → `app/__tests__/unit/<rel>`. Do not colocate `*.spec.ts(x)` or `*.test.ts(x)` under `app/src/**`.
 - HTTP-client behavior tests live under the mirrored `app/__tests__/unit/lib/clients/**` path (prefer `*.spec.ts`).
+- Prefer the package script over a bare runner (`yarn test`, not `npx jest`): scripts carry env (`TZ`), coverage, and reporters that CI depends on.
 - UI tests live under the mirrored `app/__tests__/unit/ui/**` path. Import the source under test through the `@/` alias.
 - `## Stack notes` content is stripped by `scripts/check-shared-core-drift.sh` before byte-comparing this file against `_shared/core/testing/testing-principles.md`; keep prose above (core content) verbatim against the core file.
 

package/presets/claude/next/rules/tooling-and-review/agent-team-orchestrator.md

@@ -91,8 +91,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Sc
 
 - Read the manifest before broad prior-artifact discovery. Each step receives authoritative input entry IDs, owns named output entry IDs, and finishes with one terminal receipt linked to AC/task IDs.
 - Markdown remains detailed evidence; the manifest records producer, status, authoritative paths, timestamps, outcome, and evidence paths.
-- 
-                  Agents upsert only the items in `manifest.artifacts[]` they own and preserve foreign items. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges.
+- Agents upsert only the items they own in `manifest.artifacts[]` and preserve all foreign items in that array. Parallel agents use distinct IDs; the parent/orchestrator serializes manifest merges. The top-level array key is `artifacts` — not `entries`; see `agent-artifact-contracts.md` for the schema callout.
 - The orchestration runtime/hook is the single writer for `status.json` lifecycle fields and `metrics.json`. Agents read status for eligibility but never rewrite state, gate, retry, attempt, timestamp, or metrics fields.
 - Missing/stale manifests are reported as a handoff gap; fall back to `brief.md`, `decomposition.md`, and `pipeline.json` rather than inventing authority.
 

package/presets/claude/next/rules/tooling-and-review/ai-local-overlay.md

@@ -12,8 +12,9 @@ This rule is mandatory. **You MUST** obey it on every turn, without exception.
 1. **Probe** — before answering, run `ls -la .ai.local` from the repository root.
 2. **Walk** — if `.ai.local/` exists at multiple levels (monorepo), read every level from root to leaf. **Deeper wins** in practice: more specific rules appear later in the assembled context and take precedence.
 3. **Apply** — treat every `.ai.local/rules/*.md` and `.ai.local/conventions.md` as a higher-priority rule for this repo. Do **not** load `.ai.local/team/**` as rules (shared pipeline artifacts). The block below ("Authoring `.ai.local/rules/*.md`") defines the conventions.
-4. **Conflict** — if a local rule conflicts with a preset rule, **the local rule wins**. If a local rule body contains `override: kill <preset-rule-name>`, drop that preset rule from your context window entirely.
-5. **Acknowledge** — when answering a user question, briefly state which `.ai.local/` rules apply to the current task (one line is enough). Format: `Using .ai.local: <rule-name>(, <rule-name>)*`. If no `.ai.local/` exists, do NOT mention this rule.
+4. **Activate seeds** — if `.ai.local/rules-library/<seed>.md` exists and matches the current task scope, treat it as the applicable local rule and tell the owner to move it into `.ai.local/rules/`. Seeds are **staged-inactive** templates shipped by `init` (e.g. `router-pages`, `no-react-fc`, `storybook-ui-quality-gate`, `component-child-decomposition`); they do **not** apply until moved.
+5. **Conflict** — if a local rule conflicts with a preset rule, **the local rule wins**. If a local rule body contains `override: kill <preset-rule-name>`, drop that preset rule from your context window entirely.
+6. **Acknowledge** — when answering a user question, briefly state which `.ai.local/` rules apply to the current task (one line is enough). Format: `Using .ai.local: <rule-name>(, <rule-name>)*`. If no `.ai.local/` exists, do NOT mention this rule.
 
 If `.ai.local/` does not exist → **no-op**, do not error. Do not produce any log line about its absence.
 
@@ -29,6 +30,18 @@ Each `.ai.local/rules/<name>.md` is a plain-markdown rule body. The model parses
 
 Keep files ≤ 120 lines. Match the style of preset rules (short sections, bullets, code examples).
 
+## What `init` overwrites vs preserves
+
+`init` manages the tool trees; they are **not** the home of durable project config.
+
+| Overwritten / merged by `init` | Preserved |
+|---|---|
+| `.cursor/**`, `.claude/**`, `.mavis/**`, `.opencode/**` (rules, agents, skills, commands, hooks) | `.ai.local/**` |
+| root `AGENTS.md` (from `REPO_AGENTS.md`) | `docs/specs/**`, `openspec/**` |
+| tool MCP config (`.cursor/mcp.json`; `opencode.json` — `mcp` merged, other blocks may be rewritten) | repo-root `.mcp.json`, `.ai/context/**`, `.ai.local/rules/**` |
+
+Put durable project-owned agent config and authoritative specs **outside** the tool trees (`.ai.local/`, `.ai/context/`, repo-root `.mcp.json`). After any re-init, verify consumer-owned blocks you added to a managed file (e.g. `opencode.json` `instructions` / `permission.bash`) survived.
+
 ## Limitations (read this)
 
 - Cursor, Claude, Mavis, and OpenCode do **not** natively read `.ai.local/`. This rule is a **prompt-only** mechanism: it asks you, the model, to read and apply the files. Reliability is high but not 100%.
@@ -40,4 +53,5 @@ Keep files ≤ 120 lines. Match the style of preset rules (short sections, bulle
 
 - Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package.
 - Living gotchas: `.ai.local/conventions.md`. Pipeline artifacts: `.ai.local/team/` (do not load as rules).
+- Staged seeds: `.ai.local/rules-library/**` (move a matching seed into `.ai.local/rules/` to activate).
 - Root `AGENTS.md` reinforces this rule with a `MANDATORY` section.

package/presets/claude/next/rules/tooling-and-review/code-review-mr.md

@@ -69,3 +69,7 @@ When the diff touches UI / layout / styling (paths under `app/src/ui/**`, global
 - Findings: `path:line` + Figma node id + viewport + severity. Emit a `## Figma parity (UI)` section in `review.md`.
 - **Storybook visual baselines are not a substitute.** Approving a UI MR on Storybook baselines alone is not acceptable when a Figma reference exists.
 - Missing or `unable_to_compare` parity section on a UI-touching MR with a Figma reference → `REQUEST_CHANGES`. Unbound raw values where a token exists (typography / color / spacing / imagery) → `blocker` / `important`. The full gate lives in the `code-reviewer` agent prompt; this rule cross-references it.
+
+### Spec / docs sync (behaviour change)
+
+When the diff changes documented `app/src/**` behaviour and the repo carries a spec tree (`docs/specs/**`, `openspec/specs/**`, `docs/qa/**`, or `*.cases.md`), the same changeset must update the linked page / spec / QA case (or record an explicit open-question gap). A missing update on an **AC-named** surface → `REQUEST_CHANGES`; on a non-AC surface → `important`. Do not treat `docs/specs` and `openspec` as substitutes for each other — keep both in sync.

package/presets/claude/next/rules/tooling-and-review/mcp-usage.md

@@ -93,6 +93,7 @@ Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plu
 
 ## Stack notes
 
+- **Installed Next docs first:** the installed `next` may ship version-pinned agent docs at `node_modules/next/dist/docs/` and a managed `AGENTS.md` block. Prefer them for framework APIs (they match the installed major) — reach for Context7 only when they are insufficient or absent.
 - Pipeline **`mockup-reviewer`** is the only agent that reads Figma for mockup review. See `mockup-review`.
 - Shipped besides Context7: browser automation MCP (`playwright` / `playwright-test` / `user-playwright`) and `chrome-devtools`.
 - **Split:** Playwright MCP → e2e agents (planner/generator/healer), selector checks, spec reproduction. Chrome DevTools MCP → `debugger` / `performance-auditor` against a **running app** (console, network, traces). Not a substitute for e2e.

package/presets/claude/next/rules/tooling-and-review/post-change-lint.md

@@ -19,6 +19,10 @@ Exceptions: documentation edits outside `app/`, CI configs, `.claude/rules/**`,
 
 **Pipeline exception:** if the task runs through the agent team and the next step is `build-verifier`, the developer may limit lint/type-check to **changed files**; full run is `build-verifier`’s duty. In single-agent mode (no pipeline) — always a full run.
 
+**Secondary packages:** when the repo has more than one package with a manifest (e.g. `app/` + `storybook/`), run each package's own scripts from its own directory. Do not conflate runners (app unit runner vs catalog runner).
+
+**Run the package script, not a bare runner:** prefer `yarn lint:js` / `yarn test` over `npx eslint` / `npx jest`. Scripts carry env (`TZ`), coverage, and reporters that CI depends on; a bare runner can diverge from CI.
+
 ## Required commands
 
 Working directory — **`app/`**. Package manager — **`tooling-and-review/package-manager.md`**.

package/presets/claude/next/rules/tooling-and-review/security-next.md

@@ -1,5 +1,6 @@
 ---
 description: Next.js frontend security — secrets, auth, XSS, Server Actions, env
+impact: CRITICAL
 paths:
   - "app/src/**/*.{ts,tsx}"
   - "app/**/app/**/*.{ts,tsx}"
@@ -14,6 +15,8 @@ paths:
 
 Coding-time checklist. Full audit → agent `security-reviewer` + skill `code-review`.
 
+**Deployment model first.** Read `output` in `next.config.*`. With `output: 'export'` there is **no server tier**: the Server Actions / route handlers / middleware items below are **N/A**. The applicable subset is Secrets & env, XSS, redirects, data exposure, and third-party scripts — and auth/session are enforced by the BFF plus a client route guard.
+
 ## Secrets and env
 
 - Never put service / secret keys in `NEXT_PUBLIC_*` or client bundles (`sk_`, private API keys, DB URLs).
@@ -26,6 +29,7 @@ Coding-time checklist. Full audit → agent `security-reviewer` + skill `code-re
 - Middleware may refresh sessions; do not treat middleware alone as authorization.
 - Prefer httpOnly secure cookies over `localStorage` for tokens when the repo pattern allows.
 - Never trust client-only session claims without a server verify step used by the project.
+- **Static-export / SPA repos:** there is no server session verify — use the repo's client route guard plus BFF-issued httpOnly cookies; do not invent a server verifier.
 
 ## Mutations and input
 
@@ -51,6 +55,15 @@ Coding-time checklist. Full audit → agent `security-reviewer` + skill `code-re
 | Invented auth helpers not in `package.json` / codebase | Copy patterns from existing auth routes |
 | Putting secrets in `NEXT_PUBLIC_*` | Server-only env + server modules |
 | Auth only in middleware | Server `getUser` / session verify in layout/page/action |
+| Server session verifier / Server Action in a static-export repo | Client route guard + BFF-issued httpOnly cookie |
+
+## Compliance / personal data (regulated apps)
+
+For apps that ship medical or personal data (e.g. GDPR / local data-protection law):
+
+- Logs, traces, analytics payloads, error reports, and third-party scripts must **not** carry PD, full record text, raw auth tokens, or full URL search params.
+- Flag every new third-party script and every change to the SSR/cookie payload shape for review.
+- Any change touching PD, medical data, analytics, or third-party scripts declares a **compliance impact** block (None | Affected) in its L2+ artifact; when unclear, default to Affected and block.
 
 ## Agent requirement
 

package/presets/claude/next/rules/ui-and-accessibility/component-catalog-gate.md

@@ -0,0 +1,39 @@
+---
+description: Component catalog (Storybook/Ladle) is the required UI dev + visual-review surface — stories ship with the UI change
+impact: MEDIUM
+paths:
+  - app/src/ui/**/*
+  - storybook/**/*
+---
+
+# Component catalog gate (UI quality)
+
+When the repo ships a **component catalog** (Storybook, Ladle, Chromatic, or a `stories/` tree), it is the required surface for developing and reviewing UI. A route screenshot, a source-only review, or unit tests without stories is **not** enough.
+
+## Scope
+
+- Triggers: a new `app/src/ui/**` component / page / block / modal, or a visual/interaction refactor (layout, styles, tokens, copy, hover/open, empty / error / loading).
+- Skip: types / API / store / mocks with no render or style change.
+
+## Rules
+
+- **Stories ship with the UI**, in the same change — not after.
+- **Compare against the design source** (Figma, else the AC): the catalog is the canvas, the design is the truth. Visual baselines are a **regression detector**, not a design spec — fix the implementation first, then update the baseline.
+- **Package isolation:** when the catalog is its own package (own `package.json` / lockfile / `node_modules`), it resolves dependencies from **its own** `node_modules` — never the app's. Missing package ⇒ add it to the catalog manifest; never alias into the app.
+- **Clean up** temp screenshots you created this turn; keep only intentional baselines and product assets.
+- Keep catalog tests green — do not finish with red or stale baselines.
+
+## Stack notes
+
+- Catalog: Storybook. Developer loop: read Figma → implement → preview the story → screenshot → compare → fix → **update baselines last**.
+- Run the catalog runner from the catalog directory (e.g. its own Vitest project), not the app's unit runner.
+
+## Handoff
+
+- `feature-developer`: a UI work package in a catalog repo is **not done** without a story and a green catalog test run.
+- `code-reviewer`: a UI-touching MR with a catalog present and no story → `REQUEST_CHANGES`.
+
+## Related
+
+- `design-tokens-binding.md` — Figma → repo token binding for the implementation.
+- `mockup-review.md` — the reviewer-side parity gate.

package/presets/claude/next/rules/ui-and-accessibility/design-tokens-binding.md

@@ -29,7 +29,7 @@ The implementation must mirror the Figma mockup token-for-token. Raw design valu
 
 ## Imagery & icons
 
-- **Images:** use the Figma asset source from `get_design_context` / the node’s image fill. Repo: `next/image` (or repo convention) with `src`, `width`, `height` derived from Figma. Do not use a placeholder, do not invent a URL, do not change aspect ratio.
+- **Images:** use the Figma asset source from `get_design_context` / the node’s image fill. Repo: **the project’s image primitive** — check the nearest component in the same layer (often a plain `<img>` or a DS image component; `next/image` only where the config keeps the optimizer enabled). Derive `src`, `width`, `height` from Figma. Do not use a placeholder, do not invent a URL, do not change aspect ratio.
 - **Icons:** use the `@sds/icon` (or project DS) symbol name from the Figma component instance / metadata. Do not invent icon names. The Figma node’s component name (e.g. `Icon / chevron-right`) maps to the DS symbol.
 - `alt` text from the Figma node name when meaningful; otherwise from the design context copy.