@bonesofspring/ai-rules 0.2.28 → 0.2.29

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

@@ -6,5 +6,28 @@
       "Bash(git push *)"
     ],
     "ask": []
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-shell-command.sh"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/chain-team-phases.sh"
+          }
+        ]
+      }
+    ]
   }
 }

package/presets/claude/next/CLAUDE.md

@@ -9,7 +9,8 @@ See @rules/README.md for the full catalog and loading strategy.
 ## Conventions
 
 - **One topic per file**; for large areas — subfolders under `rules/<topic>/`.
-- **Session-start rules** (no `paths:`) — exactly **three**: `next-app-core`, `package-manager`, `code-quality`.
+- **Session-start rules** (no `paths:`) — 3–5: `next-app-core`, `package-manager`, `code-quality`, `ai-local-overlay`.
+- **Local overlay (session-start):** `ai-local-overlay` has no `paths:` and counts in the 3–5 budget. On every turn, probe `ls -la .ai.local`, apply `.ai.local/rules/*.md` and `.ai.local/conventions.md`, and acknowledge `Using .ai.local: <rule-name>`. Guide: `docs/LOCAL-OVERLAY.md`.
 - **Domain-specific rules** — YAML frontmatter `paths:` (loaded when matching files are in play); `post-change-lint` — requestable (**required after code edits**); orchestrator and code-review — on-demand.
 - Slash commands — in `commands/`; scenarios — in `skills/`; subagents — in `agents/`.
 
@@ -49,3 +50,4 @@ Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `hooks/**`, `MCP.md`
   `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.
+- **Pipeline hooks:** `.claude/settings.json` `hooks` wires `guard-shell-command.sh` (`PreToolUse` / `Bash`, `permissionDecision` `ask` or `allow`) and `chain-team-phases.sh` (`SubagentStop` for kebab-case `agent_type`). See `hooks/README.md`. No `hooks.json`.

package/presets/claude/next/REPO_AGENTS.md

@@ -71,4 +71,4 @@ A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in m
 
 Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
 
-Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule (always-on for Cursor, on-demand for Claude) is the mechanism; this `MANDATORY` section is the reinforcement.
+On every turn, probe `ls -la .ai.local`, apply `.ai.local/rules/*.md` and `.ai.local/conventions.md`, and acknowledge `Using .ai.local: <rule-name>`. Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule is always-on on Cursor and session-start on Claude (no `paths:`). Mavis and OpenCode have no native `alwaysApply`; this section plus the platform entry's essential-rules list is the reinforcement.

package/presets/claude/next/hooks/README.md

@@ -5,4 +5,13 @@
 | `chain-team-phases.sh` | Continues `/task` after a producer receipt. Reads/writes `.ai.local/team/`. Agents must not patch `status.json` / `metrics.json`. |
 | `guard-shell-command.sh` | Destructive git / package-manager guard |
 
-No `hooks.json`. Wire `chain-team-phases.sh` per [Claude Code hooks](https://code.claude.com/docs/en/hooks). Cookbook: `hooks/examples/` (not enabled by default).
+No `hooks.json`. Default chain and shell guard are registered in `.claude/settings.json` (see **Shipped wiring**). Cookbook scripts in `hooks/examples/` stay unwired.
+
+## Shipped wiring (Claude Code settings)
+
+`.claude/settings.json` `hooks` (https://code.claude.com/docs/en/hooks) registers:
+
+- `PreToolUse` matcher `Bash` → `guard-shell-command.sh` (reads `tool_input.command`; emits `permissionDecision` `ask` or `allow`)
+- `SubagentStop` → `chain-team-phases.sh` (kebab-case `agent_type` maps to `status: completed`; empty or non-kebab types are ignored; `stop_hook_active` does not recurse)
+
+There is no `hooks.json`. Cookbook scripts under `hooks/examples/` stay unwired. A hook crash is not a deny (Cursor `failClosed` has no Claude field); `ask` is the supported review decision.

package/presets/claude/next/hooks/chain-team-phases.sh

@@ -21,6 +21,24 @@ try {
   process.exit(0);
 }
 
+// Claude Code SubagentStop has hook_event_name / agent_type / stop_hook_active, not status.
+// Kebab-case agent_type (preset roles) is the completed signal. Empty or non-kebab
+// types (Claude internal agents) do not advance the pipeline. stop_hook_active
+// means this hook already continued the turn — do not recurse.
+// Manual pipes of {"status":"completed"} skip this block.
+if (hookInput.hook_event_name === 'SubagentStop') {
+  if (hookInput.stop_hook_active === true) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+  const agentType = typeof hookInput.agent_type === 'string' ? hookInput.agent_type : '';
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agentType)) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+  if (hookInput.status == null) hookInput.status = 'completed';
+}
+
 if (hookInput.status !== 'completed') {
   process.stdout.write('{}');
   process.exit(0);

package/presets/claude/next/hooks/examples/README.md

@@ -10,6 +10,8 @@ Optional scripts under `hooks/examples/`. **Not** referenced from default `hooks
 
 ## Wiring (Claude Code)
 
+Default `.claude/settings.json` already registers `guard-shell-command.sh` on `PreToolUse` (matcher `Bash`) and `chain-team-phases.sh` on `SubagentStop`. Cookbook scripts are not in that default set.
+
 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`.

package/presets/claude/next/hooks/guard-shell-command.sh

@@ -17,20 +17,43 @@ try {
   process.exit(0);
 }
 
-const command = String(event.command || event.input?.command || '');
-if (!command.trim()) {
-  process.stdout.write('{ "permission": "allow" }');
-  process.exit(0);
-}
+const claudePreTool = event.hook_event_name === 'PreToolUse';
+const command = String(
+  event.command
+  || (event.input && event.input.command)
+  || (event.tool_input && event.tool_input.command)
+  || '',
+);
 
-function out(permission, userMessage, agentMessage) {
+function out(permission, userMessage) {
+  if (claudePreTool) {
+    const decision = permission === 'ask' || permission === 'deny' ? permission : 'allow';
+    const hookSpecificOutput = {
+      hookEventName: 'PreToolUse',
+      permissionDecision: decision,
+    };
+    if (userMessage && decision !== 'allow') {
+      hookSpecificOutput.permissionDecisionReason = userMessage;
+    }
+    process.stdout.write(JSON.stringify({ hookSpecificOutput }));
+    return;
+  }
+  if (!userMessage) {
+    process.stdout.write('{ "permission": "allow" }');
+    return;
+  }
   process.stdout.write(JSON.stringify({
     permission,
     user_message: userMessage,
-    agent_message: agentMessage || userMessage,
+    agent_message: userMessage,
   }));
 }
 
+if (!command.trim()) {
+  out('allow');
+  process.exit(0);
+}
+
 const dangerousGit = /\bgit\s+(reset\s+--hard|clean\s+-[^\n]*f|push\s+--force|push\s+-f|checkout\s+--\s+)/;
 if (dangerousGit.test(command)) {
   out(
@@ -59,7 +82,7 @@ if (!expected && fs.existsSync('package.json')) {
 }
 
 if (!expected) {
-  process.stdout.write('{ "permission": "allow" }');
+  out('allow');
   process.exit(0);
 }
 
@@ -73,5 +96,5 @@ if (used && used !== expected) {
   process.exit(0);
 }
 
-process.stdout.write('{ "permission": "allow" }');
+out('allow');
 NODE

package/presets/claude/next/rules/README.md

@@ -14,7 +14,7 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 
 ## Loading strategy
 
-- **Session start (no `paths:`):** 3–5 — `next-app-core`, `package-manager`, `code-quality`
+- **Session start (no `paths:`):** 3–5 — `next-app-core`, `package-manager`, `code-quality`, `ai-local-overlay`
 - **On-demand (`paths:` or via commands):** `post-change-lint` (**must after code edits**), `agent-team-intake`, `agent-team-orchestrator`, `code-review-mr`, `security-next`, architecture, imports, UI, tests, feature-delivery-workflow, `design-guidance`, `mcp-usage`, `anti-sycophancy-discipline`, `react-next-anti-hallucination`, reference-features, next-app-router, react-a11y-coding, `technical-retro`, `mockup-review`, `ux-design`, **preset-*** meta (paths on `packages/ai-rules/presets/**`)
 - **Skills:** long workflows (`feature-delivery`, `spec-authoring`, `spec-discovery`, `code-review`, …)
 

package/presets/claude/next/rules/tooling-and-review/ai-local-overlay.md

@@ -1,10 +1,5 @@
 ---
 description: Local overlay from .ai.local/ (consumer-owned rules with priority over preset rules) — MANDATORY
-paths:
-  - "**/.ai.local/**"
-  - "**/AGENTS.md"
-  - "**/CLAUDE.md"
-alwaysApply: false
 impact: CRITICAL
 ---
 

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

@@ -30,7 +30,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
 - [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
 - [ ] **i18n anchors:** kept-marked Cyrillic fragments in `tests-unit.md(c)` stay consistent with their English counterparts. Run `packages/ai-rules/scripts/check-preset-i18n.sh`.
-- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (and `sync-dogfood-mavis.sh` / `sync-dogfood-opencode.sh` when those platforms changed), or document an intentional skip, when maintaining this monorepo
+- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-claude.sh`, `sync-dogfood-mavis.sh`, and `sync-dogfood-opencode.sh` when those platforms changed, or document an intentional skip, when maintaining this monorepo
 - [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
 
 ## Pointers
@@ -40,6 +40,6 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - Budget: `preset-token-budget`
 - Leakage: `preset-no-cross-stack-leakage`
 - Validation: stack `agents/build-verifier.md` → preset-structure section
-- Dogfood scripts: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-mavis.sh`, `sync-dogfood-opencode.sh`
+- Dogfood scripts: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-claude.sh`, `sync-dogfood-mavis.sh`, `sync-dogfood-opencode.sh`
 - Drift script: `packages/ai-rules/scripts/check-shared-core-drift.sh`
 - Orchestrator: when editing presets, load this checklist + twin-sync

package/presets/claude/next/settings.json

@@ -12,5 +12,28 @@
       "Bash(npx *)",
       "Bash(pnpm *)"
     ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-shell-command.sh"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/chain-team-phases.sh"
+          }
+        ]
+      }
+    ]
   }
 }

package/presets/claude/nuxt/CLAUDE.md

@@ -9,7 +9,8 @@ See @rules/README.md for the full catalog and loading strategy.
 ## Conventions
 
 - **One topic per file**; for large areas — subfolders under `rules/<topic>/`.
-- **Session-start rules** (no `paths:`) — exactly **three**: `nuxt-app-core`, `package-manager`, `code-quality`.
+- **Session-start rules** (no `paths:`) — 3–5: `nuxt-app-core`, `package-manager`, `code-quality`, `ai-local-overlay`.
+- **Local overlay (session-start):** `ai-local-overlay` has no `paths:` and counts in the 3–5 budget. On every turn, probe `ls -la .ai.local`, apply `.ai.local/rules/*.md` and `.ai.local/conventions.md`, and acknowledge `Using .ai.local: <rule-name>`. Guide: `docs/LOCAL-OVERLAY.md`.
 - **Domain-specific rules** — YAML frontmatter `paths:` (loaded when matching files); `post-change-lint` — requestable (**required after code edits**); orchestrator and code-review — on-demand.
 - Slash commands — in `commands/`; scenarios — in `skills/`; subagents — in `agents/`.
 
@@ -49,3 +50,4 @@ Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `hooks/**`, `MCP.md`
   `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.
+- **Pipeline hooks:** `.claude/settings.json` `hooks` wires `guard-shell-command.sh` (`PreToolUse` / `Bash`, `permissionDecision` `ask` or `allow`) and `chain-team-phases.sh` (`SubagentStop` for kebab-case `agent_type`). See `hooks/README.md`. No `hooks.json`.

package/presets/claude/nuxt/REPO_AGENTS.md

@@ -72,4 +72,4 @@ A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in m
 
 Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
 
-Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule (always-on for Cursor, on-demand for Claude) is the mechanism; this `MANDATORY` section is the reinforcement.
+On every turn, probe `ls -la .ai.local`, apply `.ai.local/rules/*.md` and `.ai.local/conventions.md`, and acknowledge `Using .ai.local: <rule-name>`. Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule is always-on on Cursor and session-start on Claude (no `paths:`). Mavis and OpenCode have no native `alwaysApply`; this section plus the platform entry's essential-rules list is the reinforcement.

package/presets/claude/nuxt/hooks/README.md

@@ -5,10 +5,13 @@
 | `chain-team-phases.sh` | Pipeline chaining after subagent stop; `skipIf`, parallel, `validation_failed`, `retryAfterFix` |
 | `guard-shell-command.sh` | Destructive git / package-manager guard |
 
-Wire into Claude Code hooks per project documentation when enabling agent team auto-chain.
+No `hooks.json`. Default chain and shell guard are registered in `.claude/settings.json` (see **Shipped wiring**). Cookbook scripts in `hooks/examples/` stay unwired; keep stack-safe recipes (this preset: **nuxt**).
 
-## Optional cookbook
+## Shipped wiring (Claude Code settings)
 
-Example scripts live in `hooks/examples/` (secret-guard, format-edited, test-on-save). They are **not** auto-enabled.
+`.claude/settings.json` `hooks` (https://code.claude.com/docs/en/hooks) registers:
 
-To wire in Claude Code: copy an `.example.sh` into `hooks/`, make executable, and register per [Claude Code hooks](https://code.claude.com/docs/en/hooks) for your project. Keep stack-safe recipes (this preset: **nuxt**). Cursor twin examples under `presets/cursor/nuxt/hooks/examples/` are the same allowlist forks.
+- `PreToolUse` matcher `Bash` → `guard-shell-command.sh` (reads `tool_input.command`; emits `permissionDecision` `ask` or `allow`)
+- `SubagentStop` → `chain-team-phases.sh` (kebab-case `agent_type` maps to `status: completed`; empty or non-kebab types are ignored; `stop_hook_active` does not recurse)
+
+There is no `hooks.json`. Cookbook scripts under `hooks/examples/` stay unwired. A hook crash is not a deny (Cursor `failClosed` has no Claude field); `ask` is the supported review decision.

package/presets/claude/nuxt/hooks/chain-team-phases.sh

@@ -21,6 +21,24 @@ try {
   process.exit(0);
 }
 
+// Claude Code SubagentStop has hook_event_name / agent_type / stop_hook_active, not status.
+// Kebab-case agent_type (preset roles) is the completed signal. Empty or non-kebab
+// types (Claude internal agents) do not advance the pipeline. stop_hook_active
+// means this hook already continued the turn — do not recurse.
+// Manual pipes of {"status":"completed"} skip this block.
+if (hookInput.hook_event_name === 'SubagentStop') {
+  if (hookInput.stop_hook_active === true) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+  const agentType = typeof hookInput.agent_type === 'string' ? hookInput.agent_type : '';
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agentType)) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+  if (hookInput.status == null) hookInput.status = 'completed';
+}
+
 if (hookInput.status !== 'completed') {
   process.stdout.write('{}');
   process.exit(0);

package/presets/claude/nuxt/hooks/examples/README.md

@@ -10,6 +10,8 @@ Optional scripts under `hooks/examples/`. **Not** referenced from default `hooks
 
 ## Wiring (Claude Code)
 
+Default `.claude/settings.json` already registers `guard-shell-command.sh` on `PreToolUse` (matcher `Bash`) and `chain-team-phases.sh` on `SubagentStop`. Cookbook scripts are not in that default set.
+
 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`.

package/presets/claude/nuxt/hooks/guard-shell-command.sh

@@ -17,20 +17,43 @@ try {
   process.exit(0);
 }
 
-const command = String(event.command || event.input?.command || '');
-if (!command.trim()) {
-  process.stdout.write('{ "permission": "allow" }');
-  process.exit(0);
-}
+const claudePreTool = event.hook_event_name === 'PreToolUse';
+const command = String(
+  event.command
+  || (event.input && event.input.command)
+  || (event.tool_input && event.tool_input.command)
+  || '',
+);
 
-function out(permission, userMessage, agentMessage) {
+function out(permission, userMessage) {
+  if (claudePreTool) {
+    const decision = permission === 'ask' || permission === 'deny' ? permission : 'allow';
+    const hookSpecificOutput = {
+      hookEventName: 'PreToolUse',
+      permissionDecision: decision,
+    };
+    if (userMessage && decision !== 'allow') {
+      hookSpecificOutput.permissionDecisionReason = userMessage;
+    }
+    process.stdout.write(JSON.stringify({ hookSpecificOutput }));
+    return;
+  }
+  if (!userMessage) {
+    process.stdout.write('{ "permission": "allow" }');
+    return;
+  }
   process.stdout.write(JSON.stringify({
     permission,
     user_message: userMessage,
-    agent_message: agentMessage || userMessage,
+    agent_message: userMessage,
   }));
 }
 
+if (!command.trim()) {
+  out('allow');
+  process.exit(0);
+}
+
 const dangerousGit = /\bgit\s+(reset\s+--hard|clean\s+-[^\n]*f|push\s+--force|push\s+-f|checkout\s+--\s+)/;
 if (dangerousGit.test(command)) {
   out(
@@ -59,7 +82,7 @@ if (!expected && fs.existsSync('package.json')) {
 }
 
 if (!expected) {
-  process.stdout.write('{ "permission": "allow" }');
+  out('allow');
   process.exit(0);
 }
 
@@ -73,5 +96,5 @@ if (used && used !== expected) {
   process.exit(0);
 }
 
-process.stdout.write('{ "permission": "allow" }');
+out('allow');
 NODE

package/presets/claude/nuxt/rules/README.md

@@ -14,7 +14,7 @@ In Claude Code all `.md` files under `rules/` are **discovered recursively**. Bo
 
 ## Loading strategy
 
-- **Session start (no `paths:`):** 3–5 — `nuxt-app-core`, `package-manager`, `code-quality`
+- **Session start (no `paths:`):** 3–5 — `nuxt-app-core`, `package-manager`, `code-quality`, `ai-local-overlay`
 - **On-demand (`paths:` or via commands):** `post-change-lint`, `security-nuxt`, architecture, UI, tests, `vue-nuxt-anti-hallucination`, **preset-*** meta, …
 - **Skills:** `feature-delivery`, `vue-performance`, `code-review`, …
 

package/presets/claude/nuxt/rules/tooling-and-review/ai-local-overlay.md

@@ -1,10 +1,5 @@
 ---
 description: Local overlay from .ai.local/ (consumer-owned rules with priority over preset rules) — MANDATORY
-paths:
-  - "**/.ai.local/**"
-  - "**/AGENTS.md"
-  - "**/CLAUDE.md"
-alwaysApply: false
 impact: CRITICAL
 ---
 

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

@@ -26,7 +26,7 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - [ ] **README:** stack `rules/README.md` core→stack mapping / catalog updated if stems added
 - [ ] **CHANGELOG / package README:** note when public preset paths or install surface change
 - [ ] **i18n anchors:** kept-marked Cyrillic fragments in `tests-unit.md(c)` stay consistent with their English counterparts. Run `packages/ai-rules/scripts/check-preset-i18n.sh`.
-- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh` (and `sync-dogfood-mavis.sh` / `sync-dogfood-opencode.sh` when those platforms changed), or document an intentional skip, when maintaining this monorepo
+- [ ] **Dogfood:** run `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-claude.sh`, `sync-dogfood-mavis.sh`, and `sync-dogfood-opencode.sh` when those platforms changed, or document an intentional skip, when maintaining this monorepo
 - [ ] **shared-core drift:** for embed-mode stems, run `packages/ai-rules/scripts/check-shared-core-drift.sh` (or document intentional fork)
 
 ## Pointers
@@ -36,6 +36,6 @@ Checklist for PRs that touch `packages/ai-rules/presets/**` (and dogfood `.curso
 - Budget: `preset-token-budget`
 - Leakage: `preset-no-cross-stack-leakage`
 - Validation: stack `agents/build-verifier.md` → preset-structure section
-- Dogfood scripts: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-mavis.sh`, `sync-dogfood-opencode.sh`
+- Dogfood scripts: `packages/ai-rules/scripts/sync-dogfood-cursor.sh`, `sync-dogfood-claude.sh`, `sync-dogfood-mavis.sh`, `sync-dogfood-opencode.sh`
 - Drift script: `packages/ai-rules/scripts/check-shared-core-drift.sh`
 - Orchestrator: when editing presets, load this checklist + twin-sync

package/presets/claude/nuxt/settings.json

@@ -12,5 +12,28 @@
       "Bash(npx *)",
       "Bash(pnpm *)"
     ]
+  },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard-shell-command.sh"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/chain-team-phases.sh"
+          }
+        ]
+      }
+    ]
   }
 }

package/presets/claude/php-hexagonal/CLAUDE.md

@@ -4,7 +4,8 @@ Preset for PHP backends using ports & adapters (PSR / Composer-first).
 
 **Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root.
 
-- Session-start: `php-app-core`, `architecture/boundaries`, `code-quality` (3–5).
+- Session-start: `php-app-core`, `architecture/boundaries`, `code-quality`, `ai-local-overlay` (3–5).
+- **Local overlay (session-start):** `ai-local-overlay` has no `paths:` and counts in the 3–5 budget. On every turn, probe `ls -la .ai.local`, apply `.ai.local/rules/*.md` and `.ai.local/conventions.md`, and acknowledge `Using .ai.local: <rule-name>`. Guide: `docs/LOCAL-OVERLAY.md`.
 - Delivery: `architecture/feature-delivery.md` + skill `feature-delivery`.
 - After PHP edits: `tooling-and-review/post-change-test.md` (+ `php-tooling`).
 - Integration tests: agents `integration-test-*` + skill `integration-testing` (never Playwright/XCUITest).
@@ -41,3 +42,4 @@ Init: `npx @bonesofspring/ai-rules init claude --preset php-hexagonal` (also cop
   `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.
+- **Pipeline hooks:** `.claude/settings.json` `hooks` wires `guard-shell-command.sh` (`PreToolUse` / `Bash`, `permissionDecision` `ask` or `allow`) and `chain-team-phases.sh` (`SubagentStop` for kebab-case `agent_type`). See `hooks/README.md`. No `hooks.json`.

package/presets/claude/php-hexagonal/REPO_AGENTS.md

@@ -70,4 +70,4 @@ A `.ai.local/` directory MAY exist at the repo root or at any nesting depth in m
 
 Plain markdown rules under `.ai.local/rules/*.md` are read by the agent with higher priority than preset rules. Living gotchas live in `.ai.local/conventions.md`.
 
-Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule (always-on for Cursor, on-demand for Claude) is the mechanism; this `MANDATORY` section is the reinforcement.
+On every turn, probe `ls -la .ai.local`, apply `.ai.local/rules/*.md` and `.ai.local/conventions.md`, and acknowledge `Using .ai.local: <rule-name>`. Authoring guide: `docs/LOCAL-OVERLAY.md` in the `@bonesofspring/ai-rules` package. The `ai-local-overlay` rule is always-on on Cursor and session-start on Claude (no `paths:`). Mavis and OpenCode have no native `alwaysApply`; this section plus the platform entry's essential-rules list is the reinforcement.

package/presets/claude/php-hexagonal/hooks/README.md

@@ -5,12 +5,13 @@
 | `chain-team-phases.sh` | Pipeline chaining after subagent stop (`TEAM_ROOT=.ai.local/team`) |
 | `guard-shell-command.sh` | Destructive git / JS package-manager guard; **allows** `composer test / vendor/bin/phpunit` / `compiler/IDE inspections` / `configured static analysis` / `repo static analysis` |
 
-Claude Code may not use Cursor `hooks.json`. Wire scripts per project docs when enabling agent-team auto-chain.
+No `hooks.json`. Default chain and shell guard are registered in `.claude/settings.json` (see **Shipped wiring**). Cookbook scripts in `hooks/examples/` stay unwired; keep stack-safe recipes (this preset: **php-hexagonal**).
 
-**No `hooks.json` in Claude preset** (platform limit — same as next Claude).
+## Shipped wiring (Claude Code settings)
 
-## Optional cookbook
+`.claude/settings.json` `hooks` (https://code.claude.com/docs/en/hooks) registers:
 
-Example scripts live in `hooks/examples/` (secret-guard, format-edited, test-on-save). They are **not** auto-enabled.
+- `PreToolUse` matcher `Bash` → `guard-shell-command.sh` (reads `tool_input.command`; emits `permissionDecision` `ask` or `allow`)
+- `SubagentStop` → `chain-team-phases.sh` (kebab-case `agent_type` maps to `status: completed`; empty or non-kebab types are ignored; `stop_hook_active` does not recurse)
 
-To wire in Claude Code: copy an `.example.sh` into `hooks/`, make executable, and register per [Claude Code hooks](https://code.claude.com/docs/en/hooks) for your project. Keep stack-safe recipes (this preset: **php-hexagonal**). Cursor twin examples under `presets/cursor/php-hexagonal/hooks/examples/` are the same allowlist forks.
+There is no `hooks.json`. Cookbook scripts under `hooks/examples/` stay unwired. A hook crash is not a deny (Cursor `failClosed` has no Claude field); `ask` is the supported review decision.

package/presets/claude/php-hexagonal/hooks/chain-team-phases.sh

@@ -23,6 +23,24 @@ try {
   process.exit(0);
 }
 
+// Claude Code SubagentStop has hook_event_name / agent_type / stop_hook_active, not status.
+// Kebab-case agent_type (preset roles) is the completed signal. Empty or non-kebab
+// types (Claude internal agents) do not advance the pipeline. stop_hook_active
+// means this hook already continued the turn — do not recurse.
+// Manual pipes of {"status":"completed"} skip this block.
+if (hookInput.hook_event_name === 'SubagentStop') {
+  if (hookInput.stop_hook_active === true) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+  const agentType = typeof hookInput.agent_type === 'string' ? hookInput.agent_type : '';
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(agentType)) {
+    process.stdout.write('{}');
+    process.exit(0);
+  }
+  if (hookInput.status == null) hookInput.status = 'completed';
+}
+
 if (hookInput.status !== 'completed') {
   process.stdout.write('{}');
   process.exit(0);

package/presets/claude/php-hexagonal/hooks/examples/README.md

@@ -10,6 +10,8 @@ Optional scripts under `hooks/examples/`. **Not** referenced from default `hooks
 
 ## Wiring (Claude Code)
 
+Default `.claude/settings.json` already registers `guard-shell-command.sh` on `PreToolUse` (matcher `Bash`) and `chain-team-phases.sh` on `SubagentStop`. Cookbook scripts are not in that default set.
+
 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`.
@@ -17,4 +19,4 @@ Claude Code has no preset `hooks.json`; hooks are registered in `.claude/setting
 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: **go** — recipes must stay stack-safe (no cross-stack lint/test commands).
+Stack: **php-hexagonal** — recipes must stay stack-safe (no cross-stack lint/test commands).

package/presets/claude/php-hexagonal/hooks/guard-shell-command.sh

@@ -20,20 +20,43 @@ try {
   process.exit(0);
 }
 
-const command = String(event.command || event.input?.command || '');
-if (!command.trim()) {
-  process.stdout.write('{ "permission": "allow" }');
-  process.exit(0);
-}
+const claudePreTool = event.hook_event_name === 'PreToolUse';
+const command = String(
+  event.command
+  || (event.input && event.input.command)
+  || (event.tool_input && event.tool_input.command)
+  || '',
+);
 
-function out(permission, userMessage, agentMessage) {
+function out(permission, userMessage) {
+  if (claudePreTool) {
+    const decision = permission === 'ask' || permission === 'deny' ? permission : 'allow';
+    const hookSpecificOutput = {
+      hookEventName: 'PreToolUse',
+      permissionDecision: decision,
+    };
+    if (userMessage && decision !== 'allow') {
+      hookSpecificOutput.permissionDecisionReason = userMessage;
+    }
+    process.stdout.write(JSON.stringify({ hookSpecificOutput }));
+    return;
+  }
+  if (!userMessage) {
+    process.stdout.write('{ "permission": "allow" }');
+    return;
+  }
   process.stdout.write(JSON.stringify({
     permission,
     user_message: userMessage,
-    agent_message: agentMessage || userMessage,
+    agent_message: userMessage,
   }));
 }
 
+if (!command.trim()) {
+  out('allow');
+  process.exit(0);
+}
+
 const dangerousGit = /\bgit\s+(reset\s+--hard|clean\s+-[^\n]*f|push\s+--force|push\s+-f|checkout\s+--\s+)/;
 if (dangerousGit.test(command)) {
   out(
@@ -62,7 +85,7 @@ if (!expected && fs.existsSync('package.json')) {
 }
 
 if (!expected) {
-  process.stdout.write('{ "permission": "allow" }');
+  out('allow');
   process.exit(0);
 }
 
@@ -76,5 +99,5 @@ if (used && used !== expected) {
   process.exit(0);
 }
 
-process.stdout.write('{ "permission": "allow" }');
+out('allow');
 NODE

package/presets/claude/php-hexagonal/rules/README.md

@@ -12,7 +12,7 @@ Claude topic `.md` files are **derived** from Cursor SoT `presets/cursor/php-hex
 
 ## Loading budget
 
-- **Session-start (no `paths:`):** 3–5 — `php-app-core`, `boundaries`, `code-quality`
+- **Session-start (no `paths:`):** 3–5 — `php-app-core`, `boundaries`, `code-quality`, `ai-local-overlay`
 - All others — with `paths:`
 - **Twin depth:** domain rules target ≥15 body lines; thin aliases: `agent-team-intake`, `technical-retro`; **documented stub** (v1): `api-grpc`; `messaging-adapters` is full — see Cursor `presets/cursor/php-hexagonal/rules/README.md` Catalog (Depth column)