peaks-loop 4.1.2 → 4.1.4

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

@@ -0,0 +1,115 @@
+// Split out of `request-commands.ts`: the two
+// best-effort hooks attached to a completed `peaks request transition` — the
+// rd→qa pre-compact checkpoint + codegraph refresh, and the prd→handed-off
+// handoff auto-regen envelope.
+import { ok } from 'peaks-loop-shared/result';
+import { codegraphRefreshNotice, refreshCodegraphAfterSlice } from '../../services/codegraph/codegraph-autorefresh.js';
+import { triggerBestPracticeScan } from '../../services/prd/best-practice-auto-trigger.js';
+const NO_HOOKS = {
+    preCompact: null,
+    codegraphRefresh: null,
+    codegraphWarning: null
+};
+/**
+ * The RD → QA slice-complete boundary. Set only for rd:qa-handoff; null
+ * otherwise. Best-effort and fail-silent — never blocks the transition.
+ *
+ * When transitioning across the RD → QA boundary (rd:qa-handoff), check the
+ * active session's context-fill ratio. If it is in the 0.85–0.95 pre-compact
+ * zone, write a checkpoint BEFORE the transition completes and attach
+ * `preCompactCheckpoint: true` to the response envelope. The LLM remains the
+ * decision-maker; this hook only surfaces the signal. At ratio ≥ 0.95 the
+ * auto-compact orchestrator ASKS the harness to compact and reports that it is
+ * waiting; it does not refuse anything, because peaks-loop has no executor for
+ * a running session and a refusal it cannot enforce only deadlocked the runner.
+ *
+ * A2 (2026-09-17): never BLOCKING is kept; never VISIBLE is not. A non-refresh
+ * while a codegraph store is in use becomes a warning line beside the
+ * transition's own notes. See `codegraphRefreshNotice` for why
+ * `no-codegraph-dir` stays silent.
+ */
+export async function collectQaHandoffHooks(role, newState, sessionId, project) {
+    if (role !== 'rd' || newState !== 'qa-handoff')
+        return NO_HOOKS;
+    let preCompact = null;
+    let codegraphRefresh = null;
+    try {
+        const { maybePreCompactCheckpoint } = await import('../../services/compact/request-transition-hook.js');
+        const hook = maybePreCompactCheckpoint({
+            projectRoot: project,
+            sessionId,
+            transitionKey: `${role}:${newState}`
+        });
+        preCompact = hook.triggered ? ok('request.transition.preCompact', hook) : null;
+    }
+    catch {
+        // The hook is best-effort; never block the transition.
+        preCompact = null;
+    }
+    try {
+        codegraphRefresh = await refreshCodegraphAfterSlice(project);
+    }
+    catch {
+        // The refresh is best-effort; never block the transition.
+        codegraphRefresh = {
+            refreshed: false,
+            reason: 'unavailable',
+            note: 'auto codegraph refresh failed after transition'
+        };
+    }
+    return {
+        preCompact,
+        codegraphRefresh,
+        codegraphWarning: codegraphRefreshNotice(codegraphRefresh)
+    };
+}
+/**
+ * Only fires when the handoff is missing; existing handoffs are not
+ * overwritten. Post-step after peaks-prd's businessGoal artifact transitions to
+ * `handed-off` (the canonical "complete" state in the prd state machine). The
+ * trigger is fire-and-forget: failure NEVER blocks the transition.
+ */
+export async function buildPrdHandoffResult(ctx) {
+    const { role, newState, requestId, options, result } = ctx;
+    if (role !== 'prd' || newState !== 'handed-off' || options.sessionId === undefined) {
+        return null;
+    }
+    const { autoRegenPrdHandoff } = await import('../../services/prd/handoff-auto-regen.js');
+    const regen = await autoRegenPrdHandoff({
+        projectRoot: options.project,
+        sessionId: result.sessionId,
+        requestId,
+        role: 'prd'
+    });
+    const bpsTrigger = await triggerBestPracticeScan({
+        projectRoot: options.project,
+        sessionId: result.sessionId,
+        requestId
+    });
+    const handoffAutoRegen = regen.status === 'created'
+        ? { status: 'created', path: regen.path, sha256: regen.sha256 }
+        : regen.status === 'skipped-exists'
+            ? { status: 'skipped-exists', path: regen.path }
+            : { status: 'failed', reason: regen.reason };
+    const notes = [];
+    if (regen.status === 'failed') {
+        notes.push(`prd handoff auto-regen failed: ${regen.reason}`);
+    }
+    if (bpsTrigger.status === 'failed') {
+        notes.push(`best-practice-scan auto-trigger failed: ${bpsTrigger.reason ?? 'unknown'}`);
+    }
+    return ok('request.transition', { ...result, handoffAutoRegen, bestPracticeScanTrigger: bpsTrigger }, notes);
+}
+/**
+ * The pre-compact signal rendered into the final envelope's `nextActions`.
+ * `null` when the hook did not trigger (zone is not pre-compact OR the
+ * transition is not a slice boundary).
+ */
+export function preCompactNote(preCompact) {
+    if (preCompact === null)
+        return null;
+    const ratio = typeof preCompact.data === 'object' && preCompact.data !== null && 'ratio' in preCompact.data
+        ? String(preCompact.data.ratio)
+        : 'unknown';
+    return `Pre-compact checkpoint written at ratio=${ratio} (zone=pre-compact)`;
+}

package/dist/cli/commands/request-transition-preflight.d.ts

@@ -0,0 +1,10 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type RequestArtifactRole } from '../../services/artifacts/request-artifact-service.js';
+import type { RequestTransitionOptions } from './request-command-options.js';
+export type TransitionPreflight = {
+    proceed: true;
+    resolvedSessionId: string | undefined;
+} | {
+    proceed: false;
+};
+export declare function runTransitionPreflight(io: ProgramIO, requestId: string, role: RequestArtifactRole, options: RequestTransitionOptions): Promise<TransitionPreflight>;

package/dist/cli/commands/request-transition-preflight.js

@@ -0,0 +1,107 @@
+// Split out of `request-commands.ts`: the
+// pre-transition refusals `peaks request transition` runs before it touches an
+// artifact — session-id resolution, the `--allow-incomplete` reason rule, and
+// the assisted/strict-mode bypass gate.
+import { join } from 'node:path';
+import { fail } from 'peaks-loop-shared/result';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+import { printResult } from '../cli-helpers.js';
+import { isBypassLimitReached, recordBypass, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
+import { showRequestArtifact } from '../../services/artifacts/request-artifact-service.js';
+function refuseInvalidSession(io, options, resolvedSessionId) {
+    printResult(io, fail('request.transition', 'INVALID_SESSION_ID', `Invalid session id: ${resolvedSessionId} (must be a single path segment)`, { provided: resolvedSessionId }, ['Pass a session id that is a single path segment']), options.json);
+    process.exitCode = 1;
+}
+/**
+ * Resolve the artifact's real session up front. Falling back to a literal
+ * 'default' (the previous behavior) points the bypass counter at a
+ * non-existent .peaks/default/ dir and crashes with ENOENT, so when
+ * --session-id is omitted we look the artifact up to find its session.
+ * Returns `null` when a refusal was printed.
+ */
+async function resolveTransitionSessionId(io, requestId, role, options) {
+    let resolvedSessionId = options.sessionId;
+    // Sid axis: either arm of `resolvedSessionId` can be a caller-supplied
+    // `--session-id`, and it is joined into the bypass-counter root below.
+    if (resolvedSessionId !== undefined && isUnsafePathInput(resolvedSessionId)) {
+        refuseInvalidSession(io, options, resolvedSessionId);
+        return null;
+    }
+    if (resolvedSessionId === undefined) {
+        const located = await showRequestArtifact({ projectRoot: options.project, role, requestId });
+        if (located !== null) {
+            resolvedSessionId = located.sessionId;
+        }
+    }
+    return resolvedSessionId;
+}
+function refuseBypassReasonRequired(io, ctx) {
+    printResult(io, fail('request.transition', 'BYPASS_REASON_REQUIRED', '--allow-incomplete requires --reason explaining why prerequisites are skipped', { role: ctx.role, requestId: ctx.requestId }, [
+        'Add --reason "<short justification>" or remove --allow-incomplete and produce the missing artifacts'
+    ]), ctx.options.json);
+    process.exitCode = 1;
+}
+function refuseAllowIncompleteRestricted(io, ctx, mode) {
+    printResult(io, fail('request.transition', 'ALLOW_INCOMPLETE_RESTRICTED', `--allow-incomplete requires --confirm in ${mode} mode`, { role: ctx.role, requestId: ctx.requestId, mode }, [
+        'Ask the user via AskUserQuestion whether to proceed, then re-run with --confirm if they approve.'
+    ]), ctx.options.json);
+    process.exitCode = 1;
+}
+function refuseBypassLimitReached(io, ctx) {
+    printResult(io, fail('request.transition', 'BYPASS_LIMIT_REACHED', `--allow-incomplete limit reached (${MAX_BYPASSES_PER_SESSION} per session)`, { role: ctx.role, requestId: ctx.requestId, limit: MAX_BYPASSES_PER_SESSION }, ['Produce the missing artifacts instead of bypassing.']), ctx.options.json);
+    process.exitCode = 1;
+}
+/**
+ * Restrict --allow-incomplete in assisted/strict modes: require --confirm,
+ * then count the bypass under the canonical session home
+ * `.peaks/_runtime/<sid>/`, NOT `.peaks/_runtime/<sid>/`. The legacy path
+ * landed `.bypass-count.json` at the project root and was ignored only by
+ * `.gitignore`, not by the runtime — a back-compat reader on the root would
+ * never see it. The canonical home is the same one `peaks session info
+ * --active` resolves from `_runtime/session.json`, so all session-scoped state
+ * (artifacts + bypass counter) now lives in one tree.
+ */
+async function applyRestrictedBypassGate(io, ctx) {
+    const { options, resolvedSessionId } = ctx;
+    const { getSkillPresence } = await import('../../services/skills/skill-presence-service.js');
+    const presence = getSkillPresence(options.project);
+    if (!(presence?.mode === 'assisted' || presence?.mode === 'strict'))
+        return true;
+    if (options.confirm !== true) {
+        refuseAllowIncompleteRestricted(io, ctx, presence.mode);
+        return false;
+    }
+    const sessionRoot = join(options.project, '.peaks', '_runtime', resolvedSessionId ?? 'default');
+    if (isBypassLimitReached(sessionRoot)) {
+        refuseBypassLimitReached(io, ctx);
+        return false;
+    }
+    recordBypass(sessionRoot);
+    return true;
+}
+async function checkBypassPreconditions(io, ctx) {
+    const { options } = ctx;
+    if (options.allowIncomplete === true &&
+        (options.reason === undefined || options.reason.trim().length === 0)) {
+        refuseBypassReasonRequired(io, ctx);
+        return false;
+    }
+    if (options.allowIncomplete === true && options.forceConfirm !== true) {
+        return applyRestrictedBypassGate(io, ctx);
+    }
+    return true;
+}
+export async function runTransitionPreflight(io, requestId, role, options) {
+    const resolvedSessionId = await resolveTransitionSessionId(io, requestId, role, options);
+    if (resolvedSessionId === null)
+        return { proceed: false };
+    const allowed = await checkBypassPreconditions(io, {
+        requestId,
+        role,
+        options,
+        resolvedSessionId
+    });
+    if (!allowed)
+        return { proceed: false };
+    return { proceed: true, resolvedSessionId };
+}

package/dist/cli/commands/scan-command-shared.d.ts

@@ -0,0 +1,96 @@
+import { type RequestType } from '../../services/artifacts/artifact-prerequisites.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export type ArchetypeOptions = {
+    project: string;
+    json?: boolean;
+};
+export type ExistingSystemOptions = {
+    project: string;
+    maxTokens?: string;
+    maxSamples?: string;
+    json?: boolean;
+};
+export type RequestTypeSanityOptions = {
+    project: string;
+    type: RequestType;
+    baseRef?: string;
+    json?: boolean;
+};
+export type FileSizeScanOptions = {
+    project: string;
+    baseRef?: string;
+    threshold?: string;
+    json?: boolean;
+};
+export type ScanLibrariesOptions = {
+    project: string;
+    json?: boolean;
+};
+export type AcceptanceCoverageOptions = {
+    rid: string;
+    project: string;
+    sessionId?: string;
+    json?: boolean;
+};
+export type DiffVsScopeOptions = {
+    rid: string;
+    project: string;
+    sessionId?: string;
+    baseRef?: string;
+    json?: boolean;
+};
+/** `--format` accepts exactly these two values across the report subcommands. */
+export type ScanOutputFormat = 'md' | 'json';
+export type ApiSurfaceOptions = {
+    project: string;
+    format?: ScanOutputFormat;
+    includeDirs?: string;
+    maxPerKind?: number;
+    json?: boolean;
+};
+export type OrphanScope = 'working-tree' | 'git-diff' | 'all';
+export type OrphanOptions = {
+    project: string;
+    format?: ScanOutputFormat;
+    scope?: OrphanScope;
+    strict?: boolean;
+    json?: boolean;
+};
+export type KarpathyScope = 'working-tree' | 'all';
+export type KarpathyOptions = {
+    project: string;
+    format?: ScanOutputFormat;
+    scope?: KarpathyScope;
+    json?: boolean;
+};
+export declare function parsePositiveInt(value: string | undefined, fallback: number): number;
+export declare function parseOptionalNonNegativeInt(value: string | undefined): number | undefined;
+export declare function parseRequestType(value: string): RequestType;
+export declare function parseScanOutputFormat(value: string): ScanOutputFormat;
+export declare function parseNonNegativeIntOption(value: string): number;
+export declare function parseOrphanScope(value: string): OrphanScope;
+export declare function parseKarpathyScope(value: string): KarpathyScope;
+/**
+ * Everything `emitScanReport` needs. `renderMarkdown` is a thunk because the
+ * original callbacks built the markdown at this exact point in the flow — after
+ * the `--format json` branches have returned — and it must stay lazy so a
+ * `--format json` run never renders markdown it would throw away.
+ */
+export type ScanReportOutput = {
+    command: string;
+    format?: ScanOutputFormat | undefined;
+    json?: boolean | undefined;
+    report: unknown;
+    nextActions: string[];
+    renderMarkdown: () => string;
+};
+/**
+ * The output contract shared by `scan api-surface`, `scan orphan` and
+ * `scan karpathy`:
+ *   - `--format json` without `--json` writes the bare report (no envelope);
+ *   - `--format json` with `--json` writes the ok/data/code envelope;
+ *   - otherwise markdown goes to stdout, and `--json` wraps it as
+ *     `{ markdown, report }` while the human path prints "Next actions:" to
+ *     stderr only when there is at least one.
+ */
+export declare function emitScanReport(io: ProgramIO, output: ScanReportOutput): void;

package/dist/cli/commands/scan-command-shared.js

@@ -0,0 +1,83 @@
+// Shared plumbing for the `peaks scan` subcommands, extracted from
+// scan-commands.ts so that no single file (or function) has to carry ten
+// subcommands at once. Everything here is parameter-in / value-out: the option
+// shapes each runner receives, the parsers the command definitions hand to
+// Commander as option-processing callbacks, and the two output shapes the
+// report commands share (the format-aware envelope / markdown / raw-JSON
+// writer and its "Next actions:" tail).
+//
+// Dependency direction is one-way: this module never imports scan-commands.ts.
+import { InvalidArgumentError } from 'commander';
+import { ok } from 'peaks-loop-shared/result';
+import { isRequestType, VALID_REQUEST_TYPES } from '../../services/artifacts/artifact-prerequisites.js';
+import { printResult } from '../cli-helpers.js';
+export function parsePositiveInt(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!/^\d+$/.test(value))
+        return fallback;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+export function parseOptionalNonNegativeInt(value) {
+    return value !== undefined && /^\d+$/.test(value) ? Number(value) : undefined;
+}
+export function parseRequestType(value) {
+    if (!isRequestType(value)) {
+        throw new InvalidArgumentError(`must be one of ${VALID_REQUEST_TYPES.join(', ')}`);
+    }
+    return value;
+}
+export function parseScanOutputFormat(value) {
+    if (value !== 'md' && value !== 'json') {
+        throw new InvalidArgumentError('must be md or json');
+    }
+    return value;
+}
+export function parseNonNegativeIntOption(value) {
+    if (!/^\d+$/.test(value)) {
+        throw new InvalidArgumentError('must be a non-negative integer');
+    }
+    return Number(value);
+}
+export function parseOrphanScope(value) {
+    if (value !== 'working-tree' && value !== 'git-diff' && value !== 'all') {
+        throw new InvalidArgumentError('must be working-tree, git-diff, or all');
+    }
+    return value;
+}
+export function parseKarpathyScope(value) {
+    if (value !== 'working-tree' && value !== 'all') {
+        throw new InvalidArgumentError('must be working-tree or all');
+    }
+    return value;
+}
+/**
+ * The output contract shared by `scan api-surface`, `scan orphan` and
+ * `scan karpathy`:
+ *   - `--format json` without `--json` writes the bare report (no envelope);
+ *   - `--format json` with `--json` writes the ok/data/code envelope;
+ *   - otherwise markdown goes to stdout, and `--json` wraps it as
+ *     `{ markdown, report }` while the human path prints "Next actions:" to
+ *     stderr only when there is at least one.
+ */
+export function emitScanReport(io, output) {
+    if (output.format === 'json' && !output.json) {
+        // Raw JSON without the ok/data/code envelope.
+        process.stdout.write(JSON.stringify(output.report, null, 2) + '\n');
+        return;
+    }
+    if (output.format === 'json') {
+        printResult(io, ok(output.command, output.report, [], output.nextActions), output.json);
+        return;
+    }
+    const md = output.renderMarkdown();
+    if (output.json) {
+        printResult(io, ok(output.command, { markdown: md, report: output.report }, [], output.nextActions), output.json);
+        return;
+    }
+    process.stdout.write(md + '\n');
+    if (output.nextActions.length > 0) {
+        process.stderr.write('\nNext actions:\n' + output.nextActions.map((a) => '  - ' + a).join('\n') + '\n');
+    }
+}

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

@@ -1,3 +1,4 @@
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
+import type { Command } from 'commander';
+import type { ProgramIO } from '../cli-helpers.js';
+export type { AcceptanceCoverageOptions, ApiSurfaceOptions, ArchetypeOptions, DiffVsScopeOptions, ExistingSystemOptions, FileSizeScanOptions, KarpathyOptions, KarpathyScope, OrphanOptions, OrphanScope, RequestTypeSanityOptions, ScanLibrariesOptions, ScanOutputFormat, ScanReportOutput } from './scan-command-shared.js';
 export declare function registerScanCommands(program: Command, io: ProgramIO): void;