@bonesofspring/ai-rules 0.2.25 → 0.2.27

package/presets/opencode/go/rules/design-guidance.md

@@ -0,0 +1,104 @@
+<!-- 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).
+
+## Stack notes
+
+- Strategy via func values / small interfaces at **ports**; adapters implement, domain stays free of frameworks.
+- Suggest Facade at package public API; avoid Singleton in favor of composition root wiring.

package/presets/opencode/go/rules/domain-layer.md

@@ -0,0 +1,25 @@
+
+# Domain layer
+
+- Pure business types and rules; no I/O.
+- Prefer small value objects with validation constructors (`NewX` / `ParseX` that return typed errors).
+- Domain errors are typed (sentinel or structured); map to HTTP/gRPC statuses only in adapters.
+- Domain services orchestrate entities 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.
+
+## Forbidden imports
+
+- `net/http`, `database/sql`, ORM packages, Redis/Kafka clients, router frameworks (`gin`, `chi` as handler deps).
+- Transport DTOs and `json` tags that mirror API contracts (keep API shapes in adapters).
+- Framework `context` cancellation plumbing as a substitute for domain deadlines (prefer explicit types).
+
+## Allowed
+
+- `context` only if domain API genuinely needs deadlines (prefer application to pass primitives).
+- Stdlib: `time`, `errors`, `fmt`, `slices`, `maps`, etc.
+- Cross-aggregate references by ID, not by loading other aggregates via ports.
+
+## Tests
+
+- Table-driven unit tests; no DB, no `httptest`, no framework contexts.
+- Cover invalid constructor inputs and invariant violations explicitly.

package/presets/opencode/go/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/opencode/go/rules/go-app-core.md

@@ -0,0 +1,27 @@
+
+# Stack and environment
+
+Go, toolchain, and dependency versions — **from the target repository’s `go.mod` / `go.work`**. Preset frame:
+
+- **Language / platform:** Go (module mode); min version — from the `go` directive in `go.mod`.
+- **Architecture:** hexagonal (ports & adapters); the domain layer must not know HTTP/SQL/brokers.
+- **Entry points:** `cmd/<service>/main.go` → composition root.
+- **Concurrency:** `context.Context` at boundary APIs; do not store Context in structs longer than the request.
+- **Tests:** `testing` + table-driven; integration behind adapters; e2e HTTP smoke — as needed.
+- **HTTP:** framework-agnostic (`net/http`, chi/gin/echo — examples, not a mandate).
+- **Observability:** only if already in the repo — centralized (logs/metrics/tracing).
+
+# Structure (default: layer-first)
+
+```text
+cmd/<service>/main.go
+internal/domain/
+internal/application/          # use cases + ports
+internal/adapters/http|grpc|persistence|cache|messaging/
+internal/app/                  # optional DI wiring
+pkg/                           # optional public library API
+```
+
+**Feature-first variant** allowed: `internal/<feature>/{domain,application,adapters}` — same dependency direction.
+
+Boundaries — **`architecture-boundaries.md`**. Tooling — requestable **`go-tooling.md`**. After Go edits — **`post-change-test.md`**.

package/presets/opencode/go/rules/go-conventions.md

@@ -0,0 +1,45 @@
+# Go conventions
+
+- Follow [Effective Go](https://go.dev/doc/effective_go) and repo `golangci-lint` / `staticcheck` when present.
+- Accept `context.Context` as first param on I/O and use-case methods.
+- Prefer `camelCase` unexported, `PascalCase` exported; package names short and lowercase.
+- Do not expose `internal/` outside the module.
+- Prefer table-driven tests; use `t.Parallel` only when safe.
+
+## Errors
+
+- Always handle errors — never `_ = err`.
+- Wrap with `fmt.Errorf("…: %w", err)`; check with `errors.Is` / `errors.As`.
+- Prefer domain/custom error types for structured cases; avoid panics in library/service code.
+
+## Interfaces
+
+- Accept interfaces, return concrete types.
+- Define interfaces at the **call site** (ports / consumers), not on every implementation.
+- Prefer small, single-method interfaces when they match the use.
+
+## Packages
+
+- Avoid `util`/`common` dumping grounds — name by domain capability.
+- Keep `main` packages thin (see composition-root).
+- No `init()` for business logic; no package-level mutable state for request data.
+
+## Concurrency
+
+- Document cancelation; `defer cancel()` after creating a derived context.
+- Do not start unbounded goroutines from handlers without a termination condition / supervision (`WaitGroup`, errgroup, or context cancel).
+- Channels for communication, mutexes for shared state — match existing package patterns.
+
+## Anti-hallucination
+
+| ❌ Avoid | ✅ Prefer |
+|---------|----------|
+| `_ = err` / ignored errors | Handle or wrap with `%w` |
+| Interfaces on every struct «just in case» | Ports at consumer / call site |
+| Invented modules not in `go.mod` | Add dependency explicitly or copy existing import |
+| `interface{}` where generics or a concrete type fit | Generics / concrete types used by the repo |
+| Business logic in `init()` | Wire in composition root / `main` |
+
+## Agent requirement
+
+New Go code must stay idiomatic and verifiable against `go.mod` and neighboring packages. Less guessed code is better than more.

package/presets/opencode/go/rules/go-tooling.md

@@ -0,0 +1,28 @@
+
+# Go tooling (requestable)
+
+Before running commands, read **`go.mod`** for module path and Go version.
+
+## Common commands
+
+```bash
+go test ./...
+go vet ./...
+go test ./... -race
+go test ./... -cover
+```
+
+- If the repo has `golangci-lint` or `staticcheck`, use the project’s documented invocation (Makefile/taskfile).
+- Do not invent a lint stack; prefer what CI already runs.
+- Module ops: `go get`, `go mod tidy` only when deps change.
+- Prefer `go test ./path/to/pkg` while iterating; widen to `./...` before handoff.
+
+## Race / cover
+
+- Use `-race` for concurrent maps, workers, or shared caches.
+- Coverage is optional unless the task or CI requires a threshold.
+
+## Related
+
+- Mandatory after Go edits: **`post-change-test.md`**.
+- Pipeline gate: `build-verifier` (same commands; no yarn lint / xcodebuild).

package/presets/opencode/go/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 besides Context7: optional Figma for ad-hoc design context — **not** a mockup-review pipeline (this preset never schedules `mockup-reviewer`).
+- Do **not** require Storybook, Playwright, or Chrome DevTools MCP.
+- Observability and ticket overlays still apply when present.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept.

package/presets/opencode/go/rules/messaging-adapters.md

@@ -0,0 +1,15 @@
+
+# Messaging adapters
+
+- **Publisher** (driven): implements outbound port; serializes domain events / integration events.
+- **Consumer** (driving): deserializes → calls use case / inbound port; ack/nack policy here.
+- Idempotency keys and retry/DLQ are adapter concerns; document at-least-once assumptions.
+- Do not put broker client types in domain or application signatures.
+
+## Event shapes
+
+- Prefer explicit event structs in application or a small `events` package used by ports — map to wire format in the adapter.
+
+## Tests
+
+- Unit-test mapping with fakes; integration against embedded/broker test duals when the repo has them.

package/presets/opencode/go/rules/module-public-api.md

@@ -0,0 +1,16 @@
+
+# Module public API
+
+- Anything under `pkg/` is a compatibility surface — change carefully; prefer additive APIs.
+- Service-private code stays in `internal/`.
+- Do not import another module's `internal/` (compiler enforces for separate modules).
+- Document breaking Go API changes in CHANGELOG when the repo publishes libraries.
+
+## go.mod
+
+- Module path and Go version are SoT for toolchain.
+- Prefer minimal direct deps; pin via `go.mod` / `go.sum`.
+
+## Cross-feature
+
+- Inside one module, features communicate via application ports or small `pkg` facades — not by importing sibling feature adapter packages.

package/presets/opencode/go/rules/persistence-adapters.md

@@ -0,0 +1,24 @@
+# Persistence adapters
+
+- Implement outbound repository ports from application.
+- Use **parameterized** queries; map rows → domain entities **inside** the adapter.
+- Transactions: expose via port (`Transactional`, `UnitOfWork`) implemented here — use cases call the port, not `*sql.Tx` directly.
+- Migrations live with infra (separate package/dir) — not in domain or application.
+
+## Mapping
+
+- Persistence models (db tags) stay private to the adapter package when possible.
+- Nullability, zero values, and DB defaults convert to domain values explicitly (no silent zero-value domain objects).
+- Port methods return domain/application errors — never leak driver-specific types through the port.
+
+## Forbidden
+
+- Importing persistence from domain or leaking `*sql.DB` / ORM handles through port APIs.
+- Building SQL strings in use cases or handlers.
+- Returning scan structs / `sql.Null*` types across the port boundary.
+
+## Tests
+
+- Integration: repository **contract** round-trip (save → load → error/not-found) against testcontainers / repo-standard test DB.
+- Unit-test mappers with fixtures; do **not** substitute `httptest` for a repository contract.
+- Agents: `integration-test-{planner,generator,healer}` + skill `integration-testing`; then `post-change-test`.

package/presets/opencode/go/rules/ports-interfaces.md

@@ -0,0 +1,26 @@
+
+# Ports (interfaces)
+
+## Outbound (driven)
+
+- Repository, cache, publisher, clock, ID generator, external client — defined by **application**.
+- Signatures use **domain** types (or small application DTOs), never ORM models.
+- Keep interfaces small (ISP); prefer role interfaces over god-repos.
+- Accept `context.Context` as the first parameter when the call may block or cancel.
+
+## Inbound (driving)
+
+- Optional interface wrapping use cases for multiple drivers (HTTP + gRPC + CLI).
+- Drivers depend on inbound ports / use-case APIs — not on each other.
+- Prefer a concrete use-case struct when only one driver exists; extract an interface when a second driver appears.
+
+## Naming
+
+- `SaveOrder`, `FindOrderByID`, `PublishOrderPlaced` — verb-oriented.
+- Implementation types live in adapters (`PostgresOrderRepository`), not beside the interface in domain.
+
+## Anti-patterns
+
+- Ports returning `map[string]any` or `json.RawMessage` without need.
+- Putting port interfaces inside adapter packages (wrong owner).
+- Leakage of SQL/`driver.Valuer` types through port method signatures.

package/presets/opencode/go/rules/post-change-test.md

@@ -0,0 +1,22 @@
+
+# Post-change test (requestable; must after Go edits)
+
+After changing `*.go` / `go.mod` in a consumer repo:
+
+1. `go test ./...` (or scoped packages touched).
+2. `go vet ./...`.
+3. If present: `golangci-lint run` and/or `staticcheck ./...` per repo docs.
+4. Optional: `go test ./... -race` for concurrency-sensitive changes (`go-tooling.md`).
+
+## Scope hints
+
+- Prefer package-scoped tests while iterating; run `./...` before claiming the task done.
+- If only `*_test.go` helpers changed, still run the package under test.
+- Module/`go.mod` changes: run `go test ./...` after `go mod tidy`.
+
+## Agent requirement
+
+- Do not claim completion without running the applicable gate (or noting why CI-only).
+- Pipeline `build-verifier` enforces the same checklist.
+- Record failing command output in the task artifact when the gate fails.
+- Skip only when the change is docs/config with no `*.go` / `go.mod` impact — state that explicitly.

package/presets/opencode/go/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/opencode/go/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/opencode/go/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