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

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

@@ -0,0 +1,215 @@
+import { mkdirSync } from 'node:fs';
+import { initSop, lintSop } from '../../services/sop/sop-service.js';
+import { registerSop, readRegistry, SopRegisterError } from '../../services/sop/sop-registry-service.js';
+import { checkGate, SopCheckError } from '../../services/sop/sop-check-service.js';
+import { advanceSop, SopAdvanceError, SopGateBlockedError, SopPhaseSkipError } from '../../services/sop/sop-advance-service.js';
+import { sopStateDir } from '../../services/sop/sop-paths.js';
+import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
+import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerSopCommands(program, io) {
+    const sop = program.command('sop').description('Author and validate user-defined SOP skills');
+    addJsonOption(sop
+        .command('init')
+        .description('Scaffold a user-authored SOP (manifest + SKILL.md); global by default, --project commits it into a repo')
+        .requiredOption('--id <sop-id>', 'SOP id (lowercase kebab, e.g. team-release)')
+        .option('--name <name>', 'human-readable SOP name (defaults to the id)')
+        .option('--apply', 'write the SOP files (default: preview only)')
+        .option('--project <path>', 'scaffold into the repo (<path>/.peaks/sops, committed & team-shared) instead of global')).action(async (options) => {
+        try {
+            const initOptions = { id: options.id };
+            if (options.name !== undefined) {
+                initOptions.name = options.name;
+            }
+            if (options.apply === true) {
+                initOptions.apply = true;
+            }
+            if (options.project !== undefined) {
+                initOptions.projectRoot = options.project;
+            }
+            const result = await initSop(initOptions);
+            // Side-effecting scaffold returns explicit next steps so the user doesn't
+            // have to recall the runbook: applied → edit then lint; preview → apply.
+            const nextActions = result.applied
+                ? [
+                    `Edit ${result.manifestPath} to define your real phases and gates`,
+                    `peaks sop lint --id ${result.id} --json`
+                ]
+                : [`Re-run with --apply to write ${result.manifestPath}`];
+            printResult(io, ok('sop.init', result, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('sop.init', 'SOP_INIT_FAILED', getErrorMessage(error), { id: options.id }, ['Check the SOP id before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('lint')
+        .description('Validate a SOP manifest (id namespace, phases, gate ids, check fields)')
+        .requiredOption('--id <sop-id>', 'SOP id to lint')
+        .option('--allow-commands', 'permit command-type gates (they run shell-less processes)')
+        .option('--project <path>', 'lint the project-layer SOP (<path>/.peaks/sops) instead of global')).action(async (options) => {
+        try {
+            const lintOptions = { id: options.id };
+            if (options.allowCommands === true) {
+                lintOptions.allowCommands = true;
+            }
+            if (options.project !== undefined) {
+                lintOptions.projectRoot = options.project;
+            }
+            const result = await lintSop(lintOptions);
+            if (result === null) {
+                printResult(io, fail('sop.lint', 'SOP_NOT_FOUND', `No SOP found for id "${options.id}"`, { id: options.id }, ['Run peaks sop init --id <sop-id> --apply first']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, result.ok
+                ? ok('sop.lint', result)
+                : fail('sop.lint', 'SOP_LINT_FAILED', `${result.findings.filter((f) => f.severity === 'error').length} lint error(s) in SOP "${options.id}"`, result, ['Fix the reported findings, then re-run peaks sop lint']), options.json);
+            if (!result.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('sop.lint', 'SOP_LINT_ERROR', getErrorMessage(error), { id: options.id }, ['Check the SOP id before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('register')
+        .description('Validate a SOP and record its gates in the gate registry (global, or --project for the repo)')
+        .requiredOption('--id <sop-id>', 'SOP id to register')
+        .option('--allow-commands', 'permit command-type gates when validating')
+        .option('--dry-run', 'preview the registration without writing registry.json')
+        .option('--project <path>', 'register into the repo (<path>/.peaks/sops, committed & team-shared) instead of global')).action(async (options) => {
+        try {
+            const registerOptions = { id: options.id };
+            if (options.allowCommands === true) {
+                registerOptions.allowCommands = true;
+            }
+            if (options.dryRun === true) {
+                registerOptions.dryRun = true;
+            }
+            if (options.project !== undefined) {
+                registerOptions.projectRoot = options.project;
+            }
+            const result = await registerSop(registerOptions);
+            printResult(io, ok('sop.register', result, [], result.applied ? [] : ['Re-run without --dry-run to write registry.json']), options.json);
+        }
+        catch (error) {
+            const code = error instanceof SopRegisterError ? error.code : 'SOP_REGISTER_FAILED';
+            printResult(io, fail('sop.register', code, getErrorMessage(error), { id: options.id }, ['Run peaks sop lint to see why the SOP is not registrable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('registry')
+        .description('List registered SOPs and gates (global; merges in the cwd project layer by default)')
+        .option('--project <path>', 'also include and prefer the repo layer (<path>/.peaks/sops) (default: current directory)', '.')).action(async (options) => {
+        try {
+            const registry = await readRegistry(options.project);
+            printResult(io, ok('sop.registry', registry), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('sop.registry', 'SOP_REGISTRY_FAILED', getErrorMessage(error), {}, ['The global registry may be corrupted; inspect ~/.peaks/sops/registry.json']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('check')
+        .description('Evaluate a single SOP gate (returns pass / fail / blocked)')
+        .requiredOption('--id <sop-id>', 'SOP id')
+        .requiredOption('--gate <gate-id>', 'gate id within the SOP')
+        .option('--project <path>', 'project the gate evaluates against (default: current directory)', '.')
+        .option('--allow-commands', 'permit evaluating command-type gates')).action(async (options) => {
+        try {
+            const checkOptions = { projectRoot: options.project, id: options.id, gateId: options.gate };
+            if (options.allowCommands === true) {
+                checkOptions.allowCommands = true;
+            }
+            const result = await checkGate(checkOptions);
+            printResult(io, ok('sop.check', result), options.json);
+        }
+        catch (error) {
+            const code = error instanceof SopCheckError ? error.code : 'SOP_CHECK_FAILED';
+            printResult(io, fail('sop.check', code, getErrorMessage(error), { id: options.id, gateId: options.gate }, ['Verify the SOP id and gate id with peaks sop lint']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('advance')
+        .description('Advance a SOP to a phase; gates guarding that phase must pass (or be explicitly bypassed)')
+        .requiredOption('--id <sop-id>', 'SOP id')
+        .requiredOption('--to <phase>', 'phase to advance into')
+        .option('--project <path>', 'project whose run-state advances (default: current directory)', '.')
+        .option('--allow-commands', 'permit evaluating command-type gates')
+        .option('--allow-incomplete', 'bypass the phase gates AND phase-order check (requires --reason)')
+        .option('--reason <text>', 'justification recorded when bypassing gates')
+        .option('--confirm', 'skip interactive confirmation for a bypass in assisted/strict mode')
+        .option('--force-confirm', 'bypass mode-enforced confirmation (use with caution)')
+        .option('--dry-run', 'evaluate gates without recording the advance in state.json')).action(async (options) => {
+        try {
+            // Bypass policy mirrors `request transition`: a bypass needs a reason, and
+            // in assisted/strict mode (resolved from the target project) it needs an
+            // explicit --confirm and counts against the per-SOP bypass cap.
+            if (options.allowIncomplete === true && (options.reason === undefined || options.reason.trim().length === 0)) {
+                printResult(io, fail('sop.advance', 'BYPASS_REASON_REQUIRED', '--allow-incomplete requires --reason explaining why the gates are skipped', { id: options.id, to: options.to }, ['Add --reason "<short justification>" or satisfy the gates']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (options.allowIncomplete === true && options.forceConfirm !== true) {
+                const presence = getSkillPresence(options.project);
+                if (presence?.mode === 'assisted' || presence?.mode === 'strict') {
+                    if (options.confirm !== true) {
+                        printResult(io, fail('sop.advance', 'ALLOW_INCOMPLETE_RESTRICTED', `--allow-incomplete requires --confirm in ${presence.mode} mode`, { id: options.id, mode: presence.mode }, ['Add --confirm to bypass non-interactively']), options.json);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    // The bypass counter is keyed to the per-project SOP run-state dir (not
+                    // a session); the shared cap constant is reused. Keying it per-project
+                    // means a bypass in one project never consumes another project's budget.
+                    const bypassRoot = sopStateDir(options.project, options.id);
+                    // The per-project state dir may not exist yet (no successful advance has
+                    // written state.json), so ensure it before the counter writes its file.
+                    mkdirSync(bypassRoot, { recursive: true });
+                    if (isBypassLimitReached(bypassRoot)) {
+                        printResult(io, fail('sop.advance', 'BYPASS_LIMIT_REACHED', `gate bypass limit reached (${MAX_BYPASSES_PER_SESSION} bypasses per SOP)`, { id: options.id, limit: MAX_BYPASSES_PER_SESSION }, ['Satisfy the gates instead of bypassing']), options.json);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    // A dry-run preview must not consume a bypass.
+                    if (options.dryRun !== true) {
+                        recordBypass(bypassRoot);
+                    }
+                }
+            }
+            const advanceOptions = { projectRoot: options.project, id: options.id, toPhase: options.to };
+            if (options.allowCommands === true)
+                advanceOptions.allowCommands = true;
+            if (options.allowIncomplete === true)
+                advanceOptions.allowIncomplete = true;
+            if (options.reason !== undefined)
+                advanceOptions.reason = options.reason;
+            if (options.dryRun === true)
+                advanceOptions.dryRun = true;
+            const result = await advanceSop(advanceOptions);
+            printResult(io, ok('sop.advance', result, [], result.applied ? [] : ['Gates passed; re-run without --dry-run to record the advance']), options.json);
+        }
+        catch (error) {
+            if (error instanceof SopGateBlockedError) {
+                printResult(io, fail('sop.advance', error.code, error.message, { id: options.id, to: options.to, blockedGates: error.blockedGates }, ['Satisfy the blocking gates, or bypass with --allow-incomplete --reason "<why>"']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof SopPhaseSkipError) {
+                printResult(io, fail('sop.advance', error.code, error.message, { id: options.id, to: options.to, fromPhase: error.fromPhase, expectedNext: error.expectedNext }, [`Advance to "${error.expectedNext}" first, or bypass with --allow-incomplete --reason "<why>"`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const code = error instanceof SopAdvanceError ? error.code : 'SOP_ADVANCE_FAILED';
+            printResult(io, fail('sop.advance', code, getErrorMessage(error), { id: options.id, to: options.to }, ['Verify the SOP id and phase with peaks sop lint']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

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

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

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

@@ -0,0 +1,169 @@
+import { fail, ok } from '../../shared/result.js';
+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 });
+}
+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.'));
+    // Hidden render subcommand. This is the default behavior when the user types
+    // `peaks statusline` with no subcommand. We mark it hidden so `peaks
+    // statusline --help` does not show "render" as a subcommand.
+    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) => {
+        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);
+    });
+    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.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `peaks sub-agent` CLI command group — slice 2026-06-07-sub-agent-context-governance.
+ *
+ * Thin entry point that wires the four sub-command registrars
+ * (`dispatch`, `heartbeat`, `share`, `shared-read`, `await`) to the
+ * parent `sub-agent` command. The actual implementations live in
+ * sibling files (slice 2026-06-23-audit-p0-split refactor):
+ *
+ *   - `dispatch-commands.ts`  — `dispatch` single-dispatch action
+ *   - `dispatch-from-dag.ts`  — `dispatch --from-dag` codepath (slice 9 perf)
+ *   - `heartbeat-commands.ts` — `heartbeat` action (G6)
+ *   - `share-commands.ts`     — `share` + `shared-read` + `await` actions (G8.4 / 2.7.0)
+ *   - `sub-agent-shared.ts`   — shared types, constants, helpers
+ *
+ * Skill-first / CLI-auxiliary red line (PB-4 / AC-19/20):
+ *   These commands are primitives that the peaks-code / peaks-rd /
+ *   peaks-qa SKILL.md compose. Users do NOT invoke them directly.
+ */
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export { validateRole } from './sub-agent-shared.js';
+export declare function registerSubAgentCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,19 @@
+import { registerDispatchCommand } from './dispatch-commands.js';
+import { registerHeartbeatCommand } from './heartbeat-commands.js';
+import { registerShareCommand, registerSharedReadCommand, registerAwaitCommand } 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);
+}

package/dist/cli/commands/sub-agent-dispatch-guard.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `peaks sub-agent-dispatch-guard` — G9.5 / RL-30 strict hook-only atom.
+ *
+ * This is the **second-layer** gate (PreToolUse hook) for the G9 forced
+ * compression threshold. It re-validates the prompt size against the
+ * threshold table in `src/services/context/threshold.ts` and returns
+ * `{allow: true/false, reason, suggest}` JSON to the LLM platform.
+ *
+ * **NO `--force` flag is exposed at this layer** (RL-30 strict). The
+ * hook is the strictest layer in the G9 chain. If the CLI is bypassed
+ * (e.g. a user manually invokes the dispatch CLI with `--force` to
+ * override the 80% threshold), the hook catches it and returns
+ * `{allow: false}` regardless.
+ *
+ * This atom is **hidden from `peaks --help`** per dev-preference
+ * "skill-first / CLI-auxiliary" + PB-2 byte-stable. It is registered
+ * via the LLM platform's PreToolUse hook chain (e.g. Claude Code's
+ * `settings.json` `PreToolUse` array) and is not a user-facing command.
+ *
+ * The `peaks hooks install` command reads `IdeAdapter.promptSizeAware`
+ * to decide whether to register this hook for a given IDE.
+ */
+import { Command } from 'commander';
+import { type ContextGuardDecision } from '../../services/context/context-guard.js';
+export declare const HOOK_GUARD_RESULT_TYPE: "peaks-hook-guard/v1";
+export interface HookGuardResult {
+    readonly schema: typeof HOOK_GUARD_RESULT_TYPE;
+    readonly allow: boolean;
+    readonly code: ContextGuardDecision['code'];
+    readonly reason: string;
+    readonly suggest: string | null;
+    readonly tier: ContextGuardDecision['evaluation']['tier'];
+    readonly ratio: number;
+    readonly bytesUsed: number;
+    readonly capacityBytes: number;
+    readonly warnings: readonly string[];
+}
+/**
+ * Build the hook-guard result for a given prompt size. Pure function;
+ * no IO. The CLI atom (registered below) calls this and prints JSON.
+ *
+ * Even if the caller passes `force = true` in the input (it shouldn't —
+ * the hook CLI doesn't expose that flag), this function ignores it
+ * and treats the prompt as if no override were available. This is the
+ * RL-30 strict semantics.
+ */
+export declare function evaluateHookGuard(promptSize: number): HookGuardResult;
+/**
+ * Register the `peaks sub-agent-dispatch-guard` command. Intentionally
+ * NOT registered in the main `peaks --help` quickstart (dev-preference
+ * PB-2 byte-stable). The caller (the `peaks hooks install` flow) calls
+ * this directly via the imported function; the CLI registration in
+ * `src/cli/index.ts` uses a hidden command (no `description`, no help).
+ */
+export declare function registerSubAgentDispatchGuard(program: Command): void;

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

@@ -0,0 +1,57 @@
+import { evaluatePromptSize } from '../../services/context/context-guard.js';
+export const HOOK_GUARD_RESULT_TYPE = 'peaks-hook-guard/v1';
+/**
+ * Build the hook-guard result for a given prompt size. Pure function;
+ * no IO. The CLI atom (registered below) calls this and prints JSON.
+ *
+ * Even if the caller passes `force = true` in the input (it shouldn't —
+ * the hook CLI doesn't expose that flag), this function ignores it
+ * and treats the prompt as if no override were available. This is the
+ * RL-30 strict semantics.
+ */
+export function evaluateHookGuard(promptSize) {
+    // Intentionally pass `force: false` always. The hook layer is strict.
+    const decision = evaluatePromptSize(promptSize, { force: false });
+    return {
+        schema: HOOK_GUARD_RESULT_TYPE,
+        allow: decision.allow,
+        code: decision.code,
+        reason: decision.allow
+            ? `prompt size ${promptSize} bytes within threshold (tier=${decision.evaluation.tier})`
+            : `prompt size ${promptSize} bytes exceeds threshold (tier=${decision.evaluation.tier}, ratio=${decision.evaluation.ratio.toFixed(3)})`,
+        suggest: decision.suggest,
+        tier: decision.evaluation.tier,
+        ratio: decision.evaluation.ratio,
+        bytesUsed: decision.evaluation.bytesUsed,
+        capacityBytes: decision.evaluation.capacityBytes,
+        warnings: decision.warnings
+    };
+}
+/**
+ * Register the `peaks sub-agent-dispatch-guard` command. Intentionally
+ * NOT registered in the main `peaks --help` quickstart (dev-preference
+ * PB-2 byte-stable). The caller (the `peaks hooks install` flow) calls
+ * this directly via the imported function; the CLI registration in
+ * `src/cli/index.ts` uses a hidden command (no `description`, no help).
+ */
+export function registerSubAgentDispatchGuard(program) {
+    program
+        .command('sub-agent-dispatch-guard')
+        .description('INTERNAL: PreToolUse hook guard (G9.5 / RL-30 strict)')
+        .requiredOption('--prompt <text>', 'the prompt to validate (size in bytes is what gets checked)')
+        .option('--prompt-length <bytes>', 'DOGFOOD ONLY: synthesize a prompt of this size (overrides --prompt content for size only)')
+        .action((options) => {
+        let prompt = options.prompt;
+        if (typeof options.promptLength === 'string' && options.promptLength.length > 0) {
+            const len = Number.parseInt(options.promptLength, 10);
+            if (Number.isInteger(len) && len > 0) {
+                prompt = 'x'.repeat(len);
+            }
+        }
+        const promptSize = Buffer.byteLength(prompt, 'utf8');
+        const result = evaluateHookGuard(promptSize);
+        // Always exit 0 — the LLM platform reads `allow` from JSON.
+        // The decision is encoded in `allow` / `code`, not the exit code.
+        process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    });
+}

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;
+};