peaks-cli 1.1.2 → 1.2.1

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

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

@@ -0,0 +1,211 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { SOP_GATE_CHECK_TYPES, SOP_ID_PATTERN } from './sop-types.js';
+import { sopDir, sopManifestPath, sopSkillPath, projectSopDir, projectSopManifestPath, projectSopSkillPath, resolveSopManifestPath } from './sop-paths.js';
+/**
+ * SOP authoring substrate — Feature A, Slice 1.
+ *
+ * `initSop` scaffolds a user-authored SOP (manifest + registrable SKILL.md);
+ * `lintSop` validates the manifest. No registry, no enforcement here — Slice 1
+ * only lets users create and validate a SOP. The SOP id grammar
+ * (SOP_ID_PATTERN: lowercase kebab, no dots/slashes) doubles as the path
+ * traversal guard, matching how request artifacts guard their ids.
+ *
+ * SOP definitions are GLOBAL (`~/.peaks/sops/<id>/`, see ./sop-paths) so one
+ * authored SOP is reusable across projects; only run-state is per-project. The
+ * authoring ops here therefore take no projectRoot.
+ */
+const RESERVED_ID_PREFIX = 'peaks-';
+const RESERVED_IDS = new Set(['peaks']);
+/**
+ * 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 async function readSopManifest(id, projectRoot) {
+    const resolved = resolveSopManifestPath(id, projectRoot);
+    if (resolved === null) {
+        return null;
+    }
+    return JSON.parse(await readFile(resolved.path, 'utf8'));
+}
+/** Why an id cannot be used; null when the id is acceptable. */
+function reservedIdReason(id) {
+    if (id.startsWith(RESERVED_ID_PREFIX) || RESERVED_IDS.has(id)) {
+        return `SOP id "${id}" collides with the reserved built-in peaks-* namespace`;
+    }
+    return null;
+}
+function scaffoldManifest(id, name) {
+    return {
+        id,
+        name,
+        description: '',
+        phases: ['draft', 'review', 'done'],
+        gates: [
+            { id: 'example-gate', phase: 'review', check: { type: 'file-exists', path: 'README.md' } }
+        ]
+    };
+}
+function scaffoldSkill(manifest) {
+    const phaseList = manifest.phases.join(' → ');
+    return [
+        '---',
+        `name: ${manifest.id}`,
+        `description: User-authored Peaks SOP "${manifest.name}". Phases: ${phaseList}.`,
+        '---',
+        '',
+        `# ${manifest.name}`,
+        '',
+        'A user-authored SOP. Edit `sop.json` to define phases and gates, then run',
+        '`peaks sop lint` to validate it.',
+        '',
+        '## Phases',
+        '',
+        ...manifest.phases.map((phase) => `- ${phase}`),
+        ''
+    ].join('\n');
+}
+export async function initSop(options) {
+    if (!SOP_ID_PATTERN.test(options.id)) {
+        throw new Error(`Invalid SOP id: ${options.id} (expected lowercase letters, digits, and dashes, starting alphanumeric)`);
+    }
+    const reserved = reservedIdReason(options.id);
+    if (reserved !== null) {
+        throw new Error(reserved);
+    }
+    const inProject = options.projectRoot !== undefined;
+    const dir = inProject ? projectSopDir(options.projectRoot, options.id) : sopDir(options.id);
+    const manifestPath = inProject ? projectSopManifestPath(options.projectRoot, options.id) : sopManifestPath(options.id);
+    const skillPath = inProject ? projectSopSkillPath(options.projectRoot, options.id) : sopSkillPath(options.id);
+    if (existsSync(manifestPath)) {
+        throw new Error(`A SOP with id "${options.id}" already exists at ${manifestPath}. Remove it before re-running peaks sop init.`);
+    }
+    const manifest = scaffoldManifest(options.id, options.name ?? options.id);
+    const skillContent = scaffoldSkill(manifest);
+    const result = {
+        id: options.id,
+        dir,
+        manifestPath,
+        skillPath,
+        manifest,
+        skillContent,
+        applied: false
+    };
+    if (options.apply !== true) {
+        return result;
+    }
+    await mkdir(dir, { recursive: true });
+    await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    await writeFile(skillPath, skillContent, 'utf8');
+    return { ...result, applied: true };
+}
+function pushError(findings, code, message, gateId) {
+    findings.push(gateId === undefined ? { code, message, severity: 'error' } : { code, message, gateId, severity: 'error' });
+}
+function lintGate(gate, index, phases, seenGateIds, allowCommands, findings) {
+    const label = typeof gate?.id === 'string' && gate.id.length > 0 ? gate.id : `#${index}`;
+    if (typeof gate?.id !== 'string' || !SOP_ID_PATTERN.test(gate.id)) {
+        pushError(findings, 'INVALID_GATE_ID', `Gate ${label} has an invalid id (expected lowercase kebab)`, label);
+        return;
+    }
+    if (seenGateIds.has(gate.id)) {
+        pushError(findings, 'DUPLICATE_GATE_ID', `Duplicate gate id "${gate.id}"`, gate.id);
+        return;
+    }
+    seenGateIds.add(gate.id);
+    if (typeof gate.phase !== 'string' || !phases.has(gate.phase)) {
+        pushError(findings, 'GATE_PHASE_UNKNOWN', `Gate "${gate.id}" binds to unknown phase "${String(gate.phase)}"`, gate.id);
+    }
+    const check = gate.check;
+    if (check === null || typeof check !== 'object' || !SOP_GATE_CHECK_TYPES.includes(check.type ?? '')) {
+        pushError(findings, 'INVALID_CHECK_TYPE', `Gate "${gate.id}" has an invalid or missing check type (expected ${SOP_GATE_CHECK_TYPES.join(' | ')})`, gate.id);
+        return;
+    }
+    if (check.type === 'file-exists' && (typeof check.path !== 'string' || check.path.length === 0)) {
+        pushError(findings, 'CHECK_MISSING_FIELD', `Gate "${gate.id}" file-exists check requires a non-empty "path"`, gate.id);
+    }
+    if (check.type === 'grep' && (typeof check.file !== 'string' || check.file.length === 0 || typeof check.pattern !== 'string' || check.pattern.length === 0)) {
+        pushError(findings, 'CHECK_MISSING_FIELD', `Gate "${gate.id}" grep check requires non-empty "file" and "pattern"`, gate.id);
+    }
+    if (check.type === 'command') {
+        if (!Array.isArray(check.run) || check.run.length === 0 || !check.run.every((part) => typeof part === 'string')) {
+            pushError(findings, 'CHECK_MISSING_FIELD', `Gate "${gate.id}" command check requires a non-empty string array "run"`, gate.id);
+        }
+        if (!allowCommands) {
+            pushError(findings, 'COMMAND_NOT_ALLOWED', `Gate "${gate.id}" uses a command check; re-run with --allow-commands to permit command-type gates`, gate.id);
+        }
+    }
+}
+function lintGuard(guard, index, phases, findings) {
+    const label = `#${index}`;
+    if (typeof guard?.phase !== 'string' || !phases.has(guard.phase)) {
+        pushError(findings, 'GUARD_PHASE_UNKNOWN', `Guard ${label} binds to unknown phase "${String(guard?.phase)}"`);
+    }
+    if (typeof guard?.bash !== 'string' || guard.bash.length === 0) {
+        pushError(findings, 'GUARD_MISSING_PATTERN', `Guard ${label} requires a non-empty "bash" pattern`);
+        return;
+    }
+    try {
+        // eslint-disable-next-line no-new
+        new RegExp(guard.bash);
+    }
+    catch {
+        pushError(findings, 'GUARD_INVALID_PATTERN', `Guard ${label} has an invalid bash regex "${guard.bash}"`);
+    }
+}
+export async function lintSop(options) {
+    // lint validates the EXACT layer the caller targets (project when projectRoot
+    // is set, else global) — not the precedence resolution used for execution.
+    const manifestPath = options.projectRoot !== undefined
+        ? projectSopManifestPath(options.projectRoot, options.id)
+        : sopManifestPath(options.id);
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    const findings = [];
+    let manifest = null;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+    }
+    catch (error) {
+        pushError(findings, 'INVALID_JSON', `Manifest is not valid JSON: ${error instanceof Error ? error.message : 'parse error'}`);
+        return { ok: false, id: options.id, manifestPath, gateCount: 0, gateIds: [], findings };
+    }
+    if (typeof manifest.id !== 'string' || !SOP_ID_PATTERN.test(manifest.id)) {
+        pushError(findings, 'INVALID_ID', `Manifest id "${String(manifest.id)}" is invalid (expected lowercase kebab)`);
+    }
+    else {
+        const reserved = reservedIdReason(manifest.id);
+        if (reserved !== null) {
+            pushError(findings, 'RESERVED_ID', reserved);
+        }
+        if (manifest.id !== options.id) {
+            pushError(findings, 'ID_MISMATCH', `Manifest id "${manifest.id}" does not match its directory "${options.id}"`);
+        }
+    }
+    const phases = Array.isArray(manifest.phases) ? manifest.phases : [];
+    if (phases.length === 0) {
+        pushError(findings, 'EMPTY_PHASES', 'Manifest must declare at least one phase');
+    }
+    const phaseSet = new Set();
+    for (const phase of phases) {
+        if (phaseSet.has(phase)) {
+            pushError(findings, 'DUPLICATE_PHASE', `Duplicate phase "${phase}"`);
+        }
+        phaseSet.add(phase);
+    }
+    const gates = Array.isArray(manifest.gates) ? manifest.gates : [];
+    const seenGateIds = new Set();
+    gates.forEach((gate, index) => lintGate(gate, index, phaseSet, seenGateIds, options.allowCommands === true, findings));
+    const guards = Array.isArray(manifest.guards) ? manifest.guards : [];
+    guards.forEach((guard, index) => lintGuard(guard, index, phaseSet, findings));
+    return {
+        ok: findings.every((finding) => finding.severity !== 'error'),
+        id: options.id,
+        manifestPath,
+        gateCount: gates.length,
+        gateIds: [...seenGateIds],
+        findings
+    };
+}

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

@@ -0,0 +1,88 @@
+/**
+ * User-authored SOP (standard operating procedure) skill types — Feature A.
+ *
+ * A SOP is a user-defined workflow: ordered phases plus gates that guard entry
+ * into a phase. Gates are first-class, addressable objects (stable id) so a
+ * later metering layer (Feature B) can count them; Slice 1 only models and
+ * validates them — no registry, no enforcement.
+ */
+export type SopGateCheckType = 'file-exists' | 'grep' | 'command';
+export type SopGateCheck = {
+    type: 'file-exists';
+    path: string;
+}
+/**
+ * grep: by default passes when `pattern` is FOUND in `file`. Set `absent: true`
+ * to invert — pass when the pattern is NOT found. `absent` expresses "must not
+ * contain X" (e.g. no leftover TODO) as a pure-text check, with no command gate
+ * and no `--allow-commands` escalation.
+ */
+ | {
+    type: 'grep';
+    file: string;
+    pattern: string;
+    absent?: boolean;
+} | {
+    type: 'command';
+    run: string[];
+    expectExitZero?: boolean;
+};
+export type SopGate = {
+    /** Stable id, unique within the SOP. Addressed by `peaks sop check --gate <id>`. */
+    id: string;
+    /** The phase whose entry this gate guards; must be one of the SOP's phases. */
+    phase: string;
+    check: SopGateCheck;
+};
+/**
+ * Binds a concrete irreversible Bash action to a phase: running a command that
+ * matches `bash` (a JS regex) counts as performing that phase's action, so the
+ * phase's gates must pass first. Enforced un-bypassably by the PreToolUse hook
+ * (`peaks gate enforce`). Optional — a SOP without guards still works exactly as
+ * before; enforcement is an opt-in overlay.
+ */
+export type SopPhaseGuard = {
+    /** The phase whose gates must pass before the matching command may run. Must be a declared phase. */
+    phase: string;
+    /** JS regular expression tested against the Bash `tool_input.command`. */
+    bash: string;
+};
+export type SopManifest = {
+    /** SOP id; namespaced separately from built-in peaks-* skills. */
+    id: string;
+    name: string;
+    description?: string;
+    /** Ordered, unique phase names. */
+    phases: string[];
+    gates: SopGate[];
+    /** Optional Bash-action guards enforced by the PreToolUse hook (opt-in). */
+    guards?: SopPhaseGuard[];
+};
+/**
+ * A registered gate's workspace-level identity. `ref` (`<sopId>/<gateId>`) is
+ * unique across the workspace; `transition` (`<sopId>:<phase>`) is the binding
+ * a future enforcement layer (Slice 3) consults. Built-in peaks-* gates are
+ * never recorded here.
+ */
+export type RegisteredGate = {
+    ref: string;
+    gateId: string;
+    sopId: string;
+    phase: string;
+    transition: string;
+};
+export type RegisteredSop = {
+    id: string;
+    path: string;
+    gates: RegisteredGate[];
+};
+export type SopRegistry = {
+    version: 1;
+    sops: RegisteredSop[];
+    /** Total gate count across all registered SOPs — the workspace pool a metering layer would read. */
+    gateCount: number;
+};
+export type SopCheckResult = 'pass' | 'fail' | 'blocked';
+export declare const SOP_GATE_CHECK_TYPES: ReadonlyArray<SopGateCheckType>;
+/** SOP id grammar: lowercase kebab, must start alphanumeric. */
+export declare const SOP_ID_PATTERN: RegExp;

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

@@ -0,0 +1,11 @@
+/**
+ * User-authored SOP (standard operating procedure) skill types — Feature A.
+ *
+ * A SOP is a user-defined workflow: ordered phases plus gates that guard entry
+ * into a phase. Gates are first-class, addressable objects (stable id) so a
+ * later metering layer (Feature B) can count them; Slice 1 only models and
+ * validates them — no registry, no enforcement.
+ */
+export const SOP_GATE_CHECK_TYPES = ['file-exists', 'grep', 'command'];
+/** SOP id grammar: lowercase kebab, must start alphanumeric. */
+export const SOP_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;

package/dist/src/shared/paths.d.ts

@@ -2,5 +2,5 @@ export declare const repoRoot: string;
 export declare const skillsDir: string;
 export declare const schemasDir: string;
 export declare const templatesDir: string;
-export declare const requiredSkillNames: readonly ["peaks-solo", "peaks-prd", "peaks-ui", "peaks-rd", "peaks-qa", "peaks-sc", "peaks-txt"];
+export declare const requiredSkillNames: readonly ["peaks-solo", "peaks-prd", "peaks-ui", "peaks-rd", "peaks-qa", "peaks-sc", "peaks-txt", "peaks-sop"];
 export declare const requiredSchemaFiles: readonly ["artifact-manifest.schema.json", "context-capsule.schema.json", "approval-record.schema.json", "change-impact.schema.json", "refactor-slice-spec.schema.json", "artifact-retention-report.schema.json", "capability-source.schema.json", "capability-item.schema.json", "capability-availability.schema.json", "recommendation-plan.schema.json", "artifact-workspace.schema.json", "mcp-server.schema.json", "mcp-install-spec.schema.json", "mcp-install-plan.schema.json", "mcp-apply-result.schema.json", "openspec-change-summary.schema.json", "openspec-render-request.schema.json", "openspec-validation-result.schema.json", "doctor-report.schema.json"];

package/dist/src/shared/paths.js

@@ -23,7 +23,8 @@ export const requiredSkillNames = [
     'peaks-rd',
     'peaks-qa',
     'peaks-sc',
-    'peaks-txt'
+    'peaks-txt',
+    'peaks-sop'
 ];
 export const requiredSchemaFiles = [
     'artifact-manifest.schema.json',

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "1.1.2";
+export declare const CLI_VERSION = "1.2.1";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "1.1.2";
+export const CLI_VERSION = "1.2.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-cli",
-  "version": "1.1.2",
+  "version": "1.2.1",
   "description": "Peaks CLI and short skill family for Claude Code automation.",
   "author": "SquabbyZ",
   "license": "MIT",

package/schemas/doctor-report.schema.json

@@ -14,7 +14,7 @@
           "id": {
             "type": "string",
             "pattern": "^(skill|skill-name|skill-parse|skill-runbook|skill-apply-note|skill-presence|statusline|schema|config|doctor-self|capability):[A-Za-z0-9][A-Za-z0-9._-]*$",
-            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness), statusline:<topic> (whether the out-of-band Claude Code statusLine is installed), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version)."
+            "description": "Stable check id. Known prefixes: skill:<name> (required skill present), skill-name:<dir> (directory matches declared name), skill-parse:<dir> (skill metadata parsed), skill-runbook:<name> (Default runbook section exists), skill-apply-note:<name> (destructive --apply lines carry an authorization/--dry-run note), skill-presence:<topic> (status of .peaks/.active-skill.json — current/freshness/workspace), statusline:<topic> (out-of-band Claude Code statusLine — install/runtime), schema:<file> (schema file exists and is valid JSON), config:<scope> (optional config locations), doctor-self:<topic> (doctor validates its own output against this schema), capability:<name> (third-party capability is resolvable at the pinned version)."
           },
           "ok": { "type": "boolean" },
           "message": { "type": "string", "minLength": 1 }