peaks-loop 4.0.54 → 4.1.0

package/dist/cli/commands/best-practice-scan-helpers.d.ts

@@ -0,0 +1,12 @@
+export declare const CATCH_GATE_PROMPT: string;
+export declare const INTENT_REQUIRED_MESSAGE: string;
+export declare const SYNTHETIC_SOURCE_MESSAGE: string;
+export declare function bestPracticeDir(projectRoot: string): string;
+/** Refusal body for a synthetic scan. It is written to the artifact path so
+ *  the skip survives the fire-and-forget caller (`best-practice-auto-trigger`
+ *  spawns with `stdio: 'ignore'`, so stdout never reaches anyone). */
+export declare function renderSyntheticRefusal(opts: {
+    readonly intent: string;
+    readonly language: string;
+    readonly source: string;
+}): string;

package/dist/cli/commands/best-practice-scan-helpers.js

@@ -0,0 +1,37 @@
+/**
+ * Slice 2026-08-12 best-practice-scan — support constants + pure helpers
+ * extracted from `best-practice-scan-command.ts` (file-size cap campaign).
+ * Mechanical move only: help-text constants, the artifact directory path
+ * helper, and the synthetic-lookup refusal renderer.
+ */
+import { join } from 'node:path';
+export const CATCH_GATE_PROMPT = [
+    '⚠️ 任何跟你真实业务不一样,改 — LLM 推荐可能错。',
+    '回应 (默认 = 接受): 接受 / 接受方案 A|接受方案 B|接受方案 C / 拒绝 + 原因'
+].join('\n');
+export const INTENT_REQUIRED_MESSAGE = 'best-practice-scan requires --intent <text>: the intent is the business goal the scan is ' +
+    'for, not the project path. Deriving it from the project path labelled a scan with a ' +
+    'non-goal, so there is no fallback.';
+export const SYNTHETIC_SOURCE_MESSAGE = 'best-practice-scan: SKIPPED — the Context7 / WebSearch lookups in this build are stubs ' +
+    '(synthetic fragments), so no real documentation was consulted and there is nothing to ' +
+    'recommend. No recommendation, no comparison table and no ⚠️ catch gate were produced.';
+export function bestPracticeDir(projectRoot) {
+    return join(projectRoot, 'best-practice');
+}
+/** Refusal body for a synthetic scan. It is written to the artifact path so
+ *  the skip survives the fire-and-forget caller (`best-practice-auto-trigger`
+ *  spawns with `stdio: 'ignore'`, so stdout never reaches anyone). */
+export function renderSyntheticRefusal(opts) {
+    return [
+        `# Best-Practice Scan — ${opts.intent}`,
+        '',
+        '> SKIPPED — synthetic (stub) lookup. No real documentation lookup was performed.',
+        '',
+        SYNTHETIC_SOURCE_MESSAGE,
+        '',
+        `- language: ${opts.language}`,
+        `- transport that answered: ${opts.source} (stub)`,
+        '- Step 2.5: recorded as skipped, reason "synthetic-lookup". Re-run this step once the real',
+        '  lookup lands; a gate cannot be satisfied from a fabricated scan.'
+    ].join('\n');
+}

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

@@ -1,4 +1,4 @@
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import type { PeaksConfig } from '../../services/config/config-types.js';
 import type { CapabilityMapSourceFilter } from '../../services/recommendations/recommendation-types.js';
 import { type ProgramIO } from '../cli-helpers.js';

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

@@ -6,10 +6,16 @@ import { createCapabilityMapPlan } from '../../services/recommendations/capabili
 import { seedCapabilityItems, seedCapabilitySources } from '../../services/recommendations/seed-capability-catalog.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, printResult } from '../cli-helpers.js';
-const CAPABILITY_SOURCE_FILTERS = new Set(['all', 'access-repo', 'mcp-server']);
+const CAPABILITY_SOURCE_FILTERS = new Set([
+    'all',
+    'access-repo',
+    'mcp-server'
+]);
 export function registerCapabilityCommands(program, io) {
-    const capability = program.command('capability').description('Inspect Peaks capability catalog and runtime availability');
-    addJsonOption(capability.command("status").description("Show seed capability availability")).action((options) => runCapabilityStatus(io, options));
+    const capability = program
+        .command('capability')
+        .description('Inspect Peaks capability catalog and runtime availability');
+    addJsonOption(capability.command('status').description('Show seed capability availability')).action((options) => runCapabilityStatus(io, options));
     addCapabilityMapOptions(capability.command('map').description('Show dry-run external capability landing map')).action((options) => runCapabilityMap(io, options));
     addCapabilityMapOptions(program.command('capabilities').description('Show dry-run external capability landing map')).action((options) => runCapabilityMap(io, options));
 }
@@ -17,7 +23,11 @@ export function runCapabilityStatus(io, options) {
     const availability = resolveCapabilityAvailability(seedCapabilityItems, {
         installedCapabilityIds: getInstalledCapabilityIds(readConfig())
     });
-    printResult(io, ok("capability.status", { sources: seedCapabilitySources, items: seedCapabilityItems, availability }), options.json);
+    printResult(io, ok('capability.status', {
+        sources: seedCapabilitySources,
+        items: seedCapabilityItems,
+        availability
+    }), options.json);
 }
 function addCapabilityMapOptions(command) {
     return addJsonOption(command.option('--source <source>', 'Filter source group: all, access-repo, or mcp-server', 'all'));

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

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

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

@@ -21,26 +21,29 @@ export function registerChangesetCommands(program, io) {
         .description('Hard-gate check: exit non-zero if any .changeset/*.md file is staged ' +
         '(excluding README.md). Mirrors publish.yml gate-changeset step.')
         .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
-        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-        const gate = runChangesetHardGate(projectRoot);
-        if (gate.ok) {
-            printResult(io, ok('changeset.check', {
-                root: gate.root,
-                state: gate.state,
-                stagedFiles: gate.stagedFiles,
-                snapshotAt: gate.snapshotAt
-            }, [], []), opts.json ?? false);
-            return;
-        }
-        process.exitCode = 1;
-        printResult(io, fail('changeset.check', 'CHANGESET_BLOCKED', `${gate.stagedFiles.length} staged .changeset/*.md file(s) — refusing to proceed`, {
+        changesetCheckAction(opts, io);
+    });
+}
+function changesetCheckAction(opts, io) {
+    const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const gate = runChangesetHardGate(projectRoot);
+    if (gate.ok) {
+        printResult(io, ok('changeset.check', {
             root: gate.root,
             state: gate.state,
             stagedFiles: gate.stagedFiles,
             snapshotAt: gate.snapshotAt
-        }, [
-            `Drain pending changesets before proceeding: drain `.concat(gate.stagedFiles.join(', '), ' via the coordinating LLM (e.g. `pnpm changeset version` or `peaks changeset publish` if installed).'),
-            'Then re-run `peaks changeset check` to confirm a clean state.'
-        ]), opts.json ?? false);
-    });
+        }, [], []), opts.json ?? false);
+        return;
+    }
+    process.exitCode = 1;
+    printResult(io, fail('changeset.check', 'CHANGESET_BLOCKED', `${gate.stagedFiles.length} staged .changeset/*.md file(s) — refusing to proceed`, {
+        root: gate.root,
+        state: gate.state,
+        stagedFiles: gate.stagedFiles,
+        snapshotAt: gate.snapshotAt
+    }, [
+        `Drain pending changesets before proceeding: drain `.concat(gate.stagedFiles.join(', '), ' via the coordinating LLM (e.g. `pnpm changeset version` or `peaks changeset publish` if installed).'),
+        'Then re-run `peaks changeset check` to confirm a clean state.'
+    ]), opts.json ?? false);
 }

package/dist/cli/commands/code-gate-command.js

@@ -64,7 +64,12 @@ export function registerCodeGateCommand(program, io) {
                 printResult(io, ok('code.gate', { action: 'allow', tool: parsed.tool, filePath: extractFilePath(parsed.input ?? {}) }, [], []), opts.json);
             }
             else {
-                printResult(io, fail('code.gate', 'PEAKS_CODE_PROHIBITED_DIRECT_EDIT', verdict.message, { action: 'deny', tool: parsed.tool, filePath: verdict.filePath, reason: verdict.reason }, ['use peaks sub-agent dispatch rd']), opts.json);
+                printResult(io, fail('code.gate', 'PEAKS_CODE_PROHIBITED_DIRECT_EDIT', verdict.message, {
+                    action: 'deny',
+                    tool: parsed.tool,
+                    filePath: verdict.filePath,
+                    reason: verdict.reason
+                }, ['use peaks sub-agent dispatch rd']), opts.json);
             }
             return;
         }
@@ -79,7 +84,9 @@ function readStdin() {
     return new Promise((resolveFn, reject) => {
         let buf = '';
         process.stdin.setEncoding('utf8');
-        process.stdin.on('data', (chunk) => { buf += chunk; });
+        process.stdin.on('data', (chunk) => {
+            buf += chunk;
+        });
         process.stdin.on('end', () => resolveFn(buf));
         process.stdin.on('error', (err) => reject(err));
     });

package/dist/cli/commands/code-job-shape-commands-read-job-shape.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Slice rid-024 — `peaks code read-job-shape`.
+ *
+ * Extracted from code-job-shape-commands.ts (C wave 4 near-cap split). Owns:
+ * read-job-shape (read + print). Command name, options, emitted message text,
+ * exit code and the ok/fail payload shape are unchanged from the predecessor's
+ * inline action. The active-session-id read is passed in rather than
+ * duplicated here so the one swallowing `catch` that reads presence stays in
+ * exactly one place (silent-warning census: `catch-return-null`).
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+type ActiveSidReader = (projectRoot: string) => string | null;
+export declare function registerCodeJobShapeReadCommand(code: Command, io: ProgramIO, readActiveSid: ActiveSidReader): void;
+export {};

package/dist/cli/commands/code-job-shape-commands-read-job-shape.js

@@ -0,0 +1,70 @@
+/**
+ * Slice rid-024 — `peaks code read-job-shape`.
+ *
+ * Extracted from code-job-shape-commands.ts (C wave 4 near-cap split). Owns:
+ * read-job-shape (read + print). Command name, options, emitted message text,
+ * exit code and the ok/fail payload shape are unchanged from the predecessor's
+ * inline action. The active-session-id read is passed in rather than
+ * duplicated here so the one swallowing `catch` that reads presence stays in
+ * exactly one place (silent-warning census: `catch-return-null`).
+ */
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { readJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED } from '../../services/code/job-shape-decision.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+export function registerCodeJobShapeReadCommand(code, io, readActiveSid) {
+    // v3.1.1 Step 0.8 — read-only validator. Downstream steps call this
+    // to refuse to proceed if the LLM has not yet recorded a decision.
+    addJsonOption(code
+        .command('read-job-shape')
+        .description('v3.1.1 Step 0.8: return the recorded Job-shape decision. ' +
+        'Returns JOB_SHAPE_NOT_DECIDED when the LLM has not yet recorded a verdict.')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--project <path>', 'target project root (default: findProjectRoot(cwd))')).action((opts) => {
+        runReadJobShape(io, opts, readActiveSid);
+    });
+}
+function runReadJobShape(io, opts, readActiveSid) {
+    try {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = opts.sessionId ?? readActiveSid(projectRoot);
+        if (sessionId === null) {
+            printReadJobShapeNoSession(io, opts);
+            process.exitCode = 1;
+            return;
+        }
+        const record = readJobShapeDecision(projectRoot, sessionId);
+        printReadJobShapeDecision(io, opts, record);
+    }
+    catch (err) {
+        printReadJobShapeError(io, opts, err);
+    }
+}
+function printReadJobShapeNoSession(io, opts) {
+    printResult(io, fail('code.read-job-shape', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-code`', null, ['Re-run with --session-id <sid>']), opts.json);
+}
+function printReadJobShapeDecision(io, opts, record) {
+    printResult(io, ok('code.read-job-shape', {
+        sessionId: record.sessionId,
+        promptHash: record.promptHash,
+        decision: record.decision,
+        schemaVersion: record.schemaVersion
+    }, [], [
+        `Decision on file: isJob=${record.decision.isJob} strategy=${record.decision.suggestedStrategy} confidence=${record.decision.confidence}`
+    ]), opts.json);
+}
+function printReadJobShapeError(io, opts, err) {
+    if (err instanceof JobShapeDecisionError) {
+        printResult(io, fail('code.read-job-shape', err.code, err.message, err.details ?? null, [
+            err.code === JOB_SHAPE_NOT_DECIDED
+                ? 'Run `peaks code detect-job` to record a decision.'
+                : 'Investigate the decision file integrity.'
+        ]), opts.json);
+        process.exitCode = 1;
+        return;
+    }
+    printResult(io, fail('code.read-job-shape', 'READ_JOB_SHAPE_FAILED', getErrorMessage(err), null, [
+        'Verify the project path and try again'
+    ]), opts.json);
+    process.exitCode = 1;
+}

package/dist/cli/commands/code-job-shape-commands.js

@@ -9,9 +9,10 @@ import { join } from 'node:path';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { isUnsafePathInput } from '../../shared/path-safety.js';
 import { fail, ok } from 'peaks-loop-shared/result';
-import { readJobShapeDecision, writeJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED, JOB_SHAPE_ALREADY_DECIDED } from '../../services/code/job-shape-decision.js';
+import { writeJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED, JOB_SHAPE_ALREADY_DECIDED } from '../../services/code/job-shape-decision.js';
 import { findProjectRoot } from '../../services/config/config-safety.js';
 import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
+import { registerCodeJobShapeReadCommand } from './code-job-shape-commands-read-job-shape.js';
 export function registerCodeJobShapeCommands(code, io) {
     // v3.1.1 Step 0.8 — Job-shape decision recorder.
     // The CLI is a *recorder*, not a judge. The LLM supplies the verdict
@@ -20,10 +21,10 @@ export function registerCodeJobShapeCommands(code, io) {
     // server-side, and writes to `.peaks/_runtime/<sessionId>/job-shape.json`.
     addJsonOption(code
         .command('detect-job')
-        .description('v3.1.1 Step 0.8: record the LLM\'s Job-shape judgement. CLI is a recorder, NOT a detector. ' +
+        .description("v3.1.1 Step 0.8: record the LLM's Job-shape judgement. CLI is a recorder, NOT a detector. " +
         'Pass --is-job true|false, --rationale <text>, --suggested-job-id <slug>. ' +
         'Downstream steps call `peaks code read-job-shape` and refuse to proceed if missing.')
-        .requiredOption('--is-job <bool>', 'true | false (the LLM\'s semantic verdict)')
+        .requiredOption('--is-job <bool>', "true | false (the LLM's semantic verdict)")
         .requiredOption('--rationale <text>', '1-3 sentences the LLM writes explaining the call')
         .requiredOption('--suggested-job-id <jid>', 'LLM-chosen stable id, slug-safe (/^[a-z0-9][a-z0-9-]{2,40}$/)')
         .option('--suggested-strategy <single|rotating>', 'single | rotating', 'single')
@@ -43,7 +44,9 @@ export function registerCodeJobShapeCommands(code, io) {
                 process.exitCode = 1;
                 return;
             }
-            if (opts.confidence !== 'high' && opts.confidence !== 'medium' && opts.confidence !== 'low') {
+            if (opts.confidence !== 'high' &&
+                opts.confidence !== 'medium' &&
+                opts.confidence !== 'low') {
                 printResult(io, fail('code.detect-job', 'INVALID_FLAG', `--confidence must be high | medium | low (got "${opts.confidence}")`, { provided: opts.confidence }, ['Pass --confidence high | medium | low']), opts.json);
                 process.exitCode = 1;
                 return;
@@ -76,7 +79,8 @@ export function registerCodeJobShapeCommands(code, io) {
                     try {
                         promptText = readFileSync(lastPromptPath, 'utf8');
                     }
-                    catch { // TODO(g2): legacy silent catch — grace: 1 minor release
+                    catch {
+                        // TODO(g2): legacy silent catch — grace: 1 minor release
                         promptText = '';
                     }
                 }
@@ -101,7 +105,11 @@ export function registerCodeJobShapeCommands(code, io) {
         }
         catch (err) {
             if (err instanceof JobShapeDecisionError) {
-                const code = err.code === JOB_SHAPE_ALREADY_DECIDED ? JOB_SHAPE_ALREADY_DECIDED : err.code === JOB_SHAPE_NOT_DECIDED ? JOB_SHAPE_NOT_DECIDED : err.code;
+                const code = err.code === JOB_SHAPE_ALREADY_DECIDED
+                    ? JOB_SHAPE_ALREADY_DECIDED
+                    : err.code === JOB_SHAPE_NOT_DECIDED
+                        ? JOB_SHAPE_NOT_DECIDED
+                        : err.code;
                 printResult(io, fail('code.detect-job', code, err.message, err.details ?? null, [
                     err.code === JOB_SHAPE_ALREADY_DECIDED
                         ? 'Re-run with --force to overwrite the existing decision.'
@@ -110,50 +118,18 @@ export function registerCodeJobShapeCommands(code, io) {
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, fail('code.detect-job', 'DETECT_JOB_FAILED', getErrorMessage(err), null, ['Verify the flags and try again']), opts.json);
+            printResult(io, fail('code.detect-job', 'DETECT_JOB_FAILED', getErrorMessage(err), null, [
+                'Verify the flags and try again'
+            ]), opts.json);
             process.exitCode = 1;
         }
     });
     // v3.1.1 Step 0.8 — read-only validator. Downstream steps call this
     // to refuse to proceed if the LLM has not yet recorded a decision.
-    addJsonOption(code
-        .command('read-job-shape')
-        .description('v3.1.1 Step 0.8: return the recorded Job-shape decision. ' +
-        'Returns JOB_SHAPE_NOT_DECIDED when the LLM has not yet recorded a verdict.')
-        .option('--session-id <sid>', 'override session id (default: read from active presence)')
-        .option('--project <path>', 'target project root (default: findProjectRoot(cwd))')).action((opts) => {
-        try {
-            const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            const sessionId = opts.sessionId ?? readActiveSidForJobShape(projectRoot);
-            if (sessionId === null) {
-                printResult(io, fail('code.read-job-shape', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-code`', null, ['Re-run with --session-id <sid>']), opts.json);
-                process.exitCode = 1;
-                return;
-            }
-            const record = readJobShapeDecision(projectRoot, sessionId);
-            printResult(io, ok('code.read-job-shape', {
-                sessionId: record.sessionId,
-                promptHash: record.promptHash,
-                decision: record.decision,
-                schemaVersion: record.schemaVersion
-            }, [], [
-                `Decision on file: isJob=${record.decision.isJob} strategy=${record.decision.suggestedStrategy} confidence=${record.decision.confidence}`
-            ]), opts.json);
-        }
-        catch (err) {
-            if (err instanceof JobShapeDecisionError) {
-                printResult(io, fail('code.read-job-shape', err.code, err.message, err.details ?? null, [
-                    err.code === JOB_SHAPE_NOT_DECIDED
-                        ? 'Run `peaks code detect-job` to record a decision.'
-                        : 'Investigate the decision file integrity.'
-                ]), opts.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, fail('code.read-job-shape', 'READ_JOB_SHAPE_FAILED', getErrorMessage(err), null, ['Verify the project path and try again']), opts.json);
-            process.exitCode = 1;
-        }
-    });
+    // The command lives in code-job-shape-commands-read-job-shape.ts (wave 4 near-cap
+    // split); the active-sid reader is passed in so the presence-reading
+    // `catch` is not duplicated into a second silent-swallow site.
+    registerCodeJobShapeReadCommand(code, io, readActiveSidForJobShape);
 }
 // Local helper (was `readActiveSid` in code-commands.ts before rid-024 split).
 // Both detect-job and read-job-shape need to read the active sid from

package/dist/cli/commands/code-mode-gate-commands.d.ts

@@ -3,7 +3,21 @@
  *
  * Extracted from code-commands.ts (rid-024 split).
  * Owns: `plan` (build+print CodePlan), `should-pause` (D5 mode-gate).
+ *
+ * Slice c1-eslint-family-sweep / leaf c4w1-cli-b: the two sub-command
+ * registrations moved VERBATIM to `code-mode-gate-plan-command.ts` and
+ * `code-mode-gate-should-pause-command.ts` so this registration file clears
+ * the 300-line cap and the `max-lines-per-function` / `complexity` findings
+ * that sat on the giant commander action arrow fall with them. The
+ * `readActiveSidForModeGate` helper — which is a near-twin of
+ * `readActiveSidForJobShape` in `code-job-shape-commands.ts` (a DIFFERENT
+ * leaf this wave) — was kept in this exact file so the leaves do not
+ * collide; the should-pause sibling receives it as a callback parameter
+ * instead of importing it. Public surface unchanged: `registerCodeModeGateCommands`
+ * is still importable from `./code-mode-gate-commands.js` and the module
+ * continues to write the same observability events, print the same envelopes,
+ * and preserve the same `process.exitCode = 1` set of exits.
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerCodeModeGateCommands(code: Command, io: ProgramIO): void;

package/dist/cli/commands/code-mode-gate-commands.js

@@ -3,207 +3,27 @@
  *
  * Extracted from code-commands.ts (rid-024 split).
  * Owns: `plan` (build+print CodePlan), `should-pause` (D5 mode-gate).
+ *
+ * Slice c1-eslint-family-sweep / leaf c4w1-cli-b: the two sub-command
+ * registrations moved VERBATIM to `code-mode-gate-plan-command.ts` and
+ * `code-mode-gate-should-pause-command.ts` so this registration file clears
+ * the 300-line cap and the `max-lines-per-function` / `complexity` findings
+ * that sat on the giant commander action arrow fall with them. The
+ * `readActiveSidForModeGate` helper — which is a near-twin of
+ * `readActiveSidForJobShape` in `code-job-shape-commands.ts` (a DIFFERENT
+ * leaf this wave) — was kept in this exact file so the leaves do not
+ * collide; the should-pause sibling receives it as a callback parameter
+ * instead of importing it. Public surface unchanged: `registerCodeModeGateCommands`
+ * is still importable from `./code-mode-gate-commands.js` and the module
+ * continues to write the same observability events, print the same envelopes,
+ * and preserve the same `process.exitCode = 1` set of exits.
  */
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { GATED_STEPS, isHardFloorCategory, isCodeMode, isCommitBoundaryAction, shouldPauseAtGate, formatAutoProceedLogLine } from '../../services/code/mode-gate.js';
-import { checkStalePresence, getSkillPresence } from '../../services/skills/skill-presence-service.js';
-import { findProjectRoot } from '../../services/config/config-safety.js';
-import { emitObservabilityEvent } from '../../services/observability/observability-service.js';
-import { buildCodePlan } from './code-commands.js';
+import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
+import { registerCodeModePlan } from './code-mode-gate-plan-command.js';
+import { registerCodeModeShouldPause } from './code-mode-gate-should-pause-command.js';
 export function registerCodeModeGateCommands(code, io) {
-    code
-        .command('plan')
-        .description('Build and print a CodePlan without executing it')
-        .argument('<change-id>', 'change id to plan against')
-        .option('--fast', 'fast mode: skip memory full-load, standards preflight, and QA repair loop', false)
-        .option('--json', 'emit JSON envelope')
-        .action((sessionId, opts) => {
-        const plan = buildCodePlan({ sessionId, fast: opts.fast === true });
-        if (opts.json === true) {
-            process.stdout.write(JSON.stringify({ ok: true, data: plan }) + '\n');
-        }
-        else {
-            process.stdout.write(`change-id: ${plan.sessionId}\n`);
-            for (const step of plan.steps) {
-                const flag = step.skipped ? 'SKIP' : 'RUN ';
-                const repair = step.id === 'qa-cycle' ? ` repair=${step.repairLoop === true ? 'on' : 'off'}` : '';
-                process.stdout.write(`  [${flag}] ${step.id}${repair}\n`);
-            }
-        }
-    });
-    addJsonOption(code
-        .command('should-pause')
-        .description('v2.11.0 D5: ask the mode-gate whether the LLM should pause for an AskUserQuestion at a given step. ' +
-        'full-auto / 24h auto-proceed (recommended = chosen); assisted / strict pause. ' +
-        'The 3 hard-floor categories always pause regardless of mode. ' +
-        'v2.15.0 slice 002 AC-2: when --step step-1-mode-select AND the recorded skill presence is stale ' +
-        '(outer-session-mismatch / no-presence), the gate returns shouldPause: true with reason "stale-presence" ' +
-        'even if the user passed --mode full-auto. The re-ask is mandatory — sticky-mode from a previous ' +
-        'session is NOT authoritative.')
-        .requiredOption('--step <step>', `one of: ${GATED_STEPS.join(', ')}`)
-        // v2.18.4 slice 002-fix-first-run-step-gates (Bug 2):
-        // `--mode` is now OPTIONAL. Step 1's SEMANTIC is "ask the user
-        // what mode to use" — requiring --mode to ask mode is a
-        // chicken-and-egg. When --mode is omitted, default to
-        // 'full-auto' so the gate can still evaluate; the gate's hard-
-        // pause on `step-1-mode-select` (mode-selection-itself) will
-        // pause regardless, and the LLM-side caller can present
-        // AskUserQuestion without first knowing the mode.
-        .option('--mode <mode>', 'one of: full-auto, assisted, strict, 24h. Defaults to full-auto when omitted (Step 1 chicken-and-egg fix).')
-        .option('--hard-floor <category>', 'optional hard-floor override (irreversible-external-side-effect | authentication-credential | multi-day-investment | commit-boundary-side-effect)')
-        .option('--recommended <option>', 'recommended option label to log when auto-proceeding', 'recommended-option')
-        .option('--project <path>', 'v2.15.0 slice 002 AC-2: project root for presence:check-stale. Default: cwd. Pass only when step=step-1-mode-select.')
-        .option('--ignore-stale-presence', 'v2.15.0 slice 002 AC-2: skip the stale-presence check (test seam). Default false.')
-        .option('--commit-boundary-action <id>', 'v2.15.0 slice 002 AC-4 CLI seam (slice 002 repair): when the LLM is about to run a commit-boundary action (git push / tag / npm publish / global install), pass the action id here to force the hard-floor pause. Valid: git-push | git-tag | npm-publish | npm-install-global | peaks-global-install. Default: omitted (no override).')).action((opts) => {
-        try {
-            // v2.18.4 slice 002-fix-first-run-step-gates (Bug 2):
-            // --mode is optional. Default to 'full-auto' when omitted
-            // so step-1-mode-select can run without forcing the caller
-            // to know the mode up front. The gate's hard-pause on
-            // step-1-mode-select will still pause regardless.
-            const mode = opts.mode ?? 'full-auto';
-            if (!isCodeMode(mode)) {
-                printResult(io, fail('code.should-pause', 'INVALID_MODE', `mode must be one of full-auto, assisted, strict, 24h (got "${mode}")`, { provided: mode }, ['Pass --mode full-auto | assisted | strict | 24h']), opts.json);
-                process.exitCode = 1;
-                return;
-            }
-            if (!GATED_STEPS.includes(opts.step)) {
-                printResult(io, fail('code.should-pause', 'INVALID_STEP', `step must be one of the 14 GATED_STEPS (got "${opts.step}")`, { provided: opts.step, allowed: [...GATED_STEPS] }, ['Pass --step <one of the 14 GATED_STEPS>']), opts.json);
-                process.exitCode = 1;
-                return;
-            }
-            const hardFloor = opts.hardFloor;
-            if (hardFloor !== undefined && !isHardFloorCategory(hardFloor)) {
-                printResult(io, fail('code.should-pause', 'INVALID_HARD_FLOOR', `hard-floor must be one of: irreversible-external-side-effect | authentication-credential | multi-day-investment | commit-boundary-side-effect (got "${hardFloor}")`, { provided: hardFloor }, ['Omit --hard-floor or pass a valid category']), opts.json);
-                process.exitCode = 1;
-                return;
-            }
-            // v2.15.0 slice 002 repair (QA blocker): validate the
-            // --commit-boundary-action flag at the CLI boundary. The
-            // service-layer `shouldPauseAtGate` accepts a boolean
-            // `commitBoundaryAction: true`; this flag tells the CLI to
-            // pass it through. An unknown action id is rejected here
-            // (not silently ignored) so typos fail loud.
-            const commitBoundaryActionId = opts.commitBoundaryAction;
-            if (commitBoundaryActionId !== undefined && !isCommitBoundaryAction(commitBoundaryActionId)) {
-                printResult(io, fail('code.should-pause', 'INVALID_COMMIT_BOUNDARY_ACTION', `--commit-boundary-action must be one of: git-push | git-tag | npm-publish | npm-install-global | peaks-global-install (got "${commitBoundaryActionId}")`, { provided: commitBoundaryActionId }, ['Omit --commit-boundary-action or pass a valid action id']), opts.json);
-                process.exitCode = 1;
-                return;
-            }
-            const step = opts.step;
-            // Slice 002 (v2.15.0) AC-2: when the caller is asking about
-            // Step 1 AND the recorded presence is stale, OVERRIDE the
-            // gate decision to PAUSE with reason='stale-presence'. The
-            // hard-pause on step-1-mode-select (defect #1 fix from
-            // 2026-06-28-code-mode-bypass-fix) is already in effect, so
-            // this only adds the structured `stale` reason + an
-            // envelope-level `stalePresence` field so downstream tooling
-            // (statusline, sub-agent dispatch) can act on it.
-            let stalePresence = null;
-            if (opts.step === 'step-1-mode-select' && opts.ignoreStalePresence !== true) {
-                const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-                stalePresence = checkStalePresence({ projectRootOverride: projectRoot });
-            }
-            if (stalePresence !== null && stalePresence.stale) {
-                // Build the envelope manually so we can attach the extra
-                // structured fields (stalePresence, logLine) and emit a
-                // dedicated observability event tagged with reason='stale-presence'.
-                const sid = readActiveSidForModeGate(opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd()) ?? '';
-                if (sid.length > 0) {
-                    emitObservabilityEvent({
-                        schemaVersion: 1,
-                        ts: new Date().toISOString(),
-                        sessionId: sid,
-                        category: 'mode-gate',
-                        detail: {
-                            mode: mode,
-                            step,
-                            shouldPause: true,
-                            reason: 'stale-presence',
-                            staleReason: stalePresence.reason,
-                            recordedOuterSessionId: stalePresence.recordedOuterSessionId,
-                            currentOuterSessionId: stalePresence.currentOuterSessionId
-                        }
-                    }, { projectRoot: opts.project ?? process.cwd() });
-                }
-                printResult(io, ok('code.should-pause', {
-                    shouldPause: true,
-                    reason: `stale-presence — re-ask Step 1 (${stalePresence.reason}; recorded outer session id does not match current)`,
-                    gateKind: 'mode-selection-itself',
-                    logLine: `auto-pause (${mode}, stale-presence:${stalePresence.reason}): ${step} → re-ask`,
-                    stalePresence: {
-                        stale: true,
-                        reason: stalePresence.reason,
-                        recordedOuterSessionId: stalePresence.recordedOuterSessionId,
-                        currentOuterSessionId: stalePresence.currentOuterSessionId
-                    }
-                }, [], [
-                    `Recorded outer session id "${stalePresence.recordedOuterSessionId ?? '?'}" does not match current outer session id "${stalePresence.currentOuterSessionId ?? '?'}".`,
-                    `peaks-code Step 1 must AskUserQuestion to confirm the mode for THIS session (slice 002 AC-2).`
-                ]), opts.json);
-                return;
-            }
-            const decision = shouldPauseAtGate({
-                mode: mode,
-                step,
-                hardFloorCategory: hardFloor,
-                // v2.15.0 slice 002 repair (QA blocker): translate the CLI
-                // --commit-boundary-action flag into the service-layer
-                // boolean. The CLI accepts the action id (e.g. "git-push")
-                // for ergonomic machine consumption; the service layer only
-                // cares that *some* commit-boundary action triggered the
-                // override. The actual action id is echoed in the JSON
-                // envelope below.
-                commitBoundaryAction: commitBoundaryActionId !== undefined
-            });
-            // Slice C of v2.11.1 — observability hook #4/7. Fire-and-forget
-            // per PRD Q4 (full-auto must never fail-loud). projectRoot
-            // resolution mirrors observability-commands.ts (findProjectRoot
-            // → cwd fallback).
-            const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
-            const sid = readActiveSidForModeGate(projectRoot) ?? '';
-            if (sid.length > 0) {
-                emitObservabilityEvent({
-                    schemaVersion: 1,
-                    ts: new Date().toISOString(),
-                    sessionId: sid,
-                    category: 'mode-gate',
-                    detail: {
-                        mode: mode,
-                        step,
-                        shouldPause: decision.shouldPause,
-                        reason: decision.reason,
-                        ...(decision.hardFloorCategory !== undefined ? { hardFloorCategory: decision.hardFloorCategory } : {})
-                    }
-                }, { projectRoot });
-            }
-            const logLine = formatAutoProceedLogLine({
-                mode: mode,
-                step,
-                recommendedOption: opts.recommended ?? 'recommended-option',
-                hardFloorCategory: hardFloor
-            });
-            printResult(io, 
-            // v2.15.0 slice 002 repair: include the commit-boundary
-            // action id in the envelope (when provided) so the LLM-side
-            // caller can echo which boundary was checked. Null when no
-            // --commit-boundary-action flag was passed.
-            ok('code.should-pause', {
-                ...decision,
-                logLine,
-                ...(commitBoundaryActionId !== undefined ? { commitBoundaryAction: commitBoundaryActionId } : {})
-            }, [], [
-                decision.shouldPause
-                    ? `Mode ${mode} + step ${opts.step} → PAUSE for AskUserQuestion${commitBoundaryActionId !== undefined ? ` (commit-boundary: ${commitBoundaryActionId})` : ''}`
-                    : `Mode ${mode} + step ${opts.step} → AUTO-PROCEED with recommended option`
-            ]), opts.json);
-        }
-        catch (err) {
-            printResult(io, fail('code.should-pause', 'SHOULD_PAUSE_FAILED', getErrorMessage(err), null, ['Re-run with --json for envelope shape']), opts.json);
-            process.exitCode = 1;
-        }
-    });
+    registerCodeModePlan(code);
+    registerCodeModeShouldPause(code, io, readActiveSidForModeGate);
 }
 // Local helper (was `readActiveSid` in code-commands.ts before rid-024 split).
 // The mode-gate stale-presence check needs the active sid for the