peaks-loop 4.1.1 → 4.1.3

package/dist/cli/commands/finalize-runners.js

@@ -0,0 +1,92 @@
+/**
+ * The `finalize` action body for `peaks sub-agent`, split out of
+ * `share-commands.ts` so that registrar file stays under the line cap. The
+ * registrar fires this runner without awaiting it (the original fired a
+ * floating async IIFE in the same way).
+ *
+ * `runFinalizeSweep` builds the accumulator, applies the outcome mapping and
+ * prints the envelope; the three selection branches live in
+ * `finalize-branches.ts` and the selection rule itself in
+ * `finalize-selection.ts`.
+ */
+import { resolve } from 'node:path';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { printResult } from '../cli-helpers.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { OUTCOME_MAP, buildFinalizeHints, makeAccumulator, tryReadRecord } from './finalize-accumulator.js';
+import { finalizeAllStale, finalizeByBatch, finalizeByRequestId } from './finalize-branches.js';
+export async function runFinalize(options, io) {
+    const asJson = options.json === true;
+    try {
+        const projectRoot = resolve(options.project ?? process.cwd());
+        const sessionId = options.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        if (!options.allStale && !options.requestId && !options.batch) {
+            printResult(io, fail('sub-agent.finalize', 'MISSING_TARGET', 'Pass --request-id or --batch (or --all-stale)', { ok: false }, ['Call finalize after each Task completes.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        await runFinalizeSweep({ options, io, asJson, projectRoot, sessionId });
+    }
+    catch (error) {
+        printResult(io, fail('sub-agent.finalize', 'FINALIZE_ERROR', getErrorMessage(error), { ok: false }, [
+            'Inspect the error.'
+        ]), asJson);
+        process.exitCode = 1;
+    }
+}
+async function runFinalizeSweep(input) {
+    const { options, io, asJson, projectRoot, sessionId } = input;
+    const outcome = (options.outcome ?? 'done');
+    const writerMod = await import('../../services/dispatch/dispatch-record-writer.js');
+    const { readRecord, markCompleted, readActiveDispatchIndex } = writerMod;
+    const mapped = OUTCOME_MAP[outcome] ?? OUTCOME_MAP['done'];
+    const acc = makeAccumulator();
+    const readOne = (recordPath) => tryReadRecord(recordPath, readRecord, acc);
+    const apply = (recordPath, rid) => {
+        markCompleted({
+            recordPath,
+            now: () => new Date(),
+            status: mapped.status,
+            outcome: mapped.outcome,
+            projectRoot
+        });
+        acc.finalized.push({ recordPath, requestId: rid, status: mapped.status });
+    };
+    let selection = null;
+    if (options.allStale) {
+        finalizeAllStale({ readActiveDispatchIndex, projectRoot, sessionId, apply, acc });
+    }
+    else if (options.requestId) {
+        const result = await finalizeByRequestId({
+            projectRoot,
+            sessionId,
+            requestId: options.requestId,
+            io,
+            asJson,
+            readOne,
+            apply,
+            acc
+        });
+        if (result.kind === 'not-found')
+            return;
+        selection = result.selection;
+    }
+    else {
+        await finalizeByBatch({ projectRoot, sessionId, batchId: options.batch, readOne, apply, acc });
+    }
+    printFinalizeResult({ io, asJson, sessionId, outcome, acc, selection });
+    if (acc.errors.length > 0)
+        process.exitCode = 1;
+}
+/** Print the `sub-agent.finalize` envelope and its hints. */
+function printFinalizeResult(input) {
+    const { acc } = input;
+    printResult(input.io, ok('sub-agent.finalize', {
+        finalized: acc.finalized,
+        skipped: acc.skipped,
+        errors: acc.errors,
+        selection: input.selection,
+        sessionId: input.sessionId,
+        outcome: input.outcome
+    }, acc.errors.length > 0 ? [acc.errors.length + ' failed'] : [], buildFinalizeHints(acc, input.selection)), input.asJson);
+}

package/dist/cli/commands/finalize-selection.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The pure `--request-id` selection contract for `peaks sub-agent finalize`, plus
+ * the option shape the command registers. Extracted from `share-commands.ts` so
+ * that file stays under the line cap; these are the pieces the finalize tests
+ * import directly, and none of them touches the filesystem.
+ */
+/**
+ * A `dispatch-*.json` candidate for `finalize --request-id`, as read off disk.
+ * The record's own `createdAt` is carried as the recency key — NOT the file's
+ * mtime, which any heartbeat or finalize rewrites, so a `done` record can look
+ * newer than the `queued` one that superseded it. Keeping the key on the
+ * candidate makes the selection rule a pure function of the records and
+ * testable without a filesystem.
+ */
+export interface FinalizeCandidate {
+    readonly recordPath: string;
+    readonly requestId: string;
+    readonly status: string;
+    readonly createdAt: string;
+}
+/**
+ * What `--request-id` actually did, reported in the envelope. N3: the branch
+ * used to resolve silently and could not say WHY a record was or was not the
+ * one finalized.
+ */
+export interface FinalizeSelection {
+    readonly requestId: string;
+    readonly rule: string;
+    readonly matched: number;
+    readonly chosen: string | null;
+    readonly rejected: readonly {
+        readonly recordPath: string;
+        readonly status: string;
+        readonly reason: string;
+    }[];
+}
+/** The one selection rule `--request-id` and `--batch` now share. */
+export declare const FINALIZE_SELECTION_RULE: string;
+/** The options `peaks sub-agent finalize` accepts. */
+export interface FinalizeOptions {
+    batch?: string;
+    requestId?: string;
+    outcome?: string;
+    error?: string;
+    allStale?: boolean;
+    project?: string;
+    sessionId?: string;
+    json?: boolean;
+}
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export declare function selectFinalizeTarget(candidates: readonly FinalizeCandidate[]): FinalizeCandidate | null;
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export declare function describeFinalizeRejection(candidate: FinalizeCandidate, chosen: FinalizeCandidate | null): string;

package/dist/cli/commands/finalize-selection.js

@@ -0,0 +1,35 @@
+/**
+ * The pure `--request-id` selection contract for `peaks sub-agent finalize`, plus
+ * the option shape the command registers. Extracted from `share-commands.ts` so
+ * that file stays under the line cap; these are the pieces the finalize tests
+ * import directly, and none of them touches the filesystem.
+ */
+/** The one selection rule `--request-id` and `--batch` now share. */
+export const FINALIZE_SELECTION_RULE = 'prefer status=queued; among those, newest by record createdAt (then filename); ' +
+    'no queued match means nothing is finalized';
+/**
+ * N3 — pick the record `finalize --request-id` should act on.
+ *
+ * The branch this replaces `break`ed on the FIRST file whose record carried
+ * the requestId and never looked at `status`. With a re-dispatched request
+ * always resolved to the OLDEST one — the already-`done` RD record — so
+ * finalizing reported success while the newer `queued` QA record stayed
+ * queued forever. `--batch` never had that bug: it filters on `queued`.
+ *
+ * Both branches are now the same rule. Return `null` when nothing is queued:
+ * a record that already left `queued` is precisely the one that must NOT be
+ * re-finalized, so the caller reports the survivors instead of touching one.
+ */
+export function selectFinalizeTarget(candidates) {
+    const queued = candidates.filter((candidate) => candidate.status === 'queued');
+    if (queued.length === 0)
+        return null;
+    return [...queued].sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.recordPath.localeCompare(a.recordPath))[0];
+}
+/** Why a candidate was not the chosen one — reported, never guessed at. */
+export function describeFinalizeRejection(candidate, chosen) {
+    if (candidate.status !== 'queued' || chosen === null) {
+        return 'status is ' + candidate.status;
+    }
+    return 'superseded by the newer queued record ' + chosen.recordPath;
+}

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

@@ -1,5 +1,4 @@
 /**
- * v2.14.0 G1 AC-1.4 — `peaks fixture capture` CLI surface.
  *
  * Producer-side CLI for the G1 fixture-replay anti-fake-green test
  * suite. Captures a real envelope artifact from
@@ -16,7 +15,6 @@
  *                        --out tests/fixtures/replay
  *
  * Why a CLI (not just a service function):
- *   - AC-1.4 mandates the CLI as the producer. A1.4 honesty test:
  *     every fixture under `tests/fixtures/replay/` MUST have a
  *     `producer: 'peaks-fixture-capture-cli'` in its `fixture.meta.json`
  *     and a `capturedAt` timestamp within a window where the CLI was

package/dist/cli/commands/fresh-context-commands.d.ts

@@ -1,6 +1,5 @@
 /**
  * `peaks fresh-context preflight` CLI — deterministic trigger scan for the
- * search-first preflight (slice 2026-09-07-search-first-preflight).
  *
  * This command is the shared, deterministic surface every peaks-* orchestrator
  * calls at orchestration-start, BEFORE the first planning action, to decide

package/dist/cli/commands/gate-commands-enforce.d.ts

@@ -38,7 +38,6 @@ export declare function resolveToolMatcher(parsedStdin: unknown): string;
  * call was denied (a hard block has already been emitted and the handler must stop) and `false`
  * when the flow should continue to the SOP gate. `Other` tool kinds are not gated at all.
  *
- * 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
@@ -62,7 +61,6 @@ export declare function emitAllowSkipped(io: ProgramIO, options: GateEnforceCliO
 /** Worktree gate allowed and this is not a Bash surface — allow without running the SOP gate. */
 export declare function emitAllowWorktree(io: ProgramIO, options: GateEnforceCliOptions): void;
 /**
- * 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
@@ -74,7 +72,6 @@ export declare function emitSopWarnings(io: ProgramIO, decision: SopAllow): void
 /**
  * SOP gate allowed the command. --json mode emits 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).
  */

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

@@ -87,7 +87,6 @@ function normalizeLeaseId(value) {
  * tool input — only "worktree" isolation is gated. For all other tool kinds the worktree gate is a
  * no-op.
  *
- * 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
@@ -113,7 +112,6 @@ function buildWorktreeAuthInput(options, toolKind, command, parsedStdin) {
  * call was denied (a hard block has already been emitted and the handler must stop) and `false`
  * when the flow should continue to the SOP gate. `Other` tool kinds are not gated at all.
  *
- * 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
@@ -171,7 +169,6 @@ export function emitAllowWorktree(io, options) {
     }
 }
 /**
- * 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
@@ -194,7 +191,6 @@ export function emitSopWarnings(io, decision) {
 /**
  * SOP gate allowed the command. --json mode emits 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).
  */

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

@@ -4,6 +4,7 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { emitHint } from '../../services/hooks/output.js';
 import { parseClaudeShapeStdin } from '../../services/ide/hook-translator.js';
 import { classifyTool, emitAllowSkipped, emitAllowWorktree, emitSopAllow, emitSopDeny, emitSopWarnings, handleWorktreeGate, parseHookStdin, resolveToolMatcher } from './gate-commands-enforce.js';
+import { handleMcpSurfaceGate } from '../../services/hooks/mcp-surface-gate.js';
 export function registerGateCommands(program, io) {
     const gate = program
         .command('gate')
@@ -36,14 +37,12 @@ async function readHookPayload() {
     });
 }
 /**
- * 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
@@ -55,6 +54,19 @@ function exitWhenRealCliHook() {
         process.exit(process.exitCode || 0);
     }
 }
+/** Read the payload's surface out of the tool name, the adapter's matcher and the command. */
+function classifySurface(parsedStdin) {
+    const toolMatcher = resolveToolMatcher(parsedStdin);
+    const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
+    const toolKind = classifyTool(toolName);
+    const isBash = toolName === toolMatcher && typeof command === 'string' && command.trim().length > 0;
+    return {
+        toolKind,
+        command,
+        bashCommand: isBash ? command : null,
+        isWorktreeToolSurface: toolKind === 'Agent' || toolKind === 'EnterWorktree'
+    };
+}
 /**
  * Body of the `gate enforce` PreToolUse handler. The worktree-then-SOP ordering and every early
  * return / exit-code path are documented on the helpers this delegates to in `gate-commands-enforce`.
@@ -65,23 +77,27 @@ async function runGateEnforceAction(io, options) {
     try {
         const raw = await readHookPayload();
         const parsedStdin = parseHookStdin(raw);
-        const toolMatcher = resolveToolMatcher(parsedStdin);
-        const { toolName, command } = parseClaudeShapeStdin(parsedStdin);
-        const toolKind = classifyTool(toolName);
-        const isBashSurface = toolName === toolMatcher && typeof command === 'string' && command.trim().length > 0;
-        const isWorktreeToolSurface = toolKind === 'Agent' || toolKind === 'EnterWorktree';
-        if (!isBashSurface && !isWorktreeToolSurface) {
+        // The MCP branch runs FIRST and is fail-CLOSED, so it must not sit behind
+        // the "not a guarded surface" early return below — an MCP tool name matches
+        // neither the Bash matcher nor a worktree tool, so everything after this
+        // point would wave it through. A block here has already been emitted.
+        if (handleMcpSurfaceGate(io, parsedStdin)) {
+            return;
+        }
+        const surface = classifySurface(parsedStdin);
+        const { toolKind, command } = surface;
+        if (surface.bashCommand === null && !surface.isWorktreeToolSurface) {
             emitAllowSkipped(io, options);
             return;
         }
         if (handleWorktreeGate(io, options, toolKind, { command, parsedStdin })) {
             return;
         }
-        if (!isBashSurface) {
+        if (surface.bashCommand === null) {
             emitAllowWorktree(io, options);
             return;
         }
-        const decision = await enforceBashCommand(options.project, command);
+        const decision = await enforceBashCommand(options.project, surface.bashCommand);
         if (decision.decision === 'deny') {
             emitSopDeny(io, options, decision);
             return;

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

@@ -1,5 +1,4 @@
 /**
- * rid-007 Family 1 merge: contract-commands + classify-classify-commands.
  *
  * Pre-merge originals (now deleted):
  *   - src/cli/commands/contract-commands.ts     (167 lines)
@@ -10,10 +9,8 @@
  * 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 type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';

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

@@ -1,5 +1,4 @@
 /**
- * rid-007 Family 1 merge: contract-commands + classify-classify-commands.
  *
  * Pre-merge originals (now deleted):
  *   - src/cli/commands/contract-commands.ts     (167 lines)
@@ -10,10 +9,8 @@
  * 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
@@ -76,7 +73,6 @@ export function registerContractCommands(program, io) {
         .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) ??

package/dist/cli/commands/heartbeat-commands-action.js

@@ -27,7 +27,6 @@ import { appendHeartbeat, setStage, tryAutoReleaseLease } from '../../services/d
 import { assertSafeDispatchRecordPath } from '../../services/security/safe-settings-path.js';
 import { writeLogEntry } from '../../services/log/logger.js';
 import { failHeartbeat, heartbeatErrorCode, heartbeatErrorNextActions, resolveHeartbeatStage, validateHeartbeatArguments } from './heartbeat-commands-validation.js';
-// Slice 2026-07-29-worktree-l2-extended Part 3.A.2: the statuses that end a
 // dispatch. Hoisted out of the action body — a constant set is the same set on
 // every call, and its position in the sequence (after printResult) is unchanged.
 const TERMINAL_HEARTBEAT_STATUSES = new Set([
@@ -37,7 +36,6 @@ const TERMINAL_HEARTBEAT_STATUSES = new Set([
     'no-execution'
 ]);
 /**
- * Slice 2026-07-29-worktree-l2-extended Part 24: the heartbeat envelope
  * surfaces a `leaseHint` field when the dispatch owns a lease. The hint is a
  * one-line reminder for the sub-agent that the lease is the L2 surface it
  * should clean up before exiting (or, per Part 3.A.2, the auto-release hook
@@ -53,7 +51,6 @@ function leaseHintFor(result) {
 /** The success envelope's payload, field for field, exactly as the CLI printed it. */
 function heartbeatSuccessEnvelope(recordPath, result) {
     return {
-        // Slice 2026-06-23-audit-4th #E1: envelopeVersion marker
         // Part 24: bumped to 2.2.0 to advertise the new `leaseHint`
         // field; readers from 2.1.0 ignore the unknown field.
         envelopeVersion: '2.2.0',
@@ -66,7 +63,6 @@ function heartbeatSuccessEnvelope(recordPath, result) {
     };
 }
 /**
- * Slice 2026-07-29-worktree-l2-extended Part 3.A.2: when the heartbeat reports
  * a TERMINAL status (done / failed / cancelled / no-execution) AND the dispatch
  * owns a lease, fire the detached release. This is the common path: most
  * sub-agents finalize via heartbeat before the share-reducer calls
@@ -91,7 +87,6 @@ function releaseLeaseForTerminalHeartbeat(trustedRoot, status, result) {
         }
     }
 }
-/** Slice 2026-06-23-audit-4th #B1: structured log on success. */
 function logHeartbeatSuccess(recordPath, result) {
     try {
         writeLogEntry({
@@ -158,7 +153,6 @@ export function runHeartbeatAction(io, options) {
         return;
     }
     try {
-        // R-2 guard (slice 2026-06-23-audit-3rd): trust --project or process.cwd(),
         // NOT the --record path. deriveProjectRoot(recordPath) walked the path
         // itself, which let an attacker point --record at any other project's
         // .peaks/_sub_agents/ tree and slip past the guard. The relative()

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

@@ -38,7 +38,6 @@ export declare function failHeartbeat(io: ProgramIO, f: {
  */
 export declare function validateHeartbeatArguments(io: ProgramIO, asJson: boolean, options: HeartbeatActionOptions, recordPath: string): HeartbeatArgumentsCheck;
 /**
- * Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.2) — validate the
  * optional `--stage` against the bounded enum BEFORE the heartbeat write so the
  * caller gets a specific `INVALID_STAGE` error rather than a generic
  * `HEARTBEAT_ERROR`. An absent or empty flag is not an error: it yields
@@ -48,7 +47,6 @@ export declare function validateHeartbeatArguments(io: ProgramIO, asJson: boolea
  */
 export declare function resolveHeartbeatStage(io: ProgramIO, asJson: boolean, options: HeartbeatActionOptions, recordPath: string): HeartbeatStageCheck;
 /**
- * Slice 2026-06-23-audit-3rd #9: branch nextActions on `error.code` so
  * the LLM-side runner gets a specific hint instead of the generic
  * "see error message" fallback.
  */

package/dist/cli/commands/heartbeat-commands-validation.js

@@ -69,7 +69,6 @@ export function validateHeartbeatArguments(io, asJson, options, recordPath) {
     return { ok: true, progress };
 }
 /**
- * Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.2) — validate the
  * optional `--stage` against the bounded enum BEFORE the heartbeat write so the
  * caller gets a specific `INVALID_STAGE` error rather than a generic
  * `HEARTBEAT_ERROR`. An absent or empty flag is not an error: it yields
@@ -95,7 +94,6 @@ export function resolveHeartbeatStage(io, asJson, options, recordPath) {
     return { ok: true, stage: stageLabel };
 }
 /**
- * Slice 2026-06-23-audit-3rd #9: branch nextActions on `error.code` so
  * the LLM-side runner gets a specific hint instead of the generic
  * "see error message" fallback.
  */

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

@@ -1,7 +1,6 @@
 /**
  * `peaks sub-agent heartbeat` — G6: append a heartbeat to a dispatch record.
  *
- * Pulled out of `sub-agent-commands.ts` (slice 2026-06-23-audit-p0-split)
  * to honor the 800-line file cap. The heartbeat is fire-and-forget; the
  * parent Dispatcher polls the record during the batch-sync wait and
  * renders a status line. Sub-agents should call this at least every

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

@@ -11,7 +11,6 @@ export function registerHeartbeatCommand(parent, io) {
         .requiredOption('--status <state>', 'queued | running | finalizing | done | failed | stale | cancelled | no-execution | never-started | unreadable')
         .requiredOption('--progress <pct>', 'integer 0-100')
         .option('--note <text>', 'free-form progress note (≤ 200 chars)')
-        // Slice 2026-07-29-dispatch-stall-governance / S5 (AC-5.2) —
         // optional --stage flag. The label is bounded (see
         // src/services/dispatch/stage-enum.ts); an unknown value is
         // rejected with INVALID_STAGE so the watch surface never

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

@@ -76,7 +76,6 @@ function listExpectedEntriesForIde(ide, _skipProgress = false) {
         .map((entry) => ({ matcher: entry.matcher, sentinel: entry.sentinel }));
 }
 /**
- * Slice 2026-07-24-peaks-code-bridge-002-rootcause (G6b / G10): copy the
  * superpowers-bridge hook source from the peaks-loop repo
  * (src/services/hooks/pre-tool-superpowers-bridge.sh) into the user-global
  * `<userHome>/.claude/skills/peaks-code/hooks/` directory. The user-global
@@ -102,7 +101,6 @@ function listExpectedEntriesForIde(ide, _skipProgress = false) {
  * it without forcing the caller to inspect the filesystem.
  */
 /**
- * Slice 2026-07-29-worktree-layer3-deny: read the on-disk
  * `permissions.deny` block from a settings.json object and return
  * every peaks-managed entry currently present. Used by `hooks status`
  * to surface Layer 3 governance state without forcing the caller to
@@ -159,7 +157,6 @@ function copyBridgeHookIfPresent(userHome, dryRun = false) {
     return { copied: true, source, target };
 }
 /**
- * Slice 2026-08-06-codegate-vendor-neutral: copy the code-gate hook
  * source (`src/services/hooks/pre-tool-code-gate.sh`) into the user-
  * global peaks-code hooks dir, mirroring the bridge-hook copy. The
  * hook itself is vendor-neutral (no `claude` / `anthropic` strings in
@@ -206,7 +203,6 @@ export function registerHooksCommands(program, io) {
                 const bridgeCopy = scope === 'global'
                     ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '', true)
                     : { copied: false, source: '', target: '' };
-                // Slice 2026-08-06-codegate-vendor-neutral: also copy the
                 // code-gate hook script. The runtime gate lives at
                 // `peaks code-gate --json` (registered as a PreToolUse entry
                 // in the install output); the script is the build artifact
@@ -223,7 +219,6 @@ export function registerHooksCommands(program, io) {
                     entries: dryRunEntries,
                     bridgeHookCopy: bridgeCopy,
                     codeGateHookCopy: codeGateCopy,
-                    // Slice 2026-07-29-worktree-layer3-deny: surface the
                     // Layer 3 deny entries the install WOULD write. The
                     // dry-run branch never actually invokes
                     // `applyHookInstall`, so the on-disk snapshot is not
@@ -250,7 +245,6 @@ export function registerHooksCommands(program, io) {
             // claude-code default). The summary is derived from the install's own
             // entry table — see `listExpectedEntriesForIde`.
             const installedEntries = listExpectedEntriesForIde(ide, skipProgress);
-            // Slice 2026-07-24-peaks-code-bridge-002-rootcause (G6b / G10): when
             // the install targets global scope, also copy the superpowers-bridge
             // hook script from src/services/hooks/ to the user-global hooks
             // directory. Project scope does not need this — project's
@@ -258,7 +252,6 @@ export function registerHooksCommands(program, io) {
             const bridgeCopy = scope === 'global'
                 ? copyBridgeHookIfPresent(process.env.USERPROFILE ?? process.env.HOME ?? '')
                 : { copied: false, source: '', target: '' };
-            // Slice 2026-08-06-codegate-vendor-neutral: also copy the
             // code-gate hook script. The runtime gate lives at
             // `peaks code-gate --json` (registered as a PreToolUse entry
             // in the install output); the script is the build artifact
@@ -270,14 +263,12 @@ export function registerHooksCommands(program, io) {
                 ? [
                     'Restart the IDE (or reload the workspace) so the hook entries take effect',
                     `Installed: ${installedEntries.map((e) => `${e.matcher}→${e.sentinel}`).join(', ')}`,
-                    // Slice 2026-07-29-worktree-layer3-deny: surface L3 deny
                     // write alongside the hook install — single atomic write.
                     `Layer 3 deny: wrote ${listSuperpowersDenyEntries().length} permissions.deny entries (worktree governance)`,
                     describeHookCopy('bridge hook', bridgeCopy, scope, false),
                     describeHookCopy('code-gate hook', codeGateCopy, scope, false)
                 ].filter((line) => line !== null)
                 : [describeHookCopy('bridge hook', bridgeCopy, scope, false)].filter((line) => line !== null);
-            // Slice 2026-07-29-worktree-layer3-deny: emit L3 deny bookkeeping
             // in the JSON envelope so downstream automation (audit / sc) can
             // confirm Layer 3 was applied without re-reading the file. When
             // the install is a no-op (`applied: false`) the deny block was
@@ -313,7 +304,6 @@ export function registerHooksCommands(program, io) {
         const ide = resolveIdeForCommand(options, projectRoot);
         try {
             const result = removeHookInstall(scope, projectRoot, { ide });
-            // Slice 2026-07-29-worktree-layer3-deny: surface L3 deny removal
             // bookkeeping. `permissionsDenyRemoved` mirrors `removed` (the
             // service strips deny entries on the same atomic write that
             // strips the hook entries; they share the same boolean).
@@ -358,7 +348,6 @@ export function registerHooksCommands(program, io) {
             const localSettings = status.localSettingsPath !== undefined && existsSync(status.localSettingsPath)
                 ? readJsonObjectFile(status.localSettingsPath)
                 : {};
-            // Slice 2026-07-29-worktree-layer3-deny: report the Layer 3 deny
             // entries actually on disk. We read the existing settings.json
             // (above) and surface its `permissions.deny` block. Any entry
             // that matches the current `SUPERPOWERS_DENIED_SKILLS` set is

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

@@ -1,5 +1,4 @@
 /**
- * peaks ide * CLI (Slice 2026-07-09 add-zcode-adapter, Slice C).
  *
  * Slice C adds ONE verb:
  *

package/dist/cli/commands/job-add-slice-command.d.ts

@@ -1,5 +1,4 @@
 /**
- * rid 2026-10-03-job-ledger-truthfulness (D1) — `peaks job add-slice`.
  *
  * THE DEFECT. A job's slice list was decided once, at
  * `peaks job init --slice-list <one id>`, and no subcommand could add to it. The
@@ -9,7 +8,6 @@
  *
  *   peaks job add-slice …                          → error: unknown command 'add-slice'
  *   peaks job checkpoint --slice-id <new slice>    → ok:false  code:SLICE_NOT_FOUND
- *   peaks job progress --job-id 2026-10-02-c-wave9 → { done: 1, total: 1 }  (stuck)
  *
  * so a wave that plans its next slice only after the previous one lands — which is
  * how every split wave here runs — had no truthful way to record what it did. It

package/dist/cli/commands/job-add-slice-command.js

@@ -1,5 +1,4 @@
 /**
- * rid 2026-10-03-job-ledger-truthfulness (D1) — `peaks job add-slice`.
  *
  * THE DEFECT. A job's slice list was decided once, at
  * `peaks job init --slice-list <one id>`, and no subcommand could add to it. The
@@ -9,7 +8,6 @@
  *
  *   peaks job add-slice …                          → error: unknown command 'add-slice'
  *   peaks job checkpoint --slice-id <new slice>    → ok:false  code:SLICE_NOT_FOUND
- *   peaks job progress --job-id 2026-10-02-c-wave9 → { done: 1, total: 1 }  (stuck)
  *
  * so a wave that plans its next slice only after the previous one lands — which is
  * how every split wave here runs — had no truthful way to record what it did. It

package/dist/cli/commands/job-checkpoint-commands.d.ts

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