@bonesofspring/ai-rules 0.2.27 → 0.2.29

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## 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.
+- Claude presets now include `presets/claude/<stack>/settings.json` (harness `permissions.deny` / `ask`). `init claude` copies it to `.claude/settings.json` and overwrites that file on re-init.
+
 ### Over-abstraction guardrails + aligned always-on budget
 
 - **Shared core** `quality/code-quality-and-refactoring` gains an **Over-abstraction guardrails** section: no unnecessary constants, no invented one-off utilities (Rule of Three), decompose over conditionals. Propagated to all 10 stacks (Cursor + Claude; Mavis / OpenCode regenerated).

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/bin/cli.js

@@ -73,7 +73,7 @@ Notes:
   on shipped keys are preserved unless the preset defines them. Invalid / non-object JSON is
   copied to a timestamped *.bak.* then replaced with the preset file. JSONC is not supported).
   Cursor init copies rules, commands, agents, hooks, skills, hooks.json, BUGBOT.md, AGENTS.md → .cursor/AGENTS.md, MCP.md, mcp.json → .cursor/mcp.json.
-  Claude init copies rules, commands, skills, agents, hooks, CLAUDE.md, MCP.md, and mcp.json → .mcp.json (project root).
+  Claude init copies rules, commands, skills, agents, hooks, CLAUDE.md, settings.json (harness-level denials), MCP.md, and mcp.json → .mcp.json (project root).
   All init targets seed .ai.local/team/ (shared pipeline artifacts; never overwritten task slugs; not removed by clean)
   and .ai.local/conventions.md (living gotchas; seeded from the preset template only when absent, never overwritten).
   Because .ai.local/team/ is shared, ANY init consolidates every legacy .cursor|.claude|.mavis|.opencode/team/ into it,
@@ -505,7 +505,7 @@ function readInstallManifest(cwd, toolRoot) {
 /** Markers that mean a tool install is still present (directory leftovers do not count). */
 const TOOL_INSTALL_MARKERS = {
   '.cursor': ['.cursor/AGENTS.md', '.cursor/hooks.json', '.cursor/rules'],
-  '.claude': ['.claude/CLAUDE.md', '.claude/rules'],
+  '.claude': ['.claude/CLAUDE.md', '.claude/rules', '.claude/settings.json'],
   '.mavis': ['.mavis/.ai-rules-install.json', '.mavis/AGENTS.md'],
   '.opencode': ['.opencode/.ai-rules-install.json', '.opencode/AGENTS.md'],
 };
@@ -781,6 +781,17 @@ function cmdInit(tool, preset, cwdOption) {
       }
     }
 
+    if (tool === 'claude') {
+      const settingsFrom = path.join(base, 'settings.json');
+      if (fs.existsSync(settingsFrom)) {
+        const destAbs = path.join(toolRootAbs, 'settings.json');
+        fs.copyFileSync(settingsFrom, destAbs);
+        createdPaths.add(destAbs);
+        console.log(`Copied settings.json → ${toolRoot}/settings.json`);
+        copiedSteps++;
+      }
+    }
+
     if (cfg.mcpJsonSrc && cfg.mcpJsonDest) {
       const mcpFrom = path.join(base, cfg.mcpJsonSrc);
       if (fs.existsSync(mcpFrom)) {

package/bin/lib/seed-ai-local-team.js

@@ -255,6 +255,43 @@ function seedConventions(presetTeamSrc, cwd) {
   return true;
 }
 
+/**
+ * Seed `.ai.local/rules-library/` from `presets/<opt>/<stack>/ai-local/rules-library/`.
+ * Opt-in discipline rules the consumer enables by moving a file into
+ * `.ai.local/rules/` (consumer-owned; never overwritten).
+ *
+ * Refuses symlinks anywhere along the source path so `rmSync` and copy
+ * can't escape the install scope.
+ */
+function seedAiLocalRules(presetTeamSrc, cwd) {
+  if (!presetTeamSrc) {
+    return false;
+  }
+  const libraryDir = path.join(path.dirname(presetTeamSrc), 'ai-local', 'rules-library');
+  if (!fs.existsSync(libraryDir) || !fs.statSync(libraryDir).isDirectory()) {
+    return false;
+  }
+  const destDir = path.join(cwd, '.ai.local', 'rules-library');
+  assertSafeDest(cwd, destDir, '.ai.local/rules-library');
+  let copied = 0;
+  let skipped = 0;
+  for (const entry of fs.readdirSync(libraryDir)) {
+    if (!entry.endsWith('.md')) continue;
+    const src = path.join(libraryDir, entry);
+    const dest = path.join(destDir, entry);
+    if (fs.existsSync(dest)) {
+      skipped += 1;
+      continue;
+    }
+    copyFile(src, dest);
+    copied += 1;
+  }
+  if (copied > 0) {
+    console.log(`Seeded .ai.local/rules-library/ (${copied} rules; ${skipped} already present)`);
+  }
+  return copied > 0;
+}
+
 /**
  * Resolve a legacy `.<tool>/team` directory, refusing symlinks and anything whose
  * real path escapes the resolved `cwd`. `rmSync` through a link would delete the
@@ -392,7 +429,7 @@ function migrateLegacyTeams(cwd, dest) {
 
 /**
  * @param {{ cwd: string, presetTeamSrc?: string }} options
- * @returns {{ created: boolean, migrated: boolean, refreshed: boolean, conventionsSeeded: boolean }}
+ * @returns {{ created: boolean, migrated: boolean, refreshed: boolean, conventionsSeeded: boolean, rulesLibrarySeeded: boolean }}
  */
 function seedAiLocalTeam({ cwd, presetTeamSrc }) {
   const dest = destTeamRoot(cwd);
@@ -408,13 +445,14 @@ function seedAiLocalTeam({ cwd, presetTeamSrc }) {
 
   if (!destExisted && !hadLegacy && (!presetTeamSrc || !fs.existsSync(presetTeamSrc))) {
     console.log('Skipped .ai.local/team seed (preset team/ missing)');
-    return { created: false, migrated: false, refreshed: false, conventionsSeeded: false };
+    return { created: false, migrated: false, refreshed: false, conventionsSeeded: false, rulesLibrarySeeded: false };
   }
 
   fs.mkdirSync(dest, { recursive: true });
   const migrated = migrateLegacyTeams(cwd, dest);
   copyTemplates(presetTeamSrc, dest);
   const conventionsSeeded = seedConventions(presetTeamSrc, cwd);
+  const rulesLibrarySeeded = seedAiLocalRules(presetTeamSrc, cwd);
 
   if (migrated) {
     console.log('Migrated legacy .{tool}/team → .ai.local/team');
@@ -422,7 +460,7 @@ function seedAiLocalTeam({ cwd, presetTeamSrc }) {
 
   if (!destExisted && !hadLegacy) {
     console.log('Seeded .ai.local/team/');
-    return { created: true, migrated: false, refreshed: false, conventionsSeeded };
+    return { created: true, migrated: false, refreshed: false, conventionsSeeded, rulesLibrarySeeded };
   }
 
   if (destHasSlugs || destExisted) {
@@ -431,10 +469,10 @@ function seedAiLocalTeam({ cwd, presetTeamSrc }) {
         ? 'Refreshed .ai.local/team templates (tasks preserved)'
         : 'Refreshed .ai.local/team (no consumer task slugs)',
     );
-    return { created: false, migrated, refreshed: true, conventionsSeeded };
+    return { created: false, migrated, refreshed: true, conventionsSeeded, rulesLibrarySeeded };
   }
 
-  return { created: false, migrated, refreshed: false, conventionsSeeded };
+  return { created: false, migrated, refreshed: false, conventionsSeeded, rulesLibrarySeeded };
 }
 
 module.exports = { seedAiLocalTeam, destTeamRoot };

package/bin/opencode-install.js

@@ -190,6 +190,57 @@ function mergeServerEntry(existingEntry, presetEntry) {
   return merged;
 }
 
+function stringList(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+
+function mergeInstructionList(existingInstructions, presetInstructions) {
+  const presetList = stringList(presetInstructions);
+  if (existingInstructions == null) {
+    return presetList.length > 0 ? presetList : undefined;
+  }
+  if (!Array.isArray(existingInstructions)) {
+    return existingInstructions;
+  }
+  const merged = [];
+  const seen = new Set();
+  for (const item of existingInstructions) {
+    if (typeof item === 'string') {
+      if (seen.has(item)) continue;
+      seen.add(item);
+    }
+    merged.push(item);
+  }
+  for (const item of presetList) {
+    if (seen.has(item)) continue;
+    seen.add(item);
+    merged.push(item);
+  }
+  return merged;
+}
+
+function mergePermission(existingPermission, presetPermission) {
+  const presetPerm = isPlainObject(presetPermission) ? presetPermission : null;
+  const presetBash = presetPerm && isPlainObject(presetPerm.bash) ? presetPerm.bash : null;
+  if (existingPermission == null) {
+    if (!presetPerm) return undefined;
+    return presetBash ? { ...presetPerm, bash: { ...presetBash } } : { ...presetPerm };
+  }
+  if (!isPlainObject(existingPermission) || !presetBash) {
+    return existingPermission;
+  }
+  const merged = { ...existingPermission };
+  if (merged.bash == null) {
+    merged.bash = { ...presetBash };
+    return merged;
+  }
+  if (!isPlainObject(merged.bash)) {
+    return merged;
+  }
+  merged.bash = { ...presetBash, ...merged.bash };
+  return merged;
+}
+
 function mergeOpencodeConfig(presetObj, existingObj) {
   const preset = isPlainObject(presetObj) ? presetObj : {};
   const existing = isPlainObject(existingObj) ? existingObj : {};
@@ -207,6 +258,13 @@ function mergeOpencodeConfig(presetObj, existingObj) {
     merged.$schema = preset.$schema;
   }
   merged.mcp = mergedMcp;
+  // Re-init re-asserts preset instruction paths and missing bash keys so an
+  // upgrade is picked up. Consumer extras and same-key bash overrides stay.
+  // A non-array `instructions` or non-object `permission` is left untouched.
+  const instructions = mergeInstructionList(merged.instructions, preset.instructions);
+  if (instructions !== undefined) merged.instructions = instructions;
+  const permission = mergePermission(merged.permission, preset.permission);
+  if (permission !== undefined) merged.permission = permission;
   return { merged, extrasKept, existingServersInvalid };
 }
 

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,11 +35,11 @@ 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` |
-| `opencode.json` `instructions` globs | `unknown` | V1 docs load globs; V2 may not resolve | Do not depend on this field | `AGENTS.md` + explicit Read |
+| `opencode.json` `instructions` globs | `unknown` | V1 docs load globs; V2 may not resolve | Compact hedge for parent + per-agent "Rules to load" block is V2-safe | `AGENTS.md` + explicit Read (authoritative for subagents) |
 
 ## What we do not claim
 

package/docs/OPENCODE.md

@@ -23,7 +23,7 @@ What lands:
 | `OPENCODE.md` | `.opencode/AGENTS.md` (OpenCode load map) |
 | `rules/`, `agents/`, `skills/`, `commands/`, `hooks/` | `.opencode/<dir>/` |
 | `team/` | `.ai.local/team/` (shared pipeline artifacts; not `.opencode/team/`) |
-| `opencode.json` | `./opencode.json` (merge `mcp` only) |
+| `opencode.json` | `./opencode.json` (merge `mcp`; union preset `instructions`; fill missing `permission.bash` keys) |
 
 Remove only what this install owns:
 
@@ -31,7 +31,7 @@ Remove only what this install owns:
 npx @bonesofspring/ai-rules clean opencode
 ```
 
-`clean opencode` is **manifest-owned**: unchanged hashes are removed; files you edited stay. Without a valid `.opencode/.ai-rules-install.json`, clean is fail-safe (nothing removed). Extra keys in `opencode.json` (models, permissions, user MCP servers) are preserved.
+`clean opencode` is **manifest-owned**: unchanged hashes are removed; files you edited stay. Without a valid `.opencode/.ai-rules-install.json`, clean is fail-safe (nothing removed). Extra keys in `opencode.json` (models, user MCP servers, extra instruction paths) are preserved. Re-init still unions preset instruction paths and fills bash keys the file does not already set.
 
 The CLI **never** writes `~/.config/opencode/**`.
 
@@ -39,13 +39,23 @@ Quad-install with Cursor, Claude, or Mavis: `init multi --preset next` copies th
 
 ## How to load
 
-OpenCode has **no** `.mdc` `alwaysApply` / `globs` engine. Do **not** rely on `opencode.json` `instructions` as the only always-on path (V2 may ignore it).
+OpenCode has **no** `.mdc` `alwaysApply` / `globs` engine. The preset uses three mechanisms:
+
+| Mechanism | Role | V2-safe? |
+|-----------|------|----------|
+| Root `AGENTS.md` + `.opencode/AGENTS.md` | Always-on core (essential rules + entry maps) for the **parent** | yes |
+| `opencode.json` `instructions` | Compact hedge (`alwaysOn` paths + `.opencode/AGENTS.md`) for the **parent**; re-init unions preset paths into the consumer list | V1 yes, V2 uncertain (kept narrow) |
+| `## Rules to load (subagent context)` block in every `.opencode/agents/*.md` | Authoritative for **subagents** (`Task`/`@name`); alwaysOn + stack zone rules filtered to existing stems | yes |
+
+`bin/opencode-install.js` `mergeOpencodeConfig` on re-init **unions** preset `instructions` paths into the existing list and **fills missing** `permission.bash` keys. Extra consumer paths and same-key bash overrides stay. An empty `instructions: []` receives the preset paths. A non-array `instructions` value is left as-is.
 
 | Kind | How it loads |
 |------|----------------|
-| Essential rules | Root `AGENTS.md` lists four paths — **Read immediately** |
+| Essential rules | Root `AGENTS.md` + `.opencode/AGENTS.md` list four paths — **Read immediately** |
 | Other rules | Lazy `Read` of `.opencode/rules/<stem>.md` when the task matches |
-| Agents | Native `.opencode/agents/*.md` (`@name` / Task). `mode: subagent` |
+| Agents | Native `.opencode/agents/*.md` (`@name` / Task). `mode: subagent`. Each ships the **rules-to-load block** so subagents see the always-on + zone set |
+| MCP | `opencode.json` `mcp` — preset ships context7 / playwright / chrome-devtools / figma; merge keeps extras |
+| Harness enforcement | `opencode.json` `permission.bash` — universal `git commit/push deny` + JS-stack `npm/npx/pnpm/bun ask` + `npx jest* deny` |
 | Skills | Native `.opencode/skills/<name>/SKILL.md` (`skill` tool) |
 | Commands | Native `/task`, `/task-continue`, `/technical-retro`, `/spec-start` |
 | MCP | `opencode.json` → `mcp` |
@@ -91,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.27",
+  "version": "0.2.29",
   "description": "Presets of Cursor, Claude, Mavis, and OpenCode rules/commands for Revy Ross personal use",
   "license": "MIT",
   "author": "Revy Ross",
@@ -31,6 +31,7 @@
   ],
   "scripts": {
     "check:preset-structure": "bash scripts/check-preset-structure.sh",
+    "check:claude-agent-blocks": "node scripts/check-claude-agent-blocks.mjs",
     "check:preset-twin-map": "bash scripts/check-preset-twin-map.sh",
     "check:preset-token-budget": "bash scripts/check-preset-token-budget.sh",
     "check:preset-leakage": "bash scripts/check-preset-leakage.sh",

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/`.
 
@@ -36,3 +37,16 @@ npx @bonesofspring/ai-rules init claude --preset android-kotlin
 ```
 
 Copies `CLAUDE.md`, `rules/**`, `commands/**`, `agents/**`, `skills/**`, `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`**. Skill: `write-adr` (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.
+- **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/agents/accessibility-reviewer.md

@@ -5,6 +5,21 @@ readonly: false
 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/android-app-core.md`
+- `.claude/rules/architecture/boundaries.md` — layer boundaries and allowed imports
+- `.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 an accessibility reviewer for an **Android Kotlin / Jetpack Compose** (and View system where present) frontend.
 
 ## Inputs

package/presets/claude/android-kotlin/agents/api-contract-reviewer.md

@@ -5,6 +5,22 @@ readonly: false
 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/android-app-core.md`
+- `.claude/rules/architecture/boundaries.md` — layer boundaries and allowed imports
+- `.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/networking.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 **Android Kotlin** Feature module (`features/<name>/{api,impl}` — Domain / Data / Presentation).
 
 ## Inputs
@@ -67,4 +83,3 @@ Write the owned terminal receipt described under **Artifact contract**.
 If **MISALIGNED**, emit receipt outcome `changes_requested` when blocking implementation.
 
 Do not modify production code.
-

package/presets/claude/android-kotlin/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/android-app-core.md`
+- `.claude/rules/architecture/boundaries.md` — layer boundaries and allowed imports
+- `.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/gradle-tooling.md`
+- `.claude/rules/tooling-and-review/post-change-build.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You **validate** Android/Kotlin implementation quality — do not edit production code or tests.
 
 **SSOT for full validation:** use `tooling-and-review/gradle-tooling.md` + `tooling-and-review/post-change-build.md`. Run compile / configured lint / unit tests at CI parity even if the developer ran scoped checks.

package/presets/claude/android-kotlin/agents/ci-investigator.md

@@ -5,6 +5,31 @@ readonly: false
 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/android-app-core.md`
+- `.claude/rules/architecture/boundaries.md` — layer boundaries and allowed imports
+- `.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/ui-and-accessibility/compose.md`
+- `.claude/rules/stack/kotlin-conventions.md`
+- `.claude/rules/ui-and-accessibility/viewmodels.md`
+- `.claude/rules/ui-and-accessibility/navigation.md`
+- `.claude/rules/api-and-data/persistence.md`
+- `.claude/rules/architecture/module-public-api.md`
+- `.claude/rules/architecture/di-dagger-feature-holders.md`
+- `.claude/rules/api-and-data/networking.md`
+- `.claude/rules/tooling-and-review/gradle-tooling.md`
+- `.claude/rules/tooling-and-review/post-change-build.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are a CI failure investigator for an **Android Kotlin** project (Android Studio / AGP Cloud, GitHub Actions Android, or similar).
 
 Use the **`ci-investigation` skill** for the investigation loop.

package/presets/claude/android-kotlin/agents/code-reviewer.md

@@ -5,6 +5,22 @@ 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/android-app-core.md`
+- `.claude/rules/architecture/boundaries.md` — layer boundaries and allowed imports
+- `.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/code-review.md`
+
+Also read matching `.ai.local/rules/*.md` (local overlay) for the active zone, and the project strict rules if present.
+
 You are a senior Android / Kotlin / Jetpack Compose code reviewer. You may write only review artifacts under `.ai.local/team/**` and terminal receipts; do not modify production code.
 
 ## Inputs

package/presets/claude/android-kotlin/agents/codebase-analyzer.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/android-app-core.md`
+- `.claude/rules/architecture/boundaries.md` — layer boundaries and allowed imports
+- `.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 specialist at understanding HOW this Android codebase works. Document implementation details with precise `path:line` references.
 
 ## CRITICAL — explain as-is only