@lovrozagar/grunt 0.2.0 → 0.3.0

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

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
-/** Parent-orchestrator gate: spawn/peek/kill/todo + persistPlan writes.
+/** 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: [agent]: recap | parent-escape once; else block. MAX_STOP=3. No isCheap/trivia.
+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";
@@ -18,13 +18,32 @@ 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 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",
@@ -43,6 +62,10 @@ 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() {
@@ -76,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) {
@@ -107,6 +137,16 @@ 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));
@@ -146,21 +186,32 @@ 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 isUnderPlans(filePath, workspaceRoot) {
+  return isUnderDir(filePath, workspaceRoot, [".tmp", "plans"]);
+}
+
+export function isUnderHandoffs(filePath, workspaceRoot) {
+  return isUnderDir(filePath, workspaceRoot, [".tmp", "grunt", "handoffs"]);
+}
+
 export function isAllowedParentGruntJob(command, workspaceRoot) {
   return isWorkspaceGruntJob(command, workspaceRoot, ["search", "exec"]);
 }
@@ -177,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;
   }
@@ -229,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 });
@@ -242,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,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;
 }
 
@@ -368,7 +446,6 @@ function interceptNeed(data, hookEventName) {
   );
   emit({
     decision: "block",
-    reason,
     hookSpecificOutput: {
       hookEventName,
       additionalContext: reason,
@@ -379,14 +456,27 @@ function interceptNeed(data, hookEventName) {
 
 function stampPath(data, prefix) {
   const root = workspaceRootOf(data);
-  const sid =
-    process.env.GROK_SESSION_ID ||
-    (data && (data.sessionId || data.session_id)) ||
-    "default";
+  const sid = sessionIdOf(data) || "default";
   if (!root) return null;
   return path.join(root, ORCHESTRATOR_LOGS_DIR, prefix + "-" + sid);
 }
 
+function sessionIdOf(data) {
+  return String(
+    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, SOLO_STAMP + "-" + sid);
+}
+
 function unlinkQuiet(p) {
   if (!p) return;
   try {

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

@@ -20,7 +20,7 @@
     ],
     // Parent Stop + /parent stamp. PreToolUse parent-deny stays Grok-only
     // (child subagentType/agent_type unverified on these hosts).
-    "userPromptSubmit": [
+    "beforeSubmitPrompt": [
       {
         "type": "command",
         "command": "node \"${GROK_WORKSPACE_ROOT:-${CLAUDE_PROJECT_DIR:-.}}/.grok/hooks/orchestrate-parent.js\"",
@@ -33,6 +33,13 @@
         "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

@@ -30,8 +30,9 @@ Classify `done` | `alive` | `stuck` vs prior peek: **done** (completed/failed),
 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 only `[grunt|implementer|thinker]:` recap prefix, or consume `parent-escape-{sid}` once. Else block. No `isCheap` / trivia / long definitions.
-`/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.
+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.
 

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 only `[grunt|implementer|thinker]:` 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.
+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.
 

package/.rulesync/reference/map.md

@@ -22,13 +22,14 @@ Cheap outline. Not a file dump.
 ## Grok hand files
 - `.grok/hooks/orchestrate-parent.js` + `orchestrate-parent.json` — parent spawn/fat/stop/plan-write / SubagentStop intercept
 - `.grok/hooks/rtk.json` — RTK
-- `.grok/skills/{write-plan,implement-plan,shared,parent}/` — `/parent` one-turn; point to cascade, do not paste
+- `.grok/skills/{write-plan,implement-plan,shared}/` — hand-only (no rulesync SSOT); point to cascade, do not paste
+- `.grok/skills/{parent,explain,handoff,solo,commit,commit-and-push}/` — generated from `.rulesync/skills/`; do not hand-edit
 - `.grok/parent.md` — 1-line pointer to orchestrator agent; not SessionStart
 - `.grok/roles/*.toml`
 - `.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/skills/parent/` — `/parent` skill SSOT; copy lives in `.grok/skills/parent/`
+- `.rulesync/skills/{parent,explain,handoff,solo,commit,commit-and-push}/` — skill SSOT; `rulesync -f skills` emits `.grok/skills/`, `.claude/skills/`, `.agents/skills/` byte-equal. `/cascade` has no skill (hook-only: a `grunt`-adjacent listing entry risks mis-routing `Skill` vs `Agent`)
 
 ## Scripts
 - `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`)
@@ -36,17 +37,28 @@ Cheap outline. Not a file dump.
 - `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-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`)
+- `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/telemetry.mjs` — append-only `.tmp/orchestrator-logs/telemetry.ndjson` from hooks / grunt-job CLI; fail-open; never stdout
 
+## Tmp
+- `.tmp/plans/` — persist-plan / parent / implementer
+- `.tmp/orchestrator-logs/` — hooks + grunt-job telemetry (shared; not grunt scratch)
+- `.tmp/grunt/` — grunt scratch/tmp only
+- `.tmp/grunt/handoffs/` — persist-handoff / `/handoff`; own serial counter (not plan serials)
+
 ## Stamps (`.tmp/orchestrator-logs/`)
 - `tools-used` / `stop-block` / `need-intercept` / `parent-escape` — Stop does not waive impl finals for `tools-used`; `/parent` writes `parent-escape-{sid}` once
+- `grunt-off-{sid}` — `/solo` session mode. Sticky: only `/solo` / `/cascade` move it. Requires a real sid (never the `default` fallback). Read fail-closed — an unreadable stamp keeps grunt on
 
 ## Generated (do not hand-edit; committed, not gitignored)
 - `AGENTS.md`, `CLAUDE.md`
+- `.claude/skills/*`, `.agents/skills/*`, `.grok/skills/{parent,explain,handoff,solo,commit,commit-and-push}/` (from `.rulesync/skills/`)
 - `.grok/agents/*`
 - `.claude/agents/*`
 - `.codex/agents/*`
@@ -56,3 +68,6 @@ Cheap outline. Not a file dump.
 - `.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
+- `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)

package/.rulesync/rules/CLAUDE.md

@@ -4,10 +4,11 @@ targets:
   - claudecode
 ---
 Voice: `.rulesync/reference/output.md`
+All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
 Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not open first.
 Parent = this file not `.claude/agents/orchestrator.md`. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-First token = spawn. No try-then-spawn. No parent probe. After child: `[agent]:` echo only. No skip-spawn. /parent = one-turn.
+First token = spawn. No try-then-spawn. No parent probe. After child: `[agent]:` echo only. No skip-spawn. /parent = one-turn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`, recap `[handoff]:`.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. `timeout_ms=60000` every peek. GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.

package/.rulesync/rules/overview.md

@@ -9,10 +9,11 @@ globs:
   - "**/*"
 ---
 Voice: `.rulesync/reference/output.md` once.
+All output exclude AI attribution, Co-Authored-By, trailers, generated markers.
 Protocol: `.rulesync/reference/cascade.md`. Do not paste. Do not open first.
 Parent = orchestrator. You do not talk. Spawn wait echo.
 Spawn only grunt|implementer|thinker. Never spawn orchestrator. Children never spawn.
-First token = spawn. No try-then-spawn. No parent probe. After child: `[agent]:` echo only. No skip-spawn. /parent = one-turn.
+First token = spawn. No try-then-spawn. No parent probe. After child: `[agent]:` echo only. No skip-spawn. /parent = one-turn. /handoff = one-turn in-parent write to `.tmp/grunt/handoffs/`, recap `[handoff]:`.
 grunt ← tools (facts/search/exec/git/web/test/low-reason mechanical write; world fact: `job: web` never memory). implementer ← write defined solution. thinker ← plan/deep reason.
 Child prompt = `You are {agent} subagent.` + task + abs paths + verdicts only.
 Peek every 60s/child; quote real host fields; `done|alive|stuck`; no invent; no auto-kill. `timeout_ms=60000` every peek. GAP: block on spawn return = `done`. Stuck/blocked: quote host fields only.

package/.rulesync/skills/commit/SKILL.md

@@ -0,0 +1,22 @@
+---
+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/.rulesync/skills/commit-and-push/SKILL.md

@@ -0,0 +1,16 @@
+---
+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/.rulesync/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.