peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/skills/hooks-settings-service.js

@@ -0,0 +1,624 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { assertSafeSettingsFile } from '../ide/shared/safe-path.js';
+import { atomicWriteJson, readJsonObjectFile } from '../ide/shared/atomic-json.js';
+import { getAdapter } from '../ide/ide-registry.js';
+// --- Module-level defaults (claude-code) -----------------------------------
+// These exports remain for backward compat — tests and downstream callers
+// that only care about Claude Code can keep importing them. The per-IDE
+// values are computed lazily inside each public function call.
+/** Sentinel substring identifying a Claude-Code gate-enforce hook entry. */
+export const HOOK_ENFORCE_SENTINEL = 'peaks gate enforce';
+/** Default (claude-code) hook command — kept as a stable export for tests. */
+export const HOOK_ENFORCE_COMMAND = `peaks gate enforce --project "\${CLAUDE_PROJECT_DIR}"`;
+/**
+ * Per-IDE hook command + sentinel. The default (Claude Code) uses the
+ * legacy `peaks gate enforce` surface; Trae / Cursor / Codex (Cursor-style
+ * siblings with `before*` / `pre_*` hook events) use `peaks hook handle`,
+ * the new dispatcher. New adapters register by adding a single line here.
+ *
+ * Slice #12 + #13 (2.4.0) honor the framework's "fill the table" promise
+ * — adding a new IDE does NOT require editing this function's control
+ * flow, only adding a line to this table.
+ */
+const HOOK_COMMAND_BY_IDE = {
+    'claude-code': { command: 'peaks gate enforce', sentinel: 'peaks gate enforce' },
+    'trae': { command: 'peaks hook handle', sentinel: 'peaks hook handle' },
+    'cursor': { command: 'peaks hook handle', sentinel: 'peaks hook handle' },
+    'codex': { command: 'peaks hook handle', sentinel: 'peaks hook handle' },
+    'hermes': { command: 'peaks gate enforce', sentinel: 'peaks gate enforce' },
+    'openclaw': { command: 'peaks gate enforce', sentinel: 'peaks gate enforce' },
+    // qoder / tongyi-lingma are reserved IdeIds (slice #1) but not yet
+    // registered. When a slice adds them, add a HOOK_COMMAND_BY_IDE entry
+    // here — the function below fail-closes on missing entries.
+};
+function resolveHookSpec(ide) {
+    // getAdapter throws on unregistered IDEs — the registry is the source of truth.
+    const adapter = getAdapter(ide);
+    const spec = HOOK_COMMAND_BY_IDE[ide];
+    if (!spec) {
+        // Defensive fallback: if an adapter is added to the registry without a
+        // HOOK_COMMAND_BY_IDE entry, fail-closed with a clear error instead of
+        // silently writing a Claude-shaped entry to a non-Claude settings.json.
+        throw new Error(`peaks hooks install: unsupported IDE '${ide}' (no HOOK_COMMAND_BY_IDE entry; add one to hooks-settings-service.ts)`);
+    }
+    return {
+        hookEnforceCommand: `${spec.command} --project "\${${adapter.envVar}}"`,
+        hookEnforceSentinel: spec.sentinel,
+        hookEnforceMatcher: adapter.toolMatcher,
+        hookEnforceEvent: adapter.hookEvent
+    };
+}
+function resolveIde(options) {
+    return options?.ide ?? 'claude-code';
+}
+/** Slice #013: read the skipProgress opt-in flag. Slice #014: the underlying install no longer emits the progress-start entry, so the flag is effectively a no-op (kept for API stability). */
+function resolveSkipProgress(options) {
+    return options?.skipProgress === true;
+}
+/** Resolve settings root dir for a scope. */
+function resolveSettingsRoot(scope, projectRoot) {
+    if (scope === 'global')
+        return resolve(homedir());
+    if (!projectRoot) {
+        throw new Error('Project scope requires a project root');
+    }
+    return resolve(projectRoot);
+}
+function resolveSettingsPath(scope, ide, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const adapter = getAdapter(ide);
+    return adapter.settings.resolveSettingsFile(scope, scope === 'global' ? homedir() : projectRoot);
+}
+function assertSafeSettingsPathCompat(scope, ide, root, settingsPath) {
+    const adapter = getAdapter(ide);
+    assertSafeSettingsFile(scope, root, adapter.settings.dirName, adapter.settings.settingsFileName);
+    // The compat path receives the already-computed settingsPath; double-check
+    // that the computed path matches what assertSafeSettingsFile would have
+    // produced. This guards against drift between the two resolvers.
+    const expected = adapter.settings.resolveSettingsFile(scope, scope === 'global' ? homedir() : root);
+    if (expected !== settingsPath) {
+        throw new Error(`settings path drift: ${expected} vs ${settingsPath}`);
+    }
+}
+/** Read the existing hook array entries for the adapter's hookEvent (tolerant of any prior shape). */
+function readHookEventEntries(settings, eventKey) {
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
+        return [];
+    const arr = hooks[eventKey];
+    return Array.isArray(arr) ? arr : [];
+}
+/** Read the existing hook array entries from a `settings.hooks` object (already extracted). */
+function readHookEntriesFromHooks(hooks, eventKey) {
+    const arr = hooks[eventKey];
+    return Array.isArray(arr) ? arr : [];
+}
+/** True when every command handler in the entry matches a known peaks sentinel for the given IDE. */
+function entryIsPeaksManaged(entry, sentinels) {
+    const handlers = Array.isArray(entry?.hooks) ? entry.hooks : [];
+    if (handlers.length === 0)
+        return false;
+    return handlers.every((h) => {
+        if (typeof h?.command !== 'string')
+            return false;
+        const cmd = h.command;
+        return sentinels.some((sentinel) => cmd.includes(sentinel));
+    });
+}
+/**
+ * Slice #014: read the *actually-installed* peaks-managed hook entries
+ * from a settings object. Replaces the pre-#014 `listInstalledEntriesForIde`
+ * helper in `hooks-commands.ts`, which returned the IDE-EXPECTED list
+ * (a hardcoded 2-entry array per adapter) rather than what was on disk.
+ * That bug surfaced when slice #013's local cleanup installed
+ * `peaks hooks install --no-progress` (gate-enforce only), but the
+ * status command still reported `entries: [Bash, Task]` because the
+ * helper didn't read the file.
+ *
+ * The new helper:
+ *   1. reads each `hooks.<event>` array,
+ *   2. filters to entries that are peaks-managed for the given IDE
+ *      (matches the legacy sentinel set: gate-enforce + the no-longer-
+ *      installed progress-start),
+ *   3. returns one `{ matcher, sentinel }` row per entry, taking the
+ *      FIRST matching sentinel per entry (entries have a single command
+ *      handler in practice, but the loop tolerates multi-handler
+ *      entries by taking the first match).
+ *
+ * Pre-#014 settings.json files that have a stale progress-start entry
+ * will see it surface in the result. This is intentional: the status
+ * command is the user's tool for "what is on disk right now", and
+ * surfacing a stale entry is the only way the user can know to run
+ * `peaks hooks install` (which now strips it) or `peaks hooks
+ * uninstall` (which removes it).
+ */
+export function readInstalledEntriesFromSettings(settings, ide) {
+    const sentinels = resolveLegacySentinels(ide);
+    // Walk every event key the settings file has, not just the
+    // adapter-declared one. A pre-#014 install could have left a
+    // progress-start entry on a different event than the gate-enforce
+    // entry (Trae: both on beforeToolCall, but a stale install on a
+    // future IDE could split them).
+    const hooksRoot = settings.hooks;
+    if (!hooksRoot || typeof hooksRoot !== 'object' || Array.isArray(hooksRoot))
+        return [];
+    const result = [];
+    for (const eventKey of Object.keys(hooksRoot)) {
+        const entries = readHookEntriesFromHooks(hooksRoot, eventKey);
+        for (const entry of entries) {
+            if (!entryIsPeaksManaged(entry, sentinels))
+                continue;
+            const matcher = typeof entry.matcher === 'string' ? entry.matcher : '';
+            // Find the first matching sentinel inside the entry's command
+            // handlers. For each handler, find the first sentinel substring
+            // it contains. We pick the first handler's first matching
+            // sentinel (entries have a single command in practice).
+            const firstHandler = Array.isArray(entry.hooks) ? entry.hooks[0] : undefined;
+            const cmd = typeof firstHandler?.command === 'string' ? firstHandler.command : '';
+            const sentinel = sentinels.find((s) => cmd.includes(s));
+            if (matcher === '' || sentinel === undefined)
+                continue;
+            result.push({ matcher, sentinel });
+        }
+    }
+    return result;
+}
+/**
+ * Compute the per-IDE peaks hook entries to merge into the settings file.
+ * Replaces the slice #1 hardcoded `PEAKS_HOOK_ENTRIES` constant; the constant
+ * remains exported (computed for claude-code) for backward compat.
+ *
+ * Slice #013 (`--no-progress` flag): when `skipProgress` is true, the
+ * progress-start entry is omitted from the returned list. Install with this
+ * flag will (a) NOT emit the progress hook entry, and (b) will idempotently
+ * remove any previously-installed progress entry (sentinel-based merge).
+ *
+ * Slice #014 (refactor — full removal): only the gate-enforce entry is
+ * ever emitted. The `skipProgress` parameter is kept for API stability
+ * but is a no-op — the returned list is always single-entry. The progress
+ * entry's sentinel is included in the legacy sentinel set so uninstall
+ * can find + remove any stale progress-start entry that an older
+ * `peaks hooks install` may have written before this slice.
+ */
+function resolveHookEntries(ide, _skipProgress = false) {
+    const spec = resolveHookSpec(ide);
+    return [
+        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
+    ];
+}
+/**
+ * Legacy sentinel set used by uninstall + status to find and remove stale
+ * progress-start entries written by pre-#014 installs. The progress-start
+ * sentinel is the literal substring that older installs emitted.
+ */
+const LEGACY_PROGRESS_START_SENTINEL = 'peaks progress start';
+function resolveLegacySentinels(ide) {
+    if (ide === 'trae') {
+        return ['peaks hook handle', LEGACY_PROGRESS_START_SENTINEL];
+    }
+    return [HOOK_ENFORCE_SENTINEL, LEGACY_PROGRESS_START_SENTINEL];
+}
+// --- Slice 2026-07-29-worktree-layer3-deny -----------------------------------
+// Layer 3 of the Worktree Governance 3-layer design (see
+// .peaks/memory/2026-07-29-worktree-layer3-deny.md). The gateway is the IDE
+// native `permissions.deny` list — Claude Code refuses to invoke any Skill
+// listed there BEFORE the LLM even sees it. This is the strongest of the three
+// layers because it bypasses the LLM's tool-call decision entirely: the IDE
+// matches the deny entry against the Skill's namespace and returns a
+// permission error, so the LLM observes "skill not available" rather than
+// "skill denied" — true fail-closed.
+//
+// The list is intentionally tiny: only skills that the superpowers chain
+// *forces* downstream from peaks-loop work paths. We do NOT deny every
+// superpowers skill — only the one whose `description` field or SKILL.md body
+// recommends `git worktree add` / native worktree tools as a step. Anything
+// else stays available as a reference (peaks-code's
+// references/external-skill-invocation.md already describes every other
+// superpowers skill as informational).
+//
+// The IDE expects the deny entry in the form `UseSkill(<skill-id>)`. The
+// prefix is fixed; the skill id is the namespace-qualified name. We render
+// the entries at install time and at uninstall time so the sentinel list is
+// the single source of truth.
+/**
+ * The set of Skills whose use is denied at the IDE permissions layer for
+ * every `peaks hooks install` call. Each entry is the namespace-qualified
+ * skill id; the helper `formatSuperpowersDenyEntry` wraps it in the IDE's
+ * `UseSkill(...)` envelope.
+ *
+ * Slice 2026-07-29-worktree-layer3-deny: the list is empty-aware. To deny a
+ * new skill, append its id here and re-run `peaks hooks install`. The list
+ * is also the inverse for uninstall: `removeHookInstall` rebuilds the deny
+ * list by filtering out anything whose wrapped form matches one of these
+ * ids.
+ */
+export const SUPERPOWERS_DENIED_SKILLS = [
+    // superpowers:using-git-worktrees is the chain's "ground zero" — its
+    // SKILL.md (lines 47-99) literally instructs the LLM to run
+    // `git worktree add`. Denying this Skill at the IDE layer prevents the
+    // LLM from ever receiving that prompt.
+    'superpowers:using-git-worktrees'
+];
+function formatSuperpowersDenyEntry(skillId) {
+    return `UseSkill(${skillId})`;
+}
+const SUPERPOWERS_DENY_SENTINELS = new Set(SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry));
+/**
+ * Merge the peaks-managed Skill denylist into the existing settings object.
+ * Preserves every other `permissions.deny` entry the user (or another tool)
+ * has written so the install is additive, not destructive. The output is
+ * always deterministic: the same input always yields the same output,
+ * regardless of insertion order in the source array.
+ *
+ * Defensive behavior:
+ * - `settings.permissions` is missing or non-object → install creates a
+ *   fresh `permissions: { deny: [...our entries] }` object.
+ * - `settings.permissions.deny` is missing or non-array → install replaces
+ *   the field with a fresh array containing only our entries.
+ * - Duplicate entries (any source) are collapsed to one via `new Set`.
+ *
+ * The function is pure: it does not mutate the input. Atomic write happens
+ * at the call site (`applyHookInstall`).
+ */
+export function withSuperpowersSkillDenylist(settings) {
+    const ourEntries = SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry);
+    const permissions = (settings.permissions && typeof settings.permissions === 'object' && !Array.isArray(settings.permissions))
+        ? settings.permissions
+        : {};
+    const existingDeny = Array.isArray(permissions.deny)
+        ? permissions.deny.filter((d) => typeof d === 'string')
+        : [];
+    const otherDeny = existingDeny.filter((d) => !SUPERPOWERS_DENY_SENTINELS.has(d));
+    const finalDeny = [...new Set([...otherDeny, ...ourEntries])];
+    return {
+        ...settings,
+        permissions: { ...permissions, deny: finalDeny }
+    };
+}
+/**
+ * Inverse of `withSuperpowersSkillDenylist`. Removes every peaks-managed
+ * `UseSkill(...)` entry from the deny list. If the resulting deny list is
+ * empty, the `deny` field itself is deleted; if the `permissions` object
+ * becomes empty, the `permissions` field itself is deleted. This is the
+ * uninstall path: every field we wrote must be removed exactly, and no
+ * other field may be touched.
+ *
+ * Pure (no mutation).
+ */
+export function withoutSuperpowersSkillDenylist(settings) {
+    const permissions = (settings.permissions && typeof settings.permissions === 'object' && !Array.isArray(settings.permissions))
+        ? settings.permissions
+        : {};
+    if (!Array.isArray(permissions.deny)) {
+        return settings;
+    }
+    const remainingDeny = permissions.deny
+        .filter((d) => typeof d === 'string')
+        .filter((d) => !SUPERPOWERS_DENY_SENTINELS.has(d));
+    const nextPermissions = { ...permissions };
+    if (remainingDeny.length > 0) {
+        nextPermissions.deny = remainingDeny;
+    }
+    else {
+        delete nextPermissions.deny;
+    }
+    if (Object.keys(nextPermissions).length === 0) {
+        // The whole `permissions` object is empty (no deny, no allow, no other
+        // sub-fields). Drop it to avoid leaving an empty object on disk.
+        const { permissions: _omit, ...rest } = settings;
+        return rest;
+    }
+    return { ...settings, permissions: nextPermissions };
+}
+/**
+ * Read-only introspection. Returns the deny entries that `peaks hooks
+ * install` would write today. Useful for `peaks hooks status` and the
+ * dry-run envelope.
+ */
+export function listSuperpowersDenyEntries() {
+    return SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry);
+}
+/** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. Slice #014: only the gate-enforce entry. */
+export const PEAKS_HOOK_ENTRIES = (() => {
+    const spec = resolveHookSpec('claude-code');
+    return [
+        { sentinel: spec.hookEnforceSentinel, matcher: spec.hookEnforceMatcher, command: spec.hookEnforceCommand, event: spec.hookEnforceEvent }
+    ];
+})();
+function isInstalledForIde(settings, ide) {
+    const entries = resolveHookEntries(ide);
+    const sentinels = entries.map((e) => e.sentinel);
+    // Check every distinct event key our entries could be on.
+    const eventKeys = new Set(entries.map((e) => e.event));
+    for (const eventKey of eventKeys) {
+        if (readHookEventEntries(settings, eventKey).some((e) => entryIsPeaksManaged(e, sentinels))) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Slice #014: detect the "stale progress entry after pre-#014 install"
+ * case. The desired shape is gate-enforce-only. If the file currently
+ * has a peaks-managed progress-start entry (left behind by a pre-#014
+ * install), the install is NOT a no-op — it must strip the stale
+ * entry. This helper returns true exactly when the desired shape is
+ * fully reflected on disk: gate-enforce present AND no legacy
+ * progress-start present.
+ */
+function shapeMatchesDesired(settings, ide) {
+    const desiredEntries = resolveHookEntries(ide);
+    const desiredSentinels = new Set(desiredEntries.map((e) => e.sentinel));
+    const allPeaksSentinels = resolveLegacySentinels(ide);
+    const eventKeys = new Set(resolveHookEntries(ide).map((e) => e.event));
+    for (const eventKey of eventKeys) {
+        const present = readHookEventEntries(settings, eventKey);
+        const peaksPresent = present.filter((e) => entryIsPeaksManaged(e, allPeaksSentinels));
+        // (a) every peaks-managed entry currently on disk must match the
+        //     desired sentinel set (no stale entries the caller wants removed).
+        for (const entry of peaksPresent) {
+            const entrySentinels = (entry.hooks ?? []).map((h) => allPeaksSentinels.find((s) => String(h.command ?? '').includes(s))).filter((s) => Boolean(s));
+            if (entrySentinels.some((s) => !desiredSentinels.has(s))) {
+                return false;
+            }
+        }
+        // (b) every desired entry must be on disk.
+        for (const sentinel of desiredSentinels) {
+            const has = peaksPresent.some((entry) => (entry.hooks ?? []).some((h) => String(h.command ?? '').includes(sentinel)));
+            if (!has)
+                return false;
+        }
+    }
+    return true;
+}
+export function planHookInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const _skipProgress = resolveSkipProgress(options);
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = exists ? readJsonObjectFile(settingsPath) : {};
+    const spec = resolveHookSpec(ide);
+    return {
+        scope,
+        settingsPath,
+        exists,
+        alreadyInstalled: isInstalledForIde(settings, ide),
+        desiredCommand: spec.hookEnforceCommand,
+        sentinel: spec.hookEnforceSentinel,
+        matcher: spec.hookEnforceMatcher
+    };
+}
+/** Merge all peaks-managed hook entries into settings, preserving all other keys and hooks. */
+function withHooksInstalledForIde(settings, ide, _skipProgress = false) {
+    const existingHooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks))
+        ? settings.hooks
+        : {};
+    // Per-IDE entries may map to different events (Trae: gate-enforce on
+    // beforeToolCall; Claude: gate-enforce on PreToolUse). Group by event
+    // so each event array is independently merged.
+    const ourByEvent = new Map();
+    for (const spec of resolveHookEntries(ide)) {
+        const list = ourByEvent.get(spec.event) ?? [];
+        list.push(spec);
+        ourByEvent.set(spec.event, list);
+    }
+    // Slice #014: the legacy sentinel set includes the progress-start
+    // sentinel so a pre-#014 install's stale progress-start entry is
+    // stripped by the filter (the file converges on the new
+    // gate-enforce-only shape, idempotently). The desired set (passed
+    // in below) only contains the gate-enforce sentinel.
+    const allSentinels = resolveLegacySentinels(ide);
+    const nextHooks = { ...existingHooks };
+    for (const [eventKey, ourEntries] of ourByEvent) {
+        const existing = readHookEntriesFromHooks(nextHooks, eventKey);
+        const nonPeaks = existing.filter((entry) => !entryIsPeaksManaged(entry, allSentinels));
+        const ourFormatted = ourEntries.map((spec) => ({
+            matcher: spec.matcher,
+            hooks: [{ type: 'command', command: spec.command }]
+        }));
+        const merged = [...nonPeaks, ...ourFormatted];
+        if (merged.length > 0) {
+            nextHooks[eventKey] = merged;
+        }
+        else {
+            delete nextHooks[eventKey];
+        }
+    }
+    return {
+        ...settings,
+        hooks: nextHooks
+    };
+}
+export function applyHookInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const _skipProgress = resolveSkipProgress(options);
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = exists ? readJsonObjectFile(settingsPath) : {};
+    const spec = resolveHookSpec(ide);
+    // Slice #014: `alreadyInstalled` reflects the FULL desired shape
+    // (gate-enforce-only + no stale progress-start entry). Pre-#014
+    // installs that left a progress-start entry behind will be treated
+    // as not-yet-installed, so the merge strips the stale entry on the
+    // next install call. This is the only path that converges the file
+    // on the new shape; pure presence-checks are insufficient.
+    const alreadyInstalled = shapeMatchesDesired(settings, ide);
+    const baseResult = {
+        scope,
+        settingsPath,
+        exists,
+        alreadyInstalled,
+        desiredCommand: spec.hookEnforceCommand,
+        sentinel: spec.hookEnforceSentinel,
+        matcher: spec.hookEnforceMatcher
+    };
+    if (baseResult.alreadyInstalled) {
+        return { ...baseResult, applied: false };
+    }
+    // Slice 2026-07-29-worktree-layer3-deny: Layer 3 — write the
+    // `permissions.deny` block alongside the gate hook in a single atomic
+    // write so the two halves of the install are always co-located. The
+    // helper is idempotent and additive: any user-written deny entries
+    // are preserved.
+    //
+    // Slice 2026-07-29-worktree-l2-extended Part 29: also apply
+    // withTriggeredDenyList. If the existing settings file has a
+    // superpowers / git-worktree / podman-run entry (any source),
+    // the install appends a defensive `Edit(deny-trigger:<phrase>)`
+    // entry. The chain cannot run raw `git worktree add` (or
+    // `podman run`) without an explicit `peaks hooks uninstall`
+    // first. Both helpers are pure + idempotent.
+    const merged = withTriggeredDenyList(withSuperpowersSkillDenylist(withHooksInstalledForIde(settings, ide)));
+    atomicWriteJson(settingsPath, merged);
+    return { ...baseResult, alreadyInstalled: false, applied: true };
+}
+export function removeHookInstall(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
+    if (!existsSync(settingsPath)) {
+        return { scope, settingsPath, removed: false };
+    }
+    const settings = readJsonObjectFile(settingsPath);
+    const existingHooks = settings.hooks ?? {};
+    // Slice #014: uninstall must remove the gate-enforce entry AND any
+    // legacy progress-start entry that a pre-#014 install left behind.
+    // The legacy sentinel set covers both shapes so the uninstall
+    // converges the file on "no peaks-managed entries", regardless of
+    // what shape the file was in when the user ran uninstall.
+    const sentinels = resolveLegacySentinels(ide);
+    const eventKeys = new Set(resolveHookEntries(ide).map((e) => e.event));
+    let removedAny = false;
+    const nextHooks = { ...existingHooks };
+    for (const eventKey of eventKeys) {
+        const entries = readHookEntriesFromHooks(nextHooks, eventKey);
+        const kept = entries.filter((entry) => !entryIsPeaksManaged(entry, sentinels));
+        if (kept.length !== entries.length)
+            removedAny = true;
+        if (kept.length > 0) {
+            nextHooks[eventKey] = kept;
+        }
+        else {
+            delete nextHooks[eventKey];
+        }
+    }
+    const nextSettings = { ...settings };
+    if (Object.keys(nextHooks).length > 0) {
+        nextSettings.hooks = nextHooks;
+    }
+    else {
+        delete nextSettings.hooks;
+    }
+    // Slice 2026-07-29-worktree-layer3-deny: Layer 3 — symmetric uninstall.
+    // Strips the peaks-managed `UseSkill(...)` deny entries alongside the
+    // hook entries; user-written entries are untouched. The helper self-
+    // decomposes an empty `permissions` object.
+    //
+    // Slice 2026-07-29-worktree-l2-extended Part 29: also strip the
+    // trigger-style deny entries via withoutTriggeredDenyList. The
+    // chain of helpers is order-independent (each is idempotent and
+    // additive over the same set of peaks-managed entries).
+    const finalSettings = withoutTriggeredDenyList(withoutSuperpowersSkillDenylist(nextSettings));
+    atomicWriteJson(settingsPath, finalSettings);
+    return { scope, settingsPath, removed: removedAny };
+}
+export function readHookStatus(scope, projectRoot, options) {
+    const ide = resolveIde(options);
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, ide, projectRoot);
+    assertSafeSettingsPathCompat(scope, ide, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = exists ? readJsonObjectFile(settingsPath) : {};
+    return { scope, settingsPath, exists, installed: isInstalledForIde(settings, ide) };
+}
+/**
+ * Slice 2026-07-29-worktree-l2-extended Part 27 — trigger-style deny.
+ *
+ * In addition to the static SUPERPOWERS_DENIED_SKILLS list, peaks
+ * scans the existing settings file for "trigger phrases" that
+ * indicate the user has configured the superpowers chain (or
+ * any other auto-run worktree-creating tool) and appends a
+ * defensive deny to prevent the chain from running raw
+ * `git worktree add` (or `podman run`) directly.
+ *
+ * Triggers detected (substring match on the existing
+ * permissions.deny / permissions.allow list):
+ *
+ *  - `superpowers:using-git-worktrees` — the chain's ground zero
+ *  - `superpowers:brainstorming` etc. — the upstream skill
+ *  - `Bash(git worktree add` — the user has explicitly
+ *    allowed raw git worktree, which our L2 lease-aware gate
+ *    would also intercept (defense in depth)
+ *
+ * Append-only — never replaces, never re-orders, never removes
+ * existing entries. Idempotent: re-running the install with
+ * the same input yields the same output.
+ */
+export const TRIGGER_PHRASES = Object.freeze([
+    'superpowers:using-git-worktrees',
+    'superpowers:brainstorming',
+    'superpowers:writing-plans',
+    'superpowers:subagent-driven-development',
+    'Bash(git worktree add',
+    'Bash(podman run'
+]);
+/**
+ * Format a trigger-phrase into a stable `Edit` deny entry. We deny
+ * `Edit` (not `Bash`) on the *settings file* itself, so the
+ * user cannot edit the trigger away without an explicit
+ * `peaks hooks uninstall` first. The skill name (when
+ * applicable) is the value after the colon.
+ */
+function formatTriggerDenyEntry(phrase) {
+    return `Edit(deny-trigger:${phrase})`;
+}
+export function withTriggeredDenyList(settings) {
+    const existingDeny = Array.isArray(settings.permissions?.deny)
+        ? (settings.permissions.deny
+            .filter((d) => typeof d === 'string'))
+        : [];
+    // Detect triggers in the existing allow + deny lists.
+    const existingAllow = Array.isArray(settings.permissions?.allow)
+        ? (settings.permissions.allow
+            .filter((d) => typeof d === 'string'))
+        : [];
+    const haystack = [...existingDeny, ...existingAllow].join('|');
+    const triggered = TRIGGER_PHRASES.filter((p) => haystack.includes(p));
+    if (triggered.length === 0)
+        return settings;
+    const triggeredEntries = triggered.map(formatTriggerDenyEntry);
+    const permissions = (settings.permissions && typeof settings.permissions === 'object' && !Array.isArray(settings.permissions))
+        ? settings.permissions
+        : {};
+    const otherDeny = existingDeny.filter((d) => !triggeredEntries.includes(d));
+    return {
+        ...settings,
+        permissions: { ...permissions, deny: [...new Set([...otherDeny, ...triggeredEntries])] }
+    };
+}
+/** Inverse of withTriggeredDenyList: strip every deny-trigger entry. */
+export function withoutTriggeredDenyList(settings) {
+    const permissions = (settings.permissions && typeof settings.permissions === 'object' && !Array.isArray(settings.permissions))
+        ? settings.permissions
+        : {};
+    const existingDeny = Array.isArray(permissions.deny)
+        ? permissions.deny.filter((d) => typeof d === 'string')
+        : [];
+    const kept = existingDeny.filter((d) => !d.startsWith('Edit(deny-trigger:'));
+    const next = { ...permissions, deny: kept };
+    if (kept.length === 0)
+        delete next.deny;
+    if (Object.keys(next).length === 0) {
+        const out = { ...settings };
+        delete out.permissions;
+        return out;
+    }
+    return { ...settings, permissions: next };
+}

package/dist/services/skills/skill-conformance-service.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Skill-conformance audit (Slice #12) — checks every peaks-* SKILL.md
+ * against the 5 standards from the L1+L2+L3 redesign §5.4 Slice #12:
+ *
+ *   1. task-level frontmatter (all 12 skills must declare one)
+ *   2. CLI-back 注解 coverage (each skill body must document which
+ *      `peaks <cmd>` commands it composes; the absence is a SKILL.md
+ *      anti-pattern — it means the LLM has to discover the CLI
+ *      primitives by accident)
+ *   3. loadStrategy on-demand 标注 (skills should declare when they
+ *      load — `eager` for always-loaded, `on-demand` for invoked)
+ *   4. 800-line cap (Karpathy limit per spec §2.3)
+ *   5. outputStyle: peaks-concise-v1 frontmatter (peak-cli display
+ *      style for the skill's user-visible output)
+ *
+ * Plus 1 derived check:
+ *   6. CLI primitives declared in references/audit/ (Skill must
+ *      surface every peaks <cmd> it composes in the references/ subdir;
+ *      this is the "CLI-back 注解 100% 覆盖" check)
+ */
+export type LoadStrategy = 'eager' | 'on-demand';
+export type ConformanceLevel = 'pass' | 'warn' | 'fail';
+export interface ConformanceCheck {
+    readonly id: string;
+    readonly skill: string;
+    readonly level: ConformanceLevel;
+    readonly message: string;
+}
+export interface ConformanceReport {
+    readonly checked: number;
+    readonly passed: number;
+    readonly warned: number;
+    readonly failed: number;
+    readonly checks: readonly ConformanceCheck[];
+    readonly summary: string;
+}
+export interface SkillConformanceInput {
+    readonly projectRoot: string;
+}
+export declare function auditSkillConformance(input: SkillConformanceInput): ConformanceReport;