@lovrozagar/grunt 0.2.0 → 0.3.0

package/.rulesync/skills/solo/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: solo
+description: >
+  Session mode. /solo disables the grunt cascade for this session — one normal
+  agent, no spawn, no orchestrator. /cascade restores it. Unlike /parent and
+  /explain this IS a mode: it persists until /cascade or session end.
+---
+Session mode, not one-turn. Persists until `/cascade` or session end.
+
+This session: cascade suspended. You are one normal agent.
+
+- Do not spawn. No grunt|implementer|thinker.
+- No `[agent]:` recap. Answer the user directly.
+- No spawn-first rule. No `need:`/`verdict:` grammar.
+- Voice unchanged: `.rulesync/reference/output.md`. `/explain` is still the voice escape.
+
+Fat-tool caps stay on — token guards, not cascade.
+
+Claude/Codex/Grok: `/solo` via submit hook writes `.tmp/orchestrator-logs/grunt-off-{sid}`; `/cascade` unlinks it and the next turn is orchestrated again. Agents/Antigravity: instruction-only (this skill body); cannot create stamp via `/solo`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
+
+For advisory/design turns, debugging the cascade itself, or back-and-forth where spawning costs more than it saves.

package/.rulesync/subagents/grunt.md

@@ -27,18 +27,22 @@ antigravity-cli:
   inheritMcp: false
   commandExecutionPolicy: eager
   tools: [view_file, grep_search, run_command, replace_file_content]
+geminicli:
+  model: gemini-2.5-flash
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 
-Tools (shell/host; and more): Read, Grep, Glob, Bash, Write, Edit, Web. Git. Test runners (vitest, playwright, and similar). Other system tools. Commands of project dependencies. Installing and managing dependencies. Running dev, build, preview, deploys and similar.
+Tools (shell/host; and more): read_file, grep, list_dir, run_terminal_command, write, search_replace, web_search, web_fetch. Git. Test runners (vitest, playwright, and similar). Other system tools. Commands of project dependencies. Installing and managing dependencies. Running dev, build, preview, deploys and similar.
+You CAN run npm/git/bash via `run_terminal_command`. Do NOT wait on MCP. Do NOT request MCP for shell. `mcpInheritance: none` means no MCP — use shell/files instead.
 
 Run tools. Return output. Never spawn. Never implement complex/feature solutions (implementer agent). Never plan (thinker agent).
 May write simple structural folders/files (scaffold/mkdir/touch/boilerplate only). Not feature solutions.
 Low-reason write: mechanical/repetitive/obvious; volume OK.
+Scratch/tmp → `.tmp/grunt/` only (mkdir as needed). Never `.tmp/` root, `.tmp/plans/`, `.tmp/grunt/handoffs/`, or `.tmp/orchestrator-logs/`. Repo scaffold/mkdir/touch/boilerplate stays in the real tree.
 
 `job: search|exec` → first action `node scripts/grunt-job.mjs --job search|exec --query …`; whole reply = stdout.
 `job: test` → grunt-job; `FALLBACK` (exit 2) → LLM tools.
-`job: web` and messy test → LLM grunt (WebSearch/WebFetch).
+`job: web` and messy test → LLM grunt (web_search/web_fetch).
 Isolation/write reply ≤8 lines. Verdict grammar only — no dumps/recap/HTML/JSON/full logs:
 
 ```

package/.rulesync/subagents/implementer.md

@@ -26,6 +26,8 @@ antigravity-cli:
   inheritMcp: false
   commandExecutionPolicy: eager
   tools: [view_file, grep_search, run_command, replace_file_content]
+geminicli:
+  model: gemini-2.5-pro
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 

package/.rulesync/subagents/orchestrator.md

@@ -29,6 +29,8 @@ antigravity-cli:
   inheritMcp: false
   commandExecutionPolicy: eager
   tools: [view_file, grep_search, run_command]
+geminicli:
+  model: gemini-2.5-flash
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.

package/.rulesync/subagents/thinker.md

@@ -26,6 +26,8 @@ antigravity-cli:
   inheritMcp: false
   commandExecutionPolicy: eager
   tools: [view_file, grep_search]
+geminicli:
+  model: gemini-2.5-pro
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 

package/AGENTS.md

@@ -1,8 +1,9 @@
 Voice: `.rulesync/reference/output.md` once.
+All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
 Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not open first.
 Parent = orchestrator. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-First token = spawn. No try-then-spawn. No parent probe. After child: `[agent]:` echo only. No skip-spawn. /parent = one-turn.
+First token = spawn. No try-then-spawn. No parent probe. After child: `[agent]:` echo only. No skip-spawn. /parent = one-turn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`, recap `[handoff]:`.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. `timeout_ms=60000` every peek. GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.

package/CLAUDE.md

@@ -1,8 +1,9 @@
 Voice: `.rulesync/reference/output.md`
+All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
 Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not open first.
 Parent = this file not `.claude/agents/orchestrator.md`. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-First token = spawn. No try-then-spawn. No parent probe. After child: `[agent]:` echo only. No skip-spawn. /parent = one-turn.
+First token = spawn. No try-then-spawn. No parent probe. After child: `[agent]:` echo only. No skip-spawn. /parent = one-turn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`, recap `[handoff]:`.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. `timeout_ms=60000` every peek. GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.

package/README.md

@@ -17,7 +17,7 @@ Contributors to this repo only: local `npm i && npm test`.
 
 # GOAL
 
-- synced configs across all 4/5 major cli providers (grok build, claude code, codex, gemini cli, antigravity)! Emit matrix: grok/claude/codex/antigravity (`rulesync generate`). Gemini CLI is a tracked gap (not in generate).
+- synced configs across all 4/5 major cli providers (grok build, claude code, codex, gemini cli, antigravity)! Emit matrix: grok/claude/codex/antigravity (`rulesync generate`) then `emit-mcp-policy` + `emit-gemini` (`GEMINI.md`, `.gemini/agents/{id}/agent.md`; MCP `.gemini/settings.json`) + `emit-agent-shell-tools` (Claude grunt body `Bash`; other hosts `run_terminal_command`). No `-t geminicli`.
 - max situational speed relative to task intensity
 - max free token savings:
     maximally superterse without loosing value - sacrifice grammar for sake of concision
@@ -27,7 +27,7 @@ Contributors to this repo only: local `npm i && npm test`.
     context engineering
 - max reasoning and effort where needed and minimal reasoning and effort where not needed
 - agents:
-    - orchestrator (low model, low effort) -> always spawn+prompt; never user-facing tokens except `[agent]:` echo. `/parent` one-turn only.
+    - orchestrator (low model, low effort) -> always spawn+prompt; never user-facing tokens except `[agent]:` echo. `/parent` one-turn only; `/handoff` writes `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md` and hands the session to a fresh one.
 - subagents:
     - grunt (low model, low effort) -> tools. facts/search/exec/git/web/test/low-reason mechanical write. never feature solution. never spawn.
     - implementer (medium model, medium effort) -> write already-defined solution. does not plan or invent design. never spawn.

package/cli/init.mjs

@@ -7,10 +7,14 @@ const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
 
 const PRODUCT_SCRIPTS = [
   "check-globals.mjs",
+  "emit-agent-shell-tools.mjs",
+  "emit-gemini.mjs",
   "emit-mcp-policy.mjs",
   "gate-fat-tools.mjs",
+  "hooks-union.mjs",
   "grunt-job.mjs",
   "parse-need.mjs",
+  "persist-handoff.mjs",
   "persist-plan.mjs",
   "purge-global-mcps.mjs",
   "scrub-spawn-prompt.mjs",
@@ -21,7 +25,13 @@ const PRODUCT_SCRIPTS = [
 ]
 
 const COPY_DIRS = [".rulesync", ".grok", ".codex", ".claude", ".agents"]
-const COPY_FILES = ["AGENTS.md", "CLAUDE.md", ".mcp.json"]
+const GUARDED_MD_FILES = ["AGENTS.md", "CLAUDE.md"]
+// .mcp.json is intentionally not copied here: scripts/emit-mcp-policy.mjs
+// (run via `rulesync:generate`, see mergeClaudeSettings ordering) owns and
+// merges it, so a plain-copy would just be clobbered/redundant.
+const OWNED_HOOK_FILES = ["scrub-spawn-prompt.mjs", "gate-fat-tools.mjs", "orchestrate-parent.js"]
+const SENTINEL_BEGIN = "<!-- grunt:begin -->"
+const SENTINEL_END = "<!-- grunt:end -->"
 
 function sortKeys(obj) {
   return Object.fromEntries(Object.keys(obj).sort().map((k) => [k, obj[k]]))
@@ -48,6 +58,87 @@ export function mergeGitignore(dest) {
   fs.appendFileSync(gi, `${prefix}.tmp/\n`)
 }
 
+export function mergeGuardedMarkdown(dest, pkgRoot, file) {
+  const src = path.join(pkgRoot, file)
+  const d = path.join(dest, file)
+  if (samePath(src, d)) return
+  const srcText = fs.readFileSync(src, "utf8")
+
+  if (!fs.existsSync(d)) {
+    fs.writeFileSync(d, `${SENTINEL_BEGIN}\n${srcText}\n${SENTINEL_END}\n`)
+    return
+  }
+
+  const destText = fs.readFileSync(d, "utf8")
+  const hasSentinel = [SENTINEL_BEGIN, SENTINEL_END].every((marker) => destText.includes(marker))
+
+  if (!hasSentinel) {
+    const gruntFile = file.replace(/\.md$/, ".grunt.md")
+    fs.writeFileSync(path.join(dest, gruntFile), srcText)
+    console.log(`${file} exists without grunt sentinel; wrote ${gruntFile} instead (original untouched)`)
+    return
+  }
+
+  const beginIdx = destText.indexOf(SENTINEL_BEGIN)
+  const endIdx = destText.indexOf(SENTINEL_END)
+  const before = destText.slice(0, beginIdx)
+  const after = destText.slice(endIdx + SENTINEL_END.length)
+  fs.writeFileSync(d, `${before}${SENTINEL_BEGIN}\n${srcText}\n${SENTINEL_END}${after}`)
+}
+
+export function mergeClaudeSettings(destRoot, pkgRoot) {
+  const srcPath = path.join(pkgRoot, ".claude", "settings.json")
+  const destPath = path.join(destRoot, ".claude", "settings.json")
+
+  if (!fs.existsSync(destPath)) {
+    fs.mkdirSync(path.dirname(destPath), { recursive: true })
+    fs.copyFileSync(srcPath, destPath)
+    return
+  }
+
+  let destSettings
+  try {
+    destSettings = JSON.parse(fs.readFileSync(destPath, "utf8"))
+  } catch (err) {
+    throw new Error(`malformed JSON in ${destPath}: ${err.message}`)
+  }
+
+  const srcSettings = JSON.parse(fs.readFileSync(srcPath, "utf8"))
+  const isOwnedGroup = (group) =>
+    group.hooks.every((entry) => OWNED_HOOK_FILES.some((f) => entry.command.includes(f)))
+
+  const destHooks = { ...(destSettings.hooks || {}) }
+  for (const [event, srcGroups] of Object.entries(srcSettings.hooks)) {
+    const destGroups = destHooks[event] || []
+    destHooks[event] = [...destGroups.filter((group) => !isOwnedGroup(group)), ...srcGroups]
+  }
+  destSettings.hooks = destHooks
+
+  const destPerms = { ...(destSettings.permissions || {}) }
+  for (const key of ["deny", "allow"]) {
+    const destList = destPerms[key] || []
+    const srcList = srcSettings.permissions[key] || []
+    const seen = new Set(destList)
+    const merged = [...destList]
+    for (const item of srcList) {
+      if (!seen.has(item)) {
+        seen.add(item)
+        merged.push(item)
+      }
+    }
+    destPerms[key] = merged
+  }
+  destSettings.permissions = destPerms
+
+  for (const key of Object.keys(srcSettings)) {
+    if (key.toLowerCase().includes("mcp")) {
+      destSettings[key] = srcSettings[key]
+    }
+  }
+
+  fs.writeFileSync(destPath, `${JSON.stringify(destSettings, null, 2)}\n`)
+}
+
 export function mergePackageJson(dest, pkgRoot) {
   const destPath = path.join(dest, "package.json")
   let destPkg = {}
@@ -78,13 +169,21 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
     const src = path.join(pkgRoot, dir)
     const d = path.join(dest, dir)
     fs.mkdirSync(d, { recursive: true })
-    if (!samePath(src, d)) fs.cpSync(src, d, { recursive: true, force: true })
+    if (samePath(src, d)) continue
+    if (dir === ".claude") {
+      fs.cpSync(src, d, {
+        recursive: true,
+        force: true,
+        filter: (s) => path.basename(s) !== "settings.json",
+      })
+      mergeClaudeSettings(dest, pkgRoot)
+    } else {
+      fs.cpSync(src, d, { recursive: true, force: true })
+    }
   }
 
-  for (const file of COPY_FILES) {
-    const src = path.join(pkgRoot, file)
-    const d = path.join(dest, file)
-    if (!samePath(src, d)) fs.copyFileSync(src, d)
+  for (const file of GUARDED_MD_FILES) {
+    mergeGuardedMarkdown(dest, pkgRoot, file)
   }
 
   fs.mkdirSync(path.join(dest, "scripts"), { recursive: true })

package/cli/init.test.ts

@@ -4,7 +4,9 @@ import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   init,
+  mergeClaudeSettings,
   mergeGitignore,
+  mergeGuardedMarkdown,
   mergePackageJson,
   samePath,
 } from "./init.mjs";
@@ -23,13 +25,17 @@ function tmp(prefix: string) {
 }
 
 const COPY_DIRS = [".rulesync", ".grok", ".codex", ".claude", ".agents"];
-const COPY_FILES = ["AGENTS.md", "CLAUDE.md", ".mcp.json"];
+const GUARDED_MD_FILES = ["AGENTS.md", "CLAUDE.md"];
 const PRODUCT_FILES = [
   "check-globals.mjs",
+  "emit-agent-shell-tools.mjs",
+  "emit-gemini.mjs",
   "emit-mcp-policy.mjs",
   "gate-fat-tools.mjs",
+  "hooks-union.mjs",
   "grunt-job.mjs",
   "parse-need.mjs",
+  "persist-handoff.mjs",
   "persist-plan.mjs",
   "purge-global-mcps.mjs",
   "scrub-spawn-prompt.mjs",
@@ -38,6 +44,46 @@ const PRODUCT_FILES = [
   "telemetry.mjs",
 ];
 
+const SRC_CLAUDE_SETTINGS = {
+  permissions: {
+    deny: ["Agent(Explore)", "Agent(orchestrator)", "mcp__*"],
+  },
+  hooks: {
+    PreToolUse: [
+      {
+        matcher: "spawn",
+        hooks: [
+          {
+            type: "command",
+            command: 'node "${ROOT}/scripts/scrub-spawn-prompt.mjs"',
+          },
+        ],
+      },
+      {
+        matcher: "fat",
+        hooks: [
+          {
+            type: "command",
+            command: 'node "${ROOT}/scripts/gate-fat-tools.mjs"',
+          },
+        ],
+      },
+    ],
+    Stop: [
+      {
+        hooks: [
+          {
+            type: "command",
+            command: 'node "${ROOT}/.grok/hooks/orchestrate-parent.js"',
+          },
+        ],
+      },
+    ],
+  },
+  enableAllProjectMcpServers: false,
+  enabledMcpjsonServers: [],
+};
+
 function stubPkgRoot(pkg: Record<string, unknown> = {
   name: "fixture-pkg",
   scripts: {
@@ -57,8 +103,12 @@ function stubPkgRoot(pkg: Record<string, unknown> = {
     fs.mkdirSync(path.join(root, d));
     fs.writeFileSync(path.join(root, d, "marker"), d);
   }
-  for (const f of COPY_FILES) {
-    fs.writeFileSync(path.join(root, f), f);
+  fs.writeFileSync(
+    path.join(root, ".claude", "settings.json"),
+    `${JSON.stringify(SRC_CLAUDE_SETTINGS, null, 2)}\n`,
+  );
+  for (const f of GUARDED_MD_FILES) {
+    fs.writeFileSync(path.join(root, f), `${f} content`);
   }
   fs.mkdirSync(path.join(root, "scripts"));
   for (const name of PRODUCT_FILES) {
@@ -132,6 +182,205 @@ describe("mergeGitignore", () => {
   });
 });
 
+describe("mergeGuardedMarkdown", () => {
+  it("self: dest === src is a no-op", () => {
+    const dir = tmp("md-self-");
+    fs.writeFileSync(path.join(dir, "CLAUDE.md"), "raw content");
+    mergeGuardedMarkdown(dir, dir, "CLAUDE.md");
+    expect(fs.readFileSync(path.join(dir, "CLAUDE.md"), "utf8")).toBe("raw content");
+  });
+
+  it("dest absent: writes package copy wrapped in sentinels", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("md-absent-");
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8")).toBe(
+      "<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\n",
+    );
+  });
+
+  it("dest exists without sentinel: writes CLAUDE.grunt.md, leaves original untouched", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("md-nosentinel-");
+    fs.writeFileSync(path.join(dest, "CLAUDE.md"), "hand-written consumer doc\n");
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8")).toBe(
+      "hand-written consumer doc\n",
+    );
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.grunt.md"), "utf8")).toBe("CLAUDE.md content");
+    expect(logSpy).toHaveBeenCalledTimes(1);
+    expect(logSpy.mock.calls[0][0]).toContain("CLAUDE.grunt.md");
+    logSpy.mockRestore();
+  });
+
+  it("dest exists with sentinel: replaces only the marked region", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("md-sentinel-");
+    fs.writeFileSync(
+      path.join(dest, "CLAUDE.md"),
+      "before\n<!-- grunt:begin -->\nold generated stuff\n<!-- grunt:end -->\nafter\n",
+    );
+    mergeGuardedMarkdown(dest, pkgRoot, "CLAUDE.md");
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8")).toBe(
+      "before\n<!-- grunt:begin -->\nCLAUDE.md content\n<!-- grunt:end -->\nafter\n",
+    );
+    expect(fs.existsSync(path.join(dest, "CLAUDE.grunt.md"))).toBe(false);
+  });
+});
+
+describe("mergeClaudeSettings", () => {
+  it("dest .claude/settings.json absent: plain copy", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-absent-");
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out).toEqual(SRC_CLAUDE_SETTINGS);
+  });
+
+  it("malformed dest JSON throws with the path in the message", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-malformed-");
+    const destSettingsPath = path.join(destRoot, ".claude", "settings.json");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    fs.writeFileSync(destSettingsPath, "{ not valid json");
+    expect(() => mergeClaudeSettings(destRoot, pkgRoot)).toThrowError(
+      new RegExp(destSettingsPath.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")),
+    );
+  });
+
+  it("consumer hook group with only OWNED commands is replaced", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-owned-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: ["Agent(Explore)"] },
+        hooks: {
+          PreToolUse: [
+            {
+              matcher: "spawn",
+              hooks: [
+                {
+                  type: "command",
+                  command: 'node "${OLD_ROOT}/scripts/scrub-spawn-prompt.mjs"',
+                },
+              ],
+            },
+          ],
+        },
+        enableAllProjectMcpServers: true,
+        enabledMcpjsonServers: ["stale"],
+      }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out.hooks.PreToolUse).toEqual(SRC_CLAUDE_SETTINGS.hooks.PreToolUse);
+    expect(out.hooks.Stop).toEqual(SRC_CLAUDE_SETTINGS.hooks.Stop);
+    expect(out.enableAllProjectMcpServers).toBe(false);
+    expect(out.enabledMcpjsonServers).toEqual([]);
+  });
+
+  it("consumer hook group with only consumer commands survives", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-consumer-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    const consumerGroup = {
+      matcher: "custom",
+      hooks: [{ type: "command", command: "node scripts/my-custom-hook.mjs" }],
+    };
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: ["Agent(Explore)"] },
+        hooks: { PreToolUse: [consumerGroup] },
+      }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out.hooks.PreToolUse).toEqual([consumerGroup, ...SRC_CLAUDE_SETTINGS.hooks.PreToolUse]);
+    // event absent from dest entirely still gets appended
+    expect(out.hooks.Stop).toEqual(SRC_CLAUDE_SETTINGS.hooks.Stop);
+  });
+
+  it("MIXED group (one OWNED + one consumer command) survives intact", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-mixed-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    const mixedGroup = {
+      matcher: "mixed",
+      hooks: [
+        { type: "command", command: 'node "${OLD_ROOT}/scripts/gate-fat-tools.mjs"' },
+        { type: "command", command: "node scripts/my-custom-hook.mjs" },
+      ],
+    };
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: [] },
+        hooks: { PreToolUse: [mixedGroup] },
+      }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out.hooks.PreToolUse).toEqual([mixedGroup, ...SRC_CLAUDE_SETTINGS.hooks.PreToolUse]);
+  });
+
+  it("permissions.deny union does not grow on a second run (idempotency)", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-idempotent-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: ["Agent(Explore)", "Agent(orchestrator)"] },
+        hooks: {},
+      }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const first = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const second = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(second.permissions.deny).toEqual(first.permissions.deny);
+    expect(second.permissions.deny).toEqual([
+      "Agent(Explore)",
+      "Agent(orchestrator)",
+      "mcp__*",
+    ]);
+    expect(second.permissions.allow).toEqual(first.permissions.allow);
+  });
+
+  it("unknown consumer top-level key preserved; missing hooks/permissions default to empty", () => {
+    const pkgRoot = stubPkgRoot();
+    const destRoot = tmp("settings-unknown-key-");
+    fs.mkdirSync(path.join(destRoot, ".claude"), { recursive: true });
+    fs.writeFileSync(
+      path.join(destRoot, ".claude", "settings.json"),
+      JSON.stringify({ someCustomFlag: true }),
+    );
+    mergeClaudeSettings(destRoot, pkgRoot);
+    const out = JSON.parse(
+      fs.readFileSync(path.join(destRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(out.someCustomFlag).toBe(true);
+    expect(out.hooks).toEqual(SRC_CLAUDE_SETTINGS.hooks);
+    expect(out.permissions.deny).toEqual(SRC_CLAUDE_SETTINGS.permissions.deny);
+  });
+});
+
 describe("mergePackageJson", () => {
   it("creates {} dest and merges scripts skipping test, injects deps, sorts keys", () => {
     const pkgRoot = stubPkgRoot();
@@ -208,20 +457,37 @@ describe("init", () => {
     expect(fs.readFileSync(path.join(pkgRoot, "scripts", "telemetry.mjs"), "utf8")).toBe(
       "telemetry.mjs",
     );
+    // self-skip: markdown/settings stay exactly as-is, no sentinel wrap
+    expect(fs.readFileSync(path.join(pkgRoot, "CLAUDE.md"), "utf8")).toBe("CLAUDE.md content");
+    const settings = JSON.parse(
+      fs.readFileSync(path.join(pkgRoot, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings).toEqual(SRC_CLAUDE_SETTINGS);
   });
 
-  it("non-self: file vs dir product scripts, then npm pipeline in order", () => {
+  it("non-self: file vs dir product scripts, guarded md + settings merge, then npm pipeline in order", () => {
     const pkgRoot = stubPkgRoot();
     const dest = tmp("grunt-dest-");
     const exec = vi.fn();
     init(dest, { pkgRoot, execFileSync: exec });
 
     for (const d of COPY_DIRS) {
+      if (d === ".claude") continue;
       expect(fs.readFileSync(path.join(dest, d, "marker"), "utf8")).toBe(d);
     }
-    for (const f of COPY_FILES) {
-      expect(fs.readFileSync(path.join(dest, f), "utf8")).toBe(f);
+    expect(fs.readFileSync(path.join(dest, ".claude", "marker"), "utf8")).toBe(".claude");
+    const settings = JSON.parse(
+      fs.readFileSync(path.join(dest, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings).toEqual(SRC_CLAUDE_SETTINGS);
+
+    for (const f of GUARDED_MD_FILES) {
+      expect(fs.readFileSync(path.join(dest, f), "utf8")).toBe(
+        `<!-- grunt:begin -->\n${f} content\n<!-- grunt:end -->\n`,
+      );
     }
+    expect(fs.existsSync(path.join(dest, ".mcp.json"))).toBe(false);
+
     for (const name of PRODUCT_FILES) {
       expect(fs.statSync(path.join(dest, "scripts", name)).isFile()).toBe(true);
     }
@@ -245,6 +511,36 @@ describe("init", () => {
     }
   });
 
+  it("re-running init on an already-initialized dest merges settings.json instead of clobbering", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-rerun-");
+    const exec = vi.fn();
+    fs.mkdirSync(path.join(dest, ".claude"), { recursive: true });
+    const consumerGroup = {
+      matcher: "custom",
+      hooks: [{ type: "command", command: "node scripts/my-custom-hook.mjs" }],
+    };
+    fs.writeFileSync(
+      path.join(dest, ".claude", "settings.json"),
+      JSON.stringify({
+        permissions: { deny: ["Agent(Explore)"] },
+        hooks: { PreToolUse: [consumerGroup] },
+        someCustomFlag: true,
+      }),
+    );
+    init(dest, { pkgRoot, execFileSync: exec });
+    const settings = JSON.parse(
+      fs.readFileSync(path.join(dest, ".claude", "settings.json"), "utf8"),
+    );
+    expect(settings.someCustomFlag).toBe(true);
+    expect(settings.hooks.PreToolUse).toEqual([
+      consumerGroup,
+      ...SRC_CLAUDE_SETTINGS.hooks.PreToolUse,
+    ]);
+    expect(settings.permissions.deny).toContain("Agent(Explore)");
+    expect(settings.permissions.deny).toContain("mcp__*");
+  });
+
   it("omitted execFileSync uses default; self-skip never invokes it", () => {
     const pkgRoot = stubPkgRoot();
     init(pkgRoot, { pkgRoot });
@@ -258,6 +554,7 @@ describe("init", () => {
     init(dest, { execFileSync: exec });
     expect(fs.existsSync(path.join(dest, "AGENTS.md"))).toBe(true);
     expect(fs.existsSync(path.join(dest, "scripts", "scrub-text"))).toBe(true);
+    expect(fs.existsSync(path.join(dest, ".claude", "settings.json"))).toBe(true);
     expect(exec.mock.calls.map((c) => c[1])).toEqual([
       ["install"],
       ["run", "rulesync:generate"],