peaks-loop 4.0.0-beta.2 → 4.0.0-beta.21

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

@@ -0,0 +1,193 @@
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult, getErrorMessage } from '../cli-helpers.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { buildStatusLineModel, parseStatusLineStdin } from '../../services/skills/skill-statusline-service.js';
+import { renderStatusLine } from '../../services/skills/skill-statusline-renderer.js';
+import { applyStatusLineInstall, planStatusLineInstall, removeStatusLineInstall } from '../../services/skills/statusline-settings-service.js';
+import { readHookStatus as readSettingsStatus } from '../../services/skills/hooks-settings-service.js';
+import { detectIdeFromContext } from '../../services/ide/hook-translator.js';
+const STDIN_READ_TIMEOUT_MS = 250;
+/** Read piped stdin if present; resolve quickly with '' when attached to a TTY. */
+function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY) {
+            resolve('');
+            return;
+        }
+        let data = '';
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(data);
+        };
+        const timer = setTimeout(finish, STDIN_READ_TIMEOUT_MS);
+        timer.unref?.();
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => {
+            clearTimeout(timer);
+            finish();
+        });
+        process.stdin.on('error', () => {
+            clearTimeout(timer);
+            finish();
+        });
+    });
+}
+function resolveScope(options) {
+    return options.global ? 'global' : 'project';
+}
+/**
+ * Resolve the IDE the install should target. The CLI user can override with
+ * `--ide <id>`. Otherwise we delegate to `detectIdeFromContext` which checks
+ * `process.env[adapter.envVar]` → stdin shape → cwd `.trae`/`.claude` →
+ * fallback `'claude-code'`. Pass `parsedStdin: null` since `peaks statusline
+ * install` is not invoked from inside an IDE hook — there's no stdin payload.
+ */
+function resolveIdeForCommand(options, projectRoot) {
+    if (options.ide !== undefined && options.ide.length > 0) {
+        return options.ide;
+    }
+    return detectIdeFromContext({ env: process.env, cwd: projectRoot ?? process.cwd(), parsedStdin: null });
+}
+/**
+ * Default-statusline render body. Reused by both the top-level default
+ * action (Bug-02 dispatch) and the explicit `render` subcommand. Exported
+ * so a unit test can exercise the JSON / text output paths without going
+ * through commander.
+ */
+export async function runDefaultStatuslineRender(options, io) {
+    const raw = await readStdin();
+    const stdin = parseStatusLineStdin(raw);
+    const seeded = options.project
+        ? { ...(stdin ?? {}), workspace: { current_dir: options.project } }
+        : stdin;
+    const model = buildStatusLineModel(seeded, Date.now());
+    const text = renderStatusLine(model);
+    if (options.json === true) {
+        io.stdout(JSON.stringify({ ok: true, command: 'statusline.render', data: { text } }, null, 2));
+        return;
+    }
+    io.stdout(text);
+}
+export function registerStatusLineCommands(program, io) {
+    // Top-level `peaks statusline` — register as a group with subcommands
+    // (install | uninstall | status). When the user runs `peaks statusline` with
+    // no subcommand, commander falls back to a hidden render subcommand so the
+    // status line still renders. This pattern is required by commander 12.x:
+    // when a command has both an action AND subcommands, commander's option
+    // parser conflates the parent's options with the subcommand's and drops
+    // flags. Routing through a subcommand (even one that's hidden) avoids the
+    // option-shadowing bug.
+    const statusline = addJsonOption(program
+        .command('statusline')
+        .description('Render the Peaks skill status line for the current session, or manage the adapter-driven statusLine entry. Run with no subcommand to render; with a subcommand (install | uninstall | status) to manage.')
+        .option('--project <path>', 'project root path (used to label the status line when stdin is absent; applies to the default render path)'));
+    // Default behavior: when the user types `peaks statusline` with no
+    // subcommand, render the status line. Without this default action,
+    // commander falls back to printing usage (Bug-02, ice-cola surface check
+    // 2026-07-22). The hidden `render` subcommand is preserved so callers
+    // can still invoke it explicitly.
+    //
+    // Note (commander 12.x): when both a top-level `.action(...)` and
+    // subcommands exist, commander's option parser can conflate parent and
+    // child flags. We therefore parse `process.argv` for the bare `statusline`
+    // invocation here, and otherwise let the subcommand machinery handle the
+    // rest. The implementation is wrapped in `peekDefaultStatuslineRender` so
+    // it can be exercised in isolation by unit tests.
+    statusline.action(async (_parentOptions, command) => {
+        await runDefaultStatuslineRender(command.opts(), io);
+    });
+    // Hidden render subcommand. Preserved for callers that want to invoke
+    // render explicitly without going through the default-action dispatch.
+    statusline
+        .command('render', { hidden: true })
+        .description('Render the Peaks skill status line for the current session (reads session JSON on stdin; honors --project for the project label).')
+        .option('--project <path>', 'project root path (used to label the status line when stdin is absent)')
+        .action(async (options) => {
+        await runDefaultStatuslineRender(options, io);
+    });
+    addJsonOption(statusline
+        .command('install')
+        .description("Install the Peaks status line into the adapter's settings.json (project scope by default).")
+        .option('--global', 'install into the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')
+        .option('--force', 'overwrite an existing non-Peaks statusLine entry')
+        .option('--dry-run', 'show what would change without writing')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = scope === 'project'
+            ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())
+            : undefined;
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            if (options.dryRun) {
+                const plan = planStatusLineInstall(scope, projectRoot, { ide });
+                const warnings = plan.conflict
+                    ? [`An existing statusLine command is set: ${plan.conflictCommand}. Rerun with --force to overwrite.`]
+                    : [];
+                printResult(io, ok('statusline.install', { ...plan, ide, applied: false, dryRun: true }, warnings), options.json);
+                return;
+            }
+            const result = applyStatusLineInstall(scope, projectRoot, { force: options.force === true, ide });
+            const warnings = result.conflict && !result.applied
+                ? [`An existing statusLine command is set: ${result.conflictCommand}. Rerun with --force to overwrite.`]
+                : [];
+            const nextActions = result.applied
+                ? ['Restart the IDE (or reload the workspace) so the status line takes effect']
+                : [];
+            printResult(io, ok('statusline.install', { ...result, ide, dryRun: false }, warnings, nextActions), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.install', 'STATUSLINE_INSTALL_FAILED', message, { scope, ide, applied: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(statusline
+        .command('uninstall')
+        .description("Remove the Peaks status line from the adapter's settings.json.")
+        .option('--global', 'remove from the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = scope === 'project'
+            ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())
+            : undefined;
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const result = removeStatusLineInstall(scope, projectRoot, { ide });
+            printResult(io, ok('statusline.uninstall', { ...result, ide }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.uninstall', 'STATUSLINE_UNINSTALL_FAILED', message, { scope, ide, removed: false }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(statusline
+        .command('status')
+        .description('Report whether the Peaks status line is installed in the adapter settings.json.')
+        .option('--global', 'inspect the user-level ~/.claude/settings.json instead of the project')
+        .option('--project <path>', 'project root path (auto-detected from cwd when omitted)')
+        .option('--ide <id>', 'target adapter id (claude-code | trae); default: auto-detect from env/cwd')).action((options) => {
+        const scope = resolveScope(options);
+        const projectRoot = scope === 'project'
+            ? (options.project ?? findProjectRoot(process.cwd()) ?? process.cwd())
+            : undefined;
+        const ide = resolveIdeForCommand(options, projectRoot);
+        try {
+            const status = readSettingsStatus(scope, projectRoot, { ide });
+            printResult(io, ok('statusline.status', { ...status, ide, command: 'peaks statusline' }), options.json);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('statusline.status', 'STATUSLINE_STATUS_FAILED', message, { scope, ide }, [message]), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/sub-agent-commands.js

@@ -0,0 +1,20 @@
+import { registerDispatchCommand } from './dispatch-commands.js';
+import { registerHeartbeatCommand } from './heartbeat-commands.js';
+import { registerShareCommand, registerSharedReadCommand, registerAwaitCommand, registerFinalizeCommand } from './share-commands.js';
+// Re-export `validateRole` for backward compat — the integration test
+// suite and any external callers still import it from this entry file.
+// The canonical implementation now lives in `sub-agent-shared.ts`.
+export { validateRole } from './sub-agent-shared.js';
+export function registerSubAgentCommands(program, io) {
+    const subAgent = program
+        .command('sub-agent')
+        .description('Sub-agent dispatch primitive (skill-first / CLI-auxiliary). ' +
+        'These commands are the primitives that peaks-code / peaks-rd / ' +
+        'peaks-qa SKILL.md compose. Users do not invoke this directly.');
+    registerDispatchCommand(subAgent, io);
+    registerHeartbeatCommand(subAgent, io);
+    registerShareCommand(subAgent, io);
+    registerSharedReadCommand(subAgent, io);
+    registerAwaitCommand(subAgent, io);
+    registerFinalizeCommand(subAgent, io); // D21
+}

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

@@ -0,0 +1,148 @@
+import { InvalidArgumentError } from 'commander';
+import { scanUnderstandAnything, summarizeKnowledgeGraph } from '../../services/understand/understand-scan-service.js';
+import { buildUnderstandContext } from '../../services/understand/understand-hybrid-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+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;
+}
+const INSTALL_HINT = 'Install Understand Anything in Claude Code: `/plugin marketplace add Lum1104/Understand-Anything` then `/plugin install understand-anything`, then run `/understand` in the target project to generate .understand-anything/knowledge-graph.json.';
+export function registerUnderstandCommands(program, io) {
+    const understand = program.command('understand').description('Inspect Understand Anything artifacts inside a project (read-only)');
+    addJsonOption(understand
+        .command('status')
+        .description('Report whether Understand Anything has produced a knowledge graph in the target project')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--artifact-dir <path>', 'override the default .understand-anything directory')).action(async (options) => {
+        try {
+            const scanOptions = { projectRoot: options.project };
+            if (options.artifactDir !== undefined) {
+                scanOptions.artifactDir = options.artifactDir;
+            }
+            const report = await scanUnderstandAnything(scanOptions);
+            const nextActions = [];
+            if (!report.exists) {
+                nextActions.push(INSTALL_HINT);
+            }
+            else if (!report.graph.exists) {
+                nextActions.push('Run `/understand` inside Claude Code on this project to generate .understand-anything/knowledge-graph.json.');
+            }
+            else if (report.graph.parseError !== undefined) {
+                nextActions.push('Re-run `/understand` to regenerate the knowledge graph; the current file is not valid JSON.');
+            }
+            printResult(io, ok('understand.status', report, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.status', 'UNDERSTAND_STATUS_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .understand-anything directory before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(understand
+        .command('show')
+        .description('Summarize the Understand Anything knowledge graph (counts, layers, tours, sample nodes) for RD/TXT consumption')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--artifact-dir <path>', 'override the default .understand-anything directory')
+        .option('--sample <n>', 'maximum number of sample node ids to return (default 5)', parsePositiveInteger)).action(async (options) => {
+        try {
+            const summaryOptions = { projectRoot: options.project };
+            if (options.artifactDir !== undefined) {
+                summaryOptions.artifactDir = options.artifactDir;
+            }
+            if (options.sample !== undefined) {
+                summaryOptions.sampleSize = options.sample;
+            }
+            const summary = await summarizeKnowledgeGraph(summaryOptions);
+            if (!summary.exists) {
+                printResult(io, fail('understand.show', 'UNDERSTAND_GRAPH_MISSING', `No knowledge graph found at ${summary.path}`, summary, [INSTALL_HINT]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (summary.parseError !== undefined) {
+                printResult(io, fail('understand.show', 'UNDERSTAND_GRAPH_PARSE_ERROR', `Knowledge graph at ${summary.path} is not valid JSON: ${summary.parseError}`, summary, ['Re-run `/understand` to regenerate the knowledge graph']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('understand.show', summary), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.show', 'UNDERSTAND_SHOW_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .understand-anything directory before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // L3.1: opt-in UX subcommand. Returns the AskUserQuestion payload that
+    // the LLM-side UX layer (peaks-code / 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;
+        }
+    });
+    // Slice 2026-07-02-codegraph-ua-hybrid: hybrid context subcommand.
+    // Routes UA-first / codegraph-fallback / hybrid in the service layer;
+    // the CLI is a thin shell that surfaces the envelope and exit code.
+    addJsonOption(understand
+        .command('context')
+        .description('Build a hybrid project-context envelope: UA knowledge graph when present, codegraph affected as fallback, or both in parallel')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--artifact-dir <path>', 'override the default .understand-anything directory')
+        .option('--sample <n>', 'maximum number of sample node ids to include (default 5)', parsePositiveInteger)
+        .option('--files <file...>', 'file globs to feed `codegraph affected` (default: src/index.ts, package.json, README.md)')).action(async (options) => {
+        try {
+            const ctxOptions = { projectRoot: options.project };
+            if (options.artifactDir !== undefined)
+                ctxOptions.artifactDir = options.artifactDir;
+            if (options.sample !== undefined)
+                ctxOptions.sampleSize = options.sample;
+            if (options.files !== undefined)
+                ctxOptions.files = options.files;
+            const result = await buildUnderstandContext(ctxOptions);
+            const exitCode = result.source === 'both-missing' ? 2 : 0;
+            if (exitCode !== 0) {
+                printResult(io, fail('understand.context', 'UNDERSTAND_CONTEXT_NO_EVIDENCE', `No UA graph and codegraph affected produced no usable evidence`, result, [
+                    INSTALL_HINT,
+                    'Run `peaks codegraph index` in this project to populate the codegraph index, then retry'
+                ]), options.json);
+                process.exitCode = exitCode;
+                return;
+            }
+            printResult(io, ok('understand.context', result, [], result.warnings.length > 0 ? result.warnings : undefined), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('understand.context', 'UNDERSTAND_CONTEXT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and codegraph installation before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

@@ -0,0 +1,119 @@
+import { runUpgrade } from '../../services/upgrade/upgrade-service.js';
+import { detect1xProjectState } from '../../services/upgrade/1x-detector-service.js';
+import { initWorkspace } from '../../services/workspace/workspace-service.js';
+import { ensureSessionWithRotation } from '../../services/session/session-manager.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+export function registerUpgradeCommands(program, io) {
+    addJsonOption(program
+        .command('upgrade', { hidden: true })
+        .description('Upgrade a peaks-loop 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-loop@2.0` postinstall run this for you. Use `--detect-1x` for a read-only probe (no file writes) that the peaks-code 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-code Step 0.55 to gate the AskUserQuestion')
+        .option('--apply-init', 'slice 4 (slice 2026-06-13-selfheal-claude-settings-template): run initWorkspace so the drift-driven self-heal fires on the consumer-project .claude/settings.local.json and the offline .peaks/.claude-settings-template.json. Idempotent. Use after a peaks-loop version bump if you do not otherwise re-run init. Mutually exclusive with --detect-1x.')).action(async (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-code 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: --apply-init (slice 4 — slice 2026-06-13-selfheal-claude-settings-template).
+        //
+        // The drift-driven self-heal inside initWorkspace only fires when
+        // the user invokes init. After a peaks-loop version bump, users who
+        // never re-run init are stuck with stale templates until they do.
+        // This flag is the post-bump escape hatch: it triggers init for them.
+        //
+        // We do NOT pass --session-id (the CLI auto-generates / reuses an
+        // existing binding). We do NOT pass --no-claude-hooks (the goal is to
+        // bring the project to the current peaks-loop baseline, including the
+        // consumer-project hook).
+        if (options.applyInit === true) {
+            try {
+                const canonicalRoot = resolveCanonicalProjectRoot(projectRoot);
+                // Match the workspace-init CLI's pattern: resolve the session id
+                // (auto-generate / reuse binding / rotate on outer-mismatch)
+                // BEFORE calling initWorkspace. initWorkspace itself validates
+                // the session id and does NOT auto-generate, so we have to do
+                // the rotation-aware resolution here.
+                const sessionResolution = await ensureSessionWithRotation(canonicalRoot, {
+                    skipRotateOnOuterMismatch: false
+                });
+                const result = await initWorkspace({
+                    projectRoot: canonicalRoot,
+                    sessionId: sessionResolution.sessionId,
+                    allowSessionRebind: false
+                });
+                const nextActions = [];
+                // Surface the same self-heal messaging that workspace-init uses.
+                if (result.claudeSettings.offlineTemplate.action === 'refreshed') {
+                    nextActions.push(`Self-healed .peaks/.claude-settings-template.json (action: refreshed) — ` +
+                        'the offline recovery anchor now matches the current peaks-loop template.');
+                    nextActions.push('⚠️  If you had manually edited .peaks/.claude-settings-template.json, ' +
+                        'those edits have been overwritten by the self-heal.');
+                }
+                else if (result.claudeSettings.offlineTemplate.action === 'written') {
+                    nextActions.push('Wrote .peaks/.claude-settings-template.json (action: written) — ' +
+                        'the offline recovery anchor is now in place.');
+                }
+                if (result.claudeSettings.action === 'refreshed') {
+                    nextActions.push(`Refreshed .claude/settings.local.json (action: refreshed) — ` +
+                        'the consumer-project hook now matches the current peaks-loop template. ' +
+                        'Restart Claude Code so the hooks take effect.');
+                }
+                else if (result.claudeSettings.action === 'written') {
+                    nextActions.push('Wrote .claude/settings.local.json (action: written) — ' +
+                        'the [Fact-Forcing Gate] bypass is now in effect. Restart Claude Code so the hooks take effect.');
+                }
+                const envelope = ok('upgrade.apply-init', result, [], nextActions);
+                printResult(io, envelope, options.json);
+            }
+            catch (error) {
+                const message = getErrorMessage(error);
+                printResult(io, fail('upgrade.apply-init', 'APPLY_INIT_FAILED', message, { applied: false }, [message]), options.json);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        // Branch 3: 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;
+        }
+    });
+}

package/dist/cli/commands/user-touchpoint-commands.js

@@ -0,0 +1,78 @@
+/**
+ * v2.15.0 follow-up — G4: user touchpoint CLI.
+ *
+ *   - `peaks code gate-classify --step <step-id>` — classify a single
+ *     Code gate (business / tech / mode-selection / commit-boundary /
+ *     commit-floor)
+ *   - `peaks code user-touchpoints`                — list all gates the
+ *     user must review (vs AI auto-decides in full-auto)
+ *   - `peaks code commit-boundary-actions`         — list the 5
+ *     hard-floor commit actions (push / tag / publish / global
+ *     install)
+ *
+ * Surfaces the 12 Gaps positioning memory rule:
+ *   "user 在循环里 = 业务/产品审阅者,不参与技术决策"
+ */
+import { aiAutoDecidesGates, classifyGate, COMMIT_BOUNDARY_ACTIONS_LIST, userMustReviewGates } from '../../services/code/user-touchpoint-classifier.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerUserTouchpointCommands(program, io) {
+    // G4 commands are registered as TOP-LEVEL commands (not sub-commands
+    // of `peaks code`) because `peaks code` is a SKILL (consumed by the
+    // LLM in SKILL.md), not a CLI command. Top-level names: gate-classify /
+    // user-touchpoints / commit-boundary-actions.
+    //
+    // We do NOT create a new `peaks code` CLI command here because that
+    // would conflict with the peaks-code skill presence tracking (see
+    // `src/services/skills/skill-presence-service.ts`).
+    addJsonOption(program
+        .command('gate-classify')
+        .description('v2.15.0 follow-up G4: classify a single Code gate by its decision kind: ' +
+        'business / tech / mode-selection / commit-boundary / commit-floor. ' +
+        'Returns null when the step is unknown.')
+        .requiredOption('--step <step-id>', 'step id (e.g. step-1-mode-select, phase-2-prd-confirm)')).action((opts) => {
+        const c = classifyGate(opts.step);
+        if (c === null) {
+            printResult(io, fail('code.gate-classify', 'UNKNOWN_STEP', `unknown step "${opts.step}"`, {}, [
+                'Run `peaks code user-touchpoints` to list all known steps.'
+            ]), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('code.gate-classify', { classification: c }, [], [
+            c.userShouldReview === 'always'
+                ? 'User must review this gate in all modes.'
+                : c.userShouldReview === 'business-only'
+                    ? 'User reviews this gate only when it surfaces a business decision.'
+                    : 'AI auto-decides this gate in full-auto. User does not need to review.'
+        ]), opts.json ?? false);
+    });
+    addJsonOption(program
+        .command('user-touchpoints')
+        .description('List all Code gates the user must review. The 12 Gaps positioning ' +
+        'memory: user 在循环里 = 业务/产品审阅者,不参与技术决策。 ' +
+        'These are the only gates where the user is asked to decide.')).action((opts) => {
+        const must = userMustReviewGates();
+        const auto = aiAutoDecidesGates();
+        printResult(io, ok('code.user-touchpoints', {
+            userMustReview: must,
+            aiAutoDecides: auto,
+            counts: {
+                userMustReview: must.length,
+                aiAutoDecides: auto.length
+            }
+        }, [], [
+            `User reviews ${must.length} gate(s); AI auto-decides ${auto.length} in full-auto.`,
+            'Goal: 减少 user 被打扰次数 from 14 → 6-8 (the must-review count).'
+        ]), opts.json ?? false);
+    });
+    addJsonOption(program
+        .command('commit-boundary-actions')
+        .description('List the 5 commit-boundary hard-floor actions. These are the ' +
+        'actions that PAUSE even in full-auto (v2.15.0 slice 002 AC-4 rule: ' +
+        '"full-auto 只做到 commit"). The user is always asked to confirm.')).action((opts) => {
+        printResult(io, ok('code.commit-boundary-actions', { actions: COMMIT_BOUNDARY_ACTIONS_LIST }, [], [
+            'Even in full-auto, the user must explicitly confirm these actions.'
+        ]), opts.json ?? false);
+    });
+}