@bonesofspring/ai-rules 0.2.28 → 0.2.29

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+### Claude session-start overlay, settings hooks, and dogfood sync
+
+- Claude `ai-local-overlay` is session-start (no `paths:`) on all 10 stacks, inside the 3–5 budget, with entry-file probe text in `CLAUDE.md` and root `AGENTS.md`.
+- `.claude/settings.json` registers Claude Code hooks: `PreToolUse`/`Bash` → `guard-shell-command.sh`, `SubagentStop` → `chain-team-phases.sh`. There is still no `hooks.json`.
+- Mavis and OpenCode keep prompt-contract overlay loading (`nativeProjectRules` unknown / no-equivalent). `projectHooks` and the unverified Mavis workspace discovery fields are `manual`. Mavis `freshInit` stays `unknown`; MCP import stays `fallback-manual-import`.
+- Maintainers: `scripts/sync-dogfood-claude.sh` copies `presets/claude/<stack>` to `.claude/`.
+
 ### OpenCode re-init picks up preset rules; Claude ships `settings.json`
 
 - `init opencode` merges `opencode.json` by **unioning** preset `instructions` paths and **filling missing** `permission.bash` keys. Consumer extra paths and same-key overrides stay, including on re-init. An empty `instructions` array no longer blocks the preset list.

package/README.md

@@ -61,7 +61,7 @@ Optional check: `yarn check:product-specs <repo-root>` (WARN) or `--strict`.
 - Layers: [`presets/_shared/README.md`](presets/_shared/README.md)
 - Guide: [`docs/PRESET-CONTRIBUTION.md`](docs/PRESET-CONTRIBUTION.md)
 - Overlay: [`docs/LOCAL-OVERLAY.md`](docs/LOCAL-OVERLAY.md)
-- Dogfood: [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh) (and mavis/opencode siblings) — seeds `.ai.local/team`, preserves slugs
+- Dogfood: [`scripts/sync-dogfood-cursor.sh`](scripts/sync-dogfood-cursor.sh), [`scripts/sync-dogfood-claude.sh`](scripts/sync-dogfood-claude.sh), [`scripts/sync-dogfood-mavis.sh`](scripts/sync-dogfood-mavis.sh), [`scripts/sync-dogfood-opencode.sh`](scripts/sync-dogfood-opencode.sh) — seeds `.ai.local/team`, preserves slugs
 - Gates: `yarn check:preset-structure`
 
 `_shared` is not an installable `--preset`.

package/docs/MAVIS-COMPATIBILITY.md

@@ -41,8 +41,12 @@ write the operator's `~/.minimax/**`.
 
 ## Capability matrix
 
-Allowed status values are `confirmed`, `partial`, `unknown`, and
-`no-equivalent`. Architecture §1.3 unknowns stay `unknown` until a real `mcode`
+Allowed status values are `confirmed`, `partial`, `unknown`, `manual`, and
+`no-equivalent`. `manual` is the published contract label when a live probe
+did not observe native auto-registration and consumers must follow the invoke
+steps in [`MAVIS.md`](./MAVIS.md). Probe JSON from
+`probe-mavis-capabilities.mjs` still records `unknown` for those rows.
+Architecture §1.3 unknowns stay `unknown` until a real `mcode`
 run produces reproducible evidence. Fake-executable results are not used to
 promote a row to `confirmed`.
 
@@ -55,15 +59,15 @@ promote a row to `confirmed`.
 | `mcode init` | `unknown` | `mcode init <workdir>` | Exit 1: interactive mode requires a TTY | Ship `REPO_AGENTS.md` → root `AGENTS.md`; do not depend on `init` |
 | Project rule discovery (no root reference) | `unknown` | `exec` with `rules/probe.md` on disk and no fixture `AGENTS.md` reference | Exec succeeded; rule sentinel absent | Explicit root `AGENTS.md` reference; `.mavis/rules/**` is ai-rules-owned |
 | Project rule discovery (explicit root reference) | `confirmed` | Root `AGENTS.md` references `rules/probe.md` | `MAVIS_RULE_SENTINEL` returned | Explicit reference |
-| Workspace agent discovery | `unknown` | `exec` without `--file` while `agents/probe-agent.md` is on disk | Exec succeeded; agent sentinel absent | Explicit `--file` |
-| Workspace Skill discovery (no root reference) | `unknown` | `exec` with skill on disk and no root reference | Exec succeeded; skill sentinel absent | Explicit root reference |
+| Workspace agent discovery | `manual` (probe: `unknown`) | `exec` without `--file` while `agents/probe-agent.md` is on disk | Exec succeeded; agent sentinel absent | Explicit `--file` |
+| Workspace Skill discovery (no root reference) | `manual` (probe: `unknown`) | `exec` with skill on disk and no root reference | Exec succeeded; skill sentinel absent | Explicit root reference |
 | Workspace Skill discovery (explicit root reference) | `confirmed` | Root `AGENTS.md` references `skills/probe/SKILL.md` | `MAVIS_SKILL_SENTINEL` returned | Explicit reference |
 | Plugin Skill format | `confirmed` | Official plugin documentation | `skills/**/SKILL.md` is documented inside plugin packages | Optional plugin packaging remains deferred |
 | Plugin MCP format | `confirmed` | Official plugin and MCP documentation | Plugin `*.mcp.json` is documented | Optional plugin packaging remains deferred |
 | Project-scoped MCP path | `unknown` | Documented inspection only: `mcode mcp list --human`, `mcode mcp tools <server>`, `mcode mcp auth status` | No automated command was run; no global config was read or written | Repo-local `.mavis/mcp.json` staging plus manual import |
-| Project hooks / completion callback | `unknown` | Desktop/manual documentation inspection | No native path or event schema is assumed | Explicit manual/semi-auto chain runner |
+| Project hooks / completion callback | `manual` (probe: `unknown`) | Desktop/manual documentation inspection | No native path or event schema is assumed | Explicit manual/semi-auto chain runner |
 | External `pipeline.json` ingestion | `unknown` | Native Team manual checklist | Not run | File pipeline remains the audit source of truth |
-| File-defined slash commands | `unknown` | Desktop/manual inspection | No registration API is assumed | Natural-language procedure plus explicit `exec --file` |
+| File-defined slash commands | `manual` (probe: `unknown`) | Desktop/manual inspection | No registration API is assumed | Natural-language procedure plus explicit `exec --file` |
 | Native Team | `partial` | Official Team documentation | Leader/Worker/Verifier are documented; bridge controls are unverified | Semi-auto file lifecycle |
 
 Official documentation used for the confirmed plugin rows and the partial Team

package/docs/MAVIS.md

@@ -67,13 +67,22 @@ printf '%s\n' '{"status":"completed","attemptId":"<from-status.json>"}' \
   | bash .mavis/hooks/chain-team-phases.sh
 ```
 
-Human gates pause with `awaitingHumanGate: true` in `status.json`. Resume via `.mavis/commands/task-continue.md` (invokes hook action `end_human_gate`). There is **no** shipped `hooks.json` — project hooks are **unknown** on MiniMax; this is intentional semi-auto fallback.
+Human gates pause with `awaitingHumanGate: true` in `status.json`. Resume via `.mavis/commands/task-continue.md` (invokes hook action `end_human_gate`). There is **no** shipped `hooks.json`. Project hooks are **manual** on MiniMax (`platform-contract.json`: `projectHooks: manual`): after a producer receipt, pipe the JSON above into `bash .mavis/hooks/chain-team-phases.sh`. This is the semi-auto fallback.
 
 Full team layout: `.ai.local/team/README.md`.
 
+## First run (`init mavis`)
+
+`freshInit` stays **unknown**. `mcode init` requires a TTY (compatibility probe: exit 1, interactive mode). This package does not verify that a fresh `npx @bonesofspring/ai-rules init mavis` is picked up by a live MiniMax session. Use the ai-rules CLI, then:
+
+1. Read root `AGENTS.md` and `.mavis/AGENTS.md` (prompt contract; `nativeProjectRules` is unknown — do not claim `alwaysApply`).
+2. Probe `ls -la .ai.local` and apply `.ai.local/rules/*.md` plus `.ai.local/conventions.md`.
+3. Import MCP by hand (`fallback-manual-import`): open `.mavis/mcp.json` in the MiniMax Code UI and enable the staged servers. Project MCP auto-load is **unknown**. The CLI never writes `~/.minimax/**`.
+4. Invoke procedures with `mcode exec --file .mavis/commands/task.md` and roles with `mcode exec --file .mavis/agents/<role>.md`. After a producer receipt, pipe `{"status":"completed"}` into `bash .mavis/hooks/chain-team-phases.sh`. There is no `hooks.json`.
+
 ## MCP
 
-Preset servers are staged in **`.mavis/mcp.json`** only. Import or enable them in the MiniMax Code UI (project MCP path is **unknown** — do not assume auto-load). Extra local servers survive re-init when the file is valid JSON (same merge rules as Cursor/Claude). See `.mavis/MCP.md` and rule `mcp-usage.md`.
+Preset servers are staged in **`.mavis/mcp.json`** only. Import or enable them in the MiniMax Code UI (`fallback-manual-import`; project MCP path is **unknown** — do not assume auto-load). Extra local servers survive re-init when the file is valid JSON (same merge rules as Cursor/Claude). See `.mavis/MCP.md` and rule `mcp-usage.md`.
 
 ## Capability summary
 
@@ -85,10 +94,10 @@ Honest labels from WP-A probe. Full matrix: [`MAVIS-COMPATIBILITY.md`](./MAVIS-C
 | `mcode exec --file` | **confirmed** | Attach agents/commands |
 | Referenced rule/skill | **confirmed** | When root entry points at `.mavis/rules/` or `.mavis/skills/` |
 | Structured JSON output | **confirmed** | Parse `exec.result` wrapper |
-| Project rules/agents/skills (no reference) | **unknown** | Explicit paths only |
-| `mcode init` | **unknown** | TTY-only; use `ai-rules init mavis` |
-| Project MCP auto-load | **unknown** | `.mavis/mcp.json` + manual import |
-| Project hooks / slash commands | **unknown** | Manual chain + `exec --file` |
+| Project rules/agents/skills (no reference) | **manual** (probe unknown) | Explicit paths only; not `alwaysApply` |
+| `mcode init` / `freshInit` | **unknown** | TTY-only; a live first `init mavis` is not verified |
+| Project MCP auto-load | **unknown** | `.mavis/mcp.json` + `fallback-manual-import` |
+| Project hooks / slash commands | **manual** | Chain script and `mcode exec --file`; not auto-registered |
 | Native Team lifecycle | **partial** | File pipeline is SoT; hook is single lifecycle writer |
 
 Desktop/CLI versions in the compatibility doc are **operator snapshots**, not package pins.

package/docs/OPENCODE-COMPATIBILITY.md

@@ -21,7 +21,7 @@ Official docs used:
 
 ## Capability matrix
 
-Allowed status values are `confirmed`, `partial`, `unknown`, and `no-equivalent`. `unknown` / `no-equivalent` must not declare `nativePath`.
+Allowed status values are `confirmed`, `partial`, `unknown`, `manual`, and `no-equivalent`. `unknown` / `no-equivalent` / `manual` must not declare `nativePath`. `manual` means this preset does not auto-register the capability; follow the invoke steps in [`OPENCODE.md`](./OPENCODE.md).
 
 | Capability | Status | Evidence | Observation | Selected fallback |
 |---|---|---|---|---|
@@ -35,7 +35,7 @@ Allowed status values are `confirmed`, `partial`, `unknown`, and `no-equivalent`
 | Workspace agent discovery | `confirmed` | opencode.ai/docs/agents | `.opencode/agents/` | Native |
 | Workspace Skill discovery | `confirmed` | opencode.ai/docs/skills | `.opencode/skills/<name>/SKILL.md` | Native `skill` tool |
 | Project MCP | `confirmed` | opencode.ai/docs/mcp-servers | `opencode.json` `mcp` | Merge on init |
-| Project hooks (`hooks.json`) | `unknown` | plugins exist; this preset does not ship them | No `subagentStop` analog | Manual `chain-team-phases.sh` |
+| Project hooks (`hooks.json`) | `manual` | plugins exist; this preset does not ship them | No confirmed `subagentStop` analog was opened | Manual `chain-team-phases.sh` |
 | Slash commands | `confirmed` | opencode.ai/docs/commands | `.opencode/commands/<name>.md` | Native `/task` |
 | Plugin / skill / MCP combo | `confirmed` | skills + mcp docs | MCP inflates context | Gate unused servers in operator config |
 | Native Team lifecycle | `partial` | file pipeline is ai-rules SoT | No native team runtime | Hook owns `status.json` / `metrics.json` |

package/docs/OPENCODE.md

@@ -101,7 +101,7 @@ Labels from official OpenCode docs (live CLI probe not yet run). Full matrix: [`
 | `.opencode/agents` / `skills` / `commands` | **confirmed** (docs) | Native discovery |
 | `opencode.json` MCP | **confirmed** (docs) | Merge `mcp` |
 | Glob / alwaysApply rules | **no-equivalent** | Lazy Read catalog under `.opencode/rules/` |
-| `hooks.json` / subagentStop | **unknown** | Manual `chain-team-phases.sh` |
+| `hooks.json` / subagentStop | **manual** | `bash .opencode/hooks/chain-team-phases.sh` after receipts; no plugin in v1 |
 | Native Team lifecycle | **partial** | File pipeline is SoT; hook is single lifecycle writer |
 
 Do not pin OpenCode CLI or TUI versions in the contract.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bonesofspring/ai-rules",
-  "version": "0.2.28",
+  "version": "0.2.29",
   "description": "Presets of Cursor, Claude, Mavis, and OpenCode rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",

package/presets/_shared/core/meta/preset-pr-checklist.md

@@ -19,7 +19,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
@@ -29,6 +29,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/android-kotlin/CLAUDE.md

@@ -9,7 +9,8 @@ See @rules/README.md for mapping and loading strategy.
 ## Conventions
 
 - One topic per file; path scope — frontmatter `paths:`.
-- **Session-start rules** (no `paths:`) — exactly **three**: `android-app-core`, `boundaries`, `code-quality`.
+- **Session-start rules** (no `paths:`) — 3–5: `android-app-core`, `boundaries`, `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`.
 - Requestable / paths: orchestrator, intake, feature-delivery, code-review, post-change-build, gradle-tooling, reference-features, security-android, technical-retro, domain globs.
 - Slash commands — `commands/`; skills — `skills/`; subagents — `agents/`.
 
@@ -48,3 +49,4 @@ Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `skills/**`, `hooks/
   `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/android-kotlin/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/android-kotlin/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 / package-manager guard; **allows** `./gradlew` / `simctl` / `xcrun` |
 
-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: **android-kotlin**).
 
-**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: **android-kotlin**). Cursor twin examples under `presets/cursor/android-kotlin/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/android-kotlin/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/android-kotlin/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/android-kotlin/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/android-kotlin/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:`):** 3–5 — `android-app-core`, `boundaries`, `code-quality` (≤200 body lines total)
+- **Session-start (no `paths:`):** 3–5 — `android-app-core`, `boundaries`, `code-quality` (≤200 body lines total), `ai-local-overlay`
 - **Everything else** — with `paths:`
 - **Soft twin depth:** domain rules ≥15 body lines; thin aliases (`agent-team-intake`, `technical-retro`) may be shorter
 

package/presets/claude/android-kotlin/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/android-kotlin/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/android-kotlin/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/go/CLAUDE.md

@@ -4,7 +4,8 @@ Preset for Go backends using ports & adapters.
 
 **Repo-root agents:** see [`AGENTS.md`](../../AGENTS.md) at the project root.
 
-- Session-start: `go-app-core`, `architecture/boundaries`, `code-quality` (3–5).
+- Session-start: `go-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 Go edits: `tooling-and-review/post-change-test.md`.
 - Integration tests: agents `integration-test-*` (never Playwright/XCUITest).
@@ -24,3 +25,4 @@ Init: `npx @bonesofspring/ai-rules init claude --preset go` (also copies `REPO_A
   `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/go/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/go/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** `go test` / `go vet` / `golangci-lint` / `staticcheck` |
 
-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: **go**).
 
-**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: **go**). Cursor twin examples under `presets/cursor/go/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/go/hooks/chain-team-phases.sh

@@ -22,6 +22,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/go/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/go/hooks/guard-shell-command.sh

@@ -19,20 +19,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(
@@ -61,7 +84,7 @@ if (!expected && fs.existsSync('package.json')) {
 }
 
 if (!expected) {
-  process.stdout.write('{ "permission": "allow" }');
+  out('allow');
   process.exit(0);
 }
 
@@ -75,5 +98,5 @@ if (used && used !== expected) {
   process.exit(0);
 }
 
-process.stdout.write('{ "permission": "allow" }');
+out('allow');
 NODE

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

@@ -12,7 +12,7 @@ Claude topic `.md` files are **derived** from Cursor SoT `presets/cursor/go/rule
 
 ## Loading budget
 
-- **Session-start (no `paths:`):** 3–5 — `go-app-core`, `boundaries`, `code-quality`
+- **Session-start (no `paths:`):** 3–5 — `go-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`; checklist **stubs** documented in Cursor `presets/cursor/go/rules/README.md` Catalog (Depth column)
 

package/presets/claude/go/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/go/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/go/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/ios-swift/CLAUDE.md

@@ -9,7 +9,8 @@ See @rules/README.md for mapping and loading strategy.
 ## Conventions
 
 - One topic per file; path scope — frontmatter `paths:`.
-- **Session-start rules** (no `paths:`) — exactly **three**: `ios-app-core`, `boundaries`, `code-quality`.
+- **Session-start rules** (no `paths:`) — 3–5: `ios-app-core`, `boundaries`, `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`.
 - Requestable / paths: orchestrator, intake, feature-delivery, code-review, post-change-build, xcode-tooling, reference-features, security-ios, technical-retro, domain globs.
 - Slash commands — `commands/`; skills — `skills/`; subagents — `agents/`.
 
@@ -48,3 +49,4 @@ Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `skills/**`, `hooks/
   `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`.