peaks-cli 1.1.2 → 1.2.0

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;

package/dist/src/services/sop/sop-paths.js

@@ -0,0 +1,92 @@
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+/** Global Peaks home (`~/.peaks`), overridable via PEAKS_HOME for test isolation. */
+export function peaksHome() {
+    const override = process.env.PEAKS_HOME;
+    return override !== undefined && override.length > 0 ? resolve(override) : join(homedir(), '.peaks');
+}
+/** Global SOP definition directory: `~/.peaks/sops/<id>`. */
+export function sopDir(id) {
+    return join(peaksHome(), 'sops', id);
+}
+/** Global SOP manifest: `~/.peaks/sops/<id>/sop.json`. */
+export function sopManifestPath(id) {
+    return join(sopDir(id), 'sop.json');
+}
+/** Global SOP skill: `~/.peaks/sops/<id>/SKILL.md`. */
+export function sopSkillPath(id) {
+    return join(sopDir(id), 'SKILL.md');
+}
+/** Global registry of all registered SOPs: `~/.peaks/sops/registry.json`. */
+export function registryPath() {
+    return join(peaksHome(), 'sops', 'registry.json');
+}
+/** Project SOP definition directory: `<project>/.peaks/sops/<id>` (committed, team-shared). */
+export function projectSopDir(projectRoot, id) {
+    return join(projectRoot, '.peaks', 'sops', id);
+}
+/** Project SOP manifest: `<project>/.peaks/sops/<id>/sop.json`. */
+export function projectSopManifestPath(projectRoot, id) {
+    return join(projectSopDir(projectRoot, id), 'sop.json');
+}
+/** Project SOP skill: `<project>/.peaks/sops/<id>/SKILL.md`. */
+export function projectSopSkillPath(projectRoot, id) {
+    return join(projectSopDir(projectRoot, id), 'SKILL.md');
+}
+/** Project registry: `<project>/.peaks/sops/registry.json` (committed, team-shared). */
+export function projectRegistryPath(projectRoot) {
+    return join(projectRoot, '.peaks', 'sops', 'registry.json');
+}
+/** Definition directory for a scope. */
+export function scopedSopDir(scope, projectRoot, id) {
+    if (scope === 'project') {
+        if (projectRoot === undefined)
+            throw new Error('Project scope requires a project root');
+        return projectSopDir(projectRoot, id);
+    }
+    return sopDir(id);
+}
+/** Manifest path for a scope. */
+export function scopedSopManifestPath(scope, projectRoot, id) {
+    return join(scopedSopDir(scope, projectRoot, id), 'sop.json');
+}
+/** Registry path for a scope. */
+export function scopedRegistryPath(scope, projectRoot) {
+    if (scope === 'project') {
+        if (projectRoot === undefined)
+            throw new Error('Project scope requires a project root');
+        return projectRegistryPath(projectRoot);
+    }
+    return registryPath();
+}
+/**
+ * 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 function resolveSopManifestPath(id, projectRoot) {
+    if (projectRoot !== undefined) {
+        const projectPath = projectSopManifestPath(projectRoot, id);
+        if (existsSync(projectPath)) {
+            return { path: projectPath, scope: 'project' };
+        }
+    }
+    const globalPath = sopManifestPath(id);
+    if (existsSync(globalPath)) {
+        return { path: globalPath, scope: 'global' };
+    }
+    return 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 function sopStateDir(projectRoot, id) {
+    return join(projectRoot, '.peaks', 'sop-state', id);
+}
+/** Per-project run-state file for a SOP: `<project>/.peaks/sop-state/<id>/state.json`. */
+export function sopStatePath(projectRoot, id) {
+    return join(sopStateDir(projectRoot, id), 'state.json');
+}

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

@@ -0,0 +1,46 @@
+import { type SopScope } from './sop-paths.js';
+import type { RegisteredSop, SopRegistry } from './sop-types.js';
+/**
+ * SOP gate registry — Feature A (Slice 2) + team layer (Slice 4b).
+ *
+ * `registerSop` validates a SOP (must lint clean) then upserts its gates into a
+ * registry. SOPs live in two layers: GLOBAL (`~/.peaks/sops/registry.json`, your
+ * personal SOPs) and PROJECT (`<project>/.peaks/sops/registry.json`, committed
+ * into the repo so teammates get them). `registerSop` writes to the layer the
+ * caller targets (project when `projectRoot` is set, else global). `readRegistry`
+ * returns the MERGED view (project entries win over global by id) so execution
+ * and enumeration see every applicable SOP. The registry is the single
+ * enumerable, countable source a future metering layer (Feature B) reads; this
+ * slice only records and counts — NO limit, tier, or billing logic. Built-in
+ * peaks-* gates are never recorded here.
+ */
+export type RegisterSopResult = {
+    id: string;
+    registered: RegisteredSop;
+    /** Total gates across all registered SOPs after this upsert (the workspace pool count). */
+    gateCount: number;
+    /** Which layer the SOP was registered into. */
+    scope: SopScope;
+    /** false when --dry-run previewed the registration without writing registry.json. */
+    applied: boolean;
+};
+export type RegisterSopOptions = {
+    id: string;
+    allowCommands?: boolean;
+    /** Preview the registration without writing registry.json. */
+    dryRun?: boolean;
+    /** When set, register into the project layer (`<projectRoot>/.peaks/sops`) instead of global. */
+    projectRoot?: string;
+};
+/**
+ * Read the registry that execution/enumeration should see: the MERGED view of
+ * the project layer (when projectRoot is given) over the global layer — a
+ * project entry wins over a global one with the same id. Without projectRoot,
+ * the global registry only.
+ */
+export declare function readRegistry(projectRoot?: string): Promise<SopRegistry>;
+export declare class SopRegisterError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function registerSop(options: RegisterSopOptions): Promise<RegisterSopResult>;

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

@@ -0,0 +1,89 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { lintSop } from './sop-service.js';
+import { scopedRegistryPath, scopedSopManifestPath } from './sop-paths.js';
+/** Manifest location relative to its Peaks home (`~/.peaks/` or `<project>/.peaks/`). Machine-independent. */
+function relativeManifestPath(id) {
+    return `sops/${id}/sop.json`;
+}
+function countGates(sops) {
+    // Tolerate a hand-edited / corrupted registry: a malformed entry counts as 0
+    // gates rather than crashing the read-only `sop registry` command.
+    return sops.reduce((total, sop) => total + (Array.isArray(sop?.gates) ? sop.gates.length : 0), 0);
+}
+/** Read a single registry layer; empty when absent. Throws on corrupt JSON. */
+async function readRegistryAt(scope, projectRoot) {
+    if (scope === 'project' && projectRoot === undefined) {
+        return [];
+    }
+    const path = scopedRegistryPath(scope, projectRoot);
+    if (!existsSync(path)) {
+        return [];
+    }
+    const parsed = JSON.parse(await readFile(path, 'utf8'));
+    return Array.isArray(parsed.sops) ? parsed.sops : [];
+}
+/**
+ * Read the registry that execution/enumeration should see: the MERGED view of
+ * the project layer (when projectRoot is given) over the global layer — a
+ * project entry wins over a global one with the same id. Without projectRoot,
+ * the global registry only.
+ */
+export async function readRegistry(projectRoot) {
+    const globalSops = await readRegistryAt('global', undefined);
+    const projectSops = projectRoot !== undefined ? await readRegistryAt('project', projectRoot) : [];
+    const byId = new Map();
+    for (const sop of globalSops)
+        byId.set(sop.id, sop);
+    for (const sop of projectSops)
+        byId.set(sop.id, sop); // project wins
+    const sops = [...byId.values()].sort((left, right) => left.id.localeCompare(right.id));
+    return { version: 1, sops, gateCount: countGates(sops) };
+}
+export class SopRegisterError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'SopRegisterError';
+        this.code = code;
+    }
+}
+export async function registerSop(options) {
+    const scope = options.projectRoot !== undefined ? 'project' : 'global';
+    // Register the EXACT layer the caller targets — not the precedence resolution.
+    const manifestPath = scopedSopManifestPath(scope, options.projectRoot, options.id);
+    if (!existsSync(manifestPath)) {
+        throw new SopRegisterError('SOP_NOT_FOUND', `No SOP found for id "${options.id}"`);
+    }
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    const lintOptions = { id: options.id };
+    if (options.allowCommands === true)
+        lintOptions.allowCommands = true;
+    if (options.projectRoot !== undefined)
+        lintOptions.projectRoot = options.projectRoot;
+    const lint = await lintSop(lintOptions);
+    if (lint === null || !lint.ok) {
+        throw new SopRegisterError('SOP_INVALID', `SOP "${options.id}" must lint clean before it can be registered`);
+    }
+    const gates = manifest.gates.map((gate) => ({
+        ref: `${manifest.id}/${gate.id}`,
+        gateId: gate.id,
+        sopId: manifest.id,
+        phase: gate.phase,
+        transition: `${manifest.id}:${gate.phase}`
+    }));
+    const registered = { id: manifest.id, path: relativeManifestPath(manifest.id), gates };
+    // Upsert within the SAME layer's registry (not the merged view).
+    const current = await readRegistryAt(scope, options.projectRoot);
+    const others = current.filter((sop) => sop.id !== manifest.id);
+    const sops = [...others, registered].sort((left, right) => left.id.localeCompare(right.id));
+    const registry = { version: 1, sops, gateCount: countGates(sops) };
+    if (options.dryRun === true) {
+        return { id: manifest.id, registered, gateCount: registry.gateCount, scope, applied: false };
+    }
+    const path = scopedRegistryPath(scope, options.projectRoot);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(registry, null, 2)}\n`, 'utf8');
+    return { id: manifest.id, registered, gateCount: registry.gateCount, scope, applied: true };
+}

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

@@ -0,0 +1,47 @@
+import { type SopManifest } from './sop-types.js';
+export type SopInitOptions = {
+    id: string;
+    name?: string;
+    apply?: boolean;
+    /** When set, scaffold into the project layer (`<projectRoot>/.peaks/sops`) instead of global. */
+    projectRoot?: string;
+};
+export type SopInitResult = {
+    id: string;
+    dir: string;
+    manifestPath: string;
+    skillPath: string;
+    manifest: SopManifest;
+    skillContent: string;
+    applied: boolean;
+};
+export type SopLintSeverity = 'error' | 'warning';
+export type SopLintFinding = {
+    code: string;
+    message: string;
+    gateId?: string;
+    severity: SopLintSeverity;
+};
+export type SopLintResult = {
+    ok: boolean;
+    id: string;
+    manifestPath: string;
+    gateCount: number;
+    gateIds: string[];
+    findings: SopLintFinding[];
+};
+export type SopLintOptions = {
+    id: string;
+    /** `command`-type gates run shell-less processes; require explicit opt-in (OQ3 security). */
+    allowCommands?: boolean;
+    /** When set, lint the project-layer manifest (`<projectRoot>/.peaks/sops`) instead of global. */
+    projectRoot?: string;
+};
+/**
+ * Read and JSON-parse a SOP manifest for EXECUTION, resolving project-first then
+ * global (the project layer wins). Returns null when neither layer has it;
+ * throws on malformed JSON. Callers that need validation should run lintSop.
+ */
+export declare function readSopManifest(id: string, projectRoot?: string): Promise<SopManifest | null>;
+export declare function initSop(options: SopInitOptions): Promise<SopInitResult>;
+export declare function lintSop(options: SopLintOptions): Promise<SopLintResult | null>;