peaks-cli 1.4.2 → 2.0.0

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

@@ -2,6 +2,10 @@ import { addJsonOption, printResult } from '../cli-helpers.js';
 import { detectIdeFromContext, parseAdapterStdin, parseClaudeShapeStdin, pluckObject, pluckString } from '../../services/ide/hook-translator.js';
 import { buildCanonicalHook, formatDecisionResponse } from '../../services/ide/hook-protocol.js';
 import { getAdapter } from '../../services/ide/ide-registry.js';
+import { evaluateSoloCodeBan } from '../../services/audit/enforcers/solo-code-ban.js';
+import { isRootWrite } from '../../services/audit/enforcers/no-root-pollution.js';
+import { checkLoginGate } from '../../services/audit/enforcers/login-gate.js';
+import { resolveActiveSkillForCaller } from '../../services/audit/enforcers/active-skill-resolver.js';
 import { fail, ok } from '../../shared/result.js';
 /**
  * Read the hook payload. `PEAKS_HOOK_STDIN` is a test seam (same convention as
@@ -77,6 +81,21 @@ export function registerHookHandleCommand(program, io) {
             // Dispatch by toolName. For slice #1+, we only handle Bash. Task tool sub-agent dispatch goes through `peaks sub-agent dispatch` (slice #009) and does not need a hook entry.
             // Other tools: allow (no-op; future events will be added here).
             if (hook.toolName === 'Bash' && typeof fallbackCommand === 'string' && fallbackCommand.trim().length > 0) {
+                // L2.1 P0 #1: solo-code-ban. Deny `git commit` / `git apply` from peaks-* skills
+                // BEFORE the SOP gate runs. The active skill is read from the per-caller
+                // active-skill file (see active-skill-resolver.ts).
+                const activeSkill = resolveActiveSkillForCaller(projectRoot);
+                if (activeSkill.skill !== null) {
+                    const soloDecision = evaluateSoloCodeBan({ skill: activeSkill.skill, command: fallbackCommand });
+                    if (soloDecision.denied) {
+                        const formatted = formatDecisionResponse(ide, 'deny', soloDecision.reason);
+                        io.stdout(formatted.stdout);
+                        if (options.json === true) {
+                            io.stderr(JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: soloDecision.reason, enforcer: 'solo-code-ban' })));
+                        }
+                        return;
+                    }
+                }
                 // Lazy import to avoid circular: peaks gate enforce logic
                 const { enforceBashCommand } = await import('../../services/sop/gate-enforce-service.js');
                 const decision = await enforceBashCommand(projectRoot, fallbackCommand);
@@ -89,6 +108,37 @@ export function registerHookHandleCommand(program, io) {
                     return;
                 }
             }
+            // L2.2 P1 #1: login-gate. After solo-code-ban + gate-enforce pass,
+            // flag destructive patterns (uninstall, force-push, --force, --hard,
+            // rm -rf) so the LLM gets a soft warning (still allow). The user
+            // gets the warning via the warn channel; the command proceeds.
+            if (hook.toolName === 'Bash' && typeof fallbackCommand === 'string') {
+                const gate = checkLoginGate({ command: fallbackCommand });
+                if (gate.destructive) {
+                    io.stderr(`warning: login-gate: destructive command detected (pattern: ${gate.matchedPattern}). Confirm with the user before proceeding.`);
+                }
+            }
+            // L2.1 P0 #2: no-root-pollution. Deny Write/Edit to files outside the
+            // root allowlist. file_path is read from toolInput.file_path (Claude
+            // and most IDEs use the same shape). When the field is missing or the
+            // path is not at depth 1, the enforcer allows (no-op).
+            if (hook.toolName === 'Write' || hook.toolName === 'Edit' || hook.toolName === 'MultiEdit' || hook.toolName === 'Create') {
+                const filePath = pluckString(parsed, ['tool_input', 'file_path'])
+                    ?? pluckString(parsed, ['toolInput', 'file_path'])
+                    ?? pluckString(parsed, ['tool_input', 'path'])
+                    ?? pluckString(parsed, ['toolInput', 'path']);
+                if (typeof filePath === 'string' && filePath.trim().length > 0) {
+                    const rootCheck = isRootWrite({ projectRoot, filePath });
+                    if (!rootCheck.allowed) {
+                        const formatted = formatDecisionResponse(ide, 'deny', rootCheck.denyReason);
+                        io.stdout(formatted.stdout);
+                        if (options.json === true) {
+                            io.stderr(JSON.stringify(ok('hook.handle', { ide, tool: hook.toolName, decision: 'deny', reason: rootCheck.denyReason, enforcer: 'no-root-pollution' })));
+                        }
+                        return;
+                    }
+                }
+            }
             const allow = formatDecisionResponse(ide, 'allow');
             io.stdout(allow.stdout);
             if (options.json === true) {

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

@@ -0,0 +1,21 @@
+/**
+ * peaks loop * CLI (Slice #14) — L4 Agent Loop Integration.
+ *
+ * Per docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5.4
+ * Slice #14, ships 5 sub-features:
+ *
+ *   14.1 peaks loop distill          — extract patterns from past sessions
+ *                                       (delegates to peaks memory extract)
+ *   14.2 peaks loop preflight        — pre-run sanity checks (placeholder)
+ *   14.3 peaks loop detect-pattern   — find repeating patterns (placeholder)
+ *   14.4 peaks loop check-consistency — verify state consistency (placeholder)
+ *   14.5 peaks goal compose          — autonomous goal composition (placeholder;
+ *                                       requires IDE adapter goalCommand capability
+ *                                       per Slice #0.7)
+ *
+ * The 4 placeholders emit a clear nextActions list; the LLM-side UX
+ * layer composes the actual runtime today.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerLoopCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,128 @@
+/**
+ * peaks loop * CLI (Slice #14) — L4 Agent Loop Integration.
+ *
+ * Per docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §5.4
+ * Slice #14, ships 5 sub-features:
+ *
+ *   14.1 peaks loop distill          — extract patterns from past sessions
+ *                                       (delegates to peaks memory extract)
+ *   14.2 peaks loop preflight        — pre-run sanity checks (placeholder)
+ *   14.3 peaks loop detect-pattern   — find repeating patterns (placeholder)
+ *   14.4 peaks loop check-consistency — verify state consistency (placeholder)
+ *   14.5 peaks goal compose          — autonomous goal composition (placeholder;
+ *                                       requires IDE adapter goalCommand capability
+ *                                       per Slice #0.7)
+ *
+ * The 4 placeholders emit a clear nextActions list; the LLM-side UX
+ * layer composes the actual runtime today.
+ */
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export function registerLoopCommands(program, io) {
+    // 14.5 peaks goal compose — registered as a TOP-LEVEL command (not under
+    // `peaks loop`) because IDE adapters expose it as `goalCommand`.
+    // The sub-agent dispatch path consumes it; the slice 0.7 hermes +
+    // openclaw adapters will thread it through.
+    addJsonOption(program
+        .command('goal')
+        .description('14.5: compose an autonomous goal (returns the goal envelope that the LLM-side UX layer feeds to peaks sub-agent dispatch)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--goal <text>', 'the high-level goal to compose')).action(async (options) => {
+        try {
+            printResult(io, ok('goal.compose', {
+                project: options.project,
+                goal: options.goal,
+                status: 'placeholder',
+                nextSteps: [
+                    'The composed goal is consumed by peaks sub-agent dispatch.',
+                    'The hermes + openclaw IDE adapters (Slice #0.7) surface this as a goalCommand.',
+                ],
+            }, [], [
+                'goal.compose is a thin facade; the LLM-side UX layer decomposes the goal into sub-agent tasks.',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('goal.compose', 'GOAL_COMPOSE_FAILED', getErrorMessage(error), { project: options.project, goal: options.goal }, ['Verify the project path and --goal value']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // peaks loop *
+    const loop = program.command('loop').description('Slice #14: L4 Agent Loop sub-features (distill / preflight / detect-pattern / check-consistency)');
+    // 14.1 distill
+    addJsonOption(loop.command('distill')
+        .description('14.1: distill patterns from past sessions into .peaks/memory/ (delegates to peaks memory extract)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'write extracted memories to .peaks/memory/ (default: dry-run preview)', false)).action(async (options) => {
+        try {
+            const apply = options.apply === true;
+            // Delegate to the existing peaks memory extract CLI via dynamic
+            // import (avoids circular); the LLM-side UX layer composes the
+            // two commands.
+            const { execFileSync } = await import('node:child_process');
+            const args = ['memory', 'extract', '--project', options.project];
+            if (apply)
+                args.push('--apply');
+            const stdout = execFileSync('node', ['bin/peaks.js', ...args], {
+                cwd: options.project,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).toString('utf-8');
+            printResult(io, ok('loop.distill', {
+                project: options.project,
+                apply,
+                delegateStdout: stdout.slice(0, 200),
+            }, [], [
+                apply ? 'peaks memory extract --apply was invoked' : 'peaks memory extract dry-run was invoked',
+                'A future slice will inline the memory extract (not via execFileSync).',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('loop.distill', 'LOOP_DISTILL_FAILED', getErrorMessage(error), { project: options.project }, ['Verify the project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // 14.2 preflight
+    addJsonOption(loop.command('preflight')
+        .description('14.2: pre-run sanity checks (placeholder; future slice runs peaks doctor + peaks audit before each loop iter)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        printResult(io, ok('loop.preflight', {
+            project: options.project,
+            status: 'placeholder',
+            nextSteps: [
+                'For each L4 loop iteration, call peaks doctor + peaks audit to surface regressions.',
+                'A future slice will inline the preflight checks (not just placeholder).',
+            ],
+        }, [], [
+            'loop.preflight is a thin facade; the LLM-side UX layer composes peaks doctor + peaks audit.',
+        ]), options.json);
+    });
+    // 14.3 detect-pattern
+    addJsonOption(loop.command('detect-pattern')
+        .description('14.3: detect repeating patterns across past sessions (placeholder; future slice uses peaks retrospective search)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        printResult(io, ok('loop.detect-pattern', {
+            project: options.project,
+            status: 'placeholder',
+            nextSteps: [
+                'Run peaks retrospective search --limit 50 to surface high-frequency patterns.',
+                'A future slice will rank by frequency + LLM confidence.',
+            ],
+        }, [], [
+            'loop.detect-pattern is a thin facade; the LLM-side UX layer composes peaks retrospective search.',
+        ]), options.json);
+    });
+    // 14.4 check-consistency
+    addJsonOption(loop.command('check-consistency')
+        .description('14.4: verify state consistency (placeholder; future slice compares .peaks/_runtime across sessions)')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        printResult(io, ok('loop.check-consistency', {
+            project: options.project,
+            status: 'placeholder',
+            nextSteps: [
+                'Compare .peaks/_runtime/<sid>/session.json across recent sessions for drift.',
+                'A future slice will report drift with severity (warn / fail).',
+            ],
+        }, [], [
+            'loop.check-consistency is a thin facade; the LLM-side UX layer composes the drift scan.',
+        ]), options.json);
+    });
+}

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

@@ -5,6 +5,8 @@ import { renderOpenSpecChange } from '../../services/openspec/openspec-render-se
 import { validateOpenSpecChange } from '../../services/openspec/openspec-validate-service.js';
 import { archiveOpenSpecChange } from '../../services/openspec/openspec-archive-service.js';
 import { executeOpenSpecInit } from '../../services/openspec/openspec-init-service.js';
+import { proposeFromDoctor } from '../../services/openspec/openspec-propose-from-doctor-service.js';
+import { runDoctor } from '../../services/doctor/doctor-service.js';
 import { fail, ok } from '../../shared/result.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 function resolveScanOptions(project) {
@@ -197,4 +199,39 @@ export function registerOpenSpecCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    addJsonOption(openspec
+        .command('from-doctor')
+        .description('Slice L3.3: generate an OpenSpec change draft (proposal.md) from a peaks doctor finding')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--check-id <id>', 'the doctor check id to draft from (e.g. L3:l3-memory-health)')).action(async (options) => {
+        try {
+            const report = await runDoctor();
+            const finding = report.checks.find((c) => c.id === options.checkId);
+            if (finding === undefined) {
+                printResult(io, fail('openspec.from-doctor', 'CHECK_NOT_FOUND', `No doctor check with id "${options.checkId}"`, { availableIds: report.checks.map((c) => c.id) }, ['Run peaks doctor --json to list available check ids']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (finding.ok) {
+                printResult(io, fail('openspec.from-doctor', 'CHECK_ALREADY_PASSING', `Doctor check "${options.checkId}" is already passing; nothing to draft`, { checkId: options.checkId }, ['Pick a failing check from peaks doctor --json']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const doctorFinding = {
+                id: finding.id,
+                rule: finding.rule ?? finding.id,
+                detail: finding.message,
+                severity: 'fail',
+            };
+            const result = proposeFromDoctor({ projectRoot: options.project, finding: doctorFinding });
+            printResult(io, ok('openspec.from-doctor', result, [], [
+                `draft proposal written to ${result.proposalPath}`,
+                'Review + edit the draft, then run `peaks openspec validate <id>`',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.from-doctor', 'OPENSPEC_FROM_DOCTOR_FAILED', getErrorMessage(error), { projectRoot: options.project, checkId: options.checkId }, ['Verify the project path and the check id']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerPreferencesCommands(program: Command): void;

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

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { loadPreferences, preferencesPath, savePreferences, } from '../../services/preferences/preferences-service.js';
+const ALLOWED_KEYS = new Set([
+    'economyMode',
+    'swarmMode',
+    'uaPrompt',
+    'agentShieldPrompt',
+    'classifyConservatism',
+    'classifyRules',
+    'headroom',
+    'swarmSpeculative',
+    'loopAutonomousEnabled',
+]);
+export function registerPreferencesCommands(program) {
+    const prefs = program
+        .command('preferences')
+        .description('Manage project-local preferences (`.peaks/preferences.json`)');
+    prefs
+        .command('get')
+        .description('Get a preference value (from override or default)')
+        .requiredOption('--key <key>', 'preference key')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--json', 'JSON envelope output')
+        .action((opts) => {
+        try {
+            if (!ALLOWED_KEYS.has(opts.key)) {
+                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+            }
+            const all = loadPreferences(opts.project);
+            const value = all[opts.key];
+            const filePath = preferencesPath(opts.project);
+            // Spec bug fix: use the top-level existsSync import (the spec's
+            // `await import('node:fs')` would not compile inside a non-async action).
+            // Source is 'override' only when the key is explicitly present in
+            // the on-disk file (not merely when the file exists, since reset()
+            // may leave the file with other keys still overridden).
+            let source = 'default';
+            if (existsSync(filePath)) {
+                try {
+                    const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+                    if (Object.prototype.hasOwnProperty.call(raw, opts.key)) {
+                        source = 'override';
+                    }
+                }
+                catch {
+                    // Corrupt file: report the merged value but fall back to 'default'
+                    // source to avoid claiming an override that cannot be parsed.
+                    source = 'default';
+                }
+            }
+            // Stable ordering: source is computed, value reflects merged state.
+            const envelope = {
+                ok: true,
+                data: { key: opts.key, value, source },
+            };
+            process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(err.message + '\n');
+            process.exit(1);
+        }
+    });
+    prefs
+        .command('set')
+        .description('Override a preference value (writes to .peaks/preferences.json)')
+        .requiredOption('--key <key>', 'preference key')
+        .requiredOption('--value <value>', 'value (parsed as JSON, or string if not JSON)')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--json', 'JSON envelope output')
+        .action((opts) => {
+        try {
+            if (!ALLOWED_KEYS.has(opts.key)) {
+                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+            }
+            let parsed = opts.value;
+            try {
+                parsed = JSON.parse(opts.value);
+            }
+            catch {
+                // Not valid JSON — keep the raw string.
+            }
+            const merged = savePreferences(opts.project, {
+                [opts.key]: parsed,
+            });
+            const envelope = {
+                ok: true,
+                data: {
+                    key: opts.key,
+                    value: merged[opts.key],
+                },
+            };
+            process.stdout.write(JSON.stringify(envelope, null, 2) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(err.message + '\n');
+            process.exit(1);
+        }
+    });
+    prefs
+        .command('reset')
+        .description('Remove the override for a key (falls back to default)')
+        .requiredOption('--key <key>', 'preference key')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--json', 'JSON envelope output')
+        .action((opts) => {
+        try {
+            if (!ALLOWED_KEYS.has(opts.key)) {
+                throw new Error(`PREFERENCES_KEY_UNKNOWN: ${opts.key}`);
+            }
+            const filePath = preferencesPath(opts.project);
+            // Read raw on-disk state (not the merged view) so removing a key
+            // truly removes the override, instead of savePreferences re-inserting
+            // the default value. If no file exists, there is nothing to reset.
+            if (!existsSync(filePath)) {
+                const envelope = {
+                    ok: true,
+                    data: { key: opts.key, removed: false, reason: 'no-override-file' },
+                };
+                process.stdout.write(JSON.stringify(envelope) + '\n');
+                return;
+            }
+            let raw;
+            try {
+                raw = JSON.parse(readFileSync(filePath, 'utf8'));
+            }
+            catch (err) {
+                throw new Error(`PREFERENCES_JSON_INVALID: failed to parse ${filePath}: ${err.message}`);
+            }
+            const hadKey = Object.prototype.hasOwnProperty.call(raw, opts.key);
+            if (hadKey) {
+                delete raw[opts.key];
+                mkdirSync(dirname(filePath), { recursive: true });
+                writeFileSync(filePath, JSON.stringify(raw, null, 2) + '\n', 'utf8');
+            }
+            const envelope = {
+                ok: true,
+                data: { key: opts.key, removed: hadKey },
+            };
+            process.stdout.write(JSON.stringify(envelope) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(err.message + '\n');
+            process.exit(1);
+        }
+    });
+}

package/dist/src/cli/commands/skill-conformance-commands.d.ts

@@ -0,0 +1,9 @@
+/**
+ * peaks skills audit-conformance CLI (Slice #12) — runs the
+ * skill-conformance-service against all 12 peaks-* SKILL.md files and
+ * reports the 5 standard checks (frontmatter, CLI-back, loadStrategy,
+ * 800-line cap, outputStyle).
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSkillConformanceCommands(program: Command, io: ProgramIO): void;

package/dist/src/cli/commands/skill-conformance-commands.js

@@ -0,0 +1,39 @@
+/**
+ * peaks skills audit-conformance CLI (Slice #12) — runs the
+ * skill-conformance-service against all 12 peaks-* SKILL.md files and
+ * reports the 5 standard checks (frontmatter, CLI-back, loadStrategy,
+ * 800-line cap, outputStyle).
+ */
+import { auditSkillConformance } from '../../services/skills/skill-conformance-service.js';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export function registerSkillConformanceCommands(program, io) {
+    program
+        .command('skills:audit-conformance')
+        .description('Slice #12: audit all 12 peaks-* SKILL.md against the 5 alignment standards')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--json', 'print machine-readable JSON envelope')
+        .action(async (options) => {
+        try {
+            const report = auditSkillConformance({ projectRoot: options.project });
+            const nextActions = [];
+            if (report.failed > 0) {
+                nextActions.push(`${report.failed} hard failure(s); fix before shipping.`);
+                for (const c of report.checks.filter((c) => c.level === 'fail')) {
+                    nextActions.push(`  - ${c.skill}: ${c.id} — ${c.message}`);
+                }
+            }
+            if (report.warned > 0) {
+                nextActions.push(`${report.warned} advisory warning(s); see envelope.checks for details.`);
+            }
+            if (report.failed === 0 && report.warned === 0) {
+                nextActions.push('All 13 skills pass the 5 alignment standards.');
+            }
+            printResult(io, ok('skills.audit-conformance', report, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('skills.audit-conformance', 'AUDIT_CONFORMANCE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -75,4 +75,38 @@ export function registerUnderstandCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // L3.1: opt-in UX subcommand. Returns the AskUserQuestion payload that
+    // the LLM-side UX layer (peaks-solo / peaks-ide) should surface when
+    // uaPrompt === 'unset' and UA is absent. When uaPrompt is skip-this-session
+    // or skip-forever, returns a no-op envelope (caller does not prompt).
+    addJsonOption(understand
+        .command('opt-in')
+        .description('Returns the UA opt-in prompt payload (Slice L3.1) when uaPrompt is unset; no-op otherwise')
+        .requiredOption('--project <path>', 'target project root')).action(async (options) => {
+        try {
+            const report = await scanUnderstandAnything({ projectRoot: options.project });
+            const uaPrompt = report.uaPrompt ?? 'unset';
+            if (report.exists || uaPrompt !== 'unset') {
+                // No prompt needed: UA is installed OR user already decided.
+                printResult(io, ok('understand.opt-in', { promptNeeded: false, uaPrompt, uaInstalled: report.exists }), options.json);
+                return;
+            }
+            const prompt = {
+                version: 1,
+                tool: 'ua-opt-in',
+                artifactDir: report.artifactDir,
+                reason: 'ua-artifact-missing',
+                options: [
+                    { id: 'install', label: 'Install UA in Claude Code', description: INSTALL_HINT },
+                    { id: 'fallback-this-session', label: 'Use codegraph fallback this session', description: 'Skip UA this run; do not write preferences.json' },
+                    { id: 'fallback-forever', label: 'Use codegraph fallback forever', description: 'Write preferences.json:uaPrompt=skip-forever; suppress future prompts' }
+                ]
+            };
+            printResult(io, ok('understand.opt-in', { promptNeeded: true, uaPrompt, uaInstalled: false, prompt }), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.opt-in', 'UNDERSTAND_OPTIN_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path']), options.json);
+            process.exitCode = 1;
+        }
+    });
 }

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

@@ -0,0 +1,23 @@
+/**
+ * peaks upgrade * CLI surface — Slice: 1.x → 2.0 umbrella +
+ * Slice 3: --detect-1x flag.
+ *
+ * Per the "one-key completion" + "minimal-user-operation" tenets
+ * (2026-06-11), the user's typical upgrade path is
+ * `npm i -g peaks-cli@2.0` (the postinstall does the upgrade).
+ *
+ * The `peaks upgrade --to 2.0` CLI is the manual fallback for
+ * when the postinstall is skipped (e.g. CI uses
+ * `--ignore-scripts`). The umbrella orchestrates 7 sub-commands:
+ * config-migrate / standards-migrate / memory-extract /
+ * hooks-install / skill-sync / audit-verify + write-upgrade-record.
+ *
+ * The `--detect-1x` flag (added in slice 3) is a read-only
+ * probe that the peaks-solo skill calls to gate the
+ * AskUserQuestion that prompts the 1.x → 2.0 upgrade. The
+ * probe returns the JSON envelope from the
+ * 1x-detector-service; it does NOT modify any files.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerUpgradeCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,57 @@
+import { runUpgrade } from '../../services/upgrade/upgrade-service.js';
+import { detect1xProjectState } from '../../services/upgrade/1x-detector-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export function registerUpgradeCommands(program, io) {
+    addJsonOption(program
+        .command('upgrade')
+        .description('Upgrade a peaks-cli 1.x project to 2.0. Umbrella that orquestrates 7 sub-commands: config-migrate / standards-migrate / memory-extract / hooks-install / skill-sync / audit-verify + write-upgrade-record. Per the "one-key completion" tenet, prefer letting `npm i -g peaks-cli@2.0` postinstall run this for you. Use `--detect-1x` for a read-only probe (no file writes) that the peaks-solo skill uses to gate the 1.x → 2.0 AskUserQuestion.')
+        .option('--to <version>', 'target version (only "2.0" supported)', '2.0')
+        .option('--project <path>', 'project root to upgrade (default: cwd)')
+        .option('--auto', 'non-interactive: accept soft-fail on any sub-step (used by the postinstall hook)')
+        .option('--detect-1x', 'read-only probe: returns the 1.x state as JSON (no file writes); consumed by peaks-solo Step 0.55 to gate the AskUserQuestion')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        // Branch 1: --detect-1x (read-only probe)
+        if (options.detect1x === true) {
+            try {
+                const state = detect1xProjectState(projectRoot);
+                const nextActions = [];
+                if (state.isOneX) {
+                    nextActions.push(`Detected 1.x state. peaks-solo Step 0.55 should present an AskUserQuestion to invoke \`peaks upgrade --to 2.0 --auto --project ${state.projectRoot ?? projectRoot}\`.`);
+                }
+                else {
+                    nextActions.push('No 1.x state detected. Proceed with the standing 2.0 layout.');
+                }
+                const envelope = ok('upgrade.detect-1x', state, [], nextActions);
+                printResult(io, envelope, options.json);
+            }
+            catch (error) {
+                const message = getErrorMessage(error);
+                printResult(io, fail('upgrade.detect-1x', 'DETECT_1X_FAILED', message, { isOneX: false, signals: [], projectRoot: null, configPath: null }, [message]), options.json);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        // Branch 2: the umbrella (existing behavior)
+        try {
+            const result = runUpgrade({ projectRoot, auto: options.auto === true });
+            const nextActions = [...result.nextActions];
+            if (result.failedCount > 0) {
+                nextActions.unshift(`${result.failedCount} sub-step(s) failed. Re-run \`peaks upgrade --to 2.0\` to retry.`);
+            }
+            if (result.upgradeRecordPath !== null) {
+                nextActions.push(`Upgrade record written: ${result.upgradeRecordPath}`);
+            }
+            const envelope = ok('upgrade', result, [...result.warnings], nextActions);
+            printResult(io, envelope, options.json);
+            if (result.failedCount > 0) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('upgrade', 'UPGRADE_FAILED', message, { applied: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}