@bonesofspring/ai-rules 0.2.25 → 0.2.26

package/presets/mavis/php-hexagonal/rules/design-guidance.md

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

package/presets/mavis/php-hexagonal/rules/domain-layer.md

@@ -0,0 +1,31 @@
+
+# Domain layer
+
+- Pure business types and rules; **no I/O**, no framework, no ORM, no HTTP.
+- Prefer small value objects with validation factories (`of` / `from` / private constructors) that throw typed **domain** exceptions.
+- Domain errors are typed (`RuntimeException` subtypes or a small hierarchy); map to HTTP/gRPC statuses **only** in adapters.
+- Domain services orchestrate entities/VOs without calling outbound ports (ports live in **application**).
+- Keep invariants close to the type that owns them; avoid anemic bags of fields with all logic in use cases.
+- Prefer `readonly` / immutable types when the repo already uses them; do not invent a new VO style mid-module.
+
+## Forbidden imports
+
+- Framework HTTP kernels, PSR-15 request/response types as domain deps, Laravel/Symfony request classes.
+- Eloquent/Doctrine entities as domain types, `EntityManager`, query builders as domain deps.
+- Redis/Kafka/HTTP clients, OpenAPI/JSON serialization attributes that mirror wire contracts.
+- Framework request-scope / security-context plumbing as a substitute for domain deadlines (prefer explicit types).
+
+## Allowed
+
+- PHP stdlib: `DateTimeImmutable`, arrays/collections used by the repo, custom exceptions, pure utilities.
+- Cross-aggregate references by **ID**, not by loading other aggregates via ports.
+- Deadline/time primitives only when the domain API genuinely needs them (prefer application to pass values).
+
+## Plain-PHP / alternate frameworks
+
+Same rules: domain stays framework-free whether the edge is Slim, Symfony HttpFoundation, Laravel HTTP, or plain PHP.
+
+## Tests
+
+- PHPUnit (or Pest) unit tests; **no** DB, HTTP controller harness, or framework kernel.
+- Cover invalid factory inputs and invariant violations explicitly.

package/presets/mavis/php-hexagonal/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-hexagonal/rules/mcp-usage.md

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

package/presets/mavis/php-hexagonal/rules/messaging-adapters.md

@@ -0,0 +1,29 @@
+# Messaging adapters
+
+- **Publisher** (driven): implements an outbound port; serializes application/domain events to wire format inside the adapter.
+- **Consumer** (driving): deserializes → maps to application/domain types → calls inbound port / use case; **ack/nack** (and commit) stays in the adapter.
+- Idempotency keys, retry, and DLQ/parking-lot policy are adapter (or infra) concerns — document at-least-once vs exactly-once assumptions at the port.
+- Use the broker client already present in the repo — do not invent a second stack.
+
+## Event shapes
+
+- Prefer explicit event types in application or a small `Events` namespace used by ports.
+- Map wire DTOs ↔ application events **only** in the adapter; never pass broker payloads (`AMQPMessage`, Kafka records, SQS envelopes) into domain.
+
+## Stack notes (PHP)
+
+- Prefer the transport already wired: **Symfony Messenger**, enqueue/AMQP clients, php-rdkafka / Kafka clients, or AWS SDK for SQS — follow the repo.
+- Framework bus types (`Envelope`, `MessageBusInterface`, raw AMQP channel) stay in adapters / composition — not in domain or application ports.
+- Outbox / inbox and retry schedules are infra; ports expose intent (`publish`, `handle`) without broker APIs.
+
+## Forbidden
+
+- Broker client types (`AMQPStreamConnection`, `RdKafka\Producer`, SQS client classes, Messenger `Envelope`) in domain or application signatures.
+- Business rules inside listeners beyond mapping + calling one use case.
+- Silent catch-and-ack that drops poison messages without DLQ/metrics policy.
+
+## Tests
+
+- Unit-test mapping and idempotency branches with fakes.
+- Integration against embedded broker / Testcontainers **when the repo already has that setup**.
+- After edits: `post-change-test` (+ `php-tooling`); agents `integration-test-*` when adding consumer contracts.

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

@@ -0,0 +1,24 @@
+# Module public API
+
+- Published types under a package's public namespaces are a compatibility surface — change carefully; prefer additive APIs.
+- Service-private code stays in implementation namespaces — do not treat every namespace as public API.
+- 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.
+
+## Single-package default / multi-package variant
+
+- **Default:** one Composer package with layer-first namespaces under `src/` (see `dogfood/php-hexagonal`).
+- **Multi-package (Composer path repos / monorepo):** each package exposes a narrow public API; application ports may live in an `*-api` / `*-contracts` package; adapters depend inward. Do not invent multi-package scaffolding unless the repo already uses it.
+- Path repositories / `"repositories": [{"type":"path",...}]` — treat each package's `composer.json` `autoload.psr-4` as that package's boundary SoT.
+
+## composer.json
+
+- Package name, PHP version, and PSR-4 map are SoT for toolchain/autoload.
+- Prefer minimal direct deps; pin via `composer.lock` the repo already uses.
+- Dev-only tools (PHPUnit, PHPStan) stay in `require-dev` — not runtime public API.
+
+## Cross-feature
+
+- Inside one package, features communicate via application ports or small public facades — not by importing sibling feature adapter namespaces (`Adapters/Inbound/...` of another feature).
+- Domain and application types may be shared within the package; adapter DTOs stay local to that adapter.

package/presets/mavis/php-hexagonal/rules/persistence-adapters.md

@@ -0,0 +1,25 @@
+
+# Persistence adapters
+
+- Implement outbound repository ports from application.
+- Use parameterized queries / query builders / ORM methods — **never** string-concatenated SQL with untrusted input.
+- Map rows / ORM entities → **domain** inside the adapter; entities stay private to the adapter package when possible.
+- Transactions: use cases own the boundary (framework transaction on application services, or a `UnitOfWork` port). Adapters must not start ad-hoc transactions that hide business atomicity.
+- Migrations live with infra (`database/migrations`, Doctrine migrations dirs) — **not** in domain.
+
+## Mapping
+
+- Eloquent/Doctrine entities / PDO row mappers are adapter-local; do not pass them through port signatures or up into application/domain.
+- Nullability and DB defaults convert to domain values explicitly (no silent nulls into invariants).
+- ORM repositories may be used **inside** the adapter as helpers; the application still depends on the port interface, not on the ORM base class.
+
+## Forbidden
+
+- Importing persistence from domain, or leaking `EntityManager` / Eloquent models / PDO through port APIs.
+- Building SQL/DQL strings in use cases.
+- Returning ORM entities from HTTP controllers “because lazy loading”.
+
+## Tests
+
+- Integration tests with test DB / fixtures preferred for repos; unit-test mappers with fixtures.
+- Prefer testing through the port implementation (`integration-test-*`).

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

@@ -0,0 +1,32 @@
+
+# Stack and environment
+
+PHP and dependency versions come **from the target repository’s `composer.json` / `composer.lock`**. Preset frame:
+
+- **Language / platform:** PHP **8.x** + **Composer** + **PSR-4** namespaces.
+- **Architecture:** hexagonal (ports & adapters); domain does not know HTTP/ORM/brokers.
+- **Framework:** framework-agnostic HTTP edge; Slim / Symfony HttpFoundation / Laravel HTTP — **variants in Stack notes only** (not Laravel-first).
+- **Tests:** PHPUnit default; Pest — if already in the repo/CI.
+- **Static / format:** PHPStan/Psalm / PHP-CS-Fixer/Pint — only if already configured.
+- **HTTP:** thin controllers at the edge; map DTO ↔ application/domain.
+
+# Structure (default: layer-first)
+
+```text
+src/
+  Domain/
+  Application/              # use cases + port interfaces
+  Adapters/Inbound/Http/
+  Adapters/Outbound/Persistence|Messaging|External/
+  Composition/              # bootstrap / DI wiring (no business logic)
+tests/
+  Unit/
+  Integration/
+composer.json
+```
+
+**Feature-first variant:** `src/<Feature>/{Domain,Application,Adapters}` — same dependency direction.
+
+Namespace base — from the Composer PSR-4 map (`App\Domain\…` and similar); do not invent a classmap.
+
+Boundaries — **`architecture-boundaries.md`**. Tooling — requestable **`php-tooling.md`**. After PHP edits — **`post-change-test.md`**.

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

@@ -0,0 +1,46 @@
+
+# PHP conventions
+
+- Follow PSR-1 / PSR-12 (or the repo's PHP-CS-Fixer / Pint config) when present.
+- Naming: `PascalCase` classes, `camelCase` methods/properties, namespaces match Composer PSR-4.
+- Prefer `final` classes / `readonly` where the repo already uses them; do not invent a new style mid-module.
+- Prefer typed properties, return types, and `strict_types=1` when neighboring files use them.
+- Prefer PHPUnit data providers / Pest datasets when covering multiple cases.
+- Do not invent library APIs — verify symbols against `composer.json` and existing imports (`// VERIFY:` when unsure).
+
+## Errors / exceptions
+
+- Prefer domain/application exception types extending `\RuntimeException` (or the repo's base) unless public API requires otherwise.
+- Chain causes (`new X($msg, 0, $previous)`); never empty-catch without logging or rethrowing.
+- Prefer domain-specific exception types for structured cases; avoid bare `catch (\Throwable)`.
+- Map to HTTP/gRPC statuses only in adapters — do not throw framework HTTP exceptions from domain.
+
+## Interfaces / ports
+
+- Depend on interfaces (ports) at the call site; return concrete types from factories when simple.
+- Keep interfaces small (ISP); define ports in application, not on every adapter class «just in case».
+
+## Packages / namespaces
+
+- Avoid `Util`/`Common` dumping grounds — name by domain capability.
+- Keep bootstrap / composition / `public/index.php` thin (see `composition-root`).
+- No static mutable request state; no business logic in static initializers.
+
+## Concurrency / async
+
+- Match existing patterns (sync request/response by default; Fibers/async only if the repo already uses them).
+- Do not start unbounded background workers from handlers without a shutdown/supervision story.
+
+## Anti-hallucination
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| Empty `catch` / ignored failures | Handle, wrap with cause, or declare |
+| Interfaces on every class «just in case» | Ports at consumer / call site |
+| Invented packages not in `composer.json` | Add dependency explicitly or copy existing import |
+| Untyped `array` where a VO/DTO fits | Typed objects / arrayshape used by the repo |
+| Business logic in bootstrap | Wire in composition root |
+
+## Agent requirement
+
+New PHP code must stay idiomatic and verifiable against `composer.json` and neighboring packages. Less guessed code is better than more.

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

@@ -0,0 +1,26 @@
+# PHP tooling (requestable)
+
+Before running commands, discover from the repository:
+
+1. Require **`composer.json`** / **`composer.lock`** — Composer is the package manager.
+2. PHP version — from `composer.json` `require.php` / CI image; do not invent.
+3. Tests: prefer Composer script `test` when present; 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 |
+|------|---------|
+| Unit/integration tests | `composer test` or `vendor/bin/phpunit` |
+| Pest (if present) | `composer 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/php-cs-fixer` or `vendor/bin/pint` **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 PHP handoffs.
+- Integration tests: agents `integration-test-*` + skill `integration-testing`.

package/presets/mavis/php-hexagonal/rules/ports-interfaces.md

@@ -0,0 +1,27 @@
+
+# Ports (interfaces)
+
+## Outbound (driven)
+
+- Repository, cache, publisher, clock, ID generator, external client — defined by **application** (owner of the need).
+- Signatures use **domain** types (or small application DTOs), never Eloquent/Doctrine entities, PDO statement types, or broker message types.
+- Keep interfaces small (ISP); prefer role interfaces over god-repos (`OrderRepository` vs `EverythingRepository`).
+- Do not put ORM repository base classes in domain; if Eloquent/Doctrine is used, it stays in the outbound adapter and implements (or is wrapped by) the application port.
+
+## Inbound (driving)
+
+- Optional interface wrapping use cases for multiple drivers (HTTP + gRPC + CLI + messaging consumer).
+- Drivers depend on inbound ports / use-case APIs — not on each other.
+- Prefer a concrete use-case class when only one driver exists; extract an interface when a second driver appears (Rule of Three / YAGNI).
+
+## Naming
+
+- `saveOrder`, `findOrderById`, `publishOrderPlaced` — verb-oriented; match neighboring package style.
+- Implementation types live in adapters (`DoctrineOrderRepository`, `PdoOrderRepository`), not beside the interface in domain.
+
+## Anti-patterns
+
+- Ports returning untyped `array` bags or framework entities.
+- Putting port interfaces inside adapter packages (wrong owner — adapters implement, application defines).
+- Leakage of `EntityManager`, Eloquent models, or Redis types through port method signatures.
+- One mega-port “for convenience” that every use case depends on.

package/presets/mavis/php-hexagonal/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`** (Composer scripts preferred).
+2. Run the repository test task (`composer test` / `vendor/bin/phpunit`, or Pest if that is the repo default).
+3. If the repo **or CI** already runs PHPStan, Psalm, PHP-CS-Fixer, or Pint (config file, Composer script, or workflow step), discover and run the same locally next — **do not** introduce a tool that is absent from the project.
+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)
+- Integration: `tests-integration.md` + `integration-test-*` agents

package/presets/mavis/php-hexagonal/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 trio, 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-hexagonal/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.