peaks-loop 4.1.3 → 4.1.4

package/dist/services/workspace/claude-settings-template.js

@@ -23,10 +23,11 @@
  * it can be unit-tested in isolation and so the on-disk file matches
  * the in-memory template byte-for-byte.
  *
- * Two `Bash` matchers are emitted (the Step 0.8 mechanical gate and the
- * SOP gate-enforce handler). No `Write|Edit|MultiEdit` entry is emitted:
- * that matcher's gate is `peaks code-gate --json`, installed into the
- * committed `.claude/settings.json` by `peaks hooks install`.
+ * Four `Bash` matchers are emitted: the Step 0.8 mechanical gate, the SOP
+ * gate-enforce handler, and the two layer-B feedback hooks. No
+ * `Write|Edit|MultiEdit` entry is emitted: that matcher's gate is
+ * `peaks code-gate --json`, installed into the committed
+ * `.claude/settings.json` by `peaks hooks install`.
  *
  * The previous `Bash` matcher (which whitelisted a fixed `peaks
  * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
@@ -40,7 +41,15 @@
  * consumer project's `.claude/settings.json` and which exits 0
  * silently for any command not guarded by a registered SOP gate.
  */
-import { EXTERNAL_GATE_EXEMPT_ENV, hasExternalGateExemptions, resolveHookShell, resolveHookSpec } from '../skills/hooks-codegate-superpowers.js';
+import { EXTERNAL_GATE_EXEMPT_ENV, resolveHookShell, resolveHookSpec } from '../skills/hooks-codegate-superpowers.js';
+/**
+ * The comparison and the entry-level merge live in
+ * `claude-settings-template-merge.ts` — they were two thirds of this file's
+ * bytes and none of its template shape. Re-exported here so this module stays
+ * the single public entry point for the template concern: no caller has to
+ * know which half a symbol lives in.
+ */
+export { isRetiredTemplateEntry, mergeTemplateOwnedHooks, templateContentMatches } from './claude-settings-template-merge.js';
 export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
 /**
  * Informational version of the offline template shape. Bumped when the
@@ -98,232 +107,17 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
  *           `mergeTemplateOwnedHooks` drops the retired entry from
  *           existing on-disk files, so an earlier install converges
  *           instead of keeping a no-op with a stale absolute path.
+ *   1.9.0 — added the two layer-B feedback hook entries
+ *           (`pre-tool-peaks-current-directory-scope.sh` and
+ *           `pre-tool-piping-a-test-run-reports-the-pipes-exit-code.sh`),
+ *           pinned to `shell: bash`. Until now their registration existed only
+ *           in the generated copies on the machine that hand-wrote them: a
+ *           fresh clone got the two scripts and no registration, so the
+ *           promotion they carry was true only locally. See
+ *           `buildFeedbackHookHandler` for why the pin is `bash` and not the
+ *           `powershell` its three siblings take.
  */
-export const TEMPLATE_VERSION = '1.8.0';
-/**
- * Compare two serialized template strings: does the on-disk file already
- * declare every entry the generated tree declares?
- *
- * This comparator answers "is each entry the GENERATED tree declares present
- * on disk?", NOT "are the two `hooks` trees identical". Extra on-disk entries
- * are IGNORED, so an entry another writer put in this file never makes it look
- * drifted.
- *
- * That is the deliberate other half of the entry-level merge in
- * `mergeTemplateOwnedHooks` / `workspace-claude-settings-materializer.ts`.
- * `.claude/settings.local.json` has a SECOND writer of `hooks.PreToolUse`:
- * `installAutoCompactHook` appends a `Bash|Task` entry. Under the previous
- * exact-tree rule the merged file carried 4 entries against a 3-entry
- * generated tree, so every `peaks workspace init` answered "drifted",
- * rewrote, and reported `refreshed` forever — precisely the state whole-key
- * ownership existed to prevent, and the reason the merge could not ship alone.
- *
- * Matching is order-insensitive AND multiset-aware: the template declares TWO
- * `Bash` entries, and each must have its own counterpart on disk, so a file
- * carrying only one of them is still reported as drifted (the previous
- * index-by-index loop had the same property; it is load-bearing, not a
- * detail).
- *
- * Returns `true` iff both strings parse to objects whose `hooks.PreToolUse`
- * arrays satisfy that containment, the on-disk file carries NO entry this
- * template has retired (`isRetiredTemplateEntry`), AND the on-disk `env`
- * already carries every exemption the template declares (extra on-disk keys
- * and extra globs are allowed — a user may exempt other trees, and a
- * requirement the file already exceeds must not re-trigger a write).
- *
- * Returns `false` on any `JSON.parse` error, shape mismatch, or
- * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
- * the result — the comparison is on the parsed AST, not on bytes.
- *
- * This is the comparator `initWorkspace` uses to decide whether to
- * refresh a stale `.peaks/.claude-settings-template.json` on disk.
- */
-export function templateContentMatches(generated, onDisk) {
-    let parsedGenerated;
-    let parsedOnDisk;
-    try {
-        parsedGenerated = JSON.parse(generated);
-    }
-    catch {
-        return false;
-    }
-    try {
-        parsedOnDisk = JSON.parse(onDisk);
-    }
-    catch {
-        return false;
-    }
-    if (!isTemplateShape(parsedGenerated) || !isTemplateShape(parsedOnDisk)) {
-        return false;
-    }
-    // Multiset containment: consume one on-disk entry per generated entry so a
-    // file holding a single copy of a doubly-declared entry still fails.
-    const unmatched = [...parsedOnDisk.hooks.PreToolUse];
-    for (const required of parsedGenerated.hooks.PreToolUse) {
-        const at = unmatched.findIndex((candidate) => sameEntry(required, candidate));
-        if (at === -1) {
-            return false;
-        }
-        unmatched.splice(at, 1);
-    }
-    // A RETIRED entry on disk is drift, and this clause is what makes the
-    // retirement in `mergeTemplateOwnedHooks` reach an installed file at all.
-    //
-    // Containment alone cannot express it: a file still carrying
-    // `Write|Edit|MultiEdit` declares every entry the template declares, so
-    // `templateContentMatches` answered "current", no rewrite ran, and the merge
-    // never got the chance to drop it. Measured on a throwaway project root
-    // before this clause existed — init against the rebuilt CLI reported
-    // `already-current` and the retired entry survived verbatim. Declaring less
-    // is not a retirement; the comparator has to say so.
-    //
-    // One extra rewrite per affected install, then the fixed point holds: the
-    // merge emits no retired entry, so the next comparison finds none and
-    // answers `current`.
-    if (parsedOnDisk.hooks.PreToolUse.some((entry) => isRetiredTemplateEntry(entry))) {
-        return false;
-    }
-    // A project installed by a release that predates a template-declared
-    // exemption still needs the refresh this comparator gates — otherwise the
-    // entry would only ever appear on a machine that re-ran `peaks hooks
-    // install`. `hasExternalGateExemptions` is the same predicate the installer
-    // uses, so the two writers cannot drift apart.
-    return hasExternalGateExemptions({ env: parsedOnDisk.env });
-}
-/**
- * Merge the on-disk `hooks.PreToolUse` list with the template's.
- *
- * the entries IT DECLARES — and nothing else. Every other on-disk entry is
- * carried across verbatim, whatever its matcher, because the template has no
- * opinion about it:
- *
- *   - a `matcher` the template does not declare (`Bash|Task`, the auto-compact
- *     hook `installAutoCompactHook` appends) is never touched;
- *   - surplus entries BEYOND the template's count for a declared matcher (a
- *     user's own `Bash` hook) are surplus too, and survive;
- *   - an on-disk entry that fills a declared slot is REPLACED by the template's
- *     entry for it. That is what makes a hand-edited (or older-release) entry
- *     self-heal instead of lingering next to a correct copy of itself.
- *
- * Slot counting is per `matcher` and positional within it: the template
- * declares TWO `Bash` entries, so the first two on-disk `Bash` entries are
- * theirs and a third is the user's. The template's entries are emitted first,
- * in template order, then the preserved ones in their on-disk order — which is
- * a fixed point: re-merging the result yields the result (the template's own
- * entries are encountered first and refill their own slots).
- *
- * Non-conforming entries (no string `matcher`, no `hooks` array) are preserved
- * rather than dropped: guessing at their shape is how a user's entry gets
- * deleted.
- *
- * ONE exception to "preserve what I do not declare": an entry this template
- * used to declare and RETIRED (TEMPLATE_VERSION 1.8.0's `Write|Edit|MultiEdit`
- * gate — see `isRetiredTemplateEntry`) is dropped rather than preserved.
- * Declaring less cannot retire an entry on its own, because preserving
- * undeclared entries is exactly what this function does; without the drop, a
- * pre-1.8.0 install would keep the no-op handler and its version-pinned script
- * path forever. The predicate is narrow enough that only the exact command
- * this template emitted matches.
- */
-export function mergeTemplateOwnedHooks(onDisk, template) {
-    const slots = new Map();
-    for (const entry of template) {
-        if (!isPreToolUseEntry(entry))
-            continue;
-        slots.set(entry.matcher, (slots.get(entry.matcher) ?? 0) + 1);
-    }
-    const taken = new Map();
-    const preserved = [];
-    for (const entry of onDisk) {
-        // Retired by this template — dropped, not carried across.
-        if (isRetiredTemplateEntry(entry)) {
-            continue;
-        }
-        // Unowned by construction: not a shape the template could have declared.
-        if (!isPreToolUseEntry(entry)) {
-            preserved.push(entry);
-            continue;
-        }
-        const declared = slots.get(entry.matcher) ?? 0;
-        const used = taken.get(entry.matcher) ?? 0;
-        if (used >= declared) {
-            preserved.push(entry);
-            continue;
-        }
-        taken.set(entry.matcher, used + 1);
-    }
-    return [...template, ...preserved];
-}
-/** Structural equality of two `PreToolUse` entries. */
-function sameEntry(a, b) {
-    return a.matcher === b.matcher && sameHooksArray(a.hooks, b.hooks);
-}
-function isPreToolUseEntry(value) {
-    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
-        return false;
-    }
-    const candidate = value;
-    return typeof candidate.matcher === 'string' && Array.isArray(candidate.hooks);
-}
-function isTemplateShape(value) {
-    if (typeof value !== 'object' || value === null) {
-        return false;
-    }
-    const candidate = value;
-    if (typeof candidate.hooks !== 'object' || candidate.hooks === null) {
-        return false;
-    }
-    const hooksObj = candidate.hooks;
-    return Array.isArray(hooksObj.PreToolUse);
-}
-function sameHooksArray(a, b) {
-    if (a.length !== b.length) {
-        return false;
-    }
-    for (let i = 0; i < a.length; i += 1) {
-        const ha = a[i];
-        const hb = b[i];
-        // `shell` participates in the comparison: it is machine-specific (see
-        // `resolveHookShell`), so a file written on one platform must be
-        // recognized as drifted on the other instead of silently kept.
-        if (ha.type !== hb.type || ha.command !== hb.command || ha.shell !== hb.shell) {
-            return false;
-        }
-    }
-    return true;
-}
-/**
- * The retired `Write|Edit|MultiEdit` gate entry, as an on-disk file written by
- * a pre-1.8.0 release holds it.
- *
- * TEMPLATE_VERSION 1.8.0 stopped emitting this entry. Declaring less is not
- * enough on its own: `mergeTemplateOwnedHooks` preserves every on-disk entry
- * the template does not declare — that is the whole point of the entry-level
- * ownership rule (it is what keeps `installAutoCompactHook`'s `Bash|Task`
- * entry alive) — so a project installed by an earlier release would keep the
- * no-op handler, and its `node "C:/…/nvm/v24.14.0/…"` path, forever. This
- * predicate is the retirement: `mergeTemplateOwnedHooks` drops a match.
- *
- * Deliberately narrow. It matches the exact command shape this template used
- * to emit — one handler, `node "<…>/services/hooks/write-gate.js"` — under the
- * exact legacy matcher spelling, so a user's OWN `Write|Edit|MultiEdit` entry
- * (a different command, or more than one handler) is preserved like any other
- * entry the template does not declare. A looser "drop anything on this
- * matcher" rule would delete a user's hook, which is the failure the ownership
- * rule exists to prevent.
- */
-const RETIRED_WRITE_GATE_MATCHER = 'Write|Edit|MultiEdit';
-const RETIRED_WRITE_GATE_COMMAND = /^node "[^"]*\/services\/hooks\/write-gate\.js"$/;
-export function isRetiredTemplateEntry(entry) {
-    if (!isPreToolUseEntry(entry))
-        return false;
-    if (entry.matcher !== RETIRED_WRITE_GATE_MATCHER)
-        return false;
-    if (entry.hooks.length !== 1)
-        return false;
-    const handler = entry.hooks[0];
-    return handler.type === 'command' && RETIRED_WRITE_GATE_COMMAND.test(handler.command);
-}
+export const TEMPLATE_VERSION = '1.9.0';
 /**
  * TEMPLATE_VERSION 1.4.0 — the SOP gate-enforce handler, read from the same
  * canonical hook spec `peaks hooks install` uses. Deriving it here (rather
@@ -347,11 +141,12 @@ function buildGateEnforceHandler() {
  * forcing gate is a core feature that PreToolUse hooks can short-
  * circuit but that the `permissions` block cannot.
  *
- * As of TEMPLATE_VERSION 1.8.0 the template emits the two `Bash` matchers
- * only. The `Write|Edit|MultiEdit` fact-forcing bypass is no longer a hook:
- * it is the `env` exemption above, and that matcher's gate
- * (`peaks code-gate --json`) is installed into the committed
- * `.claude/settings.json` by `peaks hooks install`.
+ * As of TEMPLATE_VERSION 1.9.0 the template emits four `Bash` matchers: the
+ * two above, plus one per layer-B feedback hook (`FEEDBACK_HOOK_SCRIPTS`). The
+ * `Write|Edit|MultiEdit` fact-forcing bypass is no longer a hook: it is the
+ * `env` exemption above, and that matcher's gate (`peaks code-gate --json`) is
+ * installed into the committed `.claude/settings.json` by `peaks hooks
+ * install`.
  */
 export function buildClaudeSettingsLocalJson() {
     return {
@@ -387,7 +182,15 @@ export function buildClaudeSettingsLocalJson() {
                     // group and the gate would run twice per Bash call.
                     matcher: 'Bash',
                     hooks: [buildGateEnforceHandler()]
-                }
+                },
+                ...FEEDBACK_HOOK_SCRIPTS.map((script) => ({
+                    // TEMPLATE_VERSION 1.9.0 — the layer-B feedback hooks, one matcher
+                    // group each, for the same reason the entry above has its own: a
+                    // group is peaks-managed only when EVERY handler in it carries a
+                    // peaks sentinel, and none of these handlers does.
+                    matcher: 'Bash',
+                    hooks: [buildFeedbackHookHandler(script)]
+                }))
             ]
         }
     };
@@ -420,3 +223,45 @@ function buildBashGateStep08Handler() {
         ...(shell !== undefined ? { shell } : {})
     };
 }
+/**
+ * TEMPLATE_VERSION 1.9.0 — the two rules promoted to layer B by hand first: the
+ * scripts shipped in `src/services/hooks/`, but the registration existed only in
+ * the generated copy on the machine that wrote it. Emitting it here is what makes
+ * the promotion a property of the repository rather than of that machine — the
+ * layer-B feedback gate reads THIS template's `hooks` block, so a fresh clone had
+ * the enforcement and nothing registering it.
+ *
+ * The filenames are the contract: the layer-B check looks for a hook command that
+ * INVOKES A FILE NAMED AFTER THE RULE, so the command has to carry the script's
+ * name and cannot be a `peaks` verb that dispatches to it.
+ */
+const FEEDBACK_HOOK_SCRIPTS = [
+    'pre-tool-peaks-current-directory-scope.sh',
+    'pre-tool-piping-a-test-run-reports-the-pipes-exit-code.sh'
+];
+/** The shell these two handlers are pinned to. See `buildFeedbackHookHandler`. */
+const FEEDBACK_HOOK_SHELL = 'bash';
+/**
+ * The handler for one feedback hook, pinned to `shell: 'bash'`.
+ *
+ * THE PIN IS THE DECISION, and it is deliberately not the `powershell` its three
+ * siblings take. Measured on this host, both shapes run the script and both print
+ * its refusal to stderr — but they do not report the same exit code:
+ *
+ *   bash       "<script>"                       exit 2   (the script's own code)
+ *   powershell "<script>"                       exit 1   (flattened by the shell)
+ *
+ * Under the Claude Code hook protocol only exit 2 blocks; any other non-zero exit
+ * is a NON-BLOCKING ERROR and the tool call goes ahead. So pinning `powershell`
+ * here would not be a cosmetic difference on a blocking hook — it would turn the
+ * refusal into a log line and let the command through, which is the failure these
+ * two entries exist to prevent. `shell` accepts `bash` and `powershell` only, and
+ * `bash` is also the interpreter this command already names.
+ */
+function buildFeedbackHookHandler(script) {
+    return {
+        type: 'command',
+        command: `bash "\${CLAUDE_PROJECT_DIR}/src/services/hooks/${script}"`,
+        shell: FEEDBACK_HOOK_SHELL
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.1.3",
+  "version": "4.1.4",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -129,10 +129,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.43",
-    "peaks-loop-mut": "0.1.57",
-    "peaks-loop-shared-channel": "0.0.60",
-    "peaks-loop-shared": "0.0.92"
+    "peaks-loop-internal-runtime": "0.0.44",
+    "peaks-loop-shared": "0.0.93",
+    "peaks-loop-mut": "0.1.58",
+    "peaks-loop-shared-channel": "0.0.61"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",