@lovrozagar/grunt 0.2.0 → 0.3.1

package/.rulesync/reference/map.md

@@ -22,13 +22,14 @@ Cheap outline. Not a file dump.
 ## Grok hand files
 - `.grok/hooks/orchestrate-parent.js` + `orchestrate-parent.json` — parent spawn/fat/stop/plan-write / SubagentStop intercept
 - `.grok/hooks/rtk.json` — RTK
-- `.grok/skills/{write-plan,implement-plan,shared,parent}/` — `/parent` one-turn; point to cascade, do not paste
+- `.grok/skills/{write-plan,implement-plan,shared}/` — hand-only (no rulesync SSOT); point to cascade, do not paste
+- `.grok/skills/{parent,explain,handoff,solo,commit,commit-and-push}/` — generated from `.rulesync/skills/`; do not hand-edit
 - `.grok/parent.md` — 1-line pointer to orchestrator agent; not SessionStart
 - `.grok/roles/*.toml`
 - `.grok/global-settings.toml` — merged into `~/.grok/config.toml` by `scripts/sync-global-settings.mjs` (not auto-loaded; project config cannot set `[features]`)
 - `.rulesync/global-settings/` — host manifest and reserved noop payloads
 - `.rulesync/mcp-policy.jsonc` — MCP deny-default SSOT (`default: deny`, `allow: []`)
-- `.rulesync/skills/parent/` — `/parent` skill SSOT; copy lives in `.grok/skills/parent/`
+- `.rulesync/skills/{parent,explain,handoff,solo,commit,commit-and-push}/` — skill SSOT; `rulesync -f skills` emits `.grok/skills/`, `.claude/skills/`, `.agents/skills/` byte-equal. `/cascade` has no skill (hook-only: a `grunt`-adjacent listing entry risks mis-routing `Skill` vs `Agent`)
 
 ## Scripts
 - `scripts/check-globals.mjs` — `$HOME/.grok/config.toml` `[agent].name==orchestrator` + `[features].two_pass_compaction==true`; project `.grok/config.toml` must not have `[features]`/`[agent]`; wired as `sync:globals:check` (also after emit-mcp in `rulesync:check`)
@@ -36,17 +37,28 @@ Cheap outline. Not a file dump.
 - `scripts/scrub-spawn-prompt.mjs`
 - `scripts/grunt-job.mjs` — flags `--job` `--query` `--path` `--glob` (repeatable) `--cwd`; regex in `--query` OK; never `cd &&`; unknown flags / exec shell-meta → FALLBACK
 - `scripts/parse-need.mjs`
+- `scripts/persist-handoff.mjs` — `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md`; `HANDOFF_NAME:` → slug; H2 `Goal|State|Context|Next|Watch-outs`; `status` `open|resumed|done`
 - `scripts/persist-plan.mjs`
 - `scripts/sync-global-settings.mjs` — dry-run-by-default merge of `.grok/global-settings.toml` into `$HOME/.grok/config.toml`; manifest in `.rulesync/global-settings/`; `skipKeyPattern` skips MCP; never copies project MCP into `$HOME/.grok`
 - `scripts/purge-global-mcps.mjs` — dry-run-by-default purge of stubborn global MCP sources (`$HOME/.grok/config.toml` plugins + `disabled_mcp_servers`, `$HOME/.cursor/mcp.json` `MCP_DOCKER`); `--apply` writes; never project MCP
-- `scripts/emit-mcp-policy.mjs` — emit project MCP deny-default from `.rulesync/mcp-policy.jsonc` (not `rulesync -f mcp`)
+- `scripts/emit-mcp-policy.mjs` — emit project MCP deny-default from `.rulesync/mcp-policy.jsonc` (not `rulesync -f mcp`); owns `.gemini/settings.json` `mcpServers` (merge extra keys)
+- `scripts/emit-gemini.mjs` — `GEMINI.md` (`@AGENTS.md`) + `.gemini/agents/{id}/agent.md` from `.rulesync/subagents` (not `rulesync -t geminicli`); no prune; does not touch settings
+- `scripts/emit-agent-shell-tools.mjs` — after rulesync subagents: rewrite `.claude/agents/grunt.md` body `Bash`; grok/codex/gemini/generic keep `run_terminal_command`
 - `scripts/telemetry.mjs` — append-only `.tmp/orchestrator-logs/telemetry.ndjson` from hooks / grunt-job CLI; fail-open; never stdout
 
+## Tmp
+- `.tmp/plans/` — persist-plan / parent / implementer
+- `.tmp/orchestrator-logs/` — hooks + grunt-job telemetry (shared; not grunt scratch)
+- `.tmp/grunt/` — grunt scratch/tmp only
+- `.tmp/grunt/handoffs/` — persist-handoff / `/handoff`; own serial counter (not plan serials)
+
 ## Stamps (`.tmp/orchestrator-logs/`)
 - `tools-used` / `stop-block` / `need-intercept` / `parent-escape` — Stop does not waive impl finals for `tools-used`; `/parent` writes `parent-escape-{sid}` once
+- `grunt-off-{sid}` — `/solo` session mode. Sticky: only `/solo` / `/cascade` move it. Requires a real sid (never the `default` fallback). Read fail-closed — an unreadable stamp keeps grunt on
 
 ## Generated (do not hand-edit; committed, not gitignored)
 - `AGENTS.md`, `CLAUDE.md`
+- `.claude/skills/*`, `.agents/skills/*`, `.grok/skills/{parent,explain,handoff,solo,commit,commit-and-push}/` (from `.rulesync/skills/`)
 - `.grok/agents/*`
 - `.claude/agents/*`
 - `.codex/agents/*`
@@ -56,3 +68,6 @@ Cheap outline. Not a file dump.
 - `.claude/settings.json` MCP keys (`enableAllProjectMcpServers`, `enabledMcpjsonServers`, `permissions.deny` `mcp__*`); Agent denies/hooks stay
 - `.codex/config.toml` `mcp_servers` (absent when allow empty); keep `[agents] max_depth`
 - `.agents/mcp_config.json` — `mcpServers` from policy allow only
+- `GEMINI.md` — `@AGENTS.md` pointer (`emit-gemini.mjs`)
+- `.gemini/agents/{orchestrator,implementer,thinker,grunt}/agent.md` — `name` `description` `model` only (`emit-gemini.mjs`)
+- `.gemini/settings.json` — `mcpServers` from policy allow only (`emit-mcp-policy.mjs`; extra keys preserved)

package/.rulesync/rules/CLAUDE.md

@@ -4,10 +4,11 @@ targets:
   - claudecode
 ---
 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: `[orchestrator]:` (or child role tag) 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/.rulesync/rules/overview.md

@@ -9,10 +9,11 @@ globs:
   - "**/*"
 ---
 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: `[orchestrator]:` (or child role tag) 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/.rulesync/skills/commit/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: commit
+description: >
+  Inspect the diff and commit with a Conventional Commits subject line. Use for
+  /commit, "commit this", "commit these changes". Never pushes.
+---
+
+Inspect `git status` + `git diff` (staged and unstaged) before the message. Never push.
+
+Stage only user intent. Never blind `git add -A` / `git add .`. Split unrelated concerns into multiple commits.
+
+Message = Conventional Commits **subject only**: `type(scope): subject` (scope optional).
+
+Types: feat fix docs style refactor perf test build ci chore revert.
+
+Subject: imperative lowercase no trailing period.
+
+NO body. NO footer. NO `Co-Authored-By`. NO `Generated with`. NO 🤖. NO trailers. No AI attribution. Work belongs to the human.
+
+Never `git push`.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

package/.rulesync/skills/commit-and-push/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: commit-and-push
+description: >
+  Commit like /commit, then push to the current branch's upstream. Use for
+  /commit-and-push, "commit and push", "commit this and push".
+---
+
+Run commit skill rules first (`.rulesync/skills/commit/SKILL.md`). Then push.
+
+If on default branch, create/switch to a feature branch first — never push default directly.
+
+Push upstream; if no upstream `git push -u origin <current-branch>`.
+
+Never force-push.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

package/.rulesync/skills/handoff/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: handoff
+description: >
+  Parent writes a session handoff under .tmp/grunt/handoffs/ and tells the user
+  to continue in a fresh session. Use for /handoff, "context is getting long",
+  "hand this off", "start a new session". Not a plan, not a design doc.
+---
+# handoff
+
+One turn, in-parent. Parent authors from its own transcript — no child sees this session, so **do not spawn**. Write once, report path, stop.
+
+## Invocation
+
+`/handoff [focus]`
+
+Focus narrows what the handoff carries. Empty → whole session.
+
+## When
+
+Context large + work unfinished → write handoff, then advise a new session. Also on host/tool churn, or before a long unrelated detour.
+
+Nothing done yet (no edits, no findings) → `nothing to hand off` and stop. Do not write an empty file.
+
+## Path
+
+`.tmp/grunt/handoffs/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- serial: unpadded int ≥ 1, next after existing handoffs (own counter; not plan serials)
+- slug: lower, non `[a-z0-9]` → `-`, collapse, trim 50
+- stamp: `created` with `-` and `:` dropped (`20260827T143000Z`)
+
+## Format
+
+```yaml
+---
+serial: 1
+name: <slug>
+status: open        # open | resumed | done
+created: 2026-08-27T14:30:00Z   # UTC, seconds, no ms
+source: "<≤120 chars of the session task>"
+---
+```
+
+Headings, this order only: `# {slug}`, `## Goal`, `## State`, `## Context`, `## Next`, `## Watch-outs`.
+
+| Section | Amount |
+|---|---|
+| Goal | 1–3 sentences. What the session is trying to land. |
+| State | bullets. Done / changed / green-red, with absolute paths. |
+| Context | bullets. Abs paths, decisions, verdict facts the next session needs. |
+| Next | checkbox steps, `N [ ]` phase + `N.M [ ]` leaf, all `[ ]` fresh |
+| Watch-outs | bullets. Footguns. `(none)` allowed. |
+
+Boxes: `^{id} [ ] {text}$`, id `N` / `N.M` / `N.M.K`. Not `- [ ]`, not `1. [ ]`. Every phase has ≥1 leaf. Fresh handoff has zero `[x]`.
+
+Facts only. Absolute paths. No transcript paste, no dump, no secrets/tokens.
+
+## Write
+
+Line 1 of the body: `HANDOFF_NAME: <3-6 word name>`, then the body only.
+
+Parent `write`s under `.tmp/grunt/handoffs/` (any filename in that dir). Grok `orchestrate-parent.js` runs `scripts/persist-handoff.mjs`: serial/slug from `HANDOFF_NAME:` / heading, injects frontmatter, rewrites path + content. Invalid handoff or a write outside that dir is denied — fix the body, do not retry elsewhere.
+
+Host without that hook: name the file per **Path** yourself, or pipe the body to `node scripts/persist-handoff.mjs --workspace {repo}` and use its `path`.
+
+## Report
+
+```
+[handoff]: serial={int} path=.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md
+next: start a new session; first action = read that path
+```
+
+Do not dump the handoff body.
+
+## Picking one up
+
+New session, `/handoff` not needed: read the newest `.tmp/grunt/handoffs/*.md` (or the given serial), set `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
+
+## Rules
+
+- No spawn. One write. `/handoff` is not a mode.
+- Handoff ≠ plan: no Steps/Verify phases, no `.tmp/plans/` write.
+- Never rewrite or renumber an existing handoff; new session = new serial.
+- Protocol: `.rulesync/reference/cascade.md`. Do not paste it here.

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 recap tags. Do not recap `[orchestrator]:`. 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 → `{workspaceRoot}/.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

@@ -1,6 +1,6 @@
 ---
 name: orchestrator
-description: "Parent spawn supervisor. Always spawn+prompt. Echo [agent]: only. No parent search/write except /parent."
+description: "Parent spawn supervisor. Always spawn+prompt. Echo [orchestrator]: or child role tag only. No parent search/write except /parent."
 targets:
   - claudecode
   - grokcli
@@ -29,10 +29,12 @@ 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.
-You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[agent]:` + child output only.
+You do not talk. First token = spawn. No try-then-spawn. No parent probe. No skip-spawn. No trivia/cheap. User-visible = `[orchestrator]:` or child role tag + child output only.
 Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked. Never spawn `orchestrator`. Children never spawn.
 grunt ← tools. World fact → grunt `job: web`. Never memory. implementer ← specified solution (not the spec). thinker ← plan/deep reason/spec.
 Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.

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: `[orchestrator]:` (or child role tag) 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: `[orchestrator]:` (or child role tag) 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 `[orchestrator]:` (or child role tag) 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 })