peaks-loop 4.0.49 → 4.0.50

package/dist/services/config/config-safety.js

@@ -173,15 +173,17 @@ export function resolveCanonicalProjectRootStrict(startPath) {
     catch {
         throw new InvalidProjectRootError('non-existent', startPath);
     }
-    if (realStart !== start) {
-        // User passed a path through a symlink; reject as non-canonical
-        // for trust-boundary entry points.
-        throw new InvalidProjectRootError('non-canonical', startPath);
-    }
-    // Delegate to the existing canonicalization (git root → heuristic)
-    // AFTER the strict pre-checks pass.
-    const canonical = resolveCanonicalProjectRoot(startPath);
-    if (canonical === startPath || canonical === realStart) {
+    // Use the realpath form as the canonical input. macOS exposes
+    // `/var/folders/...` as a symlink to `/private/var/folders/...`, so any
+    // path returned by `os.tmpdir()` (and therefore any `mkdtempSync(...)`
+    // result) has `realStart !== start`. Rejecting that case as
+    // "non-canonical" would block the legitimate SessionStart hook path
+    // and the test fixtures under `tests/unit/hooks/`. The security
+    // property is preserved: `realpathSync` collapses any attacker-
+    // controlled symlink chain, so `realStart` IS the canonical form
+    // regardless of which prefix the caller used.
+    const canonical = resolveCanonicalProjectRoot(realStart);
+    if (canonical === realStart) {
         return canonical;
     }
     // Canonicalization moved the path (e.g. to a git root) — accept it

package/dist/services/final-review/pre-post-diff.js

@@ -123,13 +123,21 @@ function isSourcePath(path) {
  * read as two deleted cases; a class that is half-counted is worse than a class
  * that is not counted at all.
  *
+ * Word-boundary simulation, not `\b`. The JS regex could spell this as `\b`
+ * directly, but the POSIX ERE side of the count has to run on macOS too —
+ * where `git grep -E` is BSD grep, and BSD grep's POSIX ERE has no `\b`
+ * (it is a literal `b`). The two expressions therefore both spell the boundary
+ * as `(^|[^A-Za-z0-9_])`: start of line OR a non-word character. The two
+ * sides MUST agree, and `git grep -c` counts matched lines (not occurrences)
+ * so the extra prefix group does not shift the count.
+ *
  * What is deliberately NOT modelled: an occurrence inside a comment or a string
  * literal still matches. That is symmetric — the same expression is evaluated on
  * both sides — so it cancels out of the DELTA, which is the only thing a removal
  * is ever derived from.
  */
-const TEST_CASE_LINE_RE = /\b(it|test)(\.[A-Za-z]+)*\(/;
-const TEST_CASE_ERE = '\\b(it|test)(\\.[A-Za-z]+)*\\(';
+const TEST_CASE_LINE_RE = /(?:^|[^A-Za-z0-9_])(it|test)(\.[A-Za-z]+)*\(/;
+const TEST_CASE_ERE = '(^|[^A-Za-z0-9_])(it|test)(\\.[A-Za-z]+)*\\(';
 /**
  * Column-0 `export` — an export STATEMENT, not a type-checked symbol.
  *

package/dist/services/observability/observability-service.d.ts

@@ -29,8 +29,8 @@ export declare const ObservabilityEventSchema: z.ZodObject<{
     ts: z.ZodString;
     sessionId: z.ZodString;
     category: z.ZodEnum<{
-        dispatch: "dispatch";
         "slice-transition": "slice-transition";
+        dispatch: "dispatch";
         checkpoint: "checkpoint";
         "mode-gate": "mode-gate";
         "context-trigger": "context-trigger";

package/dist/services/scan/api-diff-types.js

@@ -8,7 +8,25 @@
  * is not merely annotated. `confidence: 'exact'` is reserved for lines where
  * both sides were parsed AND the recorded interface was fully readable.
  */
+import { realpathSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
+/**
+ * Canonicalize through symlinks so two paths that name the same directory through
+ * different prefixes (the macOS `/var` <-> `/private/var` quirk the brief calls
+ * out) line up as the same literal on both sides of the prefix test below.
+ * Falls back to `resolve()` when the path does not exist yet — `realpathSync`
+ * throws on missing paths, and several callers in the suite inspect not-yet-
+ * created paths (e.g. the "string prefix of a sibling" guard at
+ * api-diff-service.test.ts:462).
+ */
+function safeRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
 /** The honest boundary of the feature. Printed in the output, not just documented. */
 export const NOT_DETECTABLE = [
     'a field whose type is unchanged but whose meaning changed',
@@ -38,8 +56,8 @@ export function isRecord(value) {
  * the misleading `archive/docs/api.json`.
  */
 export function toDisplayPath(projectRoot, file) {
-    const rootParts = resolve(projectRoot).split(sep);
-    const fileParts = resolve(file).split(sep);
+    const rootParts = safeRealpath(projectRoot).split(sep);
+    const fileParts = safeRealpath(file).split(sep);
     const inside = fileParts.length > rootParts.length
         && rootParts.every((part, index) => part === fileParts[index]);
     return (inside ? fileParts.slice(rootParts.length) : fileParts).join('/');

package/dist/services/security/safe-settings-path.js

@@ -71,12 +71,30 @@ export function assertSafeDispatchRecordPath(recordPath, projectRoot) {
         // to create it). Fall back to lexical comparison against the
         // canonical projectRoot — the write will then create the file,
         // and any symlink in the parent will be caught on the next read.
+        //
+        // macOS note: the project's own realpath may still resolve the
+        // `/var -> /private/var` symlink even when the sub-agent dir does
+        // not exist yet, so the caller can compare on a stable prefix
+        // instead of having one side of the comparison on `/var/...` and
+        // the other on `/private/var/...`. We still validate that the
+        // canonical record path lives under the canonical projectRoot.
         const fallback = resolve(projectRoot, '.peaks', SUB_AGENTS_DIR);
         const rel2 = relative(fallback, recordPath);
         if (rel2.startsWith('..') || isAbsolute(rel2)) {
             throw invalidPathError(recordPath, 'must be under .peaks/_sub_agents/');
         }
-        return recordPath;
+        try {
+            realRoot = realpathSync(projectRoot);
+            const canonicalRecord = resolve(realRoot, '.peaks', SUB_AGENTS_DIR, recordPath.slice(fallback.length + 1));
+            const realRel = relative(realRoot, canonicalRecord);
+            if (realRel.startsWith('..' + sep) || realRel === '..' || isAbsolute(realRel)) {
+                throw invalidPathError(recordPath, 'escapes project root via symlink');
+            }
+            return canonicalRecord;
+        }
+        catch {
+            return recordPath;
+        }
     }
     const realRel = relative(realRoot, realRecord);
     if (realRel.startsWith('..' + sep) || realRel === '..' || isAbsolute(realRel)) {

package/dist/services/skill/skill-search-service.d.ts

@@ -32,14 +32,14 @@ export declare const SkillSearchInputSchema: z.ZodObject<{
         status: "status";
         resume: "resume";
         audit: "audit";
-        ide: "ide";
+        "final-review": "final-review";
         content: "content";
+        ide: "ide";
         test: "test";
-        research: "research";
         doctor: "doctor";
+        research: "research";
         triage: "triage";
         sop: "sop";
-        "final-review": "final-review";
         "slice-decompose": "slice-decompose";
         "issue-fix-orchestrator": "issue-fix-orchestrator";
         "perf-audit": "perf-audit";

package/dist/services/standards/loop-engineering-lint.d.ts

@@ -18,7 +18,7 @@
  * `peaks standards lint --category loop-engineering` (registered in M0's
  * plan) will read this file from disk and call this function.
  */
-export declare const EXPECTED_RED_LINE_IDS: readonly ["RL-0", "RL-1", "RL-2", "RL-3", "RL-4", "RL-5", "RL-6", "RL-7", "RL-8", "RL-9"];
+export declare const EXPECTED_RED_LINE_IDS: readonly ["RL-0", "RL-1", "RL-2", "RL-3", "RL-4", "RL-5", "RL-6", "RL-7", "RL-8", "RL-9", "RL-10"];
 export type RedLineId = (typeof EXPECTED_RED_LINE_IDS)[number];
 export declare const REQUIRED_SECTIONS: readonly ["Failure modes", "Rewrite", "Self-check", "Out-of-scope"];
 export type RedLineSection = (typeof REQUIRED_SECTIONS)[number];

package/dist/services/standards/loop-engineering-lint.js

@@ -29,6 +29,12 @@ export const EXPECTED_RED_LINE_IDS = [
     'RL-7',
     'RL-8',
     'RL-9',
+    // RL-10 was written into the guideline file (its 4 sections included) but
+    // never added here, so the lint could not see it: the closed set stopped one
+    // short of the file it was supposed to police. The file's own footer said
+    // "Total red lines: 9 (RL-0..RL-9)" while RL-10 sat below it — the two
+    // statements contradicted each other and only the file was ever read.
+    'RL-10',
 ];
 export const REQUIRED_SECTIONS = [
     'Failure modes',

package/dist/services/web/daemon-registry.js

@@ -5,10 +5,29 @@
  * WRITE goes through `assertUnder` first — the slice-wide guard against an
  * artifact escaping `<root>/.peaks/_runtime/<sid>/web/` (AC1).
  */
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { assertUnder, webDaemonDir, webDaemonInfoPath, webSpawnLockPath } from './web-artifact-paths.js';
 import { parseDaemonInfo } from './web-protocol.js';
+/**
+ * Canonicalize through symlinks so two paths that name the same directory through
+ * different prefixes compare equal — the macOS `/var` <-> `/private/var` quirk
+ * makes `mkdtempSync(...)` return `/var/folders/...` while `process.cwd()` after
+ * `chdir` returns `/private/var/folders/...`. They are the same directory on
+ * disk; without `realpathSync` the ownership check below silently rejects a
+ * legitimate record and the CLI cold-starts a real daemon instead of reusing
+ * the stub. Falls back to `resolve()` when the path is absent: a planted
+ * record naming a directory that does not exist still has to fail the
+ * containment test, and a `realpathSync` on it would throw.
+ */
+function safeRealpath(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
 /** A spawn lock older than this is reclaimed even if its owner pid is alive. */
 const SPAWN_LOCK_STALE_MS = 120_000;
 /**
@@ -46,7 +65,13 @@ export function readDaemonInfo(projectRoot, sessionId) {
     }
     try {
         const info = parseDaemonInfo(readFileSync(target, 'utf8'));
-        if (info === null || info.projectRoot !== projectRoot || info.sessionId !== sessionId) {
+        if (info === null || info.sessionId !== sessionId) {
+            return null;
+        }
+        // Canonicalize both sides — a record written from one prefix (say
+        // `/var/folders/...`) and read from the canonical one (`/private/var/...`)
+        // describes the same project on macOS.
+        if (safeRealpath(info.projectRoot) !== safeRealpath(projectRoot)) {
             return null;
         }
         return info;

package/dist/services/workspace/claude-settings-template.d.ts

@@ -2,24 +2,31 @@
  * Slice 2.0.1-bug3-fact-forcing-bypass — pure-data template for the
  * consumer-project `.claude/settings.local.json` file.
  *
- * The template is a PreToolUse hook allow-list that bypasses the
- * Claude Code [Fact-Forcing Gate] for tool calls whose paths target
- * the peaks-managed `.peaks/` workspace. Without this bypass,
- * `peaks workspace init` (Step 0 of every peaks-code session) is
- * unrunnable in a consumer project because the gate blocks the very
- * first Write.
+ * The template exempts the peaks-managed `.peaks/` workspace from the
+ * Claude Code [Fact-Forcing Gate], so `peaks workspace init` (Step 0 of
+ * every peaks-code session) is runnable in a consumer project — without
+ * the exemption the gate blocks the very first Write.
+ *
+ * The exemption is declared in the `env` block
+ * (`EXTERNAL_GATE_EXEMPT_ENV`), which is what the gate actually reads.
+ * TEMPLATE_VERSION 1.7.0 moved it there; before that it was declared by a
+ * `Write|Edit|MultiEdit` handler that exited non-zero for non-`.peaks/`
+ * paths and was documented as "fall through to the gate". That concept does
+ * not exist in the Claude Code hook protocol (only exit 2 blocks; any other
+ * non-zero exit is a NON-BLOCKING ERROR reported once per edit), so the
+ * handler was corrected to abstain on every path — and an abstaining handler
+ * that is still INSTALLED is a no-op carrying a machine-specific absolute
+ * script path. TEMPLATE_VERSION 1.8.0 removed it rather than re-point it:
+ * it decided nothing, and the exemption it was written for lives in `env`.
  *
  * The template is a pure-data function (no filesystem, no clock) so
  * it can be unit-tested in isolation and so the on-disk file matches
  * the in-memory template byte-for-byte.
  *
- * One matcher is emitted:
- *   1. `Write|Edit|MultiEdit` — a `node <script>` handler that runs the
- *      path gate shipped at `src/services/hooks/write-gate.js`. Exits 0
- *      (allow) for the paths the gate skips, exit 1 (deny → fall through to
- *      gate) for everything else. TEMPLATE_VERSION 1.6.0 moved the decision
- *      out of an inlined `node -e "<js>"` one-liner, whose escaping was
- *      bash-specific and therefore could not take a platform `shell` pin.
+ * 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`.
  *
  * The previous `Bash` matcher (which whitelisted a fixed `peaks
  * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
@@ -80,8 +87,20 @@ export declare const CLAUDE_SETTINGS_LOCAL_FILENAME = ".claude/settings.local.js
  *           (`EXTERNAL_GATE_EXEMPT_ENV`). The comparator now requires the
  *           on-disk file to declare those exemptions too, so a project
  *           installed by an earlier release refreshes once and converges.
+ *   1.8.0 — REMOVED the `Write|Edit|MultiEdit` handler and the shipped
+ *           script it invoked (`src/services/hooks/write-gate.js`, also
+ *           deleted). The handler abstained on every path by design (see
+ *           that file's header for the rationale — it is the reason this
+ *           is a deletion and not a repair), so the only things it still
+ *           contributed were a `node "<abs path>"` command pinned to the
+ *           Node version directory that happened to be on `$PATH` at
+ *           install time, and a `shell: powershell` pin. The exemption it
+ *           was written to provide is declared by the `env` block above.
+ *           `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.
  */
-export declare const TEMPLATE_VERSION = "1.7.0";
+export declare const TEMPLATE_VERSION = "1.8.0";
 /**
  * Compare two serialized template strings: does the on-disk file already
  * declare every entry the generated tree declares?
@@ -108,10 +127,11 @@ export declare const TEMPLATE_VERSION = "1.7.0";
  * detail).
  *
  * Returns `true` iff both strings parse to objects whose `hooks.PreToolUse`
- * arrays satisfy that containment 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).
+ * 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
@@ -147,23 +167,18 @@ export declare function templateContentMatches(generated: string, onDisk: string
  * 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 declare function mergeTemplateOwnedHooks(onDisk: ReadonlyArray<unknown>, template: ReadonlyArray<unknown>): unknown[];
-/**
- * Absolute path of the shipped Write|Edit|MultiEdit gate script.
- *
- * `write-gate.js` is a plain `.js` (not a compiled `.ts`) precisely so this
- * single relative filename resolves in BOTH trees: `src/services/hooks/` for
- * `tsx` / vitest, `dist/services/hooks/` for an installed consumer (copied by
- * `scripts/copy-templates.mjs`; the `dist/**` `*.js` glob in
- * `package.json#files` already ships it).
- *
- * Separators are normalized to `/` so the emitted command contains no
- * backslash at all. That is what makes the handler shell-agnostic: bash
- * reduces `\X` inside `"..."` and PowerShell escapes with a backtick, so any
- * backslash in the string is one dialect's problem waiting to happen.
- */
-export declare function writeGateScriptPath(): string;
+export declare function isRetiredTemplateEntry(entry: unknown): boolean;
 type ClaudeHookCommand = {
     type: 'command';
     command: string;
@@ -192,10 +207,11 @@ type ClaudeSettingsLocal = {
  * forcing gate is a core feature that PreToolUse hooks can short-
  * circuit but that the `permissions` block cannot.
  *
- * As of TEMPLATE_VERSION 1.2.0, only the `Write|Edit|MultiEdit`
- * matcher is emitted. Bash command enforcement is the responsibility
- * of `peaks gate enforce`, which `peaks hooks install` injects into
- * `.claude/settings.json` (not `.claude/settings.local.json`).
+ * 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`.
  */
 export declare function buildClaudeSettingsLocalJson(): ClaudeSettingsLocal;
 export {};

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

@@ -2,24 +2,31 @@
  * Slice 2.0.1-bug3-fact-forcing-bypass — pure-data template for the
  * consumer-project `.claude/settings.local.json` file.
  *
- * The template is a PreToolUse hook allow-list that bypasses the
- * Claude Code [Fact-Forcing Gate] for tool calls whose paths target
- * the peaks-managed `.peaks/` workspace. Without this bypass,
- * `peaks workspace init` (Step 0 of every peaks-code session) is
- * unrunnable in a consumer project because the gate blocks the very
- * first Write.
+ * The template exempts the peaks-managed `.peaks/` workspace from the
+ * Claude Code [Fact-Forcing Gate], so `peaks workspace init` (Step 0 of
+ * every peaks-code session) is runnable in a consumer project — without
+ * the exemption the gate blocks the very first Write.
+ *
+ * The exemption is declared in the `env` block
+ * (`EXTERNAL_GATE_EXEMPT_ENV`), which is what the gate actually reads.
+ * TEMPLATE_VERSION 1.7.0 moved it there; before that it was declared by a
+ * `Write|Edit|MultiEdit` handler that exited non-zero for non-`.peaks/`
+ * paths and was documented as "fall through to the gate". That concept does
+ * not exist in the Claude Code hook protocol (only exit 2 blocks; any other
+ * non-zero exit is a NON-BLOCKING ERROR reported once per edit), so the
+ * handler was corrected to abstain on every path — and an abstaining handler
+ * that is still INSTALLED is a no-op carrying a machine-specific absolute
+ * script path. TEMPLATE_VERSION 1.8.0 removed it rather than re-point it:
+ * it decided nothing, and the exemption it was written for lives in `env`.
  *
  * The template is a pure-data function (no filesystem, no clock) so
  * it can be unit-tested in isolation and so the on-disk file matches
  * the in-memory template byte-for-byte.
  *
- * One matcher is emitted:
- *   1. `Write|Edit|MultiEdit` — a `node <script>` handler that runs the
- *      path gate shipped at `src/services/hooks/write-gate.js`. Exits 0
- *      (allow) for the paths the gate skips, exit 1 (deny → fall through to
- *      gate) for everything else. TEMPLATE_VERSION 1.6.0 moved the decision
- *      out of an inlined `node -e "<js>"` one-liner, whose escaping was
- *      bash-specific and therefore could not take a platform `shell` pin.
+ * 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`.
  *
  * The previous `Bash` matcher (which whitelisted a fixed `peaks
  * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
@@ -33,8 +40,6 @@
  * consumer project's `.claude/settings.json` and which exits 0
  * silently for any command not guarded by a registered SOP gate.
  */
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { EXTERNAL_GATE_EXEMPT_ENV, hasExternalGateExemptions, resolveHookShell, resolveHookSpec } from '../skills/hooks-codegate-superpowers.js';
 export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
 /**
@@ -83,8 +88,20 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
  *           (`EXTERNAL_GATE_EXEMPT_ENV`). The comparator now requires the
  *           on-disk file to declare those exemptions too, so a project
  *           installed by an earlier release refreshes once and converges.
+ *   1.8.0 — REMOVED the `Write|Edit|MultiEdit` handler and the shipped
+ *           script it invoked (`src/services/hooks/write-gate.js`, also
+ *           deleted). The handler abstained on every path by design (see
+ *           that file's header for the rationale — it is the reason this
+ *           is a deletion and not a repair), so the only things it still
+ *           contributed were a `node "<abs path>"` command pinned to the
+ *           Node version directory that happened to be on `$PATH` at
+ *           install time, and a `shell: powershell` pin. The exemption it
+ *           was written to provide is declared by the `env` block above.
+ *           `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.
  */
-export const TEMPLATE_VERSION = '1.7.0';
+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?
@@ -111,10 +128,11 @@ export const TEMPLATE_VERSION = '1.7.0';
  * detail).
  *
  * Returns `true` iff both strings parse to objects whose `hooks.PreToolUse`
- * arrays satisfy that containment 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).
+ * 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
@@ -151,6 +169,23 @@ export function templateContentMatches(generated, onDisk) {
         }
         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
@@ -184,6 +219,15 @@ export function templateContentMatches(generated, onDisk) {
  * 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();
@@ -195,6 +239,10 @@ export function mergeTemplateOwnedHooks(onDisk, template) {
     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);
@@ -249,44 +297,36 @@ function sameHooksArray(a, b) {
     return true;
 }
 /**
- * This module's own directory — `<root>/src/services/workspace` in the
- * source tree, `<root>/dist/services/workspace` in a build.
- *
- * Anchored on the running module rather than on `process.argv[1]`: the
- * same reason `daemon-supervisor.ts` documents — `argv[1]` is a different
- * file in each way the CLI is entered (`bin/peaks.js`, `src/cli/index.ts`
- * under tsx, `dist/cli/index.js` when invoked directly), whereas the
- * module's own location is the one fact that is always true.
- */
-const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
-/**
- * Absolute path of the shipped Write|Edit|MultiEdit gate script.
- *
- * `write-gate.js` is a plain `.js` (not a compiled `.ts`) precisely so this
- * single relative filename resolves in BOTH trees: `src/services/hooks/` for
- * `tsx` / vitest, `dist/services/hooks/` for an installed consumer (copied by
- * `scripts/copy-templates.mjs`; the `dist/**` `*.js` glob in
- * `package.json#files` already ships it).
+ * The retired `Write|Edit|MultiEdit` gate entry, as an on-disk file written by
+ * a pre-1.8.0 release holds it.
  *
- * Separators are normalized to `/` so the emitted command contains no
- * backslash at all. That is what makes the handler shell-agnostic: bash
- * reduces `\X` inside `"..."` and PowerShell escapes with a backtick, so any
- * backslash in the string is one dialect's problem waiting to happen.
- */
-export function writeGateScriptPath() {
-    return resolve(MODULE_DIR, '..', 'hooks', 'write-gate.js').replaceAll('\\', '/');
-}
-/**
- * Build the Write|Edit|MultiEdit matcher command.
+ * 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.
  *
- * TEMPLATE_VERSION 1.6.0: `node "<script>"` with NO inline payload. The
- * decision lives in `src/services/hooks/write-gate.js` and was relocated
- * there verbatim. Because there is nothing left to escape, this handler is
- * shell-dialect-independent and can carry the same platform `shell` pin as
- * its Bash siblings (see `resolveHookShell`).
+ * 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.
  */
-function buildWriteHookCommand() {
-    return `node "${writeGateScriptPath()}"`;
+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);
 }
 /**
  * TEMPLATE_VERSION 1.4.0 — the SOP gate-enforce handler, read from the same
@@ -311,39 +351,22 @@ 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.2.0, only the `Write|Edit|MultiEdit`
- * matcher is emitted. Bash command enforcement is the responsibility
- * of `peaks gate enforce`, which `peaks hooks install` injects into
- * `.claude/settings.json` (not `.claude/settings.local.json`).
+ * 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`.
  */
 export function buildClaudeSettingsLocalJson() {
-    // TEMPLATE_VERSION 1.6.0 — the write handler can now be shell-pinned for the
-    // same Windows reason as the two Bash handlers below: a shell-form command is
-    // executed by Git Bash / MSYS2, which force-allocates a console window on
-    // every matching tool call. It could NOT take the pin while its payload was
-    // inlined JavaScript, because PowerShell does not perform bash's backslash
-    // reduction and would have corrupted the payload. `undefined` on POSIX omits
-    // the key entirely.
-    const writeShell = resolveHookShell();
     return {
-        // Slice emit-gateguard-exemption — the third-party gate exemption. Peaks
-        // already bypasses its OWN fact-forcing gate for `.peaks/**` (the
-        // Write|Edit|MultiEdit handler below); this is the same intent declared in
-        // the currency an external PreToolUse gate reads. `peaks hooks install`
-        // merges the same row into this file, so the two writers agree.
+        // Slice emit-gateguard-exemption — the third-party gate exemption. This is
+        // now the ONLY mechanism carrying the `.peaks/**` bypass (TEMPLATE_VERSION
+        // 1.8.0 removed the abstaining `Write|Edit|MultiEdit` handler that used to
+        // be described here). `peaks hooks install` merges the same row into this
+        // file, so the two writers agree.
         env: { ...EXTERNAL_GATE_EXEMPT_ENV },
         hooks: {
             PreToolUse: [
-                {
-                    matcher: 'Write|Edit|MultiEdit',
-                    hooks: [
-                        {
-                            type: 'command',
-                            command: buildWriteHookCommand(),
-                            ...(writeShell !== undefined ? { shell: writeShell } : {})
-                        }
-                    ]
-                },
                 {
                     // v3.1.2 Step 0.8 — Mechanical PreToolUse gate. Runs
                     // `peaks code gate-step-08 --project .` before every Bash
@@ -351,7 +374,6 @@ export function buildClaudeSettingsLocalJson() {
                     // describing the decision + optional `Next: slice #N+1 of
                     // M (<currentSlice>)` line when progress.json exists). Exit
                     // 2 = block (stderr contains the BLOCKED: ... reason).
-                    // The existing Write|Edit|MultiEdit matcher is preserved.
                     matcher: 'Bash',
                     hooks: [buildBashGateStep08Handler()]
                 },