@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/mavis/php-laravel/rules/events-listeners.md

@@ -0,0 +1,24 @@
+
+# Events / Listeners
+
+- Domain/application events signal that **something happened**; Listeners react (notify, project, enqueue).
+- Dispatch from Actions/Services (`TodoCreated::dispatch($todo)`); keep event payloads small (IDs / models via SerializesModels).
+- Prefer dedicated Listener classes over closures in `EventServiceProvider` when neighbors use classes.
+- Queued listeners (`ShouldQueue`) for slow side effects; sync listeners for cheap in-process reactions.
+- Discover listeners via attributes / provider registration matching the Laravel version + repo.
+
+## Structure
+
+- `app/Events/TodoCreated.php`, `app/Listeners/SendTodoCreatedNotification.php`.
+- One listener ≈ one reaction; split when a listener grows multiple unrelated side effects.
+
+## Testing
+
+- `Event::fake()`; `Event::assertDispatched(TodoCreated::class)`.
+- Feature tests may assert listener effects when not faked — match repo style.
+
+## Forbidden
+
+- Business rules that belong in Actions living only inside Listeners (harder to test/sync).
+- Circular event storms (Listener dispatches the same event without guard).
+- Using Events as a required hexagonal port layer — optional async pattern only.

package/presets/mavis/php-laravel/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/php-laravel/rules/form-requests.md

@@ -0,0 +1,24 @@
+
+# Form Requests
+
+- Validate untrusted input in **Form Requests** (or the repo's established validator) — not ad-hoc `$request->validate` sprinkled in Actions when neighbors use Form Requests.
+- `rules()` / `messages()` / `attributes()` stay at the HTTP edge; Actions receive already-validated arrays or typed props — **not** the Form Request object when avoidable.
+- Prefer `authorize()` on the Form Request **or** Policy/`$this->authorize` in the controller — pick the pattern neighbors use; do not double-authorize inconsistently.
+- Keep rules focused: required/types/uniqueness; complex cross-field domain rules may live in Action after validation basics pass.
+- Use `$request->validated()` (or `safe()->only(...)`) — never trust raw `$request->all()` into persistence.
+
+## Structure
+
+- `app/Http/Requests/<Feature>/StoreXRequest.php` (or flat `StoreXRequest`) matching repo nesting.
+- Shared rule fragments: extract only after Rule of Three; prefer Laravel Rule objects already in the repo.
+
+## Testing
+
+- Feature tests assert 422 validation envelopes for missing/invalid fields.
+- Do not unit-test every rule string in isolation unless the repo already does.
+
+## Forbidden
+
+- Importing Form Requests into Models or Jobs as a validation substitute.
+- Putting Eloquent queries that belong in Actions into Form Request `prepareForValidation` without need.
+- Inventing a custom validation framework when Laravel Form Requests suffice.

package/presets/mavis/php-laravel/rules/http-layer.md

@@ -0,0 +1,25 @@
+
+# HTTP layer (Laravel)
+
+- Controllers are **thin**: authorize → validate (Form Request) → call one Action/Service → return Resource / response.
+- Prefer invokable or resource controllers matching existing repo style; do not invent a new controller taxonomy mid-feature.
+- Map status + body at the edge; use API Resources (or repo-equivalent) for JSON — do not return Eloquent models raw when neighbors use Resources.
+- Keep business orchestration in Actions/Services — not private methods that grow into a second service layer inside the controller.
+- Middleware owns cross-cutting HTTP concerns (auth, throttle, locale) already used by the repo.
+
+## Resilience
+
+- Side-effect endpoints: accept/propagate an **idempotency key** when the domain already uses one; document if intentionally omitted.
+- Soft size hint: split when a controller grows past ~200 LOC or owns more than one use case.
+
+## Testing
+
+- Prefer Feature tests through the HTTP kernel (`tests/Feature`) with SQLite / repo test DB.
+- Unit-test Actions separately when logic is non-trivial; mock Eloquent only if the repo already does.
+
+## Forbidden
+
+- Business SQL / multi-model workflows in controllers.
+- Skipping Form Requests when neighbors validate via Form Requests.
+- Ad-hoc role/`if ($user->isAdmin)` AuthZ when a Policy exists or should.
+- Blade/Livewire/Filament concerns — **out of this preset**.

package/presets/mavis/php-laravel/rules/jobs-queues.md

@@ -0,0 +1,36 @@
+
+# Jobs / queues
+
+- Use Jobs for **deferred / async** work (email, fan-out, slow I/O) — not as a substitute for a clear sync Action.
+- Dispatch from Actions/Services after the sync write succeeds (or inside the same transaction only when the repo already uses `afterCommit`).
+- Implement `ShouldQueue` when neighbors queue; keep `handle()` focused.
+- Configure `$tries`, `$backoff`, `$timeout` only when the job needs them or neighbors set them.
+- Fail closed: don't swallow exceptions; use failed-job handling the repo already has.
+
+## Serialization / DI (queued jobs)
+
+Queued Job **constructors and public properties are serialized** onto the queue. Put only **serializable payloads** there:
+
+- Primitives, IDs, arrays of scalars, DTOs that serialize cleanly.
+- Eloquent models only when using `SerializesModels` carefully (prefer IDs when the model may change or be large).
+
+**Resolve services / repositories / collaborators via `handle()` method injection** (or container resolve inside `handle`). Do **not** inject app services, repositories, mailers, HTTP clients, or other container collaborators through the queued Job constructor — they are not reliable queue payloads.
+
+Sync-only jobs that never implement `ShouldQueue` may use constructor DI if that matches neighbors; prefer the same `handle()` injection pattern for consistency.
+
+## Structure
+
+- `app/Jobs/SendTodoCreatedNotification.php` (verb + subject naming).
+- Prefer serializing models via `SerializesModels` as Laravel defaults when models are the payload.
+
+## Testing
+
+- `Bus::fake()` / `Queue::fake()` in Feature tests; assert `Bus::assertDispatched(…)`.
+- Optionally `Bus::dispatchSync` in integration when asserting side effects end-to-end.
+
+## Forbidden
+
+- Injecting services / repositories / other collaborators via the queued Job constructor.
+- HTTP Request types inside Jobs.
+- Huge Jobs that re-implement the whole Action — pass IDs / minimal payloads.
+- Requiring external brokers in dogfood when `sync` / `array` / `database` driver suffices.

package/presets/mavis/php-laravel/rules/laravel-app-core.md

@@ -0,0 +1,30 @@
+
+# Stack and environment
+
+PHP and Laravel versions — **from the target repository’s `composer.json` / `composer.lock`**. Preset frame:
+
+- **Language / platform:** PHP **8.2+** + **Composer** + **PSR-4** (`App\…`).
+- **Framework:** **Laravel 11+** baseline in Stack notes; read exact constraint from the target repo.
+- **Architecture:** Laravel-first (HTTP → Actions/Services → Eloquent); not required hexagonal ports purity.
+- **Tests:** PHPUnit default; Pest — if already in the repo/CI; gate = `php artisan test` / `composer test`.
+- **Static / format:** Pint / PHPStan / Psalm — only if already configured.
+- **HTTP:** thin controllers; Form Requests; API Resources; Policies for AuthZ.
+
+# Layout (default: flat `app/`)
+
+```text
+app/
+  Http/Controllers|Requests|Resources|Middleware/
+  Actions/   and/or   Services/
+  Models/
+  Policies/
+  Providers/
+  Jobs/  Events/  Listeners/
+routes/api.php  routes/web.php
+tests/Unit/  tests/Feature/
+artisan  composer.json
+```
+
+**Modular variant (optional):** `app/Domain/<Module>/` — short requestable note in `domain-layer` only; default remains flat Laravel `app/`.
+
+Boundaries — **`architecture-boundaries.md`**. Tooling — requestable **`php-tooling.md`**. After PHP edits — **`post-change-test.md`**.

package/presets/mavis/php-laravel/rules/laravel-conventions.md

@@ -0,0 +1,34 @@
+
+# Laravel conventions
+
+- Follow PSR-12 / Pint config when present; naming: `PascalCase` classes, `camelCase` methods, namespaces match Composer PSR-4 (`App\…`).
+- Prefer typed properties, return types, and `strict_types=1` when neighboring files use them.
+- Prefer `final` / `readonly` where the repo already uses them; do not invent a new style mid-module.
+- Artisan generators (`php artisan make:…`) OK when they match target layout; tidy generated stubs to repo style.
+- Do not invent Laravel APIs — verify against `composer.json` / framework docs for the installed major (`// VERIFY:` when unsure).
+- Prefer Form Requests, Policies, Actions, Resources — the Laravel toolkit — over inventing hexagonal DTO trees.
+
+## Errors / exceptions
+
+- Prefer domain/application exceptions or Laravel's HTTP exceptions at the edge (`abort`, `AuthorizationException`).
+- Chain causes; never empty-catch without logging or rethrowing.
+- Map to HTTP statuses in controllers / exception handler — not inside Models.
+
+## Container / facades
+
+- Constructor injection preferred in new code; Facades OK when neighbors use them (`Route`, `DB`, `Event`).
+- Avoid service-locator `app(Foo::class)` mid-Action when constructor injection fits.
+
+## Anti-hallucination
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Invented packages not in `composer.json` | Add dependency explicitly or copy existing import |
+| Fat controllers | Thin controller → Action |
+| Blade/Livewire in API tasks | Out of preset scope |
+| Hexagonal folder mandates | Flat `app/` Laravel layout |
+| Empty `catch` | Handle, wrap, or declare |
+
+## Agent requirement
+
+New PHP code must stay idiomatic Laravel and verifiable against `composer.json` and neighboring `app/` packages.

package/presets/mavis/php-laravel/rules/mcp-usage.md

@@ -0,0 +1,92 @@
+<!-- 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.

package/presets/mavis/php-laravel/rules/module-public-api.md

@@ -0,0 +1,23 @@
+# Module public API
+
+- Published types under a package/module's public namespaces are a compatibility surface — change carefully; prefer additive APIs.
+- Prefer narrow exports; expose only what other modules/features need.
+- Do not deep-import another module's internal namespaces; depend on its published API / facade only.
+- Document breaking PHP API changes in CHANGELOG when the repo publishes libraries.
+
+## Flat app/ default / modular variant
+
+- **Default:** one Laravel app with flat `app/` namespaces (see `dogfood/php-laravel`).
+- **Modular:** when the repo already uses `app/Domain/<Module>/` or Composer path packages, each module exposes a narrow public API; other modules depend inward only.
+- Do not invent multi-package scaffolding unless the repo already uses it.
+
+## composer.json
+
+- Package name, PHP/Laravel versions, and PSR-4 map are SoT for toolchain/autoload.
+- Prefer minimal direct deps; pin via committed `composer.lock` the repo already uses.
+- Dev-only tools (PHPUnit, Pint, PHPStan) stay in `require-dev`.
+
+## Cross-feature
+
+- Features communicate via Actions/Services public methods or small facades — not by importing sibling Feature private helpers.
+- Form Request / Resource DTOs stay local to the HTTP edge of that feature.

package/presets/mavis/php-laravel/rules/php-tooling.md

@@ -0,0 +1,26 @@
+# PHP / Laravel tooling (requestable)
+
+Before running commands, discover from the repository:
+
+1. Require **`composer.json` / `composer.lock`** — Composer is the package manager.
+2. PHP / Laravel versions — from `composer.json`; do not invent.
+3. Tests: prefer **`php artisan test`**; else Composer script `test`; else `vendor/bin/phpunit`; use **Pest** only if already in repo/CI.
+4. If both PHPUnit and Pest exist, follow CI/README — do not guess.
+
+## Typical commands
+
+| Goal | Command |
+|------|---------|
+| Feature/unit tests | `php artisan test` or `composer test` |
+| Pest (if present) | via `artisan test` / `vendor/bin/pest` per repo |
+| Autoload refresh | `composer dump-autoload` |
+| Static analysis | `vendor/bin/phpstan` or `vendor/bin/psalm` **only if** config exists |
+| Format | `vendor/bin/pint` or `php-cs-fixer` **only if** configured |
+
+Do not introduce a new static/format tool as a hard gate.
+
+## Agent requirements
+
+- Mandatory after PHP edits: **`post-change-test.md`**.
+- Never require Playwright, XCUITest, `lint:js`, `lint:css`, `xcodebuild`, `mvn`, or `gradlew` as Laravel handoffs.
+- Integration/Feature tests: agents `integration-test-*` + skill `integration-testing` (Laravel Feature ≈ integration).

package/presets/mavis/php-laravel/rules/policies-authorization.md

@@ -0,0 +1,24 @@
+
+# Policies / authorization
+
+- Authorize via **Policies** / `Gate` — not scattered `$user->role === …` checks in controllers/Actions.
+- Controllers: `$this->authorize('update', $todo)` or Form Request `authorize()` — match neighbors.
+- Policy methods return `bool` / `Response`; keep them focused on AuthZ (ownership, roles, abilities).
+- Register policies via auto-discovery or `AuthServiceProvider` as the Laravel version expects.
+- Guest / unauthenticated: return false or use `Gate::before` only if the repo already uses that pattern.
+
+## Structure
+
+- `app/Policies/TodoPolicy.php` with `view`, `create`, `update`, `delete` (or repo verbs).
+- Prefer model-type hints (`User $user, Todo $todo`); use class-string abilities for create when needed.
+
+## Testing
+
+- Feature tests assert **403** on denied actions and **201/200** when allowed.
+- Use actingAs / Sanctum helpers the repo already uses.
+
+## Forbidden
+
+- Duplicating the same role check in Controller + Action + Model.
+- Putting business validation (field formats) into Policies — that belongs in Form Requests.
+- Inventing a custom ACL framework when Laravel Policies suffice.

package/presets/mavis/php-laravel/rules/post-change-test.md

@@ -0,0 +1,20 @@
+# Post-change test (requestable; must after PHP edits)
+
+After changing PHP sources or Composer descriptors:
+
+1. Detect tools via **`php-tooling.md`** (prefer `php artisan test`).
+2. Run the repository test task (`php artisan test` / `composer test` / `vendor/bin/phpunit`, or Pest if that is the repo default).
+3. If the repo **or CI** already runs Pint, PHPStan, Psalm, or PHP-CS-Fixer, discover and run the same locally next — **do not** introduce a tool that is absent.
+4. Apply **only** formatter/static-analysis steps already in the project or CI.
+
+## Pass / fail
+
+- **PASS:** tests green; configured static gates green (when present).
+- **FAIL:** red tests or configured gate failures — fix before handoff.
+- Do **not** substitute yarn `lint:js`/`lint:css`, Playwright, XCUITest, `xcodebuild`, `mvn`, or `gradlew`.
+
+## Related
+
+- Tooling discovery: `php-tooling.md`
+- Unit: `tests-unit.md` (PHPUnit / Pest)
+- Feature / integration: `tests-integration.md` + `integration-test-*` agents

package/presets/mavis/php-laravel/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/php-laravel/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/php-laravel/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/php-laravel/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.