peaks-loop 3.0.0

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

@@ -0,0 +1,45 @@
+import { readConfig } from '../../services/config/config-service.js';
+import { resolveCapabilityAvailability } from '../../services/recommendations/capability-availability.js';
+import { createCapabilityMapPlan } from '../../services/recommendations/capability-map-service.js';
+import { seedCapabilityItems, seedCapabilitySources } from '../../services/recommendations/seed-capability-catalog.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+const CAPABILITY_SOURCE_FILTERS = new Set(['all', 'access-repo', 'mcp-server']);
+export function registerCapabilityCommands(program, io) {
+    const capability = program.command('capability').description('Inspect Peaks capability catalog and runtime availability');
+    addJsonOption(capability.command("status").description("Show seed capability availability")).action((options) => runCapabilityStatus(io, options));
+    addCapabilityMapOptions(capability.command('map').description('Show dry-run external capability landing map')).action((options) => runCapabilityMap(io, options));
+    addCapabilityMapOptions(program.command('capabilities').description('Show dry-run external capability landing map')).action((options) => runCapabilityMap(io, options));
+}
+export function runCapabilityStatus(io, options) {
+    const availability = resolveCapabilityAvailability(seedCapabilityItems);
+    printResult(io, ok("capability.status", { sources: seedCapabilitySources, items: seedCapabilityItems, availability }), options.json);
+}
+function addCapabilityMapOptions(command) {
+    return addJsonOption(command.option('--source <source>', 'Filter source group: all, access-repo, or mcp-server', 'all'));
+}
+export function runCapabilityMap(io, options) {
+    const source = parseCapabilityMapSource(options.source);
+    if (!source) {
+        printResult(io, fail('capabilities.map', 'UNSUPPORTED_CAPABILITY_SOURCE', 'Supported capability sources are all, access-repo, and mcp-server', { source: options.source }, ['Rerun with --source all, --source access-repo, or --source mcp-server']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    const config = readConfig();
+    const installedCapabilityIds = getInstalledCapabilityIds(config);
+    const httpProxy = config.proxy?.httpProxy;
+    printResult(io, ok('capabilities.map', createCapabilityMapPlan({
+        source,
+        installedCapabilityIds,
+        ...(httpProxy === undefined ? {} : { httpProxy })
+    })), options.json);
+}
+export function getInstalledCapabilityIds(_config) {
+    return [];
+}
+export function parseCapabilityMapSource(source) {
+    if (CAPABILITY_SOURCE_FILTERS.has(source)) {
+        return source;
+    }
+    return null;
+}

package/dist/src/cli/commands/capability-worker-config-sc-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export declare function registerCapabilityWorkerConfigAndSCCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/capability-worker-config-sc-commands.js

@@ -0,0 +1,10 @@
+import { registerCapabilityCommands } from './capability-commands.js';
+import { registerConfigCommands } from './config-commands.js';
+import { registerSCCommands } from './sc-commands.js';
+import { registerWorkerCommands } from './worker-commands.js';
+export function registerCapabilityWorkerConfigAndSCCommands(program, io) {
+    registerCapabilityCommands(program, io);
+    registerWorkerCommands(program, io);
+    registerConfigCommands(program, io);
+    registerSCCommands(program, io);
+}

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

@@ -0,0 +1,19 @@
+/**
+ * peaks classify CLI (Slice L1a + L1b).
+ *
+ * Subcommands:
+ *   - peaks classify run --project <path> [--override <level> --reason "<text>"]
+ *     Classify the current diff via the heuristic + return a JSON envelope
+ *     with the chosen level, gate set, and audit log.
+ *   - peaks classify override --level <level> --reason "<text>" --project <path>
+ *     Force a level; writes the override to the audit log.
+ *   - peaks classify upgrade --level <level> --reason "<text>" --project <path>
+ *     Same as override but explicitly framed as an upgrade (audit log
+ *     records the upgrade event separately from override).
+ *
+ * Downgrade is REFUSED (per spec §4: "peaks classify downgrade" always
+ * errors out). LLM may ask; the CLI never grants.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerClassifyCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,151 @@
+/**
+ * peaks classify CLI (Slice L1a + L1b).
+ *
+ * Subcommands:
+ *   - peaks classify run --project <path> [--override <level> --reason "<text>"]
+ *     Classify the current diff via the heuristic + return a JSON envelope
+ *     with the chosen level, gate set, and audit log.
+ *   - peaks classify override --level <level> --reason "<text>" --project <path>
+ *     Force a level; writes the override to the audit log.
+ *   - peaks classify upgrade --level <level> --reason "<text>" --project <path>
+ *     Same as override but explicitly framed as an upgrade (audit log
+ *     records the upgrade event separately from override).
+ *
+ * Downgrade is REFUSED (per spec §4: "peaks classify downgrade" always
+ * errors out). LLM may ask; the CLI never grants.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { classifyTask } from '../../services/classify/classify-service.js';
+import { TASK_LEVELS } from '../../services/classify/classify-types.js';
+import { loadPreferences } from '../../services/preferences/preferences-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+const CLASSIFY_AUDIT_FILE = 'classify-audit.jsonl';
+function getSignalsFromGitDiff(projectRoot) {
+    // Use git diff --stat to extract file count + line count. Fall back to
+    // zeros if git is unavailable (e.g. fresh repo with no commits).
+    let stdout;
+    try {
+        const { execFileSync } = require('node:child_process');
+        stdout = execFileSync('git', ['diff', '--shortstat', 'HEAD'], {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: 32 * 1024 * 1024,
+        }).toString('utf8');
+    }
+    catch {
+        return { filesChanged: 0, linesChanged: 0, touchesDependencies: false, touchesMigrationScripts: false, isPureRefactor: true, keywords: [] };
+    }
+    const lines = stdout.split('\n').filter((l) => l.trim().length > 0);
+    const filesChanged = lines.length;
+    let added = 0;
+    let removed = 0;
+    let touchesDependencies = false;
+    let touchesMigrationScripts = false;
+    for (const line of lines) {
+        const match = /(\d+)\s+insertion.*?(\d+)\s+deletion/.exec(line);
+        if (match) {
+            added += Number(match[1]);
+            removed += Number(match[2]);
+        }
+        if (/(package\.json|pnpm-lock\.yaml|yarn\.lock|requirements\.txt|go\.mod)/.test(line)) {
+            touchesDependencies = true;
+        }
+        if (/(migrate|codemod|backfill|schema)/.test(line)) {
+            touchesMigrationScripts = true;
+        }
+    }
+    // isPureRefactor: heuristic — if added lines / removed lines < 0.1 OR
+    // no new exports were added, treat as refactor. For L2.2 the signal is
+    // binary (true/false). Default: true (no behavior change is the safe
+    // assumption; flip to false when keyword 'add' / 'new' / 'feature' present).
+    const isPureRefactor = true;
+    return {
+        filesChanged,
+        linesChanged: added + removed,
+        touchesDependencies,
+        touchesMigrationScripts,
+        isPureRefactor,
+        keywords: [],
+    };
+}
+function appendAuditEntry(projectRoot, entry) {
+    const auditDir = join(projectRoot, '.peaks/_runtime');
+    if (!existsSync(auditDir)) {
+        try {
+            mkdirSync(auditDir, { recursive: true });
+        }
+        catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    }
+    const auditPath = join(auditDir, CLASSIFY_AUDIT_FILE);
+    let body = '';
+    try {
+        if (existsSync(auditPath)) {
+            body = readFileSync(auditPath, 'utf8');
+        }
+    }
+    catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    body += JSON.stringify(entry) + '\n';
+    try {
+        writeFileSync(auditPath, body);
+    }
+    catch { /* best-effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+}
+function isTaskLevel(value) {
+    return TASK_LEVELS.includes(value);
+}
+export function registerClassifyCommands(program, io) {
+    const classify = program
+        .command('classify')
+        .description('L1a task classification: 5-level heuristic (typo/bug/feature/refactor/migration) + override/upgrade + audit log');
+    addJsonOption(classify
+        .command('run')
+        .description('Classify the current diff (git diff HEAD) into one of 5 task levels')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--override <level>', 'force a level (one of typo|bug|feature|refactor|migration); requires --reason')
+        .option('--reason <text>', 'reason for the override (mandatory when --override is set)')).action(async (options) => {
+        try {
+            const prefs = await loadPreferences(options.project);
+            const signals = getSignalsFromGitDiff(options.project);
+            let override;
+            if (options.override !== undefined) {
+                if (!isTaskLevel(options.override)) {
+                    printResult(io, fail('classify.run', 'INVALID_LEVEL', `level must be one of: ${TASK_LEVELS.join(', ')}`, { provided: options.override }, ['Pass one of typo, bug, feature, refactor, migration']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                if (options.reason === undefined || options.reason.length === 0) {
+                    printResult(io, fail('classify.run', 'REASON_REQUIRED', '--reason is required when --override is set', {}, ['Provide a non-empty reason for the override']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                override = { level: options.override, reason: options.reason };
+            }
+            const result = classifyTask(override !== undefined
+                ? { signals, conservatism: prefs.classifyConservatism, override }
+                : { signals, conservatism: prefs.classifyConservatism }, prefs.classifyRules.feature_threshold_files, prefs.classifyRules.feature_threshold_lines);
+            appendAuditEntry(options.project, result.audit);
+            printResult(io, ok('classify.run', result, [], [
+                `gate set for level "${result.level}": ${result.gateSet.stages.join(', ')}`,
+                `audit log: .peaks/_runtime/${CLASSIFY_AUDIT_FILE}`,
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('classify.run', 'CLASSIFY_RUN_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Run peaks classify --help for usage']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // Downgrade is REFUSED per spec §4. Surface this as a hard fail.
+    classify
+        .command('downgrade')
+        .description('REFUSED per spec §4 — peaks-cli never downgrades a classification; ask the user to override explicitly')
+        .requiredOption('--level <level>', 'attempted level')
+        .requiredOption('--reason <text>', 'reason for the attempt (always rejected)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--json', 'print machine-readable JSON envelope')
+        .action(async (options) => {
+        printResult(io, fail('classify.downgrade', 'DOWNGRADE_REFUSED', 'peaks classify downgrade is refused per spec §4. Use --override (with reason) on `classify run` to force a level; the CLI never downgrades a classification unilaterally.', { attemptedLevel: options.level, reason: options.reason }, ['Use `peaks classify run --override <level> --reason "<text>"` instead']), options.json);
+        process.exitCode = 2;
+    });
+}

package/dist/src/cli/commands/code-review-commands.d.ts

@@ -0,0 +1,34 @@
+/**
+ * peaks code-review * CLI surface — soft-optional ocr integration
+ * for peaks-rd Gate B3.
+ *
+ * Per the "skill-first / CLI-auxiliary" tenet, peaks-rd SKILL.md
+ * is the primary surface; this CLI returns structured JSON the
+ * skill consumes to produce a second-opinion code review.
+ *
+ * Subcommands:
+ *   - `peaks code-review detect-ocr` — JSON envelope describing the
+ *     current ocr install + config state (5 reasons: ready /
+ *     package-missing / binary-missing / config-missing /
+ *     detection-failed). Source of truth for the LLM endpoint
+ *     config is `peaksConfig.ocr.llm` in the user's peaks-cli
+ *     config (NOT `~/.opencodereview/config.json`).
+ *   - `peaks code-review run-ocr [--from --to --commit]` — invokes
+ *     `ocr review --format json` and wraps the result in a peaks
+ *     ResultEnvelope. Soft-fails when ocr isn't ready so peaks-rd
+ *     can continue without the second-opinion review. Injects the
+ *     LLM endpoint config as env vars (OCR_LLM_URL / OCR_LLM_TOKEN
+ *     / OCR_LLM_MODEL / OCR_USE_ANTHROPIC / OCR_LLM_AUTH_HEADER)
+ *     so the ocr subprocess never has to read from a file the
+ *     user did not set up themselves.
+ *   - `peaks code-review config-template` — prints the JSON snippet
+ *     the user should paste into their peaks-cli config.json. It
+ *     does NOT write anything. The user is in control of their
+ *     LLM token / URL / model. No `peaks ocr config set`; the user
+ *     either edits the JSON directly or uses `peaks config set
+ *     --key ocr.llm.url --value '...'` (a peaks-cli command, not
+ *     an ocr command).
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodeReviewCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/code-review-commands.js

@@ -0,0 +1,83 @@
+import { getOcrConfigTemplate, detectOcr, runOcrReview } from '../../services/code-review/ocr-service.js';
+import { getOcrLlmConfig, getUserConfigPath, redactConfigSecrets } from '../../services/config/config-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export function registerCodeReviewCommands(program, io) {
+    const codeReview = program
+        .command('code-review')
+        .description('Code-review primitives for peaks-rd Gate B3. Wraps the soft-optional `@alibaba-group/open-code-review` (ocr) tool when it is installed + configured; peaks-rd uses the structured JSON output as a second-opinion review alongside its own LLM review. ocr is a peerDependency of peaks-cli 2.8.2+ (was briefly promoted to a hard dependency in 2.0.1/2.0.2, then demoted to optionalDependencies 2.0.3+ — peer in 2.8.2 because its postinstall downloads a Go binary via HTTPS and would otherwise slow `npm i -g peaks-cli` in restricted environments). Install manually with `npm i -g @alibaba-group/open-code-review` if you want second-opinion reviews. LLM endpoint config lives under `peaksConfig.ocr.llm` in the user config — run `peaks code-review config-template` to see the JSON snippet to paste.');
+    addJsonOption(codeReview
+        .command('detect-ocr')
+        .description('Read-only probe: returns the ocr install + config state as a JSON envelope (5 reasons: ready / package-missing / binary-missing / config-missing / detection-failed). peaks-rd calls this first to decide whether to invoke `run-ocr`. Reads the LLM endpoint from `peaksConfig.ocr.llm` (not from ~/.opencodereview/config.json).')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        try {
+            const detect = detectOcr({
+                cwd: projectRoot,
+                peaksConfigPath: getUserConfigPath(),
+                peaksOcrConfig: getOcrLlmConfig(),
+            });
+            const envelope = detect.state === 'ready'
+                ? ok('code-review.detect-ocr', detect, [...detect.warnings], [...detect.nextActions])
+                : fail('code-review.detect-ocr', detect.state.toUpperCase().replace(/-/g, '_'), `ocr is not ready: ${detect.state}`, detect, [...detect.nextActions]);
+            printResult(io, envelope, options.json);
+            if (detect.state !== 'ready') {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('code-review.detect-ocr', 'DETECT_OCR_FAILED', getErrorMessage(error), { state: 'detection-failed', packageInstalled: false, binaryPath: null, version: null, configPath: '', configValid: false, missingKeys: [] }, ['Re-run with `--project <path>` pointing at a known-good project root.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(codeReview
+        .command('run-ocr')
+        .description('Run `ocr review --format json` and return the parsed JSON envelope. Soft-fails (exit 0, ok=false) when ocr is not ready, so peaks-rd can continue without the second-opinion review and surface the install/config nextActions to the user. The peaks-cli `peaksConfig.ocr.llm` block is injected as OCR_LLM_URL / OCR_LLM_TOKEN / ... env vars so the ocr subprocess never has to read ~/.opencodereview/config.json.')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--from <ref>', 'git ref to diff from (e.g. main, origin/main)')
+        .option('--to <ref>', 'git ref to diff to (e.g. HEAD, feature-branch)')
+        .option('--commit <sha>', 'specific commit SHA to review')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        try {
+            const result = runOcrReview({
+                cwd: projectRoot,
+                peaksConfigPath: getUserConfigPath(),
+                peaksOcrConfig: getOcrLlmConfig(),
+                input: { projectRoot, ...(options.from !== undefined && { from: options.from }), ...(options.to !== undefined && { to: options.to }), ...(options.commit !== undefined && { commit: options.commit }) },
+            });
+            // Soft-fail policy: when ocr is not ready or the subprocess
+            // failed, we still return a JSON envelope (ok=false) but
+            // do NOT set process.exitCode — the caller is expected to
+            // pattern-match on the state and proceed without ocr.
+            const envelope = result.spawned && result.exitCode === 0
+                ? ok('code-review.run-ocr', result, [...result.warnings], [...result.nextActions])
+                : fail('code-review.run-ocr', result.state.toUpperCase().replace(/-/g, '_'), result.spawned ? `ocr review exited ${result.exitCode}` : `ocr is not ready: ${result.state}`, result, [...result.nextActions]);
+            printResult(io, envelope, options.json);
+            // Intentionally do NOT set process.exitCode here — soft-fail.
+        }
+        catch (error) {
+            printResult(io, fail('code-review.run-ocr', 'RUN_OCR_FAILED', getErrorMessage(error), { spawned: false, state: 'detection-failed', exitCode: null, stdout: '', stderr: '', durationMs: 0, parsed: null }, ['Run `peaks code-review detect-ocr --json` to inspect ocr install state.']), options.json);
+            // Soft-fail on exception too — peaks-rd should continue.
+        }
+    });
+    addJsonOption(codeReview
+        .command('config-template')
+        .description('Print the JSON snippet the user should paste into their peaks-cli config (`peaksConfig.ocr.llm`). This command does NOT write anything. The user is the only party that touches the LLM token / URL / model — peaks-cli never auto-configures the endpoint. Token value is shown as the placeholder "<your-api-key>"; replace it before pasting.')).action((options) => {
+        const template = getOcrConfigTemplate();
+        const targetPath = getUserConfigPath();
+        const currentConfig = getOcrLlmConfig();
+        const currentRedacted = currentConfig === null ? null : redactConfigSecrets(currentConfig, 'ocr.llm');
+        const payload = {
+            targetPath,
+            currentConfig: currentRedacted,
+            template,
+            nextActions: [
+                `Edit ${targetPath} and add the "ocr" block from the template above.`,
+                'OR use peaks-cli config set with one key at a time: `peaks config set --key ocr.llm.url --value \'<url>\'` etc.',
+                'The authToken field is sensitive and is stored in the user layer (`~/.peaks/config.json`); peaks-cli will not commit it.',
+                'Re-run `peaks code-review detect-ocr --json` to verify the new state is `ready`.',
+            ],
+        };
+        printResult(io, ok('code-review.config-template', payload), options.json);
+    });
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerCodegraphCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,99 @@
+import { InvalidArgumentError } from 'commander';
+import { createCodegraphInvocation, executeCodegraphInvocation } from '../../services/codegraph/codegraph-service.js';
+import { fail } from '../../shared/result.js';
+import { getErrorMessage, printResult, redactSensitiveErrorMessage } from '../cli-helpers.js';
+function addPeaksJsonOption(command) {
+    return command.option('--peaks-json', 'print Peaks error envelope as machine-readable JSON');
+}
+function addProjectOption(command) {
+    return addPeaksJsonOption(command.requiredOption('--project <path>', 'target project root'));
+}
+function parsePositiveInteger(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    const parsed = Number(value);
+    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new InvalidArgumentError('must be a positive integer');
+    }
+    return parsed;
+}
+function printCodegraphFailure(io, command, error, asJson, exitCode = 1) {
+    printResult(io, fail(command, 'CODEGRAPH_COMMAND_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check the codegraph command options and project path before retrying']), asJson);
+    process.exitCode = exitCode;
+}
+async function runCodegraphCommand(io, command, options, asJson) {
+    try {
+        const invocation = createCodegraphInvocation(options);
+        const result = await executeCodegraphInvocation(invocation);
+        if (result.exitCode !== null && result.exitCode !== 0 && asJson === true) {
+            printCodegraphFailure(io, command, new Error(result.stderr || result.stdout || `codegraph exited with code ${result.exitCode}`), true, result.exitCode);
+            return;
+        }
+        const didFail = result.exitCode !== null && result.exitCode !== 0;
+        if (result.stdout.length > 0) {
+            io.stdout((didFail ? redactSensitiveErrorMessage(result.stdout) : result.stdout).trimEnd());
+        }
+        if (result.stderr.length > 0) {
+            io.stderr((didFail ? redactSensitiveErrorMessage(result.stderr) : result.stderr).trimEnd());
+        }
+        if (didFail) {
+            process.exitCode = result.exitCode;
+        }
+    }
+    catch (error) {
+        printCodegraphFailure(io, command, error, asJson);
+    }
+}
+export function registerCodegraphCommands(program, io) {
+    const codegraph = program.command('codegraph').description('Run upstream codegraph commands through the Peaks launcher');
+    addProjectOption(codegraph.command('status').description('Show codegraph status')).action((options) => runCodegraphCommand(io, 'codegraph.status', { subcommand: 'status', project: options.project }, options.peaksJson));
+    addProjectOption(codegraph.command('init').description('Initialize codegraph for a project').option('--yes', 'answer yes to upstream prompts')).action((options) => runCodegraphCommand(io, 'codegraph.init', {
+        subcommand: 'init',
+        project: options.project,
+        ...(options.yes === true ? { yes: true } : {})
+    }, options.peaksJson));
+    addProjectOption(codegraph
+        .command('index')
+        .description('Index a project with codegraph')
+        .option('--force', 'force reindexing')
+        .option('--quiet', 'reduce upstream output')).action((options) => runCodegraphCommand(io, 'codegraph.index', {
+        subcommand: 'index',
+        project: options.project,
+        ...(options.force === true ? { force: true } : {}),
+        ...(options.quiet === true ? { quiet: true } : {})
+    }, options.peaksJson));
+    addProjectOption(codegraph
+        .command('query')
+        .description('Query codegraph')
+        .argument('<search>', 'search text')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--limit <n>', 'maximum result count', parsePositiveInteger)).action((search, options) => runCodegraphCommand(io, 'codegraph.query', {
+        subcommand: 'query',
+        project: options.project,
+        search,
+        ...(options.json === true ? { json: true } : {}),
+        ...(options.limit !== undefined ? { limit: options.limit } : {})
+    }, options.peaksJson));
+    addProjectOption(codegraph
+        .command('files')
+        .description('List codegraph files')
+        .option('--json', 'forward JSON output flag to upstream codegraph')
+        .option('--max-depth <n>', 'maximum traversal depth', parsePositiveInteger)).action((options) => runCodegraphCommand(io, 'codegraph.files', {
+        subcommand: 'files',
+        project: options.project,
+        ...(options.json === true ? { json: true } : {}),
+        ...(options.maxDepth !== undefined ? { maxDepth: options.maxDepth } : {})
+    }, options.peaksJson));
+    addProjectOption(codegraph.command('context').description('Build task context with codegraph').argument('<task>', 'task text')).action((task, options) => runCodegraphCommand(io, 'codegraph.context', { subcommand: 'context', project: options.project, task }, options.peaksJson));
+    addProjectOption(codegraph
+        .command('affected')
+        .description('Find code affected by files')
+        .argument('<files...>', 'project-relative file paths')
+        .option('--json', 'forward JSON output flag to upstream codegraph')).action((files, options) => runCodegraphCommand(io, 'codegraph.affected', {
+        subcommand: 'affected',
+        project: options.project,
+        files,
+        ...(options.json === true ? { json: true } : {})
+    }, options.peaksJson));
+}

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

@@ -0,0 +1,9 @@
+/**
+ * v2.15.0 follow-up — G10: peaks complexity estimate CLI.
+ *
+ *   - `peaks complexity estimate --files <list>` — per-file tier +
+ *     aggregate. Aligns with the G2 12 Gaps memory tier definition.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerComplexityCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,34 @@
+/**
+ * v2.15.0 follow-up — G10: peaks complexity estimate CLI.
+ *
+ *   - `peaks complexity estimate --files <list>` — per-file tier +
+ *     aggregate. Aligns with the G2 12 Gaps memory tier definition.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { estimateComplexity } from '../../services/complexity/complexity-estimator.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerComplexityCommands(program, io) {
+    addJsonOption(program
+        .command('complexity-estimate')
+        .description('v2.15.0 follow-up G10: estimate the complexity tier (trivial / simple / ' +
+        'complex) of a set of files, based on LOC + export count + async usage. ' +
+        'Aligns with the G2 12 Gaps memory tier definition. The aggregate ' +
+        'tier drives scheduling (trivial / simple → overnight; complex → ' +
+        'user-attended).')
+        .requiredOption('--files <list>', 'comma-separated file paths (relative to project root)')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const files = opts.files.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        if (files.length === 0) {
+            printResult(io, fail('complexity-estimate', 'INVALID_INPUT', 'no files provided (--files)', { projectRoot }, [
+                'Pass --files with at least one file path.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const report = estimateComplexity(projectRoot, files);
+        printResult(io, ok('complexity-estimate', { projectRoot, report }, [], [
+            `Overall tier: ${report.overall}. Schedule accordingly.`
+        ]), opts.json ?? false);
+    });
+}

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

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerConfigCommands(program: Command, io: ProgramIO): void;