@bonesofspring/ai-rules 0.2.25 → 0.2.26

package/presets/opencode/java/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` ≤ 4 (4th slot reserved for `ai-local-overlay`); Claude session-start exactly 3; 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/opencode/java/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` | **≤ 4** |
+| Claude | rules **without** `paths:` | **exactly 3** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **≤ 4** |
+
+**Cursor 4th slot is reserved for `ai-local-overlay`** (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` and revert to ≤3.
+
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
+
+Session-start body budget:
+- Claude trio: ≤140 lines total (stretch ≤120).
+- Cursor 4-set: ≤170 lines total (4 rules including `ai-local-overlay`).
+- Mavis / OpenCode: ≤4 root-entry rule files; combined root `AGENTS.md` + platform entry ≤170 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
+
+## 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 exceeds 4, Claude session-start count exceeds 3 (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/opencode/java/rules/preset-twin-sync.md

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

package/presets/opencode/java/rules/product-specs-authoring.md

@@ -0,0 +1,112 @@
+<!-- shared-core: architecture/product-specs-authoring.md -->
+
+# Product specs authoring
+
+Load when **Generate** or **Bootstrap** is requested (`/spec-start`, router `spec-gen`, brief AC, or analyst author mode). Discovery-only work stays on **`product-specs`**.
+
+**Optional prefix:** when the user or AC asks **research-before-spec**, load skill **`spec-discovery`** first (subset of methods; **claim-ledger** mandatory). Not the default `/task` consume path and not a new pipeline step.
+
+## Modes
+
+1. **Consume** — default; never invent INDEX/specs (see `product-specs`).
+2. **Generate** — create/update page/feature specs + INDEX rows from brief AC, user intent, Figma, or code archaeology. Inventing *product* behavior is forbidden without a stated source (AC / user / UI copy / code-observed behavior labeled `status: draft` or `inferred`).
+3. **Bootstrap** — create `INDEX.md` + `_templates/` copies + first domain spec under greenfield policy.
+
+## Greenfield policy
+
+Agents **may** create INDEX + first specs **only when** one of:
+
+1. User runs `/spec-start` or explicitly asks to bootstrap `docs/specs`.
+2. Brief/AC includes generation or bootstrap language.
+3. Router detects `spec-gen` intent.
+
+Otherwise: missing INDEX → optional tree; do **not** invent INDEX merely because discovery loaded.
+
+## Conflict precedence
+
+1. **Human gate** decision (approved brief/spec edits).
+2. **Current task `brief.md` AC** — if AC contradicts an existing spec, analyst must reconcile (update spec as `draft` or revise AC) before developer; no silent contradiction.
+3. **Approved `docs/specs/**`** — behavior SoT for feature-developer once gate passed.
+4. **Code / `.ai/context`** — discovery evidence only; never override approved spec without gate.
+
+Label inferred-from-code lines with `status: draft` until human promotes.
+
+## INDEX.md contract (v1)
+
+| Column | Required | Notes |
+|--------|----------|-------|
+| `id` | yes | Stable kebab/id matching frontmatter `id` |
+| `type` | yes | `page` \| `feature` |
+| `domain` | yes | Domain folder under `docs/specs/domains/<domain>/` |
+| `title` | yes | Human label |
+| `path` | yes | Repo-relative path to markdown file |
+| `routes` | no | Summary; may duplicate frontmatter |
+| `aliases` | no | Comma-separated PageName / deep-link aliases |
+| `status` | no | `draft` \| `active` \| `deprecated` |
+
+Layout: `docs/specs/domains/<domain>/<id>.md` (page) and optional `docs/specs/domains/<domain>/feature.md`. Adding/renaming/removing a linked file **must** update INDEX in the **same change set**.
+
+## Frontmatter v1
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `id` | string | yes | Unique; matches INDEX |
+| `type` | enum `page` \| `feature` | yes | Backend/MCP: prefer `feature` |
+| `domain` | string | yes | |
+| `routes` | string[] | yes (may be `[]`) | Web: URL paths; mobile: deep links/screens; backend: HTTP paths; mcp-ts: tool names |
+| `ui` | string[] | yes (may be `[]`) | Component/screen refs; empty on backend/mcp |
+| `store` | string[] | yes (may be `[]`) | Slice/module refs; empty when N/A |
+| `api` | string[] | yes (may be `[]`) | Services/ports/tools |
+| `aliases` | string[] | yes (may be `[]`) | |
+| `e2e` | string[] | yes (may be `[]`) | Stack-appropriate test paths |
+| `status` | enum | no | default `draft` on agent generate |
+| `owners` | string[] | no | |
+| `related` | string[] | no | Spec ids or paths |
+
+Arrays are **always present** (empty allowed). Do not omit keys for N/A stacks.
+
+## Body headings (minimum)
+
+**`page` required:** Overview; Entry / actors; Primary flows; States (loading / empty / error / success as applicable — mark N/A explicitly); Acceptance criteria (links or bullets to brief AC / product source).
+
+**`page` optional:** Analytics, Accessibility, Edge cases, Related specs.
+
+**`feature` required:** Overview; Shared behavior / constraints; Related pages (links).
+
+**`feature` optional:** Cross-cutting states, Analytics.
+
+Compliant = valid frontmatter + all required headings present (non-empty prose or explicit `N/A`) + INDEX row with resolvable `path`.
+
+## Templates & assets
+
+**Package SoT:** `packages/ai-rules/presets/_shared/assets/docs-specs/` (`INDEX.md` stub, `_templates/page.md`, `_templates/feature.md`; `schemas/frontmatter-v1.schema.json` is a documentation artifact — the checker does not evaluate it).
+
+**CLI `init`:** when consumer `docs/specs/` is **absent**, copy INDEX stub + `_templates/*` (idempotent; **never overwrite** existing INDEX). When the tree already exists, skip seed entirely.
+
+**Skill fallback:** if consumer `_templates/` missing during author mode, copy from package/skill assets before authoring.
+
+## Author roles
+
+| Role | Responsibility |
+|------|----------------|
+| **task-analyst** | Primary author (Generate + Bootstrap); INDEX bootstrap; brief **Related specs** + **Spec gaps / generation requested**; loads this stem + skill `spec-authoring`; optional skill `spec-discovery` when research-before-spec |
+| **tech-writer** | Post-delivery sync where present; never invent product behavior without AC/code source |
+| **feature-developer** | Consumes approved specs as SoT; mechanical INDEX/frontmatter fixes only on renames |
+| **mcp-ts** | No tech-writer — author + post-sync via **task-analyst** only |
+
+## Self-check before handoff (soft block)
+
+Block handoff via `open_questions` until fixed:
+
+- [ ] Required frontmatter keys present; arrays always present (may be `[]`)
+- [ ] Required body headings present (or explicit `N/A`)
+- [ ] INDEX row added/updated with resolvable `path` in the **same change set**
+- [ ] Sources cited; invented product behavior absent (or labeled `draft` / `inferred`)
+- [ ] Conflict with brief AC reconciled or flagged
+
+## Related
+
+- `product-specs` — discovery / consume
+- Skill `spec-authoring` — procedural checklist
+- Skill `spec-discovery` — opt-in research-before-spec (not default)
+- Optional consumer script `scripts/check-product-specs.sh` (ships in the npm package; WARN default; `--strict` FAIL). Bash checks INDEX links, required frontmatter keys, and body headings — it does **not** evaluate `frontmatter-v1.schema.json`

package/presets/opencode/java/rules/product-specs.md

@@ -0,0 +1,56 @@
+<!-- shared-core: architecture/product-specs.md -->
+
+# Product specs (docs/specs)
+
+Product page/feature **behavior** specs live under the consumer repo `docs/specs/**`. This stem covers **discovery and presence** — not layer implementation order (see `feature-delivery-workflow`) and not code-structure mirroring (see `reference-features`).
+
+**Authoring** (Generate / Bootstrap modes, INDEX/frontmatter v1, body checklist, greenfield, conflict precedence) → load **`product-specs-authoring`** when generation is requested (`/spec-start`, brief AC, or router `spec-gen`).
+
+**Pipeline `specMode`:** `consume` (this stem) · `generate` (authoring stem) · `none` (spike/research — skip INDEX row requirement; do not invent a dummy INDEX). Primary field: `brief.md` `## Spec mode`; optional `pipeline.json` `specMode`.
+
+## Modes (summary)
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Consume** (default) | INDEX exists or globs hit `docs/specs/**` without generate intent | Discover via INDEX; soft-fail on miss; **never invent** INDEX/specs |
+| **Generate** | Explicit generate intent / AC / `/spec-start` with existing tree | Create/update page/feature specs + INDEX from stated sources |
+| **Bootstrap** | Explicit bootstrap / `/spec-start` when tree absent | Create INDEX + templates + first domain spec |
+| **None** (`specMode: none`) | Spike / research / preset-only | Skip INDEX requirement and author mode; no dummy INDEX row |
+
+Greenfield: agents may create INDEX/specs **only** on explicit intent, AC, or `/spec-start`. Missing INDEX alone does **not** authorize inventing the tree.
+
+## Presence policy
+
+- If `specMode` is **`none`** → do **not** require an INDEX row; continue from brief/AC. Do not invent INDEX.
+- If `docs/specs/INDEX.md` is **missing** → the tree is **optional** (greenfield OK for *consume*). Continue with code/brief discovery; do not invent an INDEX solely because this stem loaded.
+- If INDEX **exists** and `specMode` is not `none` → it is the **required discovery path** for work that touches a listed page, feature, route, or alias.
+
+## Discovery algorithm
+
+1. Always start at `docs/specs/INDEX.md` when present (skip when `specMode: none`).
+2. Resolve the entry by: route, stable `id`, PageName / alias, or domain folder.
+3. Read the **linked page** spec and, when INDEX or page Related links it, the optional domain `feature.md`. Do **not** dump the whole `docs/specs/**` tree into the prompt — locator = those linked files.
+
+## Miss policy (INDEX present, row or file missing)
+
+- Record the gap in `open_questions` / handoff gaps.
+- Fall back to code discovery and consumer `.ai/context/**` when present.
+- **Do not invent** product behavior, states, interactions, or contracts.
+- Hard-fail / block only when the task’s acceptance criteria explicitly require a named spec that is absent (human/gate decision).
+
+## Authoring pointer
+
+Same-changeset INDEX updates, frontmatter v1, required body headings, templates, and conflict precedence live in **`product-specs-authoring`**. Do not paste the full checklist here.
+
+## Non-goals
+
+- Not a replacement for `.ai/context/**` (external AI Code Review glossary) or `reference-features` (file-layout mirror).
+- Not Tessl / an external host as primary SoT.
+- No stack filesystem path recipes in this core body — path examples belong only in adapter **Stack notes**.
+
+## Related
+
+- `product-specs-authoring` — generation modes, contracts, self-check.
+- Skill `spec-discovery` — opt-in research-before-spec (author mode only; not default consume).
+- `reference-features` — code structure mirror (how to layout files), not product behavior.
+- Consumer `.ai/context/**` when present — review/domain glossary; cross-link, do not replace.

package/presets/opencode/java/rules/reference-features.md

@@ -0,0 +1,45 @@
+<!-- shared-core: architecture/reference-features.template.md -->
+
+# Reference features
+
+Before implementing, find a feature of the same type and **mirror its structure**; do not invent a new file organization.
+
+## Reference table
+
+Replace placeholders with **real** paths after `ai-rules init` / team agreement:
+
+| Layer | Reference | What to copy |
+|-------|-----------|--------------|
+| UI / Presentation | **TBD** | components, styles/data helpers, barrel |
+| State / ViewModel | **TBD** | slice/VM, selectors, types |
+| API / Data | **TBD** | service/repo, mappers, barrel |
+| Domain / Types | **TBD** | domain types, public export |
+| Unit tests | **TBD** | `*.spec` / XCTest naming |
+| E2E / UI tests | **TBD** | cases/plans, page objects / accessibility IDs |
+
+## How to use
+
+1. Identify affected layers from `decomposition.md` or the task.
+2. Open the reference from the table (after paths are filled).
+3. Mirror naming, file order, import patterns, and tests.
+4. If there is no reference — pick the **closest** existing feature of the same layer and record the choice in the handoff.
+
+## Living conventions
+
+After init the team maintains **local** gotchas, patterns, and decisions in a consumer-owned store (not in shared core and not only in root `AGENTS.md`):
+
+| Section | What to record |
+|---------|----------------|
+| Gotchas | Recurring traps, fragile spots, “do not do X in this repo” |
+| Patterns | Local patterns beyond the reference table |
+| Decisions | Short ADR links / product decisions that affect code |
+
+Path pointer and stack tables — in the preset adapter (`.ai.local/conventions.md`). The file is **not** always-on.
+
+## Related rules
+
+- `code-quality-and-refactoring` — repeat patterns, no deep-import.
+- `feature-delivery-workflow` — layer order.
+- skill `feature-delivery` — end-to-end scenario.
+
+> Concrete path tables, globs, and dogfood checklists live in the stack adapter **Stack notes**.

package/presets/opencode/java/rules/security-java.md

@@ -0,0 +1,21 @@
+
+# Security (Java)
+
+- Secrets from env / secret manager — never commit keys, tokens, or `.env` with credentials; do not log passwords or bearer tokens.
+- Validate and canonicalize untrusted input at the driving adapter edge (Bean Validation / explicit checks).
+- Prefer prepared statements / parameterized queries / JPA bind parameters in persistence adapters.
+- TLS and secure cookie/header defaults when exposing HTTP.
+- AuthN/AuthZ in filters, Spring Security config, or driving adapters; pass identity into use cases as a domain value (user ID / claims), **not** raw headers or `SecurityContext` types.
+- Minimize PII in logs; redact where needed.
+
+## Spring Security (pointer only)
+
+- When the repo uses Spring Security: keep filter chains and `SecurityFilterChain` beans in configuration / security adapters — **not** in domain.
+- Do not invent a full security architecture in this rule; follow existing `SecurityConfig` patterns and repo docs.
+- Method security (`@PreAuthorize`) belongs at application/adapter edges already using it — do not sprinkle onto domain entities.
+
+## Config
+
+- Distinguish public vs secret config fields in types (`@ConfigurationProperties` / plain records).
+- Fail closed when auth is misconfigured in production profiles.
+- Static analysis / secret scanners: run only if the repo/CI already wires them.

package/presets/opencode/java/rules/technical-retro.md

@@ -0,0 +1,11 @@
+<!-- shared-core: review/technical-retro.md -->
+
+# Technical retro — rule alias
+
+Full scenario (including the **“Agent work”** block for a slug from team tasks) lives in the slash command:
+
+**`commands/technical-retro.md`** → `/technical-retro`
+
+When a task has `metrics.json`, use the local aggregation script and state the cohort, sample size, incomplete artifacts, attribution confidence, active attempt duration, and human-gate wait separately. Do not score malformed artifacts or gate wait as agent work.
+
+Use this rule only if the command is unavailable. Do not duplicate the command contents in the response — follow the command file and skill `technical-retro`.

package/presets/opencode/java/rules/tests-e2e.md

@@ -0,0 +1,15 @@
+
+# E2E / HTTP smoke (optional)
+
+> Prefer **`tests-integration`** + `integration-test-*` for adapter contracts. E2E smoke is optional breadth — do not build a browser suite.
+
+- Black-box against a running server (`@SpringBootTest` + Testcontainers with full composition root, or localhost in CI).
+- Cover critical paths only; prefer integration + unit for breadth.
+- REST Assured / WebTestClient are optional HTTP smoke tools when already in the repo — not a mandated framework.
+- Stable test data; avoid depending on wall-clock flakiness.
+- Do **not** use browser/Playwright/XCUITest tooling in this preset.
+
+## Placement
+
+- `e2e/` package or `*E2ETest.java` / `*SmokeTest.java` under `src/test/java` if the repo separates smoke jobs.
+- Keep Failsafe/Gradle smoke tags honest — do not mark unit tests as e2e.

package/presets/opencode/java/rules/tests-integration.md

@@ -0,0 +1,19 @@
+
+# Integration tests
+
+- Exercise driven adapters against real infra doubles (**Testcontainers**, docker compose test DB, WireMock, etc.).
+- Or exercise HTTP adapter with `MockMvc` / WebTestClient / Spring Boot **test slices** + wired use case + fake/real ports — still no full prod cluster required.
+- Use Surefire/Failsafe (or Gradle test filters) if the repo separates CI unit vs integration jobs.
+- Keep fixtures deterministic; clean up data between tests.
+- Prefer testing through the **port implementation** (save/load roundtrip) over asserting on private JPA internals.
+
+## Scope
+
+- Contract of a port implementation (repo save/load, outbound client mapping).
+- Not a substitute for domain unit tests.
+- Full `@SpringBootTest` only when slices cannot prove the contract.
+
+## Agents
+
+- Planning/generation: `integration-test-{planner,generator,healer}` + skill `integration-testing` (Phase C surface).
+- Prefer integration-test agents over inventing browser e2e for backend contracts.

package/presets/opencode/java/rules/tests-unit.md

@@ -0,0 +1,26 @@
+
+# Unit tests
+
+- Prefer **JUnit 5**; clear arrange/act/assert (or Given/When/Then).
+- Domain and application: mock/fake **ports** only — no real DB/network.
+- Prefer fakes over heavy mocking when simple; **Mockito** is optional when the repo already uses it.
+- Prefer **AssertJ** fluent assertions when already on the classpath; otherwise JUnit assertions are fine.
+- Skip integration/e2e files matching `*IT.java`, `*IntegrationTest.java`, `*E2ETest.java`, `*SmokeTest.java`, or dirs `integration/`, `e2e/` — those use other rules.
+
+## Scope
+
+- Domain factories/invariants; application use cases with port fakes; pure mappers.
+- Adapter unit tests may use `MockMvc` + mocked use case — still no live DB.
+
+## Forbidden smells
+
+- `HttpServletRequest` / `ServerHttpRequest` / Spring MVC types in **domain** tests.
+- SQL or live HTTP in use-case unit tests.
+- Brittle tests on package-private adapter internals without need.
+- Loading a full `@SpringBootTest` for a pure domain/unit case.
+- Structural smells vocabulary (Feature Envy, Message Chains, …): see requestable `design-guidance` — do not duplicate the catalog here.
+
+## Naming
+
+- `UseCaseDoXTest` / `EntityInvariantTest` (or `*Tests` if the repo already uses that suffix).
+- Match Surefire patterns the CI already uses.

package/presets/opencode/java/skills/README.md

@@ -0,0 +1,5 @@
+# Skills (preset java)
+
+10 skills: `feature-delivery`, `spec-authoring`, `spec-discovery`, `unit-testing`, `integration-testing`, `ci-investigation`, `debug-investigation`, `code-review`, `technical-retro`, `write-adr`.
+
+No `playwright-e2e` / `xcuitest-e2e` / `react-performance`.

package/presets/opencode/java/skills/ci-investigation/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: ci-investigation
+description: Investigates failing CI checks on PRs and branches — mvn/gradle test, compiler, lint, integration, preset-structure — with local reproduction and minimal fixes. Use when CI is red or for ci-fix pipeline tasks.
+---
+
+# CI investigation (Java)
+
+1. Identify job + log excerpt.
+2. Reproduce locally with the same commands.
+3. Minimal fix; for ai-rules preset PRs run `yarn check:preset-structure`.
+4. Do not treat Playwright/xcodebuild/`lint:js` as default Java gates.
+
+## MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+

package/presets/opencode/java/skills/code-review/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: code-review
+description: Reviews pull requests and branch diffs for Java hexagonal services using architecture, ports/adapters, networking, and testing standards. Use when the user asks for review or when code-reviewer runs.
+---
+
+# Code review (Java)
+
+1. Diff-first; load `code-review-mr.md` + hexagonal rules.
+2. Check layer leaks, port ownership, composition root purity, tests, security-sensitive bits.
+3. **Reuse lens:** flag new helpers that duplicate existing packages/utilities; prefer shared adapters over copy-paste.
+4. **Efficiency lens:** unnecessary allocations, N+1 I/O, sequential work that should be concurrent, hot-path bloat, missing context cancellation.
+5. Write `review.md` using the output contract below.
+
+## Output
+
+- Each finding: **`path:line`** — problem — impact — concrete fix direction.
+- Severity: **`blocker` | `important` | `nit`** (list blocker → nit).
+- End with a verdict line: **`Safe to merge | needs changes | reject`**.
+- Map agent status: Safe to merge → `completed`; needs changes / reject → `changes_requested`.
+
+Never require iOS/Next-only gates (XCUITest, Playwright, `lint:js`).
+
+## Receiving review feedback
+
+<!-- shared-core: review/receiving-code-review.md -->
+
+When **implementing** review comments (not when issuing them): verify each item against the codebase before changing code; do not perform agreement (`You're absolutely right!`). Unclear items → ask, do not guess.
+
+## Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+For agent team tasks, write the review artifact and upsert the owned terminal receipt (`completed` or `changes_requested`); do not mutate `status.json`.

package/presets/opencode/java/skills/debug-investigation/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: debug-investigation
+description: Investigates bugs, failing tests, and unexpected behavior in Java services with runtime evidence before applying minimal fixes. Use for bugfix tasks, debugger agent runs, or regressions.
+---
+
+<!-- shared-core: quality/debug-investigation.md -->
+
+# Debug investigation
+
+Stack-agnostic root-cause loop. Consumed by skill `debug-investigation` and agent `debugger`. Platform paths, MCP, and stack commands belong in adapter **Stack notes**.
+
+## When
+
+Any bug, test failure, build failure, or unexpected behavior — **before** proposing a fix.
+
+## Phases (in order)
+
+1. **Evidence** — reproduce, or collect the closest evidence (error output, failing test, logs, user steps).
+2. **Isolate** — expected vs actual in one sentence; smallest relevant slice of the codebase.
+3. **Root cause** — name the cause before editing. One hypothesis at a time; do not stack speculative fixes.
+4. **Minimal fix + verify** — smallest change that preserves architecture and public contracts. Add a regression test when the behavior is user-facing or likely to recur. Re-run the **failing** check first, then the relevant lint/type/test slice.
+
+## 3-fix architecture gate
+
+If **three** fix attempts fail, or the same symptom returns after two supposed fixes: **STOP**. Do not attempt fix #4. Escalate — the design is likely wrong (human partner or `solution-architect`). Chasing symptoms is the failure mode.
+
+## Do not
+
+- Broad refactor during a bugfix.
+- Fix only where the error surfaces if invalid data originates elsewhere.
+- Claim `fixApplied: true` without re-running the failing check (see `quality/verification-before-completion.md`).
+
+## Stack notes
+
+### Stack process
+
+1. Capture failing `mvn test` / `./gradlew test` / logs / stack traces.
+2. Hypothesize layer (domain vs adapter vs wiring).
+3. Minimal fix + regression test when appropriate.
+4. Document in `debug-report.md`.
+
+### MCP usage
+
+Load requestable rule `mcp-usage` when verifying third-party library APIs (Context7) or when a local overlay MCP is present and the task fits. Discover tools at runtime; do not invent schemas. Overlay absence is not a blocker unless the user required that MCP as source of truth.
+
+If a Sentry/Datadog (or similar) MCP is ready and the task is a production error, event, or trace, use it. Do not invent telemetry.
+
+
+### Design guidance
+
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.