peaks-loop 3.0.0

package/dist/src/services/solo/post-compact-detector.d.ts

@@ -0,0 +1,61 @@
+/**
+ * v2.11.0 Group F (Tier 9) — D7: post-compact auto-resume detector.
+ *
+ * Per `.peaks/memory/2026-06-26-v2-11-post-compact-resume.md` §D7.a,
+ * post-compact auto-resume triggers when ALL of the following hold:
+ *
+ *   1. `.peaks/_runtime/<sessionId>/` is bound
+ *   2. Latest checkpoint mtime is from today (UTC date)
+ *   3. Latest checkpoint has a parseable `mode` field
+ *   4. The peak-solo skill is the active skill
+ *   5. Exactly one session has a today's checkpoint (no ambiguity)
+ *
+ * On a hit, the LLM MUST auto-resume (D7.b override of "never silently
+ * auto-resume") and emit a one-line log entry. On any miss, fall
+ * through to the normal Step 0.7 flow.
+ *
+ * Karpathy §3: the detector is the only place that decides "is this
+ * a post-compact resume?" — no inline `isPostCompact()` checks
+ * scattered across SKILL.md or other services.
+ *
+ * IO: readdir + readFile on `.peaks/_runtime/<sid>/checkpoints/`.
+ * No writes (caller logs the decision via the auto-decisions channel).
+ */
+import type { SkillPresenceMode } from '../skills/skill-presence-service.js';
+import { type SoloMode } from './mode-gate.js';
+export type PostCompactResumeReason = 'post-compact-match' | 'sid-unbound' | 'runtime-dir-missing' | 'no-checkpoint-today' | 'no-mode-field' | 'stale-checkpoint' | 'multiple-checkpoints-ambiguous' | 'active-skill-mismatch' | 'checkpoint-read-failed';
+export declare const POST_COMPACT_RESUME_REASONS: readonly PostCompactResumeReason[];
+export interface PostCompactResumeProbe {
+    readonly shouldAutoResume: boolean;
+    readonly reason: PostCompactResumeReason;
+    readonly mode?: SoloMode;
+    readonly checkpointPath?: string;
+    readonly checkpointMtime?: string;
+    readonly task?: string;
+    readonly openQuestions?: readonly string[];
+    readonly recentDecisions?: readonly string[];
+    readonly warnings: readonly string[];
+}
+export interface DetectPostCompactResumeOptions {
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    /** Injectable clock for deterministic tests; defaults to `new Date()`. */
+    readonly now?: (() => Date) | undefined;
+    /** Override the active-skill check (test seam; defaults to read presence). */
+    readonly activeSkill?: string | undefined;
+    /** Override mode read from presence (test seam). */
+    readonly presenceModeOverride?: SkillPresenceMode | undefined;
+}
+/**
+ * Detect whether the current invocation is a same-day post-compact
+ * resume. The LLM-side caller invokes this in Step 0.7 / Step 0.75
+ * after anchoring. Pure-ish: only filesystem reads of the checkpoint
+ * dir; no LLM calls.
+ */
+export declare function detectPostCompactResume(opts: DetectPostCompactResumeOptions): Promise<PostCompactResumeProbe>;
+/**
+ * One-line auto-decisions log entry. Pure formatter; no IO. The LLM
+ * appends to `.peaks/_runtime/<sessionId>/txt/auto-decisions.md` so
+ * the existing audit channel picks it up (D7.e).
+ */
+export declare function formatPostCompactResumeLogLine(probe: PostCompactResumeProbe): string;

package/dist/src/services/solo/post-compact-detector.js

@@ -0,0 +1,240 @@
+/**
+ * v2.11.0 Group F (Tier 9) — D7: post-compact auto-resume detector.
+ *
+ * Per `.peaks/memory/2026-06-26-v2-11-post-compact-resume.md` §D7.a,
+ * post-compact auto-resume triggers when ALL of the following hold:
+ *
+ *   1. `.peaks/_runtime/<sessionId>/` is bound
+ *   2. Latest checkpoint mtime is from today (UTC date)
+ *   3. Latest checkpoint has a parseable `mode` field
+ *   4. The peak-solo skill is the active skill
+ *   5. Exactly one session has a today's checkpoint (no ambiguity)
+ *
+ * On a hit, the LLM MUST auto-resume (D7.b override of "never silently
+ * auto-resume") and emit a one-line log entry. On any miss, fall
+ * through to the normal Step 0.7 flow.
+ *
+ * Karpathy §3: the detector is the only place that decides "is this
+ * a post-compact resume?" — no inline `isPostCompact()` checks
+ * scattered across SKILL.md or other services.
+ *
+ * IO: readdir + readFile on `.peaks/_runtime/<sid>/checkpoints/`.
+ * No writes (caller logs the decision via the auto-decisions channel).
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSkillPresence } from '../skills/skill-presence-service.js';
+import { emitObservabilityEvent } from '../observability/observability-service.js';
+import { isSoloMode } from './mode-gate.js';
+export const POST_COMPACT_RESUME_REASONS = [
+    'post-compact-match',
+    'sid-unbound',
+    'runtime-dir-missing',
+    'no-checkpoint-today',
+    'no-mode-field',
+    'stale-checkpoint',
+    'multiple-checkpoints-ambiguous',
+    'active-skill-mismatch',
+    'checkpoint-read-failed'
+];
+const CHECKPOINTS_DIR = 'checkpoints';
+const CHECKPOINT_EXT = '.json';
+function isToday(d, now) {
+    return (d.getUTCFullYear() === now.getUTCFullYear() &&
+        d.getUTCMonth() === now.getUTCMonth() &&
+        d.getUTCDate() === now.getUTCDate());
+}
+function safeReadCheckpoint(absPath) {
+    try {
+        const stat = statSync(absPath);
+        const raw = readFileSync(absPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const mutable = {};
+        if (typeof parsed['currentPlan'] === 'string') {
+            mutable.currentPlan = parsed['currentPlan'];
+        }
+        if (Array.isArray(parsed['openQuestions'])) {
+            mutable.openQuestions = parsed['openQuestions'].filter((q) => typeof q === 'string');
+        }
+        if (Array.isArray(parsed['recentDecisions'])) {
+            mutable.recentDecisions = parsed['recentDecisions'].filter((d) => typeof d === 'string');
+        }
+        if (typeof parsed['mode'] === 'string') {
+            mutable.mode = parsed['mode'];
+        }
+        const content = mutable;
+        return { path: absPath, mtime: stat.mtime, content };
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function readLatestTodayCheckpoint(runtimeDir, now) {
+    const dir = join(runtimeDir, CHECKPOINTS_DIR);
+    if (!existsSync(dir)) {
+        return { found: 'none' };
+    }
+    const todayFiles = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith(CHECKPOINT_EXT))
+            continue;
+        const abs = join(dir, entry);
+        const file = safeReadCheckpoint(abs);
+        if (file === null)
+            continue;
+        if (isToday(file.mtime, now)) {
+            todayFiles.push(file);
+        }
+    }
+    if (todayFiles.length === 0) {
+        return { found: 'none' };
+    }
+    if (todayFiles.length > 1) {
+        todayFiles.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+        const newest = todayFiles[0];
+        if (newest === undefined) {
+            return { found: 'none' };
+        }
+        const tieCount = todayFiles.filter((f) => f.mtime.getTime() === newest.mtime.getTime()).length;
+        if (tieCount > 1) {
+            return { found: 'multiple', files: todayFiles };
+        }
+        return { found: 'today', file: newest };
+    }
+    const only = todayFiles[0];
+    if (only === undefined) {
+        return { found: 'none' };
+    }
+    return { found: 'today', file: only };
+}
+/**
+ * Detect whether the current invocation is a same-day post-compact
+ * resume. The LLM-side caller invokes this in Step 0.7 / Step 0.75
+ * after anchoring. Pure-ish: only filesystem reads of the checkpoint
+ * dir; no LLM calls.
+ */
+export async function detectPostCompactResume(opts) {
+    const now = opts.now ?? (() => new Date());
+    const warnings = [];
+    if (!opts.sessionId || opts.sessionId.trim().length === 0) {
+        return { shouldAutoResume: false, reason: 'sid-unbound', warnings };
+    }
+    const runtimeDir = join(opts.projectRoot, '.peaks', '_runtime', opts.sessionId);
+    if (!existsSync(runtimeDir)) {
+        return { shouldAutoResume: false, reason: 'runtime-dir-missing', warnings };
+    }
+    const probe = readLatestTodayCheckpoint(runtimeDir, now());
+    if (probe.found === 'multiple') {
+        return {
+            shouldAutoResume: false,
+            reason: 'multiple-checkpoints-ambiguous',
+            warnings: [`${probe.files.length} sessions have today's checkpoint; ambiguous`]
+        };
+    }
+    if (probe.found === 'none') {
+        return { shouldAutoResume: false, reason: 'no-checkpoint-today', warnings };
+    }
+    const file = probe.file;
+    const checkpointMode = file.content.mode;
+    if (checkpointMode === undefined) {
+        return {
+            shouldAutoResume: false,
+            reason: 'no-mode-field',
+            checkpointPath: file.path,
+            checkpointMtime: file.mtime.toISOString(),
+            warnings
+        };
+    }
+    // Active skill check (D7.a.4). Defaults to reading from skill presence.
+    const expectedActiveSkill = 'peaks-solo';
+    const observedActiveSkill = opts.activeSkill ?? readActiveSkillName(opts.projectRoot);
+    if (observedActiveSkill !== expectedActiveSkill) {
+        return {
+            shouldAutoResume: false,
+            reason: 'active-skill-mismatch',
+            checkpointPath: file.path,
+            checkpointMtime: file.mtime.toISOString(),
+            warnings: [`active skill "${observedActiveSkill ?? 'unset'}" is not peaks-solo`]
+        };
+    }
+    // Mode: prefer the checkpoint's mode; fall back to the presence override
+    // (test seam) or to a fresh skill-presence read.
+    let mode;
+    if (isSoloMode(checkpointMode)) {
+        mode = checkpointMode;
+    }
+    else if (opts.presenceModeOverride !== undefined) {
+        mode = opts.presenceModeOverride;
+    }
+    else {
+        try {
+            const presence = getSkillPresence(opts.projectRoot);
+            const presenceMode = presence?.mode;
+            if (presenceMode !== undefined && isSoloMode(presenceMode)) {
+                mode = presenceMode;
+            }
+        }
+        catch (err) {
+            warnings.push(`presence read failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (mode === undefined) {
+        return {
+            shouldAutoResume: false,
+            reason: 'no-mode-field',
+            checkpointPath: file.path,
+            checkpointMtime: file.mtime.toISOString(),
+            warnings
+        };
+    }
+    const successProbe = {
+        shouldAutoResume: true,
+        reason: 'post-compact-match',
+        mode,
+        checkpointPath: file.path,
+        checkpointMtime: file.mtime.toISOString(),
+        ...(file.content.currentPlan !== undefined ? { task: file.content.currentPlan } : {}),
+        ...(file.content.openQuestions !== undefined ? { openQuestions: file.content.openQuestions } : {}),
+        ...(file.content.recentDecisions !== undefined ? { recentDecisions: file.content.recentDecisions } : {}),
+        warnings
+    };
+    emitPostCompactEvent({ projectRoot: opts.projectRoot, sessionId: opts.sessionId, probe: successProbe });
+    return successProbe;
+}
+// Slice C of v2.11.1 — observability hook #6/7. Fire-and-forget per
+// PRD Q4. The synchronous emit never throws and never blocks the
+// detector return value.
+function emitPostCompactEvent(opts) {
+    emitObservabilityEvent({
+        schemaVersion: 1,
+        ts: new Date().toISOString(),
+        sessionId: opts.sessionId,
+        category: 'post-compact',
+        detail: {
+            shouldAutoResume: opts.probe.shouldAutoResume,
+            reason: opts.probe.reason,
+            ...(opts.probe.mode !== undefined ? { mode: opts.probe.mode } : {}),
+            ...(opts.probe.checkpointPath !== undefined ? { checkpointPath: opts.probe.checkpointPath } : {})
+        }
+    }, { projectRoot: opts.projectRoot });
+}
+function readActiveSkillName(projectRoot) {
+    try {
+        const presence = getSkillPresence(projectRoot);
+        return presence?.skill;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return undefined;
+    }
+}
+/**
+ * One-line auto-decisions log entry. Pure formatter; no IO. The LLM
+ * appends to `.peaks/_runtime/<sessionId>/txt/auto-decisions.md` so
+ * the existing audit channel picks it up (D7.e).
+ */
+export function formatPostCompactResumeLogLine(probe) {
+    if (!probe.shouldAutoResume) {
+        return `post-compact skip: reason=${probe.reason}`;
+    }
+    return `post-compact resume: ${probe.task ?? 'unspecified'} mode=${probe.mode ?? 'unknown'} checkpoint=${probe.checkpointPath ?? 'unknown'}`;
+}

package/dist/src/services/solo/status-line-renderer.d.ts

@@ -0,0 +1,34 @@
+/**
+ * G6.5 — status line renderer for the peaks-solo batch-sync wait period.
+ *
+ * Single line, 80-120 chars, status-line-friendly. The shape is
+ * documented in PRD §G6.5:
+ *
+ *   [peaks-solo] swarm 3/3 running | rd-planning 45% (12s ago) | qa-test-cases 30% (5s ago) | ui-design 20% (2s ago)
+ *   [peaks-solo] swarm 3/3 running | rd-planning 70% (8s ago) | qa-test-cases 50% (3s ago) | ui-design 30% (6s ago)
+ *   ...
+ *   [peaks-solo] swarm 3/3 done in 47.3s
+ *
+ * Pure helper; the poller calls it once per tick. No IO.
+ */
+import type { DispatchRecord } from '../dispatch/dispatch-record-writer.js';
+export type SubAgentLiveView = {
+    readonly role: string;
+    readonly status: string;
+    readonly progress: number | null;
+    readonly lastBeatAgoSec: number | null;
+    readonly isStale: boolean;
+};
+export type SwarmSummary = {
+    readonly total: number;
+    readonly running: number;
+    readonly done: number;
+    readonly failed: number;
+    readonly stale: number;
+};
+/** Build a per-sub-agent view of the current state of one record. */
+export declare function viewSubAgent(record: DispatchRecord, now?: () => Date): SubAgentLiveView;
+/** Aggregate swarm summary. */
+export declare function summarize(records: readonly DispatchRecord[]): SwarmSummary;
+/** Render a single status line. */
+export declare function renderStatusLine(prefix: string, records: readonly DispatchRecord[], now?: () => Date): string;

package/dist/src/services/solo/status-line-renderer.js

@@ -0,0 +1,55 @@
+const STALE_THRESHOLD_SEC = 5 * 60;
+/** Build a per-sub-agent view of the current state of one record. */
+export function viewSubAgent(record, now = () => new Date()) {
+    const latest = record.heartbeats[record.heartbeats.length - 1];
+    const lastBeatAgo = record.lastBeatAt
+        ? Math.max(0, Math.floor((now().getTime() - new Date(record.lastBeatAt).getTime()) / 1000))
+        : null;
+    const isStale = lastBeatAgo !== null && lastBeatAgo > STALE_THRESHOLD_SEC;
+    return {
+        role: record.role,
+        status: record.status,
+        progress: latest ? latest.progress : null,
+        lastBeatAgoSec: lastBeatAgo,
+        isStale
+    };
+}
+/** Aggregate swarm summary. */
+export function summarize(records) {
+    let running = 0;
+    let done = 0;
+    let failed = 0;
+    let stale = 0;
+    for (const r of records) {
+        const v = viewSubAgent(r);
+        if (v.isStale)
+            stale += 1;
+        if (r.status === 'done')
+            done += 1;
+        else if (r.status === 'failed' || r.status === 'cancelled')
+            failed += 1;
+        else
+            running += 1;
+    }
+    return { total: records.length, running, done, failed, stale };
+}
+/** Render a single status line. */
+export function renderStatusLine(prefix, records, now = () => new Date()) {
+    if (records.length === 0) {
+        return `${prefix} swarm 0/0 idle`;
+    }
+    const summary = summarize(records);
+    const allDone = summary.done === summary.total;
+    if (allDone) {
+        return `${prefix} swarm ${summary.done}/${summary.total} done`;
+    }
+    const parts = records.map((r) => renderOne(r, now));
+    return `${prefix} swarm ${summary.running}/${summary.total} running | ${parts.join(' | ')}`;
+}
+function renderOne(record, now) {
+    const view = viewSubAgent(record, now);
+    const pct = view.progress !== null ? `${view.progress}%` : '?%';
+    const ago = view.lastBeatAgoSec !== null ? `${view.lastBeatAgoSec}s ago` : 'no beat';
+    const stale = view.isStale ? ' ⚠ stale' : '';
+    return `${view.role} ${pct} (${ago})${stale}`;
+}

package/dist/src/services/solo/user-touchpoint-classifier.d.ts

@@ -0,0 +1,44 @@
+/**
+ * v2.15.0 follow-up — G4: user touchpoint classifier.
+ *
+ * 12 Gaps positioning memory: "user 介入 = 业务/产品审阅,不是技术决策".
+ * This service classifies every Solo gate by the kind of decision it
+ * represents, so the CLI / status line can show user which gates
+ * actually need their attention vs which are technical defaults
+ * (AI auto-decides in full-auto).
+ *
+ *   - `business`         — user MUST be present (business / product decisions)
+ *   - `tech`             — AI auto-decides in full-auto (tech choices)
+ *   - `mode-selection`   — the gate IS the mode / context selection
+ *                          itself (always prompts the user, even in
+ *                          full-auto)
+ *   - `commit-boundary`  — hard-floor: push / tag / publish / global
+ *                          install (always prompts, even in full-auto)
+ *   - `commit-floor`     — other hard-floor categories
+ *                          (irreversible-external / auth / multi-day
+ *                          investment)
+ *
+ * Pure functions. No I/O.
+ */
+export type GateKind = 'business' | 'tech' | 'mode-selection' | 'commit-boundary' | 'commit-floor';
+export interface GateClassification {
+    readonly step: string;
+    readonly kind: GateKind;
+    /** Short description of what the user / AI is deciding. */
+    readonly description: string;
+    /** Whether full-auto can auto-proceed this gate. */
+    readonly fullAutoCanProceed: boolean;
+    /** When user should pay attention (always / business-only / never). */
+    readonly userShouldReview: 'always' | 'business-only' | 'never';
+}
+export declare function classifyAllGates(): readonly GateClassification[];
+/** Look up a single gate's classification. Returns null when the step is not in the table. */
+export declare function classifyGate(step: string): GateClassification | null;
+/** List all gates the user must review (per the 12 Gaps positioning). */
+export declare function userMustReviewGates(): readonly GateClassification[];
+/** List all gates AI auto-decides in full-auto. */
+export declare function aiAutoDecidesGates(): readonly GateClassification[];
+export declare const COMMIT_BOUNDARY_ACTIONS_LIST: readonly {
+    id: string;
+    description: string;
+}[];

package/dist/src/services/solo/user-touchpoint-classifier.js

@@ -0,0 +1,145 @@
+/**
+ * v2.15.0 follow-up — G4: user touchpoint classifier.
+ *
+ * 12 Gaps positioning memory: "user 介入 = 业务/产品审阅,不是技术决策".
+ * This service classifies every Solo gate by the kind of decision it
+ * represents, so the CLI / status line can show user which gates
+ * actually need their attention vs which are technical defaults
+ * (AI auto-decides in full-auto).
+ *
+ *   - `business`         — user MUST be present (business / product decisions)
+ *   - `tech`             — AI auto-decides in full-auto (tech choices)
+ *   - `mode-selection`   — the gate IS the mode / context selection
+ *                          itself (always prompts the user, even in
+ *                          full-auto)
+ *   - `commit-boundary`  — hard-floor: push / tag / publish / global
+ *                          install (always prompts, even in full-auto)
+ *   - `commit-floor`     — other hard-floor categories
+ *                          (irreversible-external / auth / multi-day
+ *                          investment)
+ *
+ * Pure functions. No I/O.
+ */
+const RAW_CLASSIFICATION = [
+    {
+        step: 'step-0.5-openspec-opt-in',
+        kind: 'mode-selection',
+        description: 'OpenSpec 一次性 opt-in(使用 OpenSpec spec-first 流程)。这是 context 选择门,user 必答。',
+        fullAutoCanProceed: false,
+        userShouldReview: 'always'
+    },
+    {
+        step: 'step-0.6-audit-goal',
+        kind: 'business',
+        description: 'Audit + Goal 确认。goal 必须明确区分业务/产品(user 写)与技术(AI 拍板)。user 必审。',
+        fullAutoCanProceed: false,
+        userShouldReview: 'always'
+    },
+    {
+        step: 'step-0.7-resume-detection',
+        kind: 'mode-selection',
+        description: '未完工作续做 vs 重开。context 选择门,user 必答。',
+        fullAutoCanProceed: false,
+        userShouldReview: 'always'
+    },
+    {
+        step: 'step-0.55-1x-upgrade',
+        kind: 'commit-floor',
+        description: '1.x → 2.0 升级检测。不可逆外部副作用(改写 config + cache schema),所有 mode 都必须 AskUserQuestion。full-auto 也暂停。',
+        fullAutoCanProceed: false,
+        userShouldReview: 'always'
+    },
+    {
+        step: 'step-0.75-checkpoint-resume',
+        kind: 'tech',
+        description: '同 session 当日重入 + checkpoint 续做。技术恢复逻辑,user 不参与。',
+        fullAutoCanProceed: true,
+        userShouldReview: 'never'
+    },
+    {
+        step: 'step-1-mode-select',
+        kind: 'mode-selection',
+        description: 'Mode 选择(全自动化 / 半自动 / 蜂群 / 严格)。context 选择门,user 必答。',
+        fullAutoCanProceed: false,
+        userShouldReview: 'always'
+    },
+    {
+        step: 'step-2.5-session-title',
+        kind: 'tech',
+        description: 'Session 标题生成(从用户首次请求抽取)。技术性 metadata,AI 自决。',
+        fullAutoCanProceed: true,
+        userShouldReview: 'never'
+    },
+    {
+        step: 'phase-2-prd-confirm',
+        kind: 'business',
+        description: 'PRD 确认。user 必审业务/产品意图(4 必填块见 prd check-blocks)。',
+        fullAutoCanProceed: false,
+        userShouldReview: 'always'
+    },
+    {
+        step: 'phase-3-swarm-gate-b',
+        kind: 'tech',
+        description: '蜂群 gate B(并行 fan-out 决策)。技术调度,AI 在 full-auto 自决。',
+        fullAutoCanProceed: true,
+        userShouldReview: 'never'
+    },
+    {
+        step: 'phase-6-qa-gate-d',
+        kind: 'business',
+        description: 'QA gate D(业务验收)。user 必审业务/产品视角 6 项清单(不是技术指标)。',
+        fullAutoCanProceed: false,
+        userShouldReview: 'always'
+    },
+    {
+        step: 'phase-10-txt-memory-extract',
+        kind: 'business',
+        description: 'TXT handoff + memory 提取。user 必审(决定哪些 peaks-memory 块落 .peaks/memory/)。',
+        fullAutoCanProceed: false,
+        userShouldReview: 'always'
+    },
+    {
+        step: 'step-n+1-final-review',
+        kind: 'business',
+        description: '4 维终审。user 必审业务交付完整性。',
+        fullAutoCanProceed: false,
+        userShouldReview: 'always'
+    },
+    {
+        step: 'frontend-only-mismatch',
+        kind: 'tech',
+        description: '前端-only 模式不匹配检测。技术模式判断,AI 在 full-auto 自决。',
+        fullAutoCanProceed: true,
+        userShouldReview: 'never'
+    },
+    {
+        step: 'standards-preflight',
+        kind: 'tech',
+        description: '项目标准预检(standards init/update dry-run)。技术 preflight,AI 自决 apply。',
+        fullAutoCanProceed: true,
+        userShouldReview: 'never'
+    }
+];
+export function classifyAllGates() {
+    return RAW_CLASSIFICATION.slice();
+}
+/** Look up a single gate's classification. Returns null when the step is not in the table. */
+export function classifyGate(step) {
+    const raw = RAW_CLASSIFICATION.find((g) => g.step === step);
+    return raw === undefined ? null : raw;
+}
+/** List all gates the user must review (per the 12 Gaps positioning). */
+export function userMustReviewGates() {
+    return RAW_CLASSIFICATION.filter((g) => g.userShouldReview !== 'never');
+}
+/** List all gates AI auto-decides in full-auto. */
+export function aiAutoDecidesGates() {
+    return RAW_CLASSIFICATION.filter((g) => g.fullAutoCanProceed);
+}
+export const COMMIT_BOUNDARY_ACTIONS_LIST = [
+    { id: 'git-push', description: 'git push / git push origin / git push --tags' },
+    { id: 'git-tag', description: 'git tag v2.15.0 / git tag -a ...' },
+    { id: 'npm-publish', description: 'npm publish / npm pub' },
+    { id: 'npm-install-global', description: 'npm install -g / npm i -g / npm add -g' },
+    { id: 'peaks-global-install', description: 'peaks-cli 全局安装 / npm install -g peaks-cli' }
+];

package/dist/src/services/sop/gate-enforce-service.d.ts

@@ -0,0 +1,33 @@
+import type { BlockedGate } from './sop-advance-service.js';
+export type MatchedGuard = {
+    sopId: string;
+    phase: string;
+    /** The non-passing gates that block this phase's guarded action. */
+    failing: BlockedGate[];
+};
+export type EnforceDecision = {
+    decision: 'allow';
+    bypassed?: boolean;
+    warnings?: string[];
+} | {
+    decision: 'deny';
+    reason: string;
+    matched: MatchedGuard[];
+};
+export declare class GateBypassError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Record a one-shot bypass token for `<sopId>:<phase>` in this project. The next
+ * `enforceBashCommand` that the transition blocks consumes it and allows once.
+ * Capped per-project-per-SOP by MAX_BYPASSES_PER_SESSION.
+ */
+export declare function recordGateBypass(projectRoot: string, sopId: string, phase: string, reason: string): {
+    count: number;
+};
+/**
+ * Decide whether a Bash command may run. Pure given the filesystem; never throws
+ * (fail-open on any internal error). Returns allow/deny for the PreToolUse hook.
+ */
+export declare function enforceBashCommand(projectRoot: string, command: string): Promise<EnforceDecision>;