@lovrozagar/grunt 0.8.1 → 0.8.3

package/.rulesync/reference/hooks.md

@@ -4,7 +4,7 @@ tags: [hooks]
 
 # Hooks
 
-SessionStart carries only the folder map: Claude / Codex run `../../scripts/session-map.mjs`, which injects the code-only map from `../../scripts/folder-map.mjs` as `additionalContext` (budget 5k tokens, cache-stable, fail-open) and logs `{rows, tokens}` to `.tmp/grunt/sessions/<sid>/map.json`. Inject nothing else at SessionStart. Antigravity has no rulesync sessionStart. Do not register a SessionStart hook on `../../.grok/hooks/orchestrate-parent.json`.
+SessionStart carries only the folder map: Claude / Codex run `../../scripts/session-map.mjs`, which injects the code-only map from `../../scripts/folder-map.mjs` as `additionalContext` (capped under Claude Code's 10,000-char per-hook `additionalContext` limit, about 2.4k tokens, below the 5k `grunt map` budget; cache-stable, fail-open) and logs `{rows, tokens}` to `.tmp/grunt/sessions/<sid>/map.json`. Inject nothing else at SessionStart. Antigravity has no rulesync sessionStart. Do not register a SessionStart hook on `../../.grok/hooks/orchestrate-parent.json`.
 
 Grok PostToolUse / SessionStart are observe-only — do not attempt output scrub; compress via RTK / spawn / isolation facts only. Do not add PostToolUse scrub hooks. Grok UserPromptSubmit may emit a one-line `sessionGate=auto|ask` plus session receipt (`hookSpecificOutput.additionalContext`). Skip host Stop banners. `/ask` exact-match slash stamps `session-gate-{sid}` to `ask`. `/auto` unlinks. Sid-less: no stamp. Default: `auto`.
 

package/.rulesync/rules/overview.md

@@ -15,7 +15,7 @@ Default `/auto`: keep going; ask on blockers. `/ask`: one step, then ask.
 Ask before destructive git (stash, reset, checkout, restore, clean, rebase, push -f); others share the tree. In a loop, skip it and edit code instead.
 
 Read `.rulesync/reference/INDEX.md` once. When a row matches the work, read that reference in full.
-Use the folder map in session context to find code. Run `node scripts/folder-map.mjs <dir>` for depth before `ls` or `find`.
+To learn the repo layout, use the folder map if it is in your context. If it is missing, or you need more depth, run `node scripts/folder-map.mjs [dir]` instead of exploring with `ls` or `find`.
 
 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.

package/AGENTS.md

@@ -6,7 +6,7 @@ Default `/auto`: keep going; ask on blockers. `/ask`: one step, then ask.
 Ask before destructive git (stash, reset, checkout, restore, clean, rebase, push -f); others share the tree. In a loop, skip it and edit code instead.
 
 Read `.rulesync/reference/INDEX.md` once. When a row matches the work, read that reference in full.
-Use the folder map in session context to find code. Run `node scripts/folder-map.mjs <dir>` for depth before `ls` or `find`.
+To learn the repo layout, use the folder map if it is in your context. If it is missing, or you need more depth, run `node scripts/folder-map.mjs [dir]` instead of exploring with `ls` or `find`.
 
 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.

package/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.3] - 2026-10-03
+
+### Changed
+
+- Root rule on the folder map now reads for every agent: use the map when it is in context, else run `node scripts/folder-map.mjs [dir]`, and only in place of `ls` / `find` for learning the repo layout
+
+## [0.8.2] - 2026-10-03
+
+### Fixed
+
+- SessionStart folder map exceeded Claude Code's 10,000-character per-hook `additionalContext` limit on large repos, so only a 2KB preview reached the model. The injected map now stays under that limit
+- Folder map depth is uniform: the deepest level (up to `depthCap`) that fits the size limit, applied to every package, instead of uneven fair-share cuts. Folders leading to a nested package always expand. The injected header names the depth used, or `complete`; the per-session `map.json` logs `depth`
+
 ## [0.8.1] - 2026-10-03
 
 ### Fixed

package/README.md

@@ -179,13 +179,13 @@ Emit writes other-CLI trees from `.rulesync` for the **next** process of that CL
 
 ### Folder map
 
-Claude and Codex get a folder map at SessionStart (`scripts/session-map.mjs`), so agents skip `ls`/`find` loops. Agents run `node scripts/folder-map.mjs <dir>` (same as `grunt map <dir>`) for depth. Grok and Antigravity get the `AGENTS.md` line only.
+Claude and Codex get a folder map at SessionStart (`scripts/session-map.mjs`), so agents skip `ls`/`find` loops. Agents run `node scripts/folder-map.mjs <dir>` (same as `grunt map <dir>`) for depth. Grok and Antigravity get the `AGENTS.md` line only. The injected map stays under Claude Code's 10,000-character per-hook `additionalContext` limit (about 2.4k tokens); past it, Claude keeps only a 2KB preview inline. `grunt map` itself uses the full `budget`.
 
 - Folders only, never files. Source: `git ls-files --cached --others --exclude-standard`, so gitignored paths never show
 - A folder shows when it or a descendant holds a code file (`codeExt`) and no path segment is a dot dir or in `skip`
 - Package roots (`package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`) show `# name  repo/relative/path`
 - Pass-through single-child chains collapse (`a/b/c/`). 12+ plain leaf dirs under one parent fold into one row
-- Budget (chars ÷ 4): breadth-first per top-level subtree; on overflow, cheapest subtrees first with an equal share; cut dirs end in `…` (the header names the command). Depth cap counts from the nearest package root
+- Depth is uniform: the map uses the deepest level (up to `depthCap`, counted from each package root) that fits the size limit, so every package shows the same number of levels. Deeper folders end in `…`; folders that lead to a nested package always expand. The size limit is `budget` × 4 chars, lowered to fit Claude Code's per-hook limit at SessionStart. The injected header names the depth used, or says `complete`
 - Size per session: `.tmp/grunt/sessions/<sid>/map.json`
 
 Optional `.rulesync/grunt.map.jsonc` (missing or invalid → defaults):

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovrozagar/grunt",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Multi-agent orchestrator SoT — deep-merge rulesync trees, product scripts, and generate pipeline into a consumer repo",
   "keywords": [
     "agents",

package/scripts/folder-map.mjs

@@ -6,6 +6,8 @@
  * shown when it or a descendant holds a code file and no segment is skipped.
  * Package roots (package.json, go.mod, Cargo.toml, pyproject.toml) carry
  * `# name  path`. Single-child chains collapse; plain leaf dirs fold at foldAt.
+ * Depth is uniform per package: the deepest level that fits the size limit;
+ * deeper folders end in `…`.
  *
  *   node scripts/folder-map.mjs [dir]
  */
@@ -197,83 +199,36 @@ export function tokens(text) {
   return Math.ceil(text.length / 4);
 }
 
+/** True when a package root sits anywhere below `row`. */
+function holdsPackage(row) {
+  return row.kids.some((k) => k.pkg != null || holdsPackage(k));
+}
+
 /**
- * Pick rows under the budget, breadth-first by display level.
- *
- * Level 0 always shows. Each deeper level is one unit per top-level subtree:
- * a subtree's rows at that level show together or not at all, so a parent's
- * kids are never half-listed. Cost is exact in chars: a row with kids is
- * charged its `…` marker until its kids land. When a level does
- * not fit, cheapest subtrees take an equal share first; a subtree that misses
- * its share stops expanding. Rows past depthCap (from the nearest package
- * root) never expand.
+ * Render rows with every package expanded to `cap` levels below its root
+ * (top-level non-package rows count from 1). A row past the cap hides its
+ * kids and ends in `…`, unless a package root sits below it: package rows
+ * always stay reachable, and their own depth restarts at 0.
  */
-function selectRows(rows, o, base) {
-  const levels = [];
-  const visit = (list, depth, top, pkgDepth) => {
-    for (const row of list) {
-      const rel = row.pkg != null ? 0 : pkgDepth;
-      row.top = top ?? row;
-      row.capped = row.kids.length > 0 && rel >= o.depthCap;
-      row.shown = false;
-      (levels[depth] ||= []).push(row);
-      if (!row.capped) visit(row.kids, depth + 1, row.top, rel + 1);
-    }
-  };
-  visit(rows, 0, null, 1);
-  const cost = (row, depth, more) => rowText(row, depth, { more, base }).length + 1;
-  const pointer = (row, depth) => cost(row, depth, true) - cost(row, depth, false);
-  const charge = (row, depth) => cost(row, depth, row.kids.length > 0);
-
-  let used = 0;
-  for (const row of levels[0] || []) {
-    row.shown = true;
-    used += charge(row, 0);
-  }
-  const limit = o.budget * 4;
-  let active = new Set(levels[0] || []);
-  for (let d = 1; d < levels.length && active.size; d++) {
-    const units = new Map();
-    for (const row of levels[d]) {
-      if (!active.has(row.top)) continue;
-      const u = units.get(row.top) || { rows: [], parents: new Set(), cost: 0 };
-      u.rows.push(row);
-      u.cost += charge(row, d);
-      units.set(row.top, u);
-    }
-    for (const row of levels[d - 1]) {
-      const u = units.get(row.top);
-      if (u && row.shown && row.kids.length && !row.capped) u.cost -= pointer(row, d - 1);
-    }
-    const next = new Set();
-    let left = limit - used;
-    const order = [...units.entries()].sort((a, b) => a[1].cost - b[1].cost);
-    order.forEach(([top, u], i) => {
-      const share = left / (order.length - i);
-      if (u.cost > share) return;
-      for (const row of u.rows) row.shown = true;
-      left -= u.cost;
-      used += u.cost;
-      next.add(top);
-    });
-    active = next;
-  }
+function renderAtDepth(rows, cap, base) {
   const lines = [];
-  const walk = (list, depth) => {
+  const walk = (list, depth, pkgDepth) => {
     for (const row of list) {
-      if (!row.shown) continue;
-      const open = row.kids.length > 0 && row.kids.some((k) => k.shown);
-      lines.push(rowText(row, depth, { more: row.kids.length > 0 && !open, base }));
-      if (open) walk(row.kids, depth + 1);
+      const rel = row.pkg != null ? 0 : pkgDepth;
+      const hidden = row.kids.length > 0 && rel >= cap && !holdsPackage(row);
+      lines.push(rowText(row, depth, { more: hidden, base }));
+      if (!hidden) walk(row.kids, depth + 1, rel + 1);
     }
   };
-  walk(rows, 0);
+  walk(rows, 0, 1);
   return lines;
 }
 
 /**
  * Map text for `root` (any dir inside a git repo), scoped to `dir` when set.
- * Returns { text, rows, tokens } or null outside git.
+ * Depth is uniform: the deepest cap (≤ depthCap) whose text fits the limit,
+ * where limit = budget × 4 chars, lowered by `opts.maxChars` (hook caps).
+ * Returns { text, rows, tokens, depth } or null outside git.
  */
 export function folderMap({ root, dir = "", ...opts } = {}) {
   const top = repoRoot(root);
@@ -282,14 +237,21 @@ export function folderMap({ root, dir = "", ...opts } = {}) {
   if (!files) return null;
   const o = { ...loadMapConfig(top), ...opts };
   const scope = dir ? repoPrefix(path.resolve(root, dir)) : "";
-  if (scope == null) return { text: "", rows: 0, tokens: 0 };
+  if (scope == null) return { text: "", rows: 0, tokens: 0, depth: 0 };
   const scoped = scope
     ? files.filter((f) => f.startsWith(`${scope}/`)).map((f) => f.slice(scope.length + 1))
     : files;
-  const tree = buildTree(scope ? path.join(top, scope) : top, scoped, o);
-  const lines = selectRows(displayRows(tree, o), o, scope);
+  const rows = displayRows(buildTree(scope ? path.join(top, scope) : top, scoped, o), o);
+  const limit = Math.min(o.budget * 4, o.maxChars ?? Infinity);
+  let lines = [];
+  let depth = o.depthCap;
+  for (; depth >= 1; depth--) {
+    lines = renderAtDepth(rows, depth, scope);
+    if (lines.join("\n").length + 1 <= limit) break;
+  }
+  depth = Math.max(depth, 1);
   const text = lines.length ? `${lines.join("\n")}\n` : "";
-  return { text, rows: lines.length, tokens: tokens(text) };
+  return { text, rows: lines.length, tokens: tokens(text), depth };
 }
 
 /** Text for `grunt map [dir]` / `node scripts/folder-map.mjs [dir]` run from `cwd`. */

package/scripts/session-map.mjs

@@ -9,8 +9,15 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { folderMap } from "./folder-map.mjs";
 
-export const HEADER =
-  "Folder map (code folders only; `…` = more inside, run `node scripts/folder-map.mjs <dir>`):";
+/** First line of the injected map; `depth` = levels per package, null when nothing was cut. */
+export function header(depth) {
+  const scope = depth == null ? "complete" : `${depth} levels per package`;
+  return `Folder map (code folders, ${scope}; \`…\` = deeper, run \`node scripts/folder-map.mjs <dir>\`):`;
+}
+/** Claude Code caps each hook's additionalContext at 10,000 chars; above it, only a 2KB preview stays inline. */
+export const HOOK_CONTEXT_CHARS = 10000;
+// Covers the header (depth is one or two digits) plus slack.
+const RESERVE = header(99).length + 1 + 100;
 
 function readStdin() {
   try {
@@ -37,14 +44,15 @@ function logSize(root, data, out) {
   if (!sid) return;
   const dir = path.join(root, ".tmp", "grunt", "sessions", sid);
   fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(path.join(dir, "map.json"), `${JSON.stringify({ rows: out.rows, tokens: out.tokens })}\n`);
+  const size = { rows: out.rows, tokens: out.tokens, depth: out.depth };
+  fs.writeFileSync(path.join(dir, "map.json"), `${JSON.stringify(size)}\n`);
 }
 
 function main() {
   try {
     const data = readStdin();
     const root = workspaceRootOf(data);
-    const out = folderMap({ root });
+    const out = folderMap({ root, maxChars: HOOK_CONTEXT_CHARS - RESERVE });
     if (!out || !out.text) return 0;
     try {
       logSize(root, data, out);
@@ -55,7 +63,7 @@ function main() {
       JSON.stringify({
         hookSpecificOutput: {
           hookEventName: "SessionStart",
-          additionalContext: `${HEADER}\n${out.text}`,
+          additionalContext: `${header(/  …$/m.test(out.text) ? out.depth : null)}\n${out.text}`,
         },
       }),
     );