@bonesofspring/ai-rules 0.2.26 → 0.2.27

package/presets/opencode/go/rules/code-review-mr.md

@@ -38,3 +38,10 @@ Procedure details live in skill `code-review`. Required shape:
 - Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
 - Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
 - End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.
+
+## Stack notes
+
+- Hexagonal boundaries: `architecture-boundaries`, `domain-layer`, ports vs adapters.
+- HTTP/persistence mapping only at edges; composition root has no business logic.
+- Tests: `tests-unit`, `tests-integration`; post-change: `post-change-test` / `go-tooling`.
+- Never require Playwright, XCUITest, `lint:js`, or `xcodebuild` for Go MRs.

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

@@ -97,3 +97,8 @@ Do not introduce a second stem (`refactoring-smells` / `design-patterns-for-agen
 - 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/mcp-usage.md

@@ -84,3 +84,10 @@ Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plu
 - 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/preset-layering.md

@@ -9,7 +9,7 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | 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** |
+| **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

package/presets/opencode/go/rules/preset-pr-checklist.md

@@ -12,7 +12,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **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
+- [ ] **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`.

package/presets/opencode/go/rules/preset-token-budget.md

@@ -8,19 +8,19 @@ Invariants for rule loading in an **installed** preset (consumer app).
 
 | 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 | `alwaysApply: true` | **3–5** |
+| Claude | rules **without** `paths:` | **3–5** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
 
-**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.
+Caps are **aligned** across platforms: minimum **3** (base invariants), maximum **5**. Slots beyond the base invariants are reserved for `ai-local-overlay` (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` / Claude `paths:`, or a non-root load mode on Mavis / OpenCode.
 
-**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). Body budget sums only the intended session-start rules (≤5).
 
 Session-start body budget:
-- Claude 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`.
+- Claude session-start: ≤200 lines total (stretch ≤170).
+- Cursor always-on: ≤200 lines total (stretch ≤170).
+- Mavis / OpenCode: ≤5 root-entry rule files; combined root `AGENTS.md` + platform entry ≤200 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 
@@ -36,4 +36,4 @@ Orchestrator, feature-delivery, code-review, post-change gates, domain globs —
 
 ## 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.
+build-verifier **FAIL** if Cursor `alwaysApply` count or Claude session-start count is outside **3–5** (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

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

@@ -110,3 +110,9 @@ Block handoff via `open_questions` until fixed:
 - 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`
+
+## Stack notes
+
+- Author via skill `spec-authoring`; prefer `type: feature`; `ui`/`store` usually `[]`.
+- **Forbidden:** web UI / Playwright path recipes.
+- Requestable — not always-on / session-start.

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

@@ -54,3 +54,9 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 - 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.
+
+## Stack notes
+
+- `routes`: HTTP paths. `ui` / `store`: usually `[]` (or handler labels). `e2e`: integration/contract test paths.
+- **Forbidden:** requiring `app/src/ui`, Playwright paths, or Next lint recipes.
+- Requestable / `docs/specs/**` globs — not always-on / session-start.

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

@@ -1,6 +1,6 @@
 ---
 name: ci-investigation
-description: Investigates failing CI checks on PRs and branches — go test, vet, lint, integration, preset-structure — with local reproduction and minimal fixes. Use when CI is red or for ci-fix pipeline tasks.
+description: "Investigates failing CI checks on PRs and branches — go test, vet, lint, integration, preset-structure — with local reproduction and minimal fixes. Use when CI is red or for ci-fix pipeline tasks."
 ---
 
 # CI investigation (Go)

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

@@ -1,6 +1,6 @@
 ---
 name: code-review
-description: Reviews pull requests and branch diffs for Go hexagonal services using architecture, ports/adapters, networking, and testing standards. Use when the user asks for review or when code-reviewer runs.
+description: "Reviews pull requests and branch diffs for Go hexagonal services using architecture, ports/adapters, networking, and testing standards. Use when the user asks for review or when code-reviewer runs."
 ---
 
 # Code review (Go)

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

@@ -1,6 +1,6 @@
 ---
 name: debug-investigation
-description: Investigates bugs, failing tests, and unexpected behavior in Go services with runtime evidence before applying minimal fixes. Use for bugfix tasks, debugger agent runs, or regressions.
+description: "Investigates bugs, failing tests, and unexpected behavior in Go services with runtime evidence before applying minimal fixes. Use for bugfix tasks, debugger agent runs, or regressions."
 ---
 
 <!-- shared-core: quality/debug-investigation.md -->

package/presets/opencode/go/skills/feature-delivery/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: feature-delivery
-description: Delivers Go hexagonal backend features end-to-end across domain, application/ports, adapters, composition root, tests, and post-change-test validation. Use when implementing or extending a feature, especially through /task or feature-developer.
+description: "Delivers Go hexagonal backend features end-to-end across domain, application/ports, adapters, composition root, tests, and post-change-test validation. Use when implementing or extending a feature, especially through /task or feature-developer."
 ---
 
 # Feature Delivery (Go hexagonal)

package/presets/opencode/go/skills/integration-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: integration-testing
-description: Plans, generates, and heals Go integration and adapter contract tests (httptest, testcontainers). Use for integration-test-* agents or adapter/e2e coverage.
+description: "Plans, generates, and heals Go integration and adapter contract tests (httptest, testcontainers). Use for integration-test-* agents or adapter/e2e coverage."
 ---
 
 # Integration testing (Go)

package/presets/opencode/go/skills/spec-authoring/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-authoring
-description: Author or bootstrap consumer docs/specs (INDEX, page/feature templates, frontmatter v1). Use with task-analyst author mode, /spec-start, or when brief AC requests Generate/Bootstrap.
+description: "Author or bootstrap consumer docs/specs (INDEX, page/feature templates, frontmatter v1). Use with task-analyst author mode, /spec-start, or when brief AC requests Generate/Bootstrap."
 ---
 
 # Spec authoring

package/presets/opencode/go/skills/spec-discovery/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-discovery
-description: Opt-in research-before-spec for task-analyst author mode. 11 named methods plus a mandatory claim ledger. Use when the user or AC asks discovery before generating docs/specs — not default /task consume.
+description: "Opt-in research-before-spec for task-analyst author mode. 11 named methods plus a mandatory claim ledger. Use when the user or AC asks discovery before generating docs/specs — not default /task consume."
 ---
 
 # Spec discovery

package/presets/opencode/go/skills/technical-retro/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-retro
-description: Facilitates technical retrospectives for tasks, sprints, incidents, releases, and agent-team pipelines. Use when the user asks for retro, postmortem, process review, or action items after delivery.
+description: "Facilitates technical retrospectives for tasks, sprints, incidents, releases, and agent-team pipelines. Use when the user asks for retro, postmortem, process review, or action items after delivery."
 ---
 
 # Technical Retro

package/presets/opencode/go/skills/unit-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: unit-testing
-description: Plans, generates, and heals table-driven Go unit tests for domain, use cases, and mappers using *_test.go and tests-unit rules. Use for unit-test planning, generation, or healing.
+description: "Plans, generates, and heals table-driven Go unit tests for domain, use cases, and mappers using *_test.go and tests-unit rules. Use for unit-test planning, generation, or healing."
 ---
 
 # Unit testing (Go)

package/presets/opencode/go/skills/write-adr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: write-adr
-description: Author an Architecture Decision Record (ADR) with Context, Decision, Consequences, and Links. Use when capturing a durable technical choice for the team.
+description: "Author an Architecture Decision Record (ADR) with Context, Decision, Consequences, and Links. Use when capturing a durable technical choice for the team."
 ---
 
 # Write ADR

package/presets/opencode/ios-swift/adapter-map.json

@@ -3,7 +3,7 @@
   "platform": "opencode",
   "stack": "ios-swift",
   "semanticSource": "cursor/ios-swift",
-  "sourceRevision": "eea10771b90f89ba28af96ae36be2261e6952b757e532a1fb93bdd4d2bd83540",
+  "sourceRevision": "c9bca6893eaac1a4f71e0211d8dfa8b2967938027af0e7945e06410bfffa522d",
   "entries": [
     {
       "source": "AGENTS.md",

package/presets/opencode/ios-swift/agents/build-verifier.md

@@ -41,15 +41,15 @@ When validating **ios-swift preset** changes (or `scope: preset-structure-valida
 
 ### FAIL (all stacks + ios-specific)
 
-1. **Token budget:** Cursor `alwaysApply: true` count ≤ **3**; Claude rules without `paths:` === **3** (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be `alwaysApply: true`.
+1. **Token budget:** Cursor `alwaysApply: true` count 3–5; Claude rules without `paths:` 3–5 (**exclude `**/README.md`** — Option A). Meta `preset-*` rules must **not** be `alwaysApply: true`.
 2. **Chain fork check:** `hooks/chain-team-phases.sh` must **not** be byte-identical to `presets/cursor/next/hooks/chain-team-phases.sh` (Claude: vs `presets/claude/next/hooks/…`).
 3. **Forbidden handoff strings** in ios-swift `chain-team-phases.sh` (Cursor + Claude): `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`, and positive yarn lint recipes (`lint:js` / `lint:css` as commands to run — negation prose alone is not enough; prefer zero occurrences). See `preset-no-cross-stack-leakage.md`.
 4. **Required handoff stems:** `AGENT_HANDOFF` must include `xcuitest-test-planner` (or generator/healer) and `build-verifier` text must mention `xcodebuild` or `post-change-build` / `xcode-tooling`.
-5. **Roster:** 21 agent stems; no `playwright-test-*` files under ios-swift `agents/`.
+5. **Roster:** 24 agent stems; no `playwright-test-*` files under ios-swift `agents/`.
 6. **Twin presence (hard):** Cursor rule change → Claude twin present **same PR** — **FAIL** if missing (next, nuxt, svelte, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel).
 7. **Mapping / README:** `claude/ios-swift/rules/README.md` mapping table present; core→stack mapping documented when `_shared` consumers exist.
 8. **shared-core consumers:** if `_shared/core/**` changed, every matching `<!-- shared-core: … -->` consumer in this PR must be updated (or intentional fork documented).
-9. **Session-start body budget:** sum of the **3** intended always-on / session-start rule bodies ≤ **140** lines (stretch ≤120); do **not** include `**/README.md` — record in report.
+9. **Session-start body budget:** sum of the intended always-on / session-start rule bodies ≤ **200** lines (stretch ≤170); do **not** include `**/README.md` — record in report.
 10. **Embed drift (hard in `check:preset-structure`):** `packages/ai-rules/scripts/check-shared-core-drift.sh` with `AI_RULES_DRIFT_FAIL=1`.
 11. **Dogfood (monorepo soft):** `packages/ai-rules/scripts/sync-dogfood-cursor.sh`; mass deletion without migration doc → risk / FAIL for maintainers.
 

package/presets/opencode/ios-swift/commands/spec-start.md

@@ -1,5 +1,5 @@
 ---
-description: Bootstrap or generate docs/specs (INDEX + page/feature) via task-analyst author mode. Optional docs-only path with human gate.
+description: "Bootstrap or generate docs/specs (INDEX + page/feature) via task-analyst author mode. Optional docs-only path with human gate."
 ---
 
 ## Invocation arguments

package/presets/opencode/ios-swift/commands/task-continue.md

@@ -1,5 +1,5 @@
 ---
-description: Continue an agent-team task after a human gate, pause, or review changes request using pipeline.json and status.json.
+description: "Continue an agent-team task after a human gate, pause, or review changes request using pipeline.json and status.json."
 ---
 
 ## Invocation arguments

package/presets/opencode/ios-swift/commands/task.md

@@ -1,5 +1,5 @@
 ---
-description: Route a natural-language task through the agent-team pipeline: task-router, pipeline.json, and the first planned specialist.
+description: "Route a natural-language task through the agent-team pipeline: task-router, pipeline.json, and the first planned specialist."
 ---
 
 ## Invocation arguments

package/presets/opencode/ios-swift/commands/technical-retro.md

@@ -1,5 +1,5 @@
 ---
-description: Facilitate a technical retrospective for a period, incident, release, or completed agent-team task slug.
+description: "Facilitate a technical retrospective for a period, incident, release, or completed agent-team task slug."
 ---
 
 ## Invocation arguments

package/presets/opencode/ios-swift/hooks/chain-team-phases.sh

@@ -42,7 +42,10 @@ try {
 }
 
 const slug = active.slug;
-if (!slug) {
+// Reject non-kebab / traversal slugs: the runtime writes status.json and
+// metrics.json under tasks/<slug>, so an unchecked slug could escape the tree.
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+if (typeof slug !== 'string' || slug.length > 48 || !SLUG_RE.test(slug)) {
   process.stdout.write('{}');
   process.exit(0);
 }
@@ -69,6 +72,9 @@ function waitForMetricsLock() {
   // and never blocked on the lock file, so two concurrent subagentStop events
   // could both acquire the lock and corrupt metrics.json. Retry EEXIST with a
   // 10 ms sleep up to 200 attempts (2 s ceiling). On any other error, throw.
+  // A lock left behind by a killed process is reclaimed once its mtime is older
+  // than STALE_LOCK_MS, so one crash cannot brick the task forever.
+  const STALE_LOCK_MS = 30000;
   for (let attempt = 0; attempt < 200; attempt += 1) {
     try {
       const fd = fs.openSync(METRICS_LOCK, 'wx');
@@ -76,6 +82,13 @@ function waitForMetricsLock() {
       return;
     } catch (error) {
       if (!error || error.code !== 'EEXIST') throw error;
+      try {
+        const lockStat = fs.statSync(METRICS_LOCK);
+        if (Date.now() - lockStat.mtimeMs > STALE_LOCK_MS) {
+          fs.unlinkSync(METRICS_LOCK);
+          continue;
+        }
+      } catch {}
       const until = Date.now() + 10;
       while (Date.now() < until) { /* 10 ms busy-wait */ }
     }
@@ -495,7 +508,10 @@ function legacyFlow() {
 
 
 if (hookInput.action === 'end_human_gate') {
-    status.awaitingHumanGate = false;
+  // Only advance when a gate was actually open. A duplicate or retried
+  // end_human_gate must be a no-op, not a silent pipeline skip.
+  const gateWasOpen = Boolean(status.activeHumanGateEventId) || status.awaitingHumanGate === true;
+  status.awaitingHumanGate = false;
   // A2 (retro §8): pin a single runId per pipeline so subsequent events don't
   // fragment the metrics ledger across multiple runId sequences. Prefer
   // metrics.json.task.runId when metrics already exist, then status.metricsRunId,
@@ -522,7 +538,7 @@ if (hookInput.action === 'end_human_gate') {
     });
     delete status.activeHumanGateEventId;
   }
-  if (hookInput.activateNext && fs.existsSync(pipelinePath)) {
+  if (gateWasOpen && hookInput.activateNext && fs.existsSync(pipelinePath)) {
     let resumePipeline = null;
     try { resumePipeline = JSON.parse(fs.readFileSync(pipelinePath, 'utf8')); } catch {}
     if (resumePipeline) {
@@ -544,6 +560,19 @@ if (hookInput.action === 'end_human_gate') {
         else out(handoffForAgent(resumeAgents[0], resumeNext.step.scope, resumeNext.step));
         process.exit(0);
       }
+      // Gate on the final step: no executable step remains. Complete the
+      // pipeline instead of leaving it in_progress forever.
+      status.state = 'completed';
+      completeTaskMetrics();
+      writeStatus({
+        pipelineIndex: resumeSteps.length,
+        phase: 'done',
+        state: 'completed',
+        currentAgent: null,
+        awaitingHumanGate: false,
+      });
+      out(`Pipeline complete for "${slug}". Run /technical-retro ${slug}.`);
+      process.exit(0);
     }
   }
   // A2 (retro §8): if gate closes the final human gate of the pipeline

package/presets/opencode/ios-swift/rules/code-quality-and-refactoring.md

@@ -14,6 +14,12 @@
 - **CUPID:** Composable; Unix philosophy (one responsibility); Predictable; Idiomatic (repo); Domain-based.
 - **Composition over inheritance;** Law of Demeter — no `a.b.c.d` chains; via public API / facade.
 
+# Over-abstraction guardrails
+
+- **No unnecessary constants:** do not hoist a one-off literal, string, or boolean into a named constant. Inline it, or use an existing token/enum when the value is meaningful and reused. Named constants are for shared, semantic, or repeated values.
+- **No invented utilities:** do not add a `utils`/helper for a single call site or a thin pass-through wrapper. Inline it or extend the existing helper; a new shared utility is justified only after the Rule of Three.
+- **Decompose over conditionals:** a unit (function, component, hook) that accumulates several branches (`if` / ternary / `switch`) should be split into smaller units with one reason to change instead of piling up conditions.
+
 # Refactoring during changes
 
 - Light refactor is OK if it reduces duplication, improves readability, and does not break public contracts.
@@ -38,3 +44,11 @@ Essentials below. Full procedural set (~17 rules) → load **`anti-sycophancy-di
 Style enforcement (formatter / linter / post-change gate) lives in the **stack toolchain** — see each adapter’s **Stack notes**.
 
 > Stack-specific lint gates, examples, and toolchain — in the preset adapter **Stack notes** section.
+
+## Stack notes
+
+- Before adding a new UI control, check DesignSystem and existing components.
+- Public API: protocols and facades between features.
+- Acceptable examples: shared mapper/validation; replace force unwrap; split an overloaded ViewModel into use cases; design tokens instead of magic numbers/colors; remove a direct View→Data dependency in favor of a protocol.
+- Post-change gate: **`post-change-build.mdc`** + `xcode-tooling.mdc` (not yarn lint).
+- Style: **SwiftLint** (+ SwiftFormat when configured) — authoritative style gate; do not duplicate linter rules in prose.

package/presets/opencode/ios-swift/rules/code-review-mr.md

@@ -38,3 +38,42 @@ Procedure details live in skill `code-review`. Required shape:
 - Rank by severity: **`blocker` | `important` | `nit`** (list blocker → nit).
 - Vague («looks risky») is not a finding — cite evidence or ask for surrounding file context.
 - End with a verdict on its own line: **`Safe to merge | needs changes | reject`**.
+
+## Stack notes
+
+On-demand rule for review flows (not always-on).
+
+- **When to apply**
+  - Requests: “review this”, “evaluate the MR/branch/diff”, “look at the changes”.
+  - Rely on the local repository: branch, `git diff`, open files.
+
+- **What the agent must check**
+  - **Architecture and layers** (`architecture-boundaries.mdc`, `ios-app-core.mdc`):
+    - View does not call APIs and does not know DTOs.
+    - ViewModel does not depend on Data implementations directly.
+    - Domain does not import SwiftUI/UIKit.
+    - Data does not pull Presentation.
+  - **Dependencies and modules**:
+    - DI via protocols; composition root in App.
+    - No deep-import between features.
+    - Files in the correct layers (`Presentation`, `Domain`, `Data`, `DesignSystem`).
+  - **Swift and concurrency** (`swift-conventions.mdc`):
+    - `@MainActor` on UI; no unjustified force unwraps.
+    - Typed errors; correct Task cancellation where needed.
+  - **UI** (`swiftui-ui.mdc`):
+    - Thin Views; Design System tokens; accessibility identifiers for testable elements.
+  - **Networking and data** (`networking-services.mdc`):
+    - DTOs separated from domain; mappers cover edge cases.
+  - **Tests**:
+    - Non-trivial logic — unit (`tests-unit.mdc`); user flows — UI (`tests-ui.mdc`).
+    - State which tests to add or update.
+
+- **Depth and format**
+  - Focus on the **MR diff**, not the whole project.
+  - Overview first (MR goal, risks), then concrete comments with file and a fix suggestion matching repo patterns.
+  - No “big refactors” without a request (`code-quality-and-refactoring.mdc`).
+
+- **Constraints**
+  - Do not invent CI/MR hosting metadata without local data.
+  - Boy scout rule within the MR.
+  - BUGBOT automated review — see root `BUGBOT.md` (Cursor).

package/presets/opencode/ios-swift/rules/design-guidance.md

@@ -97,3 +97,8 @@ Do not introduce a second stem (`refactoring-smells` / `design-patterns-for-agen
 - 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
+
+- Prefer protocol + composition over class inheritance hierarchies.
+- Suggest Adapter/Facade at Feature public API / DI boundaries — not inside Views.

package/presets/opencode/ios-swift/rules/feature-delivery-workflow.md

@@ -47,3 +47,69 @@ flowchart LR
 ## Zone → rules matrix
 
 Filled in the stack adapter: concrete globs/paths and `.mdc` / topic `.md` names.
+
+## Stack notes
+
+When the prompt or `brief.md` contains a `figma.com` URL, **mockup review** (`mockup-reviewer` / skill `mockup-review`) must complete — or the user must continue past FAIL/`BLOCKED_MCP` via `/task-continue` — **before UI implementation**. Non-UI tasks no-op this gate. When required-signal and **no** `figma.com`, **`ux-design.md`** (on the analysis manifest entry) must exist and not be `INCOMPLETE` before UI work — else **blocked**, hand back to `task-analyst`. Parallel to the mockup gate.
+
+Typical feature with data and UI. Layer details — `architecture-boundaries.mdc`, `ios-app-core.mdc`.
+
+## Checklist (work order)
+
+1. **Domain** — entities, value types, repository / use case protocols (`Features/**/Domain/**`).
+2. **Data** — DTOs (`Codable`), Domain ↔ DTO mappers, repository implementations, API client (`networking-services.mdc`).
+3. **ViewModel** — state, use case / protocol calls; DI from App; no DTOs or URLs (`state-and-viewmodels.mdc`).
+4. **View / navigation** — thin SwiftUI Views, Design System; navigation as in the repo (`swiftui-ui.mdc`).
+5. **Tests** — unit for mappers / use cases / VM (`tests-unit.mdc`); UI flows — XCUITest (`tests-ui.mdc`).
+6. **Completion** — **invoke** `post-change-build.mdc` (+ `xcode-tooling.mdc` for schemes/commands): build touched targets + lint/format per repo config. When the current WP spans **more than one** layer or module, `implementation.md` includes a **Code Map** (3–8 annotated 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 --> Repo[Repository protocol]
+  Repo --> VM[ViewModel]
+  VM --> View[SwiftUI View]
+  DataImpl[Data impl] -.-> Repo
+```
+
+## Partial scenarios
+
+| Task | Minimum |
+|------|---------|
+| API / model only | Domain + DTO + mapper + repo impl; unit for mapper. |
+| VM / logic only | Domain protocols; mocks in tests; no HTTP in View. |
+| UI only | View + existing VM/state; no DTOs. |
+| Tests only | Specs per repo convention; do not change production without need. |
+
+## Anti-patterns
+
+- DTO / `Codable` transport types in View or ViewModel.
+- `URLSession` / concrete API client in ViewModel or View.
+- Domain imports SwiftUI / UIKit.
+- Deep-import of another feature’s internal files.
+- Assembling DI inside a View.
+- **Ubiquitous language:** Domain/type names reflect the feature domain — do not mix transport/framework terms into domain without need.
+- Load `design-guidance` (rule stem) when assessing structure, smells, or pattern fit.
+- 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`.
+
+## Matrix: zone → rules
+
+| Zone | Rules |
+|------|---------|
+| `Features/**/Domain/**`, `Core/Domain/**` | `architecture-boundaries.mdc`, `ios-app-core.mdc` |
+| `Features/**/Data/**`, `**/Network*/**` | `networking-services.mdc`, `architecture-boundaries.mdc` |
+| `*ViewModel*.swift`, Presentation state | `state-and-viewmodels.mdc` |
+| `Presentation/**`, `DesignSystem/**` | `swiftui-ui.mdc`, `architecture-boundaries.mdc` |
+| `**/*.swift` (style) | `swift-conventions.mdc` |
+| `*Tests/**` | `tests-unit.mdc` |
+| `*UITests/**` | `tests-ui.mdc` |
+| After Swift edits | `post-change-build.mdc` |
+
+When adding or extending a feature, **walk the checklist** and the table rules for touched zones.
+
+## Related
+
+- Product behavior discovery: requestable **`product-specs`** (`docs/specs/INDEX.md`) — do not paste the discovery algorithm here.

package/presets/opencode/ios-swift/rules/mcp-usage.md

@@ -84,3 +84,11 @@ Policy is stack-class-specific — see adapter **Stack notes**. If a Figma **plu
 - 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
+
+- Pipeline **`mockup-reviewer`** is the only agent that reads Figma for mockup review. See `mockup-review`.
+- Shipped besides Context7: Figma (mockup-review pipeline). See `mockup-review`.
+- Do **not** require Storybook, Playwright, or Chrome DevTools MCP as handoffs or delivery gates.
+- Observability and ticket overlays still apply when present.
+- `init` **merges** `mcpServers`: preset keys update; extra local servers are kept.

package/presets/opencode/ios-swift/rules/mockup-review.md

@@ -105,3 +105,7 @@ PASS | PASS_WITH_NOTES | FAIL | BLOCKED_MCP
 ## AC coverage
 | Criterion | Status | Notes |
 ```
+
+## Stack notes
+
+Illustrative iOS size classes (not enforced pixels): compact / regular (e.g. small iPhone, large iPhone, iPad) mapped to small / medium / large.

package/presets/opencode/ios-swift/rules/preset-layering.md

@@ -9,7 +9,7 @@ Rules for **preset authors** (`packages/ai-rules/presets/**`). Not always-on in
 | 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** |
+| **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

package/presets/opencode/ios-swift/rules/preset-pr-checklist.md

@@ -12,7 +12,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **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
+- [ ] **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`.

package/presets/opencode/ios-swift/rules/preset-token-budget.md

@@ -8,19 +8,19 @@ Invariants for rule loading in an **installed** preset (consumer app).
 
 | 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 | `alwaysApply: true` | **3–5** |
+| Claude | rules **without** `paths:` | **3–5** |
+| Mavis | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
+| OpenCode | `adapter-map` rules with `loadMode: root-entry` | **3–5** |
 
-**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.
+Caps are **aligned** across platforms: minimum **3** (base invariants), maximum **5**. Slots beyond the base invariants are reserved for `ai-local-overlay` (consumer-owned `.ai.local/` rules). If you do not need local overlay, demote that rule to `globs: ["**/.ai.local/**"]` / Claude `paths:`, or a non-root load mode on Mavis / OpenCode.
 
-**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). The intended session-start trio remains **exactly 3**; body budget sums **only those 3** rules.
+**Claude Option A (README exclusion):** when counting Claude rules without `paths:` / session-start, **exclude `**/README.md`** (topic indexes are not session-start rules). Body budget sums only the intended session-start rules (≤5).
 
 Session-start body budget:
-- Claude 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`.
+- Claude session-start: ≤200 lines total (stretch ≤170).
+- Cursor always-on: ≤200 lines total (stretch ≤170).
+- Mavis / OpenCode: ≤5 root-entry rule files; combined root `AGENTS.md` + platform entry ≤200 nonempty lines. Do not dump the full rule catalog into `AGENTS.md`.
 
 ## Meta / author rules
 
@@ -36,4 +36,4 @@ Orchestrator, feature-delivery, code-review, post-change gates, domain globs —
 
 ## 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.
+build-verifier **FAIL** if Cursor `alwaysApply` count or Claude session-start count is outside **3–5** (Claude count **excludes `**/README.md`**), or if a `preset-*` meta rule is marked always-on.

package/presets/opencode/ios-swift/rules/product-specs-authoring.md

@@ -110,3 +110,9 @@ Block handoff via `open_questions` until fixed:
 - 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`
+
+## Stack notes
+
+- Author via skill `spec-authoring`; templates from package assets / consumer `docs/specs/_templates/`.
+- Field semantics match discovery stem (`routes` = deep links; `e2e` = XCUITest). **No** web Playwright recipes.
+- Requestable — not always-on / session-start.

package/presets/opencode/ios-swift/rules/product-specs.md

@@ -54,3 +54,8 @@ Same-changeset INDEX updates, frontmatter v1, required body headings, templates,
 - 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.
+
+## Stack notes
+
+- `routes`: deep links / screen ids. `ui` / `store`: Feature / View / ViewModel modules (`Features/**` or equivalent) — **not** web `app/src/ui`. `e2e`: XCUITest paths.
+- Requestable / `docs/specs/**` globs — not always-on / session-start.