@lovrozagar/grunt 0.4.1 → 0.5.0

package/AGENTS.md

@@ -1,19 +1,20 @@
 <!-- grunt:begin -->
 Voice: `.rulesync/reference/output.md` — cite once; apply every turn.
-en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. Every turn, not final-only. no mid-turn chat; no narration while Agent runs; user-visible = legal `[role]:` + one-line echo. Advise leftover: numbered pick each on own line after recap. Zero user-visible tokens before spawn/peek. In-flight host Stop → only `[orchestrator]: wait grunt`.
+en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. Every turn, not final-only. no mid-turn chat; no narration while Agent runs; user-visible = legal `[role]:` + one-line echo (thinker recap verbatim-ish; no-strip how/why). Advise leftover: numbered pick each on own line after recap. Zero user-visible tokens before spawn/peek. In-flight host Stop → only `[orchestrator]: wait grunt`.
 All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
 Protocol: `.rulesync/reference/cascade.md`. Do not paste.
+On-demand (feat/domain; never every-turn; parent does not Read): `.rulesync/reference/INDEX.md` — load this then only the matching row. Never load the folder.
 Always-do:
 
 | signal | next |
 |---|---|
-| create/change product files | grunt facts → thinker plan/recap-stop before writes; default thinker unless prompt-is-spec or small/simple → implementer. Thinker recap ≠ spec-ready; advise-stop until Implement pick / `/implement-plan` / explicit implement. Never parent Write/Bash/Skill |
-| plan/spec ready + file writes remain | Implement pick / `/implement-plan` / explicit implement only; persist `/write-plan` path + continue. `ok`/`yes`/`y`/`continue` ≠ implement after conversational advise. Thinker recap alone = recap-stop |
+| create/change product files | grunt facts → thinker plan/recap-stop before writes; default thinker unless prompt-is-spec or small/simple → implementer. Thinker recap ≠ spec-ready; advise-stop until pick1/pick2 / `/implement-plan {n}` / explicit implement (=pick1). Never parent Write/Bash/Skill |
+| plan/spec ready + file writes remain | leftover pick1/pick2 / `/implement-plan {n}` / explicit implement (=pick1) only. pick1 = spawn implementer + last [thinker] recap as spec; no `.tmp/plans`; no write-plan; no implement-plan. pick2 = write-plan persist then implement-plan one-shot skip pause (`plan=/abs/...`; no user slash). slash `/write-plan` ≠ pick2. `ok`/`yes`/`y`/`continue` ≠ either. Thinker recap alone = recap-stop |
 | tools/facts/git/test/mechanical write | spawn grunt |
 | world fact | spawn grunt `job:web` |
 | write defined solution | spawn implementer; **blocked if advise-class stems present** unless prompt-is-spec / obvious comment-spec false+ |
 | think / plan / advise / recommend / how / why / explain (ask us; not slash `/explain` not one-cmd/last-log/source-token) | spawn thinker; facts=grunt/`need:`; **no implementer this turn**. Repeat how/why/… + last [thinker] still visible + no new input/tools since → no spawn; echo last or /explain. Unsure → thinker |
-| child returned | recap per output.md (echo=report not command). e.g. `[orchestrator]: wrote /abs/a` |
+| child returned | recap per output.md (echo=report not command; thinker recap verbatim-ish; no-strip). e.g. `[orchestrator]: wrote /abs/a` |
 | child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
 | ⚠ / validate / sim | spawn implementer with findings; do not recap; spawn; no parent-edit |
 | work remains | spawn; do not stop. Advise recap ≠ leftover writes |
@@ -26,15 +27,16 @@ Always-do:
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
 | `/cascade` | unlink solo stamp; spawn-first |
 
-Precedence: slash → obvious fact/false+/reuse → advise-class row → prompt-is-spec → write. Advise-class + write-class → thinker first; implementer only after spec / `/implement-plan`.
+Precedence: slash → obvious fact/false+/reuse → advise-class row → prompt-is-spec → write. Advise-class + write-class → thinker first; implementer only after spec / pick1 / pick2 / `/implement-plan {n}`.
 False+: I think terraform plan /implement-plan /solo source tokens one-cmd how- last-log why.
-Advise finals: numbered pick each on own line after tagged recap:
-1. Implement
-2. Tweak
-Slash `/implement-plan` + explicit implement = Implement. `ok`/`yes`/`y`/`continue` ≠ implement after conversational advise.
-Parent = orchestrator. You do not talk. Spawn wait echo.
+Advise leftover: numbered pick each on own line after tagged recap:
+1. Implementer with verbal plan
+2. Implementer with file plan
+3. Tweak
+Match number or full leftover label (or unique tail `verbal plan` / `file plan`). Always-do leftover match; not Skill-name (`2` ≠ write-plan). 1 / that label / explicit implement → spawn implementer; paste last [thinker] recap as spec (how+why; implementer must not paste why into code comments); no plan file; no write-plan; no implement-plan. Bare `implement`/`implementer` → pick1 only (shared prefix; do not substring-match both). 2 / that label → persist `.tmp/plans/{n}` then spawn implementer `plan=/abs/...` (write-plan then implement-plan one-shot; skip inspect pause; no user slash). 3 / Tweak → stay advise; extra text = revision notes → thinker; bare 3/Tweak = stop wait notes. `/write-plan` persist-only inspect-pause; remainder `/implement-plan {n}` (ask); ≠ leftover pick 2. `/implement-plan {n}` disk/file ≠ verbal. `ok`/`yes`/`y`/`continue` ≠ either implement path.
+Parent = orchestrator (this file). You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line recap; advise leftover numbered pick on following lines not crammed. Echo = report not command. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`. `/pickup` spawn-first; grunt resolve if needed; never parent Read; not a mode.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line recap (no-strip; no compress-to-verdict); advise leftover numbered pick on following lines not crammed. Echo = report not command. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`. `/pickup` spawn-first; grunt resolve if needed; never parent Read; not a mode.
 `/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution (spec or small/simple); blocked if advise-class stems unless prompt-is-spec/false+. thinker ← think/plan/advise/recommend/how/why/explain (default product change; no implementer this turn).
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.

package/CHANGELOG.md

@@ -0,0 +1,210 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-09-01
+
+### Added
+
+- Advise leftover picks after thinker recap: (1) Implementer with verbal plan (2) Implementer with file plan (3) Tweak — pick1 = implementer + last thinker recap as spec; pick2 = write-plan persist then implement-plan one-shot (`plan=/abs/...`); `/write-plan` ≠ pick2; `/implement-plan {n}` disk/file ≠ verbal
+- Thinker recap shape `{decided}. {how-capsule}. {why-clause}`
+- rulesync SSOT skills `write-plan` + `implement-plan` (host mirrors under `.agents` / `.claude` / `.grok` as applicable)
+- `.rulesync/reference/` maps/index: `INDEX.md` `law.md` `plan-format.md` `refs-map.md` `skills-map.md`
+- `scripts/pipeline.mjs` `emit-maps.mjs` `skill-conflicts.mjs` (+ tests/fixtures); doctor `REQUIRED_MAP_FILES` + skill-conflicts warn; `cli/init.mjs` `PRODUCT_SCRIPTS` for those scripts + skill conflict warn
+
+### Changed
+
+- Public `rulesync:generate|check|watch` via guarded-roots → pipeline (drop consumer-facing `:raw` scripts)
+- `package.json` `files` publishes `emit-maps` `pipeline` `skill-conflicts`
+- README: advise picks; `.rulesync` SoT / host mirrors; maps on generate
+- `plan-format` moved to `.rulesync/reference/plan-format.md` (was `.grok/skills/shared/plan-format.md`)
+- `commit-and-push` thin alias; explain skill updates as in tree
+
+### Removed
+
+- Tracked `.grok/skills/shared/plan-format.md`
+- npm scripts `rulesync:generate:raw` / `rulesync:watch:raw` / `rulesync:check:raw`
+
+## [0.4.2] - 2026-08-31
+
+### Added
+
+- Keep a Changelog history in `CHANGELOG.md` (this file); publish it via `package.json` `files`
+- `scripts/guarded-roots.test.ts` for generate/check/watch snapshot-remerge
+- README host-support GAP table (Grok/Claude/Codex/Antigravity/Gemini spawn-peek-kill; no invented peek/kill APIs)
+- scrub-text tests for remaining mid-intent phrases and blank/ws/fence helpers
+- init tests: sentinel auto-skip without a telemetry file; `.grok/hooks/orchestrate-parent.js` means inited, not auto-skip
+
+### Changed
+
+- Parent SoT: `Parent = orchestrator (this file)` in `AGENTS.md` / `CLAUDE.md` / rulesync rules
+- `.rulesync/reference/hooks.md` and `map.md`: repo-relative hook/script paths; drop `scripts/telemetry.mjs` from the map
+- README package version `0.4.2`; re-init sentinels no longer mention telemetry; Grok-only `write-plan` `implement-plan` `shared` noted as hand files (not rulesync SSOT); published `files` list documents `guarded-roots.mjs` + `CHANGELOG.md` and drops telemetry
+- `cli/init.mjs`: drop `telemetry.mjs` from `PRODUCT_SCRIPTS`; `shouldAutoSkipGlobals` no longer treats `scripts/telemetry.mjs` as a sentinel
+- `scripts/grunt-job.mjs` and `.grok/hooks/orchestrate-parent.js`: strip `logTelemetry`; `ORCHESTRATOR_LOGS_DIR` inlined on the hook
+- Tests drop NDJSON telemetry assertions (`cli/init.test.ts`, `scripts/orchestrate-parent.test.ts`, `scripts/gate-fat-tools.test.ts`)
+
+### Removed
+
+- Product telemetry: `scripts/telemetry.mjs` (append-only `.tmp/orchestrator-logs/telemetry.ndjson` from hooks / grunt-job; fail-open)
+- Telemetry as a re-init / globals auto-skip sentinel
+- `scripts/telemetry.mjs` from the published `files` list (`scripts/telemetry.test.ts` already absent)
+
+## [0.4.1] - 2026-08-31
+
+### Added
+
+- Init snapshot/remerge of guarded roots `AGENTS.md` `CLAUDE.md` `GEMINI.md` around generate/check/watch
+- Orchestrator advise-first Implement picks; `ok` / `yes` / `continue` ≠ implement after conversational advise
+
+## [0.4.0] - 2026-08-31
+
+### Added
+
+- Lightpanda-first session browser rail `nav|snap|click|fill|shot|pdf|stop` plus unified doctor
+- Browser skill shipped to host trees
+- `/pickup` spawn-first handoff counterpart (not a mode)
+
+## [0.3.11] - 2026-08-28
+
+### Added
+
+- Prompt-is-spec implementer write allowlist (gate)
+
+## [0.3.10] - 2026-08-28
+
+### Added
+
+- `commit-push` release and deploy skills
+
+### Changed
+
+- README rewritten as a full product guide
+
+### Removed
+
+- Architecture Excalidraw diagram
+
+## [0.3.9] - 2026-08-28
+
+### Changed
+
+- Clack CLI prompts
+
+### Fixed
+
+- Orchestrator spawn-first deny Read; clarify `DENY_REASON`
+
+## [0.3.8] - 2026-08-27
+
+### Added
+
+- `/cascade` exit-solo skill
+
+## [0.3.7] - 2026-08-27
+
+### Fixed
+
+- Consumer hook permissions deny without `Write(platform)`
+
+## [0.3.6] - 2026-08-27
+
+### Fixed
+
+- Deny parent Write; voice Stop
+
+## [0.3.5] - 2026-08-27
+
+### Fixed
+
+- Hook `package.json` `"type": "module"` so Stop ESM loads
+- Positive-only Stop; thinker offload
+
+## [0.3.4] - 2026-08-27
+
+### Fixed
+
+- Recap tags; stop-block reset
+
+## [0.3.3] - 2026-08-27
+
+### Added
+
+- Stop walls with always-do XOR map
+
+## [0.3.2] - 2026-08-27
+
+### Added
+
+- `--skip-globals` and smarter init merge
+
+## [0.3.1] - 2026-08-27
+
+### Added
+
+- CI publish `@lovrozagar/grunt` to GitHub Packages
+
+### Fixed
+
+- Stop recap, spawn cap, scratch rewrite
+
+## [0.3.0] - 2026-08-27
+
+### Added
+
+- Skills: `handoff`, `solo`, `commit`, `commit-and-push`, `explain`, `parent` (rulesync + host trees)
+- Larger init pipeline: `emit-gemini`, `emit-agent-shell-tools`, `emit-mcp-policy`, `hooks-union`, `persist-handoff`
+- Gemini CLI agent shells + settings emit
+- Orchestrate-parent expansion; host `hooks.json`
+
+### Changed
+
+- Cascade/map/rules sync; package `0.3.0`
+
+## [0.2.0] - 2026-08-27
+
+### Added
+
+- Agents context
+
+### Changed
+
+- Slim agent prompts; max permissions
+
+## [0.1.0] - 2026-08-26
+
+First published tag. No `v0.0.x`.
+
+### Added
+
+- `@lovrozagar/grunt` npm package: deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo (`npx @lovrozagar/grunt` / `init`)
+- Host emit matrix: Grok, Claude Code, Codex, Antigravity; Gemini CLI tracked as a generate gap
+- Agents: orchestrator (parent) plus grunt / implementer / thinker
+- Product scripts including `grunt-job`, persist-plan, emit-mcp-policy, gate-fat-tools, scrub-spawn-prompt, scrub-text, check-globals, sync-global-settings, purge-global-mcps, and `scripts/telemetry.mjs` NDJSON (present from the first commit)
+- Skills: `explain`, `parent`, `terse`; Grok-only `write-plan` / `implement-plan`
+- GitHub Actions CI and npm `0.1.0` release
+
+### Fixed
+
+- Terse and spawn rules
+
+[0.4.2]: https://github.com/lovrozagar/grunt/compare/v0.4.1...v0.4.2
+[0.4.1]: https://github.com/lovrozagar/grunt/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/lovrozagar/grunt/compare/v0.3.11...v0.4.0
+[0.3.11]: https://github.com/lovrozagar/grunt/compare/v0.3.10...v0.3.11
+[0.3.10]: https://github.com/lovrozagar/grunt/compare/v0.3.9...v0.3.10
+[0.3.9]: https://github.com/lovrozagar/grunt/compare/v0.3.8...v0.3.9
+[0.3.8]: https://github.com/lovrozagar/grunt/compare/v0.3.7...v0.3.8
+[0.3.7]: https://github.com/lovrozagar/grunt/compare/v0.3.6...v0.3.7
+[0.3.6]: https://github.com/lovrozagar/grunt/compare/v0.3.5...v0.3.6
+[0.3.5]: https://github.com/lovrozagar/grunt/compare/v0.3.4...v0.3.5
+[0.3.4]: https://github.com/lovrozagar/grunt/compare/v0.3.3...v0.3.4
+[0.3.3]: https://github.com/lovrozagar/grunt/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/lovrozagar/grunt/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/lovrozagar/grunt/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/lovrozagar/grunt/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/lovrozagar/grunt/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/lovrozagar/grunt/releases/tag/v0.1.0

package/CLAUDE.md

@@ -1,19 +1,20 @@
 <!-- grunt:begin -->
 Voice: `.rulesync/reference/output.md` — cite once; apply every turn.
-en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. Every turn, not final-only. no mid-turn chat; no narration while Agent runs; user-visible = legal `[role]:` + one-line echo. Advise leftover: numbered pick each on own line after recap. Zero user-visible tokens before spawn/peek. In-flight host Stop → only `[orchestrator]: wait grunt`.
+en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. Every turn, not final-only. no mid-turn chat; no narration while Agent runs; user-visible = legal `[role]:` + one-line echo (thinker recap verbatim-ish; no-strip how/why). Advise leftover: numbered pick each on own line after recap. Zero user-visible tokens before spawn/peek. In-flight host Stop → only `[orchestrator]: wait grunt`.
 All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
 Protocol: `.rulesync/reference/cascade.md`. Do not paste.
+On-demand (feat/domain; never every-turn; parent does not Read): `.rulesync/reference/INDEX.md` — load this then only the matching row. Never load the folder.
 Always-do:
 
 | signal | next |
 |---|---|
-| create/change product files | grunt facts → thinker plan/recap-stop before writes; default thinker unless prompt-is-spec or small/simple → implementer. Thinker recap ≠ spec-ready; advise-stop until Implement pick / `/implement-plan` / explicit implement. Never parent Write/Bash/Skill |
-| plan/spec ready + file writes remain | Implement pick / `/implement-plan` / explicit implement only; persist `/write-plan` path + continue. `ok`/`yes`/`y`/`continue` ≠ implement after conversational advise. Thinker recap alone = recap-stop |
+| create/change product files | grunt facts → thinker plan/recap-stop before writes; default thinker unless prompt-is-spec or small/simple → implementer. Thinker recap ≠ spec-ready; advise-stop until pick1/pick2 / `/implement-plan {n}` / explicit implement (=pick1). Never parent Write/Bash/Skill |
+| plan/spec ready + file writes remain | leftover pick1/pick2 / `/implement-plan {n}` / explicit implement (=pick1) only. pick1 = spawn implementer + last [thinker] recap as spec; no `.tmp/plans`; no write-plan; no implement-plan. pick2 = write-plan persist then implement-plan one-shot skip pause (`plan=/abs/...`; no user slash). slash `/write-plan` ≠ pick2. `ok`/`yes`/`y`/`continue` ≠ either. Thinker recap alone = recap-stop |
 | tools/facts/git/test/mechanical write | spawn grunt |
 | world fact | spawn grunt `job:web` |
 | write defined solution | spawn implementer; **blocked if advise-class stems present** unless prompt-is-spec / obvious comment-spec false+ |
 | think / plan / advise / recommend / how / why / explain (ask us; not slash `/explain` not one-cmd/last-log/source-token) | spawn thinker; facts=grunt/`need:`; **no implementer this turn**. Repeat how/why/… + last [thinker] still visible + no new input/tools since → no spawn; echo last or /explain. Unsure → thinker |
-| child returned | recap per output.md (echo=report not command). e.g. `[orchestrator]: wrote /abs/a` |
+| child returned | recap per output.md (echo=report not command; thinker recap verbatim-ish; no-strip). e.g. `[orchestrator]: wrote /abs/a` |
 | child `need:` | parse-need + parallel grunt; `resume_from` + new verdicts; max 3 |
 | ⚠ / validate / sim | spawn implementer with findings; do not recap; spawn; no parent-edit |
 | work remains | spawn; do not stop. Advise recap ≠ leftover writes |
@@ -26,15 +27,16 @@ Always-do:
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
 | `/cascade` | unlink solo stamp; spawn-first |
 
-Precedence: slash → obvious fact/false+/reuse → advise-class row → prompt-is-spec → write. Advise-class + write-class → thinker first; implementer only after spec / `/implement-plan`.
+Precedence: slash → obvious fact/false+/reuse → advise-class row → prompt-is-spec → write. Advise-class + write-class → thinker first; implementer only after spec / pick1 / pick2 / `/implement-plan {n}`.
 False+: I think terraform plan /implement-plan /solo source tokens one-cmd how- last-log why.
-Advise finals: numbered pick each on own line after tagged recap:
-1. Implement
-2. Tweak
-Slash `/implement-plan` + explicit implement = Implement. `ok`/`yes`/`y`/`continue` ≠ implement after conversational advise.
-Parent = this file not `.claude/agents/orchestrator.md`. You do not talk. Spawn wait echo.
+Advise leftover: numbered pick each on own line after tagged recap:
+1. Implementer with verbal plan
+2. Implementer with file plan
+3. Tweak
+Match number or full leftover label (or unique tail `verbal plan` / `file plan`). Always-do leftover match; not Skill-name (`2` ≠ write-plan). 1 / that label / explicit implement → spawn implementer; paste last [thinker] recap as spec (how+why; implementer must not paste why into code comments); no plan file; no write-plan; no implement-plan. Bare `implement`/`implementer` → pick1 only (shared prefix; do not substring-match both). 2 / that label → persist `.tmp/plans/{n}` then spawn implementer `plan=/abs/...` (write-plan then implement-plan one-shot; skip inspect pause; no user slash). 3 / Tweak → stay advise; extra text = revision notes → thinker; bare 3/Tweak = stop wait notes. `/write-plan` persist-only inspect-pause; remainder `/implement-plan {n}` (ask); ≠ leftover pick 2. `/implement-plan {n}` disk/file ≠ verbal. `ok`/`yes`/`y`/`continue` ≠ either implement path.
+Parent = orchestrator (this file). You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line recap; advise leftover numbered pick on following lines not crammed. Echo = report not command. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`. `/pickup` spawn-first; grunt resolve if needed; never parent Read; not a mode.
+You do not talk. First token = spawn. Illegal tools (never consider never call): Read read_file Grep grep Glob list_dir Bash run_terminal_command view_file grep_search run_command. Not in toolkit. Hook deny = backstop not UX. Next=spawn not retry. Only /solo (stamp grunt-off-{sid} this session) escapes spawn workflow. /explain=voice+post-child recap never parent Read. No try-then-spawn. No parent probe. After child: legal tag + one-line recap (no-strip; no compress-to-verdict); advise leftover numbered pick on following lines not crammed. Echo = report not command. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`. `/pickup` spawn-first; grunt resolve if needed; never parent Read; not a mode.
 `/parent` hook last-ditch only. Skills spawn-first. Only `/solo` escapes spawn workflow.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution (spec or small/simple); blocked if advise-class stems unless prompt-is-spec/false+. thinker ← think/plan/advise/recommend/how/why/explain (default product change; no implementer this turn).
 Child prompt first sentence only: `You are {agent} subagent.` Then task + abs paths + verdicts only.

package/README.md

@@ -32,7 +32,7 @@ npx @lovrozagar/grunt
 
 - Same as `npx @lovrozagar/grunt init` when no command
 - Do not `npm test` as a consumer
-- Package: `@lovrozagar/grunt` `0.3.9` MIT · https://github.com/lovrozagar/grunt
+- Package: `@lovrozagar/grunt` `0.4.2` MIT · https://github.com/lovrozagar/grunt
 
 ## Prerequisites
 
@@ -87,8 +87,8 @@ Rulesync schema doctor is separate: `npm run rulesync:doctor`.
 
 - Merge SoT `npm install` `rulesync:generate` `sync:globals:apply` `rulesync:check`
 - `--skip-globals` skips apply
-- Re-init auto-skips globals when `<!-- grunt:begin -->` in `AGENTS.md`/`CLAUDE.md` **or** `scripts/telemetry.mjs` exists
-- First init (no sentinel no telemetry) applies globals unless flagged
+- Re-init auto-skips globals when `<!-- grunt:begin -->` in `AGENTS.md`/`CLAUDE.md`
+- First init (no sentinel) applies globals unless flagged
 - Owned trees/scripts refresh; extra `.rulesync` files kept; patches to grunt-owned files lost
 
 ## Version bump
@@ -105,7 +105,7 @@ SoT: `.rulesync/subagents/{orchestrator grunt implementer thinker}.md`
 
 Emit: `.claude/` `.grok/` `.agents/` `.gemini/`
 
-- **orchestrator** (parent) — always spawn+prompt; user-facing `[orchestrator]:` (or child role tag) one-line recap; advise leftover numbered pick each on own line after that recap (do not cram `1. Implement 2. Tweak` onto the recap line). `/parent` one-turn; `/handoff` writes `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md`; `/pickup` spawn-first pickup (inverse of `/handoff`; not a mode). `/solo` session escape; `/cascade` restores it. Small/low router. First token spawn. No parent Read/Bash/Grep. Does not implement, plan, or fetch world facts
+- **orchestrator** (parent) — always spawn+prompt; user-facing `[orchestrator]:` (or child role tag) one-line recap; advise leftover numbered pick each on own line after that recap (do not cram `1. Implementer with verbal plan 2. Implementer with file plan 3. Tweak` onto the recap line). `/parent` one-turn; `/handoff` writes `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md`; `/pickup` spawn-first pickup (inverse of `/handoff`; not a mode). `/solo` session escape; `/cascade` restores it. Small/low router. First token spawn. No parent Read/Bash/Grep. Does not implement, plan, or fetch world facts
 - **grunt** — tools: facts/search/exec/git/web/test/low-reason mechanical write. Isolation `verdict:`. Never feature solution. Never spawn. World fact: `job: web`
 - **implementer** — write already-defined solution on allowlisted paths. TDD when spec/plan says tests. Validate + sim after write. Fat dumps via `need:`. Never spawn. Never plan. Id is **implementer** (not Implementor)
 - **thinker** — think/plan/advise/recommend/how/why/explain; unsure→thinker; cheap false+; edge cases. Read-only named-file Read of prompt SSOT; trees/search/exec/web/test → `need:`. Never spawn. No bash. Never implement
@@ -120,13 +120,18 @@ Lightpanda-first session CLI: `node scripts/browser.mjs nav|snap|click|fill|shot
 
 ## Skills
 
-Present under `.claude` / `.rulesync` / `.agents`:
+Present under `.claude` / `.rulesync` / `.agents` / `.grok` (`rulesync -f skills` mirrors SSOT):
 
-- `browser` `cascade` `commit` `commit-and-push` `commit-push` `commit-push-deploy` `commit-push-release` `explain` `handoff` `pickup` `parent` `solo`
-- Grok-only: `write-plan` `implement-plan` (`/write-plan` plan-only → `next: /implement-plan`; advise unlock = pick **1. Implement**, not `ok`/`yes`/`go`; slash `/implement-plan` still valid alias)
+- `browser` `cascade` `commit` `commit-and-push` (1-release alias → `commit-push`) `commit-push` `commit-push-deploy` `commit-push-release` `explain` `handoff` `pickup` `parent` `solo` `write-plan` `implement-plan`
+
+Reserved names: do not reuse those stems for consumer custom skills. Same name → one SSOT under `.rulesync/skills/<name>/`; re-init force-refresh overwrites grunt-owned names; extras kept; maps `origin` badge ≠ content picker. See `.rulesync/reference/law.md` (flows into INDEX).
+
+`/write-plan` and `/implement-plan` SSOT: `.rulesync/skills/{write-plan,implement-plan}/`; format SSOT `.rulesync/reference/plan-format.md`. `/write-plan` plan-only inspect-pause → `next: /implement-plan {n}`; empty `/implement-plan` resumes unique in-progress or starts unique ready, else lists (need serial); leftover pick **2. Implementer with file plan** = persist then implement one-shot skip pause; leftover pick **1. Implementer with verbal plan** / explicit implement = verbal spec no plan file; slash `/implement-plan {n}` disk/file ≠ verbal; not `ok`/`yes`/`go`
 
 ## Generate
 
+SoT: `.rulesync/skills` + `.rulesync/reference`. Generate maps anything placed there. `.agents` / `.claude` (and other host trees) are mirrors, not SoT; no mirror scan.
+
 Pipeline (no `-t geminicli`):
 
 1. `rulesync generate` — emit grok / claude / codex / antigravity
@@ -141,7 +146,7 @@ Emit writes other-CLI trees from `.rulesync` for the **next** process of that CL
 ## Config
 
 - SoT merge into consumer repo; existing configs kept where not grunt-owned
-- Globals: first init apply; re-init auto-skip (sentinel / telemetry) or `--skip-globals`
+- Globals: first init apply; re-init auto-skip (sentinel) or `--skip-globals`
 - `sync-globals` / `purge-mcps`: dry-run default; `--apply` writes
 - Hosts: grok claude codex gemini antigravity
 
@@ -155,6 +160,18 @@ Draw **one** CLI host bubble. That bubble is **this** session’s CLI: Grok Buil
 
 User-visible conversation attaches only to the parent. Children never talk to the user. Children never spawn.
 
+### Host support (GAP)
+
+Not feature-parity across hosts. In-tree mapping only; do not invent peek/kill APIs. GAP rows: no fake peeks, no auto-kill; block on spawn return and classify `done`.
+
+| Host | Spawn | Peek | Kill |
+| --- | --- | --- | --- |
+| Grok | `spawn_subagent` `background:true` → `task_id` | `get_command_or_subagent_output` + `timeout_ms=60000` | `kill_command_or_subagent` (user-ask only) |
+| Claude Code | `Agent` if the parent session exposes it | GAP unless an in-tree schema names a status/output tool on that id (do not invent `TaskOutput`); else block on Agent return and classify `done`. Agent launch ≠ child done; in-flight host Stop → only `[orchestrator]: wait grunt`; no SendMessage | GAP unless in-tree; no auto-kill |
+| Codex | host agent/call | GAP; block on host agent/call return; classify `done` | GAP; no auto-kill |
+| Antigravity | main-session parent | GAP peek/kill; main-session parent | GAP; no auto-kill |
+| Gemini | not emitted; tracked gap | GAP; no fake peeks | GAP; no auto-kill |
+
 ### Nested diagram
 
 Same topology as the session recap; every legal edge labeled.
@@ -162,7 +179,7 @@ Same topology as the session recap; every legal edge labeled.
 ```
  USER
   │
-  │  session in/out  (parent only; tagged one-line recap; advise leftover 1./2. own lines)
+  │  session in/out  (parent only; tagged one-line recap; advise leftover 1./2./3. own lines)
   │  TUI local; completion tokens from Model API (mixed)
   ▼
 ┌──────────────────────── CLI HOST (this process) ────────────────────────┐
@@ -308,6 +325,8 @@ Use these labels. Do not revive “prompt input” or “agent to use”.
 
 Repo-relative (repository root):
 
+- `.rulesync/reference/INDEX.md` — aggregate catalog composed from slices (law.md, skills-map.md, refs-map.md). Maps/law = slices for deep dive. Always. Not if-maps-else
+- `.rulesync/reference/law.md` — domain law stub (protocol stays cascade/overview)
 - `.rulesync/reference/cascade.md` — parent-only spawn, peek/kill table, `need:` / `resume_from`, isolation `verdict:`
 - `.rulesync/reference/rtk.md` — Bash/shell stdout compression
 - `.rulesync/reference/map.md` — cheap outline of protocol, scripts, generated trees
@@ -318,17 +337,19 @@ Repo-relative (repository root):
 
 ## Layout
 
-Published (`package.json` `files`): `bin/grunt.js` `cli` `scripts/check-globals.mjs` `scripts/emit-agent-shell-tools.mjs` `scripts/emit-gemini.mjs` `scripts/emit-mcp-policy.mjs` `scripts/gate-fat-tools.mjs` `scripts/hooks-union.mjs` `scripts/grunt-job.mjs` `scripts/parse-need.mjs` `scripts/persist-handoff.mjs` `scripts/persist-plan.mjs` `scripts/purge-global-mcps.mjs` `scripts/scrub-spawn-prompt.mjs` `scripts/scrub-text-lib.mjs` `scripts/sync-global-settings.mjs` `scripts/telemetry.mjs` `scripts/browser.mjs` `scripts/doctor.mjs` `scripts/scrub-text` `.rulesync` `.grok` `.codex` `.claude` `.agents` `AGENTS.md` `CLAUDE.md` `.mcp.json` `README.md` `LICENSE`
+Published (`package.json` `files`): `bin/grunt.js` `cli` `scripts/check-globals.mjs` `scripts/emit-agent-shell-tools.mjs` `scripts/emit-gemini.mjs` `scripts/guarded-roots.mjs` `scripts/emit-mcp-policy.mjs` `scripts/gate-fat-tools.mjs` `scripts/hooks-union.mjs` `scripts/pipeline.mjs` `scripts/grunt-job.mjs` `scripts/parse-need.mjs` `scripts/persist-handoff.mjs` `scripts/persist-plan.mjs` `scripts/purge-global-mcps.mjs` `scripts/scrub-spawn-prompt.mjs` `scripts/scrub-text-lib.mjs` `scripts/sync-global-settings.mjs` `scripts/browser.mjs` `scripts/doctor.mjs` `scripts/scrub-text` `.rulesync` `.grok` `.codex` `.claude` `.agents` `AGENTS.md` `CLAUDE.md` `.mcp.json` `README.md` `LICENSE` `CHANGELOG.md`
+
+No `scripts/*.test.ts` `scripts/fixtures/` `docs/` `coverage/` `vitest.config.ts` in `files`. `cli` dir ships whole (includes `cli/*.test.ts`).
 
-No `scripts/*.test.ts` `scripts/fixtures/` `docs/` `coverage/` `vitest.config.ts` in `files`.
+Not packed: `GEMINI.md` `.gemini/` — `emit-gemini.mjs` writes them on `generate` / `init` (`GEMINI.md` → `@AGENTS.md`). Not in `files`.
 
-Repo root (also): `coverage/` `.gemini/` — no `src/` no `CONTRIBUTING` no `docs/`
+Repo root (also): `coverage/` `.gemini/` `GEMINI.md` — no `src/` no `CONTRIBUTING` no `docs/`
 
 - `bin/grunt.js` — CLI bin
 - `cli/grunt.mjs` — commands
-- `scripts/` — generate emits `telemetry.mjs` (re-init sentinel) `scrub-text`
-- `.rulesync/` — SoT (subagents skills reference)
-- `.claude/` `.grok/` `.codex/` `.agents/` `.gemini/` — host emit
+- `scripts/` — init copies product scripts (`grunt-job.mjs` `scrub-text` …). Re-init sentinels: `.grok/hooks/orchestrate-parent.js` `.rulesync` `<!-- grunt:begin -->`
+- `.rulesync/` — SoT (subagents skills reference). Skills + reference maps on generate; host trees are mirrors
+- `.claude/` `.grok/` `.codex/` `.agents/` `.gemini/` — host emit; not SoT; no mirror scan
 - `coverage/` — vitest local not published
 
 ## Develop
@@ -349,7 +370,7 @@ npm i && npm test
 
 Keep these four flows only:
 
-1. “Create me a react weather app” → thinker plan/recap-stop + pick 1.Implement 2.Tweak → user picks 1 or `/implement-plan` → implementer write → recap
+1. “Create me a react weather app” → thinker plan/recap-stop + pick 1.Implementer with verbal plan 2.Implementer with file plan 3.Tweak → user picks 1 (verbal spec) or 2 (file plan one-shot) or `/implement-plan {n}` → implementer write → recap
 2. “What is 2+2” → grunt → `[grunt]:` echo
 3. Marvel theatrical next → grunt `job:web` → recap
 4. `.logs` 3/6/2021 tag `framework bug` → grunt local search → recap

package/cli/init.mjs

@@ -2,6 +2,11 @@ import { execFileSync } from "node:child_process"
 import fs from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
+import {
+  WORKSPACE_SKILLS_REL,
+  findSkillContentConflicts,
+  formatSkillConflictWarn,
+} from "../scripts/skill-conflicts.mjs"
 
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
 
@@ -9,10 +14,12 @@ const PRODUCT_SCRIPTS = [
   "check-globals.mjs",
   "emit-agent-shell-tools.mjs",
   "emit-gemini.mjs",
+  "emit-maps.mjs",
   "guarded-roots.mjs",
   "emit-mcp-policy.mjs",
   "gate-fat-tools.mjs",
   "hooks-union.mjs",
+  "pipeline.mjs",
   "grunt-job.mjs",
   "parse-need.mjs",
   "persist-handoff.mjs",
@@ -21,9 +28,9 @@ const PRODUCT_SCRIPTS = [
   "scrub-spawn-prompt.mjs",
   "scrub-text-lib.mjs",
   "sync-global-settings.mjs",
-  "telemetry.mjs",
   "browser.mjs",
   "doctor.mjs",
+  "skill-conflicts.mjs",
   "scrub-text",
 ]
 
@@ -74,14 +81,13 @@ function destHasGruntSentinel(dest) {
 
 export 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 shouldAutoSkipGlobals(dest) {
-  return destHasGruntSentinel(dest) || fs.existsSync(path.join(dest, "scripts", "telemetry.mjs"))
+  return destHasGruntSentinel(dest)
 }
 
 function detectNewline(text) {
@@ -379,7 +385,7 @@ export function mergePackageJson(dest, pkgRoot) {
   const srcPkg = JSON.parse(fs.readFileSync(path.join(pkgRoot, "package.json"), "utf8"))
   destPkg.scripts = { ...(destPkg.scripts || {}) }
   for (const [k, v] of Object.entries(srcPkg.scripts || {})) {
-    if (k === "test") continue
+    if (k === "test" || k.endsWith(":raw")) continue
     destPkg.scripts[k] = mergeScriptValue(k, v, destPkg.scripts[k])
   }
   destPkg.devDependencies = { ...(destPkg.devDependencies || {}) }
@@ -408,6 +414,17 @@ export function init(dest, { pkgRoot: pkgRootOpt, execFileSync: exec = execFileS
   const self = samePath(dest, pkgRoot)
 
   phase("merge", () => {
+    const wsSkills = path.join(dest, WORKSPACE_SKILLS_REL)
+    const pkgSkills = path.join(pkgRoot, WORKSPACE_SKILLS_REL)
+    if (!samePath(wsSkills, pkgSkills)) {
+      for (const c of findSkillContentConflicts({
+        workspaceSkillsDir: wsSkills,
+        packagedSkillsDir: pkgSkills,
+      })) {
+        console.warn(formatSkillConflictWarn(c.name))
+      }
+    }
+
     for (const dir of COPY_DIRS) {
       const src = path.join(pkgRoot, dir)
       const d = path.join(dest, dir)