peaks-loop 4.0.0-beta → 4.0.0-beta.10

package/dist/cli/commands/session-auto-compact-hook-command.js

@@ -0,0 +1,127 @@
+/**
+ * `peaks session auto-compact-hook` — slice 2026-07-02-auto-compact-zero-pause.
+ *
+ * The Bash entrypoint the PreToolUse hook fires on every Bash/Task
+ * tool call from the Claude Code runner. Behaviour:
+ *
+ *   1. Read `CLAUDE_CONTEXT_USAGE_PERCENT` (or any adapter-declared
+ *      env-var via the registry — claude-code MVP). If ratio is below
+ *      the red-line threshold (0.95), exit 0 silent — the runner's
+ *      normal flow continues.
+ *   2. If ratio is ≥ 0.95 (red line), write a one-line stderr hint
+ *      so the human sees what happened, then in-band spawn
+ *      `claude --compact` so the **current** runner's context
+ *      window collapses (not a new claude process).
+ *   3. Always exit 0. The hook is a probe, not a gate — the gate is
+ *      `claude --compact` itself returning 0.
+ *
+ * Idempotency: re-running the hook is safe; if `claude --compact`
+ * is already in flight, the new process just exits 0 immediately
+ * (Claude Code's compact is a one-shot operation against the
+ * current runner).
+ *
+ * Why a CLI subcommand instead of an inline JS hook:
+ *   - Keeps the hook payload in `.claude/settings.local.json` small
+ *     (one line: `peaks session auto-compact-hook`).
+ *   - Lets the heavy lifting (ratio parsing, IDE-aware env-var
+ *     resolution, spawning `claude --compact`) live in TypeScript
+ *     where it's unit-testable.
+ *   - Discoverable via `peaks session --help` — future LLM sessions
+ *     see the primitive exists.
+ *
+ * Karpathy §2: 50 lines, no abstractions, no speculative error
+ * handling. The hook command is a single-purpose muscle; if it
+ * grows beyond ~80 lines, that's a signal to split.
+ */
+import { spawn } from 'node:child_process';
+import { detectIdeFromEnv } from '../../services/context/main-session-monitor.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+/**
+ * Red-line ratio threshold. Must match the orchestrator's
+ * AUTO_COMPACT_RED_LINE_RATIO constant (0.95). Kept here as a
+ * literal so the hook command stays self-contained — a future
+ * slice may move this to a shared constant module if the value
+ * starts drifting.
+ */
+const RED_LINE_RATIO = 0.95;
+/**
+ * Parse `CLAUDE_CONTEXT_USAGE_PERCENT` (or the adapter-declared
+ * env-var) into a ratio in [0, 1]. Returns null on missing /
+ * malformed input. Mirrors `readEnvPercent` in
+ * `auto-compact-reader.ts` so the hook command and the
+ * orchestrator agree on parsing semantics.
+ */
+function readRatioFromEnv(env) {
+    const detected = detectIdeFromEnv(env);
+    const ideId = (detected === 'unknown' ? 'claude-code' : detected);
+    const adapter = getAdapter(ideId);
+    if (!adapter.compact)
+        return null;
+    const varName = adapter.compact.envVarForContextPercent;
+    const raw = env[varName];
+    if (typeof raw !== 'string' || raw.length === 0)
+        return null;
+    const parsed = Number.parseFloat(raw);
+    if (!Number.isFinite(parsed))
+        return null;
+    // Allow either "0..1" or "0..100" encoding. Claude Code writes
+    // "0..1" today; statusline tools sometimes write "0..100". Normalize.
+    const ratio = parsed > 1.5 ? parsed / 100 : Math.max(0, Math.min(1, parsed));
+    return { ratio, varName };
+}
+export function registerSessionAutoCompactHookCommand(session) {
+    session
+        .command('auto-compact-hook')
+        .description('PreToolUse hook entrypoint — read CLAUDE_CONTEXT_USAGE_PERCENT and, ' +
+        'at ratio ≥ 0.95, in-band spawn `claude --compact` against the current ' +
+        'runner. Designed for invocation from `.claude/settings.local.json` ' +
+        'PreToolUse hooks; safe to re-run.')
+        .action(() => {
+        const probe = readRatioFromEnv(process.env);
+        if (probe === null) {
+            // No signal → exit 0 silent. The hook must never block the
+            // runner's normal flow on a missing env-var.
+            return;
+        }
+        if (probe.ratio < RED_LINE_RATIO) {
+            // Below red line → exit 0 silent. The orchestrator's
+            // pre-compact zone (0.85–0.95) is handled out-of-band by
+            // the LLM firing `peaks code auto-compact --execute`; the
+            // hook only fires on the synchronous red-line path.
+            return;
+        }
+        // Red line reached — compact the current runner in-band.
+        // The `detached: true` + `unref()` pair lets the hook return
+        // immediately while Claude Code's own slash-command processor
+        // picks up `claude --compact` against the runner's session.
+        // This is the fix for the shell-exec-spawns-a-child-process
+        // bug documented in `.peaks/memory/2026-06-27-auto-compact-design.md:139-152`.
+        //
+        // Dogfood 2026-07-02 fix: when `claude` is not on PATH (the
+        // user runs Claude Code as an MCP rather than via the CLI
+        // binary), `spawn` raises ENOENT. Catching this MUST NOT crash
+        // the runner's tool call — the hook must exit 0 silently with
+        // a one-line stderr hint so the runner keeps working. The user
+        // can then run `/compact` manually (or `peaks code auto-compact`
+        // from another terminal).
+        try {
+            const child = spawn('claude', ['--compact'], {
+                stdio: 'ignore',
+                detached: true,
+                env: process.env
+            });
+            child.on('error', () => {
+                // Spawn failed (ENOENT or EPERM). Exit 0 silently with a
+                // stderr hint — the hook contract is "never crash the
+                // runner's tool call".
+                process.stderr.write('[peaks:auto-compact-hook] claude CLI not on PATH; cannot fire in-band. Run `/compact` manually or set up the Claude Code CLI binary.\n');
+            });
+            child.unref();
+            process.stderr.write(`[peaks:auto-compact-hook] ratio=${(probe.ratio * 100).toFixed(1)}% ≥ ${(RED_LINE_RATIO * 100).toFixed(0)}%; firing claude --compact in-band\n`);
+        }
+        catch {
+            // Defensive: `spawn` can throw synchronously on some platforms.
+            process.stderr.write('[peaks:auto-compact-hook] failed to spawn claude --compact; run `/compact` manually.\n');
+        }
+    });
+}

package/dist/cli/commands/skill-loop-engineering-readiness-commands.d.ts

@@ -0,0 +1,67 @@
+/**
+ * `peaks skill lint --category loop-engineering-readiness` — M6 / spec §7.5 + §8.4
+ *
+ * Loop Engineering readiness gate for any new peaks-* skill that
+ * participates in Loop Engineering (crystallization or evolution).
+ *
+ * Usage:
+ *   peaks skill lint --category loop-engineering-readiness --path <skill-dir>
+ *   peaks skill lint --category loop-engineering-readiness --path <skill-dir> --json
+ *
+ * The command:
+ *   1. Resolves <skill-dir>/SKILL.md (default if the path is a file).
+ *   2. Calls lintSkillLoopEngineeringReadiness() with the file contents.
+ *   3. Prints a structured JSON envelope via printResult (or a
+ *      human-readable summary when --json is omitted).
+ *   4. Sets process.exitCode = 1 on a non-ok result, so the LLM
+ *      gate can short-circuit a future peaks-* skill that fails the
+ *      lint.
+ *
+ * The lint asserts three structural properties:
+ *   1. the SKILL.md references
+ *      `.peaks/standards/loop-engineering-guidelines.md`;
+ *   2. the SKILL.md does not introduce a CLI verb the user is meant
+ *      to type (only LLM-coordinated verbs from the sediment /
+ *      asset / evolution surface are allowed; RL-1);
+ *   3. the SKILL.md does not introduce a JSON / manifest
+ *      hand-authoring surface (RL-1).
+ *
+ * The user never types `peaks skill lint …` — the LLM runs it on
+ * the user's behalf. This command is also reachable as
+ * `peaks skill ready --category loop-engineering-readiness
+ *   --path <skill-dir>`
+ * via a small alias added at the bottom of this file.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare const LOOP_ENGINEERING_READINESS_CATEGORY = "loop-engineering-readiness";
+/**
+ * Resolve the SKILL.md file path from a `--path <skill-dir>` value.
+ *
+ * Accepts either:
+ *   - a directory containing a SKILL.md (the common case for a
+ *     peaks-* skill: `src/skills/<id>/`, `skills/<id>/`, etc.);
+ *   - a direct file path to a SKILL.md.
+ *
+ * Returns the absolute path to the SKILL.md, or null if no SKILL.md
+ * is found.
+ */
+export declare function resolveSkillMdPath(rawPath: string): string | null;
+/**
+ * Pure helper: run the readiness lint against the SKILL.md text and
+ * return a CLI-shaped envelope. Kept separate from the Commander
+ * action so unit + integration tests can drive it without spawning
+ * a child process.
+ */
+export declare function runReadinessLint(rawPath: string): {
+    ok: boolean;
+    code: string;
+    message: string;
+    data: {
+        path: string;
+        category: string;
+        findings: string[];
+    };
+    nextActions: string[];
+};
+export declare function registerSkillLoopEngineeringReadinessCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/skill-loop-engineering-readiness-commands.js

@@ -0,0 +1,173 @@
+/**
+ * `peaks skill lint --category loop-engineering-readiness` — M6 / spec §7.5 + §8.4
+ *
+ * Loop Engineering readiness gate for any new peaks-* skill that
+ * participates in Loop Engineering (crystallization or evolution).
+ *
+ * Usage:
+ *   peaks skill lint --category loop-engineering-readiness --path <skill-dir>
+ *   peaks skill lint --category loop-engineering-readiness --path <skill-dir> --json
+ *
+ * The command:
+ *   1. Resolves <skill-dir>/SKILL.md (default if the path is a file).
+ *   2. Calls lintSkillLoopEngineeringReadiness() with the file contents.
+ *   3. Prints a structured JSON envelope via printResult (or a
+ *      human-readable summary when --json is omitted).
+ *   4. Sets process.exitCode = 1 on a non-ok result, so the LLM
+ *      gate can short-circuit a future peaks-* skill that fails the
+ *      lint.
+ *
+ * The lint asserts three structural properties:
+ *   1. the SKILL.md references
+ *      `.peaks/standards/loop-engineering-guidelines.md`;
+ *   2. the SKILL.md does not introduce a CLI verb the user is meant
+ *      to type (only LLM-coordinated verbs from the sediment /
+ *      asset / evolution surface are allowed; RL-1);
+ *   3. the SKILL.md does not introduce a JSON / manifest
+ *      hand-authoring surface (RL-1).
+ *
+ * The user never types `peaks skill lint …` — the LLM runs it on
+ * the user's behalf. This command is also reachable as
+ * `peaks skill ready --category loop-engineering-readiness
+ *   --path <skill-dir>`
+ * via a small alias added at the bottom of this file.
+ */
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { lintSkillLoopEngineeringReadiness, } from '../../services/standards/loop-engineering-readiness-lint.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export const LOOP_ENGINEERING_READINESS_CATEGORY = 'loop-engineering-readiness';
+/**
+ * Resolve the SKILL.md file path from a `--path <skill-dir>` value.
+ *
+ * Accepts either:
+ *   - a directory containing a SKILL.md (the common case for a
+ *     peaks-* skill: `src/skills/<id>/`, `skills/<id>/`, etc.);
+ *   - a direct file path to a SKILL.md.
+ *
+ * Returns the absolute path to the SKILL.md, or null if no SKILL.md
+ * is found.
+ */
+export function resolveSkillMdPath(rawPath) {
+    const abs = resolve(rawPath);
+    if (!existsSync(abs))
+        return null;
+    const st = statSync(abs);
+    if (st.isFile()) {
+        return abs.toLowerCase().endsWith('skill.md') ? abs : null;
+    }
+    if (st.isDirectory()) {
+        const candidate = join(abs, 'SKILL.md');
+        return existsSync(candidate) ? candidate : null;
+    }
+    return null;
+}
+/**
+ * Pure helper: run the readiness lint against the SKILL.md text and
+ * return a CLI-shaped envelope. Kept separate from the Commander
+ * action so unit + integration tests can drive it without spawning
+ * a child process.
+ */
+export function runReadinessLint(rawPath) {
+    const skillMdPath = resolveSkillMdPath(rawPath);
+    if (!skillMdPath) {
+        return {
+            ok: false,
+            code: 'SKILL_FILE_NOT_FOUND',
+            message: `could not resolve SKILL.md from --path ${rawPath}`,
+            data: { path: rawPath, category: LOOP_ENGINEERING_READINESS_CATEGORY, findings: [] },
+            nextActions: [
+                'Pass a directory containing SKILL.md or a direct path to a SKILL.md file.',
+            ],
+        };
+    }
+    const text = readFileSync(skillMdPath, 'utf-8');
+    const result = lintSkillLoopEngineeringReadiness(text);
+    if (result.ok) {
+        return {
+            ok: true,
+            code: 'SKILL_READINESS_OK',
+            message: 'SKILL.md passes the Loop Engineering readiness lint',
+            data: {
+                path: skillMdPath,
+                category: LOOP_ENGINEERING_READINESS_CATEGORY,
+                findings: [],
+            },
+            nextActions: [
+                'The skill is allowed to participate in Loop Engineering (crystallization / evolution).',
+            ],
+        };
+    }
+    return {
+        ok: false,
+        code: 'SKILL_READINESS_FAILED',
+        message: `SKILL.md failed the Loop Engineering readiness lint (${result.findings.length} finding(s))`,
+        data: {
+            path: skillMdPath,
+            category: LOOP_ENGINEERING_READINESS_CATEGORY,
+            findings: result.findings,
+        },
+        nextActions: [
+            'Address every finding listed in data.findings, then re-run the lint.',
+            'See src/services/standards/loop-engineering-readiness-lint.ts for the rule definitions.',
+            'See .peaks/standards/loop-engineering-guidelines.md for the red lines the lint enforces.',
+        ],
+    };
+}
+function lintAction(options, io) {
+    if (options.category !== LOOP_ENGINEERING_READINESS_CATEGORY) {
+        printResult(io, fail('skill.lint', 'UNKNOWN_LINT_CATEGORY', `only --category ${LOOP_ENGINEERING_READINESS_CATEGORY} is implemented in M6`, { category: options.category ?? null }, [
+            `Pass --category ${LOOP_ENGINEERING_READINESS_CATEGORY}.`,
+        ]), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    if (!options.path) {
+        printResult(io, fail('skill.lint', 'MISSING_PATH', '--path <skill-dir> is required', { category: options.category }, ['Pass --path pointing at a peaks-* skill directory containing SKILL.md.']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const envelope = runReadinessLint(options.path);
+        if (envelope.ok) {
+            printResult(io, ok('skill.lint', envelope.data, [], envelope.nextActions), options.json);
+            return;
+        }
+        printResult(io, fail('skill.lint', envelope.code, envelope.message, envelope.data, envelope.nextActions), options.json);
+        process.exitCode = 1;
+    }
+    catch (error) {
+        printResult(io, fail('skill.lint', 'SKILL_READINESS_ERROR', getErrorMessage(error), { path: options.path }, ['Verify the path is readable.']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerSkillLoopEngineeringReadinessCommands(program, io) {
+    // `peaks skill lint --category loop-engineering-readiness --path <skill-dir>`
+    // — primary surface, named to match the spec §7.5 / §8.4 wording.
+    // We reuse the existing `skill` parent if one is registered; per
+    // the add-a-new-subcommand-check-for-existing-top-level-first rule,
+    // we never re-create `skill` when it's already there.
+    const existingSkill = program.commands.find((c) => c.name() === 'skill');
+    const skill = existingSkill ?? program
+        .command('skill')
+        .description('skill operations (M6: lint --category loop-engineering-readiness)');
+    addJsonOption(skill
+        .command('lint')
+        .description(`M6: lint a peaks-* SKILL.md against a category. Currently supports --category ${LOOP_ENGINEERING_READINESS_CATEGORY} (spec §7.5 / §8.4 / RL-8).`)
+        .option('--category <name>', `lint category; the M6 implementation only supports ${LOOP_ENGINEERING_READINESS_CATEGORY}`, LOOP_ENGINEERING_READINESS_CATEGORY)
+        .requiredOption('--path <skill-dir>', 'path to a peaks-* skill directory (containing SKILL.md) or directly to a SKILL.md file')).action((options) => lintAction(options, io));
+    // `peaks skill ready --category loop-engineering-readiness --path <skill-dir>`
+    // — alias verb chosen by M6 for human-facing callouts. It points at
+    // the same handler; both verbs are first-class so users (LLM
+    // proxies) can pick whichever phrasing fits the conversation.
+    // Per the spec, the user never types either verb; the LLM runs the
+    // CLI on the user's behalf.
+    skill
+        .command('ready')
+        .description(`M6 alias for \`peaks skill lint --category ${LOOP_ENGINEERING_READINESS_CATEGORY}\`; same flags, same exit codes.`)
+        .option('--category <name>', `lint category; the M6 implementation only supports ${LOOP_ENGINEERING_READINESS_CATEGORY}`, LOOP_ENGINEERING_READINESS_CATEGORY)
+        .requiredOption('--path <skill-dir>', 'path to a peaks-* skill directory or SKILL.md file')
+        .option('--json', 'print machine-readable JSON envelope')
+        .action((options) => lintAction(options, io));
+}

package/dist/cli/commands/skill-search-commands.d.ts

@@ -0,0 +1,25 @@
+/**
+ * peaks skill search — CLI primitive for S0 of the 4.0.0-beta.5
+ * peaks-solo dispatcher release.
+ *
+ * Spec: docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2
+ * Plan: docs/superpowers/plans/2026-07-08-peaks-solo-dispatcher/s0-skill-search-cli.md
+ *
+ * Wired into the existing `peaks skill` group by
+ * `src/cli/commands/core/skill-command.ts` (one import + one call).
+ * The command ALWAYS emits a JSON array on stdout, even on the
+ * no-match case (which exits 0 with `[]` per plan §"Match rules (v1)").
+ *
+ * Exit codes (locked in plan §"API Contract"):
+ *   0 — success (may be empty array)
+ *   1 — invalid args (Zod validation failure)
+ *   2 — unexpected error (skill pool read fail, etc.)
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+/**
+ * Validate the raw CLI flags, call the service, and emit a JSON
+ * envelope on stdout. Errors flow through stderr + non-zero exit
+ * codes per the plan §"API Contract" table.
+ */
+export declare function registerSkillSearchCommand(program: Command, io: ProgramIO): void;

package/dist/cli/commands/skill-search-commands.js

@@ -0,0 +1,68 @@
+import { searchSkills, SkillSearchInputSchema } from '../../services/skill/skill-search-service.js';
+import { getErrorMessage } from '../../shared/result.js';
+/**
+ * Validate the raw CLI flags, call the service, and emit a JSON
+ * envelope on stdout. Errors flow through stderr + non-zero exit
+ * codes per the plan §"API Contract" table.
+ */
+export function registerSkillSearchCommand(program, io) {
+    // The parent `skill` command is created by registerSkillCommand in
+    // core/skill-command.ts. To keep the wiring self-contained we
+    // resolve the parent by name; this also lets tests register the
+    // subcommand in isolation.
+    const skill = program.commands.find((c) => c.name() === 'skill');
+    if (skill === undefined) {
+        // Defensive: the parent must be registered before us. Surface the
+        // error visibly — the dispatcher cannot triage without `peaks skill`
+        // existing, so the LLM-side caller needs to know.
+        throw new Error('peaks skill search: parent `skill` command not found. ' +
+            'Ensure registerSkillCommand is called before registerSkillSearchCommand.');
+    }
+    skill
+        .command('search')
+        .description('Search the in-tree skill pool by --query (substring on description + triggers) ' +
+        'and/or --tag (exact match on metadata.tags) and/or --domain (exact match). ' +
+        'Outputs a JSON array (always, even on no-match) to stdout. ' +
+        'See docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2.')
+        .option('-q, --query <text>', 'case-insensitive substring matched against skill description + triggers')
+        .option('-t, --tag <tag>', 'exact match on metadata.tags (e.g. "orchestrator", "loop-engineering")')
+        .option('-d, --domain <domain>', 'exact match on metadata.domain (locked enum: code | content | doctor | research | triage | sop | audit | final-review | resume | status | test | ide | slice-decompose | issue-fix-orchestrator | perf-audit | security-audit | reviewer)')
+        .option('-l, --limit <n>', 'max results returned (1..100, default 20)', (v) => Number.parseInt(v, 10))
+        .action(async (options) => {
+        // 1) Coerce + validate input via the service's Zod schema.
+        //    The schema's refine rejects empty input — that is the
+        //    "all-empty → error" contract the spec mandates.
+        const raw = {};
+        if (options.query !== undefined)
+            raw['query'] = options.query;
+        if (options.tag !== undefined)
+            raw['tag'] = options.tag;
+        if (options.domain !== undefined)
+            raw['domain'] = options.domain;
+        if (options.limit !== undefined)
+            raw['limit'] = options.limit;
+        const parsed = SkillSearchInputSchema.safeParse(raw);
+        if (!parsed.success) {
+            // Exit code 1 = invalid args. Emit a human-readable message
+            // on stderr so the LLM-side caller can act on it; do NOT
+            // pollute stdout (which downstream tools parse as JSON).
+            for (const issue of parsed.error.issues) {
+                io.stderr(`${issue.path.join('.') || '<root>'}: ${issue.message}`);
+            }
+            process.exitCode = 1;
+            return;
+        }
+        // 2) Call the service. Any unexpected error (skill pool read
+        //    fail, etc.) maps to exit code 2.
+        try {
+            const results = await searchSkills(parsed.data);
+            // Always emit a JSON array on stdout. The plan locks this
+            // contract: even no-match returns `[]`, never `null`.
+            io.stdout(JSON.stringify(results));
+        }
+        catch (error) {
+            io.stderr(`skill.search failed: ${getErrorMessage(error)}`);
+            process.exitCode = 2;
+        }
+    });
+}

package/dist/cli/commands/sub-agent-shared.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Shared types, constants, and helpers for the `peaks sub-agent` command group.
+ *
+ * Slice 2026-06-23-audit-p0-split — pulled out of `sub-agent-commands.ts` (968
+ * lines) to honor the 800-line file cap (Karpathy #2 Simplicity First).
+ *
+ * Public exports:
+ *   - `validateRole(role)` — exported because `sub-agent-commands.test.ts`
+ *     and the integration suite rely on it as the source of truth for
+ *     role-string validation.
+ *
+ * Everything else is internal to the `peaks sub-agent` group.
+ */
+import type { SubAgentBatchResult } from '../../services/dispatch/sub-agent-dispatcher.js';
+import type { HeadroomMode } from '../../services/context/headroom-client.js';
+import type { HeartbeatStatus } from '../../services/dispatch/dispatch-record-writer.js';
+export declare const RECOMMENDED_ROLES = "rd | qa | ui | txt | qa-business | qa-perf | qa-security | qa-business-<*> | general-purpose";
+export declare const HEARTBEAT_STATUSES: readonly HeartbeatStatus[];
+export declare const HEADROOM_MODES: readonly HeadroomMode[];
+export declare const PROMPT_LIMIT_BYTES: number;
+export type DispatchOptions = {
+    prompt?: string;
+    promptLength?: string;
+    requestId?: string;
+    sessionId?: string;
+    project?: string;
+    batchId?: string;
+    writeArtifact?: string;
+    useHeadroom?: boolean;
+    headroomMode?: string;
+    force?: boolean;
+    fromDag?: string;
+    json?: boolean;
+};
+export type HeartbeatOptions = {
+    record?: string;
+    status?: string;
+    progress?: string;
+    note?: string;
+    project?: string;
+    json?: boolean;
+};
+export type ShareOptions = {
+    batch?: string;
+    key?: string;
+    value?: string;
+    from?: string;
+    requestId?: string;
+    sessionId?: string;
+    project?: string;
+    json?: boolean;
+};
+export type SharedReadOptions = {
+    batch?: string;
+    since?: string;
+    key?: string;
+    requestId?: string;
+    sessionId?: string;
+    project?: string;
+    json?: boolean;
+};
+export type AwaitOptions = {
+    batch?: string;
+    timeout?: string;
+    project?: string;
+    sessionId?: string;
+    json?: boolean;
+};
+/**
+ * Lazy-loaded module types — only resolved inside `runDispatchFromDag`
+ * to keep the warm-path dispatch CLI cold-start fast (slice 9).
+ */
+export type SliceDagModule = typeof import('../../services/dispatch/slice-dag.js');
+export type DagOrchestratorModule = typeof import('../../services/code/dag-orchestrator.js');
+export type ContractStoreModule = typeof import('../../services/dispatch/contract-store.js');
+/**
+ * Validate a role string. Returns `null` when valid, otherwise the
+ * rejection reason (mirrors commander.js option-validation shape so
+ * the action handler can pass it straight to `fail()`).
+ *
+ * Rules (per dispatch CLI spec):
+ *   - Non-empty
+ *   - ≤ 256 chars
+ *   - No whitespace, no control characters, no DEL (0x7F)
+ */
+export declare function validateRole(role: string): string | null;
+/**
+ * Roll up a batch result array into the summary the CLI envelope exposes
+ * for `peaks sub-agent await`. Counts per status; the orchestrator
+ * surface (`SubAgentBatchResult.status`) is a closed set so a single
+ * `for` loop with `if/else if` is faster and clearer than a reduce.
+ */
+export declare function summarizeBatchResults(results: readonly SubAgentBatchResult[]): {
+    readonly total: number;
+    readonly done: number;
+    readonly failed: number;
+    readonly cancelled: number;
+    readonly timeout: number;
+};

package/dist/cli/commands/user-touchpoint-commands.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerUserTouchpointCommands(program: Command, io: ProgramIO): void;

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 '../../shared/result.js';
+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);
+    });
+}