@lovrozagar/grunt 0.1.0 → 0.3.0

package/.grok/agents/thinker.md

@@ -1,25 +1,20 @@
 ---
 name: thinker
-description: 'High-tier reasoning agent. Hard design, multi-file debug, architectural decisions. Returns need: for fat dumps to parent.'
+description: Plan/deep reason. Edge cases/pitfalls. Read-only. Never spawn. No bash.
 model: grok-4.6
 agents_md: false
 mcpInheritance: none
-permission_mode: plan
+permission_mode: bypassPermissions
 tools: read_file, grep, list_dir
 ---
-You are **thinker**: high-tier reasoning agent. Read-only. Never spawn. No bash.
+Voice: `.rulesync/reference/output.md` — must follow.
 
-en-US unless asked. EVERY turn/reply — chat, trivia, meta, protocol: maximal superterse. Fragments OK. Sacrifice grammar; keep meaning. No complete-sentence padding. No host/blog communication style.
-Keep need:/verdict:/plan grammar. Only `/explain` escapes.
+Plan the solution. Deep reason. Never spawn. Never implement (implementer agent). Never run for simple tool usage (grunt agent).
+Read-only. No bash. Tiny Read/Grep/list_dir only if needed to plan. 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.
 
-**Hard problems**: architectural design, multi-file debug, tricky refactoring, cross-system decisions. Return `need:` if fat dump required.
-
-Tiny Read/Grep/list_dir in-child. `need:` is fat-only (denylist file>200KB unbounded grep/read bash dumps git web tests). See cascade.
-
-Dump stop JSON only:
+Fat dump → stop on this JSON only (≤4/batch; no serial known-parallel):
 
 ```
 need: [{"job":"search","query":"..."}]
 ```
-
-One stop may list multiple jobs; do not emit N sequential single-job stops for known-parallel dumps.

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

@@ -1,9 +1,8 @@
 #!/usr/bin/env node
-/** Parent-orchestrator gate: allow spawn/read/todo; deny write/edit/bash/web/MCP.
-Fat Read/Grep/Glob limits + path denylist via gate-fat-tools (one updatedInput).
-Parent bash: only node scripts/grunt-job.mjs --job search|exec [--path --glob --cwd].
+/** Parent-orchestrator gate: spawn/peek/kill/todo + persistPlan/persistHandoff writes.
+Parent Read/Grep/Glob/Bash/Web denied unless parent-escape (fat-gate still).
 SubagentStop intercepts need: search|exec with grunt-job verdicts.
-Stop: recap [agent]: / parent-escape stamp; do not waive impl on tools-used.
+Stop: [agent]:/[handoff]: recap | parent-escape once; else block. MAX_STOP=3. No isCheap/trivia.
 Fail-open: parse/crash → empty stdout, exit 0. Explicit JSON only when denying.
 */
 import fs from "node:fs";
@@ -19,35 +18,54 @@ import {
   subagentTypeOf,
 } from "../../scripts/gate-fat-tools.mjs";
 import { persistPlan } from "../../scripts/persist-plan.mjs";
+import { persistHandoff } from "../../scripts/persist-handoff.mjs";
 import { parseNeed } from "../../scripts/parse-need.mjs";
 import { resolveJobCwd, runJob } from "../../scripts/grunt-job.mjs";
 import { logTelemetry, ORCHESTRATOR_LOGS_DIR } from "../../scripts/telemetry.mjs";
 
 const DENY_REASON = "parent is orchestrator; spawn grunt|implementer|thinker";
-const STOP_REASON =
-  "parent is orchestrator; spawn grunt|implementer|thinker; do not complete in-parent";
-const ALLOWED_TOOLS = new Set([
-  "spawnsubagent",
-  "task",
+const STOP_REASONS = [
+  "Violation: parent replied without a [agent]: recap or /parent escape.\n" +
+    "DO NOT stop. Continue IN THIS RESPONSE:\n" +
+    "1. Spawn grunt|implementer|thinker for the pending work.\n" +
+    "2. Reply with the `[agent]:` recap only.\n" +
+    "If every spawned child already returned and the turn is done, reply with the `[agent]:` recap now.\n" +
+    "If context is long, use /handoff.",
+  "Second violation: still no [agent]: recap.\n" +
+    "DO NOT stop. Right now, in this same response:\n" +
+    "1. Spawn grunt|implementer|thinker.\n" +
+    "2. Then reply with only the `[agent]:` recap line.\n" +
+    "Already done and every child returned? Send the `[agent]:` recap immediately.\n" +
+    "Context too long? Use /handoff.",
+  "Third violation: recap still missing.\n" +
+    "This is the last check before fail-open. DO NOT stop:\n" +
+    "1. Spawn the correct agent for the remaining work.\n" +
+    "2. Reply with `[agent]:` recap only, nothing else.\n" +
+    "Complete with all children returned? Send the recap now.\n" +
+    "Long context? Use /handoff.",
+];
+const PARENT_TOOLS = new Set([
   "todowrite",
   "getcommandorsubagentoutput",
   "gettaskoutput",
   "killcommandorsubagent",
   "killtask",
-  "readfile",
-  "read",
-  "grep",
-  "grepsearch",
-  "listdir",
-  "glob",
 ]);
-const SPAWN_TOOLS = new Set(["spawnsubagent", "task"]);
+const SPAWN_TOOLS = new Set([
+  "spawnsubagent",
+  "task",
+  "agent",
+  "spawnagent",
+]);
 const WRITE_TOOLS = new Set(["write"]);
-const BASH_TOOLS = new Set(["bash", "runterminalcommand"]);
 const READ_TOOLS = new Set(["readfile", "read"]);
 const INTERCEPT_JOBS = new Set(["search", "exec"]);
 const MAX_STOP = 3;
 const MAX_INTERCEPT = 3;
+/** `/solo` enters single-agent mode; `/cascade` restores the orchestrator. */
+const SOLO_RE = /^\s*\/solo\s*$/;
+const CASCADE_RE = /^\s*\/cascade\s*$/;
+const SOLO_STAMP = "grunt-off";
 
 
 function main() {
@@ -81,6 +99,13 @@ function preToolUse(data) {
     const code = emitFat(data);
     return code == null ? 0 : code;
   }
+  if (isSoloMode(data)) {
+    // Single-agent session: no parent-deny, no spawn rewrite. Fat gate still applies.
+    const fatCode = emitFat(data);
+    if (fatCode !== null) return fatCode;
+    emit({ decision: "allow" });
+    return 0;
+  }
   if (SPAWN_TOOLS.has(toolKey)) {
     const updated = rewriteSpawn(toolInput);
     if (updated) {
@@ -98,10 +123,11 @@ function preToolUse(data) {
   if (WRITE_TOOLS.has(toolKey)) {
     return parentWrite(data, toolInput);
   }
-  if (BASH_TOOLS.has(toolKey)) {
-    return parentBash(data, toolInput);
+  if (PARENT_TOOLS.has(toolKey)) {
+    emit({ decision: "allow" });
+    return 0;
   }
-  if (ALLOWED_TOOLS.has(toolKey)) {
+  if (hasParentEscape(data)) {
     const fatCode = emitFat(data);
     if (fatCode !== null) return fatCode;
     emit({ decision: "allow" });
@@ -111,6 +137,21 @@ function preToolUse(data) {
   return 0;
 }
 
+/** Session flag, not one-turn. Fail-closed: an unreadable stamp keeps grunt on. */
+export function isSoloMode(data) {
+  try {
+    const p = soloStampPath(data);
+    return Boolean(p && fs.existsSync(p));
+  } catch {
+    return false;
+  }
+}
+
+function hasParentEscape(data) {
+  const p = stampPath(data, "parent-escape");
+  return Boolean(p && fs.existsSync(p));
+}
+
 function logPreTool(data, toolKey, toolInput) {
   const fields = {};
   if (SPAWN_TOOLS.has(toolKey) && toolInput && typeof toolInput === "object") {
@@ -145,37 +186,34 @@ function emitFat(data) {
 function workspaceRootOf(data) {
   return (
     process.env.GROK_WORKSPACE_ROOT ||
-    (data && (data.workspaceRoot || data.workspace_root || data.cwd)) ||
+    (data && (data.workspaceRoot || data.workspace_root)) ||
+    (data && data.cwd) ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.cwd() ||
     ""
   );
 }
 
-export function isUnderPlans(filePath, workspaceRoot) {
+function isUnderDir(filePath, workspaceRoot, segments) {
   if (!filePath || !workspaceRoot) return false;
   const abs = path.isAbsolute(filePath)
     ? path.resolve(filePath)
     : path.resolve(workspaceRoot, filePath);
-  const plans = path.resolve(workspaceRoot, ".tmp", "plans");
-  const rel = path.relative(plans, abs);
+  const dir = path.resolve(workspaceRoot, ...segments);
+  const rel = path.relative(dir, abs);
   return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
 }
 
-export function isAllowedParentGruntJob(command, workspaceRoot) {
-  return isWorkspaceGruntJob(command, workspaceRoot, ["search", "exec"]);
+export function isUnderPlans(filePath, workspaceRoot) {
+  return isUnderDir(filePath, workspaceRoot, [".tmp", "plans"]);
 }
 
-function parentBash(data, toolInput) {
-  if (!toolInput || typeof toolInput !== "object" || Array.isArray(toolInput)) {
-    emit({ decision: "deny", reason: DENY_REASON });
-    return 0;
-  }
-  const cmd = typeof toolInput.command === "string" ? toolInput.command : "";
-  if (!isAllowedParentGruntJob(cmd, workspaceRootOf(data))) {
-    emit({ decision: "deny", reason: DENY_REASON });
-    return 0;
-  }
-  emit({ decision: "allow" });
-  return 0;
+export function isUnderHandoffs(filePath, workspaceRoot) {
+  return isUnderDir(filePath, workspaceRoot, [".tmp", "grunt", "handoffs"]);
+}
+
+export function isAllowedParentGruntJob(command, workspaceRoot) {
+  return isWorkspaceGruntJob(command, workspaceRoot, ["search", "exec"]);
 }
 
 function parentWrite(data, toolInput) {
@@ -190,16 +228,18 @@ function parentWrite(data, toolInput) {
     toolInput.path ||
     toolInput.target_file ||
     "";
-  if (!isUnderPlans(rawPath, ws)) {
+  const handoff = isUnderHandoffs(rawPath, ws);
+  if (!handoff && !isUnderPlans(rawPath, ws)) {
     emit({ decision: "deny", reason: DENY_REASON });
     return 0;
   }
   const content = typeof toolInput.content === "string" ? toolInput.content : "";
-  const result = persistPlan({ workspaceRoot: ws, content });
+  const persist = handoff ? persistHandoff : persistPlan;
+  const result = persist({ workspaceRoot: ws, content });
   if (!result.ok) {
     emit({
       decision: "deny",
-      reason: result.error || "invalid plan",
+      reason: result.error || (handoff ? "invalid handoff" : "invalid plan"),
     });
     return 0;
   }
@@ -242,7 +282,18 @@ function isParentEscapePrompt(prompt) {
 function userPromptSubmit(data) {
   unlinkQuiet(stampPath(data, "tools-used"));
   unlinkQuiet(stampPath(data, "stop-block"));
-  if (isParentEscapePrompt(userPromptOf(data))) {
+  const prompt = userPromptOf(data);
+  // Sticky: only /solo and /cascade move it. Every other prompt leaves it alone.
+  if (SOLO_RE.test(prompt)) {
+    const solo = soloStampPath(data);
+    if (solo) {
+      fs.mkdirSync(path.dirname(solo), { recursive: true });
+      fs.writeFileSync(solo, "1");
+    }
+  } else if (CASCADE_RE.test(prompt)) {
+    unlinkQuiet(soloStampPath(data));
+  }
+  if (isParentEscapePrompt(prompt)) {
     const p = stampPath(data, "parent-escape");
     if (p) {
       fs.mkdirSync(path.dirname(p), { recursive: true });
@@ -255,16 +306,29 @@ function userPromptSubmit(data) {
 }
 
 function isChildRecap(msg) {
-  return /^\s*\[(?:grunt|implementer|thinker)\]:/.test(String(msg || ""));
+  const lines = String(msg || "").split("\n");
+  let firstNonEmpty = "";
+  for (const line of lines) {
+    if (line.trim() !== "") {
+      firstNonEmpty = line;
+      break;
+    }
+  }
+  const stripped = firstNonEmpty.replace(/^[\s`*_>]+/, "");
+  return /^\[(?:grunt|implementer|thinker|handoff)\]:/.test(stripped);
 }
 
 function stop(data) {
   if (data.subagentType || data.subagent_type) {
     return interceptNeed(data, "Stop");
   }
+  if (data.stopHookActive || data.stop_hook_active) return 0;
   const reason = String(data.reason || "");
   if (reason && reason !== "end_turn") return 0;
 
+  // Before the parent-escape consume: solo must never burn the one-turn stamp.
+  if (isSoloMode(data)) return 0;
+
   const escapeStamp = stampPath(data, "parent-escape");
   if (escapeStamp && fs.existsSync(escapeStamp)) {
     unlinkQuiet(escapeStamp);
@@ -272,8 +336,7 @@ function stop(data) {
   }
 
   const msg = data.lastAssistantMessage || data.last_assistant_message || "";
-  if (isCheap(msg) || isChildRecap(msg)) return 0;
-  if (!looksLikeImplementation(msg)) return 0;
+  if (isChildRecap(msg)) return 0;
 
   const stopStamp = stampPath(data, "stop-block");
   let n = 0;
@@ -286,7 +349,8 @@ function stop(data) {
     fs.mkdirSync(path.dirname(stopStamp), { recursive: true });
     fs.writeFileSync(stopStamp, String(n + 1));
   }
-  emit({ decision: "block", reason: STOP_REASON });
+  const reasonText = STOP_REASONS[Math.min(n, STOP_REASONS.length - 1)];
+  emit({ decision: "block", reason: reasonText });
   return 0;
 }
 
@@ -382,7 +446,6 @@ function interceptNeed(data, hookEventName) {
   );
   emit({
     decision: "block",
-    reason,
     hookSpecificOutput: {
       hookEventName,
       additionalContext: reason,
@@ -391,37 +454,27 @@ function interceptNeed(data, hookEventName) {
   return 0;
 }
 
-function looksLikeImplementation(msg) {
-  if (typeof msg !== "string") return false;
-  const t = msg;
-  if (t.includes("```")) return true;
-  if (/(?:^|\n)(?:diff --git |--- [^\n]+\n\+\+\+ |@@ )/.test(t)) return true;
-  if (/\b(?:write|create|edit)[-_ ]file\b/i.test(t)) return true;
-  const patchLines = t.split(/\n/).filter((l) => /^[+-](?![+-])/.test(l)).length;
-  if (patchLines >= 8) return true;
-  return false;
+function stampPath(data, prefix) {
+  const root = workspaceRootOf(data);
+  const sid = sessionIdOf(data) || "default";
+  if (!root) return null;
+  return path.join(root, ORCHESTRATOR_LOGS_DIR, prefix + "-" + sid);
 }
 
-function isCheap(msg) {
-  if (typeof msg !== "string") return false;
-  const t = msg.trim();
-  if (!t || t.length > 500) return false;
-  if (t.includes("```")) return false;
-  const sentences = t.split(/(?<=[.!?])(?:\s+|$)/).filter((s) => s.trim());
-  if (sentences.length > 2) return false;
-  const lines = t.split(/\n/).filter((l) => l.trim());
-  return lines.length <= 4;
+function sessionIdOf(data) {
+  return String(
+    process.env.GROK_SESSION_ID ||
+      (data && (data.sessionId || data.session_id)) ||
+      "",
+  );
 }
 
-function stampPath(data, prefix) {
-  const root =
-    process.env.GROK_WORKSPACE_ROOT ||
-    (data && (data.workspaceRoot || data.workspace_root)) ||
-    "";
-  const sid =
-    process.env.GROK_SESSION_ID || (data && (data.sessionId || data.session_id)) || "";
+/** Solo is a mode: never share a `default` stamp across sid-less sessions. */
+function soloStampPath(data) {
+  const root = workspaceRootOf(data);
+  const sid = sessionIdOf(data);
   if (!root || !sid) return null;
-  return path.join(root, ORCHESTRATOR_LOGS_DIR, prefix + "-" + sid);
+  return path.join(root, ORCHESTRATOR_LOGS_DIR, SOLO_STAMP + "-" + sid);
 }
 
 function unlinkQuiet(p) {

package/.grok/roles/thinker.toml

@@ -1,5 +1,5 @@
 description = "Deep reasoner role"
-default_capability_mode = "read-only"
+default_capability_mode = "all"
 reasoning_effort = "high"
 model = "grok-4.6"
 default_fork_context = false

package/.grok/skills/commit/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: commit
+description: >
+  Inspect the diff and commit with a Conventional Commits subject line. Use for
+  /commit, "commit this", "commit these changes". Never pushes.
+---
+Inspect `git status` + `git diff` (staged and unstaged) before the message. Never push.
+
+Stage only user intent. Never blind `git add -A` / `git add .`. Split unrelated concerns into multiple commits.
+
+Message = Conventional Commits **subject only**: `type(scope): subject` (scope optional).
+
+Types: feat fix docs style refactor perf test build ci chore revert.
+
+Subject: imperative lowercase no trailing period.
+
+NO body. NO footer. NO `Co-Authored-By`. NO `Generated with`. NO 🤖. NO trailers. No AI attribution. Work belongs to the human.
+
+Never `git push`.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

package/.grok/skills/commit-and-push/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: commit-and-push
+description: >
+  Commit like /commit, then push to the current branch's upstream. Use for
+  /commit-and-push, "commit and push", "commit this and push".
+---
+Run commit skill rules first (`.rulesync/skills/commit/SKILL.md`). Then push.
+
+If on default branch, create/switch to a feature branch first — never push default directly.
+
+Push upstream; if no upstream `git push -u origin <current-branch>`.
+
+Never force-push.
+
+Protocol: `.rulesync/reference/cascade.md`. Do not paste cascade.

package/.grok/skills/handoff/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: handoff
+description: >
+  Parent writes a session handoff under .tmp/grunt/handoffs/ and tells the user
+  to continue in a fresh session. Use for /handoff, "context is getting long",
+  "hand this off", "start a new session". Not a plan, not a design doc.
+---
+# handoff
+
+One turn, in-parent. Parent authors from its own transcript — no child sees this session, so **do not spawn**. Write once, report path, stop.
+
+## Invocation
+
+`/handoff [focus]`
+
+Focus narrows what the handoff carries. Empty → whole session.
+
+## When
+
+Context large + work unfinished → write handoff, then advise a new session. Also on host/tool churn, or before a long unrelated detour.
+
+Nothing done yet (no edits, no findings) → `nothing to hand off` and stop. Do not write an empty file.
+
+## Path
+
+`.tmp/grunt/handoffs/{serial}-{slug}-{YYYYMMDDTHHMMSSZ}.md`
+
+- serial: unpadded int ≥ 1, next after existing handoffs (own counter; not plan serials)
+- slug: lower, non `[a-z0-9]` → `-`, collapse, trim 50
+- stamp: `created` with `-` and `:` dropped (`20260827T143000Z`)
+
+## Format
+
+```yaml
+---
+serial: 1
+name: <slug>
+status: open        # open | resumed | done
+created: 2026-08-27T14:30:00Z   # UTC, seconds, no ms
+source: "<≤120 chars of the session task>"
+---
+```
+
+Headings, this order only: `# {slug}`, `## Goal`, `## State`, `## Context`, `## Next`, `## Watch-outs`.
+
+| Section | Amount |
+|---|---|
+| Goal | 1–3 sentences. What the session is trying to land. |
+| State | bullets. Done / changed / green-red, with absolute paths. |
+| Context | bullets. Abs paths, decisions, verdict facts the next session needs. |
+| Next | checkbox steps, `N [ ]` phase + `N.M [ ]` leaf, all `[ ]` fresh |
+| Watch-outs | bullets. Footguns. `(none)` allowed. |
+
+Boxes: `^{id} [ ] {text}$`, id `N` / `N.M` / `N.M.K`. Not `- [ ]`, not `1. [ ]`. Every phase has ≥1 leaf. Fresh handoff has zero `[x]`.
+
+Facts only. Absolute paths. No transcript paste, no dump, no secrets/tokens.
+
+## Write
+
+Line 1 of the body: `HANDOFF_NAME: <3-6 word name>`, then the body only.
+
+Parent `write`s under `.tmp/grunt/handoffs/` (any filename in that dir). Grok `orchestrate-parent.js` runs `scripts/persist-handoff.mjs`: serial/slug from `HANDOFF_NAME:` / heading, injects frontmatter, rewrites path + content. Invalid handoff or a write outside that dir is denied — fix the body, do not retry elsewhere.
+
+Host without that hook: name the file per **Path** yourself, or pipe the body to `node scripts/persist-handoff.mjs --workspace {repo}` and use its `path`.
+
+## Report
+
+```
+[handoff]: serial={int} path=.tmp/grunt/handoffs/{serial}-{slug}-{stamp}.md
+next: start a new session; first action = read that path
+```
+
+Do not dump the handoff body.
+
+## Picking one up
+
+New session, `/handoff` not needed: read the newest `.tmp/grunt/handoffs/*.md` (or the given serial), set `status: resumed`, work `Next` leaves in order, flip only the box. All `[x]` → `status: done`. Do not re-plan; a stale leaf → `/write-plan` a follow-up.
+
+## Rules
+
+- No spawn. One write. `/handoff` is not a mode.
+- Handoff ≠ plan: no Steps/Verify phases, no `.tmp/plans/` write.
+- Never rewrite or renumber an existing handoff; new session = new serial.
+- Protocol: `.rulesync/reference/cascade.md`. Do not paste it here.

package/.grok/skills/solo/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: solo
+description: >
+  Session mode. /solo disables the grunt cascade for this session — one normal
+  agent, no spawn, no orchestrator. /cascade restores it. Unlike /parent and
+  /explain this IS a mode: it persists until /cascade or session end.
+---
+Session mode, not one-turn. Persists until `/cascade` or session end.
+
+This session: cascade suspended. You are one normal agent.
+
+- Do not spawn. No grunt|implementer|thinker.
+- No `[agent]:` recap. Answer the user directly.
+- No spawn-first rule. No `need:`/`verdict:` grammar.
+- Voice unchanged: `.rulesync/reference/output.md`. `/explain` is still the voice escape.
+
+Fat-tool caps stay on — token guards, not cascade.
+
+Claude/Codex/Grok: `/solo` via submit hook writes `.tmp/orchestrator-logs/grunt-off-{sid}`; `/cascade` unlinks it and the next turn is orchestrated again. Agents/Antigravity: instruction-only (this skill body); cannot create stamp via `/solo`; Stop still honors a pre-existing stamp if present. Session-scoped, never global.
+
+For advisory/design turns, debugging the cascade itself, or back-and-forth where spawning costs more than it saves.

package/.rulesync/hooks.jsonc

@@ -17,6 +17,29 @@
         "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/scripts/gate-fat-tools.mjs\"",
         "timeout": 5
       }
+    ],
+    // Parent Stop + /parent stamp. PreToolUse parent-deny stays Grok-only
+    // (child subagentType/agent_type unverified on these hosts).
+    "beforeSubmitPrompt": [
+      {
+        "type": "command",
+        "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+        "timeout": 5
+      }
+    ],
+    "stop": [
+      {
+        "type": "command",
+        "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+        "timeout": 30
+      }
+    ],
+    "subagentStop": [
+      {
+        "type": "command",
+        "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
+        "timeout": 30
+      }
     ]
   }
 }

package/.rulesync/reference/cascade.md

@@ -8,37 +8,31 @@ Shipped protocol: **parent-only spawn**. Only the parent **orchestrator** sessio
 
 ## Parent orchestrator
 
-1. Super-trivial / yes-no / definition-from-prompt with zero tools **and absolutely sure** → parent answers; no grunt/child. Parent does not web_search. `2+2` → answer.
-2. Not absolutely sure / fresh or world facts → spawn grunt `job: web`. Do not answer from memory.
-3. Cheap reply already in context: answer. No tools.
-4. Tiny lookup (one file, ≤10-hit grep, list_dir): do it here. No bash. Do not spawn. Limits auto-injected; denylist / file>200KB / head_limit>500 → spawn grunt.
-5. Fat dump: `spawn_subagent` type=grunt with `job: search|exec|web|test`. Isolated window. Expect `verdict:`.
-6. Low-reason write (mechanical/repetitive/obvious; volume OK): spawn grunt. Mid reason / feature judgment: spawn implementer. Design / architecture / hard debug: spawn thinker.
-7. Unsure → implementer.
+Always spawn + prompt. First token = spawn. No try-then-spawn. No parent probe. No tiny-read/grep/list_dir/bash/grunt-job for the user. No skip-spawn. `/parent` is the only parent-tool escape.
+
+1. Tools (facts / search / exec / git / web / test / low-reason mechanical write) → grunt.
+2. Write defined solution → implementer.
+3. Plan / deep reason (edge cases / pitfalls) → thinker.
+4. Fresh/world facts → grunt `job: web`. Never answer from memory.
 
 Spawn only `grunt` | `implementer` | `thinker`. Omit `model`. Isolation `none` unless asked.
 
-Implementer/thinker may tiny-Read/Grep/list_dir themselves. `need:` is fat-only (denylist file>200KB unbounded grep/read bash dumps git web tests).
+Implementer/thinker may tiny-Read/Grep/list_dir themselves. Fat dumps via `need:` JSON.
 
 Long parent sessions rely on two-pass compaction; prefer a new parent session per task rather than unbounded resume chains. `[features] two_pass_compaction = true` must live in `~/.grok/config.toml` (from `.grok/global-settings.toml` via `npm run sync:globals` dry-run / `npm run sync:globals:apply`). Project `.grok/config.toml` cannot set `[features]`. Do not add a SessionStart hook.
 
-## Pre-spawn
-
-If dumps are known (paths, rg, test cmd): parent and implementer run `node scripts/grunt-job.mjs --job search|exec --query …` in-session and pass those `verdict:` blobs into the child prompt. Optional `--path` `--glob` (repeatable) `--cwd`. `--query` is one argv; regex `|` OK. Never `cd &&`. Unknown flags or exec shell-meta in query → FALLBACK (exit 2). Do not start the child and `need:` for a dump already known. Thinker stays read-only (no bash): fat search|exec via `need:` + SubagentStop intercept.
-
-For spawned grunt `job: search|exec`, first action is still `node scripts/grunt-job.mjs --job search|exec --query …` and echo stdout as the whole reply. Bounded `job: test` may try the same script (`--job test`); `job: web` and messy `job: test` stay LLM grunt. If the script prints `FALLBACK` (exit 2), LLM grunt may use tools.
-
 ## Wait / peek
 
 Parent-only. Non-blocking spawn so each child has a host id immediately. Per-child, not one global timer.
-Every ≤60s peek is real host status (no `sleep` then guess). First return ≤60s is the peek (earlier if the child finishes).
+Every 60s peek is real host status (no `sleep` then guess). `timeout_ms=60000` every peek.
 Quote host fields only (`status`, elapsed since spawn, last activity/output snippet) or quote the error. Never invent.
 Classify `done` | `alive` | `stuck` vs prior peek: **done** (completed/failed), **alive** (running + fields/output changed), **stuck** (running + unchanged). Unchanged snippet = stuck, not “still working”.
 Loop until done. No auto-kill. Kill only if the user asks and the host has a kill tool.
 Then print recap as `[agent]: …` with real child output. Do not redo the child's work.
 
-Parent Stop (`MAX_STOP=3`): do not waive fenced/impl finals for `tools-used` stamp. Allow cheap trivia, `[grunt|implementer|thinker]:` recap prefix, or consume `parent-escape-{sid}` once. Else block.
-`/parent` is one-turn (not a mode): UserPromptSubmit writes `.tmp/orchestrator-logs/parent-escape-{sid}`; Stop consumes+unlinks once. Next Stop resumes spawn/cheap/recap rules. Skills point here; do not paste this file.
+Parent Stop (`MAX_STOP=3`): do not waive fenced/impl finals for `tools-used` stamp. Allow only `[grunt|implementer|thinker|handoff]:` recap prefix, or consume `parent-escape-{sid}` once. Else block. No `isCheap` / trivia / long definitions.
+`/handoff` is the other in-parent turn: context large + work unfinished → parent writes one `.tmp/grunt/handoffs/` file from its own transcript (no child sees the session), recaps `[handoff]: serial=… path=…`, tells the user to continue in a new session. No spawn, one write, not a mode.
+`/solo` is the session mode (not one-turn): `beforeSubmitPrompt` writes `.tmp/orchestrator-logs/grunt-off-{sid}`, every gate short-circuits while it exists, `/cascade` unlinks it. Everything above resumes next turn. Antigravity: skill-only, no stamp create (see hooks.md). `/parent` is one-turn (not a mode): UserPromptSubmit writes `.tmp/orchestrator-logs/parent-escape-{sid}`; Stop consumes+unlinks once. Next Stop resumes spawn/recap rules. Skills point here; do not paste this file.
 
 Host mapping (in-tree only; do not invent peek/kill APIs). GAP rows: no fake peeks, no auto-kill.
 
@@ -66,7 +60,7 @@ Parent: parse with `scripts/parse-need.mjs` (same grammar). If parse succeeds, f
 
 Resume prompt = `You are {agent} subagent.` plus the new verdicts. Do not re-send the original task, cascade, or prior verdicts (`resume_from` already has the transcript).
 
-Superterse does not change need:/verdict:/plan grammar.
+Voice: [output](output.md). Does not change need:/verdict:/plan grammar.
 
 ## Isolation grunt `verdict:`
 
@@ -78,7 +72,7 @@ n: <count>
 
 Fail: first 3 error lines. ≤8 lines. No dumps, recap, HTML, JSON, full logs.
 
-Implementer/thinker: fat dumps via `need:` JSON. Implementer shell via rtk; cat/rg/curl/tests without rtk → fat `need:`. For search|exec that already fits 8-line `verdict:`, implementer runs `node scripts/grunt-job.mjs` in-session instead of `need:` (`--path`/`--glob`/`--cwd` OK; never `cd &&`).
+Implementer/thinker: fat dumps via `need:` JSON. Implementer shell via rtk; cat/rg/curl/tests without rtk → fat `need:`.
 
 Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.
 

package/.rulesync/reference/hooks.md

@@ -12,7 +12,11 @@ Claude / Codex / Antigravity PreToolUse still run `scripts/scrub-spawn-prompt.mj
 
 Parent `run_terminal_command` is deny-by-default except `node` (optional leading `rtk`) invoking `{workspace}/scripts/grunt-job.mjs` with `--job search|exec` and `--query`. Optional `--path` `--glob` (repeatable) `--cwd`. Not `web|test`, not other scripts. META strips `--query` value first so `|` inside query is allowed; pipes/`&&` outside query still deny. Never `cd &&`. Exec shell-meta in query is grunt-job FALLBACK (exit 2), not a parent-bash allow. Unknown flags → FALLBACK.
 
-SubagentStop (and child Stop with `subagentType`) intercepts a parseable `need:` whose jobs are all `search|exec` (cap 4): runs grunt-job in-hook and continues the child with concatenated `verdict:` blobs. Mixed/web/test, parse fail, FALLBACK, `stopHookActive`, or more than 3 intercepts per child session → empty stdout (allow stop; parent LLM path). Parent Stop (`MAX_STOP=3`): do not waive impl finals for `tools-used`. Allow cheap, `[grunt|implementer|thinker]:` recap prefix, or consume `parent-escape-{sid}` once (`/parent`). Stamps: `tools-used` / `stop-block` / `need-intercept` / `parent-escape`. Skills point to cascade; do not paste protocol here.
+SubagentStop (and child Stop with `subagentType`) intercepts a parseable `need:` whose jobs are all `search|exec` (cap 4): runs grunt-job in-hook and continues the child with concatenated `verdict:` blobs. Mixed/web/test, parse fail, FALLBACK, `stopHookActive`, or more than 3 intercepts per child session → empty stdout (allow stop; parent LLM path). Parent `write` is deny-by-default except `.tmp/plans/` (`persist-plan.mjs`) and `.tmp/grunt/handoffs/` (`persist-handoff.mjs`); both validate + rewrite path/content, invalid body denies. Parent Stop (`MAX_STOP=3`): do not waive impl finals for `tools-used`. Allow only `[grunt|implementer|thinker|handoff]:` recap prefix, or consume `parent-escape-{sid}` once (`/parent`). No `isCheap` / trivia. Stamps: `tools-used` / `stop-block` / `need-intercept` / `parent-escape`. Skills point to cascade; do not paste protocol here.
+
+`/solo` writes `grunt-off-{sid}`; `/cascade` unlinks it (`beforeSubmitPrompt`, exact-match only). While set: PreToolUse allows parent tools (fat gate still runs) and skips the `defaultGrunt` spawn rewrite; Stop returns 0 **before** the `parent-escape` consume, so solo never burns the one-turn stamp. Session-scoped, fail-closed.
+
+rulesync canonical event is `beforeSubmitPrompt` (→ Claude/Codex `UserPromptSubmit`), not `userPromptSubmit` — an unknown key makes Zod reject the whole `.rulesync/hooks.jsonc`, emitting nothing while `--check` still reports up to date. Antigravity supports neither `beforeSubmitPrompt` nor `subagentStop`; `/solo` degrades there to the skill body alone.
 
 Stop and SubagentStop timeout is 30s (grunt-job cap is 20s). PreToolUse / PostToolUse / UserPromptSubmit stay at 5s. If the intercept times out, the hook fail-opens and the child stops without verdicts.