peaks-loop 3.0.0 → 3.0.2

package/dist/src/services/code-review/ocr-service.js

@@ -13,9 +13,9 @@
  *   - same multi-state reason enum (clear failure-mode reporting),
  *   - same soft-fail policy (never blocks the umbrella).
  *
- * === Source of truth: peaks-cli's own config.json ===
+ * === Source of truth: peaks-loop's own config.json ===
  *
- * peaks-cli does NOT auto-configure the LLM endpoint, and it does
+ * peaks-loop does NOT auto-configure the LLM endpoint, and it does
  * NOT write `~/.opencodereview/config.json`. The user is the only
  * party that touches their LLM token / URL / model. The single
  * discoverable place they declare those values is
@@ -30,7 +30,7 @@
  *
  * When `runOcrReview` spawns the ocr subprocess it injects those
  * values as env vars. The ocr package treats env vars as the
- * highest-priority config source, so peaks-cli never has to
+ * highest-priority config source, so peaks-loop never has to
  * materialise `~/.opencodereview/config.json` itself.
  *
  * To see the JSON template to paste, run:
@@ -41,14 +41,14 @@
  * `optionalDependencies` in 2.0.3, then to `peerDependencies` in
  * 2.8.2 — the ocr postinstall downloads a Go binary via HTTPS,
  * which fails in restricted/proxied environments and would
- * otherwise slow or abort the whole `npm i -g peaks-cli` flow).
+ * otherwise slow or abort the whole `npm i -g peaks-loop` flow).
  * Peaks-cli ships with ocr *not* installed; if the user wants it,
  * they run
  *   `npm i -g @alibaba-group/open-code-review`
- * and peaks-cli's 5-state detector (below) reports whether the
+ * and peaks-loop's 5-state detector (below) reports whether the
  * binary is actually usable. pnpm-based installs additionally need
  * `pnpm approve-builds @alibaba-group/open-code-review` for the
- * binary download to run. Either way, peaks-cli never blocks on it.
+ * binary download to run. Either way, peaks-loop never blocks on it.
  */
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
@@ -57,7 +57,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
 const OCR_DETECT_TIMEOUT_MS = 5000;
 const OCR_REVIEW_TIMEOUT_MS = 180000;
-const OCR_INSTALL_HINT = 'Install: `npm i -g @alibaba-group/open-code-review` (peaks-cli 2.8.2 ships with ocr as a peer dependency — its postinstall downloads a Go binary via HTTPS, which fails in some restricted/proxied environments; that\'s why peaks-cli does not auto-install it). Then add your LLM endpoint to ~/.peaks/config.json — run `peaks code-review config-template` for the JSON snippet to paste. Under pnpm you also need `pnpm approve-builds @alibaba-group/open-code-review` to allow the binary download.';
+const OCR_INSTALL_HINT = 'Install: `npm i -g @alibaba-group/open-code-review` (peaks-loop 2.8.2 ships with ocr as a peer dependency — its postinstall downloads a Go binary via HTTPS, which fails in some restricted/proxied environments; that\'s why peaks-loop does not auto-install it). Then add your LLM endpoint to ~/.peaks/config.json — run `peaks code-review config-template` for the JSON snippet to paste. Under pnpm you also need `pnpm approve-builds @alibaba-group/open-code-review` to allow the binary download.';
 const OCR_CONFIG_TEMPLATE = JSON.stringify({
     ocr: {
         llm: {
@@ -98,7 +98,7 @@ const DEFAULT_RUNNER = {
 /**
  * Locate the ocr launcher script (`bin/ocr.js`) inside our own
  * node_modules tree. Returns null when the npm package is not
- * present (peaks-cli was installed but its dependency tree is
+ * present (peaks-loop was installed but its dependency tree is
  * corrupt, or the user removed it).
  *
  * Walks up from this file (dist/src/services/code-review/) to
@@ -118,7 +118,7 @@ export function resolveOcrLauncher(searchRoots) {
 }
 /**
  * Resolve search roots for the ocr launcher. We look in two
- * places: (1) the peaks-cli install root (next to our own dist/),
+ * places: (1) the peaks-loop install root (next to our own dist/),
  * (2) the user's cwd.
  */
 export function defaultOcrSearchRoots(currentDirPath, cwd) {
@@ -133,7 +133,7 @@ export function defaultOcrSearchRoots(currentDirPath, cwd) {
  * the block is ready to drive the ocr subprocess.
  *
  * The block is independent of the OCR package's own
- * `~/.opencodereview/config.json` file. peaks-cli only ever reads
+ * `~/.opencodereview/config.json` file. peaks-loop only ever reads
  * from its own config; the env-var injection in `runOcrReview`
  * makes the legacy file irrelevant.
  */
@@ -151,7 +151,7 @@ export function getOcrLlmMissingFields(llm) {
     return missing;
 }
 /**
- * Build the env-var overlay peaks-cli injects into the ocr
+ * Build the env-var overlay peaks-loop injects into the ocr
  * subprocess. Maps `peaksConfig.ocr.llm` onto the OCR package's
  * env-var surface (its highest-priority config source).
  */
@@ -170,7 +170,7 @@ export function buildOcrEnv(llm) {
     return env;
 }
 /**
- * The JSON template the user pastes into their peaks-cli config
+ * The JSON template the user pastes into their peaks-loop config
  * (`peaksConfig.ocr.llm`). Returned as a stable string so the
  * `peaks code-review config-template` CLI command can print it
  * verbatim, and so the detector's `nextActions` payload embeds
@@ -203,7 +203,7 @@ export function detectOcr(options) {
             missingKeys: missing,
             warnings,
             nextActions: [
-                '@alibaba-group/open-code-review is not installed in this project or peaks-cli root.',
+                '@alibaba-group/open-code-review is not installed in this project or peaks-loop root.',
                 OCR_INSTALL_HINT,
             ],
         };
@@ -255,7 +255,7 @@ export function detectOcr(options) {
             configValid: false,
             missingKeys: missing,
             warnings: [
-                `ocr is installed but peaks-cli's ocr.llm config is incomplete: missing ${missing.join(', ')}.`,
+                `ocr is installed but peaks-loop's ocr.llm config is incomplete: missing ${missing.join(', ')}.`,
             ],
             nextActions: [
                 `Paste the following into ${options.peaksConfigPath} under "ocr.llm":`,
@@ -285,7 +285,7 @@ export function detectOcr(options) {
  * The LLM endpoint config from `peaksConfig.ocr.llm` is injected
  * as env vars (`OCR_LLM_URL` / `OCR_LLM_TOKEN` / ...), which the
  * ocr package treats as the highest-priority config source. This
- * is how peaks-cli wires the user-managed config into the ocr
+ * is how peaks-loop wires the user-managed config into the ocr
  * subprocess without ever writing `~/.opencodereview/config.json`.
  */
 export function runOcrReview(options) {
@@ -321,7 +321,7 @@ export function runOcrReview(options) {
             nextActions: ['Re-run `peaks code-review detect-ocr --json` to refresh.'],
         };
     }
-    // Inject the LLM endpoint config from peaks-cli's config.json
+    // Inject the LLM endpoint config from peaks-loop's config.json
     // as env vars — the ocr package's highest-priority config path.
     const env = options.peaksOcrConfig === null
         ? process.env

package/dist/src/services/compact/decision-tables.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Strategic-compact decision tables (slice 2026-07-01-strategic-compact-cli).
+ *
+ * Pure data + lookup helpers. No I/O. The byte-for-byte text mirrors the
+ * "Compaction Decision Guide" + "What Survives Compaction" tables in
+ * ECC's strategic-compact SKILL.md (read-only reference at
+ * C:\Users\smallMark\.claude\plugins\cache\ecc\ecc\2.0.0\skills\strategic-compact\SKILL.md).
+ *
+ * The `peaks compact recommend` + `peaks compact survival` + `peaks
+ * compact dry-run` primitives read from these tables; any change to the
+ * upstream skill table must be mirrored here and re-asserted by the
+ * `tests/unit/cli/compact-command.test.ts` regression suite.
+ */
+export type Phase = 'research' | 'planning' | 'implementation' | 'testing' | 'debugging';
+export declare const PHASES: readonly Phase[];
+export declare function isPhase(value: string): value is Phase;
+/** Severity for a phase transition: matches the SKILL.md "Compact?" column. */
+export type Severity = 'yes' | 'maybe' | 'no';
+export interface PhaseTransitionDecision {
+    readonly from: Phase;
+    readonly to: Phase;
+    readonly severity: Severity;
+    readonly rationale: string;
+}
+/**
+ * Single source of truth for the strategic-compact "Compaction Decision
+ * Guide" table. Each row is a recommended from→to transition. The
+ * `rationale` field is the "Why" column verbatim from SKILL.md.
+ *
+ * The CLI accepts arbitrary from/to phase pairs; if the pair is not in
+ * the table (e.g. testing→implementation) the recommend primitive
+ * returns `severity: 'no'` with a `notInTable: true` flag and the
+ * default rationale "No documented transition; preserve context".
+ */
+export declare const PHASE_TRANSITIONS: readonly PhaseTransitionDecision[];
+/** Documented "no compact" rows from the SKILL.md table. */
+export declare const PHASE_NO_TRANSITIONS: readonly {
+    from: Phase;
+    to: Phase;
+    rationale: string;
+}[];
+/**
+ * SKILL.md "What Survives Compaction" table — byte-for-byte.
+ * The `peaks compact survival` primitive emits these lists verbatim.
+ */
+export declare const SURVIVAL_TABLE: Readonly<{
+    persists: readonly string[];
+    lost: readonly string[];
+}>;
+/**
+ * Resolve a (from, to) phase pair to a recommend() envelope.
+ * Unknown pairs return `severity: 'no'` with `notInTable: true` so the
+ * LLM can see "this transition isn't in the table" instead of silently
+ * getting a default.
+ */
+export declare function lookupPhaseTransition(from: Phase, to: Phase): {
+    severity: Severity;
+    rationale: string;
+    notInTable: boolean;
+};
+/**
+ * LLM-ready `/compact Focus on ...` prompt string. The phrasing is
+ * deliberately terse — the upstream ECC suggest-compact hook uses a
+ * similar short imperative form.
+ */
+export declare function buildSuggestedCompactMessage(from: Phase, to: Phase, severity: Severity): string;

package/dist/src/services/compact/decision-tables.js

@@ -0,0 +1,127 @@
+/**
+ * Strategic-compact decision tables (slice 2026-07-01-strategic-compact-cli).
+ *
+ * Pure data + lookup helpers. No I/O. The byte-for-byte text mirrors the
+ * "Compaction Decision Guide" + "What Survives Compaction" tables in
+ * ECC's strategic-compact SKILL.md (read-only reference at
+ * C:\Users\smallMark\.claude\plugins\cache\ecc\ecc\2.0.0\skills\strategic-compact\SKILL.md).
+ *
+ * The `peaks compact recommend` + `peaks compact survival` + `peaks
+ * compact dry-run` primitives read from these tables; any change to the
+ * upstream skill table must be mirrored here and re-asserted by the
+ * `tests/unit/cli/compact-command.test.ts` regression suite.
+ */
+export const PHASES = [
+    'research',
+    'planning',
+    'implementation',
+    'testing',
+    'debugging'
+];
+export function isPhase(value) {
+    return PHASES.includes(value);
+}
+/**
+ * Single source of truth for the strategic-compact "Compaction Decision
+ * Guide" table. Each row is a recommended from→to transition. The
+ * `rationale` field is the "Why" column verbatim from SKILL.md.
+ *
+ * The CLI accepts arbitrary from/to phase pairs; if the pair is not in
+ * the table (e.g. testing→implementation) the recommend primitive
+ * returns `severity: 'no'` with a `notInTable: true` flag and the
+ * default rationale "No documented transition; preserve context".
+ */
+export const PHASE_TRANSITIONS = [
+    {
+        from: 'research',
+        to: 'planning',
+        severity: 'yes',
+        rationale: 'Research context is bulky; plan is the distilled output'
+    },
+    {
+        from: 'planning',
+        to: 'implementation',
+        severity: 'yes',
+        rationale: 'Plan is in TodoWrite or a file; free up context for code'
+    },
+    {
+        from: 'implementation',
+        to: 'testing',
+        severity: 'maybe',
+        rationale: 'Keep if tests reference recent code; compact if switching focus'
+    },
+    {
+        from: 'debugging',
+        to: 'implementation',
+        severity: 'yes',
+        rationale: 'Debug traces pollute context for unrelated work'
+    }
+];
+/** Documented "no compact" rows from the SKILL.md table. */
+export const PHASE_NO_TRANSITIONS = [
+    {
+        from: 'implementation',
+        to: 'implementation',
+        rationale: 'Mid-implementation: losing variable names, file paths, and partial state is costly'
+    },
+    {
+        from: 'debugging',
+        to: 'debugging',
+        rationale: 'After a failed approach: keep context until you commit to a new direction'
+    }
+];
+/**
+ * SKILL.md "What Survives Compaction" table — byte-for-byte.
+ * The `peaks compact survival` primitive emits these lists verbatim.
+ */
+export const SURVIVAL_TABLE = {
+    persists: [
+        'CLAUDE.md instructions',
+        'TodoWrite task list',
+        'Memory files (~/.claude/memory/)',
+        'Git state (commits, branches)',
+        'Files on disk'
+    ],
+    lost: [
+        'Intermediate reasoning and analysis',
+        'File contents you previously read',
+        'Multi-step conversation context',
+        'Tool call history and counts',
+        'Nuanced user preferences stated verbally'
+    ]
+};
+/**
+ * Resolve a (from, to) phase pair to a recommend() envelope.
+ * Unknown pairs return `severity: 'no'` with `notInTable: true` so the
+ * LLM can see "this transition isn't in the table" instead of silently
+ * getting a default.
+ */
+export function lookupPhaseTransition(from, to) {
+    const direct = PHASE_TRANSITIONS.find((row) => row.from === from && row.to === to);
+    if (direct !== undefined) {
+        return { severity: direct.severity, rationale: direct.rationale, notInTable: false };
+    }
+    const noRow = PHASE_NO_TRANSITIONS.find((row) => row.from === from && row.to === to);
+    if (noRow !== undefined) {
+        return { severity: 'no', rationale: noRow.rationale, notInTable: false };
+    }
+    return {
+        severity: 'no',
+        rationale: 'No documented transition; preserve context',
+        notInTable: true
+    };
+}
+/**
+ * LLM-ready `/compact Focus on ...` prompt string. The phrasing is
+ * deliberately terse — the upstream ECC suggest-compact hook uses a
+ * similar short imperative form.
+ */
+export function buildSuggestedCompactMessage(from, to, severity) {
+    if (severity === 'no') {
+        return `/compact Preserve context for ongoing ${from} work; do not abandon in-flight state.`;
+    }
+    if (severity === 'maybe') {
+        return `/compact Focus on completing ${to} for the current thread; preserve recent code references.`;
+    }
+    return `/compact Focus on ${to}: ${from} context has been distilled into the plan / todo list.`;
+}

package/dist/src/services/compact/request-transition-hook.d.ts

@@ -0,0 +1,20 @@
+export interface PreCompactHookInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly transitionKey: string;
+}
+export interface PreCompactHookResult {
+    readonly triggered: boolean;
+    readonly checkpointPath: string | null;
+    readonly ratio: number;
+    readonly zone: 'none' | 'soft-warn' | 'pre-compact' | 'red-line';
+    readonly note: string;
+}
+/**
+ * Check the pre-compact zone and, if active, write a checkpoint.
+ * Returns a result envelope the caller can stitch into the
+ * transition response. NEVER throws; returns a `triggered: false`
+ * result on any error so the transition itself stays the contract
+ * surface.
+ */
+export declare function maybePreCompactCheckpoint(input: PreCompactHookInput): PreCompactHookResult;

package/dist/src/services/compact/request-transition-hook.js

@@ -0,0 +1,110 @@
+/**
+ * Slice-boundary pre-compact hook (slice 2026-07-01-strategic-compact-cli).
+ *
+ * The RD → QA and QA → final-review slice-boundary transitions go
+ * through `peaks request transition`. When the active session is in
+ * the 0.85–0.95 pre-compact zone (per auto-compact-types.ts), this
+ * hook:
+ *
+ *   1. Detects the zone via the latest `.peaks/_runtime/<sid>/usage.jsonl`
+ *      row, OR falls back to `peaks compact suggest --json`.
+ *   2. Writes a `context-fill` checkpoint BEFORE the transition so
+ *      the post-compact LLM has a deterministic resume surface.
+ *   3. Attaches `preCompactCheckpoint: true` to the transition
+ *      envelope so the LLM can audit the side-effect.
+ *
+ * The hook is INVOKED from `src/cli/commands/request-commands.ts`
+ * (RD→QA boundary) and from any future QA→final-review boundary. The
+ * 0.95 red line is NOT changed: the existing auto-compact
+ * orchestrator continues to refuse dispatch at ratio ≥ 0.95.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { writeCheckpoint } from '../session/session-checkpoint-service.js';
+import { AUTO_COMPACT_PRE_COMPACT_RATIO, AUTO_COMPACT_RED_LINE_RATIO } from '../context/auto-compact-types.js';
+const PRE_COMPACT_ZONE = {
+    preCompact: AUTO_COMPACT_PRE_COMPACT_RATIO,
+    redLine: AUTO_COMPACT_RED_LINE_RATIO
+};
+function readLatestUsageRow(projectRoot, sessionId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'usage.jsonl');
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+        if (lines.length === 0)
+            return null;
+        const last = lines[lines.length - 1];
+        if (last === undefined)
+            return null;
+        return JSON.parse(last);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * Compute the context-fill ratio from a usage row. Defaults to a
+ * 200k window when the row is missing capacity. The auto-compact
+ * types use a 256KB byte-based estimate; this hook uses a 200k
+ * token-based window to match the strategic-compact SKILL.md.
+ */
+function computeRatio(row) {
+    if (row === null)
+        return { ratio: 0, zone: 'none' };
+    const tokens = typeof row.tokens === 'number' && Number.isFinite(row.tokens) ? row.tokens : 0;
+    const capacity = typeof row.capacityTokens === 'number' && row.capacityTokens > 0 ? row.capacityTokens : 200_000;
+    const ratio = capacity > 0 ? tokens / capacity : 0;
+    if (ratio >= PRE_COMPACT_ZONE.redLine)
+        return { ratio, zone: 'red-line' };
+    if (ratio >= PRE_COMPACT_ZONE.preCompact)
+        return { ratio, zone: 'pre-compact' };
+    if (ratio >= 0.5)
+        return { ratio, zone: 'soft-warn' };
+    return { ratio, zone: 'none' };
+}
+/**
+ * Check the pre-compact zone and, if active, write a checkpoint.
+ * Returns a result envelope the caller can stitch into the
+ * transition response. NEVER throws; returns a `triggered: false`
+ * result on any error so the transition itself stays the contract
+ * surface.
+ */
+export function maybePreCompactCheckpoint(input) {
+    try {
+        const row = readLatestUsageRow(input.projectRoot, input.sessionId);
+        const { ratio, zone } = computeRatio(row);
+        if (zone !== 'pre-compact') {
+            return {
+                triggered: false,
+                checkpointPath: null,
+                ratio,
+                zone,
+                note: `ratio=${(ratio * 100).toFixed(1)}% (zone=${zone}); pre-compact hook is in 0.85–0.95 zone only`
+            };
+        }
+        const result = writeCheckpoint(input.projectRoot, {
+            sessionId: input.sessionId,
+            reason: 'context-fill',
+            gitStatus: `preCompactCheckpoint: ${input.transitionKey}`,
+            currentPlan: `Slice boundary transition: ${input.transitionKey}`
+        });
+        return {
+            triggered: true,
+            checkpointPath: result.path,
+            ratio,
+            zone,
+            note: `Pre-compact checkpoint written at ratio=${(ratio * 100).toFixed(1)}% (zone=pre-compact). The LLM is still the decision-maker; the transition will proceed.`
+        };
+    }
+    catch (error) {
+        return {
+            triggered: false,
+            checkpointPath: null,
+            ratio: 0,
+            zone: 'none',
+            note: `pre-compact hook failed: ${error.message ?? String(error)}`
+        };
+    }
+}

package/dist/src/services/compact/suggest-service.d.ts

@@ -0,0 +1,74 @@
+import { type Phase, type Severity } from './decision-tables.js';
+/** Token window sizes supported by the suggest service. */
+export type WindowKind = '200k' | '1m';
+export interface SuggestOptions {
+    readonly projectRoot: string;
+    readonly sessionId: string | null;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface SuggestResult {
+    readonly shouldSuggest: boolean;
+    readonly reason: string;
+    readonly ratio: number;
+    readonly windowKind: WindowKind;
+    readonly tokensUsed: number;
+    readonly toolCalls: number;
+    readonly thresholds: {
+        readonly contextTokens: number;
+        readonly contextInterval: number;
+        readonly toolCalls: number;
+    };
+    readonly dataUnavailable: boolean;
+    readonly source: 'usage-jsonl' | 'env-vars' | 'none';
+}
+/** Default tool-call threshold before first suggestion. */
+export declare const DEFAULT_TOOL_CALL_THRESHOLD = 50;
+/** Default additional tool calls before the suggestion repeats. */
+export declare const TOOL_CALL_REMIND_STEP = 25;
+/** Default context-size threshold on a 200k window. */
+export declare const DEFAULT_CONTEXT_THRESHOLD_200K = 160000;
+/** Default context-size threshold on a 1M window. */
+export declare const DEFAULT_CONTEXT_THRESHOLD_1M = 250000;
+/** Default re-remind interval for context size. */
+export declare const DEFAULT_CONTEXT_INTERVAL = 60000;
+export declare function suggestCompact(options: SuggestOptions): SuggestResult;
+/**
+ * `peaks compact dry-run` envelope — composed of (a) suggest, (b)
+ * recommend, (c) survival. Pure composition over the helpers; no
+ * additional I/O. The CLI emits this so the LLM can decide in one
+ * tool-call whether to act.
+ */
+export interface DryRunOptions {
+    readonly projectRoot: string;
+    readonly sessionId: string | null;
+    readonly from?: Phase;
+    readonly to?: Phase;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface DryRunResult {
+    readonly action: 'compact' | 'skip';
+    readonly suggest: SuggestResult;
+    readonly recommend: {
+        readonly from: Phase | null;
+        readonly to: Phase | null;
+        readonly shouldCompact: boolean;
+        readonly severity: Severity | null;
+        readonly rationale: string | null;
+        readonly suggestedMessage: string | null;
+    };
+    readonly survival: {
+        readonly persists: readonly string[];
+        readonly lost: readonly string[];
+    };
+}
+export declare function dryRunCompact(options: DryRunOptions): DryRunResult;
+export declare function buildRecommendEnvelopePure(from: Phase, to: Phase): {
+    from: Phase;
+    to: Phase;
+    shouldCompact: boolean;
+    severity: Severity;
+    rationale: string;
+    suggestedMessage: string;
+};
+export { PHASE_TRANSITIONS, lookupPhaseTransition, buildSuggestedCompactMessage, PHASES, isPhase, SURVIVAL_TABLE } from './decision-tables.js';
+export type { Phase, Severity } from './decision-tables.js';