@bonesofspring/ai-rules 0.2.31 → 0.2.32

package/presets/cursor/next/ai-local/rules-library/task-levels.md

@@ -0,0 +1,28 @@
+glob: always
+
+## Body
+
+# Task artifact levels (L0–L3)
+
+When sizing a task before starting, acknowledge: `Using .ai.local: task-levels(, …)*`.
+
+Every non-trivial task must live as a file artifact, never only in chat. Pick one level by size and impact; when unsure, pick the higher level.
+
+## Levels
+
+| Level | When | Where | Required files |
+|---|---|---|---|
+| **L0 — note** | 1 file, < 30 min, no plan needed | chat todos + `git diff` | none |
+| **L1 — team task** | 2–10 files, one feature/fix with discrete steps | `.ai.local/team/tasks/<slug>/` | `pipeline.json` + `status.json` + `brief.md` + `decomposition.md` + `.memlog.md` (+ per-agent artifacts) |
+| **L2 — change spec** | architecture / boundary change, compliance boundary touched, > 10 files, or multi-role review | `openspec/changes/<YYYY-MM-DD>-<slug>/` | `proposal.md` + `design.md` + `tasks.md` |
+| **L3 — hybrid** | formal change that also needs an execution pipeline | L2 (contract) + L1 (execution), cross-referenced | all of L2 + L1 |
+
+## Selection order (apply in order)
+
+1. Touches PD / medical data / analytics / third-party scripts / SSR-cookie shape → **L2 minimum** (with a compliance block).
+2. Changes the data flow or a module boundary → **L2**.
+3. > 10 files or > 1 subsystem → **L2**.
+4. Otherwise multi-step (planning + implementation + verification) → **L1**.
+5. Otherwise → **L0**.
+
+Never demote a task to keep the artifact small.

package/presets/cursor/next/ai-local/rules-library/ui-change-review-gate.md

@@ -0,0 +1,14 @@
+globs: app/src/ui/**/*.{ts,tsx}
+
+## Body
+
+# UI change review gate
+
+Before a UI change is considered complete, acknowledge: `Using .ai.local: ui-change-review-gate(, …)*`.
+
+## Required before completion
+
+1. **Mockup review artifact.** If the task scope contains `app/src/ui/**`, a terminal `mockup-review.md` with verdict `PASS`/`PASS_WITH_NOTES` exists — even when no `figma.com` URL was supplied (then review against AC / `ux-design.md`). Missing artifact = incomplete work, not a warning.
+2. **Composed frame.** For a page or block, the review node set includes the **composed page frame**, not only isolated component sets. A node id claimed by another task must be declared in `## Scope`.
+3. **Same-day rewrite.** Do not rewrite a block shipped the same day without a new review artifact and an owner (single-writer rule).
+4. **Storybook tests run.** Targeted storybook tests green without `--update`.

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

@@ -12,7 +12,7 @@
 - **`alwaysApply: true`** (Cursor) / **without `paths:`** (Claude) — base invariants (Cursor/Claude 3–5):
   - Cursor: `next-app-core`, `package-manager`, `code-quality-and-refactoring`, `ai-local-overlay`
   - Claude: `next-app-core`, `package-manager`, `code-quality`
-- **On-demand / requestable** — `post-change-lint` (**required after code edits**, not always-on), `agent-team-intake` (via orchestrator/commands), `agent-team-orchestrator`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `mcp-usage`, `anti-sycophancy-discipline`, `react-next-anti-hallucination`, reference-features, product-specs, product-specs-authoring, next-app-router, `security-next`, react-a11y-coding, `technical-retro`, `mockup-review`, `ux-design`, `design-tokens-binding`
+- **On-demand / requestable** — `post-change-lint` (**required after code edits**, not always-on), `agent-team-intake` (via orchestrator/commands), `agent-team-orchestrator`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `mcp-usage`, `anti-sycophancy-discipline`, `react-next-anti-hallucination`, reference-features, product-specs, product-specs-authoring, next-app-router, next-static-export, `security-next`, react-a11y-coding, component-catalog-gate, forms-validation, `technical-retro`, `mockup-review`, `ux-design`, `design-tokens-binding`
 - **Preset author meta** (globs `packages/ai-rules/presets/**`, never alwaysApply): `preset-layering`, `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`
 - **Skills** — long procedures (`feature-delivery`, `spec-authoring`, `spec-discovery`, `code-review`, …)
 
@@ -55,6 +55,9 @@ When editing `app/src/ui/**/*.tsx`, a **reduced** set loads (not all of `app/src
 | `no-props-spread.mdc` | `app/src/**/*.tsx` | Explicit props |
 | `arrow-functions.mdc` | `app/src/**` | Syntax |
 | `design-tokens-binding.mdc` | `app/src/ui/**/*.{ts,tsx,css}`, `app/src/styles/**` | Figma → repo token binding (typography/color/spacing/imagery); no raw values where a token exists |
+| `component-catalog-gate.mdc` | `app/src/ui/**`, `storybook/**` | Stories ship with the UI; catalog tests green |
+| `forms-validation.mdc` | `app/src/**/*Form*.tsx`, `app/src/**/*Modal*.tsx` | Repo form library + DS fields + shared validators |
+| `next-static-export.mdc` | `app/src/pages/**`, `app/next.config.*` | No server runtime; what to use instead |
 
 **Not loaded on typical UI edit:** `architecture-boundaries` (api/store/types/lib), `layer-barrel-exports` (only `index.ts`), `navigation-router-stack` (only `app/src/app/**`). Colocated styles — in `react-ui.mdc` (deprecated stub `no-cross-component-styles-import` removed).
 

package/presets/cursor/next/rules/agent-team-orchestrator.mdc

@@ -95,7 +95,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/cursor/next/rules/ai-local-overlay.mdc

@@ -13,8 +13,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.
 
@@ -30,6 +31,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/cursor/next/rules/code-review-mr.mdc

@@ -66,3 +66,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/cursor/next/rules/component-catalog-gate.mdc

@@ -0,0 +1,38 @@
+---
+description: Component catalog (Storybook/Ladle) is the required UI dev + visual-review surface — stories ship with the UI change
+globs: app/src/ui/**/*,storybook/**/*,stories/**/*
+alwaysApply: false
+impact: MEDIUM
+---
+
+# 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.mdc` — Figma → repo token binding for the implementation.
+- `mockup-review.mdc` — the reviewer-side parity gate.

package/presets/cursor/next/rules/design-tokens-binding.mdc

@@ -28,7 +28,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.
 

package/presets/cursor/next/rules/feature-delivery-workflow.mdc

@@ -11,6 +11,10 @@ alwaysApply: false
 
 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 (`component-catalog-gate`).
+
+**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**.
@@ -19,7 +23,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 `design-tokens-binding.mdc` 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/cursor/next/rules/forms-validation.mdc

@@ -0,0 +1,33 @@
+---
+description: Forms and validation — use the repo's form library + design-system fields + shared validators, not ad-hoc state
+globs: app/src/**/*Form*.tsx,app/src/**/*Form*.ts,app/src/**/*Modal*.tsx
+alwaysApply: false
+impact: MEDIUM
+---
+
+# Forms and validation
+
+Use the form solution already in the repo (`package.json` + the nearest form component). Do not hand-roll form state with `useState` when a form library is present.
+
+## Rules
+
+- One form-hook instance per form; register design-system fields through the library's controller/wrapper (controlled) — not a raw `<input>` when a DS field exists.
+- Validate with the repo's resolver/schema library and reuse the shared validators under the repo's validation utils — never re-implement email / phone / date / length rules inline.
+- Masked inputs (phone, date, card) go through the repo's mask library, not ad-hoc regex on change.
+- Disable submit while `!isValid` / `isSubmitting`; surface field errors from the form library's error state.
+- Keep side effects out of field components: the form owns `onSubmit`; data flows to store/API through the repo's layers (`architecture-boundaries-ui.mdc`).
+
+## Accessibility
+
+- Every field has a visible label and an associated error message; do not rely on placeholder-only labels.
+- Field errors are announced and tied to the input; keep the DS field's wiring instead of a bespoke error node.
+
+## Stack notes
+
+- Library: `react-hook-form` + `yup` resolver; `mode: 'onTouched'`.
+- DS fields: `app/src/ui/components/_form/**`; shared validators: `app/src/lib/utils/validations/**`; masks: `imask` / `react-imask`.
+
+## Related
+
+- `react-ui.mdc` — component structure and decomposition.
+- `architecture-boundaries-ui.mdc` — no API/DTO in UI.

package/presets/cursor/next/rules/mcp-usage.mdc

@@ -92,6 +92,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/cursor/next/rules/next-app-core.mdc

@@ -13,6 +13,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 (`next-app-router.mdc`, `navigation-router-stack.mdc`).
+- **Deployment model:** read `output` in `next.config.*`. With `output: 'export'` the app is a static SPA — no server runtime, no API routes / middleware / SSR (`next-static-export.mdc`).
+- **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/cursor/next/rules/next-static-export.mdc

@@ -0,0 +1,35 @@
+---
+description: Static-export / SPA Next.js (output 'export') — no server runtime; what is unavailable and what to use instead
+globs: app/next.config.*,app/src/pages/**/*,app/src/pages/_*.tsx
+alwaysApply: false
+impact: HIGH
+---
+
+# 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.mdc`, `api-services.mdc`).
+- 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.mdc` — phantom-import banlist for this deployment model.
+- `navigation-router-stack.mdc` — Pages Router vs App Router.

package/presets/cursor/next/rules/post-change-lint.mdc

@@ -15,6 +15,10 @@ Exceptions: documentation edits outside `app/`, CI configs, `.cursor/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** responsibility. 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 — **`package-manager.mdc`**.

package/presets/cursor/next/rules/product-specs-authoring.mdc

@@ -121,5 +121,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/cursor/next/rules/product-specs.mdc

@@ -65,5 +65,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/cursor/next/rules/react-next-anti-hallucination.mdc

@@ -10,6 +10,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 **`next-app-router.mdc`**. 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 |
@@ -55,6 +62,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-services.mdc`, `http-client.mdc`) |
 | 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 (`next-static-export.mdc`) |
+| 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/cursor/next/rules/react-ui.mdc

@@ -24,6 +24,24 @@ impact: HIGH
 - No nested ternaries in JSX. For not-ready / empty / error, use an early return or a dedicated `EmptyState` / `ErrorState` component.
 - A `variant` / `mode` flag that renders two unrelated layouts is **two** components, not one.
 
+# One component / one styled element — one purpose
+
+- Each component **and** each styled element serves exactly **one** purpose. Do not drive two distinct shapes (different padding, slot set, alignment, visual identity) from a `variant` / `is…` flag or branchy styles.
+- Two call sites that need visibly different markup → two named components (or two named styled exports). Share the base via a small primitive (`BaseCard` styled block + two thin extensions), not a universal branchy `Card`.
+- A flag that flips a single non-layout property (`compact`, `disabled`) is fine; a flag that flips layout, slots, or visual identity is not — split it.
+
+# CSS-in-JS interpolation functions
+
+- Inside `${…}` interpolations of a styled template (`styled.*`), do **not** write an inline arrow (`${({ tone }) => …}` or `${({ gap }) => gap}`). Reference a **module-level function** that takes the styled props: `${getPromoStatusColor}`.
+- Name it `get` + the value (`getColor`, `getGap`, `getPromoStatusColor`); keep the prop type shared between the styled generic and the function parameter.
+- A module-level function is debuggable, type-checkable in isolation, and reusable across sibling styled blocks; an inline arrow compiles to an untestable one-shot.
+
+# Async UI states
+
+- Loading, empty, error, and load-failed are **distinct** states — render each explicitly; do not collapse them into one spinner/blank branch.
+- Prefer a **per-block skeleton** over a page-level spinner, and reuse the repo's existing primitives (`Skeleton`, `EmptyState`, `ErrorState`, load-failed stub, global `ErrorBoundary`) instead of inventing new ones.
+- Error boundaries are usually mounted once at the app root; add a local boundary only when the repo already does so for that region.
+
 ## Incorrect
 
 ```tsx
@@ -97,7 +115,7 @@ For a reusable component:
 - **Forbidden** to import another component's `styles` (`../Other/styles`, `../../styles`). Allowed: `./styles`, shared primitives from `@/ui/components/...` or design-system packages.
 - CSS / `styled` order — Stylelint idiomatic-order: `css-property-order-stylelint.mdc` (loads on `styles.ts` / `.css`).
 - For visuals use **the style stack and tokens already in the project** (variables, theme, shared classes, design package).
-- **Token binding (Figma → repo):** typography, color, spacing, radius, shadow, and imagery must bind to the project token module and the design system (`@sds/tokens-*` / `@sds/brand-colors` / DS components like `Text variant="…"`, `@sds/icon`, `next/image`). Raw `#…` / `rgb(…)` / `px` where a token exists is a finding. The full discipline — including the per-element parity checklist and the developer self-check vs Figma — is in **`design-tokens-binding.mdc`**. When a Figma reference exists, the `mockup-review.md` `## Design contract` section is the binding table; use it.
+- **Token binding (Figma → repo):** typography, color, spacing, radius, shadow, and imagery must bind to the project token module and the design system (`@sds/tokens-*` / `@sds/brand-colors` / DS components like `Text variant="…"`, `@sds/icon`, the project image primitive). Raw `#…` / `rgb(…)` / `px` where a token exists is a finding. The full discipline — including the per-element parity checklist and the developer self-check vs Figma — is in **`design-tokens-binding.mdc`**. When a Figma reference exists, the `mockup-review.md` `## Design contract` section is the binding table; use it.
 - Avoid:
   - inline styles except simple cases;
   - duplicating styling already covered by shared primitives;

package/presets/cursor/next/rules/reference-features.mdc

@@ -30,6 +30,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/cursor/next/rules/security-next.mdc

@@ -14,6 +14,8 @@ impact: CRITICAL
 
 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 +28,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 +54,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/cursor/next/rules/store-rtk.mdc

@@ -50,6 +50,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-services.mdc` and `http-client.mdc`).
 
+# 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/cursor/next/rules/tests-e2e-structure.mdc

@@ -80,6 +80,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/cursor/next/rules/tests-unit.mdc

@@ -90,6 +90,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/cursor/next/team/fixtures/feature-with-ux-no-figma.json

@@ -2,16 +2,15 @@
   "slug": "example-feature-with-ux-no-figma",
   "intent": "feature",
   "profile": "standard",
-  "summary": "Feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; no mockup-reviewer step",
+  "summary": "UI-scope feature with required-signal UX and no Figma URL — task-analyst loads skill ux-design; UI scope forces mockup-reviewer (reviewed against AC / ux-design.md)",
   "steps": [
     { "agent": "task-analyst", "label": "Clarify, UX design, decompose" },
+    { "agent": "mockup-reviewer", "label": "UI review vs AC / ux-design" },
     { "agent": "feature-developer", "label": "Implement" },
     { "agent": "build-verifier", "label": "Validation gate", "model": "cheap" },
     { "agent": "code-reviewer", "label": "Code review", "model": "cheap" }
   ],
   "humanGates": ["after:task-analyst"],
   "autoChain": true,
-  "skipped": [
-    { "agent": "mockup-reviewer", "reason": "No figma.com URL; analyst skill ux-design covers behavioral UX" }
-  ]
+  "skipped": []
 }

package/presets/cursor/nuxt/rules/agent-team-orchestrator.mdc

@@ -96,7 +96,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/cursor/php-hexagonal/rules/agent-team-orchestrator.mdc

@@ -72,7 +72,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/cursor/php-laravel/rules/agent-team-orchestrator.mdc

@@ -72,7 +72,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/cursor/svelte/rules/agent-team-orchestrator.mdc

@@ -96,7 +96,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/mavis/android-kotlin/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "mavis",
   "stack": "android-kotlin",
   "semanticSource": "cursor/android-kotlin",
-  "sourceRevision": "6e09f86a97133b60a3818076d68660709ce3b9119175f1e00ef160b3bc747def",
+  "sourceRevision": "3c548e6420c847099873f9c3bc9570f75c30162dd6b135c436a71e12fe3de8ed",
   "entries": [
     {
       "source": "AGENTS.md",

package/presets/mavis/android-kotlin/rules/agent-team-orchestrator.md

@@ -109,8 +109,7 @@ Each slug has one `artifact-manifest.json` at `.ai.local/team/tasks/<slug>/`. Th
 
 - 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 points to authoritative paths and records producer, status, 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 unrelated 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/mavis/android-kotlin/rules/code-review-mr.md

@@ -48,7 +48,7 @@ On-demand rule for review flows (not always-on).
   - Rely on the local repository: branch, `git diff`, open files.
 
 - **What the agent must check**
-  - **Architecture and layers** (`architecture-boundaries.mdc`, `android-app-core.mdc`):
+  - **Architecture and layers** (`architecture-boundaries.md`, `android-app-core.md`):
     - View does not call APIs and does not know DTOs.
     - ViewModel does not depend on Data implementations directly.
     - Domain does not import Jetpack Compose/Android View system.
@@ -57,21 +57,21 @@ On-demand rule for review flows (not always-on).
     - DI via protocols; composition / holders in `applications/` + feature DI.
     - No deep-import between features.
     - Files in the correct layers (`presentation`, `domain`, `data`, design-system / `api`/`impl`).
-  - **Kotlin and concurrency** (`kotlin-conventions.mdc`):
+  - **Kotlin and concurrency** (`kotlin-conventions.md`):
     - `main-safe / viewModelScope` on UI; no unjustified `!!`s.
     - Typed errors; structured concurrency / cancellation where needed.
-  - **UI** (`compose-ui.mdc`):
+  - **UI** (`compose-ui.md`):
     - Thin Views; Design System tokens; semantics / content descriptions for testable elements.
-  - **Networking and data** (`networking-data.mdc`):
+  - **Networking and data** (`networking-data.md`):
     - DTOs separated from domain; mappers cover edge cases.
   - **Tests**:
-    - Non-trivial logic — unit (`tests-unit.mdc`); user flows — UI (`tests-ui.mdc`).
+    - Non-trivial logic — unit (`tests-unit.md`); user flows — UI (`tests-ui.md`).
     - State which tests to add or update.
 
 - **Depth and format**
   - Focus on the **MR diff**, not the whole project.
   - Overview first (MR goal, risks), then concrete comments with file and a fix suggestion matching repo patterns.
-  - No “big refactors” without a request (`code-quality-and-refactoring.mdc`).
+  - No “big refactors” without a request (`code-quality-and-refactoring.md`).
 
 - **Constraints**
   - Do not invent CI/MR hosting metadata without local data.