@bonesofspring/ai-rules 0.2.26 → 0.2.27

package/presets/claude/go/rules/api-and-data/adapters-driving.md

@@ -2,8 +2,8 @@
 description: Driving adapters (HTTP, gRPC, CLI) for Go hexagonal services
 paths:
   - internal/adapters/http/**/*
-  - **/adapters/http/**/*
-  - **/adapters/grpc/**/*
+  - "**/adapters/http/**/*"
+  - "**/adapters/grpc/**/*"
   - cmd/**/*
 ---
 

package/presets/claude/go/rules/api-and-data/api-grpc.md

@@ -1,8 +1,8 @@
 ---
 description: Thin gRPC/protobuf extension notes for Go hexagonal services (HTTP-first v1)
 paths:
-  - **/*.proto
-  - **/adapters/grpc/**/*
+  - "**/*.proto"
+  - "**/adapters/grpc/**/*"
 ---
 
 

package/presets/claude/go/rules/api-and-data/api-http.md

@@ -1,9 +1,9 @@
 ---
 description: HTTP API adapter conventions for Go hexagonal services
 paths:
-  - **/adapters/http/**/*
-  - **/*handler*.go
-  - **/*router*.go
+  - "**/adapters/http/**/*"
+  - "**/*handler*.go"
+  - "**/*router*.go"
 ---
 
 # HTTP API adapters

package/presets/claude/go/rules/api-and-data/messaging-adapters.md

@@ -1,7 +1,7 @@
 ---
 description: Messaging driven/driving adapters for Go hexagonal services
 paths:
-  - **/adapters/messaging/**/*
+  - "**/adapters/messaging/**/*"
 ---
 
 

package/presets/claude/go/rules/api-and-data/persistence-adapters.md

@@ -1,8 +1,8 @@
 ---
 description: Persistence driven adapters (SQL/repos) for Go hexagonal services
 paths:
-  - **/adapters/persistence/**/*
-  - **/*repository*.go
+  - "**/adapters/persistence/**/*"
+  - "**/*repository*.go"
 ---
 
 # Persistence adapters

package/presets/claude/go/rules/architecture/application-usecases.md

@@ -2,7 +2,7 @@
 description: Application use cases and orchestration in Go hexagonal services
 paths:
   - internal/application/**/*
-  - **/application/**/*
+  - "**/application/**/*"
 ---
 
 # Application / use cases

package/presets/claude/go/rules/architecture/domain-layer.md

@@ -2,7 +2,7 @@
 description: Domain layer invariants for Go hexagonal services
 paths:
   - internal/domain/**/*
-  - **/domain/**/*
+  - "**/domain/**/*"
 ---
 
 

package/presets/claude/go/rules/architecture/feature-delivery.md

@@ -3,7 +3,7 @@ description: End-to-end delivery checklist for Go hexagonal features
 paths:
   - .ai.local/team/**/*
   - .ai.local/team/**/*
-  - **/*.go
+  - "**/*.go"
   - internal/**/*
   - cmd/**/*
 ---

package/presets/claude/go/rules/architecture/ports-interfaces.md

@@ -1,9 +1,9 @@
 ---
 description: Inbound and outbound port interfaces for Go hexagonal services
 paths:
-  - **/ports/**/*
+  - "**/ports/**/*"
   - internal/application/**/*port*
-  - **/application/**/*port*
+  - "**/application/**/*port*"
 ---
 
 

package/presets/claude/go/rules/stack/go-conventions.md

@@ -1,7 +1,7 @@
 ---
 description: Idiomatic Go conventions for this hexagonal preset
 paths:
-  - **/*.go
+  - "**/*.go"
 ---
 
 # Go conventions

package/presets/claude/go/rules/testing/e2e.md

@@ -1,8 +1,8 @@
 ---
 description: End-to-end HTTP smoke tests for Go services
 paths:
-  - **/e2e/**/*_test.go
-  - **/*_e2e_test.go
+  - "**/e2e/**/*_test.go"
+  - "**/*_e2e_test.go"
 ---
 
 # E2E / HTTP smoke

package/presets/claude/go/rules/testing/integration.md

@@ -1,8 +1,8 @@
 ---
 description: Integration / adapter contract tests for Go hexagonal services
 paths:
-  - **/integration/**/*_test.go
-  - **/*_integration_test.go
+  - "**/integration/**/*_test.go"
+  - "**/*_integration_test.go"
 ---
 
 # Integration tests

package/presets/claude/go/rules/testing/unit.md

@@ -1,7 +1,7 @@
 ---
 description: Unit testing conventions for Go hexagonal services
 paths:
-  - **/*_test.go
+  - "**/*_test.go"
 ---
 
 

package/presets/claude/go/rules/tooling-and-review/agent-team-intake.md

@@ -3,7 +3,7 @@ description: Suggest /task for Go backend work requests
 paths:
   - .ai.local/team/**/*
   - .ai.local/team/**/*
-  - **/*.go
+  - "**/*.go"
   - internal/**/*
   - cmd/**/*
 ---

package/presets/claude/go/rules/tooling-and-review/agent-team-orchestrator.md

@@ -3,7 +3,7 @@ description: Orchestrates the agent team via task-router and pipeline.json for G
 paths:
   - .ai.local/team/**/*
   - .ai.local/team/**/*
-  - **/*.go
+  - "**/*.go"
   - internal/**/*
   - cmd/**/*
 ---

package/presets/claude/go/rules/tooling-and-review/code-quality.md

@@ -18,6 +18,12 @@ description: Code quality and light refactoring for Go hexagonal services
 - **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.

package/presets/claude/go/rules/tooling-and-review/code-review.md

@@ -3,7 +3,7 @@ description: Code review checklist for Go hexagonal merge requests
 paths:
   - .ai.local/team/**/*
   - .ai.local/team/**/*
-  - **/*.go
+  - "**/*.go"
   - internal/**/*
   - cmd/**/*
 ---

package/presets/claude/go/rules/tooling-and-review/go-tooling.md

@@ -3,7 +3,7 @@ description: Go toolchain commands (test, vet, lint, race) — requestable
 paths:
   - .ai.local/team/**/*
   - .ai.local/team/**/*
-  - **/*.go
+  - "**/*.go"
   - internal/**/*
   - cmd/**/*
 ---

package/presets/claude/go/rules/tooling-and-review/mcp-usage.md

@@ -1,7 +1,7 @@
 ---
 description: When to call shipped Context7 and local overlay MCP — detect presence, use if the task fits, degrade.
 paths:
-  - **/*.go
+  - "**/*.go"
 ---
 
 <!-- shared-core: quality/mcp-usage.md -->

package/presets/claude/go/rules/tooling-and-review/post-change-test.md

@@ -3,7 +3,7 @@ description: Mandatory verification after Go code edits (go test / vet / lint-if
 paths:
   - .ai.local/team/**/*
   - .ai.local/team/**/*
-  - **/*.go
+  - "**/*.go"
   - internal/**/*
   - cmd/**/*
 ---

package/presets/claude/go/rules/tooling-and-review/preset-layering.md

@@ -18,7 +18,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/claude/go/rules/tooling-and-review/preset-pr-checklist.md

@@ -21,7 +21,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/claude/go/rules/tooling-and-review/preset-token-budget.md

@@ -17,19 +17,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
 
@@ -45,4 +45,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/claude/go/rules/tooling-and-review/security-go.md

@@ -1,9 +1,9 @@
 ---
 description: Security basics for Go backends (secrets, auth, PII, TLS)
 paths:
-  - **/middleware/**/*
-  - **/auth/**/*
-  - **/config/**/*
+  - "**/middleware/**/*"
+  - "**/auth/**/*"
+  - "**/config/**/*"
 ---
 
 # Security (Go)

package/presets/claude/go/rules/tooling-and-review/technical-retro.md

@@ -3,7 +3,7 @@ description: Technical retro alias — use /technical-retro command
 paths:
   - .ai.local/team/**/*
   - .ai.local/team/**/*
-  - **/*.go
+  - "**/*.go"
   - internal/**/*
   - cmd/**/*
 ---

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

@@ -36,15 +36,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-*` must have `paths:` (not session-start).
+1. **Token budget:** Cursor `alwaysApply: true` count 3–5; Claude rules without `paths:` 3–5 (**exclude `**/README.md`** — Option A). Meta `preset-*` must have `paths:` (not session-start).
 2. **Chain fork check:** `hooks/chain-team-phases.sh` must **not** be byte-identical to next’s chain script.
 3. **Forbidden handoff strings** in ios-swift `chain-team-phases.sh`: `playwright-test-`, `playwright-agents`, `playwright-e2e`, `user-playwright`, `app/__tests__/e2e`, positive `lint:js` / `lint:css` recipes. See `tooling-and-review/preset-no-cross-stack-leakage.md`.
 4. **Required handoff stems:** `AGENT_HANDOFF` must include `xcuitest-test-planner` (or generator/healer); build-verifier mentions `xcodebuild` or `post-change-build` / `xcode-tooling`.
-5. **Roster:** 21 agent stems; no `playwright-test-*` under ios-swift `agents/`.
+5. **Roster:** 24 agent stems; no `playwright-test-*` under ios-swift `agents/`.
 6. **Twin presence (hard):** Cursor rule change → Claude twin same PR — **FAIL** if missing (next, nuxt, svelte, ios-swift, go, java, mcp-ts, php-hexagonal, and php-laravel).
 7. **Mapping / README:** Cursor→Claude mapping table present; core→stack mapping when `_shared` consumers exist.
 8. **shared-core consumers:** if `_shared/core/**` changed, update all `<!-- shared-core: … -->` consumers (or document intentional fork).
-9. **Session-start body budget:** sum of the **3** intended 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 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/claude/ios-swift/commands/task.md

@@ -1,6 +1,6 @@
 ---
 name: task
-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."
 ---
 
 # Task — single entry point

package/presets/claude/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/claude/ios-swift/hooks/examples/README.md

@@ -8,11 +8,13 @@ Optional scripts under `hooks/examples/`. **Not** referenced from default `hooks
 | `format-edited.example.sh` | Stack formatter / linter on edited files |
 | `test-on-save.example.sh` | Scoped tests for the stack |
 
-## Wiring (Cursor)
+## Wiring (Claude Code)
+
+Claude Code has no preset `hooks.json`; hooks are registered in `.claude/settings.json` and fire on events such as `PreToolUse`, `PostToolUse`, and `Stop`.
 
 1. Copy an example into `hooks/` (drop `.example` suffix), e.g. `cp hooks/examples/secret-guard.example.sh hooks/secret-guard.sh`.
 2. `chmod +x hooks/secret-guard.sh`.
-3. Add a hook entry in `.cursor/hooks.json` (e.g. `beforeShellExecution` or `afterFileEdit` — see Cursor hooks docs).
-4. Keep cookbook scripts **out** of the default preset `hooks.json` when contributing back upstream.
+3. Register the command in `.claude/settings.json` (see Claude Code hooks docs for event/matcher syntax).
+4. Keep cookbook scripts **out** of the default preset when contributing back upstream.
 
 Stack: **ios-swift** — recipes must stay stack-safe (no cross-stack lint/test commands).

package/presets/claude/ios-swift/rules/README.md

@@ -13,7 +13,7 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 
 ## Loading budget
 
-- **Session-start (no `paths:`):** exactly **3** — `ios-app-core`, `boundaries`, `code-quality` (≤140 body lines total)
+- **Session-start (no `paths:`):** 3–5 — `ios-app-core`, `boundaries`, `code-quality` (≤200 body lines total)
 - **Everything else** — with `paths:` (commands/team/agents and/or Feature/Swift globs)
 - **Soft twin depth:** domain rules ≥15 body lines; thin aliases (`agent-team-intake`, `technical-retro`) may be shorter (as in next)
 

package/presets/claude/ios-swift/rules/architecture/feature-delivery.md

@@ -5,9 +5,9 @@ paths:
   - .ai.local/team/**/*
   - .claude/agents/**/*
   - Features/**/*
-  - **/Presentation/**/*
-  - **/Domain/**/*
-  - **/Data/**/*
+  - "**/Presentation/**/*"
+  - "**/Domain/**/*"
+  - "**/Data/**/*"
 ---
 
 <!-- shared-core: architecture/feature-delivery-workflow.md -->

package/presets/claude/ios-swift/rules/architecture/reference-features.md

@@ -16,7 +16,7 @@ paths:
 
 Before implementing, find a Feature of the same type and **mirror its structure**; do not invent a new file organization.
 
-Taxonomy / shared core: [`presets/_shared/README.md`](../../../../_shared/README.md) · [Preset contribution guide](../../../../docs/PRESET-CONTRIBUTION.md).
+Taxonomy / shared core: [`presets/_shared/README.md`](../../../../_shared/README.md) · [Preset contribution guide](../../../../../docs/PRESET-CONTRIBUTION.md).
 
 ## Reference table
 

package/presets/claude/ios-swift/rules/tooling-and-review/code-quality.md

@@ -18,6 +18,12 @@ description: Maintain and improve iOS code quality and architecture
 - **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.

package/presets/claude/ios-swift/rules/tooling-and-review/mcp-usage.md

@@ -1,7 +1,7 @@
 ---
 description: When to call shipped Context7 and local overlay MCP — detect presence, use if the task fits, degrade.
 paths:
-  - **/*.swift
+  - "**/*.swift"
 ---
 
 <!-- shared-core: quality/mcp-usage.md -->

package/presets/claude/ios-swift/rules/tooling-and-review/post-change-build.md

@@ -3,8 +3,8 @@ description: Build and lint after Swift/iOS code changes. Use after editing iOS/
 paths:
   - .claude/commands/**/*
   - .claude/agents/**/*
-  - **/*.{swift,xcodeproj,xcworkspace,pbxproj}
-  - **/Package.swift
+  - "**/*.{swift,xcodeproj,xcworkspace,pbxproj}"
+  - "**/Package.swift"
 ---
 
 # Build and lint after changes

package/presets/claude/ios-swift/rules/tooling-and-review/preset-layering.md

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: Core → Stack → Platform layering. Use when editing packages/ai-rules/presets/**.
+description: "Preset authoring: Core → Stack → Platform layering. Use when editing packages/ai-rules/presets/**."
 paths:
   - packages/ai-rules/presets/**/*
   - .claude/**/*
@@ -18,7 +18,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/claude/ios-swift/rules/tooling-and-review/preset-no-cross-stack-leakage.md

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: forbid cross-stack agent/path leakage in hooks and agents.
+description: "Preset authoring: forbid cross-stack agent/path leakage in hooks and agents."
 paths:
   - packages/ai-rules/presets/**/*
   - .claude/**/*

package/presets/claude/ios-swift/rules/tooling-and-review/preset-pr-checklist.md

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: PR checklist for twin sync, budget, leakage, README. Use on preset PRs.
+description: "Preset authoring: PR checklist for twin sync, budget, leakage, README. Use on preset PRs."
 paths:
   - packages/ai-rules/presets/**/*
   - .claude/**/*
@@ -21,7 +21,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/claude/ios-swift/rules/tooling-and-review/preset-token-budget.md

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: ≤3 always-on / session-start; meta rules never alwaysApply.
+description: "Preset authoring: ≤3 always-on / session-start; meta rules never alwaysApply."
 paths:
   - packages/ai-rules/presets/**/*
   - .claude/**/*
@@ -17,19 +17,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
 
@@ -45,4 +45,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/claude/ios-swift/rules/tooling-and-review/preset-twin-sync.md

@@ -1,5 +1,5 @@
 ---
-description: Preset authoring: Cursor SoT → Claude twin same PR. Use when editing preset rules.
+description: "Preset authoring: Cursor SoT → Claude twin same PR. Use when editing preset rules."
 paths:
   - packages/ai-rules/presets/**/*
   - .claude/**/*

package/presets/claude/ios-swift/rules/ui-and-accessibility/swiftui.md

@@ -14,6 +14,13 @@ paths:
 - Before a new custom control — look for a component in `DesignSystem/` or existing features.
 - Extract repeated UI logic into `ViewModifier`, `@ViewBuilder` helpers, or subviews.
 
+# Conditional rendering
+
+- Prefer **decomposition over conditionals**: a `body` with several `if` / `switch` branches should compose small subviews, not nest conditions inline.
+- Keep the condition in the parent; subviews receive resolved state.
+- For loading / empty / error, use dedicated subviews or a small `@ViewBuilder` helper.
+- A `mode` / `variant` flag that renders two unrelated layouts is **two** views, not one.
+
 # ViewModel and binding
 
 - ViewModel — `@MainActor`, `@Observable` (iOS 17+) or `ObservableObject` — as adopted in the project.