peaks-loop 4.0.0-beta.2 → 4.0.0-beta.20

package/dist/cli/commands/slice-review-commands.js

@@ -0,0 +1,162 @@
+/**
+ * v2.15.0 follow-up — G1: slice business review CLI.
+ *
+ *   - `peaks slice review <slice-id>`      — show the 4-5 business
+ *                                            review items for a slice
+ *                                            (template; user scores 1-5)
+ *   - `peaks slice score <slice-id> --item <id> --score <1-5>`
+ *                                          — record a single item's
+ *                                            score
+ *   - `peaks slice accept <slice-id>`       — mark the slice as
+ *                                            accepted (must have all
+ *                                            items scored first)
+ *   - `peaks slice reject <slice-id> --reason <text>`
+ *                                          — mark as rejected with a
+ *                                            reason (back to RD repair)
+ *
+ * The 12 Gaps positioning memory: user reviews BUSINESS / PRODUCT,
+ * not technical metrics (which are AI auto-decided in peaks-rd's
+ * fan-out).
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { acceptReview, buildEmptySliceReview, DEFAULT_REVIEW_ITEMS, deriveDecision, readSliceReview, rejectReview, renderChecklist, scoreItem, writeSliceReview } from '../../services/slice/slice-review-state.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerSliceReviewCommands(program, io) {
+    // G1 commands registered as TOP-LEVEL commands prefixed with `slice-review-`
+    // to avoid colliding with the existing `peaks slice` commands
+    // (registered by slice-commands.ts). Same approach as user-touchpoint
+    // and qa-business-review commands.
+    // 1. review
+    addJsonOption(program
+        .command('slice-review <slice-id>')
+        .description('Show the 4-5 business review items for a slice (template; user scores 1-5). ' +
+        'If no review exists for the slice, a new one is created (pending state). ' +
+        'The 12 Gaps positioning memory: user reviews BUSINESS / PRODUCT, not technical.')
+        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json)')
+        .option('--project <path>', 'project root (default: cwd)')).action((sliceId, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = opts.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        let review = readSliceReview(projectRoot, sessionId, sliceId);
+        if (review === null) {
+            review = buildEmptySliceReview(sliceId, sessionId);
+            writeSliceReview(projectRoot, review);
+        }
+        const checklist = renderChecklist(review);
+        printResult(io, ok('slice.review', {
+            sessionId,
+            sliceId,
+            decision: review.decision,
+            derivedDecision: deriveDecision(review),
+            items: checklist,
+            averageScore: review.items.filter((it) => it.score !== null).length === 0
+                ? null
+                : review.items.reduce((s, it) => s + (it.score ?? 0), 0) / review.items.filter((it) => it.score !== null).length
+        }, review.decision === 'pending' ? [
+            `Score each item with: peaks slice score <slice-id> --item <id> --score <1-5>`,
+            `When all items are scored, run: peaks slice accept <slice-id>`
+        ] : [], review.decision === 'rejected' ? [
+            `Rejected: ${review.rejectionReason ?? '(no reason)'}`,
+            'Address the issue, then re-score and accept.'
+        ] : []), opts.json ?? false);
+    });
+    // 2. score
+    addJsonOption(program
+        .command('slice-score <slice-id>')
+        .description('Record a single item score (1-5). 1 = P0 fail, 2-3 = needs work, 4-5 = OK. ' +
+        'The 12 Gaps threshold: avg >= 3 AND no item <= 2 → accepted; otherwise rejected.')
+        .requiredOption('--item <id>', 'item id (e.g. business-match / boundary-cases / ui-assembly / mergeable)')
+        .requiredOption('--score <1-5>', 'score (1-5)')
+        .option('--note <text>', 'optional note (e.g. "fix the auth flow first")')
+        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json)')
+        .option('--project <path>', 'project root (default: cwd)')).action((sliceId, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = opts.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        const score = Number.parseInt(opts.score, 10);
+        if (Number.isNaN(score) || score < 1 || score > 5) {
+            printResult(io, fail('slice.score', 'INVALID_SCORE', `--score must be 1-5 (got "${opts.score}")`, { projectRoot }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        let review = readSliceReview(projectRoot, sessionId, sliceId);
+        if (review === null) {
+            review = buildEmptySliceReview(sliceId, sessionId);
+        }
+        const validItemIds = DEFAULT_REVIEW_ITEMS.map((it) => it.id);
+        if (!validItemIds.includes(opts.item)) {
+            printResult(io, fail('slice.score', 'UNKNOWN_ITEM', `unknown item "${opts.item}" (valid: ${validItemIds.join(', ')})`, { projectRoot }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const next = scoreItem(review, opts.item, score, opts.note);
+        writeSliceReview(projectRoot, next);
+        printResult(io, ok('slice.score', {
+            sessionId,
+            sliceId,
+            item: opts.item,
+            score,
+            derivedDecision: deriveDecision(next)
+        }, [], [
+            deriveDecision(next) === 'accepted'
+                ? 'All items now average >= 3 with no item <= 2. Run `peaks slice accept` to confirm.'
+                : 'Score recorded. Continue scoring other items or run `peaks slice accept` / `peaks slice reject`.'
+        ]), opts.json ?? false);
+    });
+    // 3. accept
+    addJsonOption(program
+        .command('slice-accept <slice-id>')
+        .description('Mark the slice as accepted (user-approved). All 4-5 items must be ' +
+        'scored; the derived decision must be "accepted" (avg >= 3 AND ' +
+        'no item <= 2). Otherwise the accept is rejected by the gate.')
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')).action((sliceId, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = opts.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        const review = readSliceReview(projectRoot, sessionId, sliceId);
+        if (review === null) {
+            printResult(io, fail('slice.accept', 'NO_REVIEW', `no review found for slice "${sliceId}" — run peaks slice review first`, { projectRoot }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const derived = deriveDecision(review);
+        if (derived === 'rejected') {
+            printResult(io, fail('slice.accept', 'CANNOT_ACCEPT', `derived decision is "rejected" (avg < 3 or item <= 2). Run peaks slice reject instead.`, { projectRoot, review }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        if (derived === 'pending') {
+            const pending = review.items.filter((it) => it.score === null).map((it) => it.id);
+            printResult(io, fail('slice.accept', 'PENDING', `not all items are scored (pending: ${pending.join(', ')})`, { projectRoot, review }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const next = acceptReview(review);
+        writeSliceReview(projectRoot, next);
+        printResult(io, ok('slice.accept', { sessionId, sliceId, decision: 'accepted', updatedAt: next.updatedAt }, [], [
+            'Slice accepted. Proceed to the next slice / final review.'
+        ]), opts.json ?? false);
+    });
+    // 4. reject
+    addJsonOption(program
+        .command('slice-reject <slice-id>')
+        .description('Mark the slice as rejected with a reason. The slice goes back to ' +
+        'peaks-rd repair-loop. The reason is persisted for the audit trail.')
+        .requiredOption('--reason <text>', 'rejection reason (required)')
+        .option('--session-id <sid>', 'session id')
+        .option('--project <path>', 'project root')).action((sliceId, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const sessionId = opts.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        const review = readSliceReview(projectRoot, sessionId, sliceId);
+        if (review === null) {
+            printResult(io, fail('slice.reject', 'NO_REVIEW', `no review found for slice "${sliceId}"`, { projectRoot }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const next = rejectReview(review, opts.reason);
+        writeSliceReview(projectRoot, next);
+        printResult(io, ok('slice.reject', { sessionId, sliceId, decision: 'rejected', reason: opts.reason, updatedAt: next.updatedAt }, [], [
+            'Slice rejected. Hand back to peaks-rd repair-loop.'
+        ]), opts.json ?? false);
+    });
+}

package/dist/cli/commands/smoke-commands.js

@@ -0,0 +1,203 @@
+/**
+ * v2.15.0 follow-up — G14: smoke regression CLI.
+ *
+ *   - `peaks smoke define`           — bulk-define critical paths (JSON or --paths)
+ *   - `peaks smoke run`             — record a run; for now this is a
+ *                                     dry-summary (no real Playwright)
+ *   - `peaks smoke run-and-repair`  — same as run, but emit a "needs
+ *                                     repair" warning when paths fail
+ *   - `peaks smoke add-path`        — add a single critical path
+ *                                     (used by `peaks impact must-check`
+ *                                     piping or manual registration)
+ *
+ * The actual Playwright execution is out of scope for this slice.
+ * The state model + 4 commands + repair-loop signal are what
+ * 2.15.0 follow-up needs.
+ */
+import { readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { addCriticalPath, CRITICAL_PATH_SOURCES, EMPTY_SMOKE_STATE, isCriticalPathSource, makeCriticalPathId, readSmokeState, recordRun, summarizeState, writeSmokeState } from '../../services/smoke/smoke-paths-state.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+const RUN_STATUSES = ['pending', 'pass', 'fail'];
+export function registerSmokeCommands(program, io) {
+    const smoke = program
+        .command('smoke')
+        .description('v2.15.0 follow-up G14: lightweight regression critical-paths management (5-10 min, no full E2E).');
+    // 1. define
+    addJsonOption(smoke
+        .command('define')
+        .description('Define the project\'s critical paths (the 5-10 paths to verify before shipping). ' +
+        'Two modes: (1) --paths <comma-separated names> registers all as source=manual, ' +
+        '(2) --from-file <json> imports paths from a JSON file. ' +
+        'Persists to `.peaks/smoke-paths.json`.')
+        .option('--paths <list>', 'comma-separated path names (registers all as source=manual)')
+        .option('--from-file <file>', 'JSON file with [{name, source?, category?}, ...]')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        if (!opts.paths && !opts.fromFile) {
+            printResult(io, fail('smoke.define', 'INVALID_INPUT', 'provide --paths or --from-file', {}, []), opts.json ?? false);
+            return;
+        }
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const now = new Date();
+        let newPaths = [];
+        if (opts.paths) {
+            const names = opts.paths.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+            newPaths = names.map((name) => ({
+                id: makeCriticalPathId(name),
+                name,
+                source: 'manual',
+                registeredAt: now.toISOString(),
+                status: 'pending',
+                history: []
+            }));
+        }
+        else if (opts.fromFile) {
+            try {
+                const filePath = resolvePath(opts.fromFile);
+                const raw = JSON.parse(readFileSync(filePath, 'utf8'));
+                newPaths = raw.map((item) => {
+                    const source = item.source && isCriticalPathSource(item.source) ? item.source : 'manual';
+                    return {
+                        id: makeCriticalPathId(item.name),
+                        name: item.name,
+                        source,
+                        registeredAt: now.toISOString(),
+                        ...(item.category !== undefined ? { category: item.category } : {}),
+                        status: 'pending',
+                        history: []
+                    };
+                });
+            }
+            catch (err) {
+                printResult(io, fail('smoke.define', 'INVALID_FILE', `failed to load --from-file: ${err.message}`, { projectRoot }, []), opts.json ?? false);
+                return;
+            }
+        }
+        const state = readSmokeState(projectRoot);
+        let next = state;
+        for (const p of newPaths)
+            next = addCriticalPath(next, p);
+        writeSmokeState(projectRoot, next);
+        printResult(io, ok('smoke.define', {
+            projectRoot,
+            registered: newPaths.length,
+            total: next.paths.length
+        }, [], [
+            'Run `peaks smoke run` to record the next regression run.'
+        ]), opts.json ?? false);
+    });
+    // 2. run
+    addJsonOption(smoke
+        .command('run')
+        .description('Record a smoke regression run. Without --record, this is a dry summary. ' +
+        'With --record and --status-id pairs (id1:pass,id2:fail), it records ' +
+        'the run result and persists updated state. ' +
+        'Real Playwright integration is out of scope for this slice.')
+        .option('--record <pairs>', 'comma-separated id:status pairs (e.g. "login:pass,logout:fail")')
+        .option('--notes <text>', 'optional run notes applied to all recorded paths')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const startMs = Date.now();
+        let state = readSmokeState(projectRoot);
+        if (opts.record) {
+            const pairs = opts.record.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+            for (const pair of pairs) {
+                const [id, status] = pair.split(':');
+                if (!id || !status) {
+                    printResult(io, fail('smoke.run', 'INVALID_RECORD', `bad pair "${pair}" (expected id:status)`, { projectRoot }, []), opts.json ?? false);
+                    return;
+                }
+                if (!RUN_STATUSES.includes(status)) {
+                    printResult(io, fail('smoke.run', 'INVALID_STATUS', `bad status "${status}" (expected pending|pass|fail)`, { projectRoot }, []), opts.json ?? false);
+                    return;
+                }
+                state = recordRun(state, id.trim(), status, opts.notes);
+            }
+            writeSmokeState(projectRoot, state);
+        }
+        const summary = summarizeState(state);
+        const durationMs = Date.now() - startMs;
+        printResult(io, ok('smoke.run', {
+            projectRoot,
+            summary: { ...summary, durationMs }
+        }, summary.failedPaths > 0
+            ? [`${summary.failedPaths} path(s) failed — consider \`peaks smoke run-and-repair\``]
+            : []), opts.json ?? false);
+    });
+    // 3. run-and-repair
+    addJsonOption(smoke
+        .command('run-and-repair')
+        .description('Same as `smoke run --record`, but emits a "needs repair" warning when any path fails. ' +
+        'Returns exit code 0 always (the CLI does not block on smoke failure; the user ' +
+        'decides whether to enter the repair loop). Real repair execution is the user\'s ' +
+        'call (run peaks-rd / re-implement / re-test).')
+        .option('--record <pairs>', 'comma-separated id:status pairs (e.g. "login:pass,logout:fail")')
+        .option('--notes <text>', 'optional run notes')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        let state = readSmokeState(projectRoot);
+        if (opts.record) {
+            const pairs = opts.record.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+            for (const pair of pairs) {
+                const [id, status] = pair.split(':');
+                if (!id || !status)
+                    continue;
+                if (!RUN_STATUSES.includes(status))
+                    continue;
+                state = recordRun(state, id.trim(), status, opts.notes);
+            }
+            writeSmokeState(projectRoot, state);
+        }
+        const summary = summarizeState(state);
+        const needsRepair = summary.failedPaths > 0;
+        printResult(io, ok('smoke.run-and-repair', {
+            projectRoot,
+            needsRepair,
+            summary
+        }, needsRepair
+            ? [
+                `Repair needed for ${summary.failedPaths} path(s):`,
+                ...summary.failedDetails.map((d) => `  - ${d.name}${d.lastRunNote ? ` (note: ${d.lastRunNote})` : ''}`),
+                'Re-run the failing paths, or enter peaks-rd repair-loop.'
+            ]
+            : ['All paths pass.']), opts.json ?? false);
+    });
+    // 4. add-path
+    addJsonOption(smoke
+        .command('add-path')
+        .description('Add a single critical path. Typically used by `peaks impact must-check` piping, ' +
+        'or by manual registration after a hotfix. The --source flag identifies where the ' +
+        'path came from (default: manual).')
+        .requiredOption('--name <text>', 'path name (also used to derive the id)')
+        .option('--source <name>', `path source (${CRITICAL_PATH_SOURCES.join(' | ')})`, 'manual')
+        .option('--category <text>', 'optional category tag')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const source = opts.source && isCriticalPathSource(opts.source) ? opts.source : 'manual';
+        const id = makeCriticalPathId(opts.name);
+        const path = {
+            id,
+            name: opts.name,
+            source,
+            registeredAt: new Date().toISOString(),
+            ...(opts.category !== undefined ? { category: opts.category } : {}),
+            status: 'pending',
+            history: []
+        };
+        const state = readSmokeState(projectRoot);
+        const next = addCriticalPath(state, path);
+        writeSmokeState(projectRoot, next);
+        printResult(io, ok('smoke.add-path', {
+            projectRoot,
+            added: { id, name: opts.name, source },
+            total: next.paths.length
+        }, [], [
+            `Run \`peaks smoke run --record ${id}:pass\` after verifying this path.`
+        ]), opts.json ?? false);
+    });
+}
+// Expose the empty state symbol so other modules (e.g. impact-commands)
+// can pipe must-check items into smoke state without circular imports.
+export { EMPTY_SMOKE_STATE };

package/dist/cli/commands/sop-commands.js

@@ -0,0 +1,215 @@
+import { mkdirSync } from 'node:fs';
+import { initSop, lintSop } from '../../services/sop/sop-service.js';
+import { registerSop, readRegistry, SopRegisterError } from '../../services/sop/sop-registry-service.js';
+import { checkGate, SopCheckError } from '../../services/sop/sop-check-service.js';
+import { advanceSop, SopAdvanceError, SopGateBlockedError, SopPhaseSkipError } from '../../services/sop/sop-advance-service.js';
+import { sopStateDir } from '../../services/sop/sop-paths.js';
+import { getSkillPresence } from '../../services/skills/skill-presence-service.js';
+import { recordBypass, isBypassLimitReached, MAX_BYPASSES_PER_SESSION } from '../../services/mode/bypass-tracker.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerSopCommands(program, io) {
+    const sop = program.command('sop').description('Author and validate user-defined SOP skills');
+    addJsonOption(sop
+        .command('init')
+        .description('Scaffold a user-authored SOP (manifest + SKILL.md); global by default, --project commits it into a repo')
+        .requiredOption('--id <sop-id>', 'SOP id (lowercase kebab, e.g. team-release)')
+        .option('--name <name>', 'human-readable SOP name (defaults to the id)')
+        .option('--apply', 'write the SOP files (default: preview only)')
+        .option('--project <path>', 'scaffold into the repo (<path>/.peaks/sops, committed & team-shared) instead of global')).action(async (options) => {
+        try {
+            const initOptions = { id: options.id };
+            if (options.name !== undefined) {
+                initOptions.name = options.name;
+            }
+            if (options.apply === true) {
+                initOptions.apply = true;
+            }
+            if (options.project !== undefined) {
+                initOptions.projectRoot = options.project;
+            }
+            const result = await initSop(initOptions);
+            // Side-effecting scaffold returns explicit next steps so the user doesn't
+            // have to recall the runbook: applied → edit then lint; preview → apply.
+            const nextActions = result.applied
+                ? [
+                    `Edit ${result.manifestPath} to define your real phases and gates`,
+                    `peaks sop lint --id ${result.id} --json`
+                ]
+                : [`Re-run with --apply to write ${result.manifestPath}`];
+            printResult(io, ok('sop.init', result, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('sop.init', 'SOP_INIT_FAILED', getErrorMessage(error), { id: options.id }, ['Check the SOP id before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('lint')
+        .description('Validate a SOP manifest (id namespace, phases, gate ids, check fields)')
+        .requiredOption('--id <sop-id>', 'SOP id to lint')
+        .option('--allow-commands', 'permit command-type gates (they run shell-less processes)')
+        .option('--project <path>', 'lint the project-layer SOP (<path>/.peaks/sops) instead of global')).action(async (options) => {
+        try {
+            const lintOptions = { id: options.id };
+            if (options.allowCommands === true) {
+                lintOptions.allowCommands = true;
+            }
+            if (options.project !== undefined) {
+                lintOptions.projectRoot = options.project;
+            }
+            const result = await lintSop(lintOptions);
+            if (result === null) {
+                printResult(io, fail('sop.lint', 'SOP_NOT_FOUND', `No SOP found for id "${options.id}"`, { id: options.id }, ['Run peaks sop init --id <sop-id> --apply first']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, result.ok
+                ? ok('sop.lint', result)
+                : fail('sop.lint', 'SOP_LINT_FAILED', `${result.findings.filter((f) => f.severity === 'error').length} lint error(s) in SOP "${options.id}"`, result, ['Fix the reported findings, then re-run peaks sop lint']), options.json);
+            if (!result.ok) {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('sop.lint', 'SOP_LINT_ERROR', getErrorMessage(error), { id: options.id }, ['Check the SOP id before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('register')
+        .description('Validate a SOP and record its gates in the gate registry (global, or --project for the repo)')
+        .requiredOption('--id <sop-id>', 'SOP id to register')
+        .option('--allow-commands', 'permit command-type gates when validating')
+        .option('--dry-run', 'preview the registration without writing registry.json')
+        .option('--project <path>', 'register into the repo (<path>/.peaks/sops, committed & team-shared) instead of global')).action(async (options) => {
+        try {
+            const registerOptions = { id: options.id };
+            if (options.allowCommands === true) {
+                registerOptions.allowCommands = true;
+            }
+            if (options.dryRun === true) {
+                registerOptions.dryRun = true;
+            }
+            if (options.project !== undefined) {
+                registerOptions.projectRoot = options.project;
+            }
+            const result = await registerSop(registerOptions);
+            printResult(io, ok('sop.register', result, [], result.applied ? [] : ['Re-run without --dry-run to write registry.json']), options.json);
+        }
+        catch (error) {
+            const code = error instanceof SopRegisterError ? error.code : 'SOP_REGISTER_FAILED';
+            printResult(io, fail('sop.register', code, getErrorMessage(error), { id: options.id }, ['Run peaks sop lint to see why the SOP is not registrable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('registry')
+        .description('List registered SOPs and gates (global; merges in the cwd project layer by default)')
+        .option('--project <path>', 'also include and prefer the repo layer (<path>/.peaks/sops) (default: current directory)', '.')).action(async (options) => {
+        try {
+            const registry = await readRegistry(options.project);
+            printResult(io, ok('sop.registry', registry), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('sop.registry', 'SOP_REGISTRY_FAILED', getErrorMessage(error), {}, ['The global registry may be corrupted; inspect ~/.peaks/sops/registry.json']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('check')
+        .description('Evaluate a single SOP gate (returns pass / fail / blocked)')
+        .requiredOption('--id <sop-id>', 'SOP id')
+        .requiredOption('--gate <gate-id>', 'gate id within the SOP')
+        .option('--project <path>', 'project the gate evaluates against (default: current directory)', '.')
+        .option('--allow-commands', 'permit evaluating command-type gates')).action(async (options) => {
+        try {
+            const checkOptions = { projectRoot: options.project, id: options.id, gateId: options.gate };
+            if (options.allowCommands === true) {
+                checkOptions.allowCommands = true;
+            }
+            const result = await checkGate(checkOptions);
+            printResult(io, ok('sop.check', result), options.json);
+        }
+        catch (error) {
+            const code = error instanceof SopCheckError ? error.code : 'SOP_CHECK_FAILED';
+            printResult(io, fail('sop.check', code, getErrorMessage(error), { id: options.id, gateId: options.gate }, ['Verify the SOP id and gate id with peaks sop lint']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(sop
+        .command('advance')
+        .description('Advance a SOP to a phase; gates guarding that phase must pass (or be explicitly bypassed)')
+        .requiredOption('--id <sop-id>', 'SOP id')
+        .requiredOption('--to <phase>', 'phase to advance into')
+        .option('--project <path>', 'project whose run-state advances (default: current directory)', '.')
+        .option('--allow-commands', 'permit evaluating command-type gates')
+        .option('--allow-incomplete', 'bypass the phase gates AND phase-order check (requires --reason)')
+        .option('--reason <text>', 'justification recorded when bypassing gates')
+        .option('--confirm', 'skip interactive confirmation for a bypass in assisted/strict mode')
+        .option('--force-confirm', 'bypass mode-enforced confirmation (use with caution)')
+        .option('--dry-run', 'evaluate gates without recording the advance in state.json')).action(async (options) => {
+        try {
+            // Bypass policy mirrors `request transition`: a bypass needs a reason, and
+            // in assisted/strict mode (resolved from the target project) it needs an
+            // explicit --confirm and counts against the per-SOP bypass cap.
+            if (options.allowIncomplete === true && (options.reason === undefined || options.reason.trim().length === 0)) {
+                printResult(io, fail('sop.advance', 'BYPASS_REASON_REQUIRED', '--allow-incomplete requires --reason explaining why the gates are skipped', { id: options.id, to: options.to }, ['Add --reason "<short justification>" or satisfy the gates']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (options.allowIncomplete === true && options.forceConfirm !== true) {
+                const presence = getSkillPresence(options.project);
+                if (presence?.mode === 'assisted' || presence?.mode === 'strict') {
+                    if (options.confirm !== true) {
+                        printResult(io, fail('sop.advance', 'ALLOW_INCOMPLETE_RESTRICTED', `--allow-incomplete requires --confirm in ${presence.mode} mode`, { id: options.id, mode: presence.mode }, ['Add --confirm to bypass non-interactively']), options.json);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    // The bypass counter is keyed to the per-project SOP run-state dir (not
+                    // a session); the shared cap constant is reused. Keying it per-project
+                    // means a bypass in one project never consumes another project's budget.
+                    const bypassRoot = sopStateDir(options.project, options.id);
+                    // The per-project state dir may not exist yet (no successful advance has
+                    // written state.json), so ensure it before the counter writes its file.
+                    mkdirSync(bypassRoot, { recursive: true });
+                    if (isBypassLimitReached(bypassRoot)) {
+                        printResult(io, fail('sop.advance', 'BYPASS_LIMIT_REACHED', `gate bypass limit reached (${MAX_BYPASSES_PER_SESSION} bypasses per SOP)`, { id: options.id, limit: MAX_BYPASSES_PER_SESSION }, ['Satisfy the gates instead of bypassing']), options.json);
+                        process.exitCode = 1;
+                        return;
+                    }
+                    // A dry-run preview must not consume a bypass.
+                    if (options.dryRun !== true) {
+                        recordBypass(bypassRoot);
+                    }
+                }
+            }
+            const advanceOptions = { projectRoot: options.project, id: options.id, toPhase: options.to };
+            if (options.allowCommands === true)
+                advanceOptions.allowCommands = true;
+            if (options.allowIncomplete === true)
+                advanceOptions.allowIncomplete = true;
+            if (options.reason !== undefined)
+                advanceOptions.reason = options.reason;
+            if (options.dryRun === true)
+                advanceOptions.dryRun = true;
+            const result = await advanceSop(advanceOptions);
+            printResult(io, ok('sop.advance', result, [], result.applied ? [] : ['Gates passed; re-run without --dry-run to record the advance']), options.json);
+        }
+        catch (error) {
+            if (error instanceof SopGateBlockedError) {
+                printResult(io, fail('sop.advance', error.code, error.message, { id: options.id, to: options.to, blockedGates: error.blockedGates }, ['Satisfy the blocking gates, or bypass with --allow-incomplete --reason "<why>"']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (error instanceof SopPhaseSkipError) {
+                printResult(io, fail('sop.advance', error.code, error.message, { id: options.id, to: options.to, fromPhase: error.fromPhase, expectedNext: error.expectedNext }, [`Advance to "${error.expectedNext}" first, or bypass with --allow-incomplete --reason "<why>"`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const code = error instanceof SopAdvanceError ? error.code : 'SOP_ADVANCE_FAILED';
+            printResult(io, fail('sop.advance', code, getErrorMessage(error), { id: options.id, to: options.to }, ['Verify the SOP id and phase with peaks sop lint']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}