@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/mavis/mcp-ts/rules/mcp-contract-testing.md

@@ -0,0 +1,32 @@
+# MCP contract testing
+
+Protect tool/resource/prompt **schemas and protocol behavior** — not browser E2E and not Go/Java adapter integration suites.
+
+## What to cover
+
+1. **Schema snapshots / fixtures** — registered input/output JSON Schema (or SDK registration result) matches the intended contract.
+2. **Handler unit tests** — validated inputs → expected results/errors (table-driven).
+3. **Compatibility** — additive changes OK; breaking field renames/removals need versioning or new tool names.
+4. **Inspector smoke (optional)** — MCP Inspector CLI may be used as evidence; it is **not** a required Phase 1 gate.
+
+## Workflow (Phase 1)
+
+- `feature-developer` owns contract verification inline (no `contract-test-*` agents yet).
+- Prefer repository test runner discovered via `mcp-ts-tooling`.
+- Store fixtures next to tools/tests (`*.fixture.json`, schema snapshots) per repo convention.
+
+## Security negatives (when capability touches FS / net / auth)
+
+Require at least one deny fixture per exposed capability:
+
+- FS: path traversal / outside-root rejected; secret paths not readable without AC.
+- Net: blocked host / metadata IP rejected; allowlisted host OK.
+- Auth: expired / wrong-audience / insufficient-scope rejected before handler; results must not echo tokens (`mcp-auth-secrets`).
+
+Align shapes with `tests-unit` and `security-mcp`.
+
+## Anti-patterns
+
+- Claiming "works in Inspector" without schema/unit coverage for the change.
+- Testing only TypeScript types without runtime validation of invalid inputs.
+- Requiring Playwright, XCUITest, or Next e2e paths.

package/presets/mavis/mcp-ts/rules/mcp-server-boundaries.md

@@ -0,0 +1,24 @@
+# MCP server boundaries
+
+Dependency direction:
+
+```text
+MCP client → transport/entry → registration → schema + handler → scoped capability
+```
+
+- **Registration** (`src/tools|resources|prompts`): owns protocol names, descriptions, schemas, result mapping. No unrelated side effects; no hidden validation skips.
+- **Handlers**: receive **validated** inputs; depend on **narrow** capability adapters (FS paths, APIs). No process-wide secrets, arbitrary filesystem, or ambient client state.
+- **Contracts**: tool/resource/prompt schemas are **versioned public interfaces**. Do not prescribe UI, DB controllers, or Go-style `domain/application/adapters` layouts.
+- **Startup / transport** (`src/index.ts`): owns transport selection, lifecycle, fail-closed config. Do not duplicate startup inside tools.
+
+# Edit bundles (load on matching paths)
+
+- `src/tools|resources|prompts/**` → `mcp-tool-design` (+ `mcp-contract-testing` when changing schemas)
+- `src/index.ts`, package/`bin` → `mcp-transport-packaging`
+- auth/config/env → `mcp-auth-secrets` + `security-mcp`
+- After `*.ts` edits → `post-change-test` (+ `mcp-ts-tooling`)
+
+# Agent requirement
+
+- Keep registration, validation, and handlers separable — avoid a monolithic `index.ts`.
+- Prefer least privilege for every tool capability.

package/presets/mavis/mcp-ts/rules/mcp-tool-design.md

@@ -0,0 +1,29 @@
+# MCP tool design
+
+Model-facing tools, resources, and prompts are **public contracts**. Optimize for least surprise for the calling model.
+
+## Names and descriptions
+
+- Use stable, verb-oriented tool names (`read_file`, `list_tickets`) — not internal codenames.
+- Descriptions must state **what** the tool does, **when** to use it, and key constraints (side effects, required scopes).
+- Prefer enums / closed sets over free-form strings when the domain is finite.
+- Document idempotency and destructive effects explicitly in the description.
+
+## Schemas (Zod-first authoring)
+
+- Author validation with **Zod** (or the repo's schema library) for TypeScript types + runtime checks.
+- MCP-facing input/output schemas are **JSON Schema-compatible protocol contracts**.
+- Convert with an **SDK-supported** path — never pass a Zod object as the wire schema without verifying the installed `@modelcontextprotocol/sdk` API.
+- When unsure: `// VERIFY: @modelcontextprotocol/sdk @ <version>` and look up docs (Context7).
+
+## Errors and results
+
+- Map failures to clear, actionable error messages; do not leak stack traces, secrets, or absolute internal paths.
+- Keep success payloads structured and stable; avoid dumping entire process env or large blobs by default.
+- Version breaking schema changes (new tool name or documented major) rather than silently reshaping fields.
+
+## Anti-patterns
+
+- Generic "execute_anything" / "run_shell" tools without AC and capability scoping.
+- Duplicated ad-hoc schemas in registration and handler.
+- Side effects inside registration helpers.

package/presets/mavis/mcp-ts/rules/mcp-transport-packaging.md

@@ -0,0 +1,34 @@
+# MCP transport and packaging
+
+## Default: stdio
+
+- Local Cursor/Claude use → **stdio** transport from the server entry (`src/index.ts` or equivalent).
+- Entry owns connect/listen lifecycle and graceful shutdown; tools must not open competing transports.
+- Fail closed on missing required startup configuration.
+
+## Packaging
+
+- Expose a `bin` / `npx`-friendly entry in `package.json` that runs the compiled or `tsx` entry as appropriate for the repo.
+- Keep `files` / publish contents minimal; do not ship secrets, `.env`, or local credentials.
+- Document install and run commands in the consumer README — not by registering a half-built server into shipped client MCP JSON.
+
+## Optional remote transport
+
+- Streamable HTTP / SSE / remote hosting is **opt-in** — load this rule + `mcp-auth-secrets` + `security-mcp`.
+- Require explicit AC for auth mode, network exposure, and rate limits.
+- Before exposing remotely: implement **per-request** token validation (issuer/audience/expiry/scopes) and trusted request context per `mcp-auth-secrets`; treat retrieved content as untrusted per `security-mcp`.
+- Do not mandate Docker/OAuth/Inspector for every stdio-only server.
+
+## Threat model by transport
+
+| Mode | Trust boundary | Who can invoke tools | Required controls |
+|------|----------------|----------------------|-------------------|
+| **stdio** (default) | Same machine / IDE process | Host user + IDE agent session | Least-privilege tools; no network AuthN assumed; secrets via env; fail closed on missing config |
+| **HTTP / SSE** (opt-in) | Network-reachable process | Any client that can reach bind address | **TLS required** for non-localhost (or trusted TLS-terminating proxy with documented boundary); localhost-only bind OK without TLS; auth fail-closed; per-request issuer/audience/expiry/scopes; rate limits; safe errors (no token echo) |
+
+- Prefer bind `127.0.0.1` for local remote-dev; treat `0.0.0.0` as production exposure needing AC + TLS (or documented TLS-terminating proxy). Never expose bearer/OAuth over plaintext off-localhost.
+- Stdio inherits host privileges — do not compensate by adding “execute anything” tools.
+
+## VERIFY
+
+- Transport constructor and `Server` / `McpServer` APIs drift across SDK versions — verify against the installed package before inventing calls.

package/presets/mavis/mcp-ts/rules/mcp-ts-app-core.md

@@ -0,0 +1,23 @@
+# Stack and environment
+
+Node, TypeScript, and `@modelcontextprotocol/sdk` versions come **from the target repository `package.json` / lockfile**. Preset frame:
+
+- **Language / platform:** TypeScript (Node); package manager — discover from lockfile / `packageManager`.
+- **SDK:** official `@modelcontextprotocol/sdk` — verify APIs before use (`VERIFY:` markers when unsure).
+- **Default transport:** **stdio-first**; remote HTTP/auth — requestable rules only.
+- **Entry point:** `src/index.ts` (or repo equivalent) owns transport + lifecycle — not individual tools.
+- **Tests:** repository runner (Vitest/Jest/node:test); contract fixtures for schemas — see `mcp-contract-testing`.
+- **Observability:** only if already in repo — never log secrets or full tool payloads with credentials.
+
+# Structure (suggested)
+
+```text
+src/index.ts                 # transport + server lifecycle
+src/tools/                   # tool registration + handlers
+src/resources/               # resource registration (if used)
+src/prompts/                 # prompt registration (if used)
+src/**/schemas.ts            # Zod authoring schemas
+package.json                 # bin / main for stdio packaging
+```
+
+Boundaries — **`mcp-server-boundaries`**. Tooling — requestable **`mcp-ts-tooling`**. After TS edits — **`post-change-test`**.

package/presets/mavis/mcp-ts/rules/mcp-ts-conventions.md

@@ -0,0 +1,22 @@
+# TypeScript conventions (MCP servers)
+
+- Prefer **strict** TypeScript (`strict` true when adding a new tsconfig; do not weaken existing strictness without AC).
+- Validate tool inputs with Zod (or repo schema lib) **before** side effects.
+- Export narrow types for handler inputs inferred from schemas (`z.infer<typeof schema>`).
+- Errors returned to clients: safe messages; log details server-side with redaction.
+- Avoid `any`; prefer `unknown` + narrowing at boundaries.
+- SDK calls: confirm symbols against installed `@modelcontextprotocol/sdk` — use `// VERIFY: @modelcontextprotocol/sdk @ <version>` when unsure.
+- Do not invent hexagonal `internal/domain|application|adapters` layouts unless the target repo already uses them.
+
+## Registration flow
+
+1. Define Zod (or equivalent) input schema next to the tool.
+2. Map schema → JSON Schema / SDK registration shape the repo uses.
+3. Implement a pure handler that accepts validated args + narrow capability ports (FS/net/secrets).
+4. Register the tool once from the server entry (`src/index.ts` or a dedicated register module) — handlers must not open a second transport.
+5. Cover invalid inputs and happy path in colocated `*.spec.ts` / `*.test.ts` before packaging.
+
+## Errors and types
+
+- Prefer typed result/error unions over throwing across the MCP boundary when the SDK pattern allows.
+- Never put stack traces, env dumps, or tokens in tool results.

package/presets/mavis/mcp-ts/rules/mcp-ts-tooling.md

@@ -0,0 +1,21 @@
+# Tooling (mcp-ts)
+
+Discover package manager **before** running scripts:
+
+1. `packageManager` in `package.json`
+2. Lockfile: `yarn.lock` → yarn; `pnpm-lock.yaml` → pnpm; `package-lock.json` → npm; `bun.lock(b)` → bun
+3. Use **only** that manager for install/run
+
+## Typical gates (adapt to repo scripts)
+
+| Gate | Discovery |
+|------|-----------|
+| Typecheck | `tsc --noEmit` or script `typecheck` / `build` that typechecks |
+| Test | script `test` / `test:unit` / Vitest / Jest / `node:test` |
+| Lint | project ESLint if configured — never invent Next `lint:js`/`lint:css` as required |
+| Inspector | optional smoke — not required for every change |
+
+## Agent requirement
+
+- Do not hard-code `yarn` if the repo uses pnpm/npm/bun.
+- Never require Go tools (`go test` / `go vet`), `xcodebuild`, or Playwright as this stack's gate.

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

@@ -0,0 +1,93 @@
+<!-- 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
+
+## Stack notes
+
+- Shipped MCP is Context7 only. Do **not** require Storybook, Playwright, Chrome DevTools, or Figma as delivery gates.
+- Observability and ticket overlays still apply when present.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept.
+- Do not add a server-under-development to shipped consumer `mcp.json`.

package/presets/mavis/mcp-ts/rules/post-change-test.md

@@ -0,0 +1,21 @@
+# Post-change test (requestable; must after TS MCP edits)
+
+After changing TypeScript / package manifests in a consumer MCP server repo:
+
+1. Discover package manager (`mcp-ts-tooling`).
+2. Run **typecheck** (project script or `tsc --noEmit`).
+3. Run **tests** scoped to touched packages/files when possible; full suite before claiming done.
+4. Optional: MCP Inspector smoke for registration changes — not a hard gate.
+
+## Scope hints
+
+- Schema-only changes: include contract/schema fixture tests.
+- Handler changes: unit tests for valid/invalid inputs and error mapping.
+- Packaging/`bin` changes: verify entry still starts under stdio (manual or smoke).
+
+## Agent requirement
+
+- Do not claim completion without running the applicable gate (or noting why CI-only).
+- Pipeline `build-verifier` enforces the same checklist.
+- Skip only when the change is docs/config with no `*.ts` / package impact — state that explicitly.
+- Never require Playwright, XCUITest, Next lint recipes, or Go toolchains.

package/presets/mavis/mcp-ts/rules/preset-layering.md

@@ -0,0 +1,27 @@
+<!-- shared-core: meta/preset-layering.md -->
+
+# Preset layering
+
+Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in consumer apps.
+
+## Layers
+
+| 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 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
+
+1. Shared principles for all stacks → **core** + adapters with `<!-- shared-core: … -->`.
+2. Only one of the installable stacks (`next` / `nuxt` / `svelte` / `ios-swift` / `android-kotlin` / `go` / `java` / `mcp-ts` / `php-hexagonal` / `php-laravel`) → **stack-specific** (not in `_shared`).
+3. Only Cursor, Claude, Mavis, or OpenCode packaging → platform artifact / frontmatter; do not duplicate semantics.
+
+## SoT
+
+- Packages path — SoT; root `.cursor/` — dogfood sync.
+- Per stack: **Cursor** `presets/cursor/<stack>/` → Claude twin same PR.
+- `_shared` is **not** a `--preset` and is not copied by CLI `init`.
+
+See also: `preset-twin-sync`, `preset-token-budget`, `preset-pr-checklist`, `preset-no-cross-stack-leakage`.

package/presets/mavis/mcp-ts/rules/preset-no-cross-stack-leakage.md

@@ -0,0 +1,90 @@
+<!-- shared-core: meta/preset-no-cross-stack-leakage.md -->
+
+# Preset no cross-stack leakage
+
+Ban leakage of stack-specific names, paths, and handoff stems across presets.
+
+## Principles
+
+- `next` must not require iOS-only or Android-only agents/tooling (`xcuitest-*`, `instrumentation-test-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `nuxt` must not require iOS-only or Android-only agents/tooling (`xcuitest-*`, `instrumentation-test-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `svelte` must not require iOS-only or Android-only agents/tooling (`xcuitest-*`, `instrumentation-test-*`, `xcodebuild` as required handoff, Keychain-only rules).
+- `ios-swift` must not ship Playwright handoffs, Android `instrumentation-test-*` handoffs, or Next lint recipes as required commands.
+- `android-kotlin` must not ship Playwright, XCUITest, `xcodebuild`, or Next lint recipes as required handoffs.
+- `go` / `java` / `php-hexagonal` / `php-laravel` / `mcp-ts` must not ship Playwright, XCUITest, Android instrumentation agents, Next lint recipes, or `xcodebuild`/`SwiftLint` as required handoffs.
+- `mcp-ts` must not ship Go tool commands (`go test`, `go vet`, `golangci-lint`) or `integration-test-*` agents as required delivery gates.
+- Shared core must not embed stack paths (`app/src/**`, `Features/**`, `playwright`, `xcodebuild`).
+- Storybook / Chrome DevTools MCP must **not** be required handoffs or agent stems (`storybook-reviewer`) on backend or mobile stacks. Frontend overlay mentions in `MCP.md` / `mcp-usage` Stack notes are OK.
+
+## Forbidden in ios-swift hooks/agents (FAIL)
+
+In ios-swift `chain-team-phases.sh` / agent handoffs (Cursor + Claude):
+
+- `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`
+- `instrumentation-test-` as required Android handoffs
+- `app/__tests__/e2e` as a required path
+- Positive yarn recipes `lint:js` / `lint:css` as commands to run (negation prose alone is weak — prefer zero occurrences)
+
+Required instead: `xcuitest-test-*` stems; build-verifier mentions `xcodebuild` or `post-change-build` / `xcode-tooling`.
+
+## Forbidden in android-kotlin hooks/agents (FAIL)
+
+In android-kotlin `chain-team-phases.sh` / agent handoffs (Cursor + Claude):
+
+- `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`
+- `app/__tests__/e2e` as a required path
+- `xcuitest-test-`, positive `xcodebuild` / `SwiftLint` as required handoffs
+- Positive yarn recipes `lint:js` / `lint:css` as commands to run
+
+Required instead: `instrumentation-test-*` stems; build-verifier mentions `gradle-tooling` and/or `post-change-build` (Gradle wrapper discovery — not `xcodebuild` as the default gate).
+
+## Forbidden in next hooks/agents (FAIL when present as required)
+
+- `xcuitest-test-` / `instrumentation-test-` as handoff stems
+- Requiring `xcodebuild` / SwiftLint as the default post-change gate for Next app work
+
+## Forbidden in nuxt hooks/agents (FAIL when present as required)
+
+- `xcuitest-test-` / `instrumentation-test-` as handoff stems
+- Requiring `xcodebuild` / SwiftLint as the default post-change gate for Nuxt app work
+- Frontend profile mirrors `next`: Playwright / `lint:js` / `lint:css` allowed
+
+## Forbidden in svelte hooks/agents (FAIL when present as required)
+
+- `xcuitest-test-` / `instrumentation-test-` as handoff stems
+- Requiring `xcodebuild` / SwiftLint as the default post-change gate for SvelteKit app work
+- Frontend profile mirrors `next` / `nuxt`: Playwright / `lint:js` / `lint:css` allowed
+
+## Forbidden in go / java / php-hexagonal / php-laravel hooks/agents (FAIL)
+
+Shared backend-stack bans (`go`, `java`, `php-hexagonal`, and `php-laravel`):
+
+- `playwright-test-`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
+- Positive yarn recipes `lint:js` / `lint:css`
+- `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
+- Agent files `accessibility-reviewer`, `mockup-reviewer`, `ux-designer` (no UI surface)
+- Required `skills/ux-design`, required `rules/ux-design`, or required pipeline handoff stem `ux-design`
+
+Required instead: `integration-test-*`; build-verifier / `post-change-test` plus stack tooling — `go-tooling` (`go test`, `go vet`), `java-tooling` (`mvn test` / `./gradlew test`), or `php-tooling` (`php artisan test` / `composer test` / `vendor/bin/phpunit`).
+
+## Forbidden in mcp-ts hooks/agents (FAIL)
+
+Same UI/mobile bans as backend stacks, plus:
+
+- `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`
+- Positive yarn recipes `lint:js` / `lint:css` as required gates
+- `xcuitest-test-`, `instrumentation-test-`, `xcodebuild`, `SwiftLint` as required handoffs
+- Go tool commands as required MCP delivery gates: `go test`, `go vet`, `golangci-lint`
+- Agent files: `playwright-test-*`, `xcuitest-test-*`, `instrumentation-test-*`, `integration-test-*`, `accessibility-reviewer`, `mockup-reviewer`, `ux-designer`
+- Required `skills/ux-design`, required `rules/ux-design`, or required pipeline handoff stem `ux-design`
+
+Required instead: package-manager–discovered typecheck/test (`mcp-ts-tooling`, `post-change-test`); Phase 1 gates `build-verifier` + `security-reviewer`.
+
+## Soft / document
+
+- Mentioning the other stack in **docs** comparing presets is OK.
+- `build-verifier` may reference other stacks when validating **preset packaging** (`scope: preset-structure-validation`).
+
+## Chain fork
+
+`hooks/chain-team-phases.sh` must differ **byte-wise** pairwise among `next`, `nuxt`, `svelte`, `ios-swift`, `android-kotlin`, `go`, `java`, `mcp-ts`, `php-hexagonal`, and `php-laravel` (per platform). Released Mavis/OpenCode stacks must also differ from the Cursor and Claude twins of the same stack.

package/presets/mavis/mcp-ts/rules/preset-pr-checklist.md

@@ -0,0 +1,36 @@
+<!-- shared-core: meta/preset-pr-checklist.md -->
+
+# Preset PR checklist
+
+Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.cursor/` sync).
+
+## Before merge
+
+- [ ] **SoT:** edits in `packages/…` (not only root `.cursor/`)
+- [ ] **Core:** if `_shared/core/**` changed — all `<!-- shared-core: … -->` consumers updated (or documented intentional fork)
+- [ ] **Twin:** Cursor change → Claude twin **same PR** (**FAIL** if missing on next, nuxt, svelte, ios-swift, android-kotlin, go, java, mcp-ts, php-hexagonal, and php-laravel — see `preset-twin-sync`)
+- [ ] **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` 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`.
+- [ ] **Chain fork:** the byte-wise MD5 uniqueness of `chain-team-phases.sh` holds pairwise among the 10 stacks × Cursor/Claude platforms, and each released Mavis/OpenCode stack hook must also differ from the Cursor and Claude twins of the same stack. Run `packages/ai-rules/scripts/check-chain-hook-coverage.sh` and `packages/ai-rules/scripts/test-chain-team-phases-coverage.mjs`.
+- [ ] **Twin depth:** domain ≥15 lines; thin aliases documented
+- [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
+- [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
+- [ ] **i18n anchors:** kept-marked Cyrillic fragments in `tests-unit.md(c)` stay consistent with their English counterparts. Run `packages/ai-rules/scripts/check-preset-i18n.sh`.
+- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (and `sync-dogfood-mavis.sh` / `sync-dogfood-opencode.sh` when those platforms changed), or document an intentional skip, when maintaining this monorepo
+- [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
+
+## Pointers
+
+- Layering: `preset-layering`
+- Sync: `preset-twin-sync`
+- Budget: `preset-token-budget`
+- Leakage: `preset-no-cross-stack-leakage`
+- Validation: stack `agents/build-verifier.md` → preset-structure section
+- Dogfood scripts: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-mavis.sh`, `sync-dogfood-opencode.sh`
+- Drift script: `packages/ai-rules/scripts/check-shared-core-drift.sh`
+- Orchestrator: when editing presets, load this checklist + twin-sync

package/presets/mavis/mcp-ts/rules/preset-token-budget.md

@@ -0,0 +1,39 @@
+<!-- shared-core: meta/preset-token-budget.md -->
+
+# Preset token budget
+
+Invariants for rule loading in an **installed** preset (consumer app).
+
+## Hard caps
+
+| Platform | Always-on | Cap |
+|----------|-----------|-----|
+| 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** |
+
+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). Body budget sums only the intended session-start rules (≤5).
+
+Session-start body budget:
+- 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
+
+Rules for preset authors (`preset-layering`, `preset-twin-sync`, …):
+
+- **Never** `alwaysApply: true` on consumer installs.
+- Cursor: `globs` limited to `packages/ai-rules/presets/**` (and dogfood `.cursor/**` where useful).
+- Claude: `paths:` limited to `packages/ai-rules/presets/**` (and `.claude/**` dogfood if present).
+
+## Heavy workflows
+
+Orchestrator, feature-delivery, code-review, post-change gates, domain globs — **requestable / paths**, not always-on.
+
+## Verifier
+
+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/mcp-ts/rules/preset-twin-sync.md

@@ -0,0 +1,99 @@
+<!-- shared-core: meta/preset-twin-sync.md -->
+
+# Preset twin sync
+
+Cursor `.mdc` — **SoT per stack**. Claude topic `.md` — derived twin.
+
+## Matrix
+
+| Stack | Cursor SoT | Claude derive | Mapping table |
+|-------|------------|---------------|---------------|
+| `next` | `presets/cursor/next/rules/*.mdc` | `presets/claude/next/rules/<topic>/` | **Required** in `claude/next/rules/README.md` |
+| `nuxt` | `presets/cursor/nuxt/rules/*.mdc` | `presets/claude/nuxt/rules/<topic>/` | **Required** in `claude/nuxt/rules/README.md` |
+| `svelte` | `presets/cursor/svelte/rules/*.mdc` | `presets/claude/svelte/rules/<topic>/` | **Required** in `claude/svelte/rules/README.md` |
+| `ios-swift` | `presets/cursor/ios-swift/rules/*.mdc` | `presets/claude/ios-swift/rules/<topic>/` | Keep in `claude/ios-swift/rules/README.md` |
+| `go` | `presets/cursor/go/rules/*.mdc` | `presets/claude/go/rules/<topic>/` | Keep in `claude/go/rules/README.md` |
+| `java` | `presets/cursor/java/rules/*.mdc` | `presets/claude/java/rules/<topic>/` | Keep in `claude/java/rules/README.md` |
+| `mcp-ts` | `presets/cursor/mcp-ts/rules/*.mdc` | `presets/claude/mcp-ts/rules/<topic>/` | Keep in `claude/mcp-ts/rules/README.md` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/rules/*.mdc` | `presets/claude/php-hexagonal/rules/<topic>/` | Keep in `claude/php-hexagonal/rules/README.md` |
+| `php-laravel` | `presets/cursor/php-laravel/rules/*.mdc` | `presets/claude/php-laravel/rules/<topic>/` | Keep in `claude/php-laravel/rules/README.md` |
+| `android-kotlin` | `presets/cursor/android-kotlin/rules/*.mdc` | `presets/claude/android-kotlin/rules/<topic>/` | Keep in `claude/android-kotlin/rules/README.md` |
+
+## Mavis derivation (not a Claude twin)
+
+| Stack | Cursor SoT | Mavis derive | Manifest |
+|-------|------------|--------------|----------|
+| `next` | `presets/cursor/next/**` | `presets/mavis/next/**` via `generate-mavis.mjs --stack next` | **Required** `adapter-map.json` |
+| `nuxt` | `presets/cursor/nuxt/**` | `presets/mavis/nuxt/**` via `generate-mavis.mjs --stack nuxt` | **Required** `adapter-map.json` |
+| `svelte` | `presets/cursor/svelte/**` | `presets/mavis/svelte/**` via `generate-mavis.mjs --stack svelte` | **Required** `adapter-map.json` |
+| `ios-swift` | `presets/cursor/ios-swift/**` | `presets/mavis/ios-swift/**` via `generate-mavis.mjs --stack ios-swift` | **Required** `adapter-map.json` |
+| `android-kotlin` | `presets/cursor/android-kotlin/**` | `presets/mavis/android-kotlin/**` via `generate-mavis.mjs --stack android-kotlin` | **Required** `adapter-map.json` |
+| `go` | `presets/cursor/go/**` | `presets/mavis/go/**` via `generate-mavis.mjs --stack go` | **Required** `adapter-map.json` |
+| `java` | `presets/cursor/java/**` | `presets/mavis/java/**` via `generate-mavis.mjs --stack java` | **Required** `adapter-map.json` |
+| `mcp-ts` | `presets/cursor/mcp-ts/**` | `presets/mavis/mcp-ts/**` via `generate-mavis.mjs --stack mcp-ts` | **Required** `adapter-map.json` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/**` | `presets/mavis/php-hexagonal/**` via `generate-mavis.mjs --stack php-hexagonal` | **Required** `adapter-map.json` |
+| `php-laravel` | `presets/cursor/php-laravel/**` | `presets/mavis/php-laravel/**` via `generate-mavis.mjs --stack php-laravel` | **Required** `adapter-map.json` |
+
+Mavis is a **third platform adapter**, not a Claude-style topic twin:
+
+```text
+_shared/core  →  cursor/<stack>  →  mavis/<stack>
+```
+
+Regenerate with `node packages/ai-rules/scripts/generate-mavis.mjs --stack <stack>`; validate with `node packages/ai-rules/scripts/check-mavis-adapter-map.mjs`.
+
+## OpenCode derivation (not a Claude twin)
+
+| Stack | Cursor SoT | OpenCode derive | Manifest |
+|-------|------------|-----------------|----------|
+| `next` | `presets/cursor/next/**` | `presets/opencode/next/**` via `generate-opencode.mjs --stack next` | **Required** `adapter-map.json` |
+| `nuxt` | `presets/cursor/nuxt/**` | `presets/opencode/nuxt/**` via `generate-opencode.mjs --stack nuxt` | **Required** `adapter-map.json` |
+| `svelte` | `presets/cursor/svelte/**` | `presets/opencode/svelte/**` via `generate-opencode.mjs --stack svelte` | **Required** `adapter-map.json` |
+| `ios-swift` | `presets/cursor/ios-swift/**` | `presets/opencode/ios-swift/**` via `generate-opencode.mjs --stack ios-swift` | **Required** `adapter-map.json` |
+| `android-kotlin` | `presets/cursor/android-kotlin/**` | `presets/opencode/android-kotlin/**` via `generate-opencode.mjs --stack android-kotlin` | **Required** `adapter-map.json` |
+| `go` | `presets/cursor/go/**` | `presets/opencode/go/**` via `generate-opencode.mjs --stack go` | **Required** `adapter-map.json` |
+| `java` | `presets/cursor/java/**` | `presets/opencode/java/**` via `generate-opencode.mjs --stack java` | **Required** `adapter-map.json` |
+| `mcp-ts` | `presets/cursor/mcp-ts/**` | `presets/opencode/mcp-ts/**` via `generate-opencode.mjs --stack mcp-ts` | **Required** `adapter-map.json` |
+| `php-hexagonal` | `presets/cursor/php-hexagonal/**` | `presets/opencode/php-hexagonal/**` via `generate-opencode.mjs --stack php-hexagonal` | **Required** `adapter-map.json` |
+| `php-laravel` | `presets/cursor/php-laravel/**` | `presets/opencode/php-laravel/**` via `generate-opencode.mjs --stack php-laravel` | **Required** `adapter-map.json` |
+
+OpenCode is a **fourth platform adapter** with a **native** install root (`.opencode/`), not a Claude-style topic twin and not an owned overlay like `.mavis/`:
+
+```text
+_shared/core  →  cursor/<stack>  →  opencode/<stack>
+```
+
+Regenerate with `node packages/ai-rules/scripts/generate-opencode.mjs --stack <stack>`; validate with `node packages/ai-rules/scripts/check-opencode-adapter-map.mjs`. Do not derive OpenCode sources from Claude.
+
+## Same-PR checklist
+
+1. Edit Cursor rule first (body + frontmatter).
+2. Update Claude twin: body + `paths:` (from Cursor `globs:` / requestable triggers); drop `alwaysApply`.
+3. Update mapping table row if stem/path changed.
+4. If body embeds core (`<!-- shared-core: … -->`), sync core consumers across stacks when core changed.
+5. When mapped `cursor/<stack>/` sources change, regenerate `mavis/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-mavis.mjs --stack <stack>` + `check-mavis-adapter-map.mjs`).
+6. When mapped `cursor/<stack>/` sources change, regenerate `opencode/<stack>/` and refresh `adapter-map.json` `sourceRevision` in the **same PR** (run `generate-opencode.mjs --stack <stack>` + `check-opencode-adapter-map.mjs`).
+
+## Twin depth
+
+- **Domain** rules: ≥15 body lines (FAIL if thin without documented alias reason).
+- **Thin aliases** (`agent-team-intake`, `technical-retro`): may be shorter (soft) if they only point to a command/skill.
+- **Slim-companion rules** (UI-edit bundle, slim app-cores, slim tooling): may be shorter than 15 lines **if and only if** the body is a pointer into shared-core / stack-prose (no standalone prose). Examples live in stack `rules/README.md` (e.g. `cursor/next/rules/README.md` "UI-edit bundle" intent).
+  - Mechanical enforcement lives in `packages/ai-rules/scripts/check-preset-token-budget.sh` — see `SLIM_COMPANION_ALLOWLIST` (the 53 stems accepted as slim pointers) and `MIN_SLIM_BODY_LINES` (5-line floor). Slim-companion rules with a body of 6–14 lines whose stem is **not** in the allowlist are reported as slim violations by the script.
+
+## Severity (build-verifier)
+
+- **next:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **nuxt:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **svelte:** missing Claude twin for a changed Cursor rule → **FAIL** (mapping table required).
+- **ios-swift:** missing Claude twin for a changed Cursor rule → **FAIL**.
+- **go:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift; mapping table required).
+- **java:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go; mapping table required).
+- **mcp-ts:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java; mapping table required).
+- **php-hexagonal:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts; mapping table required).
+- **php-laravel:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-hexagonal; mapping table required).
+- **android-kotlin:** missing Claude twin for a changed Cursor rule → **FAIL** (same as next / ios-swift / go / java / mcp-ts / php-*; mapping table required).
+- **mavis/<stack>:** `cursor/<stack>` mapped source changed without mavis regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-mavis-adapter-map.mjs`).
+- **opencode/<stack>:** `cursor/<stack>` mapped source changed without opencode regeneration / `adapter-map.json` `sourceRevision` drift → **FAIL** (`check-opencode-adapter-map.mjs`).
+
+Dogfood: sync packages → root `.cursor/` after Cursor SoT changes (not the reverse). Use `packages/ai-rules/scripts/sync-dogfood-cursor.sh`.