@bonesofspring/ai-rules 0.2.26 → 0.2.28

package/presets/claude/java/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/java/settings.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "deny": [
+      "Bash(git commit *)",
+      "Bash(git push *)"
+    ],
+    "ask": []
+  }
+}

package/presets/claude/mcp-ts/CLAUDE.md

@@ -4,10 +4,22 @@ Preset for authoring TypeScript MCP servers with `@modelcontextprotocol/sdk`.
 
 **Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root.
 
-- Session-start: `mcp-ts-app-core`, `architecture/mcp-server-boundaries`, `code-quality` (exactly 3).
+- Session-start: `mcp-ts-app-core`, `architecture/mcp-server-boundaries`, `code-quality` (3–5).
 - Delivery: `architecture/feature-delivery.md` + skill `feature-delivery`.
 - After TS edits: `tooling-and-review/post-change-test.md`.
 - Contract checks: `mcp-contract-testing` rule (Phase 1: feature-developer owns verification).
 - Never schedule Playwright / XCUITest / `accessibility-reviewer` / `integration-test-*`.
 
 Init: `npx @bonesofspring/ai-rules init claude --preset mcp-ts` (also copies `REPO_AGENTS.md` → root `AGENTS.md`).
+
+## Harness wiring
+
+- **Subagent rules** are re-declared inside every `.claude/agents/*.md` via
+  the `## Rules to load (subagent context)` block (always-on + zone rules
+  filtered to stems that exist for this stack, using the nested
+  `.claude/rules/<topic>/<stem>.md` paths). Claude Code subagents inherit
+  no parent context, so this block is the authoritative mechanism.
+- `.claude/settings.json` ships harness-level denials (universal
+  `git commit/push deny`; JS stacks also `npx jest* deny` and `npm/npx/pnpm/bun`
+  ask). Re-init overwrites the file (consumer can edit afterwards); mirror
+  with root `AGENTS.md` if you change the harness.

package/presets/claude/mcp-ts/agents/build-verifier.md

@@ -5,6 +5,23 @@ readonly: false
 model: fast
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit the parent session context or `CLAUDE.md`. Read these rules explicitly before acting:
+
+- `.claude/rules/stack/mcp-ts-app-core.md`
+- `.claude/rules/architecture/mcp-server-boundaries.md`
+- `.claude/rules/tooling-and-review/code-quality.md`
+- `.claude/rules/tooling-and-review/ai-local-overlay.md`
+- `.claude/rules/architecture/feature-delivery.md` — layer order, mockup gate, ux-design gate
+- `.claude/rules/architecture/reference-features.md` — analog files first
+- `.claude/rules/tooling-and-review/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.claude/rules/tooling-and-review/mcp-usage.md` — when verifying third-party APIs (Context7)
+- `.claude/rules/tooling-and-review/mcp-ts-tooling.md`
+- `.claude/rules/tooling-and-review/post-change-test.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are the build verifier for **TypeScript MCP servers** (and for **ai-rules preset packaging** when scope says so).
 
 ## Consumer MCP repos
@@ -32,7 +49,7 @@ From `packages/ai-rules/`:
 yarn check:preset-structure
 ```
 
-Hard gates: twin-map (stacks include **mcp-ts**), token-budget (alwaysApply/session-start = 3), leakage (`MCP_TS_FORBIDDEN_IN_CHAIN`, `MCP_TS_FORBIDDEN_AGENT_STEMS`, chain forks mcp-ts≠next≠ios-swift≠go≠java≠php-hexagonal≠php-laravel), shared-core drift (`AI_RULES_DRIFT_FAIL=1` via `check:preset-structure`).
+Hard gates: twin-map (stacks include **mcp-ts**), token-budget (alwaysApply / session-start 3–5), leakage (`MCP_TS_FORBIDDEN_IN_CHAIN`, `MCP_TS_FORBIDDEN_AGENT_STEMS`, chain forks mcp-ts≠next≠ios-swift≠go≠java≠php-hexagonal≠php-laravel), shared-core drift (`AI_RULES_DRIFT_FAIL=1` via `check:preset-structure`).
 
 Document PASS/FAIL in `validation-report.md`. Soft leakage output:
 

package/presets/claude/mcp-ts/agents/feature-developer.md

@@ -4,6 +4,28 @@ description: Feature implementation specialist for TypeScript MCP servers. Imple
 readonly: false
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit the parent session context or `CLAUDE.md`. Read these rules explicitly before acting:
+
+- `.claude/rules/stack/mcp-ts-app-core.md`
+- `.claude/rules/architecture/mcp-server-boundaries.md`
+- `.claude/rules/tooling-and-review/code-quality.md`
+- `.claude/rules/tooling-and-review/ai-local-overlay.md`
+- `.claude/rules/architecture/feature-delivery.md` — layer order, mockup gate, ux-design gate
+- `.claude/rules/architecture/reference-features.md` — analog files first
+- `.claude/rules/tooling-and-review/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.claude/rules/tooling-and-review/mcp-usage.md` — when verifying third-party APIs (Context7)
+- `.claude/rules/api-and-data/mcp-tool-design.md`
+- `.claude/rules/api-and-data/mcp-contract-testing.md`
+- `.claude/rules/api-and-data/mcp-auth-secrets.md`
+- `.claude/rules/api-and-data/mcp-transport-packaging.md`
+- `.claude/rules/stack/mcp-ts-conventions.md`
+- `.claude/rules/tooling-and-review/mcp-ts-tooling.md`
+- `.claude/rules/tooling-and-review/post-change-test.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 Implement MCP server features following **mcp-ts** boundaries.
 
 ## Mandatory flow

package/presets/claude/mcp-ts/agents/security-reviewer.md

@@ -4,6 +4,21 @@ description: Security review specialist for TypeScript MCP servers. Audits tool
 readonly: false
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit the parent session context or `CLAUDE.md`. Read these rules explicitly before acting:
+
+- `.claude/rules/stack/mcp-ts-app-core.md`
+- `.claude/rules/architecture/mcp-server-boundaries.md`
+- `.claude/rules/tooling-and-review/code-quality.md`
+- `.claude/rules/tooling-and-review/ai-local-overlay.md`
+- `.claude/rules/architecture/feature-delivery.md` — layer order, mockup gate, ux-design gate
+- `.claude/rules/architecture/reference-features.md` — analog files first
+- `.claude/rules/tooling-and-review/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.claude/rules/tooling-and-review/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 Review MCP diffs against `security-mcp.mdc` and `mcp-auth-secrets.mdc`.
 
 ## Focus

package/presets/claude/mcp-ts/agents/solution-architect.md

@@ -4,6 +4,21 @@ description: Solution architect for TypeScript MCP servers. Designs tool/resourc
 readonly: false
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit the parent session context or `CLAUDE.md`. Read these rules explicitly before acting:
+
+- `.claude/rules/stack/mcp-ts-app-core.md`
+- `.claude/rules/architecture/mcp-server-boundaries.md`
+- `.claude/rules/tooling-and-review/code-quality.md`
+- `.claude/rules/tooling-and-review/ai-local-overlay.md`
+- `.claude/rules/architecture/feature-delivery.md` — layer order, mockup gate, ux-design gate
+- `.claude/rules/architecture/reference-features.md` — analog files first
+- `.claude/rules/tooling-and-review/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.claude/rules/tooling-and-review/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 Design MCP server changes for **mcp-ts**.
 
 ## Deliverable
@@ -25,4 +40,3 @@ Write `architecture.md` covering:
 ## 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.
-

package/presets/claude/mcp-ts/agents/task-analyst.md

@@ -4,6 +4,21 @@ description: Task analysis specialist. Clarifies requirements, validates accepta
 readonly: false
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit the parent session context or `CLAUDE.md`. Read these rules explicitly before acting:
+
+- `.claude/rules/stack/mcp-ts-app-core.md`
+- `.claude/rules/architecture/mcp-server-boundaries.md`
+- `.claude/rules/tooling-and-review/code-quality.md`
+- `.claude/rules/tooling-and-review/ai-local-overlay.md`
+- `.claude/rules/architecture/feature-delivery.md` — layer order, mockup gate, ux-design gate
+- `.claude/rules/architecture/reference-features.md` — analog files first
+- `.claude/rules/tooling-and-review/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.claude/rules/tooling-and-review/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 Analyze MCP server work requests for the **mcp-ts** preset.
 
 ## Classify first

package/presets/claude/mcp-ts/agents/task-router.md

@@ -5,6 +5,21 @@ readonly: false
 model: fast
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit the parent session context or `CLAUDE.md`. Read these rules explicitly before acting:
+
+- `.claude/rules/stack/mcp-ts-app-core.md`
+- `.claude/rules/architecture/mcp-server-boundaries.md`
+- `.claude/rules/tooling-and-review/code-quality.md`
+- `.claude/rules/tooling-and-review/ai-local-overlay.md`
+- `.claude/rules/architecture/feature-delivery.md` — layer order, mockup gate, ux-design gate
+- `.claude/rules/architecture/reference-features.md` — analog files first
+- `.claude/rules/tooling-and-review/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.claude/rules/tooling-and-review/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are a task router for a **TypeScript MCP server** agent team. You **do not** implement tasks — you classify intent and plan the agent pipeline.
 
 ## Inputs

package/presets/claude/mcp-ts/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 — unified entry point (router + pipeline)

package/presets/claude/mcp-ts/hooks/chain-team-phases.sh

@@ -44,7 +44,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);
 }
@@ -71,6 +74,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');
@@ -78,6 +84,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 */ }
     }
@@ -435,7 +448,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,
@@ -462,7 +478,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) {
@@ -484,6 +500,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/mcp-ts/rules/README.md

@@ -12,7 +12,7 @@ Claude topic `.md` files are **derived** from Cursor SoT `presets/cursor/mcp-ts/
 
 ## Loading budget
 
-- **Session-start (no `paths:`):** exactly **3** — `mcp-ts-app-core`, `mcp-server-boundaries`, `code-quality`
+- **Session-start (no `paths:`):** 3–5 — `mcp-ts-app-core`, `mcp-server-boundaries`, `code-quality`
 - All others — with `paths:`
 - **Twin depth:** domain rules target ≥15 body lines; thin aliases: `agent-team-intake`, `technical-retro`
 

package/presets/claude/mcp-ts/rules/api-and-data/mcp-auth-secrets.md

@@ -1,10 +1,10 @@
 ---
 description: MCP env config, remote auth, redaction, secret handling
 paths:
-  - **/auth/**/*
-  - **/config/**/*
-  - **/.env*
-  - **/secrets/**/*
+  - "**/auth/**/*"
+  - "**/config/**/*"
+  - "**/.env*"
+  - "**/secrets/**/*"
 ---
 
 # MCP auth and secrets

package/presets/claude/mcp-ts/rules/api-and-data/mcp-contract-testing.md

@@ -1,8 +1,8 @@
 ---
 description: MCP schema snapshots, contract fixtures, optional Inspector smoke
 paths:
-  - **/*.{test,spec}.{ts,tsx,js}
-  - **/fixtures/**/*
+  - "**/*.{test,spec}.{ts,tsx,js}"
+  - "**/fixtures/**/*"
   - src/tools/**/*
   - src/resources/**/*
   - src/prompts/**/*

package/presets/claude/mcp-ts/rules/api-and-data/mcp-tool-design.md

@@ -1,5 +1,5 @@
 ---
-description: MCP tool/resource/prompt design: names, schemas, errors, least surprise
+description: "MCP tool/resource/prompt design: names, schemas, errors, least surprise"
 paths:
   - src/tools/**/*
   - src/resources/**/*

package/presets/claude/mcp-ts/rules/api-and-data/mcp-transport-packaging.md

@@ -3,8 +3,8 @@ description: MCP stdio lifecycle, optional remote transport, bin/npx packaging
 paths:
   - src/index.ts
   - package.json
-  - **/Dockerfile
-  - **/docker-compose*.yml
+  - "**/Dockerfile"
+  - "**/docker-compose*.yml"
 ---
 
 # MCP transport and packaging

package/presets/claude/mcp-ts/rules/architecture/mcp-server-boundaries.md

@@ -1,5 +1,5 @@
 ---
-description: MCP server module boundaries: registration, handler, capability, lifecycle
+description: "MCP server module boundaries: registration, handler, capability, lifecycle"
 ---
 
 # MCP server boundaries

package/presets/claude/mcp-ts/rules/testing/unit.md

@@ -1,8 +1,8 @@
 ---
 description: Unit testing conventions for MCP handlers and schemas
 paths:
-  - **/*.{test,spec}.{ts,tsx,js}
-  - **/__tests__/**/*
+  - "**/*.{test,spec}.{ts,tsx,js}"
+  - "**/__tests__/**/*"
 ---
 
 # Unit tests (MCP)

package/presets/claude/mcp-ts/rules/tooling-and-review/anti-sycophancy-discipline.md

@@ -1,8 +1,8 @@
 ---
 description: Anti-sycophancy discipline for code generation and review
 paths:
-  - **/*.ts
-  - **/*.tsx
+  - "**/*.ts"
+  - "**/*.tsx"
 ---
 
 <!-- shared-core: quality/anti-sycophancy-discipline.md -->

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

@@ -18,6 +18,12 @@ description: Code quality and light refactoring for TypeScript MCP servers
 - **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/mcp-ts/rules/tooling-and-review/mcp-ts-tooling.md

@@ -3,9 +3,9 @@ description: Discover package manager; typecheck/test/Inspector commands for MCP
 paths:
   - package.json
   - tsconfig*.json
-  - **/vitest.config.*
-  - **/jest.config.*
-  - **/eslint.config.*
+  - "**/vitest.config.*"
+  - "**/jest.config.*"
+  - "**/eslint.config.*"
 ---
 
 # Tooling (mcp-ts)

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

@@ -4,7 +4,7 @@ paths:
   - src/**/*.ts
   - src/**/*.tsx
   - package.json
-  - **/*.{test,spec}.ts
+  - "**/*.{test,spec}.ts"
 ---
 
 # Post-change test (requestable; must after TS MCP edits)

package/presets/claude/mcp-ts/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/mcp-ts/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/mcp-ts/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/mcp-ts/rules/tooling-and-review/security-mcp.md

@@ -1,5 +1,5 @@
 ---
-description: MCP security: injection boundaries, capability minimization, SSRF/secrets
+description: "MCP security: injection boundaries, capability minimization, SSRF/secrets"
 paths:
   - src/tools/**/*
   - src/resources/**/*

package/presets/claude/mcp-ts/settings.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "permissions": {
+    "deny": [
+      "Bash(git commit *)",
+      "Bash(git push *)"
+    ],
+    "ask": []
+  }
+}

package/presets/claude/next/CLAUDE.md

@@ -37,3 +37,15 @@ npx @bonesofspring/ai-rules init claude --preset next
 ```
 
 Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `hooks/**`, `MCP.md` into `.claude/`; seeds `.ai.local/team/` from `team/` (slugs preserved), plus `mcp.json` → **`.mcp.json`** and `REPO_AGENTS.md` → root **`AGENTS.md`**. Skills: `write-adr`, `react-performance` (on-demand).
+
+## Harness wiring
+
+- **Subagent rules** are re-declared inside every `.claude/agents/*.md` via
+  the `## Rules to load (subagent context)` block (always-on + zone rules
+  filtered to stems that exist for this stack, using the nested
+  `.claude/rules/<topic>/<stem>.md` paths). Claude Code subagents inherit
+  no parent context, so this block is the authoritative mechanism.
+- `.claude/settings.json` ships harness-level denials (universal
+  `git commit/push deny`; JS stacks also `npx jest* deny` and `npm/npx/pnpm/bun`
+  ask). Re-init overwrites the file (consumer can edit afterwards); mirror
+  with root `AGENTS.md` if you change the harness.

package/presets/claude/next/README.md

@@ -14,4 +14,4 @@ npx @bonesofspring/ai-rules init claude --preset next
 | `REPO_AGENTS.md` | root `AGENTS.md` |
 | `team/` | **`.ai.local/team/`** (shared; slugs preserved) |
 
-Session-start (exactly 3, no `paths:`): `next-app-core`, `package-manager`, `code-quality`. Living gotchas: `.ai.local/conventions.md`. `/task` artifacts: `.ai.local/team/tasks/<slug>/`. No Bugbot — use skill `code-review`. Catalog: [`rules/README.md`](./rules/README.md).
+Session-start (3–5, no `paths:`): `next-app-core`, `package-manager`, `code-quality`. Living gotchas: `.ai.local/conventions.md`. `/task` artifacts: `.ai.local/team/tasks/<slug>/`. No Bugbot — use skill `code-review`. Catalog: [`rules/README.md`](./rules/README.md).

package/presets/claude/next/agents/accessibility-reviewer.md

@@ -4,6 +4,23 @@ description: Accessibility review specialist. Audits UI changes for keyboard nav
 model: inherit
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit the parent session context or `CLAUDE.md`. Read these rules explicitly before acting:
+
+- `.claude/rules/stack/next-app-core.md`
+- `.claude/rules/tooling-and-review/package-manager.md`
+- `.claude/rules/tooling-and-review/code-quality.md`
+- `.claude/rules/tooling-and-review/ai-local-overlay.md`
+- `.claude/rules/architecture/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.claude/rules/architecture/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.claude/rules/architecture/reference-features.md` — analog files first
+- `.claude/rules/tooling-and-review/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.claude/rules/tooling-and-review/post-change-lint.md` — lint/type-check after code edits
+- `.claude/rules/tooling-and-review/mcp-usage.md` — when verifying third-party APIs (Context7)
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are an accessibility reviewer for a Next.js React frontend.
 
 ## Inputs

package/presets/claude/next/agents/api-contract-reviewer.md

@@ -4,6 +4,25 @@ description: API contract review specialist. Validates DTOs, mappers, mocks, and
 model: inherit
 ---
 
+## Rules to load (subagent context)
+
+This subagent does **not** inherit the parent session context or `CLAUDE.md`. Read these rules explicitly before acting:
+
+- `.claude/rules/stack/next-app-core.md`
+- `.claude/rules/tooling-and-review/package-manager.md`
+- `.claude/rules/tooling-and-review/code-quality.md`
+- `.claude/rules/tooling-and-review/ai-local-overlay.md`
+- `.claude/rules/architecture/architecture-boundaries.md` — layer boundaries and allowed imports
+- `.claude/rules/architecture/feature-delivery-workflow.md` — layer order, mockup gate, ux-design gate
+- `.claude/rules/architecture/reference-features.md` — analog files first
+- `.claude/rules/tooling-and-review/anti-sycophancy-discipline.md` — procedural anti-sycophancy rules
+- `.claude/rules/tooling-and-review/post-change-lint.md` — lint/type-check after code edits
+- `.claude/rules/tooling-and-review/mcp-usage.md` — when verifying third-party APIs (Context7)
+- `.claude/rules/api-and-data/api-services.md`
+- `.claude/rules/api-and-data/http-client.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are an API contract reviewer for a layered Next.js frontend (`@/types`, `@/api`, store, UI).
 
 ## Inputs