@pruddiman/hem 0.0.1-beta-6f925fe → 0.0.1-beta-697e946

package/dist/agents/documentation-agent.js

@@ -119,8 +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
-        const groupSubfolder = `${context.destinationPath}/${group.id}`;
-        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.`, "");
+        // 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", "");

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.
@@ -387,7 +378,7 @@ export function groupFiles(files, options = {}) {
     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)),
@@ -396,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",

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-6f925fe",
+  "version": "0.0.1-beta-697e946",
   "type": "module",
   "bin": {
     "hem": "./dist/index.js"