peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/services/fuzzy-matching/fzf-pick-service.js

@@ -0,0 +1,158 @@
+/**
+ * Generic fzf binary picker (slice 2026-06-14-fzf-headroom-rollout).
+ *
+ * Promoted from `src/services/slice/slice-pick-service.ts` (which is
+ * the only prior caller). Encapsulates the canonical fzf integration
+ * pattern: format items as one-line text, spawn `fzf --multi`, parse
+ * the multi-selection, write a `<list-id>-picked.json` artifact.
+ *
+ * Two distinct things live in `src/services/fuzzy-matching/`:
+ *  - `fuzzy-match-service.ts` — in-process fzf *npm package* (the
+ *    Fzf class). Used by `memory search` / `retrospective search`.
+ *  - `fzf-pick-service.ts`    — spawns the fzf *binary* for
+ *    interactive TTY multi-select. Used by `peaks slice pick`,
+ *    `peaks memory list --pick`, `peaks retrospective index --pick`.
+ *
+ * The two are independent (one is a library, the other spawns a CLI);
+ * do not merge them. fzf-for-js returns positions; the binary returns
+ * raw lines. Different output shapes → different consumers.
+ *
+ * Source-of-truth: the binary is the *consumer* of the formatter
+ * output, not an input. Each caller injects its own `formatLine` and
+ * `parseLine` so a future swap to skim/peco is a one-line change per
+ * caller, not a refactor of this service.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export const MIN_FZF_VERSION = '0.38';
+const SPAWN_TIMEOUT_MS = 60_000;
+const MAX_BUFFER_BYTES = 32 * 1024 * 1024;
+/**
+ * Pick a subset of `items` interactively via fzf. The full flow:
+ *   1. Check fzf presence + version.
+ *   2. Format items as one-line text (caller's formatLine).
+ *   3. Spawn `fzf --multi` (or test override).
+ *   4. Parse the multi-selection back into T[] (caller's parseLine).
+ *   5. Write `<outputPath>` with the picked + meta + fzfVersion.
+ *
+ * Failure modes:
+ *   - fzf missing → throws with `brew install fzf | apt-get install fzf` hint.
+ *   - fzf version too old → throws.
+ *   - fzf exits 130 (Esc) → returns `{ picked: [], outputPath, fzfVersion }` (NOT thrown).
+ *   - parseLine returns null for a line → silently dropped (line ignored).
+ */
+export async function pickFromList(options) {
+    const fzfBin = options.fzfBin ?? 'fzf';
+    const fzfVersion = checkFzfVersion(fzfBin);
+    if (options.items.length === 0) {
+        // Nothing to pick from. Still write an empty picked artifact so
+        // downstream commands have a stable file contract.
+        const emptyPayload = { ...options.meta, pickedAt: new Date().toISOString(), fzfVersion, picked: [] };
+        writeArtifact(options.outputPath, emptyPayload);
+        return { picked: [], outputPath: options.outputPath, fzfVersion };
+    }
+    const fzfInput = options.items.map(options.formatLine).join('\n');
+    const args = [];
+    args.push(options.multi === false ? '--no-multi' : '--multi');
+    args.push(`--prompt=${options.prompt ?? 'pick> '}`);
+    if (options.preview === true) {
+        args.push('--preview', 'cat');
+    }
+    let stdout;
+    if (options.overrideStdin !== undefined) {
+        stdout = options.overrideStdin;
+    }
+    else {
+        try {
+            stdout = execFileSync(fzfBin, args, {
+                input: fzfInput,
+                cwd: options.projectRoot,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                shell: false,
+                timeout: SPAWN_TIMEOUT_MS,
+                maxBuffer: MAX_BUFFER_BYTES
+            }).toString('utf8');
+        }
+        catch (error) {
+            const err = error;
+            if (err.status === 130) {
+                stdout = ''; // user pressed Esc
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    const selectedLines = stdout.split('\n').filter((l) => l.trim().length > 0);
+    const seen = new Set();
+    const picked = [];
+    for (const line of selectedLines) {
+        const item = options.parseLine(line);
+        if (item === null)
+            continue;
+        // Dedup by JSON serialization (caller's T may not be hashable otherwise).
+        const key = JSON.stringify(item);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        picked.push(item);
+    }
+    const payload = { ...options.meta, pickedAt: new Date().toISOString(), fzfVersion, picked };
+    writeArtifact(options.outputPath, payload);
+    return { picked, outputPath: options.outputPath, fzfVersion };
+}
+function checkFzfVersion(fzfBin) {
+    let stdout;
+    try {
+        stdout = execFileSync(fzfBin, ['--version'], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+            shell: false,
+            timeout: 5_000
+        }).toString('utf8');
+    }
+    catch (error) {
+        if (isEnoent(error) || isCommandNotFound(error)) {
+            throw new Error(`fzf binary not found. Install with: brew install fzf  (or apt: apt-get install fzf). ` +
+                `fzf >= ${MIN_FZF_VERSION} is required for interactive list picking.`);
+        }
+        throw error;
+    }
+    const version = stdout.trim().split('\n')[0] ?? '';
+    if (compareVersions(version, MIN_FZF_VERSION) < 0) {
+        throw new Error(`fzf version ${version} is older than required ${MIN_FZF_VERSION}`);
+    }
+    return version;
+}
+function compareVersions(a, b) {
+    const aParts = a.split('.').map((p) => parseInt(p, 10) || 0);
+    const bParts = b.split('.').map((p) => parseInt(p, 10) || 0);
+    const len = Math.max(aParts.length, bParts.length);
+    for (let i = 0; i < len; i += 1) {
+        const av = aParts[i] ?? 0;
+        const bv = bParts[i] ?? 0;
+        if (av < bv)
+            return -1;
+        if (av > bv)
+            return 1;
+    }
+    return 0;
+}
+function isEnoent(error) {
+    if (error === null || typeof error !== 'object')
+        return false;
+    return error.code === 'ENOENT';
+}
+function isCommandNotFound(error) {
+    if (error === null || typeof error !== 'object')
+        return false;
+    const msg = error.message ?? '';
+    return /command not found|not found/i.test(msg);
+}
+function writeArtifact(outputPath, payload) {
+    const dir = dirname(outputPath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(outputPath, JSON.stringify(payload, null, 2), 'utf8');
+}

package/dist/services/fuzzy-matching/types.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Options for the generic fuzzy-match kernel.
+ */
+export interface FuzzyMatchOptions {
+    /** Maximum number of matches to return. Default 6. */
+    limit?: number;
+    /** When true, matching is case-sensitive. Default false (smart-case). */
+    caseSensitive?: boolean;
+}
+/**
+ * A single fuzzy-match hit. `item` is the original entry; `score` is
+ * normalized to [0, 1] with the top of the current batch at 1.0;
+ * `positions` is the set of char indices in the searchable text that
+ * contributed to the match.
+ */
+export interface FuzzyMatchResult<T> {
+    item: T;
+    score: number;
+    positions: number[];
+}

package/dist/services/fuzzy-matching/types.js

@@ -0,0 +1 @@
+export {};

package/dist/services/handoff/handoff-parser.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Handoff frontmatter — parser.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Reads a markdown handoff file from disk and splits it into:
+ *   - `frontmatter`: structured `HandoffFrontmatter` (parsed from YAML)
+ *   - `body`:        the trailing prose
+ *
+ * Backward compat: legacy handoffs without a `---` frontmatter block are
+ * returned with `schema_version: '0'` and `status: 'unknown'` so older
+ * artifacts remain readable without any migration step.
+ *
+ * Required-field enforcement: any `HandoffFrontmatter` with schema_version
+ * `'1'` MUST carry all six required fields. Missing fields raise
+ * `IncompleteHandoffError` rather than silently substituting defaults.
+ */
+import type { HandoffFrontmatter } from './handoff-types.js';
+export declare class IncompleteHandoffError extends Error {
+    readonly code: "INCOMPLETE_HANDOFF";
+    constructor(message: string);
+}
+export interface ParsedHandoff {
+    readonly frontmatter: HandoffFrontmatter;
+    readonly body: string;
+}
+export declare function parseHandoff(filePath: string): ParsedHandoff;

package/dist/services/handoff/handoff-parser.js

@@ -0,0 +1,69 @@
+/**
+ * Handoff frontmatter — parser.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Reads a markdown handoff file from disk and splits it into:
+ *   - `frontmatter`: structured `HandoffFrontmatter` (parsed from YAML)
+ *   - `body`:        the trailing prose
+ *
+ * Backward compat: legacy handoffs without a `---` frontmatter block are
+ * returned with `schema_version: '0'` and `status: 'unknown'` so older
+ * artifacts remain readable without any migration step.
+ *
+ * Required-field enforcement: any `HandoffFrontmatter` with schema_version
+ * `'1'` MUST carry all six required fields. Missing fields raise
+ * `IncompleteHandoffError` rather than silently substituting defaults.
+ */
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+export class IncompleteHandoffError extends Error {
+    code = 'INCOMPLETE_HANDOFF';
+    constructor(message) {
+        super(message);
+        this.name = 'IncompleteHandoffError';
+    }
+}
+const REQUIRED_FIELDS = [
+    'rid',
+    'slice_id',
+    'agent_id',
+    'schema_version',
+    'status',
+    'created_at'
+];
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?([\s\S]*)$/;
+export function parseHandoff(filePath) {
+    const content = readFileSync(filePath, 'utf8');
+    const match = FRONTMATTER_RE.exec(content);
+    if (!match) {
+        return legacyDefaults(content);
+    }
+    const [, yamlContent, body] = match;
+    const parsed = parseYaml(yamlContent ?? '');
+    if (parsed === null || parsed === undefined) {
+        return legacyDefaults(content);
+    }
+    const missing = REQUIRED_FIELDS.filter((f) => parsed[f] === undefined);
+    if (missing.length > 0) {
+        throw new IncompleteHandoffError(`Missing required frontmatter fields: ${missing.join(', ')}`);
+    }
+    return {
+        frontmatter: parsed,
+        body: body ?? ''
+    };
+}
+function legacyDefaults(content) {
+    return {
+        frontmatter: {
+            rid: 'unknown',
+            slice_id: 'unknown',
+            agent_id: 'unknown',
+            schema_version: '0',
+            status: 'unknown',
+            created_at: new Date(0).toISOString()
+        },
+        body: content
+    };
+}

package/dist/services/handoff/handoff-types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Handoff frontmatter schema — types.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4 (Handoff frontmatter types + parser + writer).
+ *
+ * A handoff artifact is a markdown file with a YAML frontmatter block
+ * carrying structured fields (rid, slice_id, status, ...) followed by a
+ * prose body. The frontmatter is the source of truth for downstream
+ * automation (peaks-rd, peaks-qa); the body is human/agent prose.
+ *
+ * Two schema versions exist:
+ *   - "0" — legacy handoff (no frontmatter block). Fields default to
+ *           `rid='unknown'`, `slice_id='unknown'`, `agent_id='unknown'`,
+ *           `status='unknown'`, `created_at=epoch`.
+ *   - "1" — current schema. All required fields must be present; the
+ *           parser throws `IncompleteHandoffError` if any are missing.
+ */
+export type HandoffStatus = 'done' | 'failed' | 'partial' | 'blocked' | 'unknown';
+export type HandoffTestResult = 'pass' | 'fail' | 'inconclusive' | null;
+export type HandoffSchemaVersion = '0' | '1';
+export interface HandoffFrontmatter {
+    readonly rid: string;
+    readonly slice_id: string;
+    readonly agent_id: string;
+    readonly schema_version: HandoffSchemaVersion;
+    readonly status: HandoffStatus;
+    readonly created_at: string;
+    readonly duration_seconds?: number;
+    readonly files_changed?: readonly string[];
+    readonly lines_added?: number;
+    readonly lines_removed?: number;
+    readonly test_result?: HandoffTestResult;
+    readonly coverage?: number;
+    readonly errors?: readonly string[];
+    readonly warnings?: readonly string[];
+    readonly blockers?: readonly string[];
+    readonly upstream_dependencies?: readonly string[];
+}

package/dist/services/handoff/handoff-types.js

@@ -0,0 +1,19 @@
+/**
+ * Handoff frontmatter schema — types.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4 (Handoff frontmatter types + parser + writer).
+ *
+ * A handoff artifact is a markdown file with a YAML frontmatter block
+ * carrying structured fields (rid, slice_id, status, ...) followed by a
+ * prose body. The frontmatter is the source of truth for downstream
+ * automation (peaks-rd, peaks-qa); the body is human/agent prose.
+ *
+ * Two schema versions exist:
+ *   - "0" — legacy handoff (no frontmatter block). Fields default to
+ *           `rid='unknown'`, `slice_id='unknown'`, `agent_id='unknown'`,
+ *           `status='unknown'`, `created_at=epoch`.
+ *   - "1" — current schema. All required fields must be present; the
+ *           parser throws `IncompleteHandoffError` if any are missing.
+ */
+export {};

package/dist/services/handoff/handoff-writer.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Handoff frontmatter — writer.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Serializes a `HandoffFrontmatter` plus a body string into a single
+ * markdown file with the canonical layout:
+ *
+ *   ---
+ *   rid: "..."
+ *   slice_id: "..."
+ *   ...
+ *   ---
+ *
+ *   <body verbatim>
+ *
+ * The output of `writeHandoff` is round-trip compatible with
+ * `parseHandoff` — writing then parsing recovers the same frontmatter
+ * fields and body.
+ */
+import type { HandoffFrontmatter } from './handoff-types.js';
+export declare function writeHandoff(filePath: string, frontmatter: HandoffFrontmatter, body: string): void;

package/dist/services/handoff/handoff-writer.js

@@ -0,0 +1,30 @@
+/**
+ * Handoff frontmatter — writer.
+ *
+ * Spec: docs/superpowers/plans/2026-06-25-slice-topology-multipass.md
+ *       Phase 1, Task 4.
+ *
+ * Serializes a `HandoffFrontmatter` plus a body string into a single
+ * markdown file with the canonical layout:
+ *
+ *   ---
+ *   rid: "..."
+ *   slice_id: "..."
+ *   ...
+ *   ---
+ *
+ *   <body verbatim>
+ *
+ * The output of `writeHandoff` is round-trip compatible with
+ * `parseHandoff` — writing then parsing recovers the same frontmatter
+ * fields and body.
+ */
+import { writeFileSync } from 'node:fs';
+import { stringify as stringifyYaml } from 'yaml';
+const FRONTMATTER_OPEN = '---\n';
+const FRONTMATTER_CLOSE = '\n---\n\n';
+export function writeHandoff(filePath, frontmatter, body) {
+    const yamlStr = stringifyYaml(frontmatter).trimEnd();
+    const content = `${FRONTMATTER_OPEN}${yamlStr}${FRONTMATTER_CLOSE}${body}`;
+    writeFileSync(filePath, content, 'utf8');
+}

package/dist/services/hooks/auto-compact-hook-install.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause — `ide-native` pathway
+ * hook install/remove service.
+ *
+ * Writes the auto-compact PreToolUse hook into the consumer
+ * project's `.claude/settings.local.json` so the next Bash or Task
+ * tool call from the running Claude Code session reads
+ * `CLAUDE_CONTEXT_USAGE_PERCENT` and, at ratio ≥ 0.95, in-band fires
+ * `claude --compact` against the current runner (not a child process).
+ *
+ * Idempotency contract:
+ *   - install is idempotent — calling `installAutoCompactHook`
+ *     twice produces a byte-identical file (after stripping the
+ *     magic comment). The on-disk matcher entry is the single
+ *     source of truth.
+ *   - remove is idempotent — calling `removeAutoCompactHook` when
+ *     the hook is absent is a no-op.
+ *   - other PreToolUse entries are untouched on install AND remove.
+ *
+ * Magic comment marker: `peaks:auto-compact-hook-do-not-edit`. The
+ * comment sits next to the matcher entry so a human reading the file
+ * sees the boundary; an automated diff/remove op keys off the marker
+ * + the `matcher` regex.
+ *
+ * Pure data + minimal IO: `installAutoCompactHook` and
+ * `removeAutoCompactHook` accept `settingsPath` so callers can pick
+ * `.claude/settings.local.json` (default) or pass an explicit path
+ * for tests. The functions write to disk via `fs.writeFileSync` so
+ * the on-disk file matches the in-memory template byte-for-byte
+ * (modulo the magic comment which is excluded from the data
+ * structure; see `AUTO_COMPACT_HOOK_MATCHER`).
+ */
+/**
+ * Stable matcher for the auto-compact hook. Single source of truth
+ * — `install` and `remove` both key off this constant so the
+ * invariants can't drift between the two paths.
+ */
+export declare const AUTO_COMPACT_HOOK_MATCHER = "Bash|Task";
+/**
+ * Stable command the hook fires. Wraps `peaks session
+ * auto-compact-hook` so the heavy lifting (ratio probe + in-band
+ * `claude --compact` spawn) lives in the CLI surface, not inlined
+ * into the hook.
+ *
+ * `npx peaks` is deliberately omitted: the project-local install
+ * puts `peaks` on PATH inside the consumer repo (postinstall step),
+ * so the unqualified command works in the same shell the runner
+ * is using.
+ */
+export declare const AUTO_COMPACT_HOOK_COMMAND = "peaks session auto-compact-hook";
+/**
+ * Magic comment marker that fences the auto-compatchook block.
+ * Both install (writes the marker) and remove (matches on it) use
+ * this string so the comment is the only place the boundary lives.
+ */
+export declare const AUTO_COMPACT_HOOK_MARKER = "peaks:auto-compact-hook-do-not-edit";
+/**
+ * Default on-disk location — kept here (not in claude-settings-template)
+ * because the auto-compact hook is a separate install surface from
+ * the fact-forcing gate bypass template.
+ */
+export declare const AUTO_COMPACT_HOOK_SETTINGS_PATH = ".claude/settings.local.json";
+/**
+ * Result envelope for `installAutoCompactHook`.
+ */
+export type AutoCompactHookInstallResult = {
+    readonly action: 'installed';
+    readonly settingsPath: string;
+} | {
+    readonly action: 'already-installed';
+    readonly settingsPath: string;
+};
+/**
+ * Result envelope for `removeAutoCompactHook`.
+ */
+export type AutoCompactHookRemoveResult = {
+    readonly action: 'removed';
+    readonly settingsPath: string;
+} | {
+    readonly action: 'absent';
+    readonly settingsPath: string;
+};
+/**
+ * Install the auto-compact PreToolUse hook. Idempotent: a re-run
+ * returns `action: 'already-installed'` and does NOT re-write the
+ * file (preserves any unrelated edits the user has made to other
+ * entries).
+ */
+export declare function installAutoCompactHook(input: {
+    readonly projectRoot: string;
+    readonly settingsPath?: string;
+}): AutoCompactHookInstallResult;
+/**
+ * Remove the auto-compact PreToolUse hook. Idempotent: missing hook
+ * returns `action: 'absent'` without re-writing the file.
+ *
+ * Other PreToolUse entries are left untouched. The settings file
+ * structure is preserved (top-level keys like `permissions` are not
+ * deleted).
+ */
+export declare function removeAutoCompactHook(input: {
+    readonly projectRoot: string;
+    readonly settingsPath?: string;
+}): AutoCompactHookRemoveResult;

package/dist/services/hooks/auto-compact-hook-install.js

@@ -0,0 +1,157 @@
+/**
+ * Slice 2026-07-02-auto-compact-zero-pause — `ide-native` pathway
+ * hook install/remove service.
+ *
+ * Writes the auto-compact PreToolUse hook into the consumer
+ * project's `.claude/settings.local.json` so the next Bash or Task
+ * tool call from the running Claude Code session reads
+ * `CLAUDE_CONTEXT_USAGE_PERCENT` and, at ratio ≥ 0.95, in-band fires
+ * `claude --compact` against the current runner (not a child process).
+ *
+ * Idempotency contract:
+ *   - install is idempotent — calling `installAutoCompactHook`
+ *     twice produces a byte-identical file (after stripping the
+ *     magic comment). The on-disk matcher entry is the single
+ *     source of truth.
+ *   - remove is idempotent — calling `removeAutoCompactHook` when
+ *     the hook is absent is a no-op.
+ *   - other PreToolUse entries are untouched on install AND remove.
+ *
+ * Magic comment marker: `peaks:auto-compact-hook-do-not-edit`. The
+ * comment sits next to the matcher entry so a human reading the file
+ * sees the boundary; an automated diff/remove op keys off the marker
+ * + the `matcher` regex.
+ *
+ * Pure data + minimal IO: `installAutoCompactHook` and
+ * `removeAutoCompactHook` accept `settingsPath` so callers can pick
+ * `.claude/settings.local.json` (default) or pass an explicit path
+ * for tests. The functions write to disk via `fs.writeFileSync` so
+ * the on-disk file matches the in-memory template byte-for-byte
+ * (modulo the magic comment which is excluded from the data
+ * structure; see `AUTO_COMPACT_HOOK_MATCHER`).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+/**
+ * Stable matcher for the auto-compact hook. Single source of truth
+ * — `install` and `remove` both key off this constant so the
+ * invariants can't drift between the two paths.
+ */
+export const AUTO_COMPACT_HOOK_MATCHER = 'Bash|Task';
+/**
+ * Stable command the hook fires. Wraps `peaks session
+ * auto-compact-hook` so the heavy lifting (ratio probe + in-band
+ * `claude --compact` spawn) lives in the CLI surface, not inlined
+ * into the hook.
+ *
+ * `npx peaks` is deliberately omitted: the project-local install
+ * puts `peaks` on PATH inside the consumer repo (postinstall step),
+ * so the unqualified command works in the same shell the runner
+ * is using.
+ */
+export const AUTO_COMPACT_HOOK_COMMAND = 'peaks session auto-compact-hook';
+/**
+ * Magic comment marker that fences the auto-compatchook block.
+ * Both install (writes the marker) and remove (matches on it) use
+ * this string so the comment is the only place the boundary lives.
+ */
+export const AUTO_COMPACT_HOOK_MARKER = 'peaks:auto-compact-hook-do-not-edit';
+/**
+ * Default on-disk location — kept here (not in claude-settings-template)
+ * because the auto-compact hook is a separate install surface from
+ * the fact-forcing gate bypass template.
+ */
+export const AUTO_COMPACT_HOOK_SETTINGS_PATH = '.claude/settings.local.json';
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    try {
+        const raw = readFileSync(settingsPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        return isObject(parsed) ? parsed : {};
+    }
+    catch {
+        // Malformed JSON → start fresh so install doesn't error. The
+        // caller is the human / CLI, not an LLM (idempotency matters
+        // more than preserve-on-corruption here).
+        return {};
+    }
+}
+function writeSettings(settingsPath, settings) {
+    const dir = dirname(settingsPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    // 2-space JSON matches the existing template writer's style so
+    // `diff` against pre-install files is minimal.
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+function isAutoCompactEntry(entry) {
+    return entry.matcher === AUTO_COMPACT_HOOK_MATCHER;
+}
+/**
+ * Install the auto-compact PreToolUse hook. Idempotent: a re-run
+ * returns `action: 'already-installed'` and does NOT re-write the
+ * file (preserves any unrelated edits the user has made to other
+ * entries).
+ */
+export function installAutoCompactHook(input) {
+    const settingsPath = input.settingsPath ?? join(input.projectRoot, AUTO_COMPACT_HOOK_SETTINGS_PATH);
+    const settings = readSettings(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const alreadyInstalled = preToolUse.some(isAutoCompactEntry);
+    if (alreadyInstalled) {
+        return { action: 'already-installed', settingsPath };
+    }
+    const nextPreToolUse = [
+        ...preToolUse,
+        {
+            matcher: AUTO_COMPACT_HOOK_MATCHER,
+            hooks: [
+                {
+                    type: 'command',
+                    command: AUTO_COMPACT_HOOK_COMMAND
+                }
+            ]
+        }
+    ];
+    writeSettings(settingsPath, {
+        ...settings,
+        hooks: {
+            ...hooks,
+            PreToolUse: nextPreToolUse
+        }
+    });
+    return { action: 'installed', settingsPath };
+}
+/**
+ * Remove the auto-compact PreToolUse hook. Idempotent: missing hook
+ * returns `action: 'absent'` without re-writing the file.
+ *
+ * Other PreToolUse entries are left untouched. The settings file
+ * structure is preserved (top-level keys like `permissions` are not
+ * deleted).
+ */
+export function removeAutoCompactHook(input) {
+    const settingsPath = input.settingsPath ?? join(input.projectRoot, AUTO_COMPACT_HOOK_SETTINGS_PATH);
+    if (!existsSync(settingsPath))
+        return { action: 'absent', settingsPath };
+    const settings = readSettings(settingsPath);
+    const hooks = settings.hooks ?? {};
+    const preToolUse = hooks.PreToolUse ?? [];
+    const nextPreToolUse = preToolUse.filter((entry) => !isAutoCompactEntry(entry));
+    if (nextPreToolUse.length === preToolUse.length) {
+        return { action: 'absent', settingsPath };
+    }
+    writeSettings(settingsPath, {
+        ...settings,
+        hooks: {
+            ...hooks,
+            PreToolUse: nextPreToolUse
+        }
+    });
+    return { action: 'removed', settingsPath };
+}