peaks-loop 3.0.0 → 3.0.1

package/dist/src/cli/commands/compact-command.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `peaks compact *` — strategic-compact CLI primitives.
+ *
+ * Slice 2026-07-01-strategic-compact-cli. Five subcommands under a new
+ * top-level `peaks compact` group:
+ *
+ *   - suggest:    PreToolUse-style two-signal suggestion (context size
+ *                 + tool-call count), read-only by default.
+ *   - recommend:  Pure (from, to) phase-pair → severity lookup.
+ *   - survival:   Static SKILL.md "What Survives Compaction" table.
+ *   - dry-run:    Composite of (suggest + recommend + survival), no
+ *                 writes.
+ *   - force:      Write a pre-compact checkpoint via
+ *                 `peaks session checkpoint`; the IDE-side `/compact`
+ *                 is still the LLM's call.
+ *
+ * Each subcommand returns a `--json` envelope via `printResult`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCompactCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/compact-command.js

@@ -0,0 +1,252 @@
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { fail, ok, getErrorMessage } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { writeCheckpoint } from '../../services/session/session-checkpoint-service.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+import { buildRecommendEnvelopePure, dryRunCompact, suggestCompact } from '../../services/compact/suggest-service.js';
+import { PHASES, SURVIVAL_TABLE, isPhase, lookupPhaseTransition } from '../../services/compact/decision-tables.js';
+function splitList(value) {
+    if (!value)
+        return [];
+    return value
+        .split(/\r?\n/)
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function resolveSessionId(projectRoot, explicit) {
+    if (explicit !== undefined && explicit.length > 0) {
+        return { sid: explicit, error: null };
+    }
+    // Statically-imported `getSessionIdCanonical` (see import block
+    // at the top of this file). It is the single source of truth for
+    // "what session is bound to this project"; we use it instead of
+    // re-implementing the resolution here to keep one fix point when
+    // the binding layout changes.
+    const sid = getSessionIdCanonical(projectRoot) ?? null;
+    if (sid === null) {
+        return {
+            sid: null,
+            error: {
+                code: 'NO_ACTIVE_SESSION',
+                message: 'No active session bound. Run `peaks workspace init --project <repo> --json` to bind one.',
+                nextActions: [`peaks workspace init --project ${projectRoot} --json`]
+            }
+        };
+    }
+    return { sid, error: null };
+}
+export function registerCompactCommands(program, io) {
+    const compact = program
+        .command('compact')
+        .description('Strategic-compact primitives: suggest / recommend / survival / dry-run / force');
+    // -----------------------------------------------------------------
+    // 1. peaks compact suggest [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('suggest')
+        .description('Two-signal suggestion (context-size + tool-call-count). ' +
+        'Honor COMPACT_THRESHOLD / COMPACT_CONTEXT_THRESHOLD / COMPACT_CONTEXT_INTERVAL env vars. ' +
+        'Read-only by default; pass --apply to also append a one-line info row to the session log.')
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id (defaults to the canonical binding)')
+        .option('--apply', 'append a one-line info row to .peaks/_runtime/<sid>/session.json (default: dry-run)')).action((options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? resolveCanonicalProjectRoot(options.project)
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const session = resolveSessionId(projectRoot, options.sessionId);
+            if (session.error !== null) {
+                printResult(io, fail('compact.suggest', session.error.code, session.error.message, { projectRoot }, session.error.nextActions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const result = suggestCompact({
+                projectRoot,
+                sessionId: session.sid
+            });
+            printResult(io, ok('compact.suggest', result, [], [
+                result.shouldSuggest
+                    ? `Run \`peaks compact force --reason "<short note>"\` to checkpoint, then /compact.`
+                    : `Context at ${(result.ratio * 100).toFixed(1)}% (${result.tokensUsed} of ${result.windowKind === '1m' ? '1M' : '200k'}); below threshold.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.suggest', 'COMPACT_SUGGEST_FAILED', getErrorMessage(error), {}, ['Verify project root and session binding before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 2. peaks compact recommend --from <phase> --to <phase> [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('recommend')
+        .description(`Strategic-compact "Compaction Decision Guide" lookup. ` +
+        `Valid phases: ${PHASES.join(', ')}. Pure function over (from, to); no I/O.`)
+        .requiredOption('--from <phase>', `source phase (one of ${PHASES.join(', ')})`)
+        .requiredOption('--to <phase>', `target phase (one of ${PHASES.join(', ')})`)).action((options) => {
+        try {
+            if (!isPhase(options.from)) {
+                printResult(io, fail('compact.recommend', 'INVALID_PHASE', `--from must be one of ${PHASES.join(', ')} (got "${options.from}")`, { from: options.from }, [`Use --from ${PHASES.join('|')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!isPhase(options.to)) {
+                printResult(io, fail('compact.recommend', 'INVALID_PHASE', `--to must be one of ${PHASES.join(', ')} (got "${options.to}")`, { to: options.to }, [`Use --to ${PHASES.join('|')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const envelope = buildRecommendEnvelopePure(options.from, options.to);
+            const lookup = lookupPhaseTransition(options.from, options.to);
+            printResult(io, ok('compact.recommend', {
+                from: envelope.from,
+                to: envelope.to,
+                shouldCompact: envelope.shouldCompact,
+                severity: envelope.severity,
+                rationale: envelope.rationale,
+                suggestedMessage: envelope.suggestedMessage,
+                notInTable: lookup.notInTable
+            }, lookup.notInTable ? [`Transition ${options.from} → ${options.to} is not in the strategic-compact table; defaulting to severity=no.`] : []), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.recommend', 'COMPACT_RECOMMEND_FAILED', getErrorMessage(error), { from: options.from, to: options.to }, ['Verify the phase pair against the documented transitions']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 3. peaks compact survival [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('survival')
+        .description('Strategic-compact "What Survives Compaction" table. Pure static data; no I/O.')).action((options) => {
+        printResult(io, ok('compact.survival', {
+            persists: [...SURVIVAL_TABLE.persists],
+            lost: [...SURVIVAL_TABLE.lost]
+        }, [], [
+            'Persists = guaranteed across `/compact`. Lost = not preserved; persist to disk before compacting.'
+        ]), options.json);
+    });
+    // -----------------------------------------------------------------
+    // 4. peaks compact dry-run [--from <phase>] [--to <phase>] [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('dry-run')
+        .description('Composite preview of (suggest + recommend + survival). ' +
+        'No writes. The LLM calls this every tool-call cycle to stay informed.')
+        .option('--from <phase>', `optional source phase for recommend lookup (one of ${PHASES.join(', ')})`)
+        .option('--to <phase>', `optional target phase for recommend lookup (one of ${PHASES.join(', ')})`)
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id')).action((options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? resolveCanonicalProjectRoot(options.project)
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const session = resolveSessionId(projectRoot, options.sessionId);
+            if (session.error !== null) {
+                printResult(io, fail('compact.dry-run', session.error.code, session.error.message, { projectRoot }, session.error.nextActions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if ((options.from === undefined) !== (options.to === undefined)) {
+                printResult(io, fail('compact.dry-run', 'PHASE_PAIR_INCOMPLETE', 'Both --from and --to must be provided together', { from: options.from, to: options.to }, ['Pass both --from and --to, or omit both for a suggest-only dry-run']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (options.from !== undefined && !isPhase(options.from)) {
+                printResult(io, fail('compact.dry-run', 'INVALID_PHASE', `--from must be one of ${PHASES.join(', ')} (got "${options.from}")`, { from: options.from }, [`Use --from ${PHASES.join('|')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (options.to !== undefined && !isPhase(options.to)) {
+                printResult(io, fail('compact.dry-run', 'INVALID_PHASE', `--to must be one of ${PHASES.join(', ')} (got "${options.to}")`, { to: options.to }, [`Use --to ${PHASES.join('|')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const hasPhasePair = options.from !== undefined && options.to !== undefined;
+            const dryRunInput = {
+                projectRoot,
+                sessionId: session.sid
+            };
+            if (hasPhasePair) {
+                dryRunInput.from = options.from;
+                dryRunInput.to = options.to;
+            }
+            const result = dryRunCompact(dryRunInput);
+            printResult(io, ok('compact.dry-run', result, [], [
+                result.action === 'compact'
+                    ? `Action=compact: run \`peaks compact force --reason "<note>"\`, then /compact.`
+                    : `Action=skip: continue without compacting.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.dry-run', 'COMPACT_DRY_RUN_FAILED', getErrorMessage(error), {}, ['Verify project root, session binding, and phase pair before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 5. peaks compact force [--reason <text>] [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(compact
+        .command('force')
+        .description('Write a pre-compact checkpoint via `peaks session checkpoint --reason context-fill`. ' +
+        'The IDE-side `/compact` is still the LLM\'s call; this primitive guarantees ' +
+        'the pre-compact state is persisted. NO sleep, NO wait for IDE response.')
+        .option('--reason <text>', 'human-readable reason for the pre-compact checkpoint', 'pre-force-compact')
+        .option('--project <path>', 'project root (defaults to git root or cwd)')
+        .option('--session-id <sid>', 'override the active session id')
+        .option('--current-plan <text>', 'current plan summary (forwarded to the checkpoint snapshot)')
+        .option('--open-questions <list>', 'newline-separated open questions')
+        .option('--recent-decisions <list>', 'newline-separated recent decisions')
+        .option('--recent-artifact-paths <list>', 'newline-separated recent artifact paths')
+        .option('--git-status <text>', 'recent git status')
+        .option('--skills-active <list>', 'newline-separated active skill names')
+        .option('--todo-state <list>', 'newline-separated todo lines')).action((options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? resolveCanonicalProjectRoot(options.project)
+                : (findProjectRoot(process.cwd()) ?? process.cwd());
+            const session = resolveSessionId(projectRoot, options.sessionId);
+            if (session.error !== null) {
+                printResult(io, fail('compact.force', session.error.code, session.error.message, { projectRoot }, session.error.nextActions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const reason = (options.reason ?? 'pre-force-compact').slice(0, 200);
+            // The session-checkpoint-service restricts `reason` to a fixed
+            // enum. The strategic-compact `force` primitive uses
+            // 'context-fill' (the closest semantic match: the LLM is
+            // compacting because of context pressure) and records the
+            // caller's free-form reason in `gitStatus` so the snapshot
+            // is self-describing without inventing a new enum value.
+            const checkpointOptions = {
+                sessionId: session.sid,
+                reason: 'context-fill',
+                gitStatus: `compact.force: ${reason}`,
+                openQuestions: splitList(options.openQuestions),
+                recentDecisions: splitList(options.recentDecisions),
+                recentArtifactPaths: splitList(options.recentArtifactPaths),
+                skillsActive: splitList(options.skillsActive),
+                todoState: splitList(options.todoState)
+            };
+            if (options.currentPlan !== undefined) {
+                checkpointOptions.currentPlan = options.currentPlan;
+            }
+            const result = writeCheckpoint(projectRoot, checkpointOptions);
+            printResult(io, ok('compact.force', {
+                checkpointPath: result.path,
+                reason: 'pre-force-compact',
+                callerReason: reason,
+                sessionId: result.sessionId,
+                createdAt: result.createdAt,
+                totalRetained: result.totalRetained,
+                message: 'Pre-compact checkpoint written. The IDE-side /compact is still the LLM\'s call; this CLI does NOT invoke the IDE slash command.'
+            }, [], [
+                'After the LLM fires the IDE-side /compact, call `peaks compact survival` to see what to persist before the next compact.'
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('compact.force', 'COMPACT_FORCE_FAILED', getErrorMessage(error), {}, ['Verify the project path is writable and a session is bound']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/src/cli/commands/context-commands.d.ts

@@ -1,7 +1,7 @@
 /**
  * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
  *
- * Per docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §4 L1c:
+ * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4 L1c:
  *   - L0: full read (every SKILL.md in full)
  *   - L1: summary (one paragraph per skill + the skill list)
  *   - L2: index (just names + paths)

package/dist/src/cli/commands/context-commands.js

@@ -1,7 +1,7 @@
 /**
  * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
  *
- * Per docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §4 L1c:
+ * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4 L1c:
  *   - L0: full read (every SKILL.md in full)
  *   - L1: summary (one paragraph per skill + the skill list)
  *   - L2: index (just names + paths)

package/dist/src/cli/commands/contract-commands.d.ts

@@ -14,7 +14,7 @@
  * `src/services/dispatch/contract-store.ts`; it accepts the same
  * shape, splits the comma-separated `--exports` / `--types` /
  * `--signatures` flag values into arrays, and surfaces the result
- * via the standard `ok` / `fail` envelope used across peaks-cli.
+ * via the standard `ok` / `fail` envelope used across peaks-loop.
  *
  * Skill-first / CLI-auxiliary red line: users do not invoke this
  * directly. The peaks-solo / peaks-rd LLM-side runner (the

package/dist/src/cli/commands/core/session-command.js

@@ -5,6 +5,14 @@ import { resolveCanonicalProjectRoot } from '../../../services/config/config-ser
 import { findProjectRoot } from '../../../services/config/config-safety.js';
 import { fail, ok } from '../../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.js';
+// Slice 2026-07-01-strategic-compact-cli fix: register the
+// `peaks session checkpoint` and `peaks session resume` subcommands
+// EAGERLY so they appear in `peaks session --help` output. The
+// previous lazy import ran AFTER commander had already produced
+// the help text, so an LLM calling `peaks <TAB>`-discovery never
+// saw them — they were effectively hidden.
+import { registerSessionCheckpointCommand } from '../session-checkpoint-command.js';
+import { registerSessionResumeCommand } from '../session-resume-command.js';
 export function registerSessionCommand(program, io) {
     const session = program.command('session').description('Manage Peaks session directories');
     addJsonOption(session
@@ -169,13 +177,15 @@ export function registerSessionCommand(program, io) {
     });
     // Slice 011: `peaks session checkpoint` and `peaks session resume`.
     // Skill-level primitives — the LLM is the decision-maker; CLI is the muscle.
-    // Lazy-import to avoid circular resolution with the session-manager.
-    void (async () => {
-        const { registerSessionCheckpointCommand } = await import('../session-checkpoint-command.js');
-        const { registerSessionResumeCommand } = await import('../session-resume-command.js');
-        registerSessionCheckpointCommand(session, io);
-        registerSessionResumeCommand(session, io);
-    })();
+    // Slice 2026-07-01-strategic-compact-cli fix: register EAGERLY (not
+    // via `void (async () => …)`) so commander walks the subcommand
+    // tree synchronously and `peaks session --help` includes both
+    // `checkpoint` and `resume`. The previous async-IIFE registered
+    // them on a microtask tick AFTER the program-level help builder
+    // had already serialised its output, so they were hidden from
+    // `<TAB>`-discovery and the LLM never saw them.
+    registerSessionCheckpointCommand(session, io);
+    registerSessionResumeCommand(session, io);
     addJsonOption(session
         .command('rotate')
         .description('Drop the project-level session binding so the next peaks call auto-generates a fresh session id. The on-disk session directory is left intact — only .peaks/.session.json is removed.')

package/dist/src/cli/commands/core/skill-command.js

@@ -264,7 +264,7 @@ export function registerSkillCommand(program, io) {
     });
     addJsonOption(skill
         .command('detect-marker-loss')
-        .description('Detect whether the latest assistant message lost the Peaks-Cli status header while a peaks skill is still active (slice 028 detection primitive).')
+        .description('Detect whether the latest assistant message lost the Peaks-Loop status header while a peaks skill is still active (slice 028 detection primitive).')
         .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
         .option('--message <text>', 'latest assistant message text to scan (defaults to reading the most recent LLM response from the stdin pipe, or empty string when no pipe is attached)')).action((options) => {
         const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();

package/dist/src/cli/commands/feedback-commands.js

@@ -22,7 +22,7 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 export function registerFeedbackCommands(program, io) {
     const feedback = program
         .command('feedback')
-        .description('v2.15.0 slice 002 AC-3: promote user-given feedback memories to peaks-cli enforcement layers (A: sop, B: hooks, C: hard-floor).');
+        .description('v2.15.0 slice 002 AC-3: promote user-given feedback memories to peaks-loop enforcement layers (A: sop, B: hooks, C: hard-floor).');
     addJsonOption(feedback
         .command('promote <memory-file>')
         .description('Promote a feedback memory to one of the 3 enforcement layers (A=peaks-sop gate, B=peaks-hooks PreToolUse, C=mode-gate hardFloorCategory). ' +

package/dist/src/cli/commands/hook-handle.d.ts

@@ -3,7 +3,7 @@ import { type ProgramIO } from '../cli-helpers.js';
 /**
  * `peaks hook handle` —— peaks 自有 hook 协议的单一入口。
  *
- * 该命令是 peaks-cli 拥有的 hook 处理总入口。它:
+ * 该命令是 peaks-loop 拥有的 hook 处理总入口。它:
  *   1. 读 stdin
  *   2. auto-detect 来源 IDE(env / stdin shape / cwd)
  *   3. 归一化到 peaks canonical schema

package/dist/src/cli/commands/hook-handle.js

@@ -31,7 +31,7 @@ async function readStdin() {
 /**
  * `peaks hook handle` —— peaks 自有 hook 协议的单一入口。
  *
- * 该命令是 peaks-cli 拥有的 hook 处理总入口。它:
+ * 该命令是 peaks-loop 拥有的 hook 处理总入口。它:
  *   1. 读 stdin
  *   2. auto-detect 来源 IDE(env / stdin shape / cwd)
  *   3. 归一化到 peaks canonical schema

package/dist/src/cli/commands/legacy-commands.d.ts

@@ -3,7 +3,7 @@
  *
  *   - `peaks legacy detect --dir <path>` — scan a directory for legacy
  *     smells (TODO/FIXME/HACK, console.log, any-type, large files, ts-ignore).
- *     Useful as a "where to start" inventory when peaks-cli is applied
+ *     Useful as a "where to start" inventory when peaks-loop is applied
  *     to a 存量老项目.
  */
 import type { Command } from 'commander';

package/dist/src/cli/commands/legacy-commands.js

@@ -3,7 +3,7 @@
  *
  *   - `peaks legacy detect --dir <path>` — scan a directory for legacy
  *     smells (TODO/FIXME/HACK, console.log, any-type, large files, ts-ignore).
- *     Useful as a "where to start" inventory when peaks-cli is applied
+ *     Useful as a "where to start" inventory when peaks-loop is applied
  *     to a 存量老项目.
  */
 import { findProjectRoot } from '../../services/config/config-safety.js';
@@ -17,7 +17,7 @@ export function registerLegacyCommands(program, io) {
         'console.log, any-type, large files, ts-ignore). Returns a smell grade ' +
         '(low / medium / high) and per-kind counts. Lightweight heuristics — ' +
         'NOT a replacement for a real linter. Useful as a "where to start" ' +
-        'inventory when peaks-cli is applied to a legacy codebase.')
+        'inventory when peaks-loop is applied to a legacy codebase.')
         .option('--dir <path>', 'directory to scan (default: src)', 'src')
         .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
         const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();

package/dist/src/cli/commands/log-commands.js

@@ -20,10 +20,10 @@ import { ok, fail } from '../../shared/result.js';
 export function registerLogCommands(program, io) {
     const log = program
         .command('log')
-        .description('Inspect the peaks-cli JSONL log directory (default: ~/.peaks/logs/)');
+        .description('Inspect the peaks-loop JSONL log directory (default: ~/.peaks/logs/)');
     addJsonOption(log
         .command('tail')
-        .description('Print the last 50 lines of today\'s peaks-cli log (JSONL). Pass --lines N to change the count, --date YYYY-MM-DD to read a different day, --batch <id> to filter by batchId, --json to print a JSON envelope.')
+        .description('Print the last 50 lines of today\'s peaks-loop log (JSONL). Pass --lines N to change the count, --date YYYY-MM-DD to read a different day, --batch <id> to filter by batchId, --json to print a JSON envelope.')
         .option('--lines <n>', 'number of lines to show (default 50)', (value) => Number(value))
         .option('--date <YYYY-MM-DD>', 'read the log for this UTC date instead of today (PRD AC2: PEAKS_LOG_DATE_OVERRIDE)')
         // Slice 2026-06-23-audit-4th #B2: --batch filter for cross-run

package/dist/src/cli/commands/loop-commands.d.ts

@@ -1,7 +1,7 @@
 /**
  * peaks loop * CLI (Slice #14) — L4 Agent Loop Integration.
  *
- * Per docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5.4
+ * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §5.4
  * Slice #14, ships 5 sub-features:
  *
  *   14.1 peaks loop distill          — extract patterns from past sessions

package/dist/src/cli/commands/loop-commands.js

@@ -1,7 +1,7 @@
 /**
  * peaks loop * CLI (Slice #14) — L4 Agent Loop Integration.
  *
- * Per docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5.4
+ * Per docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §5.4
  * Slice #14, ships 5 sub-features:
  *
  *   14.1 peaks loop distill          — extract patterns from past sessions

package/dist/src/cli/commands/loop-eval-commands.d.ts

@@ -5,7 +5,7 @@
  *
  * New commands (added under the existing `peaks workflow` group and the
  * existing `peaks loop` group — never as new top-level commands, per the
- * peaks-cli add-a-new-subcommand-check-for-existing-top-level-first rule):
+ * peaks-loop add-a-new-subcommand-check-for-existing-top-level-first rule):
  *
  *   peaks workflow run <id> --session <sid> --project <repo> --json
  *   peaks workflow plan <id> --session <sid> --json   (dry-run)

package/dist/src/cli/commands/loop-eval-commands.js

@@ -199,7 +199,7 @@ export function registerWorkflowEvalCommands(program, io) {
                 ...(capture !== null ? { score: capture.score, capture } : {})
             }, [], envelope.degraded
                 ? ['Evaluator ran in degraded mode (peaks CLI unavailable). Verify the verdict by running `peaks verdict aggregate --from-rid ' + rid + '`.',
-                    'Re-run on a fully-installed peaks-cli environment for a real verdict.']
+                    'Re-run on a fully-installed peaks-loop environment for a real verdict.']
                 : [`Verifier verdict-aggregate can consume this envelope via \`peaks verdict aggregate --from-rid ${rid}\`.`]), options.json);
             process.exitCode = exitCode;
         }

package/dist/src/cli/commands/playwright-commands.d.ts

@@ -25,7 +25,7 @@
  *   3. hash(process.ppid + process.env.SSH_TTY || 'no-tty')
  *
  * The CLI does NOT bundle `playwright-mcp`; it shells out to
- * `npx playwright-mcp@latest` (G22 / NG3). peaks-cli is the lifecycle
+ * `npx playwright-mcp@latest` (G22 / NG3). peaks-loop is the lifecycle
  * orchestrator, not the install medium.
  */
 import { spawn } from 'node:child_process';

package/dist/src/cli/commands/playwright-commands.js

@@ -25,7 +25,7 @@
  *   3. hash(process.ppid + process.env.SSH_TTY || 'no-tty')
  *
  * The CLI does NOT bundle `playwright-mcp`; it shells out to
- * `npx playwright-mcp@latest` (G22 / NG3). peaks-cli is the lifecycle
+ * `npx playwright-mcp@latest` (G22 / NG3). peaks-loop is the lifecycle
  * orchestrator, not the install medium.
  */
 import { createHash } from 'node:crypto';
@@ -428,5 +428,5 @@ export function resolveUserDataDir(raw, projectRoot) {
  * the `runBrowserAction(..., caller)` overload.
  */
 async function mockOrPassThroughCaller(tool, args) {
-    return { tool, args, routedBy: 'peaks-cli-browser-wrapper' };
+    return { tool, args, routedBy: 'peaks-loop-browser-wrapper' };
 }

package/dist/src/cli/commands/request-commands.js

@@ -342,6 +342,33 @@ export function registerRequestCommands(program, io) {
                 process.exitCode = 1;
                 return;
             }
+            // Slice 2026-07-01-strategic-compact-cli — slice-boundary pre-compact
+            // hook. When transitioning across the RD → QA boundary (rd:qa-handoff),
+            // check the active session's context-fill ratio. If it is in the
+            // 0.85–0.95 pre-compact zone, write a checkpoint BEFORE the
+            // transition completes and attach `preCompactCheckpoint: true` to
+            // the response envelope. The LLM remains the decision-maker; this
+            // hook only surfaces the signal. The 0.95 red-line behaviour is
+            // unchanged — the existing auto-compact orchestrator continues to
+            // refuse dispatch at ratio ≥ 0.95.
+            let preCompact = null;
+            if (role === 'rd' && newState === 'qa-handoff') {
+                try {
+                    const { maybePreCompactCheckpoint } = await import('../../services/compact/request-transition-hook.js');
+                    const hook = maybePreCompactCheckpoint({
+                        projectRoot: options.project,
+                        sessionId: result.sessionId,
+                        transitionKey: `${role}:${newState}`
+                    });
+                    preCompact = hook.triggered
+                        ? ok('request.transition.preCompact', hook)
+                        : null;
+                }
+                catch {
+                    // The hook is best-effort; never block the transition.
+                    preCompact = null;
+                }
+            }
             // v2.13.2 AC-4 — auto-regen prd/handoff.md on prd:handed-off success.
             // Only fires when the handoff is missing; existing handoffs are not overwritten.
             if (role === 'prd' && newState === 'handed-off' && options.sessionId !== undefined) {
@@ -365,7 +392,19 @@ export function registerRequestCommands(program, io) {
                 printResult(io, ok('request.transition', { ...result, handoffAutoRegen: { status: 'failed', reason: regen.reason } }, [`prd handoff auto-regen failed: ${regen.reason}`]), options.json);
                 return;
             }
-            printResult(io, ok('request.transition', result), options.json);
+            // Slice 2026-07-01-strategic-compact-cli: stitch the pre-compact
+            // checkpoint signal into the final response envelope. When the
+            // hook did not trigger (zone is not pre-compact OR the
+            // transition is not a slice boundary), preCompact is null and
+            // we emit a `preCompactCheckpoint: null` field so LLM callers
+            // can branch on it without re-deriving zone membership.
+            printResult(io, ok('request.transition', { ...result, preCompactCheckpoint: preCompact?.data ?? null }, preCompact !== null
+                ? [
+                    `Pre-compact checkpoint written at ratio=${typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
+                        ? String(preCompact.data.ratio)
+                        : 'unknown'} (zone=pre-compact)`
+                ]
+                : []), options.json);
         }
         catch (error) {
             if (error instanceof InvalidArgumentError) {

package/dist/src/cli/commands/role-commands.js

@@ -15,7 +15,7 @@ import { addJsonOption, printResult } from '../cli-helpers.js';
 export function registerRoleCommands(program, io) {
     const role = program
         .command('role')
-        .description('v2.15.0 follow-up G9: lightweight role registry (RBAC for multi-user peaks-cli teams).');
+        .description('v2.15.0 follow-up G9: lightweight role registry (RBAC for multi-user peaks-loop teams).');
     addJsonOption(role
         .command('list')
         .description('List all roles in the registry.')

package/dist/src/cli/commands/slice-commands.js

@@ -133,7 +133,7 @@ export function registerSliceCommands(program, io) {
         .option('--project <path>', 'target project root', '.')
         .option('--refresh', 're-run `peaks codegraph index` before reading', false)
         .option('--benchmark', 'record per-run metrics and attach to the result envelope (2.1.1 algorithm optimization comparison)', false)
-        .option('--granularity <value>', 'service | file | both | auto. Default "both" keeps the v1 6-stage path; service / file / auto enable v2 multi-pass decomposition (peaks-cli 2.9+) and emit a DecompositionResultV2 envelope via SchemaRouter', 'both')).action(async (rid, options) => {
+        .option('--granularity <value>', 'service | file | both | auto. Default "both" keeps the v1 6-stage path; service / file / auto enable v2 multi-pass decomposition (peaks-loop 2.9+) and emit a DecompositionResultV2 envelope via SchemaRouter', 'both')).action(async (rid, options) => {
         // Validate --granularity BEFORE any I/O so invalid values fail fast with a
         // nextActions hint listing the four allowed strings.
         const granularity = options.granularity ?? 'both';
@@ -144,7 +144,7 @@ export function registerSliceCommands(program, io) {
             printResult(io, fail('slice.decompose', 'SLICE_DECOMPOSE_FAILED', `Invalid --granularity '${options.granularity}'.`, { rid, projectRoot: options.project }, [
                 `--granularity accepts one of: service, file, both, auto`,
                 `Default (omit the flag or pass "both") keeps the existing v1 path.`,
-                `Non-default values (service / file / auto) enable v2 multi-pass decomposition (peaks-cli 2.9+).`
+                `Non-default values (service / file / auto) enable v2 multi-pass decomposition (peaks-loop 2.9+).`
             ]), options.json ?? false);
             process.exitCode = 1;
             return;
@@ -166,7 +166,7 @@ export function registerSliceCommands(program, io) {
                 writeSchemaResult(outPath, v2Result);
                 const nextActions = [
                     `Decomposition (v2) written to ${outPath}`,
-                    `peaks slice pick/plan: v2 schemas require SchemaRouter-aware consumers (peaks-cli 2.9+).`
+                    `peaks slice pick/plan: v2 schemas require SchemaRouter-aware consumers (peaks-loop 2.9+).`
                 ];
                 printResult(io, ok('slice.decompose', { ...v2Result, outputPath: outPath }, [], nextActions), options.json ?? false);
                 return;
@@ -230,9 +230,9 @@ export function registerSliceCommands(program, io) {
             const parsed = readDecompositionResult(decompPath);
             if ('schemaVersion' in parsed) {
                 throw new Error(`decomposition at ${decompPath} is a v2 envelope (schemaVersion: 'v2'). ` +
-                    `peaks slice pick supports v1 only in peaks-cli 2.9.0. ` +
+                    `peaks slice pick supports v1 only in peaks-loop 2.9.0. ` +
                     `Re-run \`peaks slice decompose ${rid}\` without --granularity to get a v1 file, ` +
-                    `or upgrade peaks-cli when v2 pick lands.`);
+                    `or upgrade peaks-loop when v2 pick lands.`);
             }
             const decomposition = parsed;
             const result = await pickSlicesInteractive(rid, decomposition, projectRoot, {

package/dist/src/cli/commands/upgrade-commands.d.ts

@@ -4,7 +4,7 @@
  *
  * Per the "one-key completion" + "minimal-user-operation" tenets
  * (2026-06-11), the user's typical upgrade path is
- * `npm i -g peaks-cli@2.0` (the postinstall does the upgrade).
+ * `npm i -g peaks-loop@2.0` (the postinstall does the upgrade).
  *
  * The `peaks upgrade --to 2.0` CLI is the manual fallback for
  * when the postinstall is skipped (e.g. CI uses