peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,239 @@
+import { enforceBashCommand, recordGateBypass, GateBypassError } from '../../services/sop/gate-enforce-service.js';
+import { evaluateWorktreeAuth } from '../../services/hooks/worktree-authorization-gate.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { detectIdeFromContext, parseClaudeShapeStdin, pluckObject, pluckString } from '../../services/ide/hook-translator.js';
+import { getAdapter } from '../../services/ide/ide-registry.js';
+import { emitBlock, emitDecision, emitHint } from '../../services/hooks/output.js';
+/**
+ * Read the PreToolUse hook payload. `PEAKS_HOOK_STDIN` is a test seam; production
+ * reads stdin. The CLI-side stdin reader is intentionally kept here (not in
+ * `hook-translator.ts`) because it owns the `process.stdin` lifecycle and the
+ * test-seam env var. The translator operates on already-parsed payloads.
+ */
+async function readHookPayload() {
+    const override = process.env.PEAKS_HOOK_STDIN;
+    if (override !== undefined) {
+        return override;
+    }
+    if (process.stdin.isTTY) {
+        return '';
+    }
+    return new Promise((resolveStdin) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (chunk) => {
+            data += chunk;
+        });
+        process.stdin.on('end', () => resolveStdin(data));
+        process.stdin.on('error', () => resolveStdin(data));
+    });
+}
+/**
+ * Map Claude Code tool name to the gate's internal `ToolCallKind`. Anything we don't recognize
+ * returns `'Other'` — the worktree gate is opt-in by tool, so unknown tools short-circuit to allow.
+ */
+function classifyTool(toolName) {
+    if (toolName === 'Bash')
+        return 'Bash';
+    if (toolName === 'Agent' || toolName === 'Task')
+        return 'Agent';
+    if (toolName === 'EnterWorktree')
+        return 'EnterWorktree';
+    if (toolName === 'Workflow')
+        return 'Workflow';
+    return 'Other';
+}
+/**
+ * Best-effort extraction of the `isolation` field for `Agent` / `Task` tool calls. The Claude
+ * hook payload puts args under `tool_input`, the Cursor/Trae sibling puts them under `toolInput`.
+ * Both shapes are accepted; everything else returns null.
+ */
+function extractIsolation(parsed) {
+    if (parsed === null || typeof parsed !== 'object')
+        return null;
+    const input = pluckObject(parsed, ['tool_input']) ?? pluckObject(parsed, ['toolInput']);
+    if (input === undefined)
+        return null;
+    const value = pluckString(input, ['isolation']);
+    return value === undefined ? null : value;
+}
+export function registerGateCommands(program, io) {
+    const gate = program.command('gate').description('SOP gate enforcement (PreToolUse hook handler and bypass)');
+    addJsonOption(gate
+        .command('enforce')
+        .description('PreToolUse hook handler: deny a Bash command guarded by an unsatisfied SOP gate')
+        .option('--project <path>', 'project the gates evaluate against (default: current directory)', '.')).action(async (options) => {
+        // Trust red line: this runs on (potentially) every Bash call. Any failure to
+        // decide must FAIL-OPEN (allow), never block the user's Claude Code.
+        try {
+            const raw = await readHookPayload();
+            let parsedStdin = null;
+            if (raw.trim().length > 0) {
+                try {
+                    parsedStdin = JSON.parse(raw);
+                }
+                catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+                    // Malformed JSON — fail-open. Detect + parse on null fall back to the
+                    // default adapter and yield empty tool/command, which short-circuits
+                    // to the "not a guarded surface" early exit below.
+                }
+            }
+            const ide = detectIdeFromContext({ env: process.env, cwd: process.cwd(), parsedStdin });
+            const adapter = getAdapter(ide);
+            // For slice #1 only the Claude adapter is registered, so the parser is
+            // Claude-shaped. Future slices dispatch on `ide` to pick a per-adapter
+            // parser; the parser entry-point (`parseXxxShapeStdin`) is the only
+            // change required.
+            const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
+            if (toolName !== adapter.toolMatcher || typeof command !== 'string' || command.trim().length === 0) {
+                // Not a guarded surface — allow. Emit minimal JSON on stdout so Claude
+                // Code's PreToolUse hook validator accepts the response. Empty stdout
+                // is rejected with "Hook JSON output validation failed — Invalid input"
+                // in Claude Code 2.x; `{}` is the canonical no-op marker.
+                if (options.json === true) {
+                    printResult(io, ok('gate.enforce', { decision: 'allow', skipped: true }), true);
+                }
+                else {
+                    emitDecision(io, {});
+                }
+                return;
+            }
+            // slice 2026-07-27-worktree-user-auth: BEFORE the SOP gate runs, check the worktree
+            // authorization gate. The worktree gate is narrower than the SOP gate (it only inspects
+            // a small set of worktree-mutating operations) and is fail-CLOSED. The two layers are
+            // complementary: SOP gates decide "may this command run under this SOP's state", the
+            // worktree gate decides "did the user explicitly authorize this worktree-mutating operation
+            // in the current task". The worktree gate is cheap and self-contained, so it runs first
+            // to give the LLM a clear error reason before the SOP gate would otherwise allow.
+            //
+            // We extract the tool kind from the hook payload (Bash/Agent/EnterWorktree/Workflow).
+            // For Agent/Task we also pull `isolation` from the tool input — only "worktree" isolation
+            // is gated. For all other tool kinds the worktree gate is a no-op.
+            const toolKind = classifyTool(toolName);
+            if (toolKind !== 'Other') {
+                const sessionId = getCurrentSessionId(options.project) ?? 'unknown-sid';
+                // slice 2026-07-29-worktree-l2-extended Part 2.B: the gate consults
+                // the lease file referenced by `PEAKS_WORKTREE_LEASE_ID` as a
+                // second authorization path when no `peaks worktree auth grant`
+                // is on file. Dispatch (Part 2.C) injects the env var on every
+                // sub-agent spawn so worktree-mutating tool calls from inside
+                // the sub-agent process auto-authorize via the lease instead
+                // of requiring a separate grant.
+                const leaseId = process.env.PEAKS_WORKTREE_LEASE_ID ?? null;
+                // Part 19: container lease (L4) is the parallel path for
+                // `--isolation container` sub-agents. The env is set by the
+                // dispatch command (Part 8 + Part 12) at spawn time.
+                const containerLeaseId = process.env.PEAKS_CONTAINER_LEASE_ID ?? null;
+                const wtDecision = evaluateWorktreeAuth({
+                    projectRoot: options.project,
+                    sessionId,
+                    toolName: toolKind,
+                    command: toolKind === 'Bash' ? command : null,
+                    isolation: toolKind === 'Agent' || toolKind === 'EnterWorktree' ? extractIsolation(parsedStdin) : null,
+                    requestId: null,
+                    leaseId: leaseId !== null && /^[a-f0-9]{16}$/.test(leaseId) ? leaseId : null,
+                    containerLeaseId: containerLeaseId !== null && /^[a-f0-9]{16}$/.test(containerLeaseId) ? containerLeaseId : null
+                });
+                if (!wtDecision.allow) {
+                    // Hard block: a worktree-mutating tool call without a current-task user grant.
+                    // emitBlock writes the Claude Code permissionDecision:"deny" envelope and exits 2.
+                    // The reason includes the remediation hint so the LLM can run `peaks worktree auth grant`
+                    // and retry, and the user can read the deny text in the next-turn stderr.
+                    emitBlock(io, `[worktree-gate:${wtDecision.code}] ${wtDecision.reason} — ${wtDecision.remediation}`);
+                    if (options.json === true) {
+                        emitHint(io, JSON.stringify(ok('gate.enforce', { decision: 'deny', layer: 'worktree-auth', ...wtDecision })));
+                    }
+                    return;
+                }
+                // allow: continue to the SOP gate (the regular enforcement path).
+                // wtDecision may have arrived via lease (viaLease != null); the SOP gate does not
+                // care which path granted, only that the worktree gate said allow.
+            }
+            const decision = await enforceBashCommand(options.project, command);
+            if (decision.decision === 'deny') {
+                // PRD#2 (2026-06-16-fact-forcing-gate-format): a true SOP gate failure is
+                // a HARD block. emitBlock writes the Claude Code permissionDecision:"deny"
+                // JSON to stdout (the hook's decision signal), sets process.exitCode = 2
+                // (Claude Code's block exit code), AND surfaces the reason to stderr so
+                // the LLM sees it on the next turn. This prevents the previous behaviour
+                // where Claude Code wrapped the output as "PreToolUse:Bash hook error".
+                emitBlock(io, decision.reason);
+                if (options.json === true) {
+                    emitHint(io, JSON.stringify(ok('gate.enforce', decision)));
+                }
+                return;
+            }
+            if (decision.warnings && decision.warnings.length > 0) {
+                for (const warning of decision.warnings) {
+                    emitHint(io, warning);
+                }
+            }
+            if (options.json === true) {
+                // --json mode: emit the canonical envelope on stdout (the
+                // documented contract for downstream tooling). The hook
+                // decision (allow/deny) is still signalled via process.exitCode
+                // + the minimal `{}` on stdout in non-`--json` mode.
+                // Slice 2026-07-30-nightshift: emitHint here was wrong —
+                // emitHint writes to stderr, but the AC5 contract expects
+                // the JSON envelope on stdout. Switch to printResult(asJson=true).
+                printResult(io, ok('gate.enforce', decision), true);
+            }
+            else {
+                // allow: emit minimal JSON on stdout so Claude Code's PreToolUse hook
+                // validator accepts the response (see comment above).
+                emitDecision(io, {});
+            }
+        }
+        catch (error) {
+            // Fail-open: a bug in enforcement must not brick Claude Code.
+            emitHint(io, `gate enforce: internal error, allowing command (${getErrorMessage(error)})`);
+        }
+        // Slice 2026-07-29-windows-console-flash Part 46: actively
+        // exit the process when the gate-enforce handler returns.
+        // The default behavior is to wait for stdin EOF before
+        // exiting, but the hook's stdin pipe may not close promptly
+        // (the parent can keep the handle open even after it has
+        // finished reading the JSON decision), which causes 4
+        // Node.js processes to accumulate in the user's task
+        // manager. An explicit process.exit here forces the gate
+        // process to release all handles and exit immediately.
+        //
+        // Slice 2026-07-30-nightshift: gate the `process.exit` on
+        // being invoked as a real CLI hook (no PEAKS_HOOK_STDIN test
+        // seam, no PEAKS_TEST_SEAM env var). The test harness calls
+        // `runCommand` which invokes the same action handler in
+        // process — calling `process.exit` inside the test would
+        // kill the vitest runner before assertions complete. The
+        // `process.exitCode` set above is sufficient for the test
+        // path: Commander's `parseAsync` resolves the action, then
+        // the harness reads the captured stdout/stderr before the
+        // runner exits normally with the recorded exit code.
+        if (process.env.PEAKS_HOOK_STDIN === undefined && process.env.PEAKS_TEST_SEAM === undefined) {
+            process.exit(process.exitCode || 0);
+        }
+    });
+    addJsonOption(gate
+        .command('bypass')
+        .description('Record a one-shot bypass so the next guarded Bash command is allowed once')
+        .requiredOption('--sop <id>', 'SOP id whose guard to bypass')
+        .requiredOption('--phase <phase>', 'phase whose gate to bypass')
+        .requiredOption('--reason <text>', 'justification recorded for the bypass')
+        .option('--project <path>', 'project whose run-state holds the token (default: current directory)', '.')).action((options) => {
+        try {
+            if (options.reason.trim().length === 0) {
+                printResult(io, fail('gate.bypass', 'BYPASS_REASON_REQUIRED', '--reason must not be empty', { sop: options.sop, phase: options.phase }, ['Provide --reason "<why>"']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const result = recordGateBypass(options.project, options.sop, options.phase, options.reason);
+            printResult(io, ok('gate.bypass', { sop: options.sop, phase: options.phase, count: result.count }, [], ['The next guarded Bash command for this transition will be allowed once']), options.json);
+        }
+        catch (error) {
+            const code = error instanceof GateBypassError ? error.code : 'GATE_BYPASS_FAILED';
+            printResult(io, fail('gate.bypass', code, getErrorMessage(error), { sop: options.sop, phase: options.phase }, ['Satisfy the gate instead of bypassing']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/governance-classify-contract-commands.d.ts

@@ -0,0 +1,21 @@
+/**
+ * rid-007 Family 1 merge: contract-commands + classify-classify-commands.
+ *
+ * Pre-merge originals (now deleted):
+ *   - src/cli/commands/contract-commands.ts     (167 lines)
+ *   - src/cli/commands/classify-classify-commands.ts (190 lines)
+ *
+ * Both exported `register*Commands` functions are preserved **verbatim**
+ * (function name, signature, body). The merge is a structural refactor
+ * only — no behavior change. `autoRegisterAllCommands` discovers both
+ * exports from this single file.
+ *
+ * Why one file: the RD slice rid-007 user-confirmed one-family merge
+ * minimum; Family 1 is the cleanest demonstration because both inputs
+ * sit under 200 lines and the merged file lands at ~360 lines — well
+ * below the 400-line AC-9 sanity guard and the 800-line scan gate.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerContractCommands(program: Command, io: ProgramIO): void;
+export declare function registerClassifyCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/governance-classify-contract-commands.js

@@ -0,0 +1,273 @@
+/**
+ * rid-007 Family 1 merge: contract-commands + classify-classify-commands.
+ *
+ * Pre-merge originals (now deleted):
+ *   - src/cli/commands/contract-commands.ts     (167 lines)
+ *   - src/cli/commands/classify-classify-commands.ts (190 lines)
+ *
+ * Both exported `register*Commands` functions are preserved **verbatim**
+ * (function name, signature, body). The merge is a structural refactor
+ * only — no behavior change. `autoRegisterAllCommands` discovers both
+ * exports from this single file.
+ *
+ * Why one file: the RD slice rid-007 user-confirmed one-family merge
+ * minimum; Family 1 is the cleanest demonstration because both inputs
+ * sit under 200 lines and the merged file lands at ~360 lines — well
+ * below the 400-line AC-9 sanity guard and the 800-line scan gate.
+ */
+// ===========================================================================
+// Shared imports (consolidated; both originals pulled names from these
+// same modules — `cli-helpers.ts` re-exports `getErrorMessage` from
+// `peaks-loop-shared/result`, so the single canonical import is
+// functionally identical to either original line.)
+// ===========================================================================
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { writeContract } from '../../services/dispatch/contract-store.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { classifyTask } from '../../services/classify/classify-service.js';
+import { TASK_LEVELS } from '../../services/classify/classify-types.js';
+import { loadPreferences } from '../../services/preferences/preferences-service.js';
+// ===========================================================================
+// Section 1: `peaks contract` CLI commands (was contract-commands.ts).
+// ===========================================================================
+const INPUT_LIMIT_BYTES = 256 * 1024;
+/** Split a comma-separated flag value into a trimmed string array. */
+function splitCsv(value) {
+    if (value === undefined)
+        return [];
+    return value
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+export function registerContractCommands(program, io) {
+    const contract = program
+        .command('contract')
+        .description('Slice contract store (skill-first / CLI-auxiliary). These commands ' +
+        'are primitives that peaks-code / peaks-rd SKILL.md compose. The LLM-side ' +
+        'runner (the IDE-resident sub-agent that finished a slice) calls ' +
+        '`peaks contract write` to persist the slice\'s public surface; the ' +
+        'orchestrator picks it up on the next dispatch run via listContracts() ' +
+        'and splices it into downstream prompts via formatContractInjection().');
+    // ─────────────────────────────────────────────────────────────────
+    // peaks contract write --project <root> --session-id <sid>
+    //   --slice-id <id> --exports <a,b> --types <x,y> --signatures <s1,s2>
+    //   [--broadcast-to <b1,b2>] [--completed-at <iso>]
+    // ─────────────────────────────────────────────────────────────────
+    addJsonOption(contract
+        .command('write')
+        .description('2.7.0 slice-dag-dispatcher MVP: persist a finished slice\'s public ' +
+        'surface (exports / types / publicSignatures) to disk at ' +
+        '.peaks/_runtime/<sessionId>/dispatch/contracts/<slice-id>.json. ' +
+        'The orchestrator picks it up on the next dispatch run. Idempotent: ' +
+        're-running with the same inputs overwrites in place; the SHA-256 ' +
+        'contractHash is content-derived so a contract write from a different ' +
+        'runner (re-execution) is detected as a content change.')
+        .option('--project <path>', 'target project root (defaults to cwd)')
+        .option('--session-id <sid>', 'session id (default: resolve from .peaks/_runtime/session.json; falls back to PEAKS_SESSION_ID env var; final fallback "unknown-sid")')
+        .requiredOption('--slice-id <id>', 'slice id; must be non-empty; used as the contract filename basename')
+        .option('--exports <list>', 'comma-separated public export names (e.g. "validateDag,topologicalLevels")')
+        .option('--types <list>', 'comma-separated public type names (e.g. "SliceDag,SliceNode")')
+        .option('--signatures <list>', 'comma-separated public function/method signatures (e.g. "validateDag(dag: SliceDag): void")')
+        .option('--broadcast-to <list>', 'comma-separated downstream slice ids that should auto-inherit this contract (e.g. "B,C")')
+        .option('--completed-at <iso>', 'ISO 8601 timestamp; defaults to now()')).action((options) => {
+        const asJson = options.json === true;
+        const projectRoot = options.project ?? process.cwd();
+        // Slice 2026-06-26-unknown-sid-fallback-fix: see dispatch-commands.ts.
+        const sid = options.sessionId
+            ?? process.env.PEAKS_SESSION_ID
+            ?? getCurrentSessionId(projectRoot)
+            ?? 'unknown-sid';
+        const sliceId = options.sliceId;
+        if (sliceId === undefined || sliceId.length === 0) {
+            printResult(io, fail('contract.write', 'MISSING_SLICE_ID', '--slice-id is required', { path: null, contract: null }, [
+                'Re-run with --slice-id <id> (must be non-empty; used as the contract filename basename).'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const exports = splitCsv(options.exports);
+        const types = splitCsv(options.types);
+        const signatures = splitCsv(options.signatures);
+        const broadcastTo = splitCsv(options.broadcastTo);
+        // Cap the combined input to protect the file IO from runaway values
+        // (e.g. a 10MB comma-separated --signatures flag).
+        const inputSize = sliceId.length +
+            sid.length +
+            exports.join(',').length +
+            types.join(',').length +
+            signatures.join(',').length +
+            broadcastTo.join(',').length +
+            (options.completedAt?.length ?? 0);
+        if (inputSize > INPUT_LIMIT_BYTES) {
+            printResult(io, fail('contract.write', 'INPUT_TOO_LARGE', `combined input size ${inputSize} bytes exceeds ${INPUT_LIMIT_BYTES} (likely oversized --exports/--types/--signatures lists)`, { path: null, contract: null }, [
+                'Split the slice into smaller surfaces or omit optional fields.'
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const input = {
+                sliceId,
+                sessionId: sid,
+                exports,
+                types,
+                publicSignatures: signatures,
+                ...(broadcastTo.length > 0 ? { broadcastTo } : {}),
+                ...(options.completedAt !== undefined ? { completedAt: options.completedAt } : {})
+            };
+            const result = writeContract(projectRoot, sid, input);
+            printResult(io, ok('contract.write', {
+                path: result.path,
+                contractHash: result.contract.contractHash,
+                sliceId: result.contract.sliceId,
+                sessionId: result.contract.sessionId,
+                completedAt: result.contract.completedAt,
+                exportCount: result.contract.exports.length,
+                typeCount: result.contract.types.length,
+                signatureCount: result.contract.publicSignatures.length,
+                broadcastTo: result.contract.broadcastTo ?? []
+            }, [], [
+                `Contract written; orchestrator will pick it up on the next \`peaks sub-agent dispatch --from-dag\` run.`,
+                `Re-running with the same inputs is idempotent (overwrites in place).`
+            ]), asJson);
+        }
+        catch (err) {
+            printResult(io, fail('contract.write', 'WRITE_ERROR', getErrorMessage(err), { path: null, contract: null }, [
+                'See error message; check that --project is a writable directory and --slice-id is a valid filename basename (no path separators).'
+            ]), asJson);
+            process.exitCode = 1;
+        }
+    });
+}
+const CLASSIFY_AUDIT_FILE = 'classify-audit.jsonl';
+function getSignalsFromGitDiff(projectRoot) {
+    // Use git diff --stat to extract file count + line count. Fall back to
+    // zeros if git is unavailable (e.g. fresh repo with no commits).
+    let stdout;
+    try {
+        const { execFileSync } = require('node:child_process');
+        stdout = execFileSync('git', ['diff', '--shortstat', 'HEAD'], {
+            cwd: projectRoot,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            maxBuffer: 32 * 1024 * 1024,
+        }).toString('utf8');
+    }
+    catch {
+        return { filesChanged: 0, linesChanged: 0, touchesDependencies: false, touchesMigrationScripts: false, isPureRefactor: true, keywords: [] };
+    }
+    const lines = stdout.split('\n').filter((l) => l.trim().length > 0);
+    const filesChanged = lines.length;
+    let added = 0;
+    let removed = 0;
+    let touchesDependencies = false;
+    let touchesMigrationScripts = false;
+    for (const line of lines) {
+        const match = /(\d+)\s+insertion.*?(\d+)\s+deletion/.exec(line);
+        if (match) {
+            added += Number(match[1]);
+            removed += Number(match[2]);
+        }
+        if (/(package\.json|pnpm-lock\.yaml|yarn\.lock|requirements\.txt|go\.mod)/.test(line)) {
+            touchesDependencies = true;
+        }
+        if (/(migrate|codemod|backfill|schema)/.test(line)) {
+            touchesMigrationScripts = true;
+        }
+    }
+    // isPureRefactor: heuristic — if added lines / removed lines < 0.1 OR
+    // no new exports were added, treat as refactor. For L2.2 the signal is
+    // binary (true/false). Default: true (no behavior change is the safe
+    // assumption; flip to false when keyword 'add' / 'new' / 'feature' present).
+    const isPureRefactor = true;
+    return {
+        filesChanged,
+        linesChanged: added + removed,
+        touchesDependencies,
+        touchesMigrationScripts,
+        isPureRefactor,
+        keywords: [],
+    };
+}
+function appendAuditEntry(projectRoot, entry) {
+    const auditDir = join(projectRoot, '.peaks/_runtime');
+    if (!existsSync(auditDir)) {
+        try {
+            mkdirSync(auditDir, { recursive: true });
+        }
+        catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    }
+    const auditPath = join(auditDir, CLASSIFY_AUDIT_FILE);
+    let body = '';
+    try {
+        if (existsSync(auditPath)) {
+            body = readFileSync(auditPath, 'utf8');
+        }
+    }
+    catch { /* ignore */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+    body += JSON.stringify(entry) + '\n';
+    try {
+        writeFileSync(auditPath, body);
+    }
+    catch { /* best-effort */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+}
+function isTaskLevel(value) {
+    return TASK_LEVELS.includes(value);
+}
+export function registerClassifyCommands(program, io) {
+    const classify = program
+        .command('classify')
+        .description('L1a task classification: 5-level heuristic (typo/bug/feature/refactor/migration) + override/upgrade + audit log');
+    addJsonOption(classify
+        .command('run')
+        .description('Classify the current diff (git diff HEAD) into one of 5 task levels')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--override <level>', 'force a level (one of typo|bug|feature|refactor|migration); requires --reason')
+        .option('--reason <text>', 'reason for the override (mandatory when --override is set)')).action(async (options) => {
+        try {
+            const prefs = await loadPreferences(options.project);
+            const signals = getSignalsFromGitDiff(options.project);
+            let override;
+            if (options.override !== undefined) {
+                if (!isTaskLevel(options.override)) {
+                    printResult(io, fail('classify.run', 'INVALID_LEVEL', `level must be one of: ${TASK_LEVELS.join(', ')}`, { provided: options.override }, ['Pass one of typo, bug, feature, refactor, migration']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                if (options.reason === undefined || options.reason.length === 0) {
+                    printResult(io, fail('classify.run', 'REASON_REQUIRED', '--reason is required when --override is set', {}, ['Provide a non-empty reason for the override']), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                override = { level: options.override, reason: options.reason };
+            }
+            const result = classifyTask(override !== undefined
+                ? { signals, conservatism: prefs.classifyConservatism, override }
+                : { signals, conservatism: prefs.classifyConservatism }, prefs.classifyRules.feature_threshold_files, prefs.classifyRules.feature_threshold_lines);
+            appendAuditEntry(options.project, result.audit);
+            printResult(io, ok('classify.run', result, [], [
+                `gate set for level "${result.level}": ${result.gateSet.stages.join(', ')}`,
+                `audit log: .peaks/_runtime/${CLASSIFY_AUDIT_FILE}`,
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('classify.run', 'CLASSIFY_RUN_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Run peaks classify --help for usage']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // Downgrade is REFUSED per spec §4. Surface this as a hard fail.
+    classify
+        .command('downgrade')
+        .description('REFUSED per spec §4 — peaks-loop never downgrades a classification; ask the user to override explicitly')
+        .requiredOption('--level <level>', 'attempted level')
+        .requiredOption('--reason <text>', 'reason for the attempt (always rejected)')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--json', 'print machine-readable JSON envelope')
+        .action(async (options) => {
+        printResult(io, fail('classify.downgrade', 'DOWNGRADE_REFUSED', 'peaks classify downgrade is refused per spec §4. Use --override (with reason) on `classify run` to force a level; the CLI never downgrades a classification unilaterally.', { attemptedLevel: options.level, reason: options.reason }, ['Use `peaks classify run --override <level> --reason "<text>"` instead']), options.json);
+        process.exitCode = 2;
+    });
+}

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

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