@pruddiman/hem 0.0.1-beta-72c22cf → 0.0.1-beta-697e946

package/dist/agents/documentation-agent.d.ts

@@ -14,6 +14,21 @@
 import type { Provider } from "../providers/types.js";
 import type { FileGroup, GenerationContext, ExplorationFindings } from "../types.js";
 import { BaseAgent } from "./base-agent.js";
+/** Upper bound on the final prompt size before progressive section drops. */
+export declare const MAX_PROMPT_CHARS = 500000;
+/** Cap on per-group exploration findings text. */
+export declare const MAX_FINDINGS_CHARS = 60000;
+/** Cap on each individual existing-doc's embedded content. */
+export declare const MAX_EXISTING_DOC_CHARS = 8000;
+/** Cap on the aggregate existing-docs section (drops trailing docs beyond this). */
+export declare const MAX_EXISTING_DOCS_SECTION_CHARS = 40000;
+/** Cap on the cross-group findings summary. */
+export declare const MAX_CROSS_GROUP_CHARS = 20000;
+/**
+ * Truncate `text` to `max` chars, appending a short note explaining how to
+ * retrieve the rest. Returns the original text if already within budget.
+ */
+export declare function truncateForPrompt(text: string, max: number, tailNote: string): string;
 /**
  * An agent that uses an LLM to generate documentation for a single
  * file group. The agent writes files directly via the edit tool.

package/dist/agents/documentation-agent.js

@@ -12,6 +12,33 @@
  *   - If existing docs are provided, the agent merges inline.
  */
 import { BaseAgent } from "./base-agent.js";
+// ── Prompt-size budgets ─────────────────────────────────────────────────
+//
+// Copilot Sonnet has a ~168k token context window. Claude 1M is larger but
+// we pick the smaller envelope for a one-size-fits-all cap. At ~4 chars per
+// token the hard ceiling is ~670k chars; we target ~500k to leave headroom
+// for the model's output tokens. Per-section caps keep any single section
+// from dominating the prompt.
+/** Upper bound on the final prompt size before progressive section drops. */
+export const MAX_PROMPT_CHARS = 500_000;
+/** Cap on per-group exploration findings text. */
+export const MAX_FINDINGS_CHARS = 60_000;
+/** Cap on each individual existing-doc's embedded content. */
+export const MAX_EXISTING_DOC_CHARS = 8_000;
+/** Cap on the aggregate existing-docs section (drops trailing docs beyond this). */
+export const MAX_EXISTING_DOCS_SECTION_CHARS = 40_000;
+/** Cap on the cross-group findings summary. */
+export const MAX_CROSS_GROUP_CHARS = 20_000;
+/**
+ * Truncate `text` to `max` chars, appending a short note explaining how to
+ * retrieve the rest. Returns the original text if already within budget.
+ */
+export function truncateForPrompt(text, max, tailNote) {
+    if (text.length <= max)
+        return text;
+    return (text.slice(0, max).trimEnd() +
+        `\n\n[… truncated ${text.length - max} chars — ${tailNote}]`);
+}
 // ── Agent ───────────────────────────────────────────────────────────────
 /**
  * An agent that uses an LLM to generate documentation for a single
@@ -37,6 +64,14 @@ export class DocumentationAgent extends BaseAgent {
         if (verbose) {
             verbose(`[${tag}] Prompt: ${prompt.length.toLocaleString()} chars`);
         }
+        if (prompt.length > MAX_PROMPT_CHARS) {
+            // Per-section caps should have prevented this; log loudly so we can
+            // investigate what's overflowing rather than silently failing at the
+            // provider's 168k-token barrier.
+            process.stderr.write(`[${tag}] WARNING: prompt ${prompt.length.toLocaleString()} chars exceeds ` +
+                `MAX_PROMPT_CHARS=${MAX_PROMPT_CHARS.toLocaleString()}. ` +
+                `Provider may reject. Investigate per-section truncation.\n`);
+        }
         // 2. Create a new session
         const sessionId = await this.createSession(`Hem: doc — ${group.label}`);
         if (verbose) {
@@ -84,7 +119,11 @@ export class DocumentationAgent extends BaseAgent {
         // 1. System-level instructions
         parts.push(`Generate documentation files that answer the questions the code asks — not`, `merely describe what the code does.`, "", `**You write files directly using the edit tool.** Do NOT return Markdown content`, `in your response text. Instead, use the edit tool to create and write files in`, `the destination directory. When you are done writing all files, stop.`, "");
         // 2. Where to write files
-        parts.push("## Destination directory", "", `Write all documentation files under: \`${context.destinationPath}\``, "", `You have full autonomy over:`, `- **File naming**: Choose descriptive kebab-case filenames (e.g., \`user-authentication.md\`)`, `- **Directory structure**: Create subdirectories that make sense for this codebase`, `- **Number of files**: Create as many files as needed to properly document the group`, `- **File structure**: Design each document's heading hierarchy and sections`, "", `Guidelines for file organization:`, `- Choose a directory layout that reflects how the codebase is actually organized`, `- You may use flat files, subdirectories, or nested structures — whatever fits best`, `- Use \`.md\` extension for all files`, "");
+        // Sub-agents (IDs like `parent:sub-3`) share the parent group's folder —
+        // otherwise every chunk of a large group creates its own sibling dir.
+        const parentGroupId = group.id.split(":")[0] ?? group.id;
+        const groupSubfolder = `${context.destinationPath}/${parentGroupId}`;
+        parts.push("## Destination directory", "", `Write ALL documentation files for this group under this exact subfolder:`, "", `  \`${groupSubfolder}/\``, "", `**Do NOT** write outside this subfolder. **Do NOT** write to the root`, `\`${context.destinationPath}\` directory or any sibling group's subfolder.`, `This keeps the docs tree organized one-subfolder-per-group.`, "", `Within \`${groupSubfolder}/\` you have full autonomy over:`, `- **File naming**: Choose descriptive kebab-case filenames (e.g., \`overview.md\`, \`api-reference.md\`).`, `- **Nested subdirectories**: Create child folders inside the group subfolder if it helps (e.g., \`${groupSubfolder}/guides/getting-started.md\`).`, `- **Number of files**: Create as many files as needed to properly document the group.`, `- **File structure**: Design each document's heading hierarchy and sections.`, "", `Use \`.md\` extension for all files.`, "", `### How to create the subfolder`, "", `Run \`mkdir -p ${groupSubfolder}\` once at the start using the bash tool, then`, `use the edit tool to write each \`.md\` file into that folder. Do NOT write a`, `shell script, Python script, or any other helper file to create directories —`, `the bash tool is allowed to run \`mkdir\` directly, and the edit tool handles`, `everything else.`, "");
         // 3. Quality standards
         parts.push("## Quality Standard: Answer Every Question", "", "Your primary quality standard is: **every question from the exploration findings", "MUST be answered in the generated documentation.** Do NOT leave any question", "unanswered. If you cannot find a definitive answer, state what is known and what", "requires further investigation — but NEVER silently skip a question.", "", "For each integration discovered in the exploration findings:", "", "1. **Use `webfetch` to research answers**: When an integration has an", "   `officialDocsUrl`, fetch that URL to find authoritative answers.", "2. **Address HOW, not just WHAT**: Explain HOW to access, query, monitor,", "   and troubleshoot each integration.", "3. **Answer operational questions**: Every `operationalQuestions` entry for each", "   integration MUST be answered in the documentation.", "");
         parts.push("## Documentation quality standards", "");
@@ -103,7 +142,7 @@ export class DocumentationAgent extends BaseAgent {
         parts.push("## Exploration findings for this group", "");
         if (groupFindings) {
             parts.push("The exploration phase discovered these findings for your group:", "");
-            parts.push(DocumentationAgent.formatFindings(groupFindings));
+            parts.push(truncateForPrompt(DocumentationAgent.formatFindings(groupFindings), MAX_FINDINGS_CHARS, "re-run hem exploration or inspect the source files directly"));
         }
         else {
             parts.push("No exploration findings available for this group. Use tools to read and analyze the source files directly.", "");
@@ -111,16 +150,33 @@ export class DocumentationAgent extends BaseAgent {
         // 6. Cross-group context
         parts.push("## Cross-group context", "");
         parts.push("Other groups discovered these integrations and dependencies that may relate to", "your group:", "");
-        parts.push(DocumentationAgent.summarizeCrossGroupFindings(allFindings, group.id));
+        parts.push(truncateForPrompt(DocumentationAgent.summarizeCrossGroupFindings(allFindings, group.id), MAX_CROSS_GROUP_CHARS, "inspect sibling group docs directly with `cat`"));
         parts.push("");
         // 7. Existing docs — search-before-write with skip/update/create decisions
         if (context.existingDocs.length > 0 || (context.mentionedDocPaths && context.mentionedDocPaths.length > 0)) {
             parts.push("## Existing documentation in destination", "");
             parts.push("The destination directory already contains documentation files.", "**Before writing ANY file, you MUST search for related existing docs.**", "", "### Decision criteria for each topic you plan to document:", "", "1. **SKIP** — if an existing doc already covers the topic accurately and", "   completely. Do NOT rewrite content that is already correct.", "2. **UPDATE** — if an existing doc covers the topic but is stale, incomplete,", "   or missing sections. Update it **in place** using the edit tool. Preserve", "   accurate content; fix or expand what is stale or missing.", "3. **CREATE** — if no existing doc covers the topic. Write a new file.", "", "**Content-only changes**: Do NOT rename, move, or delete existing files.", "Only modify file content.", "");
-            // Full content for the most relevant docs
+            // Full content for the most relevant docs — with per-file + total
+            // caps so a single group's docs can't blow out the prompt window.
+            // `context.existingDocs` is already ranked by the search index, so
+            // when we hit the total budget we drop the trailing (least relevant)
+            // entries rather than truncating across the board.
             if (context.existingDocs.length > 0) {
-                parts.push(`### Most relevant existing docs (${context.existingDocs.length} file${context.existingDocs.length === 1 ? "" : "s"}, full content)`, "");
+                const includedDocs = [];
+                let includedBytes = 0;
+                let droppedDocs = 0;
                 for (const doc of context.existingDocs) {
+                    const truncated = truncateForPrompt(doc.content, MAX_EXISTING_DOC_CHARS, `run \`cat ${doc.path}\` to read the full content`);
+                    if (includedBytes + truncated.length > MAX_EXISTING_DOCS_SECTION_CHARS &&
+                        includedDocs.length > 0) {
+                        droppedDocs = context.existingDocs.length - includedDocs.length;
+                        break;
+                    }
+                    includedDocs.push({ path: doc.path, content: truncated });
+                    includedBytes += truncated.length;
+                }
+                parts.push(`### Most relevant existing docs (${includedDocs.length} of ${context.existingDocs.length} file${context.existingDocs.length === 1 ? "" : "s"}, full content${droppedDocs > 0 ? `; ${droppedDocs} omitted — read with \`cat\` as needed` : ""})`, "");
+                for (const doc of includedDocs) {
                     parts.push(`#### \`${doc.path}\``);
                     parts.push("```markdown");
                     parts.push(doc.content);

package/dist/discovery.js

@@ -26,6 +26,19 @@ const DEFAULT_IGNORE_PATTERNS = [
     "**/coverage/**",
     "**/.cache/**",
     "**/.tmp/**",
+    // Framework build output and on-disk caches. These produce noisy,
+    // non-source files that leaked into grouping when a project's own
+    // .gitignore wasn't picked up (e.g. monorepo inner packages).
+    "**/.next/**",
+    "**/.turbo/**",
+    "**/.vercel/**",
+    "**/.nuxt/**",
+    "**/.svelte-kit/**",
+    "**/.astro/**",
+    "**/.parcel-cache/**",
+    "**/.vite/**",
+    "**/out/**",
+    "**/storybook-static/**",
 ];
 /**
  * Known binary file extensions.

package/dist/grouping.js

@@ -137,15 +137,6 @@ export function commonDirectory(files) {
     }
     return common.length === 0 ? "." : common.join("/");
 }
-/**
- * Extracts the file stem (name without the final extension).
- * For multi-part suffixes like `user.controller.ts`, the stem is `user`.
- */
-function fileStem(relativePath) {
-    const base = relativePath.split("/").pop() ?? "";
-    const dotIndex = base.indexOf(".");
-    return dotIndex === -1 ? base : base.substring(0, dotIndex);
-}
 /**
  * Returns the "name" portion of the file without known layer suffixes
  * and without the actual file extension.
@@ -225,12 +216,25 @@ function toDisplayLabel(name) {
         .replace(/\b\w/g, (ch) => ch.toUpperCase());
 }
 // ── Main ────────────────────────────────────────────────────────────────
-/** Minimum files a top-level src directory needs before it's promoted. */
-const TOP_LEVEL_PROMOTION_THRESHOLD = 3;
+/**
+ * Minimum files a top-level src directory needs before it's promoted.
+ *
+ * Raised from 3 to 6 after a real-world run produced 71 groups on a
+ * Next.js monorepo — every tiny infrastructure directory (heartbeat/,
+ * ngrok/, caddy/) was auto-promoted. A higher bar keeps those files
+ * flowing through to layer/component passes or "Other".
+ */
+const TOP_LEVEL_PROMOTION_THRESHOLD = 6;
 /** Minimum size of an import-graph connected component to become a group. */
 const MIN_COMPONENT_SIZE = 2;
 /** Components larger than this split along directory boundaries. */
 const MAX_COMPONENT_SIZE = 6;
+/**
+ * Maximum number of vertical groups before consolidation kicks in. When
+ * exceeded, the smallest non-pinned groups are merged into "Other" until
+ * the count drops back under this cap.
+ */
+const MAX_VERTICAL_GROUPS = 20;
 /**
  * Groups discovered files. See module docstring for the priority order.
  *
@@ -269,7 +273,7 @@ export function groupFiles(files, options = {}) {
         addFeature(match.key, toDisplayLabel(match.name), file);
         pinnedKeys.add(match.key);
     }
-    // ── Pass 2: src top-level promotion (≥3 files) ──
+    // ── Pass 2: src top-level promotion (≥TOP_LEVEL_PROMOTION_THRESHOLD files) ──
     const topLevelCounts = countTopLevelDirs(textFiles);
     for (const file of textFiles) {
         if (assigned.has(file.path))
@@ -279,6 +283,8 @@ export function groupFiles(files, options = {}) {
             continue;
         if (LAYER_DIRECTORIES.has(top.toLowerCase()))
             continue;
+        if (!isValidLabelCandidate(top))
+            continue;
         const count = topLevelCounts.get(top) ?? 0;
         if (count < TOP_LEVEL_PROMOTION_THRESHOLD)
             continue;
@@ -291,6 +297,8 @@ export function groupFiles(files, options = {}) {
         const feature = extractFeatureName(file.path);
         if (!feature)
             continue;
+        if (!isValidLabelCandidate(feature))
+            continue;
         addFeature(feature.toLowerCase(), toDisplayLabel(feature), file);
     }
     // Demote single-file feature buckets (unless pinned by a prior).
@@ -345,12 +353,32 @@ export function groupFiles(files, options = {}) {
     }
     // ── Pass 6: catch-all "Other" ──
     const ungrouped = textFiles.filter((f) => !assigned.has(f.path));
+    // ── Pass 7: consolidate if too many vertical groups ──
+    // Monorepos with many top-level feature dirs produce too many verticals
+    // to be useful. Fold the smallest non-pinned ones into "Other" until
+    // we're back under the cap. Priors stay pinned regardless.
+    // If consolidation runs, "Other" will exist afterward, so we target
+    // one fewer bucket to keep the total (buckets + Other) at the cap.
+    if (featureBuckets.size > MAX_VERTICAL_GROUPS - 1) {
+        const candidates = [...featureBuckets.entries()]
+            .filter(([key]) => !pinnedKeys.has(key))
+            .sort(([, a], [, b]) => a.length - b.length);
+        let excess = featureBuckets.size - (MAX_VERTICAL_GROUPS - 1);
+        for (const [key, bucket] of candidates) {
+            if (excess <= 0)
+                break;
+            ungrouped.push(...bucket);
+            featureBuckets.delete(key);
+            featureLabels.delete(key);
+            excess--;
+        }
+    }
     // ── Build FileGroup objects ──
     const groups = [];
     for (const [key, bucket] of featureBuckets) {
         const label = featureLabels.get(key) ?? toDisplayLabel(key);
         groups.push({
-            id: toKebabCase(label) + "-feature",
+            id: toKebabCase(label),
             label,
             type: "vertical",
             files: bucket.sort((a, b) => a.path.localeCompare(b.path)),
@@ -359,6 +387,10 @@ export function groupFiles(files, options = {}) {
     }
     for (const [label, bucket] of layerBuckets) {
         groups.push({
+            // Layer groups keep the `-layer` suffix because they're a different
+            // architectural concept than feature verticals, and without it an
+            // "Auth" feature + "Controllers" layer + "Controllers" feature prior
+            // could collide on ID.
             id: toKebabCase(label) + "-layer",
             label,
             type: "horizontal",
@@ -424,25 +456,58 @@ function buildComponentGroups(components, byPath) {
         if (files.length < MIN_COMPONENT_SIZE)
             continue;
         if (files.length <= MAX_COMPONENT_SIZE) {
-            out.push(componentToGroup(files));
+            const group = componentToGroup(files);
+            if (group)
+                out.push(group);
             continue;
         }
         for (const sub of bisectByDirectory(files)) {
             if (sub.length < MIN_COMPONENT_SIZE)
                 continue;
-            out.push(componentToGroup(sub));
+            const group = componentToGroup(sub);
+            if (group)
+                out.push(group);
         }
     }
     return out;
 }
+/**
+ * Build a vertical group from an import-graph component.
+ *
+ * Returns `null` when the component has no meaningful shared directory
+ * (root-level files) or when the derived basename would produce a
+ * degenerate label (leading dot, hash-only, empty). Rejected components
+ * fall through to the "Other" bucket rather than inventing a group name
+ * from a filename.
+ */
 function componentToGroup(files) {
     const commonDir = commonDirectory(files);
-    const basename = commonDir.split("/").filter((s) => s.length > 0).pop() ?? "cluster";
+    if (commonDir === "." || commonDir === "")
+        return null;
+    const basename = commonDir.split("/").filter((s) => s.length > 0).pop() ?? "";
+    if (!isValidLabelCandidate(basename))
+        return null;
     const label = toDisplayLabel(basename);
-    // Append a stable short hash of paths to avoid collisions with other buckets.
     const key = basename.toLowerCase() + "-cluster";
     return { key, label, files };
 }
+/**
+ * Reject directory/label candidates that would produce junk group IDs:
+ *   - leading dot (`.next`, `.turbo`, `.vite`) — build-output leaks.
+ *   - empty string.
+ *   - hash-like strings (≥12 consecutive lowercase-alnum chars with no
+ *     vowels or separators) — Next.js dev-cache hash dirs.
+ */
+function isValidLabelCandidate(name) {
+    if (!name)
+        return false;
+    if (name.startsWith("."))
+        return false;
+    const lower = name.toLowerCase();
+    if (/^[a-z0-9]{12,}$/.test(lower) && !/[aeiou]/.test(lower))
+        return false;
+    return true;
+}
 /**
  * Split a large component into sub-groups by directory prefix. Files are
  * bucketed by their first directory segment; singletons collapse back into

package/dist/providers/copilot.js

@@ -20,7 +20,7 @@
  */
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-// ── Read-only bash command allowlist ────────────────────────────────────
+// ── Bash command allowlists ─────────────────────────────────────────────
 /**
  * Base commands allowed in read-only bash mode.
  * Mirrors the READ_ONLY_BASH config in OpenCodeProvider.
@@ -29,6 +29,16 @@ const READ_ONLY_CMDS = new Set([
     "cat", "head", "tail", "grep", "find", "ls",
     "wc", "file", "tree", "du",
 ]);
+/**
+ * Filesystem-setup commands writing agents are allowed to run. Mirrors
+ * WRITING_AGENT_BASH in OpenCodeProvider. These are needed so agents can
+ * create their per-group output subfolder without falling back to writing
+ * throwaway scripts.
+ */
+const WRITING_AGENT_CMDS = new Set([
+    ...READ_ONLY_CMDS,
+    "mkdir", "rmdir", "touch", "echo", "mv", "cp",
+]);
 /**
  * Check whether a shell command is read-only (safe to run without write access).
  * Matches READ_ONLY_BASH from OpenCodeProvider:
@@ -48,6 +58,28 @@ function isReadOnlyCommand(cmd) {
     }
     return false;
 }
+/**
+ * Check whether a shell command is allowed for writing agents. Includes
+ * the read-only set plus filesystem-setup commands (mkdir, touch, etc.).
+ */
+function isWritingAgentCommand(cmd) {
+    if (isReadOnlyCommand(cmd))
+        return true;
+    const base = cmd.trim().split(/\s+/)[0] ?? "";
+    return WRITING_AGENT_CMDS.has(base);
+}
+/**
+ * Writing agents that are allowed to mkdir / touch / mv / cp for
+ * scaffolding their per-group output subfolder. Matches the OpenCode
+ * `writingAgentPermission` / `orgAgentPermission` list.
+ */
+const WRITING_AGENTS = new Set([
+    "hem-doc",
+    "hem-arch",
+    "hem-index",
+    "hem-org",
+    "hem-xref",
+]);
 /** Environment variable names checked for GitHub token, in priority order. */
 const TOKEN_ENV_VARS = ["COPILOT_GITHUB_TOKEN", "GH_TOKEN", "GITHUB_TOKEN"];
 /** Resolve the broadcast MCP server path relative to this compiled module. */
@@ -76,6 +108,10 @@ function agentAllowsShell(agentName, command) {
     // hem-group uses READ_ONLY_BASH too (bash is explicitly read-only, not "deny")
     if (isReadOnlyCommand(command))
         return true;
+    // Writing agents (hem-doc / hem-arch / hem-index / hem-org / hem-xref)
+    // also need mkdir/touch/mv/cp/echo/rmdir to scaffold their output folder.
+    if (WRITING_AGENTS.has(agentName) && isWritingAgentCommand(command))
+        return true;
     // hem-org additionally allows rm (mirrors ORG_AGENT_BASH)
     if (agentName === "hem-org" && command.trim().split(/\s+/)[0] === "rm")
         return true;

package/dist/providers/opencode.d.ts

@@ -40,14 +40,52 @@ export declare const READ_ONLY_BASH: {
     readonly "git diff *": "allow";
     readonly "*": "deny";
 };
+/**
+ * Bash permission set for writing agents (hem-doc, hem-arch, hem-index,
+ * hem-xref). Inherits read-only inspection commands and additionally
+ * allows the minimum set of filesystem-setup commands agents need to
+ * create per-group subfolders and scaffold empty files without resorting
+ * to writing throwaway scripts (e.g. a Python `make_dir.py`).
+ *
+ * Writing agents with only READ_ONLY_BASH got stuck in a loop trying to
+ * mkdir their output directory via the Copilot shell tool, being denied,
+ * and then fabricating Python to work around it.
+ */
+export declare const WRITING_AGENT_BASH: {
+    readonly "mkdir *": "allow";
+    readonly "rmdir *": "allow";
+    readonly "touch *": "allow";
+    readonly "echo *": "allow";
+    readonly "mv *": "allow";
+    readonly "cp *": "allow";
+    readonly "cat *": "allow";
+    readonly "head *": "allow";
+    readonly "tail *": "allow";
+    readonly "grep *": "allow";
+    readonly "find *": "allow";
+    readonly "ls *": "allow";
+    readonly "wc *": "allow";
+    readonly "file *": "allow";
+    readonly "tree *": "allow";
+    readonly "du *": "allow";
+    readonly "git status *": "allow";
+    readonly "git diff *": "allow";
+    readonly "*": "deny";
+};
 /**
  * Extended bash permission set for organization workers. Inherits all
- * read-only commands from {@link READ_ONLY_BASH} and additionally allows
- * `rm` so workers can delete files when executing arbiter DELETE decisions
- * instead of writing empty content as a deletion proxy.
+ * writing-agent commands from {@link WRITING_AGENT_BASH} and additionally
+ * allows `rm` so workers can delete files when executing arbiter DELETE
+ * decisions instead of writing empty content as a deletion proxy.
  */
 export declare const ORG_AGENT_BASH: {
     readonly "rm *": "allow";
+    readonly "mkdir *": "allow";
+    readonly "rmdir *": "allow";
+    readonly "touch *": "allow";
+    readonly "echo *": "allow";
+    readonly "mv *": "allow";
+    readonly "cp *": "allow";
     readonly "cat *": "allow";
     readonly "head *": "allow";
     readonly "tail *": "allow";

package/dist/providers/opencode.js

@@ -43,14 +43,34 @@ export const READ_ONLY_BASH = {
     "git diff *": "allow",
     "*": "deny",
 };
+/**
+ * Bash permission set for writing agents (hem-doc, hem-arch, hem-index,
+ * hem-xref). Inherits read-only inspection commands and additionally
+ * allows the minimum set of filesystem-setup commands agents need to
+ * create per-group subfolders and scaffold empty files without resorting
+ * to writing throwaway scripts (e.g. a Python `make_dir.py`).
+ *
+ * Writing agents with only READ_ONLY_BASH got stuck in a loop trying to
+ * mkdir their output directory via the Copilot shell tool, being denied,
+ * and then fabricating Python to work around it.
+ */
+export const WRITING_AGENT_BASH = {
+    ...READ_ONLY_BASH,
+    "mkdir *": "allow",
+    "rmdir *": "allow",
+    "touch *": "allow",
+    "echo *": "allow",
+    "mv *": "allow",
+    "cp *": "allow",
+};
 /**
  * Extended bash permission set for organization workers. Inherits all
- * read-only commands from {@link READ_ONLY_BASH} and additionally allows
- * `rm` so workers can delete files when executing arbiter DELETE decisions
- * instead of writing empty content as a deletion proxy.
+ * writing-agent commands from {@link WRITING_AGENT_BASH} and additionally
+ * allows `rm` so workers can delete files when executing arbiter DELETE
+ * decisions instead of writing empty content as a deletion proxy.
  */
 export const ORG_AGENT_BASH = {
-    ...READ_ONLY_BASH,
+    ...WRITING_AGENT_BASH,
     "rm *": "allow",
 };
 // ── OpenCode Provider ───────────────────────────────────────────────────
@@ -183,10 +203,11 @@ export class OpenCodeProvider {
             // modelID may already include a sub-provider prefix (e.g. "github-copilot/opus-4.6")
             // when the user picked an opencode sub-provider model via `hem config`. Use it as-is.
             : modelID.includes("/") ? modelID : `${providerID}/${modelID}`;
-        // Writing agents get scoped access to the destination directory.
+        // Writing agents get scoped access to the destination directory plus
+        // the filesystem-setup commands they need to create group subfolders.
         const writingAgentPermission = {
             edit: "allow",
-            bash: READ_ONLY_BASH,
+            bash: WRITING_AGENT_BASH,
             webfetch: "allow",
             external_directory: "allow",
         };

package/dist/types.d.ts

@@ -71,7 +71,7 @@ export interface FileInfo {
 }
 /** A collection of related source files to be documented together. */
 export interface FileGroup {
-    /** Unique group identifier (e.g., `user-feature`, `controllers-layer`). */
+    /** Unique group identifier (e.g., `user`, `auth`, `controllers-layer`). */
     id: string;
     /** Human-readable group name (e.g., "User Feature", "Controllers"). */
     label: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pruddiman/hem",
-  "version": "0.0.1-beta-72c22cf",
+  "version": "0.0.1-beta-697e946",
   "type": "module",
   "bin": {
     "hem": "./dist/index.js"