peaks-loop 4.1.2 → 4.1.4

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.1.2",
+  "version": "4.1.4",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -75,16 +75,25 @@
     "scripts/copy-templates.mjs",
     "scripts/sync-version.mjs",
     "scripts/install-skills.mjs",
+    "scripts/install-skills-fs.mjs",
+    "scripts/install-skills-report.mjs",
+    "scripts/install-skills-user-config.mjs",
+    "scripts/install-skills-ide.mjs",
+    "scripts/install-skills-bundles.mjs",
+    "scripts/install-skills-output-styles.mjs",
+    "scripts/install-skills-output-style-default.mjs",
     "scripts/canonical-store.mjs",
     "scripts/canonical-store-link.mjs",
     "scripts/canonical-store-prune.mjs",
     "scripts/watch.mjs",
+    "scripts/watch-tree.mjs",
     "skills/**",
     "!skills/**/test-prompts.json",
     "!skills/**/.DS_Store",
     "output-styles/**",
     "agents/**",
     "schemas/*.json",
+    "contracts/readonly-argv-whitelist.json",
     ".claude-plugin/**",
     "config/eslint/.peaks-rules.cjs",
     "config/eslint/tsconfig.lint.json",
@@ -120,10 +129,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.42",
-    "peaks-loop-shared-channel": "0.0.59",
-    "peaks-loop-mut": "0.1.56",
-    "peaks-loop-shared": "0.0.91"
+    "peaks-loop-internal-runtime": "0.0.44",
+    "peaks-loop-shared": "0.0.93",
+    "peaks-loop-mut": "0.1.58",
+    "peaks-loop-shared-channel": "0.0.61"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",
@@ -148,7 +157,9 @@
     "vitest": "^4.1.10"
   },
   "scripts": {
-    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && pnpm -r --filter \"./packages/*\" run build && node ./scripts/write-package-dist-stamps.mjs && tsc -p tsconfig.build.json && node ./scripts/copy-templates.mjs && node ./scripts/check-build-integrity.mjs && node ./scripts/write-dist-stamp.mjs",
+    "build": "node ./scripts/sync-version.mjs && node ./scripts/clean-dist.mjs && pnpm -r --filter \"./packages/*\" run build && node ./scripts/write-package-dist-stamps.mjs && node node_modules/tsx/dist/cli.mjs scripts/generate-readonly-whitelist.ts && node node_modules/tsx/dist/cli.mjs scripts/generate-plugin-manifest.ts && tsc -p tsconfig.build.json && node ./scripts/copy-templates.mjs && node ./scripts/check-build-integrity.mjs && node ./scripts/write-dist-stamp.mjs",
+    "readonly:whitelist": "node node_modules/tsx/dist/cli.mjs scripts/generate-readonly-whitelist.ts",
+    "plugin:manifest": "node node_modules/tsx/dist/cli.mjs scripts/generate-plugin-manifest.ts",
     "prepublish": "node ./scripts/sync-version.mjs",
     "postinstall": "node ./scripts/install-skills.mjs",
     "predev": "node ./scripts/sync-version.mjs",

package/scripts/install-skills-bundles.mjs

@@ -0,0 +1,233 @@
+// scripts/install-skills-bundles.mjs
+//
+// The two installers that read a directory of bundled assets out of the package and
+// reconcile each entry into an IDE directory: the DIRECTORY-shaped family (skills) and
+// the FILE-shaped one (agents). Each owns its dispatch precedence and its repair rule.
+//
+// Split out of `scripts/install-skills.mjs` (rid-043). Every line below was moved
+// VERBATIM from that file; only this header, the import block, and the `export`
+// keyword on names a sibling imports are new.
+
+import { existsSync, lstatSync, mkdirSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { reconcileCanonicalEntry } from './canonical-store.mjs';
+import { reconcileCanonicalFileEntry } from './canonical-store-link.mjs';
+import { pruneBundledEntries } from './canonical-store-prune.mjs';
+import { createInstallResult } from './install-skills-report.mjs';
+import { createInstallRootValidator, resolvePackageRoot } from './install-skills-fs.mjs';
+import { resolveBundleTargetRoot } from './install-skills-ide.mjs';
+
+/**
+ * THE INSTALL CANDIDATE LIST — every skill the package ships, as
+ * `{ skillName, sourcePath }`.
+ *
+ * After the v2.13.0 bee-demote (commit de0872b), the role skills (peaks-prd,
+ * peaks-rd, peaks-qa, peaks-ui, peaks-sc, peaks-txt) moved under
+ * `skills/bee/<role>/` while user-facing helpers stayed at `skills/<name>/`. So the
+ * list is built by walking top-level entries (user-facing helpers) AND
+ * `skills/bee/<role>` (demoted role skills). Each candidate is installed under its
+ * basename, so the postinstall links `~/.claude/skills/peaks-rd` to
+ * `skills/bee/peaks-rd` rather than to `skills/bee`.
+ *
+ * De-dupe rule: a top-level helper with the same name WINS, which preserves the
+ * existing install contract for any helper sharing a name with a demoted role skill
+ * (legacy overlap).
+ *
+ * @param {string} skillsRoot
+ * @returns {Array<{ skillName: string, sourcePath: string }>}
+ */
+function collectSkillCandidates(skillsRoot) {
+  const beeRoot = join(skillsRoot, 'bee');
+  /** @type {Array<{ skillName: string, sourcePath: string }>} */
+  const candidates = [];
+  for (const skillName of readdirSync(skillsRoot)) {
+    if (skillName === 'bee') continue;
+    const sourcePath = join(skillsRoot, skillName);
+    if (!isSkillSource(sourcePath)) continue;
+    candidates.push({ skillName, sourcePath });
+  }
+  if (existsSync(beeRoot) && isDirectoryEntry(beeRoot)) {
+    for (const skillName of readdirSync(beeRoot)) {
+      const sourcePath = join(beeRoot, skillName);
+      if (!isSkillSource(sourcePath)) continue;
+      if (candidates.some((c) => c.skillName === skillName)) continue;
+      candidates.push({ skillName, sourcePath });
+    }
+  }
+  return candidates;
+}
+
+/** A real directory entry — `lstat`, so a symlink to one is NOT one. */
+function isDirectoryEntry(entryPath) {
+  return lstatSync(entryPath).isDirectory();
+}
+
+/** A directory entry that is a skill: a real directory holding a `SKILL.md`. */
+function isSkillSource(sourcePath) {
+  return isDirectoryEntry(sourcePath) && existsSync(join(sourcePath, 'SKILL.md'));
+}
+
+export function installBundledSkills(options = {}) {
+  const packageRoot = resolvePackageRoot(options);
+  const skillsRoot = join(packageRoot, 'skills');
+
+  if (process.env.PEAKS_SKIP_SKILL_INSTALL === '1' || !existsSync(skillsRoot)) {
+    return createInstallResult();
+  }
+
+  // Slice #011: IDE-aware dispatch — the precedence itself now lives in ONE place
+  // (`resolveBundleTargetRoot` in `install-skills-ide.mjs`), because all three
+  // families stated it and only this one also warns.
+  const targetRoot = resolveBundleTargetRoot(options, {
+    profileField: 'skillsDir',
+    envVar: 'PEAKS_CLAUDE_SKILLS_DIR',
+    fallback: '.claude/skills',
+    warn: true
+  });
+
+  const installed = [];
+  const skipped = [];
+  mkdirSync(targetRoot, { recursive: true });
+  const validateSkillsRoot = createInstallRootValidator(targetRoot, 'Peaks skills');
+
+  const candidates = collectSkillCandidates(skillsRoot);
+
+  for (const { skillName, sourcePath } of candidates) {
+    const targetPath = join(targetRoot, skillName);
+
+    // Slice 2 (`agents-canonical-store`) — the entry points at the CANONICAL
+    // STORE (`~/.peaks/skills/<name>`), not at `<packageRoot>/skills/<name>`,
+    // because `<packageRoot>` changes on every `npm i -g peaks-loop@latest` and
+    // the links must bind to a PATH peaks-loop owns, not to a VERSION. Repair is
+    // the only behaviour: an entry peaks-loop owns (sidecar matches, or the link
+    // dangles) is relinked onto the store; only a real directory the user authored
+    // is left alone and reported `skipped`. `options.reconcileJunctions` is
+    // therefore READ NOWHERE here — still accepted (`sync-service.ts` forwards it)
+    // so passing it changes nothing, and removing it is a CLI-surface change this
+    // slice does not own.
+    validateSkillsRoot();
+    const reconciled = reconcileCanonicalEntry({
+      kind: 'skills',
+      name: skillName,
+      sourcePath,
+      linkPath: targetPath
+    });
+    validateSkillsRoot();
+
+    if (reconciled.linkAction === 'skipped') {
+      skipped.push(skillName);
+      continue;
+    }
+    installed.push(skillName);
+  }
+
+  // Slice 3 — PRUNE. The loop above only ever ADDS. A skill removed from the
+  // package left its canonical copy, every IDE link and every sidecar on the
+  // user's machine forever, because nothing walked the DESTINATIONS. This does,
+  // and deletes only what `isManagedEntry` proves is ours.
+  const { pruned } = pruneBundledEntries({
+    kind: 'skills',
+    keepNames: candidates.map((candidate) => candidate.skillName),
+    linkDirs: [targetRoot]
+  });
+
+  return { installed, skipped, pruned };
+}
+
+/**
+ * Slice 7/7 — bundled agents (Claude Code sub-agent prompts).
+ *
+ * Writes into the IDE's sub-agent loader directory (`~/.claude/agents/` for Claude
+ * Code, and whatever `agentsDir` the detected profile declares). The bytes live in
+ * the canonical store (`~/.peaks/agents/<name>`) and the IDE entry is a link to it.
+ *
+ * Ownership policy — ONE predicate, in `canonical-store-link.mjs::isOwnedFileEntry`,
+ * and it is deliberately not a string comparison:
+ *   - entry resolves to the canonical copy              → leave it (idempotent run)
+ *   - entry is a link we wrote (sidecar agrees, dangles) → relink onto the store
+ *   - entry is a real file with OUR sidecar beside it    → re-point it at the store
+ *   - entry is a real file with a LEGACY sidecar whose
+ *     recorded package path no longer resolves           → same: repair it
+ *   - entry is a real file we never wrote (no sidecar)   → skip (user-authored)
+ *   - entry is a real file whose sidecar names a path
+ *     that STILL resolves                                → skip (a second live install)
+ *
+ * The two "skip" arms above are the ones the old code got wrong in opposite
+ * directions: it skipped whenever the package path merely DIFFERED, which froze
+ * every entry on the first upgrade, silently and permanently. See
+ * `isOwnedFileEntry` for why a vanished package path is proof of an earlier install.
+ */
+export function installBundledAgents(options = {}) {
+  const packageRoot = resolvePackageRoot(options);
+  const agentsRoot = join(packageRoot, 'agents');
+
+  // Per-IDE env-var override (claude-code only today): PEAKS_CLAUDE_AGENTS_DIR.
+  // Universal escape hatch: PEAKS_SKIP_AGENT_INSTALL=1 (parallel to
+  // PEAKS_SKIP_SKILL_INSTALL).
+  if (
+    process.env.PEAKS_SKIP_SKILL_INSTALL === '1' ||
+    process.env.PEAKS_SKIP_AGENT_INSTALL === '1' ||
+    !existsSync(agentsRoot)
+  ) {
+    return createInstallResult();
+  }
+
+  // Slice #011: IDE-aware dispatch — same precedence as the other two families,
+  // resolved by the same helper (`resolveBundleTargetRoot`).
+  const targetRoot = resolveBundleTargetRoot(options, {
+    profileField: 'agentsDir',
+    envVar: 'PEAKS_CLAUDE_AGENTS_DIR',
+    fallback: '.claude/agents'
+  });
+
+  const installed = [];
+  const skipped = [];
+  const fallbacks = [];
+  mkdirSync(targetRoot, { recursive: true });
+  const validateAgentsRoot = createInstallRootValidator(targetRoot, 'Peaks agents');
+
+  // Slice 4 (`agents-canonical-store`) — the canonical store owns the bytes and the
+  // IDE entry points at it. Everything this loop used to decide about ownership is
+  // now `reconcileCanonicalFileEntry`'s, and the reason is the defect the brief
+  // names as this slice's core: the old test was
+  // `resolve(marker.sourcePath) === resolve(sourcePath)`, a STRING comparison against
+  // the package path of the installing version — a path with a node version inside it
+  // (`…\nvm\v24.21.0\node_modules\peaks-loop\agents\…`). It went false the first time
+  // the package moved and stayed false, so the agent silently never updated again.
+  const bundledAgentNames = [];
+  for (const agentFileName of readdirSync(agentsRoot)) {
+    const sourcePath = join(agentsRoot, agentFileName);
+    if (!lstatSync(sourcePath).isFile() || !agentFileName.endsWith('.md')) continue;
+    bundledAgentNames.push(agentFileName);
+
+    validateAgentsRoot();
+    const reconciled = reconcileCanonicalFileEntry({
+      kind: 'agents',
+      name: agentFileName,
+      sourcePath,
+      linkPath: join(targetRoot, agentFileName),
+      createFileLink: options.createFileLink
+    });
+    validateAgentsRoot();
+
+    if (reconciled.linkAction === 'skipped') {
+      skipped.push(agentFileName);
+      continue;
+    }
+    installed.push(agentFileName);
+    if (reconciled.fallback !== null) {
+      fallbacks.push({ name: agentFileName, ...reconciled.fallback });
+    }
+  }
+
+  // The delete half: an agent the package stops shipping used to leave its canonical
+  // copy, its IDE entry and both sidecars on the machine forever.
+  const { pruned } = pruneBundledEntries({
+    kind: 'agents',
+    keepNames: bundledAgentNames,
+    linkDirs: [targetRoot]
+  });
+
+  return { installed, skipped, pruned, fallbacks };
+}