peaks-cli 1.1.1 → 1.2.0

package/dist/src/cli/index.js

@@ -5,6 +5,18 @@ createProgram().parseAsync(process.argv).catch((error) => {
     if (error instanceof CommanderError && error.code === 'commander.version') {
         return;
     }
+    // exitOverride() also throws for help; suppress those — the text already went
+    // to stdout/stderr, the error envelope confuses newcomers. --help is success
+    // (exit 0); a bad command/option is an error (exit 1).
+    if (error instanceof CommanderError) {
+        if (error.code === 'commander.help' || error.code === 'commander.helpDisplayed') {
+            return;
+        }
+        if (error.code === 'commander.missingArgument' || error.code === 'commander.unknownCommand' || error.code === 'commander.unknownOption') {
+            process.exitCode = 1;
+            return;
+        }
+    }
     console.error(JSON.stringify({
         ok: false,
         command: 'cli',

package/dist/src/cli/program.js

@@ -1,4 +1,7 @@
+import { readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { Command } from 'commander';
+import { skillsDir } from '../shared/paths.js';
 import { CLI_VERSION } from '../shared/version.js';
 import { registerCoreAndArtifactCommands } from './commands/core-artifact-commands.js';
 import { registerWorkflowCommands } from './commands/workflow-commands.js';
@@ -10,6 +13,9 @@ import { registerProjectCommands } from './commands/project-commands.js';
 import { registerRequestCommands } from './commands/request-commands.js';
 import { registerScanCommands } from './commands/scan-commands.js';
 import { registerShadcnCommands } from './commands/shadcn-commands.js';
+import { registerSopCommands } from './commands/sop-commands.js';
+import { registerGateCommands } from './commands/gate-commands.js';
+import { registerHooksCommands } from './commands/hooks-commands.js';
 import { registerStatusLineCommands } from './commands/statusline-commands.js';
 import { registerUnderstandCommands } from './commands/understand-commands.js';
 import { registerWorkspaceCommands } from './commands/workspace-commands.js';
@@ -18,7 +24,14 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
     const program = new Command();
     program
         .name('peaks')
-        .description('Peaks CLI and short skill family runtime manager')
+        .description(`Peaks CLI ${CLI_VERSION} — workflow-gating CLI + skill family for Claude Code
+
+Run peaks (no arguments) for a quickstart. You likely want one of:
+  peaks doctor     check your environment
+  peaks skill      list or manage skills
+  peaks sop        author your own workflow gates
+  peaks hooks      install the un-bypassable gate-enforcement hook
+  peaks gate       enforce/bypass SOP gates on Bash commands`)
         .configureOutput({
         writeOut: (text) => io.stdout(text.trimEnd()),
         writeErr: (text) => io.stderr(text.trimEnd())
@@ -26,9 +39,38 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
         .version(CLI_VERSION, '-v, --version')
         .option('-V', 'output the version number')
         .action(() => {
-        if (program.opts().V) {
+        const opts = program.opts();
+        if (opts.V) {
             io.stdout(CLI_VERSION);
+            return;
         }
+        // Count bundled skills by reading the skills dir directly (synchronous so
+        // the quickstart renders instantly — no import/async overhead on startup).
+        let skillCount = 0;
+        const skillsPath = skillsDir;
+        try {
+            if (existsSync(skillsPath)) {
+                skillCount = readdirSync(skillsPath, { withFileTypes: true })
+                    .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+                    .filter((entry) => existsSync(join(skillsPath, entry.name, 'SKILL.md')))
+                    .length;
+            }
+        }
+        catch { /* disk read is best-effort; zero skills is still truthful */ }
+        io.stdout(`Peaks CLI ${CLI_VERSION}  ·  ${skillCount} skills ready
+
+  Peaks is a workflow-gating CLI + skill family for Claude Code.
+  It turns "don't skip steps" into hard enforcement — gates that block
+  advancement in-conversation, un-bypassably.
+
+  Before diving into a project, two things worth doing now:
+
+    peaks doctor             check your environment in one glance
+    peaks-sop                <<< ask this skill to author your first SOP
+
+  Or jump straight in:
+    peaks sop init --id my-flow --apply && peaks hooks install
+`);
     })
         .exitOverride();
     registerCoreAndArtifactCommands(program, io);
@@ -41,6 +83,9 @@ export function createProgram(io = { stdout: (text) => console.log(text), stderr
     registerRequestCommands(program, io);
     registerScanCommands(program, io);
     registerShadcnCommands(program, io);
+    registerSopCommands(program, io);
+    registerGateCommands(program, io);
+    registerHooksCommands(program, io);
     registerStatusLineCommands(program, io);
     registerUnderstandCommands(program, io);
     registerWorkspaceCommands(program, io);

package/dist/src/services/artifacts/artifact-lint-service.js

@@ -35,6 +35,15 @@ const ALLOWLIST_PATTERNS = [
 function isAllowlisted(line) {
     return ALLOWLIST_PATTERNS.some((pattern) => pattern.test(line));
 }
+/**
+ * Remove inline code spans (`...`) before applying placeholder rules. Content
+ * inside backticks is literal example text — e.g. a documented command syntax
+ * `peaks sop init <id>` — not an unfilled prose placeholder. Lint checks prose,
+ * not code, so a `<...>` token only counts when it appears outside code spans.
+ */
+function stripInlineCode(line) {
+    return line.replace(/`[^`]*`/g, '');
+}
 export async function lintRequestArtifact(options) {
     const showOptions = {
         projectRoot: options.projectRoot,
@@ -50,14 +59,24 @@ export async function lintRequestArtifact(options) {
     }
     const lines = artifact.content.split(/\r?\n/);
     const findings = [];
+    let insideFence = false;
     for (let index = 0; index < lines.length; index += 1) {
         const rawLine = lines[index];
         if (rawLine === undefined)
             continue;
+        // Fenced code blocks hold literal examples, not prose to fill; skip their
+        // contents entirely (the fence delimiters themselves toggle the state).
+        if (/^\s*```/.test(rawLine)) {
+            insideFence = !insideFence;
+            continue;
+        }
+        if (insideFence)
+            continue;
         if (isAllowlisted(rawLine))
             continue;
+        const testLine = stripInlineCode(rawLine);
         for (const rule of RULES) {
-            if (rule.test(rawLine)) {
+            if (rule.test(testLine)) {
                 findings.push({
                     line: index + 1,
                     text: rawLine.trim(),

package/dist/src/services/artifacts/artifact-prerequisites.js

@@ -1,5 +1,5 @@
-import { join } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { join, dirname, basename } from 'node:path';
+import { readFile, readdir } from 'node:fs/promises';
 import { pathExists } from '../../shared/fs.js';
 export const VALID_REQUEST_TYPES = [
     'feature',
@@ -111,6 +111,36 @@ export function getPrerequisitesFor(role, newState, requestType = DEFAULT_REQUES
 function resolvePrerequisitePath(prerequisite, requestId) {
     return prerequisite.relativePath.replace('<rid>', requestId);
 }
+/**
+ * Resolve a prerequisite to an on-disk path, tolerating the numbered filename
+ * prefix that `request init` writes (e.g. `001-<rid>.md`). When the prerequisite
+ * path contains `<rid>`, we accept either the legacy bare `<rid>.md` form or any
+ * `NNN-<rid>.md` numbered form — mirroring the matcher in request-artifact-service.
+ * Returns the matched absolute path, or null when nothing matches.
+ */
+async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, requestId) {
+    const relative = resolvePrerequisitePath(prerequisite, requestId);
+    const exact = join(sessionRoot, relative);
+    if (await pathExists(exact)) {
+        return exact;
+    }
+    // Only `<rid>`-templated prerequisites can carry a numbered prefix; fixed paths
+    // (e.g. rd/tech-doc.md) are matched exactly above.
+    if (!prerequisite.relativePath.includes('<rid>')) {
+        return null;
+    }
+    const dir = dirname(exact);
+    const targetSuffix = `-${basename(exact)}`;
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return null;
+    }
+    const match = entries.find((name) => /^\d+-/.test(name) && name.endsWith(targetSuffix));
+    return match ? join(dir, match) : null;
+}
 export async function checkPrerequisites(options) {
     const requirements = getPrerequisitesFor(options.role, options.newState, options.requestType);
     if (requirements.length === 0) {
@@ -120,8 +150,8 @@ export async function checkPrerequisites(options) {
     const missing = [];
     for (const prerequisite of requirements) {
         const relative = resolvePrerequisitePath(prerequisite, options.requestId);
-        const absolute = join(sessionRoot, relative);
-        if (!(await pathExists(absolute))) {
+        const absolute = await resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, options.requestId);
+        if (absolute === null) {
             missing.push({ path: relative, description: prerequisite.description });
             continue;
         }

package/dist/src/services/dashboard/project-dashboard-service.js

@@ -74,8 +74,10 @@ function buildCapabilitiesSummary(sampleSize) {
         }))
     };
 }
-function buildSkillPresenceSummary(presence) {
-    const resolved = presence === undefined ? getSkillPresence() : presence;
+function buildSkillPresenceSummary(presence, projectRoot) {
+    // When the caller doesn't supply presence, resolve it from the dashboard's
+    // project root rather than the process cwd.
+    const resolved = presence === undefined ? getSkillPresence(projectRoot) : presence;
     if (resolved === null) {
         return { active: false, fresh: true };
     }
@@ -126,6 +128,6 @@ export async function loadProjectDashboard(options) {
         doctor: doctorAndRunbook.doctor,
         runbookHealth: doctorAndRunbook.runbookHealth,
         capabilities: buildCapabilitiesSummary(sampleSize),
-        skillPresence: buildSkillPresenceSummary(options.skillPresence)
+        skillPresence: buildSkillPresenceSummary(options.skillPresence, options.projectRoot)
     };
 }

package/dist/src/services/mode/mode-enforcement.js

@@ -31,7 +31,8 @@ export class ConfirmationRequiredError extends Error {
     }
 }
 export async function requireUserConfirmation(options) {
-    const presence = getSkillPresence();
+    // Resolve presence from the project being operated on, not the process cwd.
+    const presence = getSkillPresence(options.projectRoot);
     if (!presence?.mode) {
         return;
     }

package/dist/src/services/scan/type-sanity-service.js

@@ -25,6 +25,16 @@ function classifyFile(filePath) {
         return 'source';
     return 'unknown';
 }
+/**
+ * Peaks' own artifact workspace. Changes here (PRD/RD/QA markdown, session
+ * state) are never the "code change" a request type describes, so they must be
+ * excluded from the diff — otherwise a PRD-planning-phase handoff that only
+ * wrote `.peaks/**` markdown would be misclassified as a docs change.
+ */
+function isArtifactWorkspaceFile(filePath) {
+    const normalized = filePath.replace(/\\/g, '/');
+    return normalized === '.peaks' || normalized.startsWith('.peaks/');
+}
 function tryGitDiffFiles(projectRoot, baseRef) {
     try {
         // Combine: tracked changes vs baseRef + untracked files. Use porcelain status for untracked too.
@@ -32,7 +42,7 @@ function tryGitDiffFiles(projectRoot, baseRef) {
         const tracked = trackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
         const untrackedRaw = execFileSync('git', ['-C', projectRoot, 'ls-files', '--others', '--exclude-standard'], { encoding: 'utf8' });
         const untracked = untrackedRaw.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-        const merged = Array.from(new Set([...tracked, ...untracked]));
+        const merged = Array.from(new Set([...tracked, ...untracked])).filter((file) => !isArtifactWorkspaceFile(file));
         return { ok: true, files: merged };
     }
     catch {

package/dist/src/services/skills/hooks-settings-service.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Installs (and removes) the Peaks gate-enforcement PreToolUse hook in a Claude
+ * Code settings.json. The hook runs `peaks gate enforce` before every Bash call;
+ * when a SOP guard's gates fail it returns `permissionDecision: "deny"`, which
+ * blocks the tool call BEFORE Claude Code's permission checks — making the gate
+ * un-bypassable by the agent (it holds even under --dangerously-skip-permissions).
+ *
+ * Installation is an EXPLICIT user command (never postinstall): skills describe,
+ * the CLI performs side effects. Writes preserve all other settings keys and any
+ * other hooks, reject symlinked targets, and use an atomic rename so a partial
+ * write can never corrupt the settings file. Our entry is merged into (not
+ * replacing) the existing `hooks.PreToolUse` array and is identified by a
+ * sentinel substring in its command, so install is idempotent and uninstall
+ * removes only our own entry.
+ */
+export type HookScope = 'project' | 'global';
+/** The hook command written into settings. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
+export declare const HOOK_ENFORCE_COMMAND = "peaks gate enforce --project \"${CLAUDE_PROJECT_DIR}\"";
+/** Substring that identifies a Peaks-managed PreToolUse hook entry. */
+export declare const HOOK_SENTINEL = "peaks gate enforce";
+export type HookInstallPlan = {
+    scope: HookScope;
+    settingsPath: string;
+    exists: boolean;
+    alreadyInstalled: boolean;
+    desiredCommand: string;
+};
+export type HookInstallResult = HookInstallPlan & {
+    applied: boolean;
+};
+export type HookRemoveResult = {
+    scope: HookScope;
+    settingsPath: string;
+    removed: boolean;
+};
+export type HookStatus = {
+    scope: HookScope;
+    settingsPath: string;
+    exists: boolean;
+    installed: boolean;
+};
+export declare function planHookInstall(scope: HookScope, projectRoot?: string): HookInstallPlan;
+export declare function applyHookInstall(scope: HookScope, projectRoot?: string): HookInstallResult;
+export declare function removeHookInstall(scope: HookScope, projectRoot?: string): HookRemoveResult;
+export declare function readHookStatus(scope: HookScope, projectRoot?: string): HookStatus;

package/dist/src/services/skills/hooks-settings-service.js

@@ -0,0 +1,167 @@
+import { closeSync, constants, existsSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { homedir } from 'node:os';
+/** The hook command written into settings. `${CLAUDE_PROJECT_DIR}` is injected by Claude Code. */
+export const HOOK_ENFORCE_COMMAND = 'peaks gate enforce --project "${CLAUDE_PROJECT_DIR}"';
+/** Substring that identifies a Peaks-managed PreToolUse hook entry. */
+export const HOOK_SENTINEL = 'peaks gate enforce';
+const HOOK_MATCHER = 'Bash';
+function isInsidePath(childPath, parentPath) {
+    const rel = relative(parentPath, childPath);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+}
+function resolveSettingsRoot(scope, projectRoot) {
+    if (scope === 'global')
+        return resolve(homedir());
+    if (!projectRoot) {
+        throw new Error('Project scope requires a project root');
+    }
+    return resolve(projectRoot);
+}
+function resolveSettingsPath(scope, projectRoot) {
+    return join(resolveSettingsRoot(scope, projectRoot), '.claude', 'settings.json');
+}
+function assertSafeSettingsPath(scope, root, settingsPath) {
+    const claudeDir = join(root, '.claude');
+    if (existsSync(claudeDir) && lstatSync(claudeDir).isSymbolicLink()) {
+        throw new Error('.claude directory must not be a symlink');
+    }
+    if (existsSync(settingsPath)) {
+        if (lstatSync(settingsPath).isSymbolicLink()) {
+            throw new Error('settings.json must not be a symlink');
+        }
+        const realRoot = realpathSync(root);
+        if (!isInsidePath(realpathSync(settingsPath), realRoot)) {
+            throw new Error(`settings.json must stay inside the ${scope} root`);
+        }
+    }
+}
+function readSettings(settingsPath) {
+    if (!existsSync(settingsPath))
+        return {};
+    const fd = openSync(settingsPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const raw = readFileSync(fd, 'utf8').trim();
+        if (raw.length === 0)
+            return {};
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('settings.json must contain a JSON object');
+        }
+        return parsed;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function atomicWriteJson(settingsPath, settings) {
+    const dir = dirname(settingsPath);
+    mkdirSync(dir, { recursive: true });
+    const tempPath = join(dir, `.settings.${randomUUID()}.tmp`);
+    const fd = openSync(tempPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(settings, null, 2)}\n`, 'utf8');
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tempPath, settingsPath);
+    }
+    catch (error) {
+        try {
+            unlinkSync(tempPath);
+        }
+        catch {
+            // best effort cleanup
+        }
+        throw error;
+    }
+}
+/** Read the existing PreToolUse matcher entries (tolerant of any prior shape). */
+function readPreToolUse(settings) {
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks))
+        return [];
+    const pre = hooks.PreToolUse;
+    return Array.isArray(pre) ? pre : [];
+}
+function entryIsPeaksManaged(entry) {
+    const handlers = Array.isArray(entry?.hooks) ? entry.hooks : [];
+    return handlers.length > 0 && handlers.every((h) => typeof h?.command === 'string' && h.command.includes(HOOK_SENTINEL));
+}
+function isInstalled(settings) {
+    return readPreToolUse(settings).some(entryIsPeaksManaged);
+}
+export function planHookInstall(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = readSettings(settingsPath);
+    return { scope, settingsPath, exists, alreadyInstalled: isInstalled(settings), desiredCommand: HOOK_ENFORCE_COMMAND };
+}
+/** Merge our PreToolUse entry into settings, preserving all other keys and hooks. */
+function withHookInstalled(settings) {
+    const existingHooks = (settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks))
+        ? settings.hooks
+        : {};
+    const preToolUse = readPreToolUse(settings);
+    const ourEntry = { matcher: HOOK_MATCHER, hooks: [{ type: 'command', command: HOOK_ENFORCE_COMMAND }] };
+    return {
+        ...settings,
+        hooks: { ...existingHooks, PreToolUse: [...preToolUse, ourEntry] }
+    };
+}
+export function applyHookInstall(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = readSettings(settingsPath);
+    if (isInstalled(settings)) {
+        return { scope, settingsPath, exists, alreadyInstalled: true, desiredCommand: HOOK_ENFORCE_COMMAND, applied: false };
+    }
+    atomicWriteJson(settingsPath, withHookInstalled(settings));
+    return { scope, settingsPath, exists, alreadyInstalled: false, desiredCommand: HOOK_ENFORCE_COMMAND, applied: true };
+}
+export function removeHookInstall(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    if (!existsSync(settingsPath)) {
+        return { scope, settingsPath, removed: false };
+    }
+    const settings = readSettings(settingsPath);
+    const preToolUse = readPreToolUse(settings);
+    const kept = preToolUse.filter((entry) => !entryIsPeaksManaged(entry));
+    if (kept.length === preToolUse.length) {
+        return { scope, settingsPath, removed: false };
+    }
+    const existingHooks = settings.hooks ?? {};
+    const nextHooks = { ...existingHooks };
+    if (kept.length > 0) {
+        nextHooks.PreToolUse = kept;
+    }
+    else {
+        delete nextHooks.PreToolUse;
+    }
+    const nextSettings = { ...settings };
+    if (Object.keys(nextHooks).length > 0) {
+        nextSettings.hooks = nextHooks;
+    }
+    else {
+        delete nextSettings.hooks;
+    }
+    atomicWriteJson(settingsPath, nextSettings);
+    return { scope, settingsPath, removed: true };
+}
+export function readHookStatus(scope, projectRoot) {
+    const root = resolveSettingsRoot(scope, projectRoot);
+    const settingsPath = resolveSettingsPath(scope, projectRoot);
+    assertSafeSettingsPath(scope, root, settingsPath);
+    const exists = existsSync(settingsPath);
+    const settings = exists ? readSettings(settingsPath) : {};
+    return { scope, settingsPath, exists, installed: isInstalled(settings) };
+}

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>;

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