peaks-loop 4.0.47 → 4.0.49

package/dist/services/workflow/pipeline-verify-service.js

@@ -5,7 +5,7 @@
  * returns a structured `PipelineVerification` envelope. Type
  * declarations live in `pipeline-verify-types.ts`; private gate
  * helpers (`rdGatesForType`, `qaGatesForType`, `extractState`,
- * `findRequestFile`, the `_runtime/` prefix strip, the RD/QA handoff
+ * `findRequestFile`, the RD/QA handoff
  * state sets, and the RD/QA evidence path probes) live in
  * `pipeline-verify-gate-support.ts`. The re-export shim at the
  * bottom preserves the original public surface so existing import
@@ -16,7 +16,7 @@
 import { isRequestType } from '../artifacts/artifact-prerequisites.js';
 import { readSkipState } from './workflow-state-store.js';
 import { getSessionIdCanonical } from '../session/session-manager.js';
-import { listUnpromotedFeedback } from '../feedback/feedback-promotion-service.js';
+import { listPromotionExempt, listUnpromotedFeedback } from '../feedback/feedback-promotion-service.js';
 import { QA_COMPLETE_STATES, RD_QA_HANDOFF_STATES, extractState, findRequestFile, qaGatesForType, rdGatesForType, resolveQaEvidencePaths, resolveRdEvidencePaths } from './pipeline-verify-gate-support.js';
 export async function verifyPipeline(options) {
     const requestType = isRequestType(options.requestType ?? '') ? options.requestType : 'feature';
@@ -96,7 +96,7 @@ export async function verifyPipeline(options) {
     // to `options.rid` would make every missing-evidence path look like
     // a per-rid scope dir.
     const rdEvidenceDir = resolvedChangeId || options.sessionId || getSessionIdCanonical(options.projectRoot) || options.rid;
-    const rdTracker = resolveRdEvidencePaths(rdGates, rdEvidenceDir, options.projectRoot, violations, nextActions, { anyEvidenceResolved: false, allResolvedPathsCanonical: true });
+    const rdTracker = resolveRdEvidencePaths(rdGates, rdEvidenceDir, options.projectRoot, options.rid, requestType, violations, nextActions, { anyEvidenceResolved: false, allResolvedPathsCanonical: true });
     // Check if RD reached qa-handoff
     if (rdInvoked && !RD_QA_HANDOFF_STATES.has(rdState)) {
         violations.push(`RD not ready for QA: state is "${rdState}" — must reach "qa-handoff" (unit tests, karpathy-guidelines §1 Think / §2 Simplicity / §3 Surgical / §4 Goal-Driven, code review, security review complete)`);
@@ -118,16 +118,11 @@ export async function verifyPipeline(options) {
         nextActions.push('Invoke Skill(skill="peaks-qa") with the request-id for functional/performance/security testing');
         qaGates[0].detail = 'not found';
     }
-    // Check QA evidence files.
-    // v2.18.1 bug #5 fix: when no RD/QA artifact is on disk yet
-    // (resolvedChangeId is empty), fall back to the current session id
-    // from the binding-store instead of `rdEvidenceDir` (= the rid). The
-    // session axis `.peaks/_runtime/<sessionId>/qa/...` is the canonical
-    // v2.17.0 home; the legacy `_runtime/change/<sessionId>/qa/...` probe
-    // should only fire for pre-v2.17.0 workspaces, not as a default for
-    // new requests.
-    const changeIdForResolver = resolvedChangeId || getSessionIdCanonical(options.projectRoot) || rdEvidenceDir;
-    const qaTracker = resolveQaEvidencePaths(qaGates, options.projectRoot, rdEvidenceDir, changeIdForResolver, options.rid, violations, nextActions, rdTracker);
+    // Check QA evidence files. (The v2.18.1 bug #5 `changeIdForResolver`
+    // fallback — current session id when no RD/QA artifact is on disk yet —
+    // was dropped by rid 2026-09-14-verify-pipeline-contract-drift along with
+    // the security/perf findings branch that was its only consumer.)
+    const qaTracker = resolveQaEvidencePaths(qaGates, options.projectRoot, rdEvidenceDir, requestType, options.rid, violations, nextActions, rdTracker);
     const anyEvidenceResolved = qaTracker.anyEvidenceResolved;
     const allResolvedPathsCanonical = qaTracker.allResolvedPathsCanonical;
     // Check if QA reached verdict-issued
@@ -183,10 +178,12 @@ export async function verifyPipeline(options) {
     }
     // Slice 002 (v2.15.0) AC-3 — Gate H "feedback-promotion". Scans
     // `.peaks/memory/*.md` for `metadata.type === 'feedback'` entries
-    // without a promotion marker (HTML comment or `.promotion.json`
-    // sidecar). When any unpromoted feedback is found, the gate fails
-    // and the pipeline does not complete until the user promotes via
-    // `peaks feedback promote <memory-file> --layer <A|B|C>`.
+    // that lack a promotion marker (HTML comment or `.promotion.json`
+    // sidecar) OR whose marker is not backed by the layer's artifact
+    // (rid 2026-09-14-gate-h-promotion). When any such feedback is
+    // found, the gate fails and the pipeline does not complete until the
+    // user promotes via `peaks feedback promote <memory-file> --layer
+    // <A|B|C>` — which now produces the artifact, not just the marker.
     //
     // The scan is intentionally non-throwing — a missing or unreadable
     // memory dir is treated as "no feedback found, gate passes" so
@@ -201,14 +198,25 @@ export async function verifyPipeline(options) {
     ];
     try {
         const unpromoted = listUnpromotedFeedback({ projectRoot: options.projectRoot });
+        // rid 2026-09-14-gate-h-promotion (classify slice): memories that declare
+        // themselves out of the gate are reported, never dropped. An exemption the
+        // gate does not show would be indistinguishable from a fixed violation.
+        const exempt = listPromotionExempt({ projectRoot: options.projectRoot });
+        const exemptNote = exempt.length === 0
+            ? ''
+            : `; ${exempt.length} declared not-to-be-promoted: ${exempt.map((e) => `${e.name} (${e.code})`).join('; ')}`;
         if (unpromoted.length === 0) {
             feedbackGates[0].passed = true;
-            feedbackGates[0].detail = `0 unpromoted feedback memories in .peaks/memory/`;
+            feedbackGates[0].detail = `0 unpromoted feedback memories in .peaks/memory/${exemptNote}`;
         }
         else {
-            feedbackGates[0].detail = `${unpromoted.length} unpromoted feedback memor${unpromoted.length === 1 ? 'y' : 'ies'}: ${unpromoted.map((u) => u.name).join(', ')}`;
-            violations.push(`Gate H feedback-promotion FAILED: ${unpromoted.length} feedback memor${unpromoted.length === 1 ? 'y is' : 'ies are'} not yet promoted to an enforcement layer (${unpromoted.map((u) => u.name).join(', ')}). Run \`peaks feedback promote <memory-file> --layer <A|B|C>\` for each. See sops/feedback-promotion-sop.md.`);
-            nextActions.push(`Run \`peaks feedback promote <memory-file> --layer <A|B|C>\` for each unpromoted feedback memory to satisfy Gate H.`);
+            // rid 2026-09-14-gate-h-promotion: the gate no longer passes on a marker
+            // alone. `listUnpromotedFeedback` now also reports markers whose layer
+            // artifact is absent, so `unpromoted` mixes "never promoted" with
+            // "promoted on paper only" — the reason on each entry says which.
+            feedbackGates[0].detail = `${unpromoted.length} feedback memor${unpromoted.length === 1 ? 'y' : 'ies'} without a backed promotion: ${unpromoted.map((u) => `${u.name} (${u.reason})`).join('; ')}${exemptNote}`;
+            violations.push(`Gate H feedback-promotion FAILED: ${unpromoted.length} feedback memor${unpromoted.length === 1 ? 'y is' : 'ies are'} not yet promoted to an enforcement layer with a real artifact (${unpromoted.map((u) => u.name).join(', ')})${exemptNote}. A marker alone does not count: layer A needs a registered SOP manifest, layer B a hook command that runs something named after the rule in .peaks/.claude-settings-template.json, layer C a hard-floor category in src/services/code/mode-gate.ts. Run \`peaks feedback promote <memory-file> --layer <A|B|C>\` for each and read what it reports. See sops/feedback-promotion-sop.md.`);
+            nextActions.push(`Run \`peaks feedback promote <memory-file> --layer <A|B|C>\` for each feedback memory without a backed promotion to satisfy Gate H.`);
         }
     }
     catch {
@@ -225,20 +233,26 @@ export async function verifyPipeline(options) {
     const complete = rdInvoked && qaInvoked && allRdGatesPassed && allQaGatesPassed && allFeedbackGatesPassed
         && RD_QA_HANDOFF_STATES.has(rdState) && QA_COMPLETE_STATES.has(qaState);
     // Slice 025 — derive the `acceptedForm` and `gateC` verdict. The form is
-    // 'suffixed' if both the security + perf gates passed via the new
-    // per-rid path; 'legacy' if either was consumed via the legacy fallback;
-    // 'none' if neither passed.
-    const secGate = qaGates.find((g) => g.name === 'security-findings');
-    const perfGate = qaGates.find((g) => g.name === 'performance-findings');
-    const secForm = secGate?.detail?.includes(`-${options.rid}.md`) ? 'suffixed' : 'legacy';
-    const perfForm = perfGate?.detail?.includes(`-${options.rid}.md`) ? 'suffixed' : 'legacy';
+    // 'suffixed' when the contract's current path served the file and 'legacy'
+    // when the deprecated fallback did; 'none' if neither gate passed.
+    //
+    // rid 2026-09-14-verify-pipeline-contract-drift: the two gates moved from the
+    // QA phase to the RD phase, because that is where the current contract puts
+    // the evidence (`AUDIT_SECURITY` / `AUDIT_PERF` at `rd:qa-handoff`). The
+    // `-<rid>.md` suffix that used to distinguish the forms is a real one again
+    // after slice `2026-09-14-audit-artifact-rid-scoping` rid-scoped the audit
+    // paths; the resolver marks which form served the file with
+    // `[LEGACY_EVIDENCE_PATH]`.
+    const secGate = rdGates.find((g) => g.name === 'security-review');
+    const perfGate = rdGates.find((g) => g.name === 'perf-baseline');
+    const formOf = (gate) => gate?.passed === true && !gate.detail.includes('LEGACY_EVIDENCE_PATH') ? 'suffixed' : 'legacy';
+    const secForm = formOf(secGate);
+    const perfForm = formOf(perfGate);
     const acceptedForm = !secGate?.passed && !perfGate?.passed
         ? 'none'
-        : (secForm === 'suffixed' && perfForm === 'suffixed')
-            ? 'suffixed'
-            : (secForm === 'legacy' || perfForm === 'legacy')
-                ? 'legacy'
-                : 'suffixed';
+        : (secForm === 'legacy' || perfForm === 'legacy')
+            ? 'legacy'
+            : 'suffixed';
     const gateC = allQaGatesPassed ? 'pass' : 'fail';
     const gateH = allFeedbackGatesPassed ? 'pass' : 'fail';
     // Slice 2026-06-28-code-mode-bypass-fix (defect #3): `true` when

package/dist/services/workflow/pipeline-verify-types.d.ts

@@ -50,18 +50,27 @@ export type PipelineVerification = {
      * Slice 002 (v2.15.0) AC-3: Gate H "feedback-promotion". Always
      * present (single-element array). Evaluates whether every
      * `metadata.type === 'feedback'` memory in `.peaks/memory/`
-     * carries a promotion marker (comment OR sidecar). Failures
-     * block the `complete` verdict via the `gateH` field below; the
-     * pipeline only completes when every gate in this array passes.
+     * carries a promotion marker (comment OR sidecar) AND whether the
+     * layer that marker claims is actually backed by its artifact
+     * (rid 2026-09-14-gate-h-promotion). Failures block the `complete`
+     * verdict via the `gateH` field below; the pipeline only completes
+     * when every gate in this array passes.
      */
     feedbackPhase?: {
         gates: PipelineGate[];
     };
     violations: string[];
     nextActions: string[];
-    /** Form of the security/performance findings artifacts Gate C accepted
-     * (slice 025). `'suffixed'` for the new per-rid form, `'legacy'` for the
-     * pre-slice-025 non-suffixed form, `'none'` when neither was found. */
+    /** Form of the security/performance evidence the RD gates accepted
+     * (slice 025). `'suffixed'` when the current contract's path served the
+     * file, `'legacy'` when a deprecated fallback did, `'none'` when neither
+     * gate passed. The per-rid `<rid>.md` suffix the union was named after was
+     * retired with `qa/security-findings-<rid>.md` (v2.11.0 D1/D4); the evidence
+     * now lives at `audit/security-<rid>.md` / `audit/perf-<rid>.md`
+     * (rid-scoped since slice `2026-09-14-audit-artifact-rid-scoping`) with
+     * `audit/security.md` / `audit/perf.md` and
+     * `rd/security-review.md` / `rd/perf-baseline.md` as the declared legacy
+     * fallbacks (rid 2026-09-14-verify-pipeline-contract-drift). */
     acceptedForm?: 'suffixed' | 'legacy' | 'none';
     /** `gateC` is the pre-computed verdict string (AC7 dogfood shape). */
     gateC?: 'pass' | 'fail';

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

@@ -83,15 +83,35 @@ export declare const CLAUDE_SETTINGS_LOCAL_FILENAME = ".claude/settings.local.js
  */
 export declare const TEMPLATE_VERSION = "1.7.0";
 /**
- * Compare two serialized template strings for semantic equivalence: does the
- * on-disk file already declare everything the generated template declares?
+ * Compare two serialized template strings: does the on-disk file already
+ * declare every entry the generated tree declares?
  *
- * Returns `true` iff both strings parse to objects whose
- * `hooks.PreToolUse` arrays are structurally identical (same length;
- * each entry's `matcher`, `hooks[].type`, `hooks[].command` match) 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).
+ * OWNERSHIP IS PER ENTRY, NOT PER KEY (rid 2026-09-13-two-decisions item ②).
+ * 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 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
@@ -101,6 +121,34 @@ export declare const TEMPLATE_VERSION = "1.7.0";
  * refresh a stale `.peaks/.claude-settings-template.json` on disk.
  */
 export declare function templateContentMatches(generated: string, onDisk: string): boolean;
+/**
+ * Merge the on-disk `hooks.PreToolUse` list with the template's.
+ *
+ * THE OWNERSHIP RULE (rid 2026-09-13-two-decisions item ②): this template owns
+ * 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.
+ */
+export declare function mergeTemplateOwnedHooks(onDisk: ReadonlyArray<unknown>, template: ReadonlyArray<unknown>): unknown[];
 /**
  * Absolute path of the shipped Write|Edit|MultiEdit gate script.
  *

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

@@ -86,15 +86,35 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
  */
 export const TEMPLATE_VERSION = '1.7.0';
 /**
- * Compare two serialized template strings for semantic equivalence: does the
- * on-disk file already declare everything the generated template declares?
+ * Compare two serialized template strings: does the on-disk file already
+ * declare every entry the generated tree declares?
  *
- * Returns `true` iff both strings parse to objects whose
- * `hooks.PreToolUse` arrays are structurally identical (same length;
- * each entry's `matcher`, `hooks[].type`, `hooks[].command` match) 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).
+ * OWNERSHIP IS PER ENTRY, NOT PER KEY (rid 2026-09-13-two-decisions item ②).
+ * 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 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
@@ -121,20 +141,15 @@ export function templateContentMatches(generated, onDisk) {
     if (!isTemplateShape(parsedGenerated) || !isTemplateShape(parsedOnDisk)) {
         return false;
     }
-    const generatedEntries = parsedGenerated.hooks.PreToolUse;
-    const onDiskEntries = parsedOnDisk.hooks.PreToolUse;
-    if (generatedEntries.length !== onDiskEntries.length) {
-        return false;
-    }
-    for (let i = 0; i < generatedEntries.length; i += 1) {
-        const a = generatedEntries[i];
-        const b = onDiskEntries[i];
-        if (a.matcher !== b.matcher) {
-            return false;
-        }
-        if (!sameHooksArray(a.hooks, b.hooks)) {
+    // 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 project installed by a release that predates a template-declared
     // exemption still needs the refresh this comparator gates — otherwise the
@@ -143,6 +158,69 @@ export function templateContentMatches(generated, onDisk) {
     // 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 OWNERSHIP RULE (rid 2026-09-13-two-decisions item ②): this template owns
+ * 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.
+ */
+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) {
+        // 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;

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

@@ -13,7 +13,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { withExternalGateExemptions } from '../skills/hooks-codegate-superpowers.js';
-import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME, templateContentMatches } from './claude-settings-template.js';
+import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME, mergeTemplateOwnedHooks, templateContentMatches } from './claude-settings-template.js';
 /** Read a file as text, or `undefined` when it cannot be read. */
 function readTextIfPresent(filePath) {
     try {
@@ -48,12 +48,16 @@ function readEnvObject(serialized) {
  * The top-level keys this function's template is allowed to DECIDE. Every other
  * key on disk belongs to whoever put it there and is carried across verbatim.
  *
- *  - `hooks` — the tree this function exists to keep in sync. `peaks workspace
- *    init` is the writer that converges a consumer's file on the current
+ *  - `hooks` — the tree this function exists to keep in sync, ENTRY BY ENTRY.
+ *    `peaks workspace init` converges a consumer's file on the current
  *    release's handler set, and `templateContentMatches` (the drift detector
- *    that decides whether to rewrite at all) compares exactly this tree. Letting
- *    the disk win here would make the rewrite a no-op that reports `refreshed`
- *    forever.
+ *    that decides whether to rewrite at all) asks whether every entry the
+ *    generated tree declares is present — not whether the trees are equal.
+ *    Letting the disk win outright would make the rewrite a no-op that reports
+ *    `refreshed` forever AND would never deliver a changed handler; letting the
+ *    template win outright is what deleted the auto-compact hook. See
+ *    `mergeHooksTree` / `mergeTemplateOwnedHooks` for the rule that does
+ *    neither.
  *  - `env` — jointly owned with `peaks hooks install`, which unions the user's
  *    exemption globs into it. Handled as a union below, not by either side
  *    winning outright.
@@ -62,6 +66,35 @@ function readEnvObject(serialized) {
  * direction matters. A whitelist drops every key it was not told about — which
  * is how `permissions` was lost — whereas anything absent from this list is
  * preserved by default, including keys no release of peaks-loop knows about.
+ *
+ * ⚠️ `hooks` USED TO BE OWNED WHOLE — every entry in it was deleted by the next
+ * `peaks workspace init` unless the template declared it, silently:
+ * `templateContentMatches` saw the extra entry, answered "drifted", and the
+ * rewrite emitted `{...template}`. That was not hypothetical.
+ * `.claude/settings.local.json` has a second writer of peaks' OWN hooks:
+ * `installAutoCompactHook` (`src/services/hooks/auto-compact-hook-install.ts`),
+ * reached from `peaks code auto-compact` on an adapter declaring
+ * `compactPathway: 'ide-native'` — which `claude-code` does. Measured on a
+ * throwaway project root (rid 2026-09-13-two-decisions item ②):
+ *
+ *   init (written, 3 PreToolUse entries: Write|Edit|MultiEdit, Bash, Bash)
+ *   → installAutoCompactHook (installed, 4: … | Bash|Task)
+ *   → init again (REFRESHED, 3: … )   ← the Bash|Task entry is gone
+ *
+ * and nothing re-installs it: the hook's whole job was to fire on the next
+ * Bash/Task call, so once it is deleted the auto-compact contract stops
+ * silently.
+ *
+ * FIXED 2026-09-13 (user-decided): this template now owns only the entries IT
+ * DECLARES. `mergeHooksTree` below unions the rest of the on-disk `hooks` tree
+ * across verbatim, and `templateContentMatches` — the drift detector — was
+ * changed in the same slice from "the trees are identical" to "every entry the
+ * generated tree declares is present". The two halves are one change: the merge
+ * alone would leave the comparator comparing a 3-entry generated tree against a
+ * 4-entry file on EVERY init and reporting `refreshed` forever, which is the
+ * state whole-key ownership existed to prevent. See
+ * `mergeTemplateOwnedHooks` in `claude-settings-template.ts` for the ownership
+ * rule and `templateContentMatches` for the containment rule it implies.
  */
 const TEMPLATE_OWNED_KEYS = new Set(['hooks', 'env']);
 /** `template`'s own keys, then every on-disk key the template does not own. */
@@ -72,8 +105,34 @@ function carryUserOwnedKeys(onDisk, template) {
             continue;
         merged[key] = value;
     }
+    merged.hooks = mergeHooksTree(onDisk.hooks, template.hooks);
     return merged;
 }
+/**
+ * Merge the on-disk `hooks` tree with the template's, one event at a time.
+ *
+ * Only the events the template DECLARES are merged (and only their declared
+ * entries — see `mergeTemplateOwnedHooks`); every other event, and every other
+ * key under `hooks`, is carried across from the disk untouched. The template
+ * currently declares `PreToolUse` alone, so this is what keeps a hand-added or
+ * future-installer `SessionStart` entry in this file instead of deleting it —
+ * the latent half of the hazard the header describes.
+ */
+function mergeHooksTree(onDiskHooks, templateHooks) {
+    const onDisk = isPlainRecord(onDiskHooks) ? { ...onDiskHooks } : {};
+    const template = isPlainRecord(templateHooks) ? templateHooks : {};
+    for (const [event, declared] of Object.entries(template)) {
+        const current = onDisk[event];
+        onDisk[event] = Array.isArray(declared)
+            ? mergeTemplateOwnedHooks(Array.isArray(current) ? current : [], declared)
+            : declared;
+    }
+    return onDisk;
+}
+/** A JSON object, as opposed to a null / array / primitive. */
+function isPlainRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 /**
  * The peaks-managed snippet appended to the consumer project's
  * `.peaks/.gitignore` so the local-only settings file never lands
@@ -213,6 +272,17 @@ export async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks)
  * Returns the action taken so the caller can surface it in the
  * envelope. Read failures are treated as drift so a malformed
  * on-disk file always self-heals on the next init.
+ *
+ * WHAT IS COMPARED (rid 2026-09-13-two-decisions item ②): the copy is checked
+ * against the TEMPLATE'S OWN entries — `buildClaudeSettingsLocalJson()` — not
+ * against `serialized`, the merged LOCAL file content it is written from. This
+ * file is a copy of the template (its name and this doc both say so), so
+ * "is it current?" is a question about the template's entries only; asking it
+ * against the merged local file made the copy report `refreshed` once for every
+ * entry another writer had added to `.claude/settings.local.json` — drift noise
+ * about a file the copy does not own, on the very init that is supposed to be a
+ * no-op. With entry-containment semantics the copy is current as soon as it
+ * declares every template entry, whatever else it carries.
  */
 async function writeOfflineTemplateCopy(projectRoot, serialized) {
     const copyPath = join(projectRoot, '.peaks', '.claude-settings-template.json');
@@ -222,7 +292,8 @@ async function writeOfflineTemplateCopy(projectRoot, serialized) {
         try {
             const { readFile } = await import('node:fs/promises');
             const existing = await readFile(copyPath, 'utf8');
-            if (templateContentMatches(serialized, existing)) {
+            const declared = JSON.stringify(buildClaudeSettingsLocalJson());
+            if (templateContentMatches(declared, existing)) {
                 action = 'already-current';
             }
             else {

package/dist/shared/runtime-root.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The one seam through which a `.peaks/_runtime` path is built.
+ *
+ * Slice 2026-09-15 (runtime-path-unrepresentable). Three attempts to *detect*
+ * a caller-supplied id reaching a runtime join all failed the same way: the
+ * shipped text rule caught 4 of 12 fixture shapes where the name-based
+ * predicate it replaced caught 8, and the version that reached 10 of 12 gave
+ * back the change that reached 12 because it cost seven findings on live code —
+ * two of them structural (a guard helper, and readers that take the guarded
+ * value as a parameter). Its measured verdict: reassignment between guard and
+ * join, and guard-after-join, are **domination failures inside a single
+ * function, invisible to any text key**.
+ *
+ * So the instrument is retired in favour of a property. The id cannot reach a
+ * runtime join unguarded because there is no longer a join that accepts an
+ * unguarded string: `RuntimeRoot.join` takes `GuardedSegment`, and a
+ * `GuardedSegment` can only be produced by `guardRuntimeSegment`, which throws
+ * on the shapes the escapes used. A newly written unguarded join is a type
+ * error at authoring time — not a removed guard that some later scan notices.
+ *
+ * The raw root is not obtainable as a string except through `dir()`, which is
+ * named so that a join written from it (`join(root.dir(), id)`) reads at review
+ * time as the bypass it is. `dir()` exists because callers legitimately
+ * enumerate the root itself; it is not a join.
+ */
+declare const RUNTIME_SEGMENT: unique symbol;
+/**
+ * A path segment that has been checked as a single safe segment.
+ *
+ * Unforgeable by construction: the brand is a `unique symbol` that is never
+ * exported, so `value as GuardedSegment` outside this module is a type error
+ * and a plain `string` is not assignable. `guardRuntimeSegment` is the only
+ * producer.
+ */
+export type GuardedSegment = string & {
+    readonly [RUNTIME_SEGMENT]: true;
+};
+/**
+ * Check a caller-supplied string and brand it for use as a runtime path
+ * segment. `label` names the id in the error the way the caller knows it
+ * ("session id", "project id"), because the throw site is one function away
+ * from the caller that supplied it.
+ *
+ * Rejects exactly the shapes `isUnsafePathInput` rejects: separators, `..`,
+ * absolute and drive-prefixed paths, UNC and URL shapes, and empty segments.
+ */
+export declare function guardRuntimeSegment(value: string, label: string): GuardedSegment;
+/**
+ * The `.peaks/_runtime` root of one project, as a capability rather than a
+ * string. `#path` is a private field, so the raw root cannot be read off the
+ * object and joined by an unguarded `join()`.
+ */
+export declare class RuntimeRoot {
+    #private;
+    private constructor();
+    /** The runtime root of `projectRoot`. */
+    static at(projectRoot: string): RuntimeRoot;
+    /**
+     * Join guarded segments onto the root. At least one segment is required: a
+     * zero-argument `join()` would hand back the bare root as a `string`, which
+     * is the capability this class exists to withhold.
+     */
+    join(first: GuardedSegment, ...rest: readonly GuardedSegment[]): string;
+    /**
+     * The root itself, for READ-only enumeration (`readdir`, `existsSync`) — not
+     * for joining. Deliberately a method rather than a property so a bypass is
+     * legible at the call site.
+     */
+    dir(): string;
+}
+/** The runtime root of `projectRoot`. */
+export declare function runtimeRoot(projectRoot: string): RuntimeRoot;
+export {};