@lovrozagar/grunt 0.3.1 → 0.3.3

package/.agents/agents/implementer.md

@@ -15,6 +15,7 @@ inheritMcp: false
 Voice: `.rulesync/reference/output.md` — must follow.
 
 Implement specified solution. Never spawn. Never run for simple tool usage (grunt agent). Never plan (thinker agent).
+After write: validate+sim (mandatory). Fix hard failures. Return findings. Never skip validation
 Read/Grep/list_dir only if needed for edit. Prefer: implement the spec; dump via `need:`.
 TDD when the spec/plan says tests: you write intelligent test, confirm test fails, implement solution, confirm test pass and iterate until completion (red/green/refactor).
 Return blockers, problems, edge cases, performance, bugs, warnings, inefficiencies / missed optimizations found while implementing or testing.

package/.agents/agents/orchestrator.md

@@ -13,10 +13,26 @@ inheritMcp: false
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
+Always-do:
+
+| signal | next |
+|---|---|
+| tools/facts/git/test/mechanical write | spawn grunt |
+| world fact | spawn grunt `job:web` |
+| write defined solution | spawn implementer |
+| plan/deep reason | spawn thinker |
+| child returned | recap `[orchestrator]:` or role tag |
+| child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
+| ⚠ / validate / sim | spawn implementer with findings; do not recap done; no parent-edit |
+| work remains | spawn; do not stop |
+| children done + no findings | recap; stop allowed |
+| `/parent` | one-turn parent tools |
+| `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+
 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.
+Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
 `/parent` = one-turn parent-tool escape. Next turn: spawn-only.

package/.claude/agents/implementer.md

@@ -18,6 +18,7 @@ effort: medium
 Voice: `.rulesync/reference/output.md` — must follow.
 
 Implement specified solution. Never spawn. Never run for simple tool usage (grunt agent). Never plan (thinker agent).
+After write: validate+sim (mandatory). Fix hard failures. Return findings. Never skip validation
 Read/Grep/list_dir only if needed for edit. Prefer: implement the spec; dump via `need:`.
 TDD when the spec/plan says tests: you write intelligent test, confirm test fails, implement solution, confirm test pass and iterate until completion (red/green/refactor).
 Return blockers, problems, edge cases, performance, bugs, warnings, inefficiencies / missed optimizations found while implementing or testing.

package/.claude/agents/orchestrator.md

@@ -16,10 +16,26 @@ effort: low
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
+Always-do:
+
+| signal | next |
+|---|---|
+| tools/facts/git/test/mechanical write | spawn grunt |
+| world fact | spawn grunt `job:web` |
+| write defined solution | spawn implementer |
+| plan/deep reason | spawn thinker |
+| child returned | recap `[orchestrator]:` or role tag |
+| child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
+| ⚠ / validate / sim | spawn implementer with findings; do not recap done; no parent-edit |
+| work remains | spawn; do not stop |
+| children done + no findings | recap; stop allowed |
+| `/parent` | one-turn parent tools |
+| `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+
 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.
+Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
 `/parent` = one-turn parent-tool escape. Next turn: spawn-only.

package/.codex/agents/implementer.toml

@@ -8,6 +8,7 @@ developer_instructions = '''
 Voice: `.rulesync/reference/output.md` — must follow.
 
 Implement specified solution. Never spawn. Never run for simple tool usage (grunt agent). Never plan (thinker agent).
+After write: validate+sim (mandatory). Fix hard failures. Return findings. Never skip validation
 Read/Grep/list_dir only if needed for edit. Prefer: implement the spec; dump via `need:`.
 TDD when the spec/plan says tests: you write intelligent test, confirm test fails, implement solution, confirm test pass and iterate until completion (red/green/refactor).
 Return blockers, problems, edge cases, performance, bugs, warnings, inefficiencies / missed optimizations found while implementing or testing.

package/.codex/agents/orchestrator.toml

@@ -7,10 +7,26 @@ approval_policy = "never"
 developer_instructions = '''
 Voice: `.rulesync/reference/output.md` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
+Always-do:
+
+| signal | next |
+|---|---|
+| tools/facts/git/test/mechanical write | spawn grunt |
+| world fact | spawn grunt `job:web` |
+| write defined solution | spawn implementer |
+| plan/deep reason | spawn thinker |
+| child returned | recap `[orchestrator]:` or role tag |
+| child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
+| ⚠ / validate / sim | spawn implementer with findings; do not recap done; no parent-edit |
+| work remains | spawn; do not stop |
+| children done + no findings | recap; stop allowed |
+| `/parent` | one-turn parent tools |
+| `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+
 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.
+Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
 `/parent` = one-turn parent-tool escape. Next turn: spawn-only.

package/.grok/agents/implementer.md

@@ -10,6 +10,7 @@ tools: read_file, grep, list_dir, write, search_replace, run_terminal_command, w
 Voice: `.rulesync/reference/output.md` — must follow.
 
 Implement specified solution. Never spawn. Never run for simple tool usage (grunt agent). Never plan (thinker agent).
+After write: validate+sim (mandatory). Fix hard failures. Return findings. Never skip validation
 Read/Grep/list_dir only if needed for edit. Prefer: implement the spec; dump via `need:`.
 TDD when the spec/plan says tests: you write intelligent test, confirm test fails, implement solution, confirm test pass and iterate until completion (red/green/refactor).
 Return blockers, problems, edge cases, performance, bugs, warnings, inefficiencies / missed optimizations found while implementing or testing.

package/.grok/agents/orchestrator.md

@@ -9,10 +9,26 @@ tools: spawn_subagent, read_file, grep, list_dir, write, todo_write, get_command
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
+Always-do:
+
+| signal | next |
+|---|---|
+| tools/facts/git/test/mechanical write | spawn grunt |
+| world fact | spawn grunt `job:web` |
+| write defined solution | spawn implementer |
+| plan/deep reason | spawn thinker |
+| child returned | recap `[orchestrator]:` or role tag |
+| child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
+| ⚠ / validate / sim | spawn implementer with findings; do not recap done; no parent-edit |
+| work remains | spawn; do not stop |
+| children done + no findings | recap; stop allowed |
+| `/parent` | one-turn parent tools |
+| `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+
 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.
+Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
 `/parent` = one-turn parent-tool escape. Next turn: spawn-only.

package/.grok/hooks/orchestrate-parent.js

@@ -32,21 +32,18 @@ import { logTelemetry, ORCHESTRATOR_LOGS_DIR } from "../../scripts/telemetry.mjs
 
 const DENY_REASON = "parent is orchestrator; spawn grunt|implementer|thinker";
 export const STOP_REASONS = [
-  "Violation: parent replied without a recap tag.\n" +
-    "DO NOT stop. Continue IN THIS RESPONSE:\n" +
-    "1. Spawn grunt|implementer|thinker if work remains.\n" +
-    "2. Recap with `[orchestrator]:` or the child role tag (`[grunt]:` `[implementer]:` `[thinker]:` `[handoff]:`).\n" +
-    "If every spawned child already returned and the turn is done, recap now.",
-  "Second violation: still no recap tag.\n" +
-    "DO NOT stop. Right now, in this same response:\n" +
-    "1. Spawn grunt|implementer|thinker if needed.\n" +
-    "2. Then recap only with `[orchestrator]:` or the matching child role tag.\n" +
-    "Already done and every child returned? Send that recap immediately.",
-  "Third violation: recap still missing.\n" +
-    "This is the last check before fail-open. DO NOT stop:\n" +
-    "1. Spawn the correct agent for remaining work if needed.\n" +
-    "2. Reply with `[orchestrator]:` or the child role tag only, nothing else.\n" +
-    "Complete with all children returned? Send the recap now.",
+  "Violation: Stop is not a recap-only wall. XOR one action now. DO NOT stop.\n" +
+    "⚠/validate/sim findings → spawn implementer with them; do not recap done; no parent-edit.\n" +
+    "Else work remains → spawn grunt|implementer|thinker; do not recap done.\n" +
+    "Else all children returned and no findings → recap `[orchestrator]:` or `[grunt]:` `[implementer]:` `[thinker]:` `[handoff]:`.",
+  "Second violation: still no exclusive next action. XOR one. DO NOT stop.\n" +
+    "⚠/validate/sim findings → spawn implementer with them; do not recap done; no parent-edit.\n" +
+    "Else work remains → spawn grunt|implementer|thinker; do not recap done.\n" +
+    "Else all children returned and no findings → recap `[orchestrator]:` or `[grunt]:` `[implementer]:` `[thinker]:` `[handoff]:`.",
+  "Third violation: last check before fail-open. XOR one action. DO NOT stop.\n" +
+    "⚠/validate/sim findings → spawn implementer with them; do not recap done; no parent-edit.\n" +
+    "Else work remains → spawn grunt|implementer|thinker; do not recap done.\n" +
+    "Else all children returned and no findings → recap `[orchestrator]:` or `[grunt]:` `[implementer]:` `[thinker]:` `[handoff]:`.",
 ];
 const TRANSCRIPT_TAIL_BYTES = 512 * 1024;
 const PARENT_TOOLS = new Set([

package/.rulesync/reference/cascade.md

@@ -8,6 +8,10 @@ Shipped protocol: **parent-only spawn**. Only the parent **orchestrator** sessio
 
 ## Parent orchestrator
 
+Always-do lives in orchestrator/overview (do not open this file first). Peek/kill/`need:` stay here as reference.
+⚠ / validate / sim → spawn implementer; not stop.
+Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
+
 Always spawn + prompt. First token = spawn. No try-then-spawn. No parent probe. No tiny-read/grep/list_dir/bash/grunt-job for the user. No skip-spawn. `/parent` is the only parent-tool escape.
 
 1. Tools (facts / search / exec / git / web / test / low-reason mechanical write) → grunt.
@@ -74,6 +78,6 @@ Fail: first 3 error lines. ≤8 lines. No dumps, recap, HTML, JSON, full logs.
 
 Implementer/thinker: fat dumps via `need:` JSON. Implementer shell via rtk; cat/rg/curl/tests without rtk → fat `need:`.
 
-Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.
+Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 
 Grok PostToolUse is observe-only. SessionStart stays empty (token baseline). See [hooks](hooks.md).

package/.rulesync/rules/CLAUDE.md

@@ -6,11 +6,27 @@ targets:
 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.
+Always-do:
+
+| signal | next |
+|---|---|
+| tools/facts/git/test/mechanical write | spawn grunt |
+| world fact | spawn grunt `job:web` |
+| write defined solution | spawn implementer |
+| plan/deep reason | spawn thinker |
+| child returned | recap `[orchestrator]:` or role tag |
+| child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
+| ⚠ / validate / sim | spawn implementer with findings; do not recap done; no parent-edit |
+| work remains | spawn; do not stop |
+| children done + no findings | recap; stop allowed |
+| `/parent` | one-turn parent tools |
+| `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+
 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: `[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]:`.
+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.
+Child prompt first sentence only: `You are {agent} subagent.` Then 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.
 `need:` JSON → parse-need + parallel grunt; one `resume_from` + new verdicts; max 3; no re-send task; no fresh-spawn.
 Child: this file does not apply; your agent file gates you. Never spawn.

package/.rulesync/rules/overview.md

@@ -11,11 +11,27 @@ 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.
+Always-do:
+
+| signal | next |
+|---|---|
+| tools/facts/git/test/mechanical write | spawn grunt |
+| world fact | spawn grunt `job:web` |
+| write defined solution | spawn implementer |
+| plan/deep reason | spawn thinker |
+| child returned | recap `[orchestrator]:` or role tag |
+| child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
+| ⚠ / validate / sim | spawn implementer with findings; do not recap done; no parent-edit |
+| work remains | spawn; do not stop |
+| children done + no findings | recap; stop allowed |
+| `/parent` | one-turn parent tools |
+| `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+
 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: `[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]:`.
+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.
+Child prompt first sentence only: `You are {agent} subagent.` Then 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.
 `need:` JSON → parse-need + parallel grunt; one `resume_from` + new verdicts; max 3; no re-send task; no fresh-spawn.
 Child: this file does not apply; your agent file gates you. Never spawn.

package/.rulesync/subagents/implementer.md

@@ -32,6 +32,7 @@ geminicli:
 Voice: `.rulesync/reference/output.md` — must follow.
 
 Implement specified solution. Never spawn. Never run for simple tool usage (grunt agent). Never plan (thinker agent).
+After write: validate+sim (mandatory). Fix hard failures. Return findings. Never skip validation
 Read/Grep/list_dir only if needed for edit. Prefer: implement the spec; dump via `need:`.
 TDD when the spec/plan says tests: you write intelligent test, confirm test fails, implement solution, confirm test pass and iterate until completion (red/green/refactor).
 Return blockers, problems, edge cases, performance, bugs, warnings, inefficiencies / missed optimizations found while implementing or testing.

package/.rulesync/subagents/orchestrator.md

@@ -1,6 +1,7 @@
 ---
 name: orchestrator
 description: "Parent spawn supervisor. Always spawn+prompt. Echo [orchestrator]: or child role tag only. No parent search/write except /parent."
+tier: cheap
 targets:
   - claudecode
   - grokcli
@@ -34,10 +35,26 @@ geminicli:
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste. Do not open first.
+Always-do:
+
+| signal | next |
+|---|---|
+| tools/facts/git/test/mechanical write | spawn grunt |
+| world fact | spawn grunt `job:web` |
+| write defined solution | spawn implementer |
+| plan/deep reason | spawn thinker |
+| child returned | recap `[orchestrator]:` or role tag |
+| child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
+| ⚠ / validate / sim | spawn implementer with findings; do not recap done; no parent-edit |
+| work remains | spawn; do not stop |
+| children done + no findings | recap; stop allowed |
+| `/parent` | one-turn parent tools |
+| `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+
 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.
+Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. Grok: `get_command_or_subagent_output` `timeout_ms=60000` every peek. Else GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.
 Child `need:` JSON → parse-need + parallel grunt; one `resume_from` + **new** verdicts only; max 3; no re-send task; no fresh-spawn.
 `/parent` = one-turn parent-tool escape. Next turn: spawn-only.

package/AGENTS.md

@@ -1,11 +1,27 @@
 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.
+Always-do:
+
+| signal | next |
+|---|---|
+| tools/facts/git/test/mechanical write | spawn grunt |
+| world fact | spawn grunt `job:web` |
+| write defined solution | spawn implementer |
+| plan/deep reason | spawn thinker |
+| child returned | recap `[orchestrator]:` or role tag |
+| child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
+| ⚠ / validate / sim | spawn implementer with findings; do not recap done; no parent-edit |
+| work remains | spawn; do not stop |
+| children done + no findings | recap; stop allowed |
+| `/parent` | one-turn parent tools |
+| `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+
 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: `[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]:`.
+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.
+Child prompt first sentence only: `You are {agent} subagent.` Then 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.
 `need:` JSON → parse-need + parallel grunt; one `resume_from` + new verdicts; max 3; no re-send task; no fresh-spawn.
 Child: this file does not apply; your agent file gates you. Never spawn.

package/CLAUDE.md

@@ -1,11 +1,27 @@
 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.
+Always-do:
+
+| signal | next |
+|---|---|
+| tools/facts/git/test/mechanical write | spawn grunt |
+| world fact | spawn grunt `job:web` |
+| write defined solution | spawn implementer |
+| plan/deep reason | spawn thinker |
+| child returned | recap `[orchestrator]:` or role tag |
+| child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
+| ⚠ / validate / sim | spawn implementer with findings; do not recap done; no parent-edit |
+| work remains | spawn; do not stop |
+| children done + no findings | recap; stop allowed |
+| `/parent` | one-turn parent tools |
+| `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
+
 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: `[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]:`.
+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.
+Child prompt first sentence only: `You are {agent} subagent.` Then 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.
 `need:` JSON → parse-need + parallel grunt; one `resume_from` + new verdicts; max 3; no re-send task; no fresh-spawn.
 Child: this file does not apply; your agent file gates you. Never spawn.

package/README.md

@@ -13,8 +13,18 @@ npx @lovrozagar/grunt
 
 Same as `npx @lovrozagar/grunt init`. Merge SoT, `npm install`, `rulesync:generate`, `sync:globals:apply`, `rulesync:check`. Do not `npm test` as a consumer.
 
+`--skip-globals` skips `sync:globals:apply`. Re-init auto-skips globals when `<!-- grunt:begin -->` is in AGENTS.md/CLAUDE.md or `scripts/telemetry.mjs` exists. First init (no sentinel, no telemetry) still applies globals unless flagged.
+
 Contributors to this repo only: local `npm i && npm test`.
 
+# Version bump
+
+```
+npm i -D @lovrozagar/grunt@latest && npx @lovrozagar/grunt init
+```
+
+Owned trees/scripts refresh. Extra `.rulesync` files kept. Patches to grunt-owned files lost. Globals: first init applies; re-init auto-skips (or pass `--skip-globals`).
+
 # 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`) 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`.

package/cli/grunt.mjs

@@ -16,6 +16,9 @@ Commands:
   check      npm run rulesync:check
   help       Show this help
   version    Print package version
+
+Flags:
+  --skip-globals  Skip sync:globals:apply (auto-skipped when already initialized)
 `
 
 function pkgVersion() {
@@ -28,7 +31,9 @@ function npmRun(script) {
 }
 
 export function start() {
-  const [cmd] = process.argv.slice(2)
+  const args = process.argv.slice(2)
+  const skipGlobals = args.includes("--skip-globals")
+  const [cmd] = args.filter((a) => a !== "--skip-globals")
   if (cmd === "help" || cmd === "--help" || cmd === "-h") {
     process.stdout.write(USAGE)
     return
@@ -38,7 +43,7 @@ export function start() {
     return
   }
   if (!cmd || cmd === "init") {
-    init(process.cwd())
+    init(process.cwd(), { skipGlobals })
     return
   }
   if (cmd === "generate") {

package/cli/grunt.test.ts

@@ -21,6 +21,9 @@ Commands:
   check      npm run rulesync:check
   help       Show this help
   version    Print package version
+
+Flags:
+  --skip-globals  Skip sync:globals:apply (auto-skipped when already initialized)
 `;
 
 const pkgRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
@@ -74,7 +77,7 @@ describe("start", () => {
     process.argv = ["node", "grunt"];
     start();
     expect(init).toHaveBeenCalledOnce();
-    expect(init).toHaveBeenCalledWith(process.cwd());
+    expect(init).toHaveBeenCalledWith(process.cwd(), { skipGlobals: false });
     expect(execFileSync).not.toHaveBeenCalled();
   });
 
@@ -82,7 +85,18 @@ describe("start", () => {
     process.argv = ["node", "grunt", "init"];
     start();
     expect(init).toHaveBeenCalledOnce();
-    expect(init).toHaveBeenCalledWith(process.cwd());
+    expect(init).toHaveBeenCalledWith(process.cwd(), { skipGlobals: false });
+  });
+
+  it.each([
+    ["node", "grunt", "--skip-globals"],
+    ["node", "grunt", "init", "--skip-globals"],
+    ["node", "grunt", "--skip-globals", "init"],
+  ])("passes skipGlobals when argv is %s", (...argv) => {
+    process.argv = argv;
+    start();
+    expect(init).toHaveBeenCalledOnce();
+    expect(init).toHaveBeenCalledWith(process.cwd(), { skipGlobals: true });
   });
 
   it("generate npm-runs rulesync:generate", () => {

package/cli/init.mjs

@@ -58,7 +58,22 @@ export function mergeGitignore(dest) {
   fs.appendFileSync(gi, `${prefix}.tmp/\n`)
 }
 
-export function mergeGuardedMarkdown(dest, pkgRoot, file) {
+function destHasGruntSentinel(dest) {
+  return GUARDED_MD_FILES.some((file) => {
+    const p = path.join(dest, file)
+    return fs.existsSync(p) && fs.readFileSync(p, "utf8").includes(SENTINEL_BEGIN)
+  })
+}
+
+function destAlreadyInited(dest) {
+  return (
+    fs.existsSync(path.join(dest, "scripts", "telemetry.mjs")) ||
+    fs.existsSync(path.join(dest, ".grok", "hooks", "orchestrate-parent.js")) ||
+    fs.existsSync(path.join(dest, ".rulesync"))
+  )
+}
+
+export function mergeGuardedMarkdown(dest, pkgRoot, file, { alreadyInited = false } = {}) {
   const src = path.join(pkgRoot, file)
   const d = path.join(dest, file)
   if (samePath(src, d)) return
@@ -73,6 +88,7 @@ export function mergeGuardedMarkdown(dest, pkgRoot, file) {
   const hasSentinel = [SENTINEL_BEGIN, SENTINEL_END].every((marker) => destText.includes(marker))
 
   if (!hasSentinel) {
+    if (alreadyInited) return "skipped-side-file"
     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)`)
@@ -139,6 +155,42 @@ export function mergeClaudeSettings(destRoot, pkgRoot) {
   fs.writeFileSync(destPath, `${JSON.stringify(destSettings, null, 2)}\n`)
 }
 
+function looksGruntOwnedPrefix(prefix) {
+  return /rulesync|sync:globals|^npm run /.test(prefix)
+}
+
+function commandCount(script) {
+  return script.split(/\s*(?:&&|;)\s*/).filter(Boolean).length
+}
+
+function extraOwnedSuffix(cur, newSrc) {
+  const nNew = commandCount(newSrc)
+  const nCur = commandCount(cur)
+  if (nCur <= nNew) return null
+  let completed = 1
+  const re = / &&| ;|&&/g
+  let m
+  while ((m = re.exec(cur))) {
+    if (completed === nNew) {
+      const prefix = cur.slice(0, m.index)
+      if (!looksGruntOwnedPrefix(prefix)) return null
+      return cur.slice(m.index)
+    }
+    completed++
+  }
+  return null
+}
+
+function mergeScriptValue(name, newSrc, cur) {
+  if (cur == null) return newSrc
+  if (cur.startsWith(newSrc)) return cur
+  const suffix = extraOwnedSuffix(cur, newSrc)
+  if (suffix != null) return newSrc + suffix
+  if (looksGruntOwnedPrefix(cur)) return newSrc
+  console.warn(`script \`${name}\` left untouched (unrelated customization)`)
+  return cur
+}
+
 export function mergePackageJson(dest, pkgRoot) {
   const destPath = path.join(dest, "package.json")
   let destPkg = {}
@@ -151,7 +203,7 @@ export function mergePackageJson(dest, pkgRoot) {
   destPkg.scripts = { ...(destPkg.scripts || {}) }
   for (const [k, v] of Object.entries(srcPkg.scripts || {})) {
     if (k === "test") continue
-    destPkg.scripts[k] = v
+    destPkg.scripts[k] = mergeScriptValue(k, v, destPkg.scripts[k])
   }
   destPkg.devDependencies = { ...(destPkg.devDependencies || {}) }
   destPkg.devDependencies["smol-toml"] = srcPkg.devDependencies["smol-toml"]
@@ -161,9 +213,12 @@ export function mergePackageJson(dest, pkgRoot) {
   fs.writeFileSync(destPath, `${JSON.stringify(destPkg, null, 2)}\n`)
 }
 
-export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileSync } = {}) {
+export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileSync, skipGlobals = false } = {}) {
   dest = path.resolve(dest)
   const pkgRoot = path.resolve(pkgRootOpt ?? PKG_ROOT)
+  const alreadyInited = destAlreadyInited(dest)
+  const skipGlobalsApply =
+    skipGlobals || destHasGruntSentinel(dest) || fs.existsSync(path.join(dest, "scripts", "telemetry.mjs"))
 
   for (const dir of COPY_DIRS) {
     const src = path.join(pkgRoot, dir)
@@ -182,8 +237,14 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
     }
   }
 
+  let skippedSideFile = false
   for (const file of GUARDED_MD_FILES) {
-    mergeGuardedMarkdown(dest, pkgRoot, file)
+    if (mergeGuardedMarkdown(dest, pkgRoot, file, { alreadyInited }) === "skipped-side-file") {
+      skippedSideFile = true
+    }
+  }
+  if (skippedSideFile) {
+    console.log("AGENTS.md/CLAUDE.md lack markers and were left alone")
   }
 
   fs.mkdirSync(path.join(dest, "scripts"), { recursive: true })
@@ -207,6 +268,8 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
   mergePackageJson(dest, pkgRoot)
   exec("npm", ["install"], { cwd: dest, stdio: "inherit" })
   exec("npm", ["run", "rulesync:generate"], { cwd: dest, stdio: "inherit" })
-  exec("npm", ["run", "sync:globals:apply"], { cwd: dest, stdio: "inherit" })
+  if (!skipGlobalsApply) {
+    exec("npm", ["run", "sync:globals:apply"], { cwd: dest, stdio: "inherit" })
+  }
   exec("npm", ["run", "rulesync:check"], { cwd: dest, stdio: "inherit" })
 }

package/cli/init.test.ts

@@ -415,13 +415,170 @@ describe("mergePackageJson", () => {
     mergePackageJson(dest, pkgRoot);
     const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
     expect(out.scripts.test).toBe("jest");
-    expect(out.scripts.alpha).toBe("a");
+    expect(out.scripts.alpha).toBe("old");
     expect(out.scripts.foo).toBe("bar");
     expect(out.devDependencies.lodash).toBe("4");
     expect(out.devDependencies["smol-toml"]).toBe("^1.8.0");
     expect(out.devDependencies.rulesync).toBe("latest");
   });
 
+  it("preserves dest suffix after an upgraded grunt script prefix", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { "rulesync:generate": "rulesync generate -t bar" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-suffix-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          "rulesync:generate": "rulesync generate -t foo && node scripts/codex-sync.mjs",
+        },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["rulesync:generate"]).toBe(
+      "rulesync generate -t bar && node scripts/codex-sync.mjs",
+    );
+  });
+
+  it("preserves suffix after a multi-command grunt script upgrade", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: {
+        "rulesync:generate": "rulesync generate -t bar && node scripts/emit.mjs",
+      },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-multi-suffix-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: {
+          "rulesync:generate":
+            "rulesync generate -t foo && node scripts/emit.mjs && node scripts/codex-sync.mjs",
+        },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["rulesync:generate"]).toBe(
+      "rulesync generate -t bar && node scripts/emit.mjs && node scripts/codex-sync.mjs",
+    );
+  });
+
+  it("does not treat a non-owned prefix plus extra && as a grunt suffix", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { alpha: "a" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-nonowned-suffix-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({ scripts: { alpha: "echo custom && extra" } }),
+    );
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts.alpha).toBe("echo custom && extra");
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it("falls through suffix scan when extra commands use bare semicolons", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { "rulesync:generate": "rulesync generate -t bar" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-semi-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: { "rulesync:generate": "echo custom;echo extra" },
+      }),
+    );
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["rulesync:generate"]).toBe("echo custom;echo extra");
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+  });
+
+  it("keeps dest when dest script already equals src", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { "rulesync:generate": "rulesync generate -t bar" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-equal-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({ scripts: { "rulesync:generate": "rulesync generate -t bar" } }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["rulesync:generate"]).toBe("rulesync generate -t bar");
+  });
+
+  it("keeps dest when it already starts with the new src value plus suffix", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { "rulesync:generate": "rulesync generate -t bar" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-prefix-");
+    const cur = "rulesync generate -t bar && node scripts/codex-sync.mjs";
+    fs.writeFileSync(path.join(dest, "package.json"), JSON.stringify({ scripts: { "rulesync:generate": cur } }));
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["rulesync:generate"]).toBe(cur);
+  });
+
+  it("keeps unrelated custom script values and dest-only keys, warns on skip", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("pj-unrelated-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: { alpha: "echo custom", foo: "bar", test: "jest" },
+      }),
+    );
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts.alpha).toBe("echo custom");
+    expect(out.scripts.foo).toBe("bar");
+    expect(out.scripts.test).toBe("jest");
+    expect(out.scripts.zeta).toBe("z");
+    expect(warnSpy.mock.calls.some((c) => String(c[0]).includes("alpha") && String(c[0]).includes("untouched"))).toBe(
+      true,
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("replaces a grunt-owned script with no suffix", () => {
+    const pkgRoot = stubPkgRoot({
+      name: "fixture-pkg",
+      scripts: { "rulesync:generate": "rulesync generate -t bar", "sync:globals:apply": "node scripts/sync-global-settings.mjs --apply" },
+      devDependencies: { "smol-toml": "^1.8.0", rulesync: "latest" },
+    });
+    const dest = tmp("pj-owned-");
+    fs.writeFileSync(
+      path.join(dest, "package.json"),
+      JSON.stringify({
+        scripts: { "rulesync:generate": "rulesync generate -t foo" },
+      }),
+    );
+    mergePackageJson(dest, pkgRoot);
+    const out = JSON.parse(fs.readFileSync(path.join(dest, "package.json"), "utf8"));
+    expect(out.scripts["rulesync:generate"]).toBe("rulesync generate -t bar");
+  });
+
   it("early return when name is @lovrozagar/grunt", () => {
     const pkgRoot = stubPkgRoot();
     const dest = tmp("pj-self-");
@@ -562,4 +719,85 @@ describe("init", () => {
       ["run", "rulesync:check"],
     ]);
   });
+
+  it("--skip-globals skips sync:globals:apply", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-skip-globals-");
+    const exec = vi.fn();
+    init(dest, { pkgRoot, execFileSync: exec, skipGlobals: true });
+    expect(exec.mock.calls.map((c) => [c[0], c[1]])).toEqual([
+      ["npm", ["install"]],
+      ["npm", ["run", "rulesync:generate"]],
+      ["npm", ["run", "rulesync:check"]],
+    ]);
+  });
+
+  it("auto-skip globals when telemetry.mjs exists", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-auto-tel-");
+    fs.mkdirSync(path.join(dest, "scripts"), { recursive: true });
+    fs.writeFileSync(path.join(dest, "scripts", "telemetry.mjs"), "existing");
+    const exec = vi.fn();
+    init(dest, { pkgRoot, execFileSync: exec });
+    expect(exec.mock.calls.map((c) => c[1])).toEqual([
+      ["install"],
+      ["run", "rulesync:generate"],
+      ["run", "rulesync:check"],
+    ]);
+  });
+
+  it("auto-skip globals when AGENTS.md already has a grunt sentinel", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-auto-sent-");
+    fs.writeFileSync(
+      path.join(dest, "AGENTS.md"),
+      "<!-- grunt:begin -->\nold\n<!-- grunt:end -->\n",
+    );
+    const exec = vi.fn();
+    init(dest, { pkgRoot, execFileSync: exec });
+    expect(exec.mock.calls.map((c) => c[1])).toEqual([
+      ["install"],
+      ["run", "rulesync:generate"],
+      ["run", "rulesync:check"],
+    ]);
+  });
+
+  it("re-run without sentinel does not create/overwrite *.grunt.md", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-rerun-nosent-");
+    fs.writeFileSync(path.join(dest, "CLAUDE.md"), "hand-written consumer doc\n");
+    fs.writeFileSync(path.join(dest, "AGENTS.md"), "hand-written consumer doc\n");
+    fs.mkdirSync(path.join(dest, "scripts"), { recursive: true });
+    fs.writeFileSync(path.join(dest, "scripts", "telemetry.mjs"), "existing");
+    fs.writeFileSync(path.join(dest, "CLAUDE.grunt.md"), "stale side");
+    const exec = vi.fn();
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    init(dest, { pkgRoot, execFileSync: exec });
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.md"), "utf8")).toBe("hand-written consumer doc\n");
+    expect(fs.readFileSync(path.join(dest, "AGENTS.md"), "utf8")).toBe("hand-written consumer doc\n");
+    expect(fs.readFileSync(path.join(dest, "CLAUDE.grunt.md"), "utf8")).toBe("stale side");
+    expect(fs.existsSync(path.join(dest, "AGENTS.grunt.md"))).toBe(false);
+    expect(logSpy.mock.calls.filter((c) => String(c[0]).includes("lack markers"))).toHaveLength(1);
+    logSpy.mockRestore();
+  });
+
+  it("first init without sentinel still creates *.grunt.md", () => {
+    const pkgRoot = stubPkgRoot();
+    const dest = tmp("grunt-first-nosent-");
+    fs.writeFileSync(path.join(dest, "CLAUDE.md"), "hand-written consumer doc\n");
+    fs.writeFileSync(path.join(dest, "AGENTS.md"), "hand-written consumer doc\n");
+    const exec = vi.fn();
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    init(dest, { pkgRoot, execFileSync: exec });
+    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(fs.readFileSync(path.join(dest, "AGENTS.grunt.md"), "utf8")).toBe("AGENTS.md content");
+    expect(exec.mock.calls.map((c) => c[1])).toEqual([
+      ["install"],
+      ["run", "rulesync:generate"],
+      ["run", "sync:globals:apply"],
+      ["run", "rulesync:check"],
+    ]);
+    logSpy.mockRestore();
+  });
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.3.1",
-  "description": "Multi-agent orchestrator SoT \u2014 deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
+  "version": "0.3.3",
+  "description": "Multi-agent orchestrator SoT — deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",
     "grunt",

package/scripts/hooks-union.mjs

@@ -47,6 +47,7 @@ export const GIT_HOOKS = [
   "scripts/git-hooks/pre-push",
   "scripts/git-hooks/pre-push.mjs",
 ];
+export const POST_WRITE_MATCHER = "Write|Edit|write|search_replace";
 
 const CAVEAT_BEHIND =
   "NOT ported: PreToolUse check-behind.mjs. Gemini has no confirmed before-tool deny event.";
@@ -180,7 +181,7 @@ function desiredPost(root) {
   const hooks = [];
   if (hasScript(root, "validate.mjs")) hooks.push(hookCmd(VALIDATE));
   if (hasScript(root, "sim.mjs")) hooks.push(hookCmd(SIM));
-  return hooks.length ? [{ matcher: "Write|Edit", hooks }] : null;
+  return hooks.length ? [{ matcher: POST_WRITE_MATCHER, hooks }] : null;
 }
 
 function consumerNamed(root) {
@@ -210,10 +211,10 @@ function consumerNamed(root) {
     timeout: 5,
   };
   if (hasScript(root, "validate.mjs")) {
-    named["validate-artifact"] = { event: "PostToolUse", matcher: ".*", command: VALIDATE };
+    named["validate-artifact"] = { event: "PostToolUse", matcher: POST_WRITE_MATCHER, command: VALIDATE };
   }
   if (hasScript(root, "sim.mjs")) {
-    named["simulate-artifact"] = { event: "PostToolUse", matcher: ".*", command: SIM };
+    named["simulate-artifact"] = { event: "PostToolUse", matcher: POST_WRITE_MATCHER, command: SIM };
   }
   return named;
 }
@@ -262,7 +263,7 @@ function applyAgents(root) {
   }
   const post = desiredPost(root);
   if (post) {
-    rulesync.PostToolUse = [{ matcher: ".*", hooks: post[0].hooks }];
+    rulesync.PostToolUse = [{ matcher: POST_WRITE_MATCHER, hooks: post[0].hooks }];
   }
   const named = presentAutorun(root).length ? consumerNamed(root) : {};
   saveJson(abs, { ...live, ...named, rulesync });