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

package/dist/cli/commands/config-commands.js

@@ -0,0 +1,220 @@
+import { executeMigration, planMigration } from '../../services/config/config-migration.js';
+import { getConfig, getMiniMaxProviderConfig, getMiniMaxProviderStatus, isSensitiveConfigPath, redactConfigSecrets, setConfig, setMiniMaxProviderConfig } from '../../services/config/config-service.js';
+import { listAvailableFields, restoreField } from '../../services/config/config-restore.js';
+import { executeRollback, planRollback } from '../../services/config/config-rollback.js';
+import { testMiniMaxProvider } from '../../services/providers/minimax-provider-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, isMiniMaxHttpsUrl, parseConfigLayer, printInvalidConfigLayer, printResult, redactSensitiveErrorMessage, summarizeMiniMaxSmokeResult } from '../cli-helpers.js';
+export function registerConfigCommands(program, io) {
+    const config = program.command('config').description('Manage Peaks configuration');
+    registerConfigGetSetCommands(config, io);
+    registerConfigMigrationCommands(config, io);
+    registerMiniMaxProviderCommands(config, io);
+}
+function registerConfigGetSetCommands(config, io) {
+    addJsonOption(config.command('get').description('Get current config or a specific key').option('--key <path>', 'dot-notation key path').option('--layer <layer>', 'user or project')).action((options) => {
+        const layer = parseConfigLayer(options.layer);
+        if (layer === null) {
+            printInvalidConfigLayer(io, 'config.get', options.json);
+            return;
+        }
+        const getOpts = { ...(layer !== undefined ? { layer } : {}), ...(options.key !== undefined ? { key: options.key } : {}) };
+        const value = getConfig(getOpts);
+        const isSensitiveKey = options.key !== undefined && isSensitiveConfigPath(options.key);
+        printResult(io, ok('config.get', isSensitiveKey ? '***' : redactConfigSecrets(value, options.key ?? '')), options.json);
+    });
+    addJsonOption(config.command('set').description('Set a config value').requiredOption('--key <path>', 'dot-notation key path').requiredOption('--value <json>', 'JSON value').option('--layer <layer>', 'user or project')).action((options) => {
+        const parsedLayer = parseConfigLayer(options.layer);
+        if (parsedLayer === null) {
+            printInvalidConfigLayer(io, 'config.set', options.json);
+            return;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(options.value);
+        }
+        catch {
+            printResult(io, fail('config.set', 'INVALID_JSON', 'Could not parse value as JSON', {}, ['Use valid JSON: --value \'{"key":"value"}\'']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            setConfig({ key: options.key, value: parsed, layer: parsedLayer ?? 'user' });
+            const value = isSensitiveConfigPath(options.key) ? '***' : redactConfigSecrets(parsed);
+            printResult(io, ok('config.set', { key: options.key, value }), options.json);
+        }
+        catch (error) {
+            printConfigSetError(io, error, options.json);
+        }
+    });
+}
+function registerConfigMigrationCommands(config, io) {
+    // Slice 0.5 Task 14 — peaks config {migrate,rollback,restore} subcommands.
+    // Wires up the config-migration / config-rollback / config-restore services
+    // from Tasks 10-12. The default mode is dry-run; --apply writes.
+    config
+        .command('migrate')
+        .description('Migrate global config from 1.x to 2.0 (YAGNI slim + per-project fields)')
+        .option('--project <path>', 'current project root (for migrating per-project fields)', process.cwd())
+        .option('--apply', 'actually write changes (default is dry-run)')
+        .option('--dry-run', 'plan only, do not write (default)')
+        .option('--json', 'JSON envelope output')
+        .action((options) => {
+        try {
+            const apply = options.apply === true;
+            if (apply) {
+                const result = executeMigration({ currentProjectRoot: options.project, apply: true });
+                printResult(io, ok('config.migrate', result), options.json);
+                return;
+            }
+            const plan = planMigration({ currentProjectRoot: options.project });
+            printResult(io, ok('config.migrate', { ...plan, applied: false }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('config.migrate', 'CONFIG_MIGRATE_FAILED', getErrorMessage(error), {}, ['Inspect ~/.peaks/config.json and re-run with --apply']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    config
+        .command('rollback')
+        .description('Rollback global config to 1.x from .bak')
+        .option('--apply', 'actually write changes (default is dry-run)')
+        .option('--dry-run', 'plan only, do not write (default)')
+        .option('--json', 'JSON envelope output')
+        .action((options) => {
+        try {
+            const apply = options.apply === true;
+            if (apply) {
+                const result = executeRollback({ apply: true });
+                printResult(io, ok('config.rollback', result), options.json);
+                return;
+            }
+            const plan = planRollback();
+            printResult(io, ok('config.rollback', { ...plan, applied: false }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            const code = message.startsWith('NO_BACKUP') ? 'NO_BACKUP' : 'CONFIG_ROLLBACK_FAILED';
+            io.stderr(`${code}: ${message}`);
+            printResult(io, fail('config.rollback', code, message, {}, ['Re-run peaks config migrate --apply to recreate the .bak']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    config
+        .command('restore')
+        .description('Restore a single archived field from .bak to a sidecar file')
+        .option('--field <name>', 'field name to restore (e.g. language, currentWorkspace)')
+        .option('--list', 'list all fields available in .bak')
+        .option('--apply', 'actually write sidecar (default is dry-run)')
+        .option('--dry-run', 'plan only, do not write (default)')
+        .option('--json', 'JSON envelope output')
+        .action((options) => {
+        try {
+            if (options.list === true || !options.field) {
+                const fields = listAvailableFields();
+                printResult(io, ok('config.restore', { fields, applied: false }), options.json);
+                return;
+            }
+            const apply = options.apply === true;
+            const result = restoreField({ field: options.field, apply });
+            printResult(io, ok('config.restore', result), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            let code = 'CONFIG_RESTORE_FAILED';
+            if (message.startsWith('NO_BACKUP'))
+                code = 'NO_BACKUP';
+            else if (message.startsWith('RESTORE_GUARDED'))
+                code = 'RESTORE_GUARDED';
+            else if (message.startsWith('FIELD_NOT_FOUND'))
+                code = 'FIELD_NOT_FOUND';
+            io.stderr(`${code}: ${message}`);
+            printResult(io, fail('config.restore', code, message, {}, ['Use --list to see available fields']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+function printConfigSetError(io, error, asJson) {
+    const message = getErrorMessage(error);
+    if (message === 'Sensitive config keys must be stored in the user config layer') {
+        printResult(io, fail('config.set', 'SECRET_CONFIG_REQUIRES_USER_LAYER', message, {}, ['Use --layer user or peaks config provider minimax set']), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    if (message === 'Project config not found') {
+        printResult(io, fail('config.set', 'PROJECT_CONFIG_NOT_FOUND', message, {}, ['Create a safe .peaks/config.json in the project or use --layer user']), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    if (message === 'MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials') {
+        printResult(io, fail('config.set', 'INVALID_MINIMAX_BASE_URL', message, {}, ['Use a MiniMax Anthropic-compatible HTTPS endpoint']), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    printResult(io, fail('config.set', 'CONFIG_SET_FAILED', message, {}, ['Check the config key and layer, then retry']), asJson);
+    process.exitCode = 1;
+}
+function registerMiniMaxProviderCommands(config, io) {
+    const minimaxProvider = config.command('provider').description('Manage model provider settings').command('minimax').description('Manage MiniMax provider settings');
+    addJsonOption(minimaxProvider.command('set').description('Set MiniMax provider settings in user config').option('--base-url <url>', 'MiniMax Anthropic-compatible base URL')).action((options) => {
+        const baseUrl = options.baseUrl?.trim();
+        const apiKey = process.env.MINIMAX_API_KEY?.trim();
+        if (!baseUrl && !apiKey) {
+            printResult(io, fail('config.provider.minimax.set', 'MINIMAX_PROVIDER_NO_VALUES', 'Provide --base-url and set MINIMAX_API_KEY', {}, ['Export MINIMAX_API_KEY and rerun peaks config provider minimax set --base-url <url>']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        if (baseUrl && !isMiniMaxHttpsUrl(baseUrl)) {
+            printResult(io, fail('config.provider.minimax.set', 'INVALID_MINIMAX_BASE_URL', 'MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials', {}, ['Use a MiniMax Anthropic-compatible HTTPS endpoint']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const input = {};
+            if (baseUrl)
+                input.baseUrl = baseUrl;
+            if (apiKey)
+                input.apiKey = apiKey;
+            const status = setMiniMaxProviderConfig(input);
+            printResult(io, ok('config.provider.minimax.set', status), options.json);
+        }
+        catch (error) {
+            printMiniMaxProviderSetError(io, error, options.json);
+        }
+    });
+    addJsonOption(minimaxProvider.command('get').description('Show redacted MiniMax provider settings')).action((options) => {
+        const configValue = getMiniMaxProviderConfig();
+        const status = getMiniMaxProviderStatus();
+        printResult(io, ok('config.provider.minimax.get', { ...redactConfigSecrets(configValue, 'providers.minimax'), ...status }), options.json);
+    });
+    addJsonOption(minimaxProvider.command('status').description('Show MiniMax provider configuration status')).action((options) => {
+        printResult(io, ok('config.provider.minimax.status', getMiniMaxProviderStatus()), options.json);
+    });
+    addJsonOption(minimaxProvider.command('test').description('Run a redacted MiniMax provider smoke test').option('--model <model>', 'model name for the smoke test', 'MiniMax-M2.7')).action(async (options) => {
+        try {
+            const result = await testMiniMaxProvider(getMiniMaxProviderConfig(), { model: options.model });
+            const safeResult = summarizeMiniMaxSmokeResult(result);
+            if (!result.configured) {
+                printResult(io, fail('config.provider.minimax.test', 'MINIMAX_PROVIDER_NOT_CONFIGURED', 'MiniMax provider requires baseUrl and apiKey in user config', safeResult, ['Export MINIMAX_API_KEY or set MINIMAX_API_KEY']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, result.ok ? ok('config.provider.minimax.test', safeResult) : fail('config.provider.minimax.test', 'MINIMAX_PROVIDER_TEST_FAILED', 'MiniMax provider smoke test failed', safeResult, ['Check the MiniMax base URL, API key, and model name']), options.json);
+            if (!result.ok)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            printResult(io, fail('config.provider.minimax.test', 'MINIMAX_PROVIDER_TEST_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check network connectivity and MiniMax provider settings']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+function printMiniMaxProviderSetError(io, error, asJson) {
+    if (getErrorMessage(error) === 'MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials') {
+        printResult(io, fail('config.provider.minimax.set', 'INVALID_MINIMAX_BASE_URL', 'MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials', {}, ['Use a MiniMax Anthropic-compatible HTTPS endpoint']), asJson);
+        process.exitCode = 1;
+        return;
+    }
+    printResult(io, fail('config.provider.minimax.set', 'MINIMAX_PROVIDER_SET_FAILED', getErrorMessage(error), {}, ['Check MiniMax provider settings and retry']), asJson);
+    process.exitCode = 1;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * `peaks context <sub>` — CLI surface for the ContextBuilder.
+ * Per spec §4.1 — these commands are the only sanctioned entry point;
+ * peaks-rd / peaks-qa / peaks-mut invoke them programmatically.
+ */
+import { Command } from 'commander';
+import type { DocFetcher } from '../../services/context/doc-retriever.js';
+export interface ContextCommandsOptions {
+    readonly fetcher: DocFetcher;
+}
+export declare function createContextCommands(options: ContextCommandsOptions): Command;

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

@@ -0,0 +1,85 @@
+/**
+ * `peaks context <sub>` — CLI surface for the ContextBuilder.
+ * Per spec §4.1 — these commands are the only sanctioned entry point;
+ * peaks-rd / peaks-qa / peaks-mut invoke them programmatically.
+ */
+import { Command } from 'commander';
+import { readFile } from 'node:fs/promises';
+import { buildContext } from '../../services/context/context-builder.js';
+import { ContextJsonSchema } from '../../services/context/context-schema.js';
+export function createContextCommands(options) {
+    const context = new Command('context').description('peaks-context: build versioned, version-locked context.json (spec §4.1)');
+    context
+        .command('build')
+        .requiredOption('--goal <text>', 'user request goal')
+        .requiredOption('--project <path>', 'project root')
+        .option('--audience <role>', 'peaks-rd | peaks-qa | peaks-mut | all', 'all')
+        .option('--deps-mode <mode>', 'locked | latest', 'locked')
+        .option('--doc-budget-tokens <n>', 'token budget for renderer', '8000')
+        .requiredOption('--out <path>', 'output path for context.json')
+        .option('--json', 'machine-readable output', false)
+        .action(async (opts) => {
+        const ctx = await buildContext({
+            goal: opts.goal,
+            project: opts.project,
+            audience: opts.audience,
+            depsMode: opts.depsMode,
+            docBudgetTokens: Number(opts.docBudgetTokens),
+            out: opts.out,
+            fetcher: options.fetcher,
+        });
+        if (opts.json) {
+            process.stdout.write(JSON.stringify({ ok: true, sha256: ctx.sha256 }) + '\n');
+        }
+        else {
+            process.stdout.write(`context.json written: ${opts.out}\nsha256: ${ctx.sha256}\n`);
+        }
+    });
+    context
+        .command('validate <file>')
+        .action(async (file) => {
+        const raw = await readFile(file, 'utf8');
+        const parsed = JSON.parse(raw);
+        const result = ContextJsonSchema.safeParse(parsed);
+        if (!result.success) {
+            process.stderr.write(`INVALID: ${result.error.message}\n`);
+            process.exit(2);
+        }
+        process.stdout.write(`OK: ${file}\n`);
+    });
+    context
+        .command('inspect <file>')
+        .action(async (file) => {
+        const raw = await readFile(file, 'utf8');
+        const ctx = JSON.parse(raw);
+        process.stdout.write([
+            `version: ${ctx.version}`,
+            `goal: ${ctx.goal}`,
+            `sha256: ${ctx.sha256}`,
+            `deps: ${Object.keys(ctx.collector.deps).join(', ')}`,
+            `fetchedDocs: ${ctx.docRetriever.fetchedDocs.length}`,
+            `skipped: ${ctx.docRetriever.skipped.length}`,
+            `truncated: ${ctx.renderer.truncated}`,
+            `audience: ${ctx.renderer.audience}`,
+        ].join('\n') + '\n');
+    });
+    context
+        .command('schema')
+        .action(async () => {
+        // Pre-flight fix #3: read from the canonical schemas/context.schema.json
+        // (generated by Task 12) instead of serializing Zod internals at runtime.
+        // Both files must agree; if schema.json is missing, this command fails
+        // with a clear message pointing at Task 12.
+        const fs = await import('node:fs/promises');
+        try {
+            const content = await fs.readFile('schemas/context.schema.json', 'utf8');
+            process.stdout.write(content + '\n');
+        }
+        catch {
+            process.stderr.write('BLOCKED: schemas/context.schema.json not found.\n' +
+                'Run Task 12 of Plan 1 to generate it.\n');
+            process.exit(2);
+        }
+    });
+    return context;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
+ *
+ * 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)
+ *   - L3: fuzzy search by query (delegates to peaks memory search)
+ *
+ * The LLM-side UX layer (peaks-code / peaks-ide) picks the layer based
+ * on the L1a task level:
+ *   - typo:     L0 only (a few lines)
+ *   - bug:     L0 + L1
+ *   - feature: L0 + L1 + L2 + L3(按需)
+ *   - refactor: L0 + L1 + L2 + L3
+ *   - migration: L0 + L1 + L2 + L3 + codegraph
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export type ContextLayer = 'L0' | 'L1' | 'L2' | 'L3';
+export declare function registerContextCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,254 @@
+/**
+ * peaks context * CLI (Slice #3 L1c) — context 4-layer loader.
+ *
+ * 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)
+ *   - L3: fuzzy search by query (delegates to peaks memory search)
+ *
+ * The LLM-side UX layer (peaks-code / peaks-ide) picks the layer based
+ * on the L1a task level:
+ *   - typo:     L0 only (a few lines)
+ *   - bug:     L0 + L1
+ *   - feature: L0 + L1 + L2 + L3(按需)
+ *   - refactor: L0 + L1 + L2 + L3
+ *   - migration: L0 + L1 + L2 + L3 + codegraph
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { searchMemory } from '../../services/memory/memory-search-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+import { emitObservabilityEvent } from '../../services/observability/observability-service.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+import { evaluateMainSessionThreshold, pickMainSessionTrigger, formatMainSessionTriggerLogLine, detectIdeFromEnv } from '../../services/context/main-session-monitor.js';
+const SKILLS_DIR = 'skills';
+function readSkillsDir(projectRoot) {
+    const skillsRoot = join(projectRoot, SKILLS_DIR);
+    if (!existsSync(skillsRoot))
+        return [];
+    const out = [];
+    for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory() || entry.name.startsWith('.'))
+            continue;
+        const skillMd = join(skillsRoot, entry.name, 'SKILL.md');
+        if (existsSync(skillMd)) {
+            out.push(`skills/${entry.name}/SKILL.md`);
+        }
+    }
+    return out;
+}
+function readSkillFile(projectRoot, relPath) {
+    const abs = join(projectRoot, relPath);
+    try {
+        return readFileSync(abs, 'utf-8');
+    }
+    catch {
+        return '';
+    }
+}
+async function fetchL0(projectRoot) {
+    const files = readSkillsDir(projectRoot);
+    const warnings = [];
+    let content = '';
+    let byteSize = 0;
+    const sizes = [];
+    for (const rel of files) {
+        const body = readSkillFile(projectRoot, rel);
+        if (body.length === 0) {
+            warnings.push(`failed to read ${rel}`);
+            continue;
+        }
+        content += `## ${rel}\n\n${body}\n\n`;
+        sizes.push({ path: rel, bytes: body.length });
+        byteSize += body.length;
+    }
+    return { layer: 'L0', description: 'full read: every SKILL.md concatenated', files: sizes, content, byteSize, warnings };
+}
+async function fetchL1(projectRoot) {
+    const files = readSkillsDir(projectRoot);
+    const warnings = [];
+    let content = '';
+    let byteSize = 0;
+    const sizes = [];
+    for (const rel of files) {
+        const body = readSkillFile(projectRoot, rel);
+        if (body.length === 0) {
+            warnings.push(`failed to read ${rel}`);
+            continue;
+        }
+        const firstPara = body.split(/\r?\n\r?\n/, 2)[0] ?? body.slice(0, 400);
+        content += `## ${rel}\n\n${firstPara}\n\n`;
+        sizes.push({ path: rel, bytes: firstPara.length });
+        byteSize += firstPara.length;
+    }
+    return { layer: 'L1', description: 'summary: first paragraph per skill', files: sizes, content, byteSize, warnings };
+}
+async function fetchL2(projectRoot) {
+    const files = readSkillsDir(projectRoot);
+    const content = files.map((f) => `- ${f}`).join('\n') + '\n';
+    const byteSize = content.length;
+    return {
+        layer: 'L2',
+        description: 'index: skill paths only (no body)',
+        files: files.map((f) => ({ path: f, bytes: 0 })),
+        content,
+        byteSize,
+        warnings: [],
+    };
+}
+async function fetchL3(projectRoot, query) {
+    const warnings = [];
+    if (query.trim().length === 0) {
+        warnings.push('empty query; L3 requires a --query string for fuzzy search');
+        return { layer: 'L3', description: 'fuzzy search (empty query)', files: [], content: '', byteSize: 0, warnings };
+    }
+    try {
+        const hits = searchMemory({ projectRoot, query, limit: 10 });
+        const lines = [];
+        for (const hit of hits) {
+            lines.push(`- [${hit.score.toFixed(2)}] ${hit.sourcePath}: ${hit.description.slice(0, 120)}`);
+        }
+        const content = lines.join('\n') + '\n';
+        return {
+            layer: 'L3',
+            description: 'fuzzy search: top 10 hits from memory index',
+            files: hits.map((h) => ({ path: h.sourcePath, bytes: h.description.length })),
+            content,
+            byteSize: content.length,
+            warnings,
+        };
+    }
+    catch (error) {
+        return {
+            layer: 'L3',
+            description: 'fuzzy search (failed)',
+            files: [],
+            content: '',
+            byteSize: 0,
+            warnings: [`L3 search failed: ${getErrorMessage(error)}`],
+        };
+    }
+}
+export function registerContextCommands(program, io) {
+    const context = program
+        .command('context')
+        .description('Slice L1c: context 4-layer loader (L0 full / L1 summary / L2 index / L3 fuzzy)');
+    addJsonOption(context
+        .command('layer')
+        .description('Fetch a context layer (L0 = full SKILL.md; L1 = first paragraph; L2 = index; L3 = fuzzy search by --query)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--level <L0|L1|L2|L3>', 'context layer to load')
+        .option('--query <text>', 'fuzzy search query (required for L3)')).action(async (options) => {
+        try {
+            const level = options.level;
+            if (level !== 'L0' && level !== 'L1' && level !== 'L2' && level !== 'L3') {
+                printResult(io, fail('context.layer', 'INVALID_LEVEL', `level must be one of L0, L1, L2, L3 (got ${level})`, { provided: level }, ['Pass --level L0|L1|L2|L3']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            let payload;
+            if (level === 'L0')
+                payload = await fetchL0(options.project);
+            else if (level === 'L1')
+                payload = await fetchL1(options.project);
+            else if (level === 'L2')
+                payload = await fetchL2(options.project);
+            else
+                payload = await fetchL3(options.project, options.query ?? '');
+            printResult(io, ok('context.layer', payload, [], [
+                `${payload.layer} loaded: ${payload.byteSize} bytes across ${payload.files.length} file(s)`,
+                payload.warnings.length > 0 ? `${payload.warnings.length} warning(s); see envelope.warnings` : null
+            ].filter((x) => typeof x === 'string')), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('context.layer', 'CONTEXT_LAYER_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path and --level value']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(context
+        .command('status')
+        .description('v2.11.0 D6: report main-session threshold tier for a given prompt size (no trigger dispatched). Useful for `--json` probes before invoking `peaks context check --auto-trigger`.')
+        .requiredOption('--prompt-size <bytes>', 'estimated prompt size in bytes')
+        .option('--capacity <bytes>', 'override the 256K default capacity (test seam)', '262144')).action((opts) => {
+        try {
+            const promptSize = Number(opts.promptSize);
+            const capacity = opts.capacity !== undefined ? Number(opts.capacity) : undefined;
+            if (!Number.isFinite(promptSize) || promptSize < 0) {
+                printResult(io, fail('context.status', 'INVALID_PROMPT_SIZE', `prompt-size must be a non-negative number (got "${opts.promptSize}")`, { provided: opts.promptSize }, ['Pass --prompt-size <bytes>']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const evaluation = evaluateMainSessionThreshold(promptSize, capacity);
+            printResult(io, ok('context.status', { ...evaluation, ide: detectIdeFromEnv() }, [...evaluation.warnings], [
+                `Main-session tier=${evaluation.tier} (${(evaluation.ratio * 100).toFixed(0)}%)`
+            ]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('context.status', 'CONTEXT_STATUS_FAILED', getErrorMessage(err), null, ['Verify --prompt-size is a non-negative number']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(context
+        .command('check')
+        .description('v2.11.0 D6: threshold check + IDE-aware trigger dispatch. With --auto-trigger, returns the trigger path the LLM should follow; without, returns a dry-run recommendation. The LLM is responsible for actually invoking the trigger (slash command, self-compress, or escalation).')
+        .requiredOption('--prompt-size <bytes>', 'estimated prompt size in bytes')
+        .option('--capacity <bytes>', 'override the 256K default capacity (test seam)', '262144')
+        .option('--in-flight-batch', 'a sub-agent batch is in flight (defer trigger per D6.e)', false)
+        .option('--auto-trigger', 'return the trigger path the LLM should follow', false)).action((opts) => {
+        try {
+            const promptSize = Number(opts.promptSize);
+            const capacity = opts.capacity !== undefined ? Number(opts.capacity) : undefined;
+            if (!Number.isFinite(promptSize) || promptSize < 0) {
+                printResult(io, fail('context.check', 'INVALID_PROMPT_SIZE', `prompt-size must be a non-negative number (got "${opts.promptSize}")`, { provided: opts.promptSize }, ['Pass --prompt-size <bytes>']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const trigger = pickMainSessionTrigger({
+                promptSize,
+                capacityBytes: capacity,
+                inFlightBatch: opts.inFlightBatch === true ? { hasInFlightBatch: true, sharedChannelEntries: 1 } : undefined
+            });
+            // Slice C of v2.11.1 — observability hook #5/7. Fire-and-forget
+            // per PRD Q4. The synchronous emit never throws.
+            const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+            const sid = getSessionIdCanonical(projectRoot) ?? '';
+            if (sid.length > 0) {
+                emitObservabilityEvent({
+                    schemaVersion: 1,
+                    ts: new Date().toISOString(),
+                    sessionId: sid,
+                    category: 'context-trigger',
+                    detail: {
+                        kind: trigger.kind,
+                        promptSize,
+                        ...(trigger.kind === 'soft-warn' || trigger.kind === 'compact'
+                            ? { ratio: trigger.ratio }
+                            : {})
+                    }
+                }, { projectRoot });
+            }
+            const logLine = formatMainSessionTriggerLogLine(trigger, 'main');
+            const payload = {
+                ...trigger,
+                autoTrigger: opts.autoTrigger === true,
+                logLine
+            };
+            printResult(io, ok('context.check', payload, [], [
+                trigger.kind === 'compact'
+                    ? `Tier reached → trigger ${trigger.path} on ${trigger.ide} (code=${trigger.code})`
+                    : trigger.kind === 'defer'
+                        ? `Deferred: ${trigger.reason}`
+                        : trigger.kind === 'soft-warn'
+                            ? `Soft warning at ${(trigger.ratio * 100).toFixed(0)}% (no trigger yet)`
+                            : 'Below threshold; no trigger'
+            ]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('context.check', 'CONTEXT_CHECK_FAILED', getErrorMessage(err), null, ['Verify --prompt-size is a non-negative number']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,26 @@
+/**
+ * `peaks contract` CLI commands — 2.7.0 slice-dag-dispatcher MVP
+ * (slice 1.2.c — LLM-side contract writer).
+ *
+ * Round-2 fix #5 (upgrade placeholder prompt) tells the LLM-side
+ * runner to execute `peaks contract write --project <root> ...` to
+ * persist its slice's public surface so the orchestrator can splice
+ * the contract into downstream dispatch prompts via
+ * `formatContractInjection`. This file is the actual implementation
+ * of that command — without it, the round-2 prompt would direct the
+ * LLM to a CLI that doesn't exist (the round-5 audit caught this).
+ *
+ * The command is a thin wrapper over `writeContract` from
+ * `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-loop.
+ *
+ * Skill-first / CLI-auxiliary red line: users do not invoke this
+ * directly. The peaks-code / peaks-rd LLM-side runner (the
+ * IDE-resident sub-agent that finished a slice) calls this command
+ * after the slice completes.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerContractCommands(program: Command, io: ProgramIO): void;