@bonesofspring/ai-rules 0.2.22 → 0.2.24

package/presets/mavis/next/rules/design-guidance.md

@@ -0,0 +1,99 @@
+<!-- shared-core: quality/design-guidance.md -->
+
+# Design guidance (smells & patterns)
+
+Glossary of **code smells** (Fowler) and **design patterns** (GoF) for agents during implement / review / debug.
+
+Apply only within the task or MR scope. Light refactor — yes; a “big” rewrite without an explicit request — no.
+
+Name a pattern **only if** the repository already does it that way or the match is minimal. Otherwise — extract/split/move without a GoF label.
+
+Does not replace always-on Principles in `code-quality-and-refactoring` (KISS, DRY + Rule of Three, YAGNI, SOLID, CUPID, composition, Demeter).
+
+## When to load
+
+- **Feature delivery / implement** — assess module structure, boundaries, and duplication.
+- **Code review** — smells and pattern fit **in the MR diff**, not across the whole repo.
+- **Debug** — root cause looks like wrong abstraction, Feature Envy, Message Chains, Shotgun Surgery.
+- **Light refactor only** — improvements within boy-scout / MR scope; do not expand the task for the catalog.
+
+Agents and skills load this stem via one-liner wiring — do not copy this catalog into the agent prompt.
+
+## How to use (agent rules of thumb)
+
+1. First check against Principles (always-on): is the solution simpler, is there no premature abstraction, is the public API respected.
+2. Then mark smells **in the changed files** of the task/MR; propose a fix only if it fits a light refactor.
+3. A GoF pattern is an optional label after the structure is already clear; do not start design by picking a pattern.
+4. If a smell or pattern conflicts with stack layer boundaries — stack boundaries and existing repo patterns win.
+5. Do not require renaming “for GoF” if behavior is already correct and readable.
+
+## Code smells (Fowler, curated ≤12)
+
+Table: smell → detect hint → fix hint (one line each). No mechanical refactoring menus.
+
+| # | Smell | Detect | Fix hint |
+|---|-------|--------|----------|
+| 1 | Duplicate Code | same logic in ≥2 places | dedupe after Rule of Three |
+| 2 | Long Method / Long Module | unit does too much | extract within scope; no big rewrite |
+| 3 | Feature Envy | method touches foreign data more than its own | move logic toward the data / public API |
+| 4 | Data Clumps | the same argument groups travel together | group into a type / value object |
+| 5 | Primitive Obsession | raw string/int instead of domain concepts | typed ids / value objects when the domain needs them |
+| 6 | Speculative Generality | unused hooks, flags, “for later” abstractions | remove (YAGNI) |
+| 7 | Message Chains | `a.b.c.d` chains | Demeter; facade / module public API |
+| 8 | Middle Man | class almost only forwards calls | remove pass-through **or** keep as a boundary |
+| 9 | Divergent Change | one module changes for different reasons | split by reasons to change |
+| 10 | Shotgun Surgery | one semantic change spreads across many files | consolidate responsibility |
+| 11 | Inappropriate Intimacy | access to foreign internals / private details | public API / ports / facades only |
+| 12 | Refused Bequest / Parallel Inheritance | subtype ignores base; mirrored class hierarchies | composition; do not grow parallel trees |
+
+**Skip Fowler (not in core):** Lazy Class, Incomplete Library Class, Comments-as-smell dogma, full 70+ catalog, step-by-step recipe menus.
+
+Smell conflict priority: Inappropriate Intimacy and Message Chains (module boundaries) > Duplicate Code (after Rule of Three) > Long Method inside an already correct module.
+
+## Design patterns (GoF, curated ≤8)
+
+Suggest only when repo already uses the shape or the match is minimal. Prefer extract-function over naming Strategy for the label alone.
+
+Patterns below are the **allowed minimum** for agents; the rest of GoF is Skip by default.
+
+| Pattern | When to suggest | Anti-trigger |
+|---------|-----------------|--------------|
+| Strategy | interchangeable algorithms already (or clearly soon) chosen by policy | one algorithm with no policy branching |
+| Adapter | wrap external / foreign API under a local port | extra wrapper around your own API |
+| Facade | simplify a multi-step subsystem behind a public API | facade turns into a god-object |
+| Factory Method | polymorphic creation already accepted in repo style | factory for every trivial `new` |
+| Decorator | additive behavior without exploding subclass hierarchies | decorator “for layers” with no real need |
+| Observer | events / subscriptions already exist in the architecture | homemade pub/sub with no repo precedent |
+| Template Method | shared algorithm skeleton + variable hooks | inheritance for a couple of differing lines |
+| Composite | tree of homogeneous nodes (UI/domain), as already in the repo | Composite on a flat list with no hierarchy |
+
+If unsure between two patterns — choose the simpler extract/compose without a name; the label may be added on review if the repo already speaks that way.
+
+## Skip / avoid by default
+
+| Catalog | Skip |
+|---------|------|
+| GoF | Singleton, Abstract Factory, Flyweight, Memento, Interpreter, Visitor, Bridge, Prototype |
+| GoF (conditional) | Command, Chain of Responsibility, State — mention **only if** the repo already uses them |
+| Fowler | everything beyond the 12 smells above |
+| DDD | Aggregates, bounded-context maps, event sourcing, CQRS — **not in core** |
+| DDD (pointer) | ubiquitous language anti-pattern — expand in `feature-delivery-workflow`, not here |
+| GRASP | Larman list as separate rules — skip (covered by SOLID/CUPID) |
+| Clean Code dogma | hard caps on function lines / “exactly one assert” — skip |
+
+Do not introduce a second stem (`refactoring-smells` / `design-patterns-for-agents`) — one catalog: `design-guidance`.
+
+## Out of scope for this stem
+
+- Full GoF (23) and full Fowler catalog.
+- Stack-specific recipes (module paths, lint commands) — only in the adapter **Stack notes**.
+- Security, a11y, perf — separate review rules; here only structural smells/patterns.
+- A fourth always-on rule — forbidden; this stem is requestable / agent-load only.
+
+## Cross-refs
+
+- Always-on Principles: `code-quality-and-refactoring`.
+- DIP / ports vs adapters: stack `architecture-boundaries` (stack details — in adapter Stack notes).
+- Ubiquitous language: `feature-delivery-workflow` (lineage).
+- MR checklist (smells in scope; pattern name only if repo uses it): `code-review-mr`.
+- Token / twin policy for authors: `preset-token-budget`, `preset-twin-sync` (meta, not consumer always-on).

package/presets/mavis/next/rules/feature-delivery-workflow.md

@@ -0,0 +1,49 @@
+<!-- shared-core: architecture/feature-delivery-workflow.md -->
+
+# Feature delivery (end-to-end order)
+
+Typical feature with data and UI. Concrete directories and rule stems — in the adapter **Stack notes**.
+
+## Checklist (abstract order)
+
+1. **Domain / types** — Domain/types-layer entities and contracts; layer public API.
+2. **Transport / DTO** — DTOs and mappers Domain ↔ transport (must not leak into UI).
+3. **Services / Data** — repository / API-service implementations via the stack’s public clients.
+4. **State** — store / ViewModel / use cases; no direct HTTP and no DTOs in UI.
+5. **UI** — thin views/components; data via state; design system. If the prompt or `brief.md` contains a `figma.com` URL, **mockup review must complete** (or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue`) **before UI work**. When required-signal and **no** `figma.com`, **`ux-design.md` must exist** (not `INCOMPLETE`) before UI work — else blocked, hand back to analyst. Non-UI tasks no-op these gates.
+6. **Tests** — unit for mappers / non-trivial logic; e2e/UI per stack convention.
+7. **Completion** — stack post-change gate (lint/build) + package/toolchain rules. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated repo-relative paths) and **Suggested Review Order** (`concern | path:line | ≤15 word note`). Omit both for a single-file or single-layer WP.
+
+## Data flow (orientation)
+
+```mermaid
+flowchart LR
+  DTO[DTO] --> Mappers[Mappers]
+  Mappers --> Domain[Domain]
+  Domain --> Service[Service / Repo]
+  Service --> State[Store / VM]
+  State --> UI[UI]
+```
+
+## Partial scenarios
+
+| Task | Minimum |
+|------|---------|
+| API / model only | Domain + DTO + mapper + service/repo; unit for mapper |
+| State only | Protocols/services; no HTTP in UI |
+| UI only | Existing state; no DTOs |
+| Tests only | Specs per convention; do not change production without need |
+
+## Anti-patterns (shared)
+
+- DTO / transport types in UI or presentation state.
+- Low-level HTTP / concrete client from UI bypassing the service.
+- Deep-import of another module/feature’s internal files.
+- Breaking layer boundaries for brevity.
+- **Ubiquitous language:** Domain/type names and boundaries reflect the feature’s subject domain — do not mix transport/framework terms into the domain without need; presentation must not dictate the model vocabulary.
+- When assessing structure, smells, or pattern choice — load requestable **`design-guidance`** (not always-on); do not copy the catalog into the feature checklist.
+- Do not mutate pipeline `status.json` / `metrics.json`; the orchestration hook is the single writer. Skills upsert the owned terminal receipt in `artifact-manifest.json`.
+
+## Zone → rules matrix
+
+Filled in the stack adapter: concrete globs/paths and `.mdc` / topic `.md` names.

package/presets/mavis/next/rules/http-client.md

@@ -0,0 +1,55 @@
+# HTTP transport
+
+**Names** of factories, error classes, response types, and config — **as in the current repo code** and in the barrel `app/src/types/index.ts`. Below are **architectural rules**, not a rename specification.
+
+## Layer role
+
+- Ordinary REST calls to the backend go through **one implementation** in `app/src/lib/clients/**` (shared client module) and **preconfigured instances** in `app/src/api/clients/**`, following the pattern already adopted in the project.
+- Where transport sits in the overall **ports and adapters** picture — see `architecture-boundaries.md` (section **“Ports and adapters”**).
+- **Do not** call `fetch` directly from `app/src/api/services/**`, store, or UI (see `architecture-boundaries.md`, `api-services.md`); from store/UI — only calls through services from `@/api` (`public-imports.md`).
+- **Exceptions** (narrow protocols, separate transport) — only where the repo already has an example; repeat it, do not invent arbitrary bypasses of the shared client.
+
+## Types
+
+- Everything related to the **request/response/error contract** of the app and re-exported for the HTTP layer must be imported **only** from the `@/types` barrel, without deep imports from internal `app/src/types/**` files (see `public-imports.md`).
+- Do not introduce **types or dependencies on an external HTTP client** the project has moved away from; use **`package.json`** and existing calls as the guide.
+
+## Error contract
+
+- Network and HTTP errors must arrive in the **single shape** defined by the shared client (usually a class/wrapper with a field like `response` for body and status).
+- In **`catch`**, align with the **actual error shape** in this repo (as in neighboring slices/services): access body, status, diagnostic code — **via fields of the current implementation**, without inventing a second format.
+
+## Behavior that stays in the client
+
+- Common headers, `credentials`, file uploads (**FormData** / stripping extra headers), binary responses (**blob** and equivalents), uniform parsing of JSON and other bodies.
+- Intercepting **401 / refresh**, handling **404**, etc. — **centrally**, if the client already does so; do not duplicate the same logic in every service.
+
+## Store relationship
+
+- A thunk may return the **successful response wrapper type** if the service is structured that way; in **state**, prefer **domain** types after mapping. See `store-rtk.md`.
+
+## Agent requirement
+
+- When changing the shared client implementation — **update or add behavior tests** under the mirrored `app/__tests__/unit/lib/clients/**` path (`tests-unit.md`).
+- Do not introduce a **second full HTTP stack** without an explicit task and alignment with repo architecture.
+
+## Incorrect
+
+```ts
+// Inside api/services — ad-hoc fetch bypasses shared client
+export const getSettings = async () => {
+  const res = await fetch('/api/settings')
+  return res.json()
+}
+```
+
+## Correct
+
+```ts
+import { appHttpClient } from '@/api/clients/appHttpClient'
+
+export const getSettings = async () => {
+  const { data } = await appHttpClient.get('/settings')
+  return mapSettingsResponse(data)
+}
+```

package/presets/mavis/next/rules/layer-barrel-exports.md

@@ -0,0 +1,68 @@
+# Layer barrel exports with public API
+
+## When to apply
+
+For **any layer** (directory, package, bounded context) that has:
+
+- a **root barrel** — single import entry for external consumers;
+- deep imports inside the layer **forbidden** from outside (ESLint `no-restricted-imports`, `public-imports.md` rules).
+
+Example alias/entry points in different projects: `@/api`, `@/types`, `@/core`, `@/store`, `packages/foo`.
+
+## Two barrel levels
+
+1. **Local** — module/feature `index.ts` inside the layer.
+2. **Root public API** — layer barrel (e.g. `src/<layer>/index.ts`).
+
+**Inside** the layer — relative imports and paths between submodules. **Outside** — only the root barrel and **explicitly allowed** secondary entry points (if fixed in project rules, e.g. `@/types/enums`).
+
+## What to re-export externally
+
+Only symbols that **must be available** to layer consumers: public functions/services/facades, contract types, constants and helpers needed by other layers or tests.
+
+**Do not re-export:** internal adapters, mappers, transport details, intermediate objects used to assemble a facade inside the layer.
+
+Grouping in the root barrel — **per repo convention** (guide — neighboring modules in the same layer).
+
+## Agent checklist (must)
+
+When adding or substantially extending a **module inside a regulated layer**:
+
+1. Identify the layer, its **root barrel**, and additional entry points (`public-imports.md`).
+2. Create/update **local** `index.ts` — public symbols only.
+3. If the layer has a **facade/aggregator** (`*ApiService.ts`, `rootReducer`, …) — wire the module there.
+4. Add **re-export** of new public symbols in the layer **root barrel**.
+5. **Check:** grep for the symbol name or path `./<Module>` in the root barrel; no deep imports from outside the layer.
+
+The module is **not done** until the checklist passes.
+
+## How to find regulated layers in the repo
+
+1. `public-imports.md` rules in `.mavis/rules/`.
+2. ESLint `no-restricted-imports` — patterns `@/<layer>/*` with barrel exception.
+3. `architecture-boundaries.md`, project README.
+
+## In this repo
+
+| Layer | Root barrel | Import rule |
+|------|-------------------|------------------|
+| API | `app/src/api/index.ts` | `public-imports.md` |
+| Types | `app/src/types/index.ts` | `public-imports.md` (+ `@/types/enums`) |
+| Core | `app/src/core/index.ts` | ESLint: `@/core/index` |
+
+Two-level illustration (API): local `services/.../<Feature>/index.ts` → facade `*ApiService.ts` → `app/src/api/index.ts`.
+
+## Incorrect
+
+```ts
+// app/src/api/index.ts — leaking internals
+export { mapCardResponse } from './services/CardsApi/cardResponseMappers'
+export { rawCardsClient } from './clients/rawCardsClient'
+```
+
+## Correct
+
+```ts
+// app/src/api/index.ts — public facade only
+export { cardsApi } from './services/CardsApi'
+```

package/presets/mavis/next/rules/mcp-usage.md

@@ -0,0 +1,86 @@
+<!-- shared-core: quality/mcp-usage.md -->
+
+# MCP usage
+
+Requestable protocol for **shipped** and **local-overlay** MCP servers. Agents load this stem via one-liner wiring — do not copy tool schemas into prompts; discover them at runtime.
+
+Does not replace Figma mockup-review (that checklist stays on `mockup-review`). Does not add pipeline agents or required handoff stems.
+
+## Presence (runtime catalog is SoT)
+
+1. Inspect the **session MCP catalog** (server names + `serverStatus`). Project `mcp.json` / `.mcp.json` is a hint, not proof the server is up (user-level and plugin servers never appear there).
+2. Treat `error`, `needsAuth`, and `loading` as **unavailable**. Authenticate only when this task needs that server.
+3. **Discover tool schemas before calling.** Never invent tool names or arguments from memory.
+4. Match overlay servers by **documented aliases** or exact catalog ids. Prefer a ready `plugin-*` id over an unknown similarly named server; if several match, ask rather than guessing.
+5. If two servers expose the same product (plugin + project entry), use the **ready** one; do not call both.
+
+## Classes
+
+| Class | Who adds it | Policy |
+|-------|-------------|--------|
+| **Shipped** | Preset `mcp.json` | Assume it should be there; call when the task fits; degrade if down (do not block unless noted below) |
+| **Local overlay** | Consumer project or user MCP | Use only when present **and** the task fits. Never a required pipeline step |
+
+Shipped in every preset: **Context7** (library docs). Other shipped servers are stack-specific — see adapter **Stack notes**.
+
+## Context7 (shipped)
+
+**When to call** (after lockfile / manifest + sibling files still do not confirm the symbol):
+
+- Third-party API that would otherwise get `// VERIFY: lib.symbol @ version`
+- Version-sensitive framework or SDK APIs
+- Migrations / major upgrades
+- Library is in the lockfile but the signature is unclear
+
+**When not to call:** repo public API; a sibling file already imports the symbol; a trivial call already in this module.
+
+**Flow:**
+
+1. Discover server `context7`.
+2. Resolve a library id, then query docs (read the live schema; typical names `resolve-library-id` then `query-docs`).
+3. Put the **installed major** from the project manifest into the query.
+4. Cap: **≤3 doc queries per question**.
+5. Source priority: lockfile / sibling code **>** Context7 **>** training data. If docs disagree with the installed major, keep the installed API.
+6. If Context7 is down: `// VERIFY` (or stack equivalent) and say MCP was unavailable. **Do not block** the task.
+
+## Local overlay protocol
+
+If a matching server is ready and a **task signal** fires → discover and use. Otherwise continue from files / native tools (`gh`, repo docs, source).
+
+Absence of an overlay is **not** `BLOCKED` unless the user required that MCP as source of truth.
+
+### Observability (Sentry, Datadog, similar)
+
+**Signal:** production error, event/trace id, APM / latency, pasted dashboard or issue URL.
+
+Use the **first ready** observability MCP. Do not invent metrics or stack traces. Do not require two observability servers.
+
+### Tickets (Linear, Jira, Notion, similar)
+
+**Signal:** ticket/page URL in the prompt or brief, or an explicit “pull from \<tracker\>”.
+
+Read-only by default. Task-folder artifacts (`brief.md`, `decomposition.md`) remain SoT — do not replace them with a tracker page. Write back to the tracker **only** if the user asked.
+
+### Component-library overlay
+
+**Signal:** UI component public API, stories, controls, or explicit component-docs MCP.
+
+If such a server is ready, use it for documented props/variants instead of inventing them. If it is down, read story/source files. **Block** only when the user required that MCP as SoT.
+
+Usual aliases and runtime needs live in frontend **Stack notes**. Do not ship this server in preset `mcp.json`.
+
+### GitHub MCP
+
+Native `gh` / git remain SoT for PRs and checks. A GitHub MCP may be used when present; do not require it.
+
+## Figma
+
+Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plugin** and a project `figma` server are both present, use the ready one and do not duplicate calls.
+
+## Forbidden
+
+- Secrets in `mcp.json` / `.mcp.json`
+- New pipeline agents or required handoffs for overlay MCP
+- Treating overlay absence as blocked (except user-required SoT)
+- Tracker/admin write tools without an explicit ask
+- Calling overlay MCP “just in case” on unrelated tasks

package/presets/mavis/next/rules/mockup-review.md

@@ -0,0 +1,107 @@
+<!-- shared-core: review/mockup-review.md -->
+
+# Mockup review checklist
+
+On-demand reviewer checklist for Figma mockups. **Procedure:** skill `mockup-review`. **Agent:** `mockup-reviewer`. Do not inline this checklist into the agent prompt.
+
+Stack-agnostic: no app-source globs, Playwright, or `xcodebuild`. Breakpoint **examples** live in adapter **Stack notes** only — do not FAIL on exact pixels.
+
+## When to load
+
+- Pipeline step `mockup-reviewer` (standalone intent `mockup-review` or embedded after analyst)
+- Prompt or `brief.md` contains a `figma.com` URL on a UI-capable stack
+- User asks to review a mockup / Figma file (not a code MR)
+
+## Inputs
+
+1. Task `artifact-manifest.json`, then prompt Figma URL(s); `brief.md` / `decomposition.md` when present
+2. Skill `mockup-review` + this rule
+3. If plugin skills `figma-use` / `figma-design-to-code` are installed: **reference** them for URL parse and MCP invocation only — do not copy their bodies; do not run design-to-code
+
+## MCP-first
+
+Required when MCP is up: `get_metadata`, `get_design_context`, `search_design_system`, `get_variable_defs`, `get_screenshot`. Optional: `get_libraries`, `get_code_connect_map`.
+
+**Forbidden:** `use_figma`, `create_new_file`, `generate_*`, `weave_*`, `upload_assets`, `send_code_connect_mappings`. FigJam URL → `BLOCKED_MCP` / out of scope (do not call `get_figjam` unless the URL is a FigJam board — then still `BLOCKED_MCP`).
+
+Cite `fileKey` + node IDs. Screenshots are supporting evidence, not a second reviewer. No screenshot-only path.
+
+**Node caps:** ≤12 screen-level frames; `get_metadata` depth ≤3 named-frame levels; ≤3 screenshots (prefer one per small/medium/large). `search_design_system` once; `get_variable_defs` once per file. No node-id on URL: pick top-level frames matching the feature name; if still unbounded → `BLOCKED_MCP` (or `PASS_WITH_NOTES` only if MCP returned a tiny file) — do not dump the whole file.
+
+**Degradation:** MCP unavailable or OAuth fail → verdict `BLOCKED_MCP`. Do **not** invent DS compliance claims.
+
+## Review dimensions
+
+### DS components (AC-4)
+
+When an attached library is detectable (`search_design_system` / `get_metadata`): list **library component instances vs custom frames** with file/node references. Flag substitutions where a DS equivalent exists.
+
+- Critical DS reimplementation (custom frame where an attached-library component exists) → **FAIL**
+- One-off frame, no DS equivalent; mixed/unpublished library → WARN or notes (`PASS_WITH_NOTES`)
+- No attached library detectable → notes only; do not invent DS claims (`PASS_WITH_NOTES`)
+
+Confidence: `high` (MCP library match) / `low` (unpublished or mixed) — prefer `PASS_WITH_NOTES` over FAIL when confidence is low.
+
+### Tokens (AC-5)
+
+When variables/styles are available (`get_variable_defs`, style metadata): flag fills, strokes, spacing, or typography that use raw values instead of bound variables/styles.
+
+- Isolated unbound values → **WARN** (`PASS_WITH_NOTES`)
+- Wholesale token ignore on a library-attached file (systemic; treat as critical DS with AC-4) → **FAIL**
+
+### Quality (AC-6)
+
+Cover at minimum, each item PASS / WARN / FAIL eligible:
+
+- Layer/frame naming hygiene
+- Auto-layout vs absolute positioning for responsive regions
+- Text style usage
+- Component variant/property correctness
+- Detached or orphaned component instances
+
+Naming hygiene, minor detached instances, text-style drift → **WARN**. Detached **core** DS component that is a substitution → **FAIL** (same as AC-4 critical). Absolute layout on a region that is the only «responsive» evidence → WARN unless it also fails viewports.
+
+### Feature coverage (AC-7)
+
+Map **flows → screens/frames**, **actions → interactive elements**, and **states** (empty, loading, error, success, disabled/validation). List explicit **missing** items. Label scope **`inferred`** when only a URL is provided (no brief AC).
+
+- Missing **core** flow or primary action from brief AC (or labeled `inferred` primary flow from the URL) → **FAIL**
+- Missing empty/loading/error/success on a form/list called out in AC → **FAIL**
+- Missing secondary states (disabled/validation) not in AC → **WARN**
+
+### Viewports (AC-8)
+
+Verify **≥3 viewport representations** (small / medium / large) via dedicated frames, Figma viewport presets, or responsive component variants.
+
+- Fewer than 3 → **FAIL**
+- 3 exist but sizes ≠ stack example buckets → **WARN** only (no exact pixel enforcement in core)
+
+## Severity (v1)
+
+Isolated **WARN** never blocks. Overall verdict = worst FAIL > BLOCKED_MCP > PASS_WITH_NOTES > PASS. Multiple WARNs without FAIL → `PASS_WITH_NOTES`, not FAIL.
+
+## Report headings
+
+Write `mockup-review.md` with these headings (must match the agent template):
+
+```markdown
+# Mockup review: <slug>
+
+## Verdict
+PASS | PASS_WITH_NOTES | FAIL | BLOCKED_MCP
+
+## Scope
+- Figma fileKey / node IDs
+- MCP: available | unavailable (reason)
+- Feature scope source: brief AC | prompt | inferred
+
+## Critical (must fix)
+## Warnings (should fix)
+## Suggestions
+## DS compliance (AC-4, AC-5)
+## Quality (AC-6)
+## Feature coverage (AC-7)
+## Viewport matrix (AC-8)
+## AC coverage
+| Criterion | Status | Notes |
+```

package/presets/mavis/next/rules/navigation-router-stack.md

@@ -0,0 +1,56 @@
+# Navigation and routing: project stack first
+
+**For any task involving navigation, page transitions, URLs, redirects, breadcrumbs, protected routes, or programmatic route changes** — before proposing code or imports you **must not** default to “typical React”. **Explicitly verify the target repo stack** and use **one** mechanism consistent with the project.
+
+## Dependencies: what to check first
+
+1. **`package.json`** at the app root (e.g. `app/package.json` in a monorepo — the package that is actually built and deployed). Check **`dependencies`** and if needed **`peerDependencies`**:
+   - **`next`** — Next.js; version matters for API nuances (cross-check docs for that major).
+   - **`react-router-dom`**, **`@remix-run/*`**, **`@tanstack/react-router`**, etc. — separate routing; do not substitute their API with Next calls without verifying that stack is actually used.
+   - **`next`** and **`react-router-dom`** together — possible legacy or hybrid; **do not** pick API by default — see “Implementation in code” below.
+
+2. **Monorepo / workspaces** — routing may live outside the root `package.json`. Open the **`package.json` of the workspace** where pages and `next.config.*` / SPA entry live.
+
+3. **Actual installation** — when in doubt, check the lockfile (`bun.lock`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) or `node_modules` for the relevant package: confirm the declared package is installed, not only documented.
+
+## Routing implementation in the project (code and structure)
+
+Before proposing a navigation pattern **align with how the repo already does it**:
+
+1. **Route tree**
+   - Next **App Router**: **`app/`** (or `src/app/`) with `layout.tsx`, `page.tsx`, segments `[id]`, etc.
+   - Next **Pages Router**: **`pages/`** with `_app`, dynamic `[slug].tsx`.
+   - Both **`app/`** and **`pages/`** present — clarify via `next.config` and project docs which layer is primary.
+
+2. **Entry points and wrappers**
+   - Code search for imports: **`from 'next/navigation'`**, **`from 'next/router'`**, **`from 'next/link'`**, **`from 'react-router-dom'`**, **`createBrowserRouter`**, **`RouterProvider`**, **`BrowserRouter`**.
+   - Where routes are declared (Next file structure vs SPA route config / `routes.tsx`).
+
+3. **Project abstractions**
+   - Link wrappers (`@/ui/...`, design-system `Link`), path helpers, route constants — **use them**, do not duplicate raw router.
+
+4. **Neighboring feature files**
+   - New navigation code — same style as pages/hooks in that area (`next/navigation` vs `react-router-dom` as in neighboring imports).
+
+## How to decide what to use (summary)
+
+1. **Dependencies** — see above; they define the allowed package set.
+2. **Structure** — App Router vs Pages vs SPA by directories and config.
+3. **Actual code** — which imports and wrappers dominate in the app.
+
+## What to use (quick matrix)
+
+| Stack | Programmatic navigation / path read | Links |
+|------|-------------------------------------|--------|
+| **Next.js App Router** | `next/navigation` (`useRouter`, `usePathname`, `useSearchParams`, `redirect`, etc. per Next docs for your version) | `next/link` |
+| **Next.js Pages Router** | `next/router` | `next/link` |
+| **SPA + React Router** | `react-router-dom` (`useNavigate`, `useParams`, `useLocation`, …) | `<Link>` from `react-router-dom` |
+
+**Do not:** add `react-router-dom` to a Next.js project “by habit”; import hooks from `next/router` in App Router components without checking; mix two routers in one app without an explicit architectural reason in the codebase.
+
+## Agent requirement
+
+- Before generating or reviewing navigation code **briefly record the conclusion** (e.g. “dependencies: `next` without `react-router-dom`; code uses `next/navigation` everywhere → use the same”) and follow it.
+- **Mandatory check:** current **`dependencies`** in the relevant workspace `package.json` + **how routes and imports are already implemented** (repo search, neighboring files). Do not rely on a single signal alone (e.g. only the presence of an `app/` folder).
+- If the stack is unclear (two routers in dependencies, hybrid) — **cross-check lockfile / installed packages** and **dominant imports** in `src`/`app`, then choose the API.
+- For **this** repo the baseline guide is **`next-app-core.md`**: Next.js; prefer **`next/navigation`** and **`next/link`** where App Router is used.

package/presets/mavis/next/rules/navigation-router-ui.md

@@ -0,0 +1,10 @@
+# Navigation in UI components
+
+Before links, programmatic navigation, or URL work in UI:
+
+1. **`package.json`** of the app workspace — `next` vs `react-router-dom`.
+2. **Neighboring imports** in the same feature (`next/navigation`, `next/link` vs `react-router-dom`).
+3. **Project wrappers** (`@/ui/...` Link) — preferred over raw router API.
+4. **Default (preset):** Next.js App Router → `next/navigation` + `next/link` (`next-app-core.md`, `next-app-router.md`).
+
+Full audit (route tree, hybrids, lockfile): **`navigation-router-stack.md`** — when editing `app/src/app/**`.

package/presets/mavis/next/rules/next-app-core.md

@@ -0,0 +1,29 @@
+# Stack and environment
+
+Concrete versions come **from `package.json` and configs of the target repository**. Preset frame: Next.js, React, TypeScript; runner/e2e/mocks/UI/APM — as established in the repo.
+
+# Project structure
+
+- `app/` — Next.js root; `app/src/**` — code; `app/__tests__/e2e/**` — e2e.
+- `app/tsconfig.json`: `baseUrl: "."`, `paths: { "@/*": ["./src/*"] }`.
+- **Requirement:** `@/*` instead of relative imports that climb the tree.
+
+# Architectural layers
+
+| Layer | Directory | Details |
+|-------|-----------|---------|
+| UI | `app/src/ui/**` (pages, components) | `react-ui.md`, `architecture-boundaries-ui.md` |
+| Store | `app/src/store/**` (slices, middleware) | `store-rtk.md` |
+| API | `app/src/api/**` (services, clients, barrel) | `api-services.md`, `http-client.md` |
+| HTTP | `app/src/lib/clients/**`, `app/src/api/clients/**` | `http-client.md` |
+| Types | `app/src/types/**` | `public-imports.md`, `types-jsdoc.md` |
+| Mocks | `app/src/mocks/**` | per repository layout |
+
+Layer boundaries, ports/adapters, UI→API — **`architecture-boundaries.md`**. Imports of `@/types`, `@/api` — **`public-imports.md`**.
+
+# Agent work
+
+- Architecture and imports: `architecture-boundaries.md`, `public-imports.md`
+- Features: `feature-delivery-workflow.md` + skill `feature-delivery`
+- After edits: **invoke** `post-change-lint.md` (requestable, required after code edits); package manager: `package-manager.md`
+- Copy patterns from neighboring files in the target layer; do not use `any` (prefer `unknown` + narrowing)

package/presets/mavis/next/rules/next-app-router.md

@@ -0,0 +1,44 @@
+# Next.js App Router
+
+Apply when working with `app/src/app/**` or App Router routes in the target repo.
+
+## Server vs Client
+
+- **Server Components by default** — no `'use client'` unless hooks, browser APIs, or event handlers are required.
+- **`'use client'`** — only for interactivity, `useState`/`useEffect`, and browser-only APIs.
+- Do not pull store/RTK and heavy client state into Server Components without need.
+
+## Data fetching
+
+- Prefer fetch/data-loader on the **server** (RSC, route handlers, server actions — per the repo’s established pattern).
+- **Do not duplicate** the same request in RSC and client without reason.
+- Cache and revalidate — match existing pages in the repo (`fetch` options, `revalidate`, tags).
+
+## Routes and UX
+
+- For async data routes, sibling **`loading.tsx`** and **`error.tsx`** are **required** (and `not-found.tsx` where appropriate) — follow neighboring routes.
+- **Suspense** — for slow client/server sections; fallback aligned with the design system.
+- Navigation — `navigation-router-stack.md` + project router/link patterns.
+
+## Layer boundaries
+
+- RSC/route handlers **must not import UI components with client-only dependencies** directly into the server tree without a `'use client'` boundary.
+- Domain types — `@/types`; backend calls — via `@/api` / services, not raw `fetch` from `page.tsx` without an API layer.
+
+## Anti-hallucination (App Router)
+
+Less guessed code is better than more. Cross-check APIs against the Next version in `package.json` and neighboring routes.
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Sync `params` / `searchParams` / `cookies()` / `headers()` when the installed Next treats them as async | `await params` / `await cookies()` / patterns from existing pages |
+| Invented `getSession()`-only server auth without project verify | Server session verify used by the repo (`security-next.md`) |
+| Auth enforcement only in Edge middleware | Layout/page/Server Action checks + middleware refresh if present |
+| New App Router APIs not in the installed Next major | Copy from a sibling route; mark `VERIFY` if unsure |
+| Client `fetch` in `page.tsx` bypassing `@/api` | Services via `@/api` / established data loaders |
+
+See also: **`react-next-anti-hallucination`** — broader React / RTK / Next phantom-import banlist (requestable).
+
+## Reference
+
+Look at an existing route of similar complexity in `app/src/app/**` and repeat its structure (`reference-features.md`).