peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/code/emit-handoff.js

@@ -0,0 +1,79 @@
+/**
+ * v3.1.2 Step 11 / final handoff — Size-fear ban.
+ *
+ * Refuses to emit a final handoff while a Job has remaining slices.
+ * Closes the v3.1.0 incident pattern: LLM writes a fake-completion
+ * message at high context-fill before Job mode kicks in.
+ *
+ * Decision tree:
+ *   - job-shape.json missing OR isJob === false  → ALLOW (normal handoff)
+ *   - isJob === true, no state.json              → JOB_NOT_INITIALIZED (LLM
+ *     skipped `peaks job init`)
+ *   - isJob === true, state.json, remaining > 0,
+ *     no --force-under-job                        → JOB_REMAINING_BLOCKED
+ *   - isJob === true, state.json, remaining === 0 → ALLOW (Job done)
+ *   - isJob === true, state.json, remaining > 0,
+ *     --force-under-job                            → ALLOW (override path)
+ *
+ * Karpathy §2 (Simplicity First): ~70 lines, no LLM call, no regex.
+ * Pure read + arithmetic. The CLI wrapper in code-commands.ts
+ * translates the verdict into exit code + JSON envelope.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED } from './job-shape-decision.js';
+export const JOB_NOT_INITIALIZED = 'JOB_NOT_INITIALIZED';
+export const JOB_REMAINING_BLOCKED = 'JOB_REMAINING_BLOCKED';
+function countRemaining(statePath) {
+    let raw;
+    try {
+        raw = readFileSync(statePath, 'utf8');
+    }
+    catch {
+        return Number.NaN;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return Number.NaN;
+    }
+    if (!Array.isArray(parsed.slices))
+        return Number.NaN;
+    return parsed.slices.filter((sl) => sl.status !== 'done' && sl.status !== 'skipped').length;
+}
+function statePath(projectRoot, sessionId, jobId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'state.json');
+}
+export function evaluateEmitHandoff(input) {
+    let decision = null;
+    try {
+        const record = readJobShapeDecision(input.projectRoot, input.sessionId);
+        decision = record.decision;
+    }
+    catch (err) {
+        if (err instanceof JobShapeDecisionError && err.code === JOB_SHAPE_NOT_DECIDED) {
+            return { kind: 'allow-not-job' };
+        }
+        throw err;
+    }
+    if (!decision.isJob)
+        return { kind: 'allow-not-job' };
+    const jobId = input.jobId ?? decision.suggestedJobId;
+    const path = statePath(input.projectRoot, input.sessionId, jobId);
+    if (!existsSync(path)) {
+        return { kind: 'block-not-initialized', code: JOB_NOT_INITIALIZED, jobId };
+    }
+    const remaining = countRemaining(path);
+    if (!Number.isFinite(remaining)) {
+        return { kind: 'block-not-initialized', code: JOB_NOT_INITIALIZED, jobId };
+    }
+    if (remaining === 0) {
+        return { kind: 'allow-done', remaining };
+    }
+    if (input.forceUnderJob === true) {
+        return { kind: 'allow-force-override', remaining };
+    }
+    return { kind: 'block-remaining', code: JOB_REMAINING_BLOCKED, jobId, remaining };
+}

package/dist/services/code/job-shape-decision.d.ts

@@ -0,0 +1,71 @@
+/**
+ * v3.1.1 Step 0.8 — Job-shape decision recorder.
+ *
+ * The CLI is a *recorder and gate*, not a judge. The LLM makes the
+ * semantic call ("is this a Job?") and writes the verdict via
+ * `peaks code detect-job`; this service persists the verdict to
+ * `.peaks/_runtime/<sessionId>/job-shape.json` and refuses downstream
+ * steps that need a decision when the file is missing.
+ *
+ * Karpathy §2 (Simplicity First): ~100 lines, pure validation + fs
+ * writes, NO keyword regex, NO LLM call inside. The LLM is the
+ * source of truth for whether the request is Job-shaped; this file
+ * just enforces that a decision was made at all.
+ *
+ * Decision file lives at `.peaks/_runtime/<sessionId>/job-shape.json`
+ * (sibling of `session.json`, NOT under `job/<jid>/` because no jid
+ * exists yet at the moment of Step 0.8).
+ */
+export type JobStrategy = 'single' | 'rotating';
+export type JobConfidence = 'high' | 'medium' | 'low';
+export interface JobShapeDecision {
+    readonly isJob: boolean;
+    readonly rationale: string;
+    readonly suggestedJobId: string;
+    readonly suggestedStrategy: JobStrategy;
+    readonly confidence: JobConfidence;
+    /** ISO 8601; stamped server-side in `writeJobShapeDecision`. */
+    readonly decidedAt: string;
+}
+export interface JobShapeRecord {
+    readonly sessionId: string;
+    /** sha1 of the user prompt (first 16 hex). */
+    readonly promptHash: string;
+    readonly decision: JobShapeDecision;
+    readonly schemaVersion: 1;
+}
+export declare const JOB_SHAPE_SCHEMA_VERSION: 1;
+export declare const JOB_SHAPE_FILE_NAME = "job-shape.json";
+export declare const JOB_SHAPE_ALREADY_DECIDED: "JOB_SHAPE_ALREADY_DECIDED";
+export declare const JOB_SHAPE_NOT_DECIDED: "JOB_SHAPE_NOT_DECIDED";
+export declare const JOB_SHAPE_INVALID: "JOB_SHAPE_INVALID";
+export declare class JobShapeDecisionError extends Error {
+    readonly code: typeof JOB_SHAPE_NOT_DECIDED | typeof JOB_SHAPE_ALREADY_DECIDED | typeof JOB_SHAPE_INVALID;
+    readonly details?: unknown;
+    constructor(opts: {
+        code: typeof JobShapeDecisionError.prototype.code;
+        message: string;
+        details?: unknown;
+    });
+}
+/** Pure validator; throws on bad input. No fs IO. */
+export declare function validateJobShapeDecision(input: unknown): JobShapeDecision;
+/** Read the canonical record; throws JOB_SHAPE_NOT_DECIDED if absent or malformed. */
+export declare function readJobShapeDecision(projectRoot: string, sessionId: string): JobShapeRecord;
+export interface WriteJobShapeDecisionInput {
+    readonly isJob: boolean;
+    readonly rationale: string;
+    readonly suggestedJobId: string;
+    readonly suggestedStrategy: JobStrategy;
+    readonly confidence: JobConfidence;
+    readonly prompt: string;
+}
+/**
+ * Persist a new decision; refuses overwrite unless `force: true`.
+ * Stamps `decidedAt` server-side via `now` (defaults to `new Date()`)
+ * so the LLM cannot back-date.
+ */
+export declare function writeJobShapeDecision(projectRoot: string, sessionId: string, decision: WriteJobShapeDecisionInput, opts?: {
+    force?: boolean;
+    now?: () => Date;
+}): JobShapeRecord;

package/dist/services/code/job-shape-decision.js

@@ -0,0 +1,151 @@
+/**
+ * v3.1.1 Step 0.8 — Job-shape decision recorder.
+ *
+ * The CLI is a *recorder and gate*, not a judge. The LLM makes the
+ * semantic call ("is this a Job?") and writes the verdict via
+ * `peaks code detect-job`; this service persists the verdict to
+ * `.peaks/_runtime/<sessionId>/job-shape.json` and refuses downstream
+ * steps that need a decision when the file is missing.
+ *
+ * Karpathy §2 (Simplicity First): ~100 lines, pure validation + fs
+ * writes, NO keyword regex, NO LLM call inside. The LLM is the
+ * source of truth for whether the request is Job-shaped; this file
+ * just enforces that a decision was made at all.
+ *
+ * Decision file lives at `.peaks/_runtime/<sessionId>/job-shape.json`
+ * (sibling of `session.json`, NOT under `job/<jid>/` because no jid
+ * exists yet at the moment of Step 0.8).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+export const JOB_SHAPE_SCHEMA_VERSION = 1;
+export const JOB_SHAPE_FILE_NAME = 'job-shape.json';
+export const JOB_SHAPE_ALREADY_DECIDED = 'JOB_SHAPE_ALREADY_DECIDED';
+export const JOB_SHAPE_NOT_DECIDED = 'JOB_SHAPE_NOT_DECIDED';
+export const JOB_SHAPE_INVALID = 'JOB_SHAPE_INVALID';
+const SUGGESTED_JID_RE = /^[a-z0-9][a-z0-9-]{2,40}$/;
+const JobShapeDecisionSchema = z.object({
+    isJob: z.boolean(),
+    rationale: z.string().min(1).max(2000),
+    suggestedJobId: z.string().regex(SUGGESTED_JID_RE, 'suggestedJobId must match /^[a-z0-9][a-z0-9-]{2,40}$/'),
+    suggestedStrategy: z.enum(['single', 'rotating']),
+    confidence: z.enum(['high', 'medium', 'low']),
+    decidedAt: z.string().datetime()
+});
+const JobShapeRecordSchema = z.object({
+    sessionId: z.string().min(1),
+    promptHash: z.string().regex(/^[a-f0-9]{16}$/, 'promptHash must be 16 hex chars'),
+    decision: JobShapeDecisionSchema,
+    schemaVersion: z.literal(JOB_SHAPE_SCHEMA_VERSION)
+});
+export class JobShapeDecisionError extends Error {
+    code;
+    details;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'JobShapeDecisionError';
+        this.code = opts.code;
+        if (opts.details !== undefined)
+            this.details = opts.details;
+    }
+}
+function runtimeDir(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId);
+}
+function decisionPath(projectRoot, sessionId) {
+    return join(runtimeDir(projectRoot, sessionId), JOB_SHAPE_FILE_NAME);
+}
+function sha1Prefix16(input) {
+    return createHash('sha1').update(input, 'utf8').digest('hex').slice(0, 16);
+}
+/** Pure validator; throws on bad input. No fs IO. */
+export function validateJobShapeDecision(input) {
+    return JobShapeDecisionSchema.parse(input);
+}
+function validateRecord(input) {
+    return JobShapeRecordSchema.parse(input);
+}
+/** Read the canonical record; throws JOB_SHAPE_NOT_DECIDED if absent or malformed. */
+export function readJobShapeDecision(projectRoot, sessionId) {
+    const path = decisionPath(projectRoot, sessionId);
+    if (!existsSync(path)) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `No Job-shape decision recorded for session ${sessionId}. Run \`peaks code detect-job\` to record a decision.`,
+            details: { path }
+        });
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `Job-shape decision file is unreadable for session ${sessionId}. Run \`peaks code detect-job\` to re-record.`,
+            details: { path, cause: err instanceof Error ? err.message : String(err) }
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `Job-shape decision file is malformed JSON for session ${sessionId}. Run \`peaks code detect-job --force\` to overwrite.`,
+            details: { path, cause: err instanceof Error ? err.message : String(err) }
+        });
+    }
+    try {
+        return validateRecord(parsed);
+    }
+    catch (err) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `Job-shape decision file is schema-invalid for session ${sessionId}. Run \`peaks code detect-job --force\` to overwrite.`,
+            details: { path, cause: err instanceof Error ? err.message : String(err) }
+        });
+    }
+}
+/**
+ * Persist a new decision; refuses overwrite unless `force: true`.
+ * Stamps `decidedAt` server-side via `now` (defaults to `new Date()`)
+ * so the LLM cannot back-date.
+ */
+export function writeJobShapeDecision(projectRoot, sessionId, decision, opts = {}) {
+    const path = decisionPath(projectRoot, sessionId);
+    if (existsSync(path) && opts.force !== true) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_ALREADY_DECIDED,
+            message: `Job-shape decision already exists for session ${sessionId}. Re-run with --force to overwrite.`,
+            details: { path }
+        });
+    }
+    // Validate the LLM-supplied fields first so a bad call fails loud
+    // before we touch the filesystem.
+    const partial = {
+        isJob: decision.isJob,
+        rationale: decision.rationale,
+        suggestedJobId: decision.suggestedJobId,
+        suggestedStrategy: decision.suggestedStrategy,
+        confidence: decision.confidence
+    };
+    // Validate the LLM-supplied shape (decidedAt is server-stamped).
+    JobShapeDecisionSchema.omit({ decidedAt: true }).parse(partial);
+    const now = opts.now ?? (() => new Date());
+    const stamped = { ...partial, decidedAt: now().toISOString() };
+    const promptHash = sha1Prefix16(decision.prompt);
+    const record = {
+        sessionId,
+        promptHash,
+        decision: stamped,
+        schemaVersion: JOB_SHAPE_SCHEMA_VERSION
+    };
+    const dir = runtimeDir(projectRoot, sessionId);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    return record;
+}

package/dist/services/code/mode-gate.d.ts

@@ -0,0 +1,163 @@
+/**
+ * v2.11.0 Group F (Tier 9) — D5: full-auto self-decision gate.
+ *
+ * Single source of truth for "should this code path auto-proceed or
+ * pause for an AskUserQuestion round-trip?" The D5 design (per
+ * `.peaks/memory/2026-06-26-v2-11-full-auto-self-decision.md`) requires:
+ *
+ *   - `full-auto` and `swarm` modes → auto-proceed (recommended = chosen)
+ *   - `assisted` and `strict` modes → pause for confirmation
+ *   - 3 hard-floor categories ALWAYS ask, regardless of mode:
+ *     1. Irreversible external side effects (git push, npm publish, …)
+ *     2. Authentication / credential usage
+ *     3. Multi-day investment decisions (release tag, breaking change)
+ *
+ * Karpathy §2: no inline `mode === 'full-auto'` checks scattered across
+ * files — this module is the only place. Karpathy §3: this file is
+ * surgical to the D5 design; do not extend with unrelated mode helpers.
+ *
+ * Re-uses `SkillPresenceMode` from `skill-presence-service.ts` so the
+ * 4 mode values stay in lockstep with the rest of the runtime.
+ */
+import type { SkillPresenceMode } from '../skills/skill-presence-service.js';
+export type CodeMode = SkillPresenceMode;
+export declare const CODE_MODES: readonly CodeMode[];
+export type HardFloorCategory = 'irreversible-external-side-effect' | 'authentication-credential' | 'multi-day-investment'
+/**
+ * v2.15.0 slice 002 AC-4: actions that are past the user's
+ * explicit full-auto boundary = commit only. Per user-given rule
+ * from `.peaks/memory/2026-06-28-full-auto-boundary.md`: full-auto
+ * ends at commit. push / tag / npm publish / global install are
+ * commit-BOUNDARY side effects — they extend the commit to an
+ * external system, and full-auto must NOT auto-perform them even
+ * if every other mode says yes. Always pauses.
+ */
+ | 'commit-boundary-side-effect';
+export declare const HARD_FLOOR_CATEGORIES: readonly HardFloorCategory[];
+/**
+ * The 14 SKILL.md AskUserQuestion sites mapped in the D5 memory's
+ * "Inventory of unconditional confirmation gates" table. Each row
+ * is the bare minimum needed to gate it through `shouldPauseAtGate`.
+ */
+export type GatedStepId = 'step-0.5-openspec-opt-in' | 'step-0.6-audit-goal' | 'step-0.7-resume-detection' | 'step-0.55-1x-upgrade' | 'step-1-mode-select' | 'step-2.5-session-title' | 'phase-2-prd-confirm' | 'phase-3-swarm-gate-b' | 'phase-6-qa-gate-d' | 'phase-10-txt-memory-extract' | 'step-n+1-final-review' | 'frontend-only-mismatch' | 'step-0.75-checkpoint-resume' | 'standards-preflight';
+export declare const GATED_STEPS: readonly GatedStepId[];
+/**
+ * Slice 2026-06-28-code-mode-bypass-fix: the kind of gate that
+ * produced this decision. The LLM-side caller (peaks-code body) reads
+ * this to distinguish "you paused because the user must choose the
+ * mode" (`mode-selection-itself`) from "you paused because the mode
+ * you already chose is assisted/strict" (`mode-driven`) from "you
+ * paused because a hard-floor category always wins" (`hard-floor`).
+ *
+ *   - `'mode-selection-itself'` — the gate IS the mode/context
+ *     selection step itself (step-1-mode-select,
+ *     step-0.5-openspec-opt-in, step-0.7-resume-detection). Even
+ *     `full-auto` mode pauses here; otherwise the user's first turn
+ *     would auto-lock the mode without their consent.
+ *   - `'mode-driven'`           — the gate paused because the active
+ *     mode is assisted/strict (the existing default).
+ *   - `'hard-floor'`            — the gate paused because a
+ *     hard-floor category always wins (irreversible external side
+ *     effect / auth / multi-day investment).
+ */
+export type GateKind = 'mode-selection-itself' | 'mode-driven' | 'hard-floor';
+export interface GateDecision {
+    readonly shouldPause: boolean;
+    /** Human-readable rationale; surfaces in `peaks code should-pause --json` */
+    readonly reason: string;
+    /** Hard-floor override applied? Surfaces in audit log when true */
+    readonly hardFloorCategory?: HardFloorCategory;
+    /** Slice 2026-06-28-code-mode-bypass-fix: kind of gate that produced
+     * this decision. Always present; defaults to `'mode-driven'` for the
+     * assisted/strict pause branch. */
+    readonly gateKind: GateKind;
+}
+export declare function isCodeMode(value: string): value is CodeMode;
+export declare function isHardFloorCategory(value: string): value is HardFloorCategory;
+/**
+ * `true` when the current mode should auto-proceed (skip the
+ * AskUserQuestion round-trip). Mirrors D5.a: "recommended = chosen
+ * in full-auto / swarm; always log, never silently skip".
+ */
+export declare function shouldAutoProceed(mode: CodeMode): boolean;
+/**
+ * Should the LLM emit an AskUserQuestion at `step` given `mode`?
+ * Pure function: no IO, no LLM call. The LLM-side caller passes the
+ * mode it loaded from skill presence, and the step it is about to
+ * execute; this function returns a `GateDecision` with the rationale.
+ *
+ * The hard-floor categories always win — even full-auto pauses for
+ * irreversible external side effects, auth/credential usage,
+ * multi-day investment decisions (D5.b), and commit-boundary side
+ * effects (v2.15.0 slice 002 AC-4: push, tag, publish, global install).
+ *
+ * `hardFloorCategory` is optional on the `GateDecision` so callers can
+ * stamp the override into the auto-decisions log without a second
+ * switch.
+ */
+/**
+ * v2.15.0 slice 002 AC-4: the 5 action identifiers that qualify as
+ * commit-boundary side effects. Matched by the LLM-side caller
+ * (peaks-code body / peaks-rd fork agent) when it is about to run a
+ * Bash command that maps to one of these. Set `commitBoundaryAction:
+ * true` on the `shouldPauseAtGate` call to trigger the hard-floor
+ * override.
+ */
+export type CommitBoundaryActionId = 'git-push' | 'git-tag' | 'npm-publish' | 'npm-install-global' | 'peaks-global-install';
+export declare const COMMIT_BOUNDARY_ACTIONS: readonly CommitBoundaryActionId[];
+export declare function isCommitBoundaryAction(value: string): value is CommitBoundaryActionId;
+export declare function shouldPauseAtGate(opts: {
+    mode: CodeMode;
+    step: GatedStepId;
+    hardFloorCategory?: HardFloorCategory | undefined;
+    /**
+     * v2.15.0 slice 002 AC-4: when `true`, force a pause regardless of
+     * mode. Reserved for the 5 commit-boundary side effects
+     * (push/tag/publish/global install) that are past the user's
+     * full-auto boundary. The hard-floor override ALWAYS wins — even
+     * over the mode-driven auto-proceed branch.
+     */
+    commitBoundaryAction?: boolean | undefined;
+}): GateDecision;
+/**
+ * Format a one-line audit message for the auto-decisions log.
+ * Karpathy §3: this is a pure formatter; it does NOT touch the file
+ * system. The CLI / LLM is responsible for appending.
+ */
+export declare function formatAutoProceedLogLine(opts: {
+    mode: CodeMode;
+    step: GatedStepId;
+    recommendedOption: string;
+    hardFloorCategory?: HardFloorCategory | undefined;
+}): string;
+/**
+ * v2.15.0 slice 002 AC-4: regex matchers the LLM-side caller uses
+ * to flag a Bash command as a commit-boundary action. Centralised
+ * here so the test seam + the CLI wiring share one source of
+ * truth. Each entry is an anchored pattern matched against the
+ * user-invoked command (after commander / shell normalisation,
+ * before execution).
+ *
+ * Patterns intentionally cover the common canonical forms:
+ *
+ *   - `git-push`            → `git push`, `git push origin main`, `git push --tags`
+ *   - `git-tag`             → `git tag v2.15.0`, `git tag -a v2.15.0 -m ...`
+ *   - `npm-publish`         → `npm publish`, `npm publish --access public`
+ *   - `npm-install-global`  → `npm install -g <pkg>`, `npm i -g <pkg>`
+ *   - `peaks-global-install`→ `npm install -g peaks-loop`, `pnpm add -g peaks-loop`
+ *
+ * These are coarse — false positives are fine (worst case: a
+ * non-actionable command gets paused for confirmation; the user
+ * can confirm in one click). False negatives are NOT fine — a
+ * missed publish would violate the full-auto boundary.
+ */
+export declare const COMMIT_BOUNDARY_PATTERNS: Readonly<Record<CommitBoundaryActionId, RegExp>>;
+/**
+ * v2.15.0 slice 002 AC-4: detect whether a Bash command matches any
+ * commit-boundary action pattern. Returns the action id of the
+ * first match, or `null` when none match. The CLI / LLM caller
+ * passes the command through this function and forwards the
+ * result to `shouldPauseAtGate({ commitBoundaryAction: true })` to
+ * force the hard-floor pause.
+ */
+export declare function detectCommitBoundaryAction(command: string): CommitBoundaryActionId | null;

package/dist/services/code/mode-gate.js

@@ -0,0 +1,212 @@
+/**
+ * v2.11.0 Group F (Tier 9) — D5: full-auto self-decision gate.
+ *
+ * Single source of truth for "should this code path auto-proceed or
+ * pause for an AskUserQuestion round-trip?" The D5 design (per
+ * `.peaks/memory/2026-06-26-v2-11-full-auto-self-decision.md`) requires:
+ *
+ *   - `full-auto` and `swarm` modes → auto-proceed (recommended = chosen)
+ *   - `assisted` and `strict` modes → pause for confirmation
+ *   - 3 hard-floor categories ALWAYS ask, regardless of mode:
+ *     1. Irreversible external side effects (git push, npm publish, …)
+ *     2. Authentication / credential usage
+ *     3. Multi-day investment decisions (release tag, breaking change)
+ *
+ * Karpathy §2: no inline `mode === 'full-auto'` checks scattered across
+ * files — this module is the only place. Karpathy §3: this file is
+ * surgical to the D5 design; do not extend with unrelated mode helpers.
+ *
+ * Re-uses `SkillPresenceMode` from `skill-presence-service.ts` so the
+ * 4 mode values stay in lockstep with the rest of the runtime.
+ */
+export const CODE_MODES = [
+    'full-auto',
+    'assisted',
+    'swarm',
+    'strict'
+];
+export const HARD_FLOOR_CATEGORIES = [
+    'irreversible-external-side-effect',
+    'authentication-credential',
+    'multi-day-investment',
+    'commit-boundary-side-effect'
+];
+export const GATED_STEPS = [
+    'step-0.5-openspec-opt-in',
+    'step-0.6-audit-goal',
+    'step-0.7-resume-detection',
+    'step-0.55-1x-upgrade',
+    'step-1-mode-select',
+    'step-2.5-session-title',
+    'phase-2-prd-confirm',
+    'phase-3-swarm-gate-b',
+    'phase-6-qa-gate-d',
+    'phase-10-txt-memory-extract',
+    'step-n+1-final-review',
+    'frontend-only-mismatch',
+    'step-0.75-checkpoint-resume',
+    'standards-preflight'
+];
+export function isCodeMode(value) {
+    return CODE_MODES.includes(value);
+}
+export function isHardFloorCategory(value) {
+    return HARD_FLOOR_CATEGORIES.includes(value);
+}
+/**
+ * `true` when the current mode should auto-proceed (skip the
+ * AskUserQuestion round-trip). Mirrors D5.a: "recommended = chosen
+ * in full-auto / swarm; always log, never silently skip".
+ */
+export function shouldAutoProceed(mode) {
+    return mode === 'full-auto' || mode === 'swarm';
+}
+export const COMMIT_BOUNDARY_ACTIONS = [
+    'git-push',
+    'git-tag',
+    'npm-publish',
+    'npm-install-global',
+    'peaks-global-install'
+];
+export function isCommitBoundaryAction(value) {
+    return COMMIT_BOUNDARY_ACTIONS.includes(value);
+}
+/**
+ * Hard-pause steps: these pause regardless of mode. They are the gates
+ * whose decision *creates* or *recreates* the mode/state under which
+ * later gates run. Auto-proceeding on them would silently fix the mode
+ * without user consent (defect #1: new Code session skipped Step 1
+ * AskUserQuestion because `full-auto` mode triggered `shouldAutoProceed`
+ * on `step-1-mode-select` itself).
+ *
+ * v2.18.4 slice 002-fix-first-run-step-gates: added
+ * `step-0.55-1x-upgrade`. The 1.x → 2.0 upgrade is an irreversible
+ * external side effect (migration rewrites config files and the
+ * on-disk cache shape) — it must always pause, even in full-auto.
+ * Without this, `full-auto` mode auto-proceeds and silently
+ * downgrades a 1.x install to 2.0 without user consent.
+ */
+const HARD_PAUSE_STEPS = new Set([
+    'step-1-mode-select',
+    'step-0.5-openspec-opt-in',
+    'step-0.7-resume-detection',
+    'step-0.55-1x-upgrade'
+]);
+export function shouldPauseAtGate(opts) {
+    if (opts.hardFloorCategory !== undefined && isHardFloorCategory(opts.hardFloorCategory)) {
+        return {
+            shouldPause: true,
+            reason: `hard-floor category "${opts.hardFloorCategory}" always pauses regardless of mode (D5.b)`,
+            hardFloorCategory: opts.hardFloorCategory,
+            gateKind: 'hard-floor'
+        };
+    }
+    // Slice 002 (v2.15.0) AC-4: commit-boundary side effects override
+    // every other decision. Per the user-given rule in
+    // `.peaks/memory/2026-06-28-full-auto-boundary.md` ("full-auto 只
+    // 做到 commit"), push / tag / npm publish / global install must
+    // AskUserQuestion even in full-auto. This is the mechanical
+    // enforcement of that rule.
+    if (opts.commitBoundaryAction === true) {
+        return {
+            shouldPause: true,
+            reason: 'commit-boundary side effect (push/tag/publish/global-install) → always pause regardless of mode (slice 002 AC-4, full-auto boundary = commit only)',
+            hardFloorCategory: 'commit-boundary-side-effect',
+            gateKind: 'hard-floor'
+        };
+    }
+    // Slice 2026-06-28-code-mode-bypass-fix: hard-pause steps that
+    // determine the active mode or session context MUST prompt the
+    // user. Otherwise full-auto silently locks in `mode=full-auto` on
+    // the first tool call, skipping the AskUserQuestion Step 1 mandates.
+    if (HARD_PAUSE_STEPS.has(opts.step)) {
+        return {
+            shouldPause: true,
+            reason: `step=${opts.step} is a mode/context-selection step → always pause (defect #1 fix)`,
+            gateKind: 'mode-selection-itself'
+        };
+    }
+    if (shouldAutoProceed(opts.mode)) {
+        return {
+            shouldPause: false,
+            reason: `mode=${opts.mode} → recommended = chosen; emit auto-decision log (D5.a)`,
+            gateKind: 'mode-driven'
+        };
+    }
+    return {
+        shouldPause: true,
+        reason: `mode=${opts.mode} → pause for AskUserQuestion (assisted/strict default)`,
+        gateKind: 'mode-driven'
+    };
+}
+/**
+ * Format a one-line audit message for the auto-decisions log.
+ * Karpathy §3: this is a pure formatter; it does NOT touch the file
+ * system. The CLI / LLM is responsible for appending.
+ */
+export function formatAutoProceedLogLine(opts) {
+    if (opts.hardFloorCategory !== undefined && isHardFloorCategory(opts.hardFloorCategory)) {
+        return `auto-pause (${opts.mode}, hard-floor:${opts.hardFloorCategory}): ${opts.step} → ${opts.recommendedOption}`;
+    }
+    return `auto-proceed (${opts.mode}): ${opts.step} → ${opts.recommendedOption}`;
+}
+/**
+ * v2.15.0 slice 002 AC-4: regex matchers the LLM-side caller uses
+ * to flag a Bash command as a commit-boundary action. Centralised
+ * here so the test seam + the CLI wiring share one source of
+ * truth. Each entry is an anchored pattern matched against the
+ * user-invoked command (after commander / shell normalisation,
+ * before execution).
+ *
+ * Patterns intentionally cover the common canonical forms:
+ *
+ *   - `git-push`            → `git push`, `git push origin main`, `git push --tags`
+ *   - `git-tag`             → `git tag v2.15.0`, `git tag -a v2.15.0 -m ...`
+ *   - `npm-publish`         → `npm publish`, `npm publish --access public`
+ *   - `npm-install-global`  → `npm install -g <pkg>`, `npm i -g <pkg>`
+ *   - `peaks-global-install`→ `npm install -g peaks-loop`, `pnpm add -g peaks-loop`
+ *
+ * These are coarse — false positives are fine (worst case: a
+ * non-actionable command gets paused for confirmation; the user
+ * can confirm in one click). False negatives are NOT fine — a
+ * missed publish would violate the full-auto boundary.
+ */
+export const COMMIT_BOUNDARY_PATTERNS = {
+    'git-push': /\bgit\s+push\b/,
+    'git-tag': /\bgit\s+tag\b/,
+    'npm-publish': /\bnpm\s+(publish|pub)\b/,
+    'npm-install-global': /\bnpm\s+(install|i|add)\s+(-g|--global)\b/,
+    'peaks-global-install': /\b(peaks-loop)\b/
+};
+/**
+ * v2.15.0 slice 002 AC-4: detect whether a Bash command matches any
+ * commit-boundary action pattern. Returns the action id of the
+ * first match, or `null` when none match. The CLI / LLM caller
+ * passes the command through this function and forwards the
+ * result to `shouldPauseAtGate({ commitBoundaryAction: true })` to
+ * force the hard-floor pause.
+ */
+export function detectCommitBoundaryAction(command) {
+    if (typeof command !== 'string' || command.length === 0)
+        return null;
+    // Order matters: peaks-global-install is the most specific
+    // (matches only the peaks-loop package name). Test that FIRST so
+    // `npm install -g peaks-loop` is attributed correctly. Then
+    // git-push, git-tag, npm-publish, npm-install-global.
+    if (COMMIT_BOUNDARY_PATTERNS['peaks-global-install'].test(command)) {
+        return 'peaks-global-install';
+    }
+    if (COMMIT_BOUNDARY_PATTERNS['git-push'].test(command)) {
+        return 'git-push';
+    }
+    if (COMMIT_BOUNDARY_PATTERNS['git-tag'].test(command)) {
+        return 'git-tag';
+    }
+    if (COMMIT_BOUNDARY_PATTERNS['npm-publish'].test(command)) {
+        return 'npm-publish';
+    }
+    if (COMMIT_BOUNDARY_PATTERNS['npm-install-global'].test(command)) {
+        return 'npm-install-global';
+    }
+    return null;
+}