peaks-cli 1.1.2 → 1.2.1

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

package/dist/src/services/sop/sop-advance-service.js

@@ -0,0 +1,115 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { readSopManifest } from './sop-service.js';
+import { sopStatePath } from './sop-paths.js';
+import { evaluateGate } from './sop-check-service.js';
+export class SopAdvanceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SopAdvanceError';
+        this.code = code;
+    }
+}
+export class SopGateBlockedError extends Error {
+    code = 'SOP_GATE_BLOCKED';
+    blockedGates;
+    constructor(toPhase, blockedGates) {
+        super(`Cannot advance to "${toPhase}": ${blockedGates.length} gate(s) not satisfied (${blockedGates.map((g) => `${g.gateId}=${g.result}`).join(', ')})`);
+        this.name = 'SopGateBlockedError';
+        this.blockedGates = blockedGates;
+    }
+}
+export class SopPhaseSkipError extends Error {
+    code = 'SOP_PHASE_SKIP';
+    fromPhase;
+    toPhase;
+    expectedNext;
+    constructor(fromPhase, toPhase, expectedNext) {
+        super(`Cannot advance to "${toPhase}": it skips ahead of the declared phase order (current: ${fromPhase ?? 'none'}, next allowed: ${expectedNext}). Bypass with --allow-incomplete --reason "<why>" if you really must skip.`);
+        this.name = 'SopPhaseSkipError';
+        this.fromPhase = fromPhase;
+        this.toPhase = toPhase;
+        this.expectedNext = expectedNext;
+    }
+}
+const EMPTY_STATE = { currentPhase: null, history: [] };
+export async function readSopState(projectRoot, id) {
+    const path = sopStatePath(projectRoot, id);
+    if (!existsSync(path)) {
+        return { currentPhase: null, history: [] };
+    }
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    return {
+        currentPhase: typeof parsed.currentPhase === 'string' ? parsed.currentPhase : null,
+        history: Array.isArray(parsed.history) ? parsed.history : []
+    };
+}
+/**
+ * Enforce declared phase order: a move may stay put, step back, or advance to
+ * the immediately-next phase, but must not skip ahead. `currentPhase: null`
+ * (never advanced) is treated as index -1, so only the first phase is reachable.
+ * Throws SopPhaseSkipError on a forward skip.
+ */
+function assertNoPhaseSkip(phases, currentPhase, toPhase) {
+    const currentIndex = currentPhase === null ? -1 : phases.indexOf(currentPhase);
+    const targetIndex = phases.indexOf(toPhase);
+    // A current phase that is no longer declared (hand-edited manifest) cannot
+    // anchor order; fall back to "first phase only" rather than silently allowing.
+    const anchorIndex = currentIndex >= 0 ? currentIndex : -1;
+    if (targetIndex > anchorIndex + 1) {
+        // A forward skip means anchorIndex + 1 < targetIndex ≤ phases.length - 1,
+        // so the next phase always exists — no fallback branch needed.
+        const expectedNext = phases[anchorIndex + 1];
+        throw new SopPhaseSkipError(currentPhase, toPhase, expectedNext);
+    }
+}
+export async function advanceSop(options) {
+    const manifest = await readSopManifest(options.id, options.projectRoot);
+    if (manifest === null) {
+        throw new SopAdvanceError('SOP_NOT_FOUND', `No SOP found for id "${options.id}"`);
+    }
+    if (!manifest.phases.includes(options.toPhase)) {
+        throw new SopAdvanceError('INVALID_PHASE', `Phase "${options.toPhase}" is not declared by SOP "${options.id}"`);
+    }
+    const previous = await readSopState(options.projectRoot, options.id);
+    const phaseGates = manifest.gates.filter((gate) => gate.phase === options.toPhase);
+    if (options.allowIncomplete !== true) {
+        // Structural check first: a forward skip is invalid regardless of gate state.
+        assertNoPhaseSkip(manifest.phases, previous.currentPhase, options.toPhase);
+        const evaluateOptions = {};
+        if (options.allowCommands !== undefined)
+            evaluateOptions.allowCommands = options.allowCommands;
+        if (options.commandTimeoutMs !== undefined)
+            evaluateOptions.commandTimeoutMs = options.commandTimeoutMs;
+        const blocked = [];
+        for (const gate of phaseGates) {
+            const verdict = evaluateGate(options.projectRoot, gate, evaluateOptions);
+            if (verdict.result !== 'pass') {
+                blocked.push(verdict.reason === undefined
+                    ? { gateId: gate.id, result: verdict.result }
+                    : { gateId: gate.id, result: verdict.result, reason: verdict.reason });
+            }
+        }
+        if (blocked.length > 0) {
+            throw new SopGateBlockedError(options.toPhase, blocked);
+        }
+    }
+    const bypassed = options.allowIncomplete === true;
+    if (options.dryRun === true) {
+        return { id: options.id, phase: options.toPhase, bypassed, previousPhase: previous.currentPhase, applied: false };
+    }
+    const entry = options.reason === undefined
+        ? { phase: options.toPhase, bypassed }
+        : { phase: options.toPhase, bypassed, reason: options.reason };
+    const nextState = {
+        currentPhase: options.toPhase,
+        history: [...previous.history, entry]
+    };
+    const path = sopStatePath(options.projectRoot, options.id);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(nextState, null, 2)}\n`, 'utf8');
+    return { id: options.id, phase: options.toPhase, bypassed, previousPhase: previous.currentPhase, applied: true };
+}
+export { EMPTY_STATE };

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

@@ -0,0 +1,29 @@
+import type { SopGate, SopCheckResult } from './sop-types.js';
+export type GateVerdict = {
+    result: SopCheckResult;
+    reason?: string;
+};
+export type CheckGateResult = GateVerdict & {
+    id: string;
+    gateId: string;
+    phase: string;
+};
+export type CheckGateOptions = {
+    projectRoot: string;
+    id: string;
+    gateId: string;
+    allowCommands?: boolean;
+    /** Override the command-gate timeout (ms). Defaults to GATE_COMMAND_TIMEOUT_MS. */
+    commandTimeoutMs?: number;
+};
+export declare class SopCheckError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type EvaluateGateOptions = {
+    allowCommands?: boolean;
+    commandTimeoutMs?: number;
+};
+/** Evaluate a single gate's check to a pass/fail/blocked verdict. Shared by `sop check` and `sop advance`. */
+export declare function evaluateGate(projectRoot: string, gate: SopGate, options?: EvaluateGateOptions): GateVerdict;
+export declare function checkGate(options: CheckGateOptions): Promise<CheckGateResult>;

package/dist/src/services/sop/sop-check-service.js

@@ -0,0 +1,148 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { isInsidePath } from '../../shared/path-utils.js';
+import { readSopManifest } from './sop-service.js';
+/**
+ * SOP gate evaluation — Feature A, Slice 2.
+ *
+ * Evaluates a single gate to one of three verdicts: pass / fail / blocked.
+ * "blocked" means the check could not be evaluated (e.g. unreadable target,
+ * command not permitted, spawn failure) — a verdict, not an error. Only an
+ * inability to start (SOP/gate missing) is an evaluator error.
+ *
+ * Security (OQ3/R1): command gates run via execFileSync with an argv array and
+ * NO shell (no injection), a hard timeout, and cwd set to the project, and they
+ * are refused unless explicitly permitted. file-exists/grep targets are pinned
+ * inside the project root. NOTE: the command executable itself is NOT
+ * sandboxed — a command gate can invoke any binary on the machine. The trust
+ * boundary is "whoever authored the SOP"; --allow-commands is the gate.
+ */
+const GATE_COMMAND_TIMEOUT_MS = 30_000;
+export class SopCheckError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SopCheckError';
+        this.code = code;
+    }
+}
+/** Resolve a user-authored relative path and require it to stay inside the project. */
+function resolveInsideProject(projectRoot, target) {
+    const root = resolve(projectRoot);
+    const resolved = resolve(root, target);
+    return isInsidePath(resolved, root) ? resolved : null;
+}
+function evaluateFileExists(projectRoot, path) {
+    const resolved = resolveInsideProject(projectRoot, path);
+    if (resolved === null) {
+        return { result: 'blocked', reason: `path "${path}" escapes the project root` };
+    }
+    return existsSync(resolved) ? { result: 'pass' } : { result: 'fail', reason: `file "${path}" does not exist` };
+}
+function evaluateGrep(projectRoot, file, pattern, absent) {
+    const resolved = resolveInsideProject(projectRoot, file);
+    if (resolved === null) {
+        return { result: 'blocked', reason: `file "${file}" escapes the project root` };
+    }
+    if (!existsSync(resolved)) {
+        return { result: 'blocked', reason: `file "${file}" cannot be read` };
+    }
+    let regex;
+    try {
+        regex = new RegExp(pattern);
+    }
+    catch {
+        return { result: 'blocked', reason: `invalid grep pattern "${pattern}"` };
+    }
+    let content;
+    try {
+        content = readFileSync(resolved, 'utf8');
+    }
+    catch {
+        return { result: 'blocked', reason: `file "${file}" cannot be read` };
+    }
+    const found = regex.test(content);
+    // absent gate: pass when the pattern is NOT present ("must not contain X").
+    const pass = absent ? !found : found;
+    if (pass) {
+        return { result: 'pass' };
+    }
+    return absent
+        ? { result: 'fail', reason: `pattern "${pattern}" must be absent but was found in "${file}"` }
+        : { result: 'fail', reason: `pattern "${pattern}" not found in "${file}"` };
+}
+function evaluateCommand(projectRoot, run, expectExitZero, allowCommands, timeoutMs) {
+    if (!allowCommands) {
+        return { result: 'blocked', reason: 'command checks require --allow-commands' };
+    }
+    // Manifests reach here unvalidated (checkGate/advanceSop don't pre-lint), so
+    // guard the untrusted shape rather than assert run[0]; an empty run is a
+    // blocked verdict, not a thrown evaluator error.
+    const [bin, ...args] = run;
+    if (bin === undefined) {
+        return { result: 'blocked', reason: 'command gate has no executable' };
+    }
+    let exitCode;
+    try {
+        execFileSync(bin, args, { cwd: resolve(projectRoot), timeout: timeoutMs, stdio: 'ignore' });
+        exitCode = 0;
+    }
+    catch (error) {
+        const err = error;
+        // Timeout surfaces as ETIMEDOUT on some platforms and killed+SIGTERM on others.
+        if (err.code === 'ETIMEDOUT' || err.killed === true) {
+            return { result: 'blocked', reason: `command timed out after ${timeoutMs}ms` };
+        }
+        if (typeof err.status === 'number') {
+            exitCode = err.status;
+        }
+        else {
+            return { result: 'blocked', reason: `command could not be run (${String(err.code ?? 'spawn error')})` };
+        }
+    }
+    const zero = exitCode === 0;
+    const pass = expectExitZero ? zero : !zero;
+    return pass ? { result: 'pass' } : { result: 'fail', reason: `command exited ${exitCode} (expectExitZero=${expectExitZero})` };
+}
+function evaluateCheck(projectRoot, check, allowCommands, timeoutMs) {
+    switch (check.type) {
+        case 'file-exists':
+            return evaluateFileExists(projectRoot, check.path);
+        case 'grep':
+            return evaluateGrep(projectRoot, check.file, check.pattern, check.absent === true);
+        case 'command':
+            return evaluateCommand(projectRoot, check.run, check.expectExitZero !== false, allowCommands, timeoutMs);
+        default:
+            return { result: 'blocked', reason: 'unknown check type' };
+    }
+}
+/** Evaluate a single gate's check to a pass/fail/blocked verdict. Shared by `sop check` and `sop advance`. */
+export function evaluateGate(projectRoot, gate, options = {}) {
+    return evaluateCheck(projectRoot, gate.check, options.allowCommands === true, options.commandTimeoutMs ?? GATE_COMMAND_TIMEOUT_MS);
+}
+export async function checkGate(options) {
+    // Resolve the definition project-first then global; the gate's check still
+    // evaluates against options.projectRoot.
+    const manifest = await readSopManifest(options.id, options.projectRoot);
+    if (manifest === null) {
+        throw new SopCheckError('SOP_NOT_FOUND', `No SOP found for id "${options.id}"`);
+    }
+    const gate = manifest.gates.find((candidate) => candidate.id === options.gateId);
+    if (gate === undefined) {
+        throw new SopCheckError('GATE_NOT_FOUND', `Gate "${options.gateId}" not found in SOP "${options.id}"`);
+    }
+    const evaluateOptions = {};
+    if (options.allowCommands !== undefined) {
+        evaluateOptions.allowCommands = options.allowCommands;
+    }
+    if (options.commandTimeoutMs !== undefined) {
+        evaluateOptions.commandTimeoutMs = options.commandTimeoutMs;
+    }
+    const verdict = evaluateGate(options.projectRoot, gate, evaluateOptions);
+    const result = { id: options.id, gateId: gate.id, phase: gate.phase, result: verdict.result };
+    if (verdict.reason !== undefined) {
+        result.reason = verdict.reason;
+    }
+    return result;
+}

package/dist/src/services/sop/sop-paths.d.ts

@@ -0,0 +1,62 @@
+/**
+ * SOP path model — two definition layers + per-project run-state.
+ *
+ * A SOP *definition* (manifest + SKILL.md) and its registry can live in two
+ * layers:
+ *   - GLOBAL (`~/.peaks/sops/`): your personal SOPs, reusable across every
+ *     project on this machine.
+ *   - PROJECT (`<project>/.peaks/sops/`): committed into the repo, so a teammate
+ *     who clones it gets the SOP — and, with the gate hook installed, is enforced
+ *     too. The project layer takes PRECEDENCE over global for the same id.
+ *
+ * A SOP's *run-state* (current phase, bypass history) always lives under the
+ * project it runs in (`<project>/.peaks/sop-state/<id>/`), so the same SOP tracks
+ * independent progress per project. Gate checks resolve their target paths
+ * against the caller's `--project`, which is what makes a relative gate path
+ * (`posts/current.md`) reusable across projects.
+ *
+ * `PEAKS_HOME` overrides the global root; tests inject a temp dir through it so
+ * a unit test never reads or writes the real `~/.peaks`.
+ */
+export type SopScope = 'project' | 'global';
+/** Global Peaks home (`~/.peaks`), overridable via PEAKS_HOME for test isolation. */
+export declare function peaksHome(): string;
+/** Global SOP definition directory: `~/.peaks/sops/<id>`. */
+export declare function sopDir(id: string): string;
+/** Global SOP manifest: `~/.peaks/sops/<id>/sop.json`. */
+export declare function sopManifestPath(id: string): string;
+/** Global SOP skill: `~/.peaks/sops/<id>/SKILL.md`. */
+export declare function sopSkillPath(id: string): string;
+/** Global registry of all registered SOPs: `~/.peaks/sops/registry.json`. */
+export declare function registryPath(): string;
+/** Project SOP definition directory: `<project>/.peaks/sops/<id>` (committed, team-shared). */
+export declare function projectSopDir(projectRoot: string, id: string): string;
+/** Project SOP manifest: `<project>/.peaks/sops/<id>/sop.json`. */
+export declare function projectSopManifestPath(projectRoot: string, id: string): string;
+/** Project SOP skill: `<project>/.peaks/sops/<id>/SKILL.md`. */
+export declare function projectSopSkillPath(projectRoot: string, id: string): string;
+/** Project registry: `<project>/.peaks/sops/registry.json` (committed, team-shared). */
+export declare function projectRegistryPath(projectRoot: string): string;
+/** Definition directory for a scope. */
+export declare function scopedSopDir(scope: SopScope, projectRoot: string | undefined, id: string): string;
+/** Manifest path for a scope. */
+export declare function scopedSopManifestPath(scope: SopScope, projectRoot: string | undefined, id: string): string;
+/** Registry path for a scope. */
+export declare function scopedRegistryPath(scope: SopScope, projectRoot: string | undefined): string;
+/**
+ * Resolve where a SOP's manifest lives, project-first: the project layer wins
+ * when present, otherwise global. Returns null when neither layer has it.
+ */
+export declare function resolveSopManifestPath(id: string, projectRoot?: string): {
+    path: string;
+    scope: SopScope;
+} | null;
+/**
+ * Per-project run-state directory for a SOP: `<project>/.peaks/sop-state/<id>/`.
+ * Holds `state.json` (current phase + history) and the bypass counter, so a
+ * SOP's execution data stays isolated per project even though its definition is
+ * global.
+ */
+export declare function sopStateDir(projectRoot: string, id: string): string;
+/** Per-project run-state file for a SOP: `<project>/.peaks/sop-state/<id>/state.json`. */
+export declare function sopStatePath(projectRoot: string, id: string): string;