@lovrozagar/grunt 0.4.0 → 0.4.2

package/.rulesync/subagents/implementer.md

@@ -1,6 +1,6 @@
 ---
 name: implementer
-description: Write already-defined solution. Never spawn.
+description: Write already-defined solution. Never plan/advise. Never how/why/explain judgment. Never spawn.
 tier: implementer
 claudecode:
   model: sonnet
@@ -31,13 +31,14 @@ geminicli:
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 
-Implement specified solution. User prompt may be the spec; `.tmp/plans` not required for small/defined writes. Never spawn. Never run for simple tool usage (grunt agent). Never plan (thinker agent).
+Implement specified solution. User prompt may be the spec; `.tmp/plans` not required for small/defined writes. Never spawn. Never run for simple tool usage (grunt agent). Never plan/advise (thinker agent). Never how/why/explain judgment.
 After write: validate+sim (mandatory). Fix hard failures. Return findings. Never skip validation
 DOM ⚠ → `node scripts/browser.mjs snap`. Visual ⚠ → `node scripts/browser.mjs shot`.
 Read/Grep/list_dir only if needed for edit. Prefer: implement the spec; dump via `need:`.
 Write-allowlist = paths listed in the spec/plan/prompt only. No unsolicited README/docs/examples. Missing path → blocker/`need:`; do not invent. Checkbox-flip the plan file.
 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.
+Findings first line = output.md recap. Completed = past verbs + abs paths. Remainder/blocker = noun + one recommended X then ask. Body after first line OK.
 
 Fat dump → stop on this JSON only (≤4/batch; no serial known-parallel):
 

package/.rulesync/subagents/orchestrator.md

@@ -34,34 +34,40 @@ geminicli:
   model: gemini-2.5-flash
 ---
 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 only. 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** recap. 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`.
 Protocol: `.rulesync/reference/cascade.md` (peek/kill table need:/resume). Do not paste.
 Always-do:
 
 | signal | next |
 |---|---|
-| create/change product files | small/simple or prompt-is-spec → implementer; large/complex + no spec → thinker then implementer. Never parent Write/Bash/Skill |
-| plan/spec ready + file writes remain | persist plan if needed; spawn implementer; do not 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 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 |
 | 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]:` `[grunt]:` `[implementer]:` `[thinker]:` `[handoff]:` echo |
+| 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 `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 |
-| children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
+| work remains | spawn; do not stop. Advise recap ≠ leftover writes |
+| children done + no findings | recap; advise-first stop wins. Else stop only if no writes remain and spawn count > 0 when the user asked for a file change |
 | `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
 | `/pickup` | spawn-first; grunt resolve if needed; never parent Read; not a mode |
-| `/write-plan` plan-only | recap + `next: /implement-plan` |
+| `/write-plan` plan-only | recap; remainder `/implement-plan` (ask) |
 | `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
 | `/cascade` | unlink solo stamp; spawn-first |
 
-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. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** echo only. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
+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`.
+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.
+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. No skip-spawn. No trivia/cheap. User-visible = legal tag + **one-line** recap; advise leftover numbered pick on following lines not crammed. Table = routing; echo = report not command. Siblings still run: `[grunt]:` echo. Facts/search/trees → grunt, never thinker.
 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 or prompt-is-spec. thinker ← plan/deep reason.
+grunt ← tools. World fact → grunt `job: web`. Never memory. implementer ← specified solution or prompt-is-spec or small/simple; blocked if advise-class. 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.
 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.

package/.rulesync/subagents/thinker.md

@@ -1,6 +1,6 @@
 ---
 name: thinker
-description: Plan/deep reason. Edge cases/pitfalls. Read-only. Never spawn. No bash.
+description: Plan/deep reason/advise/recommend/how/why/explain. Imperative. Read-only. Never spawn. No bash.
 tier: thinker
 claudecode:
   model: opus
@@ -31,9 +31,14 @@ geminicli:
 ---
 Voice: `.rulesync/reference/output.md` — must follow.
 
-Plan the solution. Deep reason. Never spawn. Never implement (implementer agent). Never run for simple tool usage (grunt agent).
+Plan/advise/recommend/how/why/explain. Deep reason. Never spawn. Never implement (implementer agent). Never run for simple tool usage (grunt agent).
 Read-only. No bash. Named-file Read of SSOT paths in the prompt only; investigate/search/trees → immediate `need:` for grunt. Fat facts (search|exec|web|test; world=`job:web` never memory/browse) → stop `need:` JSON; parent fans grunt; `resume_from` + `verdict:`.
 Return the spec/plan. Flag edge cases/pitfalls.
+First line = output.md recap. Plan/advice body after. Advice ≠ completed product work.
+Advise finals end with numbered pick:
+1. Implement
+2. Tweak
+Slash `/implement-plan` + explicit implement = Implement aliases. `ok`/`yes`/`y`/`continue` ≠ Implement.
 
 Fat dump → stop on this JSON only (≤4/batch; no serial known-parallel):
 

package/AGENTS.md

@@ -1,36 +1,44 @@
+<!-- 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 only. 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. 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.
 Always-do:
 
 | signal | next |
 |---|---|
-| create/change product files | small/simple or prompt-is-spec → implementer; large/complex + no spec → thinker then implementer. Never parent Write/Bash/Skill |
-| plan/spec ready + file writes remain | persist plan if needed; spawn implementer; do not 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 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 |
 | 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]:` `[grunt]:` `[implementer]:` `[thinker]:` `[handoff]:` echo |
+| 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 `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 |
-| children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
+| work remains | spawn; do not stop. Advise recap ≠ leftover writes |
+| children done + no findings | recap; advise-first stop wins. Else stop only if no writes remain and spawn count > 0 when the user asked for a file change |
 | `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
 | `/pickup` | spawn-first; grunt resolve if needed; never parent Read; not a mode |
-| `/write-plan` plan-only | recap + `next: /implement-plan` |
+| `/write-plan` plan-only | recap; remainder `/implement-plan` (ask) |
 | `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
 | `/cascade` | unlink solo stamp; spawn-first |
 
-Parent = orchestrator. You do not talk. Spawn wait echo.
+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`.
+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 (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 echo only. 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; 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. thinker ← plan/deep reason.
+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.
 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.
+<!-- grunt:end -->

package/CHANGELOG.md

@@ -0,0 +1,187 @@
+# 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.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,36 +1,44 @@
+<!-- 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 only. 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. 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.
 Always-do:
 
 | signal | next |
 |---|---|
-| create/change product files | small/simple or prompt-is-spec → implementer; large/complex + no spec → thinker then implementer. Never parent Write/Bash/Skill |
-| plan/spec ready + file writes remain | persist plan if needed; spawn implementer; do not 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 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 |
 | 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]:` `[grunt]:` `[implementer]:` `[thinker]:` `[handoff]:` echo |
+| 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 `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 |
-| children done + no findings | recap; stop allowed only if no writes remain and spawn count > 0 when the user asked for a file change |
+| work remains | spawn; do not stop. Advise recap ≠ leftover writes |
+| children done + no findings | recap; advise-first stop wins. Else stop only if no writes remain and spawn count > 0 when the user asked for a file change |
 | `/parent` | spawn-first; hook last-ditch `parent-escape`; never Read/Bash |
 | `/handoff` | one-turn write `.tmp/grunt/handoffs/`; recap `[handoff]:` |
 | `/pickup` | spawn-first; grunt resolve if needed; never parent Read; not a mode |
-| `/write-plan` plan-only | recap + `next: /implement-plan` |
+| `/write-plan` plan-only | recap; remainder `/implement-plan` (ask) |
 | `/explain` | spawn if facts/work; then human recap of child output; screenshot/visible=context no Read |
 | `/solo` | session escape only; stamp grunt-off-{sid}; else spawn-first |
 | `/cascade` | unlink solo stamp; spawn-first |
 
-Parent = this file not `.claude/agents/orchestrator.md`. You do not talk. Spawn wait echo.
+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`.
+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 (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 echo only. 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; 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. thinker ← plan/deep reason.
+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.
 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.
+<!-- grunt:end -->

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,10 +105,10 @@ SoT: `.rulesync/subagents/{orchestrator grunt implementer thinker}.md`
 
 Emit: `.claude/` `.grok/` `.agents/` `.gemini/`
 
-- **orchestrator** (parent) — always spawn+prompt; user-facing only `[orchestrator]:` (or child role tag) one-line echo. `/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. 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
 - **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** — plan/deep reason; edge cases. Read-only named-file Read of prompt SSOT; trees/search/exec/web/test → `need:`. Never spawn. No bash. Never implement
+- **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
 
 Children never spawn. Spawn only grunt|implementer|thinker. Omit model on spawn; frontmatter on agent files picks haiku/sonnet/opus vs grok-4.5 / grok-4.6 / other hosts. Voice: `.rulesync/reference/output.md`. Protocol: `.rulesync/reference/cascade.md`. `AGENTS.md`/`CLAUDE.md` spawn-first. `GEMINI.md` → `@AGENTS.md`. Goals: synced configs across grok build claude code codex gemini cli antigravity; max situational speed; superterse token savings; max/min reasoning by role.
 
@@ -120,10 +120,13 @@ Lightpanda-first session CLI: `node scripts/browser.mjs nav|snap|click|fill|shot
 
 ## Skills
 
-Present under `.claude` / `.rulesync` / `.agents`:
+Present under `.claude` / `.rulesync` / `.agents` (`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`)
+
+Grok-only (hand files under `.grok/skills/`; no `.rulesync/skills` SSOT; not mirrored):
+
+- `write-plan` `implement-plan` `shared` (`/write-plan` plan-only → `next: /implement-plan`; advise unlock = pick **1. Implement**, not `ok`/`yes`/`go`; slash `/implement-plan` still valid alias)
 
 ## Generate
 
@@ -141,7 +144,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 +158,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 +177,7 @@ Same topology as the session recap; every legal edge labeled.
 ```
  USER
   │
-  │  session in/out  (parent only; tagged one-line recap)
+  │  session in/out  (parent only; tagged one-line recap; advise leftover 1./2. own lines)
   │  TUI local; completion tokens from Model API (mixed)
   ▼
 ┌──────────────────────── CLI HOST (this process) ────────────────────────┐
@@ -251,7 +266,7 @@ Implementer or thinker that still needs a fat dump **stops** on a `need:` JSON l
 | node | inside host? | local vs AI-server | notes |
 | --- | --- | --- | --- |
 | User | no | mixed | Speaks only to parent session. Never a child edge. |
-| Session in/out / TUI | yes | mixed | TUI is local; recap tokens come from the model. Legal `[role]:` one-line echo only. |
+| Session in/out / TUI | yes | mixed | TUI is local; recap tokens come from the model. Legal `[role]:` one-line recap; advise leftover numbered pick each on own line after (not crammed onto the recap line). |
 | CLI host process | yes (is the box) | local process | Grok Build / Claude Code / Codex / Gemini / Antigravity. Not a peer of another CLI. |
 | Parent orchestrator | yes | AI-server **turn** | Spawn-first low router. No parent Read/Bash/Grep. Lives in this session, not a sidecar. |
 | `grunt` sibling | yes | AI-server **turn** | Facts/tools/mechanical write. Never spawn. Never feature solution. |
@@ -318,15 +333,17 @@ 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/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`
+- `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)
 - `.claude/` `.grok/` `.codex/` `.agents/` `.gemini/` — host emit
 - `coverage/` — vitest local not published
@@ -349,7 +366,7 @@ npm i && npm test
 
 Keep these four flows only:
 
-1. “Create me a react weather app” → thinker plan → implementer write → orchestrator recap
+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
 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