@akanjs/devkit 3.0.0-alpha.14 → 3.0.0-alpha.15

package/agentsIndex.test.ts

@@ -10,6 +10,7 @@ import {
   renderRecipeEntries,
   renderScopeAgentBlock,
   renderScopeAgentsMd,
+  renderScopeClaudeMd,
   upsertAgentBlock,
 } from "./agentsIndex";
 import type { RecipeInfo } from "./recipeScanner";
@@ -48,6 +49,15 @@ describe("renderScopeAgentBlock", () => {
   });
 });
 
+describe("renderScopeClaudeMd", () => {
+  test("points at AGENTS.md and restates only the comment rule", () => {
+    const claude = renderScopeClaudeMd({ type: "app", name: "minimal" });
+    expect(claude).toContain("@AGENTS.md");
+    expect(claude).toContain("## Comments — Overrides Your Default");
+    expect(claude).not.toContain("## Recipes In Scope");
+  });
+});
+
 describe("upsertAgentBlock / extractAgentBlock", () => {
   test("round-trips: fresh file → replace block → extract equals block", () => {
     const fresh = renderScopeAgentsMd({ type: "app", name: "minimal" }, "OLD");

package/agentsIndex.ts

@@ -165,8 +165,28 @@ ${block}
 ${AGENT_BLOCK_END}
 `;
 
-/** Claude Code reads nested CLAUDE.md files as it works under a directory; keep it a thin pointer. */
+export const CLAUDE_COMMENT_RULE = `## Comments — Overrides Your Default
+
+Write **no comments** unless the comment passes the test below. This is the rule agents break most often here, so it
+is repeated outside the guide: a diff that adds a comment the test rejects is a diff to redo.
+
+Before typing \`//\`, \`/*\`, or a doc block, ask — **does this sentence carry a fact that is nowhere in the code?**
+
+- Restates the identifier, the signature, or the line under it → delete it.
+- Labels a section (\`// helpers\`, \`// state\`) or narrates a step (\`// fetch the user\`, \`// then save\`) → delete it.
+- JSDoc on an ordinary function, or a why/how preamble on ordinary logic → delete it.
+- Explains the edit you just made, for whoever reads the diff → say it in your reply, not in the file.
+- Names a vendor or protocol quirk, an infrastructure constraint, a library gotcha, security reasoning, a math
+  derivation, a domain field's business meaning, a state transition, or why an obvious alternative was rejected →
+  keep it, one line.
+
+That keep-list is exact — \`Comments\` in the guide is the full version. "It aids readability" and "this logic is
+subtle" are not on it: rename or split the code instead. When you edit an existing file, match its density; if the
+surrounding code carries none, your diff carries none.`;
+
 export const renderScopeClaudeMd = (scope: AgentsIndexScope): string => `# ${scope.name} — Claude Code Guide
 
 @AGENTS.md
+
+${CLAUDE_COMMENT_RULE}
 `;

package/executors.ts

@@ -233,7 +233,7 @@ export class Executor {
         );
       });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal)
+        if (code || signal)
           reject(
             new CommandExecutionError({
               command,
@@ -342,7 +342,7 @@ export class Executor {
         );
       });
       proc.on("exit", (code, signal) => {
-        if (!!code || signal)
+        if (code || signal)
           reject(
             new CommandExecutionError({
               command: modulePath,

package/incrementalBuilder/devWatchBatch.test.ts

@@ -22,27 +22,25 @@ describe("prepareDevWatchBatch", () => {
     expect(prepared.event.devPlan?.files).toEqual(prepared.files);
   });
 
-  test.each([
-    "common",
-    "srvkit",
-    "ui",
-    "webkit",
-  ])("keeps %s facet add/delete generated index in the same generation", (facet) => {
-    const root = "/repo";
-    const changedFile = `${root}/libs/shared/${facet}/tmpExample.ts`;
-    const generatedIndex = `${root}/libs/shared/${facet}/index.ts`;
-    const prepared = prepareDevWatchBatch({
-      generation: 20,
-      batch: { files: [changedFile], kinds: new Set(["code"]) },
-      indexSync: { changedFiles: [generatedIndex], errors: [] },
-      changePlanner: new DevChangePlanner({ workspaceRoot: root }),
-    });
+  test.each(["common", "srvkit", "ui", "webkit"])(
+    "keeps %s facet add/delete generated index in the same generation",
+    (facet) => {
+      const root = "/repo";
+      const changedFile = `${root}/libs/shared/${facet}/tmpExample.ts`;
+      const generatedIndex = `${root}/libs/shared/${facet}/index.ts`;
+      const prepared = prepareDevWatchBatch({
+        generation: 20,
+        batch: { files: [changedFile], kinds: new Set(["code"]) },
+        indexSync: { changedFiles: [generatedIndex], errors: [] },
+        changePlanner: new DevChangePlanner({ workspaceRoot: root }),
+      });
 
-    expect(new Set(prepared.files)).toEqual(new Set([changedFile, generatedIndex]));
-    expect(prepared.event.devPlan?.generatedFiles).toEqual([generatedIndex]);
-    expect(prepared.event.devPlan?.roles).toContain("barrel");
-    expect(prepared.event.devPlan?.actions).toContain("sync-generated");
-  });
+      expect(new Set(prepared.files)).toEqual(new Set([changedFile, generatedIndex]));
+      expect(prepared.event.devPlan?.generatedFiles).toEqual([generatedIndex]);
+      expect(prepared.event.devPlan?.roles).toContain("barrel");
+      expect(prepared.event.devPlan?.actions).toContain("sync-generated");
+    },
+  );
 
   test("marks failed generated index sync as an error generation", () => {
     const root = "/repo";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.14",
+  "version": "3.0.0-alpha.15",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -45,7 +45,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.14",
+    "akanjs": "3.0.0-alpha.15",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",