peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/slice/slice-review-state.js

@@ -0,0 +1,109 @@
+/**
+ * v2.15.0 follow-up — G1: slice business review state.
+ *
+ * The 12 Gaps positioning memory: each slice completion triggers a
+ * business review by the user (not a technical review). The user
+ * evaluates 4-5 business / product items; technical metrics (coverage,
+ * P99, security scan) are AI auto-decided in `peaks-rd`'s fan-out.
+ *
+ * State persistence: `.peaks/_runtime/<sid>/slice-reviews/<slice-id>.json`.
+ *
+ *   reviewScore: 1-5 per item; overallOk when avg >= 3 AND no P0 fail
+ *   decision: pending | accepted | rejected
+ *   rejectionReason: only when decision = rejected
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+/** The 5 default review items per slice (the 12 Gaps memory checklist). */
+export const DEFAULT_REVIEW_ITEMS = [
+    { id: 'business-match', question: '这个 slice 做完,业务流程对吗?(跟产品最初给的需求匹配)' },
+    { id: 'boundary-cases', question: '边界 case 跟业务预期一致吗?(异常输入/错误提示/空/加载/失败状态)' },
+    { id: 'ui-assembly', question: 'UI 装配跟产品预期一致吗?(页面模式/关键交互/信息密度,非视觉设计)' },
+    { id: 'mergeable', question: '能合入下个业务版本吗?(业务风险/集成断点)' }
+];
+export function buildEmptySliceReview(sliceId, sessionId, now = new Date()) {
+    return {
+        sliceId,
+        sessionId,
+        createdAt: now.toISOString(),
+        updatedAt: now.toISOString(),
+        decision: 'pending',
+        items: DEFAULT_REVIEW_ITEMS.map((it) => ({ id: it.id, question: it.question, score: null }))
+    };
+}
+export function getReviewDir(projectRoot, sessionId) {
+    return resolve(projectRoot, '.peaks', '_runtime', sessionId, 'slice-reviews');
+}
+export function getReviewPath(projectRoot, sessionId, sliceId) {
+    return join(getReviewDir(projectRoot, sessionId), `${sliceId}.json`);
+}
+export function readSliceReview(projectRoot, sessionId, sliceId) {
+    const path = getReviewPath(projectRoot, sessionId, sliceId);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        console.warn(`readSliceReview: failed to read or parse ${path}: ${err.message}`);
+        return null;
+    }
+}
+export function writeSliceReview(projectRoot, review) {
+    const path = getReviewPath(projectRoot, review.sessionId, review.sliceId);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(review, null, 2), 'utf8');
+}
+/** Update a single item's score. Returns the new state. */
+export function scoreItem(review, itemId, score, note, now = new Date()) {
+    let found = false;
+    const items = review.items.map((it) => {
+        if (it.id !== itemId)
+            return it;
+        found = true;
+        return { id: it.id, question: it.question, score, ...(note !== undefined ? { note } : {}) };
+    });
+    if (!found)
+        return review;
+    return { ...review, items, updatedAt: now.toISOString() };
+}
+/** Compute the average score across all scored items. */
+export function averageScore(review) {
+    const scored = review.items.filter((it) => it.score !== null);
+    if (scored.length === 0)
+        return null;
+    return scored.reduce((sum, it) => sum + it.score, 0) / scored.length;
+}
+/** Decide accept/reject based on the 12 Gaps threshold:
+ *   - avg score >= 3 AND no item scored <= 2 → accepted
+ *   - any item scored 1 (P0 fail) or avg < 3 → rejected
+ */
+export function deriveDecision(review) {
+    if (review.items.some((it) => it.score === 1))
+        return 'rejected';
+    const avg = averageScore(review);
+    if (avg === null)
+        return 'pending';
+    if (avg < 3)
+        return 'rejected';
+    // Any item <= 2 also rejects.
+    if (review.items.some((it) => it.score !== null && it.score <= 2))
+        return 'rejected';
+    return 'accepted';
+}
+/** Apply the derived decision to a review (used by `peaks slice accept`). */
+export function acceptReview(review, now = new Date()) {
+    return { ...review, decision: 'accepted', updatedAt: now.toISOString() };
+}
+export function rejectReview(review, reason, now = new Date()) {
+    return { ...review, decision: 'rejected', rejectionReason: reason, updatedAt: now.toISOString() };
+}
+export function renderChecklist(review) {
+    return review.items.map((it) => ({
+        id: it.id,
+        question: it.question,
+        currentScore: it.score,
+        prompt: `  [ ] ${it.question} (current: ${it.score === null ? 'not scored' : it.score + '/5'})`
+    }));
+}

package/dist/services/slice/slice-topology-types.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Type envelope for v2 multi-pass slice decomposition.
+ *
+ * v2 extends the v1 `DecompositionResult` with a `passes[]` array (one entry
+ * per decomposition pass) and `crossPassEdges[]` (edges that span passes),
+ * plus an `llmArbitrations[]` trace for any LLM calls made during
+ * decomposition. The new schema is what `peaks-slice-decompose` (and the
+ * new `MultiPassOrchestrator`) emit; v1 files remain readable via the
+ * `SchemaRouter` (Task 8) so existing `peaks slice pick` / `peaks slice plan`
+ * flows do not break.
+ *
+ * Conventions:
+ * - All fields are `readonly` to enforce immutable construction.
+ * - Literal unions (`SchemaVersion`, `PassNumber`, etc.) are preferred over
+ *   `enum` so the JSON serialisation is the literal string, not a number.
+ * - `CrossPassEdge.confidence` extends the structural|semantic union with
+ *   `'llm'` because LLM-arbitrated edges are neither — they were guessed
+ *   by an LLM and must carry the arbitration trace via `arbitratedBy`.
+ */
+import type { CodegraphEnvelope, UnderstandAnythingEnvelope } from './slice-decompose-types.js';
+/** Schema discriminator. v1 files do NOT carry a `schemaVersion` field. */
+export type SchemaVersion = 'v1' | 'v2';
+/** How coarse a slice is. */
+export type SliceGranularity = 'service' | 'file' | 'sub-file';
+/** Pass index. v2 only goes up to Pass 3 (sub-file is reserved for future). */
+export type PassNumber = 1 | 2 | 3;
+/** Edge source confidence. */
+export type EdgeConfidence = 'structural' | 'semantic';
+/** LLM-reported confidence of a single arbitration. */
+export type LlmConfidence = 'high' | 'medium' | 'low';
+/** Edge kinds for edges within a single pass. */
+export type InternalEdgeKind = 'imports' | 'calls' | 'depends_on' | 'contains_flow' | 'flow_step';
+/** Edge kinds for edges that connect two different passes. */
+export type CrossPassEdgeKind = 'type-shares' | 'fixture-shares' | 'import-re-export' | 'llm-arbitrated';
+/** Configuration for a single decomposition pass. */
+export interface PassConfig {
+    readonly passNumber: PassNumber;
+    readonly granularity: SliceGranularity;
+    /** Optional list of files (or semantic anchors) to scope this pass to. */
+    readonly scopeFilter?: readonly string[];
+}
+/** A single v2 slice, scoped to one pass. */
+export interface SliceV2 {
+    /** Stable id within this pass (e.g. "S1" for Pass 1, "S1.3" for Pass 2 child of S1). */
+    readonly id: string;
+    /** Human-readable label; shown in `peaks slice pick` fzf list. */
+    readonly label: string;
+    readonly granularity: SliceGranularity;
+    readonly files: readonly string[];
+    /** Total LoC across all `files`. */
+    readonly loc: number;
+    /** Parent slice id from the previous pass, or null for Pass 1. */
+    readonly parentSliceId: string | null;
+    /** Domain anchor; "domain:<name>" if understand-anything indexed, else "file:<path>". */
+    readonly semanticAnchor: string;
+}
+/** Edge connecting two slices within the same pass. */
+export interface InternalEdge {
+    readonly from: string;
+    readonly to: string;
+    readonly kind: InternalEdgeKind;
+    /** Edge weight for downstream min-cut / dispatch-ordering heuristics. */
+    readonly weight: number;
+    /** Human-readable evidence: the actual import statement or graph edge. */
+    readonly evidence: string;
+    readonly confidence: EdgeConfidence;
+}
+/** Edge connecting a slice in one pass to a slice in another pass. */
+export interface CrossPassEdge {
+    readonly fromPass: PassNumber;
+    readonly toPass: PassNumber;
+    readonly fromSliceId: string;
+    readonly toSliceId: string;
+    readonly kind: CrossPassEdgeKind;
+    /** `llm` is only valid for `kind: 'llm-arbitrated'`. */
+    readonly confidence: EdgeConfidence | 'llm';
+    /** Human-readable evidence: the import line, shared fixture id, etc. */
+    readonly evidence: string;
+    /** The `LlmArbitration.callId` that produced this edge, or null. */
+    readonly arbitratedBy: string | null;
+}
+/** Record of one LLM call made during decomposition. */
+export interface LlmArbitration {
+    readonly callId: string;
+    /** sha256 hex of the prompt (used for content-hash cache lookup). */
+    readonly promptHash: string;
+    readonly input: string;
+    readonly output: string;
+    readonly confidence: LlmConfidence;
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+    };
+}
+/** The slices + internal edges produced by one decomposition pass. */
+export interface PassResult {
+    readonly passNumber: PassNumber;
+    readonly granularity: SliceGranularity;
+    readonly slices: readonly SliceV2[];
+    readonly internalEdges: readonly InternalEdge[];
+}
+/** Top-level v2 decomposition result. */
+export interface DecompositionResultV2 {
+    readonly schemaVersion: 'v2';
+    readonly rid: string;
+    /** ISO 8601 UTC, e.g. "2026-06-25T12:00:00.000Z". */
+    readonly generatedAt: string;
+    readonly passes: readonly PassResult[];
+    readonly crossPassEdges: readonly CrossPassEdge[];
+    readonly llmArbitrations: readonly LlmArbitration[];
+    readonly codegraph: CodegraphEnvelope;
+    readonly understandAnything: UnderstandAnythingEnvelope;
+    /** True iff any pass failed to complete and the result is a partial. */
+    readonly partial: boolean;
+}

package/dist/services/slice/slice-topology-types.js

@@ -0,0 +1,20 @@
+/**
+ * Type envelope for v2 multi-pass slice decomposition.
+ *
+ * v2 extends the v1 `DecompositionResult` with a `passes[]` array (one entry
+ * per decomposition pass) and `crossPassEdges[]` (edges that span passes),
+ * plus an `llmArbitrations[]` trace for any LLM calls made during
+ * decomposition. The new schema is what `peaks-slice-decompose` (and the
+ * new `MultiPassOrchestrator`) emit; v1 files remain readable via the
+ * `SchemaRouter` (Task 8) so existing `peaks slice pick` / `peaks slice plan`
+ * flows do not break.
+ *
+ * Conventions:
+ * - All fields are `readonly` to enforce immutable construction.
+ * - Literal unions (`SchemaVersion`, `PassNumber`, etc.) are preferred over
+ *   `enum` so the JSON serialisation is the literal string, not a number.
+ * - `CrossPassEdge.confidence` extends the structural|semantic union with
+ *   `'llm'` because LLM-arbitrated edges are neither — they were guessed
+ *   by an LLM and must carry the arbitration trace via `arbitratedBy`.
+ */
+export {};

package/dist/services/smoke/smoke-paths-state.d.ts

@@ -0,0 +1,73 @@
+/**
+ * v2.15.0 follow-up — G14: smoke regression state service.
+ *
+ * Tracks the project's "critical paths" — the 5-10 paths the user
+ * (or the QA agent) must verify in 5-10 minutes before shipping.
+ * Persistence: `.peaks/smoke-paths.json` in the project root.
+ *
+ * The actual path execution (Playwright / curl / manual) is OUT OF
+ * SCOPE for this slice — this ships the model + the run-result
+ * record path. A follow-up slice wires real Playwright integration.
+ */
+export type CriticalPathSource = 'prd-business-scenario' | 'boss-stated' | 'historical-incident' | 'impact-must-check' | 'manual';
+export type CriticalPathStatus = 'pending' | 'pass' | 'fail';
+export interface CriticalPath {
+    /** Unique id. */
+    readonly id: string;
+    /** Human-readable name / description. */
+    readonly name: string;
+    /** Where this path came from. */
+    readonly source: CriticalPathSource;
+    /** When it was registered (ISO). */
+    readonly registeredAt: string;
+    /** Optional category tag (e.g. "登录", "权限", "数据列表"). */
+    readonly category?: string;
+    /** Latest status + when it was last run. */
+    readonly status: CriticalPathStatus;
+    readonly lastRunAt?: string;
+    readonly lastRunNote?: string;
+    /** Optional run history (last 5 runs, oldest first). */
+    readonly history: readonly {
+        readonly at: string;
+        readonly status: CriticalPathStatus;
+        readonly note?: string;
+    }[];
+}
+export interface SmokeState {
+    readonly version: 1;
+    readonly paths: readonly CriticalPath[];
+}
+export declare const EMPTY_SMOKE_STATE: SmokeState;
+export declare function getSmokeStatePath(projectRoot: string): string;
+export declare function readSmokeState(projectRoot: string): SmokeState;
+export declare function writeSmokeState(projectRoot: string, state: SmokeState): void;
+/** Sources accepted by the CLI's --source flag. */
+export declare const CRITICAL_PATH_SOURCES: readonly CriticalPathSource[];
+export declare function isCriticalPathSource(value: string): value is CriticalPathSource;
+/** Generate a stable id from a name (lowercase, hyphens). */
+export declare function makeCriticalPathId(name: string): string;
+/** Add a critical path. Deduplicates by id. */
+export declare function addCriticalPath(state: SmokeState, path: CriticalPath): SmokeState;
+/** Add a run result to a path's history. Keeps the last 5. */
+export declare function recordRun(state: SmokeState, id: string, status: CriticalPathStatus, note?: string, now?: Date): SmokeState;
+/** Convert peaks impact must-check items to critical paths. */
+export declare function impactMustChecksToCriticalPaths(items: readonly {
+    scenario: string;
+    category: string;
+    priority: string;
+}[], now?: Date): CriticalPath[];
+/** Run summary for `peaks smoke run`. */
+export interface SmokeRunResult {
+    readonly totalPaths: number;
+    readonly passedPaths: number;
+    readonly failedPaths: number;
+    readonly pendingPaths: number;
+    readonly failedDetails: readonly {
+        id: string;
+        name: string;
+        lastRunNote?: string;
+    }[];
+    readonly durationMs: number;
+}
+/** Compute run summary from current state. */
+export declare function summarizeState(state: SmokeState): SmokeRunResult;

package/dist/services/smoke/smoke-paths-state.js

@@ -0,0 +1,117 @@
+/**
+ * v2.15.0 follow-up — G14: smoke regression state service.
+ *
+ * Tracks the project's "critical paths" — the 5-10 paths the user
+ * (or the QA agent) must verify in 5-10 minutes before shipping.
+ * Persistence: `.peaks/smoke-paths.json` in the project root.
+ *
+ * The actual path execution (Playwright / curl / manual) is OUT OF
+ * SCOPE for this slice — this ships the model + the run-result
+ * record path. A follow-up slice wires real Playwright integration.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+export const EMPTY_SMOKE_STATE = { version: 1, paths: [] };
+const STATE_FILE = '.peaks/smoke-paths.json';
+export function getSmokeStatePath(projectRoot) {
+    return resolve(projectRoot, STATE_FILE);
+}
+export function readSmokeState(projectRoot) {
+    const path = getSmokeStatePath(projectRoot);
+    if (!existsSync(path))
+        return EMPTY_SMOKE_STATE;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== 1)
+            return EMPTY_SMOKE_STATE;
+        return { version: 1, paths: Array.isArray(parsed.paths) ? parsed.paths : [] };
+    }
+    catch {
+        return EMPTY_SMOKE_STATE;
+    }
+}
+export function writeSmokeState(projectRoot, state) {
+    const path = getSmokeStatePath(projectRoot);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(state, null, 2), 'utf8');
+}
+/** Sources accepted by the CLI's --source flag. */
+export const CRITICAL_PATH_SOURCES = [
+    'prd-business-scenario',
+    'boss-stated',
+    'historical-incident',
+    'impact-must-check',
+    'manual'
+];
+export function isCriticalPathSource(value) {
+    return CRITICAL_PATH_SOURCES.includes(value);
+}
+/** Generate a stable id from a name (lowercase, hyphens). */
+export function makeCriticalPathId(name) {
+    return name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+/** Add a critical path. Deduplicates by id. */
+export function addCriticalPath(state, path) {
+    const filtered = state.paths.filter((p) => p.id !== path.id);
+    return { version: 1, paths: [...filtered, path] };
+}
+/** Add a run result to a path's history. Keeps the last 5. */
+export function recordRun(state, id, status, note, now = new Date()) {
+    let found = false;
+    const paths = state.paths.map((p) => {
+        if (p.id !== id)
+            return p;
+        found = true;
+        const newHistory = [...p.history, { at: now.toISOString(), status, ...(note !== undefined ? { note } : {}) }].slice(-5);
+        return {
+            ...p,
+            status,
+            lastRunAt: now.toISOString(),
+            ...(note !== undefined ? { lastRunNote: note } : {}),
+            history: newHistory
+        };
+    });
+    if (!found)
+        return state;
+    return { version: 1, paths };
+}
+/** Convert peaks impact must-check items to critical paths. */
+export function impactMustChecksToCriticalPaths(items, now = new Date()) {
+    return items.map((item) => ({
+        id: makeCriticalPathId(item.scenario),
+        name: item.scenario,
+        source: 'impact-must-check',
+        registeredAt: now.toISOString(),
+        category: item.category,
+        status: 'pending',
+        history: []
+    }));
+}
+/** Compute run summary from current state. */
+export function summarizeState(state) {
+    let passed = 0, failed = 0, pending = 0;
+    const failedDetails = [];
+    for (const p of state.paths) {
+        if (p.status === 'pass')
+            passed++;
+        else if (p.status === 'fail') {
+            failed++;
+            failedDetails.push({ id: p.id, name: p.name, ...(p.lastRunNote !== undefined ? { lastRunNote: p.lastRunNote } : {}) });
+        }
+        else
+            pending++;
+    }
+    return {
+        totalPaths: state.paths.length,
+        passedPaths: passed,
+        failedPaths: failed,
+        pendingPaths: pending,
+        failedDetails,
+        durationMs: 0 // CLI measures wall time; the service itself is instant
+    };
+}

package/dist/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>;

package/dist/services/sop/gate-enforce-service.js

@@ -0,0 +1,168 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readRegistry } from './sop-registry-service.js';
+import { readSopManifest } from './sop-service.js';
+import { evaluateGate } from './sop-check-service.js';
+import { sopStateDir } from './sop-paths.js';
+import { isBypassLimitReached, recordBypass, MAX_BYPASSES_PER_SESSION } from '../mode/bypass-tracker.js';
+/**
+ * Gate enforcement — Feature A, Slice 4 (the un-bypassable closure).
+ *
+ * `enforceBashCommand` is the brain behind the PreToolUse hook: given a Bash
+ * command the agent is about to run, it finds every registered SOP whose phase
+ * `guards` match that command, evaluates that phase's gates, and decides
+ * allow/deny. A deny, surfaced by the hook as `permissionDecision: "deny"`,
+ * blocks the tool call before Claude Code's permission checks — so the action
+ * cannot happen while a gate fails, regardless of agent cooperation or
+ * `--dangerously-skip-permissions`.
+ *
+ * TRUST RED LINE: this runs on (potentially) every Bash call. A bug here must
+ * never brick the user's Claude Code. So every internal failure (unreadable
+ * registry, malformed manifest, invalid guard regex) is FAIL-OPEN — it allows
+ * the command and emits a warning. Only a genuine gate failure denies.
+ *
+ * Escape hatch: a one-shot bypass token (written by `peaks gate bypass`) for a
+ * matched transition is consumed here and turns the deny into an allow, capped
+ * per-project-per-SOP by the shared bypass tracker.
+ */
+const BYPASS_TOKENS_FILE = '.gate-bypass.json';
+function bypassTokensPath(projectRoot, sopId) {
+    return join(sopStateDir(projectRoot, sopId), BYPASS_TOKENS_FILE);
+}
+function readBypassTokens(projectRoot, sopId) {
+    const path = bypassTokensPath(projectRoot, sopId);
+    if (!existsSync(path)) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (!Array.isArray(parsed)) {
+            return [];
+        }
+        return parsed.filter((t) => t !== null && typeof t === 'object' && typeof t.phase === 'string');
+    }
+    catch {
+        return [];
+    }
+}
+function writeBypassTokens(projectRoot, sopId, tokens) {
+    const dir = sopStateDir(projectRoot, sopId);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(bypassTokensPath(projectRoot, sopId), `${JSON.stringify(tokens, null, 2)}\n`, 'utf8');
+}
+function hasBypassToken(projectRoot, sopId, phase) {
+    return readBypassTokens(projectRoot, sopId).some((t) => t.phase === phase);
+}
+/** Remove the first matching bypass token (one-shot). Returns true if one was consumed. */
+function consumeBypassToken(projectRoot, sopId, phase) {
+    const tokens = readBypassTokens(projectRoot, sopId);
+    const index = tokens.findIndex((t) => t.phase === phase);
+    if (index === -1) {
+        return false;
+    }
+    tokens.splice(index, 1);
+    writeBypassTokens(projectRoot, sopId, tokens);
+    return true;
+}
+export class GateBypassError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'GateBypassError';
+        this.code = code;
+    }
+}
+/**
+ * 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 function recordGateBypass(projectRoot, sopId, phase, reason) {
+    const root = sopStateDir(projectRoot, sopId);
+    if (isBypassLimitReached(root)) {
+        throw new GateBypassError('BYPASS_LIMIT_REACHED', `gate bypass limit reached (${MAX_BYPASSES_PER_SESSION} bypasses per SOP per project)`);
+    }
+    const tokens = readBypassTokens(projectRoot, sopId);
+    writeBypassTokens(projectRoot, sopId, [...tokens, { phase, reason }]);
+    const count = recordBypass(root);
+    return { count };
+}
+function denyReason(matched) {
+    const lines = matched.map((m) => {
+        const gates = m.failing.map((g) => `${g.gateId}=${g.result}${g.reason ? ` (${g.reason})` : ''}`).join(', ');
+        return `SOP "${m.sopId}" phase "${m.phase}": ${gates}`;
+    });
+    const hint = matched
+        .map((m) => `peaks gate bypass --sop ${m.sopId} --phase ${m.phase} --reason "<why>"`)
+        .join(' ; ');
+    return `Blocked by Peaks gate(s): ${lines.join(' | ')}. Satisfy the gate(s), or bypass once: ${hint}`;
+}
+/**
+ * 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 async function enforceBashCommand(projectRoot, command) {
+    const warnings = [];
+    let sopIds;
+    try {
+        // Merged view: project-layer SOPs (committed in the repo — a teammate who
+        // clones gets them) over global. This is what makes enforcement work for a
+        // teammate who has only the repo, not your global ~/.peaks.
+        sopIds = (await readRegistry(projectRoot)).sops.map((sop) => sop.id);
+    }
+    catch (error) {
+        return { decision: 'allow', warnings: [`gate enforce: could not read registry (${error instanceof Error ? error.message : 'error'}); allowing`] };
+    }
+    const matched = [];
+    for (const sopId of sopIds) {
+        let manifest;
+        try {
+            manifest = await readSopManifest(sopId, projectRoot);
+        }
+        catch (error) {
+            warnings.push(`gate enforce: SOP "${sopId}" manifest unreadable (${error instanceof Error ? error.message : 'error'}); skipping`);
+            continue;
+        }
+        if (manifest === null || !Array.isArray(manifest.guards) || manifest.guards.length === 0) {
+            continue;
+        }
+        for (const guard of manifest.guards) {
+            let regex;
+            try {
+                regex = new RegExp(guard.bash);
+            }
+            catch {
+                warnings.push(`gate enforce: SOP "${sopId}" guard has an invalid regex "${guard.bash}"; skipping`);
+                continue;
+            }
+            if (!regex.test(command)) {
+                continue;
+            }
+            const failing = [];
+            for (const gate of manifest.gates.filter((g) => g.phase === guard.phase)) {
+                const verdict = evaluateGate(projectRoot, gate, { allowCommands: true });
+                if (verdict.result !== 'pass') {
+                    failing.push(verdict.reason === undefined
+                        ? { gateId: gate.id, result: verdict.result }
+                        : { gateId: gate.id, result: verdict.result, reason: verdict.reason });
+                }
+            }
+            if (failing.length > 0) {
+                matched.push({ sopId, phase: guard.phase, failing });
+            }
+        }
+    }
+    if (matched.length === 0) {
+        return warnings.length > 0 ? { decision: 'allow', warnings } : { decision: 'allow' };
+    }
+    // One-shot bypass: only allow if EVERY blocked transition has a token to spend
+    // (don't burn tokens on a partial pass-through).
+    const allBypassable = matched.every((m) => hasBypassToken(projectRoot, m.sopId, m.phase));
+    if (allBypassable) {
+        for (const m of matched) {
+            consumeBypassToken(projectRoot, m.sopId, m.phase);
+        }
+        return { decision: 'allow', bypassed: true, ...(warnings.length > 0 ? { warnings } : {}) };
+    }
+    return { decision: 'deny', reason: denyReason(matched), matched };
+}