@lovrozagar/grunt 0.5.2 → 0.6.0

package/.rulesync/reference/map.md

@@ -7,79 +7,82 @@ tags: [map]
 Cheap outline. Not a file dump.
 
 ## Protocol
-- `.rulesync/reference/cascade.md` — spawn / need / resume
+- `.rulesync/reference/cascade.md` — session agent tools; grunt-job first; spawn grunt when cheaper
 - `.rulesync/reference/rtk.md` — shell compression
-- `.rulesync/reference/browser.md` — Lightpanda-first session CLI (`nav|snap|click|fill|shot|pdf|stop`); not MCP
+- `.rulesync/reference/browser.md` — Lightpanda-first session CLI (`nav|snap|click|fill|scroll|wait|hover|select|shot|pdf|stop`); not MCP
 - `.rulesync/reference/hooks.md` — hook policy
 - `.rulesync/reference/map.md` — this file
 - `.rulesync/reference/output.md` — default voice
+- `.rulesync/reference/scope.md` — size gate; research → suggest → wait → `/write-plan` → `/implement-plan`
 - `.rulesync/reference/law.md` — domain law (stub; protocol stays cascade/overview)
-- Generated catalogs: `.rulesync/reference/INDEX.md` — aggregate catalog composed from slices (law.md, skills-map.md, refs-map.md). Maps/law = slices for deep dive. INDEX always. Not if-maps-else.
+- Generated catalogs: `.rulesync/reference/INDEX.md` — aggregate catalog composed from slices (law.md, skills-map.md, refs-map.md). Maps/law = slices for deep dive. INDEX always. Not if-maps-else
 
 ## Agent SSOT
 - Docs SoT: `.rulesync/skills` + `.rulesync/reference`. Generate maps anything placed there. `.agents` / `.claude` (and other host trees) are mirrors, not SoT; no mirror scan
-- `.rulesync/subagents/{orchestrator,implementer,thinker,grunt}.md`
+- `.rulesync/subagents/{orchestrator,grunt}.md`
 - `.rulesync/rules/overview.md` → `AGENTS.md`
 - `.rulesync/rules/CLAUDE.md` → `CLAUDE.md`
 - Default output: `.rulesync/reference/output.md` (overview.md → AGENTS.md; also agent bodies + CLAUDE.md, not auto-injected)
 
 ## Grok hand files
-- `.grok/hooks/orchestrate-parent.js` + `.grok/hooks/orchestrate-parent.json` — parent spawn/fat/stop/plan-write / SubagentStop intercept
+- `.grok/hooks/orchestrate-parent.js` + `.grok/hooks/orchestrate-parent.json` — spawn/fat/stop/persist / SubagentStop intercept / session receipt
+- Init/upgrade prune (cumulative): retired skills `parent` `solo` `cascade`; agents `implementer` `thinker` (host files + `.grok/roles/{name}.toml` + `.gemini/agents/{name}/`); scripts `telemetry.mjs` `grunt-config.mjs`; `.grok/parent.md`; `.grok/skills/shared`; `.rulesync/grunt.config.jsonc` plus local overlay and example; reserved skill dirs this package no longer ships
 - `.grok/hooks/rtk.json` — RTK
-- `.grok/skills/{parent,explain,handoff,pickup,solo,cascade,auto,ask,commit,commit-and-push,commit-push,commit-push-deploy,commit-push-release,write-plan,implement-plan}/` — generated from `.rulesync/skills/`; do not hand-edit
-- `.grok/parent.md` — 1-line pointer to orchestrator agent; not SessionStart
-- `.grok/roles/*.toml`
+- `.grok/skills/` — generated from `.rulesync/skills/`; do not hand-edit
 - `.grok/global-settings.toml` — merged into `~/.grok/config.toml` by `scripts/sync-global-settings.mjs` (not auto-loaded; project config cannot set `[features]`)
 - `.rulesync/global-settings/` — host manifest and reserved noop payloads
 - `.rulesync/mcp-policy.jsonc` — MCP deny-default SSOT (`default: deny`, `allow: []`)
-- `.rulesync/grunt.config.jsonc` — leftover-gate + spawnMode SSOT (`version` `1`, `leftoverGate` `ask`|`auto` committed default `ask`, `spawnMode` `solo`|`cascade` committed default `cascade` never `solo`). Effective spawn: stamp `spawn-mode-{sid}` > one-release `grunt-off` > config > `cascade`. Fail-closed cascade. Keys independent.
-- `.rulesync/skills/{parent,explain,handoff,pickup,solo,cascade,auto,ask,commit,commit-and-push,commit-push,commit-push-deploy,commit-push-release,browser,write-plan,implement-plan}/` — skill SSOT; `rulesync -f skills` emits `.grok/skills/`, `.claude/skills/`, `.agents/skills/` byte-equal. `/cascade` = exit solo / restore cascade (not a sticky second mode). `/auto` `/ask` = session leftover-gate (not spawn-escape)
+- `.rulesync/skills/{ask,auto,browser,clasp,commit,commit-and-push,commit-push,commit-push-deploy,commit-push-release,explain,google-workspace,handoff,implement-plan,listen,pickup,speak,tmp,write-plan}/` — skill SSOT; `rulesync -f skills` emits host mirrors byte-equal
 
 ## Scripts
 - `scripts/pipeline.mjs` — inner generate/check/watch chain (rulesync + emit-* + hooks-union / check-globals). Called by `guarded-roots`; not a public npm script (`rulesync:generate` `rulesync:check` `rulesync:watch` only)
 - `scripts/guarded-roots.mjs` — snapshot/remerge `AGENTS.md` `CLAUDE.md` `GEMINI.md` around pipeline; check interiors wrapper
-- `scripts/check-globals.mjs` — `$HOME/.grok/config.toml` `[agent].name==orchestrator` + `[features].two_pass_compaction==true`; project `.grok/config.toml` must not have `[features]`/`[agent]`; wired as `sync:globals:check` (also after emit-mcp in `rulesync:check`)
+- `scripts/check-globals.mjs` — `$HOME/.grok/config.toml` `[agent].name==orchestrator` + `[features].two_pass_compaction==true`
 - `scripts/gate-fat-tools.mjs`
 - `scripts/scrub-spawn-prompt.mjs`
 - `scripts/grunt-job.mjs` — flags `--job` `--query` `--path` `--glob` (repeatable) `--cwd`; regex in `--query` OK; never `cd &&`; unknown flags / exec shell-meta → FALLBACK
 - `scripts/parse-need.mjs`
-- `scripts/persist-handoff.mjs` — `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md`; `HANDOFF_NAME:` → slug; H2 `Goal|State|Context|Next|Watch-outs`; `status` `open|resumed|done`
-- `scripts/persist-tmp.mjs` — `.tmp/grunt/{serial}-{slug}-{stamp}.{ext}` root files; `TMP_NAME:` / `TMP_EXT:`; own serial; skip reserved dirs
+- `scripts/persist-handoff.mjs` — `.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md`
+- `scripts/persist-tmp.mjs` — `.tmp/grunt/{serial}-{slug}-{stamp}.{ext}` root files
 - `scripts/persist-plan.mjs`
-- `scripts/sync-global-settings.mjs` — dry-run-by-default merge of `.grok/global-settings.toml` into `$HOME/.grok/config.toml`; manifest in `.rulesync/global-settings/`; `skipKeyPattern` skips MCP; never copies project MCP into `$HOME/.grok`
-- `scripts/purge-global-mcps.mjs` — dry-run-by-default purge of stubborn global MCP sources (`$HOME/.grok/config.toml` plugins + `disabled_mcp_servers`, `$HOME/.cursor/mcp.json` `MCP_DOCKER`); `--apply` writes; never project MCP
-- `scripts/emit-mcp-policy.mjs` — emit project MCP deny-default from `.rulesync/mcp-policy.jsonc` (not `rulesync -f mcp`); owns `.gemini/settings.json` `mcpServers` (merge extra keys)
-- `scripts/emit-gemini.mjs` — `GEMINI.md` (`@AGENTS.md`) + `.gemini/agents/{id}/agent.md` from `.rulesync/subagents` (not `rulesync -t geminicli`); no prune; does not touch settings
-- `scripts/emit-agent-shell-tools.mjs` — after rulesync subagents: rewrite `.claude/agents/grunt.md` body `Bash`; grok/codex/gemini/generic keep `run_terminal_command`
-- `scripts/browser.mjs` — session browser rail `nav|snap|click|fill|shot|pdf|stop`; Lightpanda default; Chromium on verb/OS/probe/paint-host/one-escalate; `.tmp/grunt/browser/`
-- `scripts/grunt-config.mjs` — `loadLeftoverGate(workspaceRoot)` fail-closed `ask`; `loadSpawnMode(workspaceRoot)` fail-closed `cascade`; keys independent
+- `scripts/persist-implementation.mjs` — `.tmp/grunt/implementations/{serial}-{slug}-{stamp}.md`
+- `scripts/sync-global-settings.mjs`
+- `scripts/purge-global-mcps.mjs`
+- `scripts/emit-mcp-policy.mjs`
+- `scripts/emit-gemini.mjs`
+- `scripts/emit-agent-shell-tools.mjs`
+- `scripts/browser.mjs` — session browser rail
+- `scripts/google-workspace.mjs` — Sheets Docs Slides Calendar Gmail Drive
+- `scripts/speak.mjs` — TTS
+- `scripts/listen.mjs` — STT
+- `scripts/setup.mjs` — handheld speak / listen / google-workspace / browser (`~/.grunt/`)
+- `scripts/doctor.mjs` — unified prereqs; optional google-workspace (`oauth` `tokens` `adc` `clasprc`), speak, clasp, ffmpeg, whisper-cli
 
 ## Tmp
-- `.tmp/grunt/plans/` — persist-plan / parent / implementer; format SSOT = `.rulesync/reference/plan-format.md`
-- `.tmp/grunt/orchestrator-logs/` — parent stamps
-- `.tmp/grunt/` — grunt scratch + `/tmp` dumps `{serial}-{slug}-{stamp}.{ext}` at root (not nested `tmp/`)
+- `.tmp/grunt/plans/` — persist-plan; format SSOT = `.rulesync/reference/plan-format.md`
+- `.tmp/grunt/implementations/` — persist-implementation; format SSOT = `.rulesync/reference/implementation-format.md`
+- `.tmp/grunt/orchestrator-logs/` — need-intercept, session-gate, stop-block stamps
+- `.tmp/grunt/` — scratch + `/tmp` dumps `{serial}-{slug}-{stamp}.{ext}` at root (not nested `tmp/`)
 - `.tmp/grunt/browser/` — browser session/profile/shot/pdf (not MCP)
-- `.tmp/grunt/handoffs/` — persist-handoff / `/handoff`; own serial counter (not plan serials)
-
-## Stamps (`.tmp/grunt/orchestrator-logs/`)
-- `tools-used` / `stop-block` / `need-intercept` / `parent-escape` / `auto-ask` / `spawn-mode` — Stop does not waive impl finals for `tools-used`; `/parent` writes `parent-escape-{sid}` once
-- `spawn-mode-{sid}` — spawn session stamp. Body `solo`|`cascade`. Slash==config unlinks. Sid-less: no stamp. Unreadable/bad body ignored (dual-read `grunt-off` else config → cascade). `/solo` `/cascade` always unlink `grunt-off`
-- `grunt-off-{sid}` — one-release dual-read as solo when spawn-mode stamp missing or body not exact `solo`|`cascade`. `/solo` `/cascade` always unlink. Requires a real sid (never the `default` fallback). Do not write new `grunt-off`
-- `auto-ask-{sid}` — leftover-gate session stamp. Body `auto`|`ask`. Slash==config unlinks. Sid-less: no stamp. Unreadable/bad body ignored (fall through config → ask). Not spawn-escape.
+- `.tmp/grunt/handoffs/` — persist-handoff / `/handoff`
+- `.tmp/grunt/stash/` — grunt-job / snap overflow
+- `.tmp/grunt/sessions/{sid}/` — wrote/read/receipt
+- `.tmp/grunt/speak/` — TTS mp3
+- `.tmp/grunt/listen/` — STT wav + `latest.txt`
 
 ## Generated (do not hand-edit; committed, not gitignored)
 - `AGENTS.md`, `CLAUDE.md`
 - `.rulesync/reference/INDEX.md`, `skills-map.md`, `refs-map.md` (`emit-maps.mjs`)
-- `.claude/skills/*`, `.agents/skills/*`, `.grok/skills/{parent,explain,handoff,pickup,solo,cascade,auto,ask,commit,commit-and-push,commit-push,commit-push-deploy,commit-push-release,write-plan,implement-plan}/` (from `.rulesync/skills/`)
+- `.claude/skills/*`, `.agents/skills/*`, `.grok/skills/*` (from `.rulesync/skills/`)
 - `.grok/agents/*`
 - `.claude/agents/*`
 - `.codex/agents/*`
 - `.agents/agents/*`
 - `.grok/config.toml` — project MCP `[[permissions]]` + `[plugins] deny_default`; no `[features]`
 - `.mcp.json` — `mcpServers` from policy allow only
-- `.claude/settings.json` MCP keys (`enableAllProjectMcpServers`, `enabledMcpjsonServers`, `permissions.deny` `mcp__*`); Agent denies/hooks stay
-- `.codex/config.toml` `mcp_servers` (absent when allow empty); keep `[agents] max_depth`
-- `.agents/mcp_config.json` — `mcpServers` from policy allow only
+- `.claude/settings.json` MCP keys; Agent denies/hooks stay
+- `.codex/config.toml` `mcp_servers` (absent when allow empty)
+- `.agents/mcp_config.json`
 - `GEMINI.md` — `@AGENTS.md` pointer (`emit-gemini.mjs`)
-- `.gemini/agents/{orchestrator,implementer,thinker,grunt}/agent.md` — `name` `description` `model` only (`emit-gemini.mjs`)
-- `.gemini/settings.json` — `mcpServers` from policy allow only (`emit-mcp-policy.mjs`; extra keys preserved)
+- `.gemini/agents/{orchestrator,grunt}/agent.md`
+- `.gemini/settings.json` — `mcpServers` from policy allow only

package/.rulesync/reference/output.md

@@ -4,56 +4,8 @@ tags: [output]
 
 # Output
 
-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 that tagged recap; one empty blank line immediately before leftover 1. (leftover last; not adjacent to recap/body) — do not cram 1./2./3. onto the recap line
+en-US unless asked. Concise complete sentences with natural grammar. Skip filler and fluff.
 
-**Mid-turn** (in-flight; first line still legal tag): `[orchestrator]: wait grunt` only. `need:` stop = JSON only. Grunt isolation = `verdict:` only; parent maps to natural recap. ⚠/validate: no recap; spawn. Imperative = routing/mid-turn only.
+Completed work uses past verbs and paths. If more work remains, say what. Ask in English when a choice is real. `/auto` asks on blockers; `/ask` asks after each step.
 
-**Final recap** (children done / child return; omit empty buckets): natural language. No literal `done:` `in_progress:` `left:` `blocked:` tokens. No `|` key join.
-
-Buckets (semantic; not tokens):
-
-- completed — work landed; past verbs + abs paths
-- in-flight — siblings/peek still live; host state not past
-- remainder — more work; noun + one recommended X then ask
-- blocker — cannot continue; noun + one recommended X then ask
-
-Past-tense: completed work = past verbs only. Remainder/blocker = noun + one recommended X then ask. Do not break `need:` JSON, `verdict:`, wait-grunt, or legal first-line tag regex.
-
-Ask = recap line + stop (no invent ask_user_question). Named `Do X?` / `X? y/n`: `y` = accept X. Bare `ok`/`yes`/`y`/`continue` after advise still ≠ pick1/pick2.
-
-**Do not ask** mid-turn / siblings-alive — stay `[orchestrator]: wait grunt` or tag+echo + peek.
-
-Examples:
-```
-[orchestrator]: wrote /abs/a.md
-[orchestrator]: wrote /abs/a.md. Spawn implementer on /abs/b.md? y/n
-[implementer]: missing /abs/b.md. Prefetch via grunt? y/n
-```
-
-Child first line = those buckets in natural language. Body may continue (plans/findings). Parent echo one recap line. Advise leftover continues after it: one empty blank line then numbered pick each on own line. Do not force children to one line only for body/logs.
-
-Advise recap includes why-clause (one clause not treatise): `{decided}. {how-capsule}. {why-clause}`. Why-clause = rejected alt + constraint. Parent echo = that recap verbatim-ish; no-strip; forbid compress-to-verdict. Still one recap line. Do not dump body. Do not invent why if omitted. Pick1 recap-as-spec includes how+why; implementer must not paste why into code comments. Always-why recap ≠ `/explain` (`/explain` = expansion not the why path).
-
-`/write-plan`: remainder `/implement-plan` (ask). `/explain`: same four buckets; sentences OK.
-
-Advise leftover: numbered pick (number or full leftover label, or unique tail `verbal plan` / `file plan`). Always-print typed leftover triple (advise-class final recap only) unless effective leftover-gate=auto and Implement-typed (pick2 chain skip leftover wait). Else always-print typed triple on advise-class final recap. Write-typed under auto still leftover wait. One verb per recap; never jammed `Implement/write`. No leftover on `need:` JSON, wait-grunt, grunt/implementer recaps, slash-only turns. Leftover ⊆ remainder kinds.
-1. {Implement|Write} with verbal plan
-2. {same verb} with file plan
-3. Tweak
-Type Implement — how-capsule = in-repo product writes (code tests `.rulesync/` CLAUDE/AGENTS skills). Product docs in-tree = Implement. Type Write — persist-only or implementer-nonsense: `.tmp/grunt/plans` inspect-pause `/tmp` artifact advise-only how/why with no product writes do-not-code external-human (SCA/bank/credentials). Recap remainder still names the human gate; leftover is not `4. Contact bank`. `/handoff` stays slash not Write pick1. Print all three every advise-class final recap. No omit 1/2. No frozen 4. Do not relabel 3.
-```
-[orchestrator]: wrote /abs/a
-
-1. Implement with verbal plan
-2. Implement with file plan
-3. Tweak
-```
-```
-[orchestrator]: advise-only how. Remainder persist note.
-
-1. Write with verbal plan
-2. Write with file plan
-3. Tweak
-```
-Parent echoes printed leftover lines. Reuse echo: reprint last thinker’s leftover triple. Always-do leftover match printed lines (output.md cascade.md skills Rules); not Skill-name (`2` ≠ write-plan). Stop leftover-lines = recap format only; no code maps leftover numbers → skills; no leftover-label parser. `1` / full label / unique tail `verbal plan` → pick1. `2` / full / `file plan` → pick2. `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 verbal plan` / `Implementer with file plan` → pick1/pick2 iff Implement-typed. 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/...` (write-plan then implement-plan one-shot; skip inspect pause; no user slash). Write pick1 = `/tmp` sequencing: persist recap/body under `.tmp/grunt/`; no implementer. Write pick2 = write-plan sequencing only: thinker draft + persist `.tmp/grunt/plans/{n}`; stop inspect-pause; remainder ask `/implement-plan {n}`; no implementer this turn. `/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.
-Owned-defect recap: `Fix {owned path}`. Leftover always-print typed triple (Implement when in-repo writes). Do not relabel 3 to the bug. Workaround in why-clause not remainder.
+Grunt-job stdout is a sentence plus up to 6 dash facts, cap 8 lines, optional `stash=` receipt.

package/.rulesync/reference/plan-format.md

@@ -1,6 +1,6 @@
 # Plan format (SSOT)
 
-Local implementer checklist. Not a design doc, PR stack, or DAG.
+Local session checklist. Not a design doc, PR stack, or DAG.
 
 ## Path
 
@@ -81,7 +81,7 @@ No required Why heading. Optional why footnote only (not a `##`). Pick2 file pla
 - Fresh plans: all `[ ]`, never `[x]`
 - Marking done: only flip the box. No renumber, delete, or rewrite leaf text
 - Depth 2 default (`N` phase + `N.M` leaf). 3rd level only if a leaf would itself be a mini-plan
-- Every phase `N` has ≥1 leaf `N.M`. Implementer **executes leaves**. Roll up: all children `[x]` ⇒ parent `[x]`
+- Every phase `N` has ≥1 leaf `N.M`. The session agent **executes leaves**. Roll up: all children `[x]` ⇒ parent `[x]`
 - Verify = last numbered phase, same grammar
 - Done plan: every checkbox `[x]`, `status: done`
 
@@ -94,6 +94,8 @@ No required Why heading. Optional why footnote only (not a `##`). Pick2 file pla
 | Steps | bulk of the file; each leaf = one coherent edit or one file-level action |
 | Verify | 1–5 runnable leaves (cmd or observable) |
 
+Tests live in Steps (not a new heading). New behavior or a bug: a failing test leaf before the impl leaf. Other behavior change: a test leaf immediately after the impl leaf. Docs, rename-only, config-only, generated: no test leaf. Verify is the end gate (project cmd or named subset), not a substitute for those leaves. Do not re-run the whole suite after every leaf unless it is cheap.
+
 Thinker cites **absolute paths**. Leaves must be implementable without re-planning. Product fork → pick the narrowest default, state it under Constraints, still emit steps.
 
 ## Validation checklist

package/.rulesync/reference/refs-map.md

@@ -4,11 +4,18 @@
 
 | path | title | tags | summary |
 | --- | --- | --- | --- |
-| .rulesync/reference/browser.md | Browser | browser | Zero-config in-tree session rail. Not MCP. Not env. Not raw Playwright. |
-| .rulesync/reference/cascade.md | Cascade | cascade | Shipped protocol: **parent-only spawn**. Only the parent **orchestrator** session calls `spawn_subagent`. Implementer a… |
+| .rulesync/reference/browser.md | Browser | browser | Zero-config in-tree session rail. Not MCP. Not env. Not raw Playwright. Lightpanda first; swap to Chromium when blocked. |
+| .rulesync/reference/cascade.md | Protocol | cascade | The session agent has tools. Fat Read/Grep/Bash dumps are rewritten to `scripts/grunt-job.mjs` (squeez + stash). Isolat… |
+| .rulesync/reference/clasp.md | Clasp | clasp | Low-level Apps Script CLI. Optional. Doctor reports it. |
+| .rulesync/reference/google-workspace.md | google-workspace | google-workspace | Create and edit Google Sheets, Docs, Slides, Calendar events, and Gmail from the session. |
 | .rulesync/reference/hooks.md | Hooks | hooks | SessionStart: keep empty (token baseline). Do not inject context. Do not register a SessionStart hook on `../../.grok/h… |
-| .rulesync/reference/law.md | Law |  | Protocol stays cascade/overview; domain fills this. |
+| .rulesync/reference/implementation-format.md | Implementation format (SSOT) |  | Local session journal for `/implement-plan`. Not a plan, handoff, or git commit. |
+| .rulesync/reference/law.md | Law |  | Protocol stays overview; domain fills this. |
+| .rulesync/reference/listen.md | Listen | listen | Speech-to-text from the session. Input only. Not TTS. Not a live voice agent. Not MCP. |
 | .rulesync/reference/map.md | Map | map | Cheap outline. Not a file dump. |
-| .rulesync/reference/output.md | Output | output | en-US unless asked. every output maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. Parent and child. E… |
-| .rulesync/reference/plan-format.md | Plan format (SSOT) |  | Local implementer checklist. Not a design doc, PR stack, or DAG. |
+| .rulesync/reference/output.md | Output | output | en-US unless asked. Concise complete sentences with natural grammar. Skip filler and fluff. |
+| .rulesync/reference/plan-format.md | Plan format (SSOT) |  | Local session checklist. Not a design doc, PR stack, or DAG. |
 | .rulesync/reference/rtk.md | RTK | rtk | Shell stdout compression. PreToolUse: Bash → `rtk <cmd>`. Not Read/Grep/Glob/prompts/images. |
+| .rulesync/reference/scope.md | Scope | scope | Default: do the work. Escalate only when it is not a straight shot. This file is the size-gate SSOT. |
+| .rulesync/reference/setup.md | Setup | setup | Handheld machine setup for optional integrations. Any OS. Secrets stay in `~/.grunt/` (Windows `%USERPROFILE%\.grunt`).… |
+| .rulesync/reference/speak.md | Speak | speak | Text-to-speech from the session. Output only. Not STT. Not a mic. Not MCP. Speech-to-text is `/listen`: `.rulesync/refe… |

package/.rulesync/reference/rtk.md

@@ -6,17 +6,18 @@ tags: [rtk]
 
 Shell stdout compression. PreToolUse: Bash → `rtk <cmd>`. Not Read/Grep/Glob/prompts/images.
 
-Grok PostToolUse is observe-only — do not attempt output scrub; compress via RTK / spawn / isolation verdict only.
+Grok PostToolUse is observe-only — do not attempt output scrub; compress via RTK / spawn / isolation facts only.
 
 ## Commands
 
-ls · tree · read · smart · git · gh · glab · aws · psql · pnpm · err · test · json · deps · env · find · diff · log · dotnet · docker · kubectl · oc · summary · grep · rg · init · wget · wc · gain · cc-economics · config · jest · vitest · prisma · tsc · next · lint · prettier · format · playwright · lightpanda · cargo · npm · npx · curl · discover · session · telemetry · learn · run · proxy · pipe · trust · untrust · verify · ruff · pytest · mypy · rake · rubocop · rspec · pip · go · gt · golangci-lint · gradlew · mvn · hook-audit · rewrite · hook · help
+ls · tree · read · smart · git · gh · glab · clasp · aws · psql · pnpm · err · test · json · deps · env · find · diff · log · dotnet · docker · kubectl · oc · summary · grep · rg · init · wget · wc · gain · cc-economics · config · jest · vitest · prisma · tsc · next · lint · prettier · format · playwright · lightpanda · cargo · npm · npx · curl · discover · session · telemetry · learn · run · proxy · pipe · trust · untrust · verify · ruff · pytest · mypy · rake · rubocop · rspec · pip · go · gt · golangci-lint · gradlew · mvn · hook-audit · rewrite · hook · help
 
 **git:** diff · log · status · show · add · commit · push · pull · branch · fetch · stash (list show pop apply drop push) · worktree
 **cargo:** build · test · clippy · check · install · nextest
 **go:** test · build · vet
 **docker:** ps · images · logs · compose (ps logs build)
 **gh:** pr · issue · run · repo
+**clasp:** login · logout · create · clone · pull · push · status · open · run · deploy · logs · setting
 
 Flags: `-v`/`-vv`/`-vvv` · `--ultra-compact` · `--skip-env` · `-h` · `-V`
 

package/.rulesync/reference/scope.md

@@ -0,0 +1,37 @@
+---
+tags: [scope]
+---
+
+# Scope
+
+Default: do the work. Escalate only when it is not a straight shot. This file is the size-gate SSOT.
+
+## Gate
+
+Straight shot: one obvious path, the user named the edit, or a follow-up on work already agreed. Do it. Do not run this file as a ritual.
+
+Not a straight shot: ambiguous goal, two or more valid approaches, cross-cutting, or hard to undo — or the user asked to plan.
+
+Skip the loop: questions, lookups, one-file named edits, "just do it", commits.
+
+`/ask` is not this loop. `/ask` pauses after each execution step. This loop pauses until the approach is agreed. `/auto` already treats a real choice as a blocker; "which approach?" is that blocker.
+
+## Research
+
+Read and search until you can pick an approach. Enough to choose, not a literature review. Fat notes go under `.tmp/grunt/` (`/tmp` if they must persist). Do not add `## Research` to a plan.
+
+## Suggest
+
+5–10 lines: approach, why, rejected alternative, one open question. Not a fake plan. Do not `/write-plan` in the same turn.
+
+## Wait
+
+Stop. One real question. Feedback → research if needed → suggest again. Repeat until the approach is agreed.
+
+## Plan
+
+After agreement only: `/write-plan`. Format: `.rulesync/reference/plan-format.md`. Distill facts into Context, Constraints, Watch-outs. Leaves are the work. Report serial. Stop unless the user said plan and do it.
+
+## Implement
+
+`/implement-plan` in a separate turn, or the same turn only if the user said plan and do it. Skip `[x]`. Write-allowlist = paths listed in the plan. Do not skip test leaves. Journal: `.rulesync/reference/implementation-format.md` under `.tmp/grunt/implementations/` (create on start; not for straight shots). Straight-shot behavior change: run the nearest existing test if the repo has one. Bugfix: repro first. Do not scaffold a test file on a straight shot unless it is a bug.

package/.rulesync/reference/setup.md

@@ -0,0 +1,27 @@
+---
+tags: [setup]
+---
+
+# Setup
+
+Handheld machine setup for optional integrations. Any OS. Secrets stay in `~/.grunt/` (Windows `%USERPROFILE%\.grunt`). Not git. Env still wins over the file.
+
+```
+npm exec grunt setup
+node scripts/setup.mjs
+node scripts/setup.mjs speak
+node scripts/setup.mjs listen
+node scripts/setup.mjs google-workspace
+node scripts/setup.mjs browser
+```
+
+TTY: menu with ok/missing. Already ok asks redo (`--redo` skips the ask). Missing bins: print the OS command (never run it), then re-check PATH. Ends with a four-line status. Non-TTY needs flags (keys / `--creds`). Doctor never installs bins; setup never installs bins either.
+
+| target | what it writes | flags |
+| --- | --- | --- |
+| speak | `~/.grunt/speak.json` | `--elevenlabs-key` `--openai-key` `--provider` `--skip-verify` |
+| listen | same file (`openai` / `listen`) plus `~/.grunt/whisper/` | `--openai-key` `--device` `--skip-download` |
+| google-workspace | Desktop OAuth JSON + tokens under `~/.grunt/` | `--creds PATH` `--account NAME` `--project ID` |
+| browser | nothing (print Lightpanda / Chromium hints; both required except win32 Chromium-only) | |
+
+Do not invent keys. If the session is not a TTY, tell the user to run `grunt setup` in their terminal. This spec is enough. Do not read https://github.com/lovrozagar/grunt#readme unless this file is missing.

package/.rulesync/reference/skills-map.md

@@ -4,20 +4,21 @@
 
 | name | origin | description | task | commandPath | refs |
 | --- | --- | --- | --- | --- | --- |
-| ask | local | Session leftover-gate. /ask sets leftover-gate ask for this session — leftover triple wait on advise-class recaps. Not… |  |  |  |
-| auto | local | Session leftover-gate. /auto sets leftover-gate auto for this session — Implement-typed pick2 chains write-plan persist… |  |  |  |
-| browser | local | Live URL/interact → this; not websearch. /browser or browse a URL. Call node scripts/browser.mjs nav\|snap\|click\|fill\|sh… |  |  |  |
-| cascade | local | Session mode. /cascade exits solo and restores the grunt cascade for this session — spawn, orchestrator, recap, need\|ve… |  |  |  |
+| ask | local | Session flag. Finish one step, recap, then ask before the next. |  |  |  |
+| auto | local | Session flag. Default. Work the task through. Ask on blockers instead of monkey-patching. |  |  |  |
+| browser | local | Browse via node scripts/browser.mjs (Lightpanda). App e2e uses Playwright. |  |  |  |
+| clasp | local | Low-level Apps Script CLI. Prefer /google-workspace for sheet, doc, meeting, mail. |  |  |  |
 | commit | local | Inspect the diff and commit with a Conventional Commits subject line. Use for /commit, "commit this", "commit these cha… |  |  |  |
 | commit-and-push | local | Alias of commit-push (1-release stub). Use for /commit-and-push, "commit and push", "commit this and push". Must push.… |  |  |  |
 | commit-push | local | Commit with a Conventional Commits subject, then push. Use for /commit-push, "commit and push", "commit this and push".… |  |  |  |
 | commit-push-deploy | local | Commit, push, then deploy only if allowlisted infra already exists. Use for /commit-push-deploy, "commit push deploy",… |  |  |  |
 | commit-push-release | local | Commit, push, bump package.json, tag vX.Y.Z, push the tag. CI publishes. Use for /commit-push-release, "commit push rel… |  |  |  |
-| explain | local | One-off human recap. /explain. First action = spawn grunt\|implementer\|thinker if facts/work; else recap already-visible… |  |  |  |
-| handoff | local | Parent writes a session handoff under .tmp/grunt/handoffs/ and tells the user to continue in a fresh session. Use for /… |  |  |  |
-| implement-plan | local | Implementer executes a local .tmp/grunt/plans checklist: continue, resume, or pick among plans. Empty /implement-plan r… |  |  |  |
-| parent | local | One-turn parent-orchestrator escape. Use for /parent. Not a session mode. |  |  |  |
-| pickup | local | Pick up/continue a session handoff under .tmp/grunt/handoffs/. Use for /pickup, pick up, continue handoff, serial, drag… |  |  |  |
-| solo | local | Session mode. /solo disables the grunt cascade for this session — one normal agent, no spawn, no orchestrator. /cascade… |  |  |  |
-| tmp | local | One-off convo artifact dump under .tmp/grunt/. Use for /tmp, dump a draft, save a note/email/script from this session.… |  |  |  |
-| write-plan | local | Thinker drafts a local implementer-ready checklist plan; parent Write persists .tmp/grunt/plans/{serial}-{slug}-{YYYYMM… |  |  |  |
+| explain | local | Longer human recap this reply only. |  |  |  |
+| google-workspace | local | Google Sheets, Docs, Slides, Calendar, Gmail via node scripts/google-workspace.mjs. |  |  |  |
+| handoff | local | Write a session handoff under .tmp/grunt/handoffs/. Continue with /pickup. |  |  |  |
+| implement-plan | local | Execute remaining leaves in a .tmp/grunt/plans checklist. Skip [x]. |  |  |  |
+| listen | local | Speech-to-text via node scripts/listen.mjs (ffmpeg mic + local whisper.cpp, OpenAI fallback). Input only. |  |  |  |
+| pickup | local | Continue a handoff under .tmp/grunt/handoffs/. |  |  |  |
+| speak | local | Text-to-speech via node scripts/speak.mjs (ElevenLabs or OpenAI). Output only. |  |  |  |
+| tmp | local | Dump a one-off convo artifact under .tmp/grunt/. |  |  |  |
+| write-plan | local | Write a local checklist under .tmp/grunt/plans/. Then /implement-plan {n}. |  |  |  |

package/.rulesync/reference/speak.md

@@ -0,0 +1,59 @@
+---
+tags: [speak]
+---
+
+# Speak
+
+Text-to-speech from the session. Output only. Not STT. Not a mic. Not MCP. Speech-to-text is `/listen`: `.rulesync/reference/listen.md` and `node scripts/listen.mjs`.
+
+```
+node scripts/speak.mjs whoami
+node scripts/speak.mjs voices [--provider elevenlabs|openai]
+node scripts/speak.mjs say --text "hello" [--provider elevenlabs|openai] [--voice ID] [--out path] [--play]
+```
+
+`say` writes an mp3 under `.tmp/grunt/speak/` (or `--out`) and prints the path. `--play` is local `afplay` (mac) or `ffplay`.
+
+## Auth
+
+Handheld (any OS): `node scripts/setup.mjs speak` or `npm exec grunt setup` → speak. Opens the key page, hides the paste, writes `~/.grunt/speak.json`, verifies. Non-TTY: `--elevenlabs-key` / `--openai-key`.
+
+If a key is missing or rejected, the CLI prints `setup: node scripts/setup.mjs speak` and exits 1. Agents should show that line, not a stack or JSON. Do not invent a key.
+
+One key is enough. Never commit it.
+
+| | env | file |
+| --- | --- | --- |
+| ElevenLabs | `ELEVENLABS_API_KEY` | `elevenlabs.apiKey` |
+| OpenAI | `OPENAI_API_KEY` | `openai.apiKey` |
+| Force provider | `SPEAK_PROVIDER` | `provider` |
+
+`~/.grunt/speak.json` (chmod 600):
+
+```json
+{
+  "provider": "elevenlabs",
+  "elevenlabs": {
+    "apiKey": "sk_…",
+    "voiceId": "JBFqnCBsd6RMkjVDRZzb",
+    "modelId": "eleven_multilingual_v2"
+  },
+  "openai": {
+    "apiKey": "sk-…",
+    "voice": "coral",
+    "model": "gpt-4o-mini-tts"
+  }
+}
+```
+
+Env wins over the file. Default provider is `SPEAK_PROVIDER` else the first configured key (elevenlabs, then openai).
+
+## Defaults
+
+- ElevenLabs voice: George `JBFqnCBsd6RMkjVDRZzb`. Model: `eleven_multilingual_v2`.
+- OpenAI voice: `coral`. Model: `gpt-4o-mini-tts`.
+- Format: mp3.
+
+Create an ElevenLabs key at https://elevenlabs.io/app/settings/api-keys. OpenAI at https://platform.openai.com/api-keys.
+
+Doctor reports speak as optional: `ok` when a key or `~/.grunt/speak.json` exists, else `missing (optional)`. It prints the provider name, not the secret.

package/.rulesync/rules/CLAUDE.md

@@ -2,53 +2,7 @@
 root: true
 targets:
   - claudecode
+globs:
+  - "**/*"
 ---
-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 (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 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; 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). 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; 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 / pick1 / pick2 / `/implement-plan {n}`.
-False+: I think terraform plan /implement-plan /solo source tokens one-cmd how- last-log why.
-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 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; 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.
+@AGENTS.md

package/.rulesync/rules/overview.md

@@ -8,52 +8,14 @@ targets:
 globs:
   - "**/*"
 ---
-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 (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:
+You are the session agent. Do the work. Use en-US unless asked. Write concise complete sentences with natural grammar. Skip filler and fluff. Ship optimal solutions only; rewrite if not. Flag blockers. Do not monkey-patch. Keep all work free of AI attribution, Co-Authored-By, trailers, and generated markers.
 
-| 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 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; 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). 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; 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 |
+Size first. Straight shot: do it. Else read `.rulesync/reference/scope.md`.
+Default `/auto`: keep going; ask on blockers. `/ask`: one step, then ask.
 
-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 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 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; 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.
+Read `.rulesync/reference/INDEX.md` once. When a row matches the work, read that reference in full.
+
+Large dumps are compressed (search, test logs, snaps). Scratch and dumps live in `.tmp/grunt/` (gitignored). After a write, recap the path; edit with an offset slice when you need lines.
+Fat dumps: `node scripts/grunt-job.mjs --job search|exec|slice|fetch|test` first; spawn grunt only when the dump needs judgment.
+
+Browse with `node scripts/browser.mjs`. Lightpanda first; the rail swaps to Chromium when Lightpanda is blocked, empty, or client-rendered. Do not stop and say you cannot. App e2e is `playwright test`.