@lovrozagar/grunt 0.4.2 → 0.5.2

package/CLAUDE.md

@@ -1,43 +1,50 @@
 <!-- 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: one empty blank line after recap/body then numbered pick each on own line. 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 iff Implement-typed). Never parent Write/Bash/Skill |
+| plan/spec ready + file writes remain | leftover pick1/pick2 / `/implement-plan {n}` / explicit implement (=pick1 iff Implement-typed) only. Implement pick1 = spawn implementer + last [thinker] recap as spec; no `.tmp/grunt/plans`; no write-plan; no implement-plan. Implement pick2 = persist `.tmp/grunt/plans/{n}` then implementer `plan=/abs/...` one-shot skip pause. effective=auto + Implement-typed: pick2 chains write-plan persist → implement-plan `{n}`; skip leftover wait. Write pick1 = `/tmp` persist recap; no implementer. Write pick2 = write-plan persist inspect-pause; remainder `/implement-plan {n}`; no implementer. slash `/write-plan` ≠ leftover 2. `ok`/`yes`/`y`/`continue` ≠ either. Thinker recap alone = recap-stop |
 | tools/facts/git/test/mechanical write | spawn grunt |
+| snippet / cite / "what is X" | spawn grunt `job:web`. URL-in-a-cite ≠ browse |
+| URL / browse / click / fill / snap / live DOM | spawn grunt; child prompt must include abs `.rulesync/skills/browser/SKILL.md` and `.rulesync/reference/browser.md`; Read then `node scripts/browser.mjs`; Lightpanda default; never websearch that page |
 | 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 |
 | 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]:` |
+| `/tmp` | one-turn write `.tmp/grunt/`; recap `[tmp]:` |
 | `/pickup` | spawn-first; grunt resolve if needed; never parent Read; not a mode |
-| `/write-plan` plan-only | recap; remainder `/implement-plan` (ask) |
+| `/write-plan` plan-only | recap; remainder `/implement-plan` (ask). effective=auto + Implement-typed → persist then implement-plan `{n}` skip leftover wait; Write-typed still inspect-pause leftover wait |
 | `/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 |
+| `/solo` | session escape; stamp spawn-mode-{sid} iff slash≠config; always unlink grunt-off; else spawn-first |
+| `/cascade` | restore cascade; stamp spawn-mode-{sid} iff slash≠config; always unlink grunt-off; spawn-first |
+| `/auto` | session leftover-gate auto; stamp auto-ask-{sid} iff slash≠config; not spawn-escape; not autofix |
+| `/ask` | session leftover-gate ask; stamp auto-ask-{sid} iff slash≠config; not leftover y/n; not pick 3 |
 
-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.
+Advise leftover: numbered pick each on own line after tagged recap; one empty blank line immediately before leftover 1. (leftover last; not adjacent to recap/body). Always-print typed leftover triple (advise-class final recap only). One verb per recap; never jammed Implement/write. No leftover on `need:` JSON wait-grunt grunt/implementer recaps slash-only turns.
+1. {Implement|Write} with verbal plan
+2. {same verb} with file plan
+3. Tweak
+Type Implement = in-repo product writes. Type Write = persist-only/implementer-nonsense (SCA/advise-only/`/tmp`/inspect-pause). Recap remainder still names the human gate; leftover is not `4. Contact bank`. `/handoff` stays slash not Write pick1. No omit 1/2. No frozen 4. Do not relabel 3. Parent echoes printed leftover. Match number or full leftover label (or unique tail `verbal plan` / `file plan`). Always-do leftover match printed lines; not Skill-name (`2` ≠ write-plan). Implement pick1 = spawn implementer; paste last [thinker] recap as spec (how+why; implementer must not paste why into code comments); no `.tmp/grunt/plans`; no write-plan; no implement-plan. Implement pick2 = persist `.tmp/grunt/plans/{n}` then spawn implementer `plan=/abs/...` one-shot skip pause. Write pick1 = `/tmp` persist recap/body under `.tmp/grunt/`; no implementer. Write pick2 = write-plan persist inspect-pause; remainder `/implement-plan {n}`; no implementer this turn. 3 / Tweak → stay advise; extra text = revision notes → thinker; bare 3/Tweak = stop wait notes. Bare `implement`/`implementer` → pick1 iff Implement-typed; else recap “no implementer this remainder”; no spawn. Bare `write` → pick1 iff Write-typed; else not a match. Type-mismatch → that recap no spawn. Alias `Implementer with …` → pick1/pick2 iff Implement-typed. `/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 pick.
 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 spawn-mode-{sid} iff slash≠config; unlink grunt-off) 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 printed leftover; always-print typed triple). Echo = report not command. Siblings still run: `[grunt]:` echo. No skip-spawn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`; recap `[handoff]:`. `/tmp` = one-turn in-parent write to `.tmp/grunt/`; recap `[tmp]:`. `/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.
+grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; snippet/cite/"what is X": `job: web`; URL/browse/click/fill/snap/live DOM: paste skill+browser.md abs paths, never websearch that page; 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. Browse tags match → prompt must include abs `.rulesync/skills/browser/SKILL.md` and `.rulesync/reference/browser.md`.
 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

@@ -55,7 +55,7 @@ Exit 1 if any required missing; 0 if all required ok. Optional `gh` reported onl
 | chromium-family | yes | linux `sudo apt install chromium` · mac `brew install --cask chromium` or `google-chrome` · win `winget install Google.Chrome` / `Microsoft.Edge` + PATH |
 | gh | no | report only |
 
-Rulesync schema doctor is separate: `npm run rulesync:doctor`.
+Rulesync schema doctor is separate: `npm run grunt:rulesync:doctor`.
 
 ## Usage
 
@@ -67,12 +67,12 @@ Rulesync schema doctor is separate: `npm run rulesync:doctor`.
 
 ### Commands
 
-- `init` → `init()` — merge SoT, `npm install`, `rulesync:generate`, `sync:globals:apply`, `rulesync:check`
-- `generate` → `npm run rulesync:generate`
-- `check` → `npm run rulesync:check`
-- `sync-globals` → `npm run sync:globals` (dry-run); `--apply` → `sync:globals:apply`
-- `purge-mcps` → `npm run purge:global-mcps` (dry-run); `--apply` → `purge:global-mcps:apply`
-- `doctor` → `npm run doctor` (`node scripts/doctor.mjs`). Rulesync schema: `npm run rulesync:doctor`
+- `init` → `init()` — merge SoT, `npm install`, `grunt:rulesync:generate`, `grunt:sync:globals:apply`, `grunt:rulesync:check`
+- `generate` → `npm run grunt:rulesync:generate`
+- `check` → `npm run grunt:rulesync:check`
+- `sync-globals` → `npm run grunt:sync:globals` (dry-run); `--apply` → `grunt:sync:globals:apply`
+- `purge-mcps` → `npm run grunt:purge:global-mcps` (dry-run); `--apply` → `grunt:purge:global-mcps:apply`
+- `doctor` → `npm run grunt:doctor` (`npx grunt doctor` / `node scripts/doctor.mjs` stay). Rulesync schema: `npm run grunt:rulesync:doctor`
 - `help`
 - `version`
 
@@ -85,11 +85,12 @@ Rulesync schema doctor is separate: `npm run rulesync:doctor`.
 
 ## Init
 
-- Merge SoT `npm install` `rulesync:generate` `sync:globals:apply` `rulesync:check`
+- Merge SoT `npm install` `grunt:rulesync:generate` `grunt:sync:globals:apply` `grunt:rulesync:check`
 - `--skip-globals` skips apply
 - 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
+- Breaking: consumer npm scripts are `grunt:<SoT-key>` (`grunt:rulesync:generate`, `grunt:doctor`). Re-init migrates `package.json` (owned unprefixed keys + suffixes; `npm run` refs in other dest scripts). CI/husky/`npm run rulesync:*` / `npm run doctor` must switch. No aliases. SoT repo scripts stay unprefixed (`npm run rulesync:generate`).
 
 ## Version bump
 
@@ -105,8 +106,8 @@ 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
-- **grunt** — tools: facts/search/exec/git/web/test/low-reason mechanical write. Isolation `verdict:`. Never feature solution. Never spawn. World fact: `job: web`
+- **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; one empty blank line immediately before leftover 1. (leftover last; not adjacent to recap/body) — 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`; `/tmp` writes `.tmp/grunt/{serial}-{slug}-{stamp}.{ext}`; `/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. Snippet/cite/"what is X"/world fact: `job: web`. URL/browse/click/fill/snap/live DOM: browser rail (`node scripts/browser.mjs`; Lightpanda default); child prompt includes `.rulesync/skills/browser/SKILL.md` + `.rulesync/reference/browser.md`; never websearch that page. URL-in-a-cite ≠ browse. No `job:browse`; parent does not Skill-invoke `browser`
 - **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
 
@@ -114,22 +115,24 @@ Children never spawn. Spawn only grunt|implementer|thinker. Omit model on spawn;
 
 ## Browser
 
-Lightpanda-first session CLI: `node scripts/browser.mjs nav|snap|click|fill|shot|pdf|stop|doctor|ensure`. Zero MCP. Zero env knobs. Chromium only for `shot`/`pdf`/`trace`, Windows, missing Lightpanda, one probe-fail replay, or paint hosts. Session: `.tmp/grunt/browser/`. Spec: [`.rulesync/reference/browser.md`](.rulesync/reference/browser.md).
+Lightpanda-first session CLI: `node scripts/browser.mjs nav|snap|click|fill|shot|pdf|stop|doctor|ensure`. Zero MCP. Zero env knobs. Chromium only for `shot`/`pdf`/`trace`, Windows, missing Lightpanda, one probe-fail replay, or paint hosts. Session: `.tmp/grunt/browser/`. Spec: [`.rulesync/reference/browser.md`](.rulesync/reference/browser.md). Parent routes URL/browse/click/fill/snap/live DOM to grunt (paste skill+browser.md abs paths; never Skill-invoke `browser`; no `job:browse`). URL-in-a-cite ≠ browse.
 
 `node scripts/browser.mjs doctor` (alias `ensure`) runs the unified doctor (`scripts/doctor.mjs`). Install engines: [Prerequisites](#prerequisites).
 
 ## Skills
 
-Present under `.claude` / `.rulesync` / `.agents` (`rulesync -f skills` mirrors SSOT):
+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`
+- `browser` `cascade` `commit` `commit-and-push` (1-release alias → `commit-push`) `commit-push` `commit-push-deploy` `commit-push-release` `explain` `handoff` `pickup` `parent` `solo` `tmp` `write-plan` `implement-plan`
 
-Grok-only (hand files under `.grok/skills/`; no `.rulesync/skills` SSOT; not mirrored):
+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` `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)
+`/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
@@ -177,7 +180,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 blank then 1./2./3. own lines)
   │  TUI local; completion tokens from Model API (mixed)
   ▼
 ┌──────────────────────── CLI HOST (this process) ────────────────────────┐
@@ -266,7 +269,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 recap; advise leftover numbered pick each on own line after (not crammed onto the recap line). |
+| 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; one empty blank line immediately before leftover 1. (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. |
@@ -278,7 +281,7 @@ Implementer or thinker that still needs a fat dump **stops** on a `need:` JSON l
 | RTK | yes | **local** | Bash/shell stdout compression only. Not Read/Grep/Glob/prompts/images. |
 | `scrub-spawn-prompt` / `parse-need` / `grunt-job` | yes | **local** | Hooks and scripts. Isolation `verdict:` is grunt output, not a model hop. |
 | emit / generate / init | yes (this repo / install) | **local** | Writes other-CLI configs. Not a runtime line to those CLIs. |
-| WebSearch / web_fetch | tool from host | **remote-not-LLM** | Network search/fetch. Not a second Model API box. World facts: grunt `job: web`. |
+| WebSearch / web_fetch | tool from host | **remote-not-LLM** | Network search/fetch. Not a second Model API box. Snippet/cite/"what is X"/world fact: grunt `job: web`. Live URL/DOM: grunt browser rail, not this box. |
 | MCP | policy deny | n/a | Denied by policy in-tree. Do not draw as a main path. |
 | Model API | **no** (one box outside) | AI-server | This host’s vendor SDK only. Parent and child **turns** complete here. Spawn omits model; frontmatter on `.rulesync/subagents/*.md` picks the model. |
 | Other CLIs | no (not this process) | emit/config only | Same protocol files emitted elsewhere. No hop, no shared peek. |
@@ -323,6 +326,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
@@ -333,7 +338,7 @@ 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/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`
+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-tmp.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`).
 
@@ -344,8 +349,8 @@ Repo root (also): `coverage/` `.gemini/` `GEMINI.md` — no `src/` no `CONTRIBUT
 - `bin/grunt.js` — CLI bin
 - `cli/grunt.mjs` — commands
 - `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
+- `.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
@@ -366,7 +371,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/grunt.mjs

@@ -2,7 +2,7 @@ import { execFileSync } from "node:child_process"
 import { readFileSync } from "node:fs"
 import path from "node:path"
 import { fileURLToPath } from "node:url"
-import { destAlreadyInited, init, shouldAutoSkipGlobals } from "./init.mjs"
+import { destAlreadyInited, init, shouldAutoSkipGlobals, toGruntScriptName } from "./init.mjs"
 import { confirm, isInteractive, select, spinner } from "./prompt.mjs"
 
 const PKG_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..")
@@ -12,12 +12,12 @@ const USAGE = `Usage: grunt [command]
 Default (no command): TTY menu; else init — full setup
 
 Commands:
-  init          Full setup: merge SoT, npm install, rulesync:generate, sync:globals:apply, rulesync:check
-  generate      npm run rulesync:generate
-  check         npm run rulesync:check
-  sync-globals  npm run sync:globals (dry-run; --apply to write)
-  purge-mcps    npm run purge:global-mcps (dry-run; --apply to write)
-  doctor        npm run doctor
+  init          Full setup: merge SoT, npm install, grunt:rulesync:generate, grunt:sync:globals:apply, grunt:rulesync:check
+  generate      npm run grunt:rulesync:generate
+  check         npm run grunt:rulesync:check
+  sync-globals  npm run grunt:sync:globals (dry-run; --apply to write)
+  purge-mcps    npm run grunt:purge:global-mcps (dry-run; --apply to write)
+  doctor        npm run grunt:doctor
   help          Show this help
   version       Print package version
 
@@ -146,24 +146,24 @@ async function dispatch(cmd, flags, interactive) {
     return
   }
   if (cmd === "generate") {
-    npmRun("rulesync:generate")
+    npmRun(toGruntScriptName("rulesync:generate"))
     return
   }
   if (cmd === "check") {
-    npmRun("rulesync:check")
+    npmRun(toGruntScriptName("rulesync:check"))
     return
   }
   if (cmd === "sync-globals") {
-    const script = flags.apply ? "sync:globals:apply" : "sync:globals"
+    const script = flags.apply ? toGruntScriptName("sync:globals:apply") : toGruntScriptName("sync:globals")
     npmRun(script, hostExtra(flags.host))
     return
   }
   if (cmd === "purge-mcps") {
-    npmRun(flags.apply ? "purge:global-mcps:apply" : "purge:global-mcps")
+    npmRun(flags.apply ? toGruntScriptName("purge:global-mcps:apply") : toGruntScriptName("purge:global-mcps"))
     return
   }
   if (cmd === "doctor") {
-    npmRun("doctor")
+    npmRun(toGruntScriptName("doctor"))
     return
   }
   process.stdout.write(USAGE)

package/cli/grunt.test.ts

@@ -6,6 +6,9 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 const init = vi.hoisted(() => vi.fn());
 const destAlreadyInited = vi.hoisted(() => vi.fn(() => false));
 const shouldAutoSkipGlobals = vi.hoisted(() => vi.fn(() => false));
+const toGruntScriptName = vi.hoisted(
+  () => (k) => (String(k).startsWith("grunt:") ? k : `grunt:${k}`),
+);
 const execFileSync = vi.hoisted(() => vi.fn());
 const isInteractive = vi.hoisted(() => vi.fn(() => false));
 const select = vi.hoisted(() => vi.fn());
@@ -15,7 +18,13 @@ const spinner = vi.hoisted(() =>
 );
 const bailIfCancel = vi.hoisted(() => vi.fn((v) => v));
 
-vi.mock("./init.mjs", () => ({ init, destAlreadyInited, shouldAutoSkipGlobals }));
+vi.mock("./init.mjs", () => ({
+  init,
+  destAlreadyInited,
+  shouldAutoSkipGlobals,
+  toGruntScriptName,
+  GRUNT_NPM_PREFIX: "grunt:",
+}));
 vi.mock("node:child_process", () => ({ execFileSync }));
 vi.mock("./prompt.mjs", () => ({
   isInteractive,
@@ -32,12 +41,12 @@ const USAGE = `Usage: grunt [command]
 Default (no command): TTY menu; else init — full setup
 
 Commands:
-  init          Full setup: merge SoT, npm install, rulesync:generate, sync:globals:apply, rulesync:check
-  generate      npm run rulesync:generate
-  check         npm run rulesync:check
-  sync-globals  npm run sync:globals (dry-run; --apply to write)
-  purge-mcps    npm run purge:global-mcps (dry-run; --apply to write)
-  doctor        npm run doctor
+  init          Full setup: merge SoT, npm install, grunt:rulesync:generate, grunt:sync:globals:apply, grunt:rulesync:check
+  generate      npm run grunt:rulesync:generate
+  check         npm run grunt:rulesync:check
+  sync-globals  npm run grunt:sync:globals (dry-run; --apply to write)
+  purge-mcps    npm run grunt:purge:global-mcps (dry-run; --apply to write)
+  doctor        npm run grunt:doctor
   help          Show this help
   version       Print package version
 
@@ -148,22 +157,22 @@ describe("start", () => {
     },
   );
 
-  it("generate npm-runs rulesync:generate", async () => {
+  it("generate npm-runs grunt:rulesync:generate", async () => {
     process.argv = ["node", "grunt", "generate"];
     await start();
     expect(execFileSync).toHaveBeenCalledOnce();
-    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "rulesync:generate"], {
+    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "grunt:rulesync:generate"], {
       cwd: process.cwd(),
       stdio: "inherit",
     });
     expect(init).not.toHaveBeenCalled();
   });
 
-  it("check npm-runs rulesync:check", async () => {
+  it("check npm-runs grunt:rulesync:check", async () => {
     process.argv = ["node", "grunt", "check"];
     await start();
     expect(execFileSync).toHaveBeenCalledOnce();
-    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "rulesync:check"], {
+    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "grunt:rulesync:check"], {
       cwd: process.cwd(),
       stdio: "inherit",
     });
@@ -173,7 +182,7 @@ describe("start", () => {
     process.argv = ["node", "grunt", "sync-globals", "--yes"];
     await start();
     expect(execFileSync).toHaveBeenCalledOnce();
-    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "sync:globals"], {
+    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "grunt:sync:globals"], {
       cwd: process.cwd(),
       stdio: "inherit",
     });
@@ -184,7 +193,7 @@ describe("start", () => {
     await start();
     expect(execFileSync).toHaveBeenCalledWith(
       "npm",
-      ["run", "sync:globals", "--", "--host", "grok"],
+      ["run", "grunt:sync:globals", "--", "--host", "grok"],
       { cwd: process.cwd(), stdio: "inherit" },
     );
   });
@@ -194,7 +203,7 @@ describe("start", () => {
     await start();
     expect(execFileSync).toHaveBeenCalledWith(
       "npm",
-      ["run", "sync:globals:apply", "--", "--host", "grok"],
+      ["run", "grunt:sync:globals:apply", "--", "--host", "grok"],
       { cwd: process.cwd(), stdio: "inherit" },
     );
   });
@@ -212,7 +221,7 @@ describe("start", () => {
     await start();
     expect(execFileSync).toHaveBeenCalledWith(
       "npm",
-      ["run", "sync:globals", "--", "--host", "claude"],
+      ["run", "grunt:sync:globals", "--", "--host", "claude"],
       { cwd: process.cwd(), stdio: "inherit" },
     );
   });
@@ -220,7 +229,7 @@ describe("start", () => {
   it("purge-mcps dry-run default", async () => {
     process.argv = ["node", "grunt", "purge-mcps"];
     await start();
-    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "purge:global-mcps"], {
+    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "grunt:purge:global-mcps"], {
       cwd: process.cwd(),
       stdio: "inherit",
     });
@@ -231,15 +240,15 @@ describe("start", () => {
     await start();
     expect(execFileSync).toHaveBeenCalledWith(
       "npm",
-      ["run", "purge:global-mcps:apply"],
+      ["run", "grunt:purge:global-mcps:apply"],
       { cwd: process.cwd(), stdio: "inherit" },
     );
   });
 
-  it("doctor npm-runs doctor", async () => {
+  it("doctor npm-runs grunt:doctor", async () => {
     process.argv = ["node", "grunt", "doctor"];
     await start();
-    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "doctor"], {
+    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "grunt:doctor"], {
       cwd: process.cwd(),
       stdio: "inherit",
     });
@@ -285,7 +294,7 @@ describe("start", () => {
     select.mockResolvedValue("generate");
     process.argv = ["node", "grunt"];
     await start();
-    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "rulesync:generate"], {
+    expect(execFileSync).toHaveBeenCalledWith("npm", ["run", "grunt:rulesync:generate"], {
       cwd: process.cwd(),
       stdio: "inherit",
     });