peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

package/dist/cli/commands/slice-integrate-commands.d.ts

@@ -0,0 +1,11 @@
+/**
+ * v2.15.0 follow-up — G6: peaks slice integrate CLI.
+ *
+ *   - `peaks slice integrate --slices <id1,id2,...> --project <path>`
+ *     Verifies that the public contracts of multiple completed slices
+ *     integrate cleanly (no duplicate exports, no signature drift).
+ *     Pure read of .peaks/_runtime/<sid>/dispatch/contracts/.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSliceIntegrateCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,74 @@
+/**
+ * v2.15.0 follow-up — G6: peaks slice integrate CLI.
+ *
+ *   - `peaks slice integrate --slices <id1,id2,...> --project <path>`
+ *     Verifies that the public contracts of multiple completed slices
+ *     integrate cleanly (no duplicate exports, no signature drift).
+ *     Pure read of .peaks/_runtime/<sid>/dispatch/contracts/.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { integrateSlices } from '../../services/slice/slice-integration.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+function loadContractsForSlices(projectRoot, sessionId, sliceIds) {
+    const dir = resolve(projectRoot, '.peaks', '_runtime', sessionId, 'dispatch', 'contracts');
+    if (!existsSync(dir))
+        return [];
+    const result = [];
+    for (const sliceId of sliceIds) {
+        const file = join(dir, `${sliceId}.json`);
+        if (!existsSync(file))
+            continue;
+        try {
+            const raw = readFileSync(file, 'utf8');
+            result.push(JSON.parse(raw));
+        }
+        catch (err) {
+            // skip malformed contracts but warn (silent-warning-detector)
+            console.warn(`loadContractsForSlices: skipping malformed contract at ${file}: ${err.message}`);
+        }
+    }
+    return result;
+}
+export function registerSliceIntegrateCommands(program, io) {
+    addJsonOption(program
+        .command('slice-integrate')
+        .description('v2.15.0 follow-up G6: verify that multiple completed slice contracts integrate cleanly. ' +
+        'Reads the contracts of the given slice ids (from .peaks/_runtime/<sid>/dispatch/contracts/) ' +
+        'and reports duplicate exports / signature drift. The 12 Gaps memory: in the layered-parallel ' +
+        'execution model (G12), slices complete out of order — this catches the integration breaks ' +
+        'before downstream consumers see them.')
+        .requiredOption('--slices <list>', 'comma-separated slice ids to integrate-verify')
+        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json)')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? resolve(process.cwd());
+        const sessionId = opts.sessionId ?? getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+        const sliceIds = opts.slices.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        if (sliceIds.length < 2) {
+            printResult(io, fail('slice-integrate', 'TOO_FEW_SLICES', 'need at least 2 slice ids to verify integration', { projectRoot, sessionId, sliceIds }, [
+                'Pass --slices id1,id2,id3 (at least 2).'
+            ]), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const contracts = loadContractsForSlices(projectRoot, sessionId, sliceIds);
+        if (contracts.length === 0) {
+            printResult(io, fail('slice-integrate', 'NO_CONTRACTS', `no contracts found for the given slice ids under session ${sessionId}`, { projectRoot, sessionId, sliceIds }, [
+                'Run `peaks contract write` first, or check --session-id.'
+            ]), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const report = integrateSlices({ contracts });
+        printResult(io, ok('slice-integrate', { projectRoot, sessionId, report }, [], report.ok
+            ? []
+            : [
+                `${report.summary.errors} integration error(s) found.`,
+                'Address duplicate exports / signature drift before merging slices.'
+            ]), opts.json ?? false);
+        if (!report.ok)
+            process.exitCode = 1;
+    });
+}

package/dist/cli/commands/slice-review-commands.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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 type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSliceReviewCommands(program: Command, io: ProgramIO): void;

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 '../../shared/result.js';
+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.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 type { Command } from 'commander';
+import { EMPTY_SMOKE_STATE } from '../../services/smoke/smoke-paths-state.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSmokeCommands(program: Command, io: ProgramIO): void;
+export { EMPTY_SMOKE_STATE };

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 '../../shared/result.js';
+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.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerSopCommands(program: Command, io: ProgramIO): void;