cleargate 0.11.1 → 0.11.4

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 All notable changes to this project are documented in this file.
 Format: [Common Changelog](https://common-changelog.org/) — most-recent version first.
 
+## [0.11.4] — 2026-05-05
+
+SPRINT-26 Dogfood Hardening — Issues Surfaced by Live Use. Five items shipped (3 bugs + 2 CRs); the SDLC Hardening arc closed in SPRINT-25, this is the first sprint addressing dogfood-surfaced framework gaps from real-use testing on `markdown_file_renderer`.
+
+### Fixed
+- **Token-ledger `work_item` fallback grep no longer misattributes to first lexical EPIC-NNN** (BUG-027) — `cleargate-planning/.claude/hooks/token-ledger.sh` resolver chain now tries (1) prior ledger row's `work_item_id` then (2) most-recent `dispatch-marker:` log line BEFORE falling back to transcript grep. Regression of [[BUG-024]] (closed in SPRINT-19); 12 misattribution instances observed during the SPRINT-02 dogfood test on `markdown_file_renderer` (~25% of session output tokens tagged to wrong epic). New authoritative snapshot `cleargate-cli/test/snapshots/hooks/token-ledger.bug-027.sh` supersedes cr-044's byte-equality assertion (cr-044 demoted to existence-only).
+- **`cleargate upgrade --dry-run` and live run now report identical `state=` for every file** (BUG-028) — `cleargate-cli/src/commands/upgrade.ts` dry-run path now computes a hypothetical `postSha` by reading the upstream payload and emits a two-state line `state=<pre> → <post>` for upstream-changed files. `cleargate-cli/src/lib/merge-ui.ts` `renderInlineDiff()` appends a `(whitespace/EOL-only differences — N bytes changed)` annotation when `createPatch()` produces an empty body, so the user always sees a signal in the merge prompt. Discovered when the same `.claude/hooks/session-start.sh` file reported `state=clean` in dry-run and `state=upstream-changed` in the immediately-following real run.
+- **Parallel-eligible Task dispatches no longer silently serialize** (BUG-029) — `cleargate-planning/.claude/hooks/write_dispatch.sh` and `cleargate-planning/.claude/hooks/pending-task-sentinel.sh` now uniquify marker filenames with `${ts}-${PID}-${RANDOM}` suffixes (was: single `.dispatch-${SESSION_ID}.json` and `.pending-task-${TURN_INDEX}.json` per orchestrator session, which collided when two Agent calls fired in one turn). `cleargate-planning/.claude/hooks/token-ledger.sh` SubagentStop handler now matches completion to dispatch by `(work_item_id, agent_type)` tuple from the transcript instead of the prior `ls -t | head -1` newest-file lookup. Discovered during the SPRINT-02 dogfood test where two parallel-eligible stories dispatched at the same timestamp but only one produced a ledger row; the second was silently dropped and re-dispatched 18 minutes later. New authoritative snapshot `cleargate-cli/test/snapshots/hooks/token-ledger.bug-029.sh`; `bug-027.sh` rolls forward to the new canonical state and is demoted to existence-only.
+
+### Added
+- **Smarter session-load restart warning — suppresses no-op rewrites** (CR-059) — new helper `cleargate-cli/src/lib/session-load-delta.ts` exporting `extractSessionLoadDelta(filePath, oldContent, newContent)` returns `true` only when schema-meaningful keys actually changed: `hooks.{PreToolUse,PostToolUse,SessionStart,SubagentStop}.*` for `.claude/settings.json`, `mcpServers.cleargate` for `.mcp.json`. Both `upgrade.ts` and `init.ts` now consult the helper before emitting the v0.11.2 "Restart Claude Code" warning, so cosmetic re-formats (key order, whitespace, trailing newline) don't trigger warning fatigue. Conservative on parse failure: when in doubt, warn.
+
+### Changed
+- **`CLAUDE.md` "Dogfood split" section clarified** (CR-060) — explicit one-paragraph note that target repos do **not** receive a `cleargate-planning/` directory; only the *contents* of `.claude/` and `.cleargate/` are copied. Top-level `CLAUDE.md` is bounded-block-injected; top-level `MANIFEST.json` is skipped per `cleargate-cli/src/init/copy-payload.ts:54` SKIP_FILES; install snapshot lands at `.cleargate/.install-manifest.json`. Pure doc, no behavior change.
+
+## [0.11.3] — 2026-05-05
+
+Hotfix.
+
+### Fixed
+- **`cleargate upgrade` no longer strips the executable bit from `.sh` hook scripts** — `cleargate-cli/src/commands/upgrade.ts` `writeAtomic()` now `chmod 0o755` after writing any `.sh` target. `fs.writeFile` defaults to 0o644; init solved this in `copy-payload.ts` (BUG-018) but upgrade's write path bypassed that fix. Result: every Claude Code hook in target repos failed with `Permission denied` after upgrade until manually re-chmod'd. Observed today on `markdown_file_renderer` after the SPRINT-02 PostToolUse:Edit hook fired.
+
+## [0.11.2] — 2026-05-05
+
+Hotfix.
+
+### Fixed
+- **`cleargate upgrade` and `cleargate init` now warn when session-loaded configs change** — `cleargate-cli/src/commands/upgrade.ts` tracks modifications to `.claude/settings.json` and `.mcp.json` during the run and prints a `⚠ Restart Claude Code in this repo` block at the end if either changed. `init.ts` adds the same "restart Claude Code if already open" suffix to its `Updated .claude/settings.json` log line (parallels the existing `.mcp.json` message). Without this, hook wiring + MCP-server changes silently fail to load until the user happens to restart their session — observed today when SPRINT-02 drafts in `markdown_file_renderer` did not trigger `stamp-and-gate.sh` after upgrade because the running session held a pre-upgrade settings snapshot.
+
 ## [0.11.1] — 2026-05-05
 
 Hotfix.

package/dist/MANIFEST.json

@@ -1,6 +1,6 @@
 {
-  "cleargate_version": "0.11.1",
-  "generated_at": "2026-05-04T22:23:50.738Z",
+  "cleargate_version": "0.11.4",
+  "generated_at": "2026-05-05T17:48:13.929Z",
   "files": [
     {
       "path": ".claude/agents/architect.md",
@@ -67,7 +67,7 @@
     },
     {
       "path": ".claude/hooks/pending-task-sentinel.sh",
-      "sha256": "8204286b19287c490cc09014b0c87e2b2686e6bd120393b7165895d215d6b49a",
+      "sha256": "a3c2dc71a803c37527afd059b81e2adad2104d4887ae125846a2416f2f719b71",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -123,7 +123,7 @@
     },
     {
       "path": ".claude/hooks/token-ledger.sh",
-      "sha256": "6678f814520c379b3ab055f3a1b98c92f631fd415ae24752d45aa8bee058c29c",
+      "sha256": "37a5bc311ca36f016ed72f1ded92d70d2b0acdd8993d634667b05d3407de0f22",
       "tier": "hook",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false
@@ -389,7 +389,7 @@
     },
     {
       "path": ".cleargate/scripts/write_dispatch.sh",
-      "sha256": "abdcaf09b09251f3ab42cb7ec8bdedc5806fd0eb337578f55043bffb158d8128",
+      "sha256": "2d4ebbd8a6f0e833c86b534c3106377018d54f6e24b3ff1a171b18d807103748",
       "tier": "script",
       "overwrite_policy": "always",
       "preserve_on_uninstall": false

package/dist/cli.cjs

@@ -696,7 +696,7 @@ var import_commander = require("commander");
 // package.json
 var package_default = {
   name: "cleargate",
-  version: "0.11.1",
+  version: "0.11.4",
   private: false,
   type: "module",
   description: "Planning framework for Claude Code agents \u2014 sprint/epic/story protocol, five-role agent team (architect/developer/qa/devops/reporter), Karpathy-style awareness wiki.",
@@ -3176,6 +3176,62 @@ function resolveScaffoldRoot(opts) {
   };
 }
 
+// src/lib/session-load-delta.ts
+init_cjs_shims();
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return "[" + value.map(canonicalize).join(",") + "]";
+  }
+  const obj = value;
+  const sortedKeys = Object.keys(obj).sort();
+  const pairs = sortedKeys.map((k) => JSON.stringify(k) + ":" + canonicalize(obj[k]));
+  return "{" + pairs.join(",") + "}";
+}
+var HOOK_EVENTS = ["PreToolUse", "PostToolUse", "SessionStart", "SubagentStop"];
+function extractSettingsHooksBlock(settings) {
+  const hooks = settings["hooks"] ?? {};
+  const extracted = {};
+  for (const event of HOOK_EVENTS) {
+    if (Object.prototype.hasOwnProperty.call(hooks, event)) {
+      extracted[event] = hooks[event];
+    }
+  }
+  return extracted;
+}
+function extractMcpCleargateEntry(mcp2) {
+  const servers = mcp2["mcpServers"] ?? {};
+  return servers["cleargate"] ?? null;
+}
+function extractSessionLoadDelta(filePath, oldContent, newContent) {
+  const normalized = filePath.replace(/\\/g, "/");
+  if (normalized === ".claude/settings.json") {
+    try {
+      const oldSettings = JSON.parse(oldContent);
+      const newSettings = JSON.parse(newContent);
+      const oldHooks = extractSettingsHooksBlock(oldSettings);
+      const newHooks = extractSettingsHooksBlock(newSettings);
+      return canonicalize(oldHooks) !== canonicalize(newHooks);
+    } catch {
+      return true;
+    }
+  }
+  if (normalized === ".mcp.json") {
+    try {
+      const oldMcp = JSON.parse(oldContent);
+      const newMcp = JSON.parse(newContent);
+      const oldEntry = extractMcpCleargateEntry(oldMcp);
+      const newEntry = extractMcpCleargateEntry(newMcp);
+      return canonicalize(oldEntry) !== canonicalize(newEntry);
+    } catch {
+      return true;
+    }
+  }
+  return true;
+}
+
 // src/commands/init.ts
 var HOOK_ADDITION = {
   hooks: {
@@ -3351,10 +3407,17 @@ async function initHandler(opts = {}) {
     }
   }
   const mergedSettings = mergeSettings(existingSettings, HOOK_ADDITION);
+  const mergedSettingsContent = JSON.stringify(mergedSettings, null, 2) + "\n";
+  const existingSettingsContent = existingSettings !== null ? JSON.stringify(existingSettings, null, 2) + "\n" : "{}";
   fs17.mkdirSync(path18.dirname(settingsPath), { recursive: true });
-  writeAtomic(settingsPath, JSON.stringify(mergedSettings, null, 2) + "\n");
-  stdout(`[cleargate init] Updated .claude/settings.json: merged PostToolUse hook
+  writeAtomic(settingsPath, mergedSettingsContent);
+  if (extractSessionLoadDelta(".claude/settings.json", existingSettingsContent, mergedSettingsContent)) {
+    stdout(`[cleargate init] Updated .claude/settings.json: merged PostToolUse hook \u2014 restart Claude Code if already open.
 `);
+  } else {
+    stdout(`[cleargate init] .claude/settings.json unchanged (hooks block already current)
+`);
+  }
   const claudeMdPath = path18.join(cwd, "CLAUDE.md");
   const claudeMdSrcPath = path18.join(payloadDir, "CLAUDE.md");
   let claudeMdBlock;
@@ -8863,7 +8926,16 @@ function removeClearGateHooks(settings) {
 init_cjs_shims();
 var import_diff = require("diff");
 function renderInlineDiff(ours, theirs, filePath) {
-  return (0, import_diff.createPatch)(filePath, ours, theirs, "installed", "upstream");
+  const patch = (0, import_diff.createPatch)(filePath, ours, theirs, "installed", "upstream");
+  const hasHunkLines = patch.split("\n").filter((l) => l.startsWith("+") || l.startsWith("-")).filter((l) => !l.startsWith("+++") && !l.startsWith("---")).length > 0;
+  if (!hasHunkLines) {
+    const ourBytes = Buffer.byteLength(ours, "utf-8");
+    const theirBytes = Buffer.byteLength(theirs, "utf-8");
+    const byteNote = ourBytes !== theirBytes ? `${Math.abs(theirBytes - ourBytes)} bytes changed` : "same byte count";
+    return patch + `(whitespace/EOL-only differences \u2014 ${byteNote})
+`;
+  }
+  return patch;
 }
 async function promptMergeChoice(opts) {
   const { path: filePath, state: state2, ours, theirs } = opts;
@@ -8934,6 +9006,9 @@ async function writeAtomic2(filePath, content) {
   const tmpPath = filePath + ".tmp." + Date.now();
   await fsp.writeFile(tmpPath, content, "utf-8");
   await fsp.rename(tmpPath, filePath);
+  if (filePath.endsWith(".sh")) {
+    await fsp.chmod(filePath, 493);
+  }
 }
 async function updateSnapshotEntry(projectRoot, filePath, newSha) {
   const snapshotPath = path41.join(projectRoot, ".cleargate", ".install-manifest.json");
@@ -9156,7 +9231,15 @@ async function upgradeHandler(flags, cli) {
     let count = 0;
     for (const item of workItems) {
       const state2 = classify(item.entry.sha256, item.installSha, item.currentSha, item.entry.tier);
-      stdout(`[dry-run] ${item.entry.path}  action=${item.action}  state=${state2}`);
+      const projectedPostSha = item.entry.sha256;
+      const projectedPostState = classify(
+        item.entry.sha256,
+        item.entry.sha256,
+        projectedPostSha,
+        item.entry.tier
+      );
+      const stateLabel = state2 !== projectedPostState ? `state=${state2} \u2192 ${projectedPostState}` : `state=${state2}`;
+      stdout(`[dry-run] ${item.entry.path}  action=${item.action}  ${stateLabel}`);
       count++;
     }
     stdout(`[dry-run] ${count} files planned. No changes made.`);
@@ -9164,8 +9247,19 @@ async function upgradeHandler(flags, cli) {
   }
   const packageRoot = cli?.packageRoot ?? cwd;
   const driftMap = {};
+  const SESSION_LOAD_PATHS = /* @__PURE__ */ new Set([".claude/settings.json", ".mcp.json"]);
+  const sessionRestartFiles = [];
   for (const item of workItems) {
     const { entry, currentSha, installSha, action } = item;
+    let preMutationContent = null;
+    if (SESSION_LOAD_PATHS.has(entry.path)) {
+      const targetPath = path41.join(cwd, entry.path);
+      try {
+        preMutationContent = await fsp.readFile(targetPath, "utf-8");
+      } catch {
+        preMutationContent = "";
+      }
+    }
     switch (action) {
       case "skip": {
         stdout(`[skip] ${entry.path}  policy=${entry.overwrite_policy}`);
@@ -9196,9 +9290,28 @@ async function upgradeHandler(flags, cli) {
       current_sha: postSha,
       package_sha: entry.sha256
     };
+    if (SESSION_LOAD_PATHS.has(entry.path) && preMutationContent !== null) {
+      const targetPath = path41.join(cwd, entry.path);
+      let postMutationContent;
+      try {
+        postMutationContent = await fsp.readFile(targetPath, "utf-8");
+      } catch {
+        postMutationContent = "";
+      }
+      if (extractSessionLoadDelta(entry.path, preMutationContent, postMutationContent)) {
+        sessionRestartFiles.push(entry.path);
+      }
+    }
   }
   await writeDriftState(cwd, driftMap, { lastRefreshed: now.toISOString() });
   stdout("[upgrade] complete.");
+  if (sessionRestartFiles.length > 0) {
+    stdout("");
+    stdout(`\u26A0 Restart Claude Code in this repo to load the new ${sessionRestartFiles.length === 1 ? "config" : "configs"}:`);
+    for (const f of sessionRestartFiles) {
+      stdout(`    ${f} (loaded once at session start)`);
+    }
+  }
 }
 
 // src/commands/uninstall.ts