peaks-cli 1.1.2 → 1.2.0

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

package/dist/src/services/sop/sop-advance-service.d.ts

@@ -0,0 +1,74 @@
+import type { SopCheckResult } from './sop-types.js';
+/**
+ * SOP phase advancement with gate enforcement — Feature A, Slice 3 (range 3).
+ *
+ * `advanceSop` moves a SOP to a target phase only if (a) the move does not skip
+ * ahead in the declared phase order, and (b) every gate guarding that phase
+ * passes. A forward skip throws SopPhaseSkipError (SOP_PHASE_SKIP); a
+ * fail/blocked gate throws SopGateBlockedError (SOP_GATE_BLOCKED). Both block
+ * UNCONDITIONALLY in all modes — a gate is an objective check, not a
+ * confirmation prompt, so a mode could never silently skip it (that would
+ * defeat "don't drop steps"). The only escape is an explicit bypass
+ * (allowIncomplete), which the CLI gates behind --reason / --confirm / a cap.
+ *
+ * The SOP *definition* is global (`~/.peaks/sops/`), but run-state is
+ * PER-PROJECT (`<project>/.peaks/sop-state/<id>.json`) so the same authored SOP
+ * tracks independent progress in every project it runs in.
+ *
+ * This is a standalone command path: it does NOT touch the built-in request
+ * artifact transition machinery or mode-enforcement, so those keep their exact
+ * behavior (preserved behavior P2/P3).
+ */
+export type BlockedGate = {
+    gateId: string;
+    result: SopCheckResult;
+    reason?: string;
+};
+export type SopHistoryEntry = {
+    phase: string;
+    bypassed: boolean;
+    reason?: string;
+};
+export type SopState = {
+    currentPhase: string | null;
+    history: SopHistoryEntry[];
+};
+export type AdvanceSopResult = {
+    id: string;
+    phase: string;
+    bypassed: boolean;
+    previousPhase: string | null;
+    /** false when --dry-run evaluated the gates without recording the advance. */
+    applied: boolean;
+};
+export type AdvanceSopOptions = {
+    projectRoot: string;
+    id: string;
+    toPhase: string;
+    allowCommands?: boolean;
+    allowIncomplete?: boolean;
+    reason?: string;
+    commandTimeoutMs?: number;
+    /** Evaluate gates (still blocks on failure) but do not write state.json. */
+    dryRun?: boolean;
+};
+export declare class SopAdvanceError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class SopGateBlockedError extends Error {
+    readonly code = "SOP_GATE_BLOCKED";
+    readonly blockedGates: BlockedGate[];
+    constructor(toPhase: string, blockedGates: BlockedGate[]);
+}
+export declare class SopPhaseSkipError extends Error {
+    readonly code = "SOP_PHASE_SKIP";
+    readonly fromPhase: string | null;
+    readonly toPhase: string;
+    readonly expectedNext: string;
+    constructor(fromPhase: string | null, toPhase: string, expectedNext: string);
+}
+declare const EMPTY_STATE: SopState;
+export declare function readSopState(projectRoot: string, id: string): Promise<SopState>;
+export declare function advanceSop(options: AdvanceSopOptions): Promise<AdvanceSopResult>;
+export { EMPTY_STATE };