peaks-loop 4.0.46 → 4.0.48

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/migrate-service.js

@@ -426,7 +426,7 @@ async function gitMv(from, to, projectRoot) {
         // command must be run from inside the project so it can locate
         // .git/ (the migrate target may be a temp dir created by tests).
         try {
-            execFileSync('git', ['mv', from, to], { cwd: projectRoot, stdio: 'pipe' });
+            execFileSync('git', ['mv', from, to], { cwd: projectRoot, stdio: 'pipe', windowsHide: true });
         }
         catch {
             throw error;

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 {
@@ -24,22 +24,115 @@ function readTextIfPresent(filePath) {
     }
 }
 /**
- * The `env` object of a serialized settings file, or `undefined` when the file
- * is malformed or has no `env` object. Tolerant on purpose: a bad on-disk file
- * must not stop the materialization.
+ * The parsed top-level object of a serialized settings file, or `undefined`
+ * when the file is malformed or is not a JSON object. Tolerant on purpose: a
+ * bad on-disk file must not stop the materialization.
  */
-function readEnvObject(serialized) {
+function readSettingsObject(serialized) {
     try {
         const parsed = JSON.parse(serialized);
         if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
             return undefined;
-        const env = parsed.env;
-        return typeof env === 'object' && env !== null && !Array.isArray(env) ? env : undefined;
+        return parsed;
     }
     catch {
         return undefined;
     }
 }
+/** The `env` object of a serialized settings file, or `undefined`. */
+function readEnvObject(serialized) {
+    const env = readSettingsObject(serialized)?.env;
+    return typeof env === 'object' && env !== null && !Array.isArray(env) ? env : undefined;
+}
+/**
+ * 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, 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) 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.
+ *
+ * This is deliberately an owned-key LIST and not a preserved-key whitelist: the
+ * 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. */
+function carryUserOwnedKeys(onDisk, template) {
+    const merged = { ...template };
+    for (const [key, value] of Object.entries(onDisk)) {
+        if (TEMPLATE_OWNED_KEYS.has(key))
+            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
@@ -102,8 +195,18 @@ export async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks)
     // the rewrite this function is about to do, or a refresh would silently
     // drop someone else's exemptions. The template's own row is added on top, so
     // the result is a union either way.
+    //
+    // The same argument applies to every OTHER top-level key on disk, which the
+    // rewrite used to drop wholesale: `{ ...template }` emitted only the keys the
+    // template declares, so a user's `permissions.allow`, `statusLine`, `model`,
+    // … were deleted by an init that had no opinion about them. The user's
+    // permission rules are not this function's to remove, and the removal was
+    // silent — the envelope reported only `refreshed`. See `carryUserOwnedKeys`
+    // for which keys the template still decides.
+    const onDisk = existing === undefined ? undefined : readSettingsObject(existing);
     const onDiskEnv = existing === undefined ? undefined : readEnvObject(existing);
-    const serialized = JSON.stringify(withExternalGateExemptions(onDiskEnv === undefined ? template : { ...template, env: onDiskEnv }), null, 2) + '\n';
+    const merged = onDisk === undefined ? template : carryUserOwnedKeys(onDisk, template);
+    const serialized = JSON.stringify(withExternalGateExemptions(onDiskEnv === undefined ? merged : { ...merged, env: onDiskEnv }), null, 2) + '\n';
     // Always drop (or self-heal) a copy of the template under .peaks/
     // so the --no-claude-hooks recovery flow has a known source-of-truth
     // on disk. The file is gitignored by the snippet below.
@@ -169,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');
@@ -178,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/services/workspace/workspace-service.js

@@ -6,6 +6,7 @@ import { getSessionIdCanonical, setCurrentSessionBinding, setSessionMeta } from
 import { updateCallerBindingSessionId } from '../session/caller-binding-service.js';
 import { resolveCallerProjection } from '../session/resolve-caller-id.js';
 import { normalizePath } from '../../shared/path-utils.js';
+import { assertWritableProjectRoot } from '../config/config-safety.js';
 /**
  * Slice 2026-09-10 (rid=rebind-must-update-caller-binding): repoint the
  * calling process's own per-caller binding at the session id this init just
@@ -180,6 +181,13 @@ export function validateSessionId(sessionId) {
 }
 export async function initWorkspace(options) {
     validateSessionId(options.sessionId);
+    // Before anything is created: a project tree must never be materialized into
+    // the user's home directory. `--project .` from a fresh terminal (whose cwd
+    // is `$HOME`) resolved to `$HOME` and did exactly that — `.peaks/`,
+    // `.gitignore`, `.claude/settings.local.json` and a codegraph index, all in
+    // the user's home. Enforced here as well as at the CLI so a non-CLI caller
+    // (`peaks upgrade`) cannot reach the same write by another door.
+    assertWritableProjectRoot(options.projectRoot);
     // Phase 6 refactor (slice 2026-06-05-change-id-as-unit-of-work) +
     // slice 006 (2026-06-06-change-folder-simplify-and-lazy-role-subdirs) +
     // slice 2026-06-22-top-level-change-id-cleanup (2.8.3):

package/dist/services/worktree/host-worktree-reconciler.js

@@ -11,6 +11,7 @@ export function reconcileHostWorktrees(input) {
             cwd: input.projectRoot,
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
         });
         records = parseGitWorktreePorcelain(raw);
     }

package/dist/services/worktree/long-path-cleanup.js

@@ -14,8 +14,9 @@ export function removeRegisteredWorktree(input) {
         execFileSync('git', ['worktree', 'remove', '--force', input.worktreePath], {
             cwd: input.projectRoot,
             stdio: ['ignore', 'pipe', 'pipe'],
+            windowsHide: true,
         });
-        execFileSync('git', ['worktree', 'prune'], { cwd: input.projectRoot, stdio: 'ignore' });
+        execFileSync('git', ['worktree', 'prune'], { cwd: input.projectRoot, stdio: 'ignore', windowsHide: true });
         return { removed: !existsSync(input.worktreePath), strategy: 'git' };
     }
     catch (error) {
@@ -24,7 +25,7 @@ export function removeRegisteredWorktree(input) {
         }
         try {
             rmSync(windowsLongPath(input.worktreePath), { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
-            execFileSync('git', ['worktree', 'prune'], { cwd: input.projectRoot, stdio: 'ignore' });
+            execFileSync('git', ['worktree', 'prune'], { cwd: input.projectRoot, stdio: 'ignore', windowsHide: true });
             return { removed: !existsSync(input.worktreePath), strategy: 'windows-long-path' };
         }
         catch (fallbackError) {

package/dist/shared/process.js

@@ -1,7 +1,7 @@
 import { execFile } from 'node:child_process';
 export async function execCommand(command, args, options) {
     return new Promise((resolve, reject) => {
-        execFile(command, args, { cwd: options?.cwd, env: options?.env }, (error, stdout) => {
+        execFile(command, args, { cwd: options?.cwd, env: options?.env, windowsHide: true }, (error, stdout) => {
             if (error) {
                 reject(error);
                 return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.46",
+  "version": "4.0.48",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -102,10 +102,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.31",
-    "peaks-loop-shared": "0.0.80",
-    "peaks-loop-shared-channel": "0.0.48",
-    "peaks-loop-mut": "0.1.44"
+    "peaks-loop-internal-runtime": "0.0.33",
+    "peaks-loop-shared-channel": "0.0.50",
+    "peaks-loop-shared": "0.0.82",
+    "peaks-loop-mut": "0.1.46"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",
@@ -141,7 +141,7 @@
     "test:dev": "vitest run tests/unit",
     "test:dev:cli": "vitest run tests/unit",
     "test:unit": "vitest run tests/unit",
-    "test:integration": "vitest run tests/integration",
+    "test:integration": "vitest run --config vitest.config.integration.ts tests/integration",
     "test:capability-guard": "vitest run --config vitest.config.integration.ts tests/integration/capability-guard",
     "test:cli": "vitest run tests/unit",
     "test:workflow": "vitest run tests/unit",

package/scripts/install-skills.mjs

@@ -1273,6 +1273,7 @@ export async function autoUpgrade1xProjectIfPresent(options = {}) {
       encoding: 'utf8',
       stdio: ['ignore', 'pipe', 'pipe'],
       timeout: 120_000,
+      windowsHide: true,
     });
     return {
       ran: true,

package/scripts/watch.mjs

@@ -30,7 +30,9 @@ export function runCommand(command, args, options = {}) {
     let child;
 
     try {
-      child = spawn(command, args, { stdio: 'inherit', ...options });
+      // `windowsHide` is a default, not a lock: a caller that passes its own
+      // value in `options` still wins, because the spread comes after it.
+      child = spawn(command, args, { stdio: 'inherit', windowsHide: true, ...options });
     } catch (error) {
       rejectPromise(error);
       return;

package/skills/bee/peaks-perf-audit/SKILL.md

@@ -12,7 +12,7 @@ metadata:
     - schema: .peaks/project-scan/audit-output-schema.md
 ---
 
-<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+<!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
 
 ## Loop hygiene (every turn — MANDATORY)
 

package/skills/bee/peaks-prd/SKILL.md

@@ -8,7 +8,7 @@ description: |
 visibility: internal
 ---
 
-<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+<!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
 
 ## Loop hygiene (every turn — MANDATORY)
 
@@ -122,7 +122,7 @@ Then display: `Peaks-Loop Skill: peaks-prd | Peaks-Loop Gate: startup | Next: <o
 
 ## Mandatory per-request artifact
 
-Every PRD invocation — feature, bug, refactor, clarification — must write a durable artifact at `.peaks/_runtime/<session-id>/prd/requests/<request-id>.md`. The artifact is the canonical trace; the chat transcript is not. Handoff to RD/UI/QA is blocked while the artifact is missing or in `draft` state. After user confirmation, the **immutable handoff** is written separately at `.peaks/_runtime/<sid>/prd/handoff.md` (Step 5.5 below) — sha256-locked, schemaVersion: 2 — and is the source of truth for RD, QA, and the 4 audit sub-agents (code-reviewer / security-reviewer / karpathy-reviewer / qa-test-cases-writer).
+Every PRD invocation — feature, bug, refactor, clarification — must write a durable artifact at `.peaks/_runtime/<session-id>/prd/requests/<request-id>.md`. The artifact is the canonical trace; the chat transcript is not. Handoff to RD/UI/QA is blocked while the artifact is missing or in `draft` state. After user confirmation, the **immutable handoff** is written separately at `.peaks/_runtime/<sid>/prd/handoff-<rid>.md` (Step 5.5 below) — sha256-locked, schemaVersion: 2 — and is the source of truth for RD, QA, and the 4 audit sub-agents (code-reviewer / security-reviewer / karpathy-reviewer / qa-test-cases-writer).
 
 Use `<request-id>` of the form `YYYY-MM-DD-<kebab-slug>` (or whatever id the user assigned) so PRD/UI/RD/QA/SC can cross-link the same request.
 
@@ -198,15 +198,17 @@ peaks request show <request-id> --role prd --project <repo> --json
 
 # 5.5 — write the immutable handoff (sha256-locked; BLOCKING before RD/QA handoff)
 # Reads the PRD request artifact body, computes sha256, writes a v2.11.0 handoff
-# at .peaks/_runtime/<sid>/prd/handoff.md that downstream RD + QA + 4 audit
-# sub-agents consume as the authoritative source of truth. Dry-run by default
-# (omit --apply) so the operator can review before commit.
+# at .peaks/_runtime/<sid>/prd/handoff-<rid>.md that downstream RD + QA + 4 audit
+# sub-agents consume as the authoritative source of truth. The rid is part of
+# the filename: one capsule per SLICE, so a second slice in the same session
+# cannot overwrite the first's. Dry-run by default (omit --apply) so the
+# operator can review before commit.
 peaks prd handoff init \
   --rid <request-id> --sid <session-id> --change-id <change-id> \
   --body "@.peaks/_runtime/<session-id>/prd/requests/<request-id>.md" \
   --goals <G-ids> --ac <AC-ids> --preserve <P-ids> \
   [--project <repo>] [--apply]
-peaks prd handoff verify --path .peaks/_runtime/<session-id>/prd/handoff.md
+peaks prd handoff verify --path .peaks/_runtime/<session-id>/prd/handoff-<request-id>.md
 
 peaks skill presence:clear --project <repo>                      # handoff complete, remove presence indicator
 ```

package/skills/bee/peaks-qa/SKILL.md

@@ -8,7 +8,7 @@ description: |
 visibility: internal
 ---
 
-<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+<!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
 
 ## Loop hygiene (every turn — MANDATORY)
 
@@ -104,9 +104,9 @@ Project-level security + perf plans live at `.peaks/_runtime/<sessionId>/qa/secu
 
 ## QA fan-out (业务 only — v2.11.0 D1)
 
-When peaks-qa is the **main loop** (i.e. it is the active skill and is about to run its own sub-agent dispatch, rather than being a sub-agent itself), it fans out only the **business verification** sub-agent: `qa-business`. Security and performance review are **NOT** peaks-qa's responsibility in v2.11.0 — they are owned by peaks-rd's 4-way audit fan-out (code-review + security-review + perf-baseline + karpathy-review) and the rd-side evidence files (`rd/security-review.md`, `rd/perf-baseline.md`). peaks-qa reads those files by reference; it does NOT re-do them.
+When peaks-qa is the **main loop** (i.e. it is the active skill and is about to run its own sub-agent dispatch, rather than being a sub-agent itself), it fans out only the **business verification** sub-agent: `qa-business`. Security and performance review are **NOT** peaks-qa's responsibility in v2.11.0 — they are owned by peaks-rd's 4-way audit fan-out (code-review + security-review + perf-baseline + karpathy-review) and the rd-side evidence files (`audit/security-<rid>.md`, `audit/perf-<rid>.md`). peaks-qa reads those files by reference; it does NOT re-do them.
 
-> **v2.15.0+ 校准:** `qa-business` 只跑业务/产品视角的 6 项验收清单(业务流程 / 需求覆盖 / 边界 case / UI 装配 / 异常态语调 / 能上线吗),**不跑技术指标**(覆盖率 / 性能 / 安全)。技术指标由 RD 4-way fan-out 自决,QA 只读 `rd/security-review.md` + `rd/perf-baseline.md`。详见 `.peaks/memory/peaks-loop-slice-review-and-qa-perspective.md`。
+> **v2.15.0+ 校准:** `qa-business` 只跑业务/产品视角的 6 项验收清单(业务流程 / 需求覆盖 / 边界 case / UI 装配 / 异常态语调 / 能上线吗),**不跑技术指标**(覆盖率 / 性能 / 安全)。技术指标由 RD 4-way fan-out 自决,QA 只读 `audit/security-<rid>.md` + `audit/perf-<rid>.md`。详见 `.peaks/memory/peaks-loop-slice-review-and-qa-perspective.md`。
 
 If the PRD or project warrants it, subdivide `qa-business` further into roles like `qa-business-api` / `qa-business-frontend` / `qa-business-regression`. Subdivision must stay ≤ 2 levels deep (RL-4).
 
@@ -128,7 +128,7 @@ When this skill is running in the main Claude session (not as a sub-agent), befo
 - verify API behavior and frontend behavior when either surface exists;
 - generate a validation report with commands, browser evidence, findings, and residual risks.
 
-**Out of scope (v2.11.0 D1/D4):** peaks-qa does **not** own security review or performance review. Those are owned by peaks-rd's audit fan-out (sub-agents `security-review` and `perf-baseline`) and the rd-side evidence files. peaks-qa reads `rd/security-review.md` and `rd/perf-baseline.md` by reference; it does NOT produce `qa/security-findings.md` or `qa/performance-findings.md` of its own.
+**Out of scope (v2.11.0 D1/D4):** peaks-qa does **not** own security review or performance review. Those are owned by peaks-rd's audit fan-out (sub-agents `security-review` and `perf-baseline`) and the rd-side evidence files. peaks-qa reads `audit/security-<rid>.md` and `audit/perf-<rid>.md` by reference; it does NOT produce `qa/security-findings.md` or `qa/performance-findings.md` of its own.
 
 ## Mandatory per-request artifact
 
@@ -148,7 +148,7 @@ See `references/qa-runbook.md` for the full 10-step runbook (steps #0–#9) with
 
 You cannot declare a phase complete from memory. CLI enforcement: the gates below are ALSO enforced by `peaks request transition`, which fails with `code: PREREQUISITES_MISSING` if any are absent. Per-type required files: feature / refactor → test-cases + test-reports + security-findings + performance-findings; bugfix → test-cases + test-reports + security-findings (perf optional); config → security-findings only; docs / chore → none.
 
-Gate index: A (test-cases), A2 (tests executed), A3 (security reference — v2.11.0: read rd/security-review.md), A4 (performance reference — v2.11.0: read rd/perf-baseline.md), B (test-reports with results), C (all 3 QA files present before verdict: test-cases + test-reports + requests — security/perf evidence live under rd/), D (browser screenshots), E (acceptance coverage scan), F (QA artifact lint).
+Gate index: A (test-cases), A2 (tests executed), A3 (security reference — v2.12.0+: read audit/security-<rid>.md), A4 (performance reference — v2.12.0+: read audit/perf-<rid>.md), B (test-reports with results), C (all 3 QA files present before verdict: test-cases + test-reports + requests — security/perf evidence live under audit/), D (browser screenshots), E (acceptance coverage scan), F (QA artifact lint).
 
 → see `references/qa-transition-gates.md` for the full per-gate contract + `ls` / `grep` shell snippets.
 
@@ -194,7 +194,7 @@ Every QA invocation must produce a test-report artifact at `.peaks/_runtime/<ses
 
 ## Mandatory validation gates
 
-QA cannot pass a change until the report contains evidence for every applicable gate. The 9 gates (0 test-case generation, 1 test-report, 2 unit tests, 3 API validation, 4 frontend browser validation, 5 browser-error feedback loop, 8 library version regressions, 9 validation report, 10 acceptance coverage) are mapped to Peaks-Loop Gates A/A2/B/C/D/E/F. **v2.11.0 D1/D4 trim:** Gates A3 (security) and A4 (performance) are no longer peaks-qa's responsibility — security review and performance baseline live under peaks-rd's audit fan-out (rd/security-review.md + rd/perf-baseline.md) and are cited by reference from the test report.
+QA cannot pass a change until the report contains evidence for every applicable gate. The 9 gates (0 test-case generation, 1 test-report, 2 unit tests, 3 API validation, 4 frontend browser validation, 5 browser-error feedback loop, 8 library version regressions, 9 validation report, 10 acceptance coverage) are mapped to Peaks-Loop Gates A/A2/B/C/D/E/F. **v2.11.0 D1/D4 trim:** Gates A3 (security) and A4 (performance) are no longer peaks-qa's responsibility — security review and performance baseline live under peaks-rd's audit fan-out (audit/security-<rid>.md + audit/perf-<rid>.md) and are cited by reference from the test report.
 
 If Playwright MCP is unavailable, the LLM checks its own tool list for the Playwright MCP server entry; if absent, the LLM tells the user the install command (`claude mcp add playwright -- npx @playwright/mcp@latest` for Claude Code) and marks the gate blocked with the missing capability. Screenshots, logs, manual steps, or other tools must not substitute for the mandatory frontend browser gate. Do not silently downgrade frontend validation to API-only testing.
 
@@ -298,4 +298,4 @@ QA contracts to assert on the L2 surface (a minimal acceptance test set):
 
 ## Sub-role detached mode (Phase C, slice 2026-08-10)
 
-QA sub-roles (`qa-business`, `qa-perf`, `qa-security`, `qa-business-api`, `qa-business-frontend`, `qa-business-regression`) accept `--mode detached --vendor <vendor>` for parallel test-case execution. Detached mode spawns a real OS process via `peaks sub-agent dispatch --mode detached`, isolated from the orchestrator session. Use detached mode when the test-case writer's expected runtime exceeds 60s OR it processes ≥ 20 source files. The default remains `in-process` (backward compat; existing 106+ dispatch tests untouched). When `--mode detached` is used, the child QA agent receives the G8 infinite-context auto-compact marker (0.85 / 0.95 thresholds; unlimited spend authorized). See `peaks-code/references/sub-agent-dispatch.md` §"Detached Mode" for the full contract.
+QA sub-roles (`qa-business`, `qa-perf`, `qa-security`, `qa-business-api`, `qa-business-frontend`, `qa-business-regression`) accept `--mode detached --vendor <vendor>` for parallel test-case execution. Detached mode spawns a real OS process via `peaks sub-agent dispatch --mode detached`, isolated from the orchestrator session. Use detached mode when the test-case writer's expected runtime exceeds 60s OR it processes ≥ 20 source files. The default remains `in-process` (backward compat; existing 106+ dispatch tests untouched). When `--mode detached` is used, the child QA agent receives the `<peaks-auto-compact>` marker (corrected 2026-09-13, rid `2026-09-13-defects-e`): it asks the child to persist durable state to `.peaks/_runtime/<sid>/detached/<rid>/compact/<n>.json` before its own harness compacts the session — the child cannot compact itself, and nothing is spliced back into its prompt. See `peaks-code/references/sub-agent-dispatch.md` §"Detached Mode" for the full contract.

package/skills/bee/peaks-qa/references/qa-runbook.md

@@ -36,8 +36,8 @@ peaks openspec validate <change-id> --project <repo> --prefer-external --json
 # 5. EXECUTE tests against the actual implementation — Peaks-Loop Gate A2
 #    Run the project test command. Record output. Tests on paper are worthless.
 #    NOTE (v2.11.0 D1/D4): Security review + performance check are NOT run by peaks-qa.
-#    They are owned by peaks-rd's audit fan-out and surface as rd/security-review.md and
-#    rd/perf-baseline.md under .peaks/_runtime/<sessionId>/rd/. Read them by reference;
+#    They are owned by the independent audit skills and surface as audit/security-<rid>.md
+#    and audit/perf-<rid>.md under .peaks/_runtime/<sessionId>/audit/. Read them by reference;
 #    do NOT re-do them or create qa/security-findings.md / qa/performance-findings.md.
 
 # 6. write test-report — MANDATORY, write to .peaks/_runtime/<sessionId>/qa/test-reports/<request-id>.md

package/skills/bee/peaks-qa/references/qa-transition-gates.md

@@ -11,7 +11,7 @@
 | config | (none) | `qa/test-reports/<rid>.md` |
 | docs / chore | (none) | (none) |
 
-Security and performance evidence surface under `rd/security-review.md` and `rd/perf-baseline.md` (peaks-rd's audit fan-out) and are referenced by reference from the QA test report body. The pre-v2.11.0 `qa/security-findings.md` / `qa/performance-findings.md` files are no longer required; existing ones are kept for auditability but ignored by the gate.
+Security and performance evidence surface under `audit/security-<rid>.md` and `audit/perf-<rid>.md` (the independent `peaks-security-audit` / `peaks-perf-audit` skills, v2.12.0+; slice `2026-09-14-audit-artifact-rid-scoping` put the rid in the filename so two slices in one session cannot overwrite each other's evidence) and are referenced by reference from the QA test report body. The older `rd/security-review.md` / `rd/perf-baseline.md` and the ridless `audit/security.md` / `audit/perf.md` remain accepted back-compat tiers. The pre-v2.11.0 `qa/security-findings.md` / `qa/performance-findings.md` files are no longer required; existing ones are kept for auditability but ignored by the gate.
 
 **Peaks-Loop Gate A — After test-case generation:**
 ```bash
@@ -29,18 +29,18 @@ npx vitest run --changed --reporter=verbose 2>&1 | tail -30
 
 **Peaks-Loop Gate A3 — Security review referenced (v2.11.0 D1/D4: read-only reference, NOT a separate QA file):**
 ```bash
-# peaks-qa does NOT own a qa/security-findings.md. peaks-rd's audit fan-out
-# produces rd/security-review.md; QA references it by path in the test report body.
-grep -E "rd/security-review\\.md|security-review" .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md 2>&1
+# peaks-qa does NOT own a qa/security-findings.md. The security audit produces
+# audit/security-<rid>.md; QA references it by path in the test report body.
+grep -E "audit/security|rd/security-review|security-review" .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md 2>&1
 # Expected: at least one reference to the rd-side security review.
 # Empty → BLOCKED: the test report must cite where security evidence lives.
 ```
 
 **Peaks-Loop Gate A4 — Performance baseline referenced (v2.11.0 D1/D4: read-only reference, NOT a separate QA file):**
 ```bash
-# peaks-qa does NOT own a qa/performance-findings.md. peaks-rd's audit fan-out
-# produces rd/perf-baseline.md; QA references it by path in the test report body.
-grep -E "rd/perf-baseline\\.md|perf-baseline" .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md 2>&1
+# peaks-qa does NOT own a qa/performance-findings.md. The perf audit produces
+# audit/perf-<rid>.md; QA references it by path in the test report body.
+grep -E "audit/perf|rd/perf-baseline|perf-baseline" .peaks/_runtime/<sessionId>/qa/test-reports/<rid>.md 2>&1
 # Expected: at least one reference to the rd-side perf baseline.
 # Empty → BLOCKED: the test report must cite where perf evidence lives.
 ```