@bonesofspring/ai-rules 0.2.26 → 0.2.27

package/presets/mavis/mcp-ts/rules/product-specs.md

@@ -54,3 +54,9 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 - Skill `spec-discovery` — opt-in research-before-spec (author mode only; not default consume).
 - `reference-features` — code structure mirror (how to layout files), not product behavior.
 - Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.
+
+## Stack notes
+
+- `routes`: MCP **tool names**. `ui` / `store`: `[]`. `api`: tools/handlers. `e2e`: contract/unit paths.
+- Prefer `type: feature`. **Forbidden:** requiring `app/src/ui`, Playwright paths, or Next lint recipes.
+- Requestable / `docs/specs/**` globs — not always-on / session-start.

package/presets/mavis/mcp-ts/skills/debug-investigation/SKILL.md

@@ -24,3 +24,18 @@ If **three** fix attempts fail, or the same symptom returns after two supposed f
 - Broad refactor during a bugfix.
 - Fix only where the error surfaces if invalid data originates elsewhere.
 - Claim `fixApplied: true` without re-running the failing check (see `quality/verification-before-completion.md`).
+
+## Stack notes
+
+### Stack process
+
+1. Reproduce with unit/contract fixtures before changing code.
+2. Check schema validation vs handler logic vs registration wiring.
+3. Prefer repository tests over ad-hoc Inspector-only claims.
+4. Load `anti-sycophancy-discipline` — report what was verified.
+
+### MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.

package/presets/mavis/next/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "mavis",
   "stack": "next",
   "semanticSource": "cursor/next",
-  "sourceRevision": "f0cc109df31c45d0fa768868bdc4b85af95b78683d04e78c88da1109b048061f",
+  "sourceRevision": "04c6021a277bc3eaa2feb108188726dbbc733cd875425ce31e8250ac5122b362",
   "entries": [
     {
       "source": "AGENTS.md",

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

@@ -31,12 +31,12 @@ When validating **preset packaging** changes (paths under `packages/ai-rules/pre
 
 ### FAIL (all stacks)
 
-1. **Token budget:** Cursor `alwaysApply: true` count ≤ **4** (4th slot reserved for `ai-local-overlay`); Claude rules without `paths:` === **3** (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be `alwaysApply: true`.
+1. **Token budget:** Cursor `alwaysApply: true` count 3–5 (extra slots reserved for `ai-local-overlay`); Claude rules without `paths:` 3–5 (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be `alwaysApply: true`.
 2. **Leakage (next):** hooks/agents must not require `xcuitest-test-*` handoffs or `xcodebuild` as the default Next post-change gate. See `preset-no-cross-stack-leakage.md`.
 3. **Mapping / README:** `claude/next/rules/README.md` must include a Cursor→Claude mapping table; stack `rules/README.md` should document core→stack mapping when `_shared` consumers exist.
 4. **shared-core consumers:** if `_shared/core/**` changed, every file with matching `<!-- shared-core: … -->` in this PR must be updated (or intentional fork documented in validation-report).
 5. **Twin presence:** Cursor rule change without Claude twin same PR → **FAIL** (next, nuxt, svelte, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel). Domain twin body ≥15 lines; thin aliases (`agent-team-intake`, `technical-retro`) may be shorter.
-6. **Session-start body budget (soft→document, FAIL if grossly over):** sum body lines of the **3** intended always-on / session-start rules ≤ **140** (stretch ≤120); do **not** include `**/README.md`. Record the sum in validation-report.
+6. **Session-start body budget (soft→document, FAIL if grossly over):** sum body lines of the intended always-on / session-start rules ≤ **200** (stretch ≤170); do **not** include `**/README.md`. Record the sum in validation-report.
 7. **Embed drift (hard in `check:preset-structure`):** run `packages/ai-rules/scripts/check-shared-core-drift.sh` with `AI_RULES_DRIFT_FAIL=1` (bundled by the structure orchestrator). Lineage stems are excluded from body equality.
 8. **Dogfood (monorepo soft):** if root `.cursor/` is in the PR, prefer sync via `packages/ai-rules/scripts/sync-dogfood-cursor.sh`; mass deletion of tracked dogfood without migration doc → note as risk / FAIL for maintainers.
 

package/presets/mavis/next/commands/spec-start.md

@@ -4,7 +4,7 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 
 ## What to do
 
-1. Extract description from arguments after the spec-start procedure in `.mavis/commands/spec-start.md` (domain, page/feature ids, sources).
+1. Extract description from arguments after `/spec-start` (domain, page/feature ids, sources).
 2. Generate a **slug** (kebab-case, ≤48 chars), e.g. `spec-<domain>-<id>`.
 3. Ensure `.ai.local/team/tasks/<slug>/` exists (Write artifacts; not Shell mkdir).
 4. Write `.ai.local/team/active-task.json` → `{ "slug": "<slug>" }`.
@@ -16,7 +16,7 @@ Routes intent **`spec-gen`** (or bootstrap) → **task-analyst** in **author mod
 
 - Show created/updated spec paths and INDEX diff.
 - Ask user to approve drafts (`status: draft` → promote) or send edits.
-- Continue: continue `<slug>` using `.mavis/commands/task-continue.md` only after approval when implementation follows; otherwise stop after docs.
+- Continue: `/task-continue <slug>` only after approval when implementation follows; otherwise stop after docs.
 
 ## Notes
 

package/presets/mavis/next/commands/task.md

@@ -1,10 +1,10 @@
 # Task — unified entry point (router + pipeline)
 
-Main command for task intake. Parent agent = orchestrator (`agent-team-orchestrator.md`). Intake for work requests without the task procedure in `.mavis/commands/task.md` — `agent-team-intake.md`.
+Main command for task intake. Parent agent = orchestrator (`agent-team-orchestrator.md`). Intake for work requests without `/task` — `agent-team-intake.md`.
 
 ## Arguments
 
-Everything after the task procedure in `.mavis/commands/task.md` is the task description in natural language.
+Everything after `/task` is the task description in natural language.
 
 Examples:
 
@@ -25,13 +25,13 @@ Examples:
 1. **Slug** — kebab-case from the description (≤48 characters). Create `.ai.local/team/tasks/<slug>/` via **Write** (e.g. placeholder `pipeline.json` or empty marker) — runtime/hook owns `status.json` — **not** via Shell `mkdir` (sandbox → `Operation not permitted`).
 2. **Router** — invoke subagent **task-router** with the task description and slug path.
 3. **Plan** — show the user the table from `pipeline.json`: intent, steps, skipped, humanGates.
-4. **Intent retro** — if `intent === "retro"`, run the technical-retro procedure in `.mavis/commands/technical-retro.md` and **stop**.
+4. **Intent retro** — if `intent === "retro"`, run `/technical-retro` and **stop**.
 5. **Start** — after router:
    - confirm `pipeline.json` and `active-task.json`;
    - **do not** write lifecycle fields in `status.json` / `metrics.json` yourself — orchestration runtime/hook owns them (see **agent-artifact-contracts**). If `status.json` is missing, only minimal bootstrap is allowed (`slug`, `intent`, `pipelineIndex: 0`, `currentAgent: steps[0]`, `state: in_progress`) — **do not** increment `pipelineIndex` manually;
    - invoke subagent for `pipeline.steps[0].agent` (slug, artifact paths, scope).
 6. **After each agent** — wait for hook handoff / reconciliation terminal receipt → `status.state`; do not start the next step until `status.json` reflects handoff (or until there is a `followup_message` from the hook).
-7. **Human gate** — if after the current step there is a gate in `humanGates` (`after:<agent>`), after the agent finishes **stop** and ask for continue `<slug>` using `.mavis/commands/task-continue.md`.
+7. **Human gate** — if after the current step there is a gate in `humanGates` (`after:<agent>`), after the agent finishes **stop** and ask for `/task-continue <slug>`.
 
 ## Do not
 
@@ -41,10 +41,10 @@ Examples:
 
 ## If slug is taken
 
-- `awaitingHumanGate` / `state: awaiting_approval` → offer artifact review or continue `<slug>` using `.mavis/commands/task-continue.md`.
+- `awaitingHumanGate` / `state: awaiting_approval` → offer artifact review or `/task-continue <slug>`.
 - `in_progress` → ask: continue or new slug.
 
 
 ## Metrics
 
-Runtime/hook owns `metrics.json` and `status.json` attempt ledgers. Before the first invocation ensure `task_started` and one `activeAttempts[attemptId]` + `attempt_started` exist (router/runtime bootstrap — parent must not invent parallel indices). On the task-continue procedure in `.mavis/commands/task-continue.md`, run the installed chain hook `end_human_gate` action (or wrapper) so `human_gate_ended` lands before the next attempt. Do not calculate durations in agents.
+Runtime/hook owns `metrics.json` and `status.json` attempt ledgers. Before the first invocation ensure `task_started` and one `activeAttempts[attemptId]` + `attempt_started` exist (router/runtime bootstrap — parent must not invent parallel indices). On `/task-continue`, run the installed chain hook `end_human_gate` action (or wrapper) so `human_gate_ended` lands before the next attempt. Do not calculate durations in agents.

package/presets/mavis/next/hooks/chain-team-phases.sh

@@ -42,7 +42,10 @@ try {
 }
 
 const slug = active.slug;
-if (!slug) {
+// Reject non-kebab / traversal slugs: the runtime writes status.json and
+// metrics.json under tasks/<slug>, so an unchecked slug could escape the tree.
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+if (typeof slug !== 'string' || slug.length > 48 || !SLUG_RE.test(slug)) {
   process.stdout.write('{}');
   process.exit(0);
 }
@@ -69,6 +72,9 @@ function waitForMetricsLock() {
   // and never blocked on the lock file, so two concurrent subagentStop events
   // could both acquire the lock and corrupt metrics.json. Retry EEXIST with a
   // 10 ms sleep up to 200 attempts (2 s ceiling). On any other error, throw.
+  // A lock left behind by a killed process is reclaimed once its mtime is older
+  // than STALE_LOCK_MS, so one crash cannot brick the task forever.
+  const STALE_LOCK_MS = 30000;
   for (let attempt = 0; attempt < 200; attempt += 1) {
     try {
       const fd = fs.openSync(METRICS_LOCK, 'wx');
@@ -76,6 +82,13 @@ function waitForMetricsLock() {
       return;
     } catch (error) {
       if (!error || error.code !== 'EEXIST') throw error;
+      try {
+        const lockStat = fs.statSync(METRICS_LOCK);
+        if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
+          fs.unlinkSync(METRICS_LOCK);
+          continue;
+        }
+      } catch {}
       const until = Date.now() + 10;
       while (Date.now() < until) { /* 10 ms busy-wait */ }
     }
@@ -495,7 +508,10 @@ function legacyFlow() {
 
 
 if (hookInput.action === 'end_human_gate') {
-    status.awaitingHumanGate = false;
+  // Only advance when a gate was actually open. A duplicate or retried
+  // end_human_gate must be a no-op, not a silent pipeline skip.
+  const gateWasOpen = Boolean(status.activeHumanGateEventId) || status.awaitingHumanGate === true;
+  status.awaitingHumanGate = false;
   // A2 (retro §8): pin a single runId per pipeline so subsequent events don't
   // fragment the metrics ledger across multiple runId sequences. Prefer
   // metrics.json.task.runId when metrics already exist, then status.metricsRunId,
@@ -522,7 +538,7 @@ if (hookInput.action === 'end_human_gate') {
     });
     delete status.activeHumanGateEventId;
   }
-  if (hookInput.activateNext && fs.existsSync(pipelinePath)) {
+  if (gateWasOpen && hookInput.activateNext && fs.existsSync(pipelinePath)) {
     let resumePipeline = null;
     try { resumePipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8')); } catch {}
     if (resumePipeline) {
@@ -544,6 +560,19 @@ if (hookInput.action === 'end_human_gate') {
         else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope, resumeNext.step));
         process.exit(0);
       }
+      // Gate on the final step: no executable step remains. Complete the
+      // pipeline instead of leaving it in_progress forever.
+      status.state = 'completed';
+      completeTaskMetrics();
+      writeStatus({
+        pipelineIndex: resumeSteps.length,
+        phase: 'done',
+        state: 'completed',
+        currentAgent: null,
+        awaitingHumanGate: false,
+      });
+      out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
+      process.exit(0);
     }
   }
   // A2 (retro §8): if gate closes the final human gate of the pipeline

package/presets/mavis/next/rules/api-services.md

@@ -14,8 +14,8 @@
 - For each domain area (for example, orders, billing, account settings):
   - a separate directory in `app/src/api/services/<ServiceName or feature>/**` following repository convention.
 - Inside a module:
-  - files with API calls (`index.ts` or `*.service.ts`);
-  - mapper files (`*responseMappers.ts`);
+  - files with API calls — follow the repo's shape: `index.ts` / `*.service.ts`, **or** a per-domain module exporting an object (`XxxApiMethods` in `<Domain>.apiMethods.ts` with `<Domain>.endpoints.ts` and `<Domain>.responseTypes.ts`) as in neighboring services;
+  - mapper files (`*responseMappers.ts`) — pure `format…` / `map…` functions named as in the repo;
   - request/response-specific types (if not moved to `app/src/types/**` with export through the `@/types` barrel).
   - when needed — local `index.ts` / barrel inside the module for structure **within** `app/src/api/**`; **outside** this layer UI, store, and other code import only from the root barrel `app/src/api/index.ts` (`import … from '@/api'`, **`public-imports.md`**).
 
@@ -63,10 +63,12 @@ export const getCard = async (id: string) => {
 
 ```ts
 import type { TCard } from '@/types'
-import { mapCardResponse } from './cardResponseMappers'
+import { formatCardResponse } from './cardResponseMappers'
 
 export const getCard = async (id: string): Promise<TCard> => {
   const { data } = await cardsClient.get(`/cards/${id}`)
-  return mapCardResponse(data)
+  return formatCardResponse(data)
 }
 ```
+
+Mapper function verb (`format…` vs `map…`) follows the repo — match neighboring mappers.

package/presets/mavis/next/rules/code-quality-and-refactoring.md

@@ -14,6 +14,12 @@
 - **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
 - **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
 
+# Over-abstraction guardrails
+
+- **No unnecessary constants:** do not hoist a one-off literal, string, or boolean into a named constant. Inline it, or use an existing token/enum when the value is meaningful and reused. Named constants are for shared, semantic, or repeated values.
+- **No invented utilities:** do not add a `utils`/helper for a single call site or a thin pass-through wrapper. Inline it or extend the existing helper; a new shared utility is justified only after the Rule of Three.
+- **Decompose over conditionals:** a unit (function, component, hook) that accumulates several branches (`if` / ternary / `switch`) should be split into smaller units with one reason to change instead of piling up conditions.
+
 # Refactoring during changes
 
 - Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.
@@ -38,3 +44,10 @@ Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-di
 Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**.
 
 > Stack-specific lint gates, examples, and toolchain — in the preset adapter **Stack notes** section.
+
+## Stack notes
+
+- Before adding a new UI control, check existing UI code and project packages.
+- Public API: index/barrel files and explicitly exported entities (`public-imports.mdc`, `layer-barrel-exports.mdc`).
+- Allowed examples: shared hook/utility; typing `any`/`unknown`; splitting a large component; CSS tokens instead of “magic” values.
+- Lint/stylelint — only **`post-change-lint.mdc`**; ESLint config: `app/eslint.config.mjs`. Disabling a rule (`eslint-disable`) — only **locally** (line/small block) with a short “why” comment. Style prose in domain rules stays thin — prefer ESLint/Stylelint over duplicating formatter recipes.

package/presets/mavis/next/rules/code-review-mr.md

@@ -38,3 +38,16 @@ Procedure details live in skill `code-review`. Required shape:
 - Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
 - Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
 - End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.
+
+## Stack notes
+
+On-demand rule for review flows. **Procedure and output format:** skill `code-review`.
+
+### Checklist references
+
+- Architecture layers: `architecture-boundaries.mdc`, `next-app-core.mdc`; network: `http-client.mdc`
+- Imports: `public-imports.mdc`, `layer-barrel-exports.mdc`
+- UI: `react-ui.mdc`
+- Security: `security-next.mdc`
+- Tests: `tests-unit.mdc`, `playwright-agents.mdc`, `tests-e2e-structure.mdc`
+- Lint gate before final report: `post-change-lint.mdc`

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

@@ -97,3 +97,8 @@ Do not introduce a second stem (`refactoring-smells` / `design-patterns-for-agen
 - 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).
+
+## Stack notes
+
+- Prefer hooks/mappers over HOC or new pattern names when the repo already extracts that way.
+- Suggest Strategy/Adapter only when ports or policy branching already exist in `app/src/**`.

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

@@ -47,3 +47,88 @@ flowchart LR
 ## Zone → rules matrix
 
 Filled in the stack adapter: concrete globs/paths and `.mdc` / topic `.md` names.
+
+## Stack notes
+
+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.
+
+## 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**.
+
+Typical feature with backend data and shared state. Layer details — `architecture-boundaries.mdc`, `next-app-core.mdc`.
+
+## Checklist (work order)
+
+1. **Domain types** — `app/src/types/**`, export via barrel (`public-imports.mdc`, **`layer-barrel-exports.mdc`**); JSDoc — `types-jsdoc.mdc`.
+2. **API contract** — DTOs where the repo uses them; domain types in `@/types`.
+3. **Mappers** — DTO → domain in `*responseMappers.ts` (`api-services.mdc`).
+4. **Services** — clients `app/src/api/clients/**`, barrel `@/api` (`api-services.mdc`, `http-client.mdc`, **`layer-barrel-exports.mdc`**). No `fetch` from UI/store.
+5. **State** — `createSlice` / `createAsyncThunk` (`store-rtk.mdc`); thunk → services from `@/api`.
+6. **UI** — types from `@/types`, no DTOs (`react-ui.mdc`, `architecture-boundaries-ui.mdc`, `no-props-spread.mdc`).
+7. **Mocks** — per repo layout; register in `app/src/mocks/handlers.ts` (see below).
+8. **Tests** — unit for mappers (`tests-unit.mdc`); e2e from `*.cases.md` (`tests-e2e-structure.mdc`, `playwright-agents.mdc`).
+9. **Completion** — **`post-change-lint.mdc`**: `lint:js` + `lint:css` + `type-check`; package manager — `package-manager.mdc`. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated 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
+  subgraph transport [Transport]
+    HttpClient[HttpClient]
+  end
+  DTO[DTO] --> Mappers[Mappers]
+  Mappers --> Domain[Domain types]
+  Domain --> Service[API service]
+  Service --> HttpClient
+  Service --> Thunk[Thunk]
+  Thunk --> Store[Store]
+  Store --> UI[UI]
+```
+
+## Registration by layer
+
+1. **Types** — `app/src/types/**`; domain model is the source of truth for UI and store.
+2. **API** — `app/src/api/services/<ServiceRoot>/<Segment>/`; public exports (incl. **path constants** for mocks) → **`app/src/api/index.ts`**.
+3. **Mocks (MSW)** — `app/src/mocks/data/<feature>/`; handlers in **`app/src/mocks/handlers.ts`**. Paths from `@/api`; do not duplicate URL strings. Check browser worker and Node `setupServer` if both are used.
+4. **Store** — `app/src/store/slices/<FeatureName>/`; reducer in **`app/src/store/reducers.ts`**. Middleware → `app/src/store/middleware/**`, register in **`app/src/store/index.ts`**.
+5. **UI** — `app/src/ui/pages/<FeatureName>Page/**` and/or `components/**`; data via store/hooks.
+6. **Unit** — `*.spec.ts(x)`; mappers and non-trivial logic are required.
+7. **E2E** — `app/__tests__/e2e/<Area>/<plan>.cases.md` + `*.spec.ts`.
+
+## Partial scenarios
+
+| Task | Minimum actions |
+|------|-----------------|
+| API + types only | Types, service, mappers, `@/api` barrel; unit for mapper. |
+| Mocks only | Path in `@/api`; handlers + `mocks/handlers.ts`. |
+| Store only | Thunk via `@/api`; slice + `reducers.ts`. |
+| UI only | Store state; no HTTP/DTO. |
+| E2E only | `*.cases.md` + spec; page object. |
+
+## Anti-patterns
+
+- DTO in UI or untyped store.
+- HTTP client from a component/thunk bypassing the service.
+- Deep-import `@/api/services/**` from UI/store.
+- `{...props}` into components — `no-props-spread.mdc`.
+- **Ubiquitous language:** Domain/type names reflect the feature’s subject domain — do not mix transport/framework terms into the domain without need.
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+- 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`.
+
+## Matrix: zone → rules
+
+| Zone | Rules |
+|------|-------|
+| `app/src/api/clients/**`, `app/src/lib/clients/**` | `http-client.mdc`, `tests-unit.mdc` (behavior) |
+| `app/src/api/services/**` | `api-services.mdc`, `layer-barrel-exports.mdc`, `http-client.mdc` |
+| `app/src/store/**` | `store-rtk.mdc`, `architecture-boundaries.mdc`, `public-imports.mdc` |
+| `app/src/ui/**` | `react-ui.mdc`, `no-props-spread.mdc`, `public-imports.mdc` |
+| `app/src/types/**` | `public-imports.mdc`, `types-jsdoc.mdc`, `layer-barrel-exports.mdc` |
+| `app/__tests__/e2e/**` | `tests-e2e-structure.mdc`, `playwright-agents.mdc` |
+
+When adding or extending a feature, **walk the checklist** and the rules from the table for affected zones.
+
+## Related
+
+- Product behavior discovery: requestable **`product-specs`** (`docs/specs/INDEX.md`) — do not paste the discovery algorithm here.

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

@@ -84,3 +84,12 @@ Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plu
 - 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
+
+## Stack notes
+
+- 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.
+- **Storybook overlay** (not shipped): aliases `storybook`, `user-storybook`, `plugin-storybook`, `storybook-mcp-addon`. Needs Storybook running (often `http://localhost:6006/mcp`). Discover docs/dev/testing toolsets. If down, read story/source files. Block only if the user required Storybook MCP as SoT.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept. User-level MCP is never touched.
+- If a Figma plugin is already connected, do not also require the project `figma` server.

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

@@ -105,3 +105,7 @@ PASS | PASS_WITH_NOTES | FAIL | BLOCKED_MCP
 ## AC coverage
 | Criterion | Status | Notes |
 ```
+
+## Stack notes
+
+Illustrative web buckets (not enforced pixels): ~375 / ~768 / ~1280 mapped to small / medium / large.

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

@@ -5,8 +5,9 @@ Concrete versions come **from `package.json` and configs of the target repositor
 # Project structure
 
 - `app/` — Next.js root; `app/src/**` — code; `app/__tests__/e2e/**` — e2e.
-- `app/tsconfig.json`: `baseUrl: "."`, `paths: { "@/*": ["./src/*"] }`.
+- `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.md`, `navigation-router-stack.md`).
 
 # Architectural layers
 

package/presets/mavis/next/rules/preset-layering.md

@@ -9,7 +9,7 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | Layer | Where | What to put |
 |-------|-------|-------------|
 | **Core** | `presets/_shared/core/**` | Stack-agnostic prose + checklists; no frontmatter; no paths `app/**`, `Features/**`, Playwright, xcodebuild |
-| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on trio, stack examples in **Stack notes** |
+| **Stack** | `presets/{cursor\|claude\|mavis\|opencode}/<stack>/` | Domain/tooling, stack always-on set (3–5), stack examples in **Stack notes** |
 | **Platform** | Cursor `.mdc` / Claude `.md` / Mavis `.md` / OpenCode `.md` | Frontmatter (`alwaysApply`/`globs` vs `paths:` vs OpenCode `mode`/`permission`), platform-only (`BUGBOT.md`, `CLAUDE.md`) |
 
 ## Where to put a new rule

package/presets/mavis/next/rules/preset-pr-checklist.md

@@ -12,7 +12,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **Mavis derive:** mapped `cursor/<stack>/` change → `mavis/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-mavis.mjs --stack <stack>` + `check-mavis-adapter-map.mjs`; see `preset-twin-sync` § Mavis derivation)
 - [ ] **OpenCode derive:** mapped `cursor/<stack>/` change → `opencode/<stack>/` + `adapter-map.json` **same PR** when the stack is in `releasedStacks` (run `generate-opencode.mjs --stack <stack>` + `check-opencode-adapter-map.mjs`; see `preset-twin-sync` § OpenCode derivation)
 - [ ] **Mapping:** `claude/<stack>/rules/README.md` mapping table is current
-- [ ] **Token budget:** Cursor `alwaysApply` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; meta rules not always-on
+- [ ] **Token budget:** Cursor `alwaysApply` and Claude session-start both **3–5** (extra slots reserved for `ai-local-overlay`); body sum ≤200 (stretch ≤170); meta rules not always-on
 - [ ] **Local overlay coverage:** every installable stack ships `ai-local-overlay.mdc` (Cursor) and `ai-local-overlay.md` (Claude) with `MANDATORY` + acknowledgement format + `docs/LOCAL-OVERLAY.md` pointer; Claude twin listed in `claude/<stack>/rules/README.md` mapping table. Run `packages/ai-rules/scripts/check-local-overlay.sh`.
 - [ ] **Leakage:** no foreign stack agent stems / handoff strings (`preset-no-cross-stack-leakage`)
 - [ ] **Hook-only lifecycle:** `status.json` / `metrics.json` writes happen only inside `hooks/`; agents read but never rewrite lifecycle fields. Run `packages/ai-rules/scripts/check-hook-only-lifecycle.sh`.

package/presets/mavis/next/rules/preset-token-budget.md

@@ -8,19 +8,19 @@ Invariants for rule loading in an **installed** preset (consumer app).
 
 | Platform | Always-on | Cap |
 |----------|-----------|-----|
-| Cursor | `alwaysApply: true` | **≤ 4** |
-| Claude | rules **without** `paths:` | **exactly 3** |
-| Mavis | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
-| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+| Cursor | `alwaysApply: true` | **3–5** |
+| Claude | rules **without** `paths:` | **3–5** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
 
-**Cursor 4th slot is reserved for `ai-local-overlay`** (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` and revert to ≤3.
+Caps are **aligned** across platforms: minimum **3** (base invariants), maximum **5**. Slots beyond the base invariants are reserved for `ai-local-overlay` (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` / Claude `paths:`, or a non-root load mode on Mavis / OpenCode.
 
-**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). Body budget sums only the intended session-start rules (≤5).
 
 Session-start body budget:
-- Claude trio: ≤140 lines total (stretch ≤120).
-- Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
-- Mavis / OpenCode: ≤4 root-entry rule files; combined root `AGENTS.md` + platform entry ≤170 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
+- Claude session-start: ≤200 lines total (stretch ≤170).
+- Cursor always-on: ≤200 lines total (stretch ≤170).
+- Mavis / OpenCode: ≤5 root-entry rule files; combined root `AGENTS.md` + platform entry ≤200 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 
@@ -36,4 +36,4 @@ Orchestrator, feature-delivery, code-review, post-change gates, domain globs —
 
 ## Verifier
 
-build-verifier **FAIL** if Cursor `alwaysApply` count exceeds 4, Claude session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.
+build-verifier **FAIL** if Cursor `alwaysApply` count or Claude session-start count is outside **3–5** (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/mavis/next/rules/product-specs-authoring.md

@@ -110,3 +110,9 @@ Block handoff via `open_questions` until fixed:
 - Skill `spec-authoring` — procedural checklist
 - Skill `spec-discovery` — opt-in research-before-spec (not default)
 - Optional consumer script `scripts/check-product-specs.sh` (ships in the npm package; WARN default; `--strict` FAIL). Bash checks INDEX links, required frontmatter keys, and body headings — it does **not** evaluate `frontmatter-v1.schema.json`
+
+## Stack notes
+
+- Author via skill `spec-authoring`; templates from package assets / consumer `docs/specs/_templates/`.
+- Field semantics match discovery stem (`routes` = URL paths; `e2e` = Playwright).
+- Requestable — not always-on / session-start.

package/presets/mavis/next/rules/product-specs.md

@@ -54,3 +54,9 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 - Skill `spec-discovery` — opt-in research-before-spec (author mode only; not default consume).
 - `reference-features` — code structure mirror (how to layout files), not product behavior.
 - Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.
+
+## 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).
+- Dogfood example (emedcard-web AnalysisPage): `docs/specs/domains/analysis/analysis-page.md`.
+- Requestable / `docs/specs/**` globs — not always-on / session-start.

package/presets/mavis/next/rules/react-ui.md

@@ -1,6 +1,7 @@
 # General component rules
 
 - Use **functional components** with hooks, no classes.
+- Export as `export const ComponentName = ({ ... }: IProps) => …` (arrow + props type). No `FC` / `React.FC`.
 - A component should:
   - stay as "thin" as possible on business logic;
   - delegate state to store/hooks when needed in multiple places;
@@ -9,6 +10,41 @@
 - For repeated logic, create `useSomething` hooks nearby or in `src/ui/hooks/**`.
  - When accessing store, API, shared helpers, and utilities, components and hooks must use only their **public API** (for example, `@/store`, `@/store/slices/Foo`, `@/lib/utils`), not internal implementation files of other modules.
 
+# Conditional rendering
+
+- Prefer **decomposition over conditionals**: a component with more than one or two branches (nested ternaries, long `&&` chains, several early returns) should extract each branch into a child under `./components/<Name>/`, keeping the parent a thin switch.
+- Keep the condition in the parent; the child receives resolved props.
+- 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.
+
+## Incorrect
+
+```tsx
+export const OrderPanel = ({ order }: Props) => (
+  <div>
+    {order == null ? (
+      <Spinner />
+    ) : order.items.length === 0 ? (
+      <p>No items</p>
+    ) : order.status === 'paid' ? (
+      <PaidList items={order.items} />
+    ) : (
+      <UnpaidList items={order.items} />
+    )}
+  </div>
+)
+```
+
+## Correct
+
+```tsx
+export const OrderPanel = ({ order }: Props) => {
+  if (order == null) return <Spinner />
+  if (order.items.length === 0) return <EmptyState />
+  return <OrderItems order={order} />
+}
+```
+
 # File structure
 
 For a page/large block:
@@ -63,7 +99,7 @@ For a reusable component:
 # Props and typing
 
 - **Do not pass props via spread** (`<Foo {...x} />`). Only explicit attributes; details and exceptions — `no-props-spread.md` (in `app/src/ui` ESLint catches this too).
-- Describe props with `type Props = { ... }` or `interface Props { ... }`.
+- Describe props with a local `interface` / `type` named as the repo does (`interface IProps` / `type TProps`); match the neighboring component. No `FC` / `React.FC`.
 - Do not use `any`; when needed:
   - generics (`<T>`), `unknown`, type predicates and user-defined type guards.
 - For domain entities use types from `@/types` (and enums from `@/types/enums`), not redefined locally (`public-imports.md`).

package/presets/mavis/next/rules/reference-features.md

@@ -43,3 +43,39 @@ Path pointer and stack tables — in the preset adapter (`.ai.local/conventions.
 - skill `feature-delivery` — end-to-end scenario.
 
 > Concrete path tables, globs, and dogfood checklists live in the stack adapter **Stack notes**.
+
+## Stack notes
+
+Before implementing, find a feature of the same type and **mirror its structure**; do not invent a new file organization.
+
+Taxonomy / shared core: [`presets/_shared/README.md`](../../../_shared/README.md) · [Preset contribution guide](../../../../docs/PRESET-CONTRIBUTION.md).
+
+## Reference table
+
+Replace **TBD** with real paths after team agreement (or on `ai-rules init` in the target repo):
+
+| Layer | Reference | What to copy |
+|-------|-----------|--------------|
+| UI page | **TBD** `app/src/ui/pages/<Example>/` | `components/`, `*.data.ts`, `styles.ts`, barrel |
+| Store slice | **TBD** `app/src/store/slices/<example>/` | slice, thunks, selectors, types |
+| API service | **TBD** `app/src/api/services/<example>/` | service, mappers, barrel |
+| 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/` |
+
+## How to use
+
+1. Identify affected layers from `decomposition.md` or the task.
+2. Open the reference from the table (after paths are filled).
+3. Mirror naming, file order, import patterns, and tests.
+4. If there is no reference — pick the **closest** existing feature of the same layer and record the choice in the handoff.
+
+## Living conventions
+
+Post-init gotchas / patterns / decisions: **`.ai.local/conventions.md`** (shared across tools; `.ai.local/team/**` is pipeline artifacts, not rules). Consumer-owned; not always-on. See root `AGENTS.md` § Living conventions.
+
+## Related rules
+
+- `code-quality-and-refactoring.mdc` — repeat patterns, no deep-import.
+- `feature-delivery-workflow.mdc` — layer order.
+- skill `feature-delivery` — end-to-end scenario.

package/presets/mavis/next/rules/store-rtk.md

@@ -11,13 +11,14 @@
 # Slice structure
 
 - Each domain module — its own slice in `app/src/store/slices/**`.
-- A slice exports:
-  - default `reducer`;
-  - `actions` as named exports;
-  - selectors `selectSomething(state: RootState): Type`.
+- A slice exports — follow the repo's shape:
+  - a named slice (`xxxSlice`) re-exported through a per-slice barrel (`index.ts`), **or** a default `reducer`;
+  - actions as named exports;
+  - selectors named as in the repo (`selectSomething(state: RootState): Type`, or a curried `xxxSelector = (args) => (state) => …`); memoize derived values with `createSelector`.
 - State:
   - explicit state type;
-  - careful `initialState` initialization.
+  - careful `initialState` initialization;
+  - typed root state — use the repo's `RootState` if present, otherwise the local `IRootState` interface neighboring slices use.
 
 # Async and side effects
 

package/presets/mavis/next/rules/tests-e2e-structure.md

@@ -70,3 +70,18 @@ Bad (no capital after period; or wrong locale for configured ESLint):
 ## E2E: keep plans and selectors in sync with UI
 
 - When changing UI: update selectors in page objects and cross-check with the scenario plan. When adding/changing tests: read the matching plan and sync scenario titles first.
+
+## Stack notes
+
+- Runner: Playwright (`@playwright/test`).
+- 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.
+- Tests: `*.spec.ts` files — Playwright scenario implementations.
+- Shared utilities and abstractions: `app/__tests__/e2e/_shared/**` — constants, fluent interfaces, helpers.
+- Root exceptions that do not mirror a single source module: `_shared/`, `smoke.spec.ts`, and `seed.spec.ts`.
+- `data-testid` naming scheme: `{parent}__{element}` — example `history-page__title`, `history-page__recognition-banner__attach-files-button`.
+- `PREFIX-XXX` example: `OrderHistory` → `OH`, `BillingReport` → `BR`; Russian example — `test('OH-001 Отображается список заказов', async ({ page }) => { ... })` <!-- i18n-keep: E5 --> (Order list is displayed).
+- Page object example filename: `OrderHistoryPage.ts` (the seed test pointer lives at `app/__tests__/e2e/seed.spec.ts`).
+- Cross-reference: See also **`playwright-agents.mdc`** for the e2e planner / generator / healer agents.
+- `## 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.