peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/codegraph/codegraph-service.js

@@ -0,0 +1,160 @@
+import { existsSync, realpathSync, statSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { defaultCodegraphProcessRunner } from './codegraph-process-runner.js';
+const CODEGRAPH_PACKAGE_NAME = '@colbymchenry/codegraph';
+const CODEGRAPH_PACKAGE_VERSION = '0.7.10';
+const CODEGRAPH_EXECUTABLE = process.execPath;
+const CODEGRAPH_BINARY_PATH = resolveCodegraphBinaryPath();
+const POSITIONAL_ARGUMENT_PREFIX = '-';
+const ALLOWED_SUBCOMMANDS = ['status', 'init', 'index', 'query', 'files', 'context', 'affected'];
+const NUMERIC_FLAG_NAMES = ['limit', 'maxDepth'];
+const COMMON_OPTION_KEYS = ['subcommand', 'project'];
+const ALLOWED_OPTIONS_BY_SUBCOMMAND = {
+    status: [],
+    init: ['yes'],
+    index: ['force', 'quiet'],
+    query: ['search', 'json', 'limit'],
+    files: ['json', 'maxDepth'],
+    context: ['task'],
+    affected: ['files', 'json']
+};
+function resolveCodegraphBinaryPath() {
+    const require = createRequire(import.meta.url);
+    const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
+    const binaryPath = resolve(dirname(packageJsonPath), 'dist', 'bin', 'codegraph.js');
+    return binaryPath;
+}
+function assertSupportedSubcommand(subcommand) {
+    if (!ALLOWED_SUBCOMMANDS.includes(subcommand)) {
+        throw new Error(`Unsupported codegraph subcommand: ${subcommand}`);
+    }
+}
+function resolveProjectRoot(project) {
+    const projectRoot = resolve(project);
+    try {
+        if (!statSync(projectRoot).isDirectory()) {
+            throw new Error('Project path must exist and be a directory');
+        }
+        return realpathSync.native(projectRoot);
+    }
+    catch {
+        throw new Error('Project path must exist and be a directory');
+    }
+}
+function assertPositiveInteger(value, flagName) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`${flagName} must be a positive integer`);
+    }
+}
+function assertPositionalArgument(value, argumentName) {
+    if (value.startsWith(POSITIONAL_ARGUMENT_PREFIX)) {
+        throw new Error(`${argumentName} must not start with -`);
+    }
+}
+function assertSupportedOptions(options) {
+    const allowedOptions = new Set(ALLOWED_OPTIONS_BY_SUBCOMMAND[options.subcommand]);
+    const presentOptionKeys = Object.keys(options).filter((key) => !COMMON_OPTION_KEYS.includes(key));
+    const unsupportedOption = presentOptionKeys.find((key) => !allowedOptions.has(key));
+    if (unsupportedOption) {
+        throw new Error(`Unsupported option ${unsupportedOption} for codegraph ${options.subcommand}`);
+    }
+}
+function assertRequiredOptions(options) {
+    if (options.subcommand === 'query' && (!options.search || options.search.trim() === '')) {
+        throw new Error('search must be non-empty');
+    }
+    if (options.subcommand === 'query' && options.search) {
+        assertPositionalArgument(options.search, 'search');
+    }
+    if (options.subcommand === 'context') {
+        assertPositionalArgument(options.task, 'task');
+    }
+}
+function assertInsideProject(projectRoot, absolutePath) {
+    const relativePath = relative(projectRoot, absolutePath);
+    if (relativePath === '' || relativePath.startsWith('..') || isAbsolute(relativePath)) {
+        throw new Error('Affected files must stay inside the project');
+    }
+}
+function resolveExistingBoundary(absoluteFilePath) {
+    if (existsSync(absoluteFilePath)) {
+        return absoluteFilePath;
+    }
+    let currentPath = dirname(absoluteFilePath);
+    while (!existsSync(currentPath)) {
+        const parentPath = dirname(currentPath);
+        currentPath = parentPath;
+    }
+    return currentPath;
+}
+function normalizeProjectRelativeFile(projectRoot, file) {
+    assertPositionalArgument(file, 'Affected files');
+    const absoluteFilePath = resolve(projectRoot, file);
+    assertInsideProject(projectRoot, absoluteFilePath);
+    const realBoundary = realpathSync.native(resolveExistingBoundary(absoluteFilePath));
+    assertInsideProject(projectRoot, realBoundary);
+    return relative(projectRoot, absoluteFilePath).split(sep).join('/');
+}
+function buildAffectedFileArgs(projectRoot, files) {
+    if (!files || files.length < 1) {
+        throw new Error('affected requires at least one file');
+    }
+    return files.map((file) => normalizeProjectRelativeFile(projectRoot, file));
+}
+function buildCommandArgs(options, projectRoot) {
+    const args = [CODEGRAPH_BINARY_PATH, options.subcommand];
+    if (options.subcommand === 'query' && options.search) {
+        args.push(options.search);
+    }
+    if (options.subcommand === 'context') {
+        if (options.task.trim() === '') {
+            throw new Error('task must be non-empty');
+        }
+        args.push(options.task);
+    }
+    if (options.subcommand === 'affected') {
+        args.push(...buildAffectedFileArgs(projectRoot, options.files));
+    }
+    if (options.yes === true) {
+        args.push('--yes');
+    }
+    if (options.force === true) {
+        args.push('--force');
+    }
+    if (options.json === true) {
+        args.push('--json');
+    }
+    if (options.quiet === true) {
+        args.push('--quiet');
+    }
+    if (options.limit !== undefined) {
+        args.push('--limit', String(options.limit));
+    }
+    if (options.maxDepth !== undefined) {
+        args.push('--max-depth', String(options.maxDepth));
+    }
+    return args;
+}
+export function createCodegraphInvocation(options) {
+    assertSupportedSubcommand(options.subcommand);
+    const projectRoot = resolveProjectRoot(options.project);
+    assertSupportedOptions(options);
+    assertRequiredOptions(options);
+    assertPositiveInteger(options.limit, 'limit');
+    assertPositiveInteger(options.maxDepth, 'maxDepth');
+    return {
+        executable: CODEGRAPH_EXECUTABLE,
+        args: buildCommandArgs(options, projectRoot),
+        cwd: projectRoot,
+        packageName: CODEGRAPH_PACKAGE_NAME,
+        packageVersion: CODEGRAPH_PACKAGE_VERSION,
+        subcommand: options.subcommand
+    };
+}
+export async function executeCodegraphInvocation(invocation, runner = defaultCodegraphProcessRunner) {
+    return runner(invocation);
+}

package/dist/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/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/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/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/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';