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

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

@@ -0,0 +1,201 @@
+/**
+ * `peaks observability <subcommand>` — Slice B/C of v2.11.1.
+ *
+ * Slice B ships 4 read-only subcommands (AC-1 to AC-4):
+ *   - `peaks observability status`         (AC-1)
+ *   - `peaks observability slices`         (AC-2)
+ *   - `peaks observability fanout`         (AC-3)
+ *   - `peaks observability repair-cycles`  (AC-4)
+ *
+ * `peaks observability report` (AC-5) lands in Slice D when the
+ * markdown report formatter is implemented.
+ *
+ * Read-only — never writes. Reads the JSONL metrics files emitted
+ * by the `peaks request transition` hook (Slice A) plus the future
+ * Slice C hook sites (dispatch / checkpoint / mode-gate / context
+ * / post-compact). The aggregations tolerate zero events gracefully
+ * so each subcommand returns a meaningful empty result on a fresh
+ * tree.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { getSessionIdCanonical } from '../../services/session/session-manager.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { aggregateFanout, aggregateRepairCycles, aggregateSlices, aggregateStatus, filterByPeriod, periodStartIso, readAllSessionEvents, readSessionEvents } from '../../services/observability/aggregation.js';
+import { renderObservabilityReport } from '../../services/observability/report-formatter.js';
+function resolveProjectRoot(optionProject) {
+    return optionProject !== undefined
+        ? resolveCanonicalProjectRoot(optionProject)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+}
+function resolveSessionId(optionSession, projectRoot) {
+    if (optionSession !== undefined)
+        return optionSession;
+    return getSessionIdCanonical(projectRoot) ?? undefined;
+}
+function runStatus(io, options) {
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(options.session, projectRoot);
+    try {
+        const events = sessionId !== undefined
+            ? readSessionEvents(projectRoot, sessionId)
+            : readAllSessionEvents(projectRoot);
+        const status = aggregateStatus(events);
+        const warnings = sessionId === undefined && status.totalEvents === 0
+            ? ['No observability events found in any session — emit a slice transition via `peaks request transition` to populate.']
+            : [];
+        printResult(io, ok('observability.status', {
+            scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
+            status
+        }, warnings), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('observability.status', 'OBSERVABILITY_STATUS_FAILED', getErrorMessage(error), { projectRoot }, ['Run `peaks observability slices` for per-slice detail']), options.json);
+        process.exitCode = 1;
+    }
+}
+function runSlices(io, options) {
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(options.session, projectRoot);
+    try {
+        const events = sessionId !== undefined
+            ? readSessionEvents(projectRoot, sessionId)
+            : readAllSessionEvents(projectRoot);
+        const slices = aggregateSlices(events);
+        printResult(io, ok('observability.slices', {
+            scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
+            total: slices.length,
+            slices
+        }, []), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('observability.slices', 'OBSERVABILITY_SLICES_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
+        process.exitCode = 1;
+    }
+}
+function runFanout(io, options) {
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(options.session, projectRoot);
+    try {
+        const events = sessionId !== undefined
+            ? readSessionEvents(projectRoot, sessionId)
+            : readAllSessionEvents(projectRoot);
+        const fanout = aggregateFanout(events);
+        const warnings = fanout.total === 0
+            ? ['No dispatch events recorded yet — Slice C will wire `peaks sub-agent dispatch`; until then fanout is empty.']
+            : [];
+        printResult(io, ok('observability.fanout', {
+            scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
+            fanout
+        }, warnings), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('observability.fanout', 'OBSERVABILITY_FANOUT_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
+        process.exitCode = 1;
+    }
+}
+function runRepairCycles(io, options) {
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(options.session, projectRoot);
+    try {
+        const events = sessionId !== undefined
+            ? readSessionEvents(projectRoot, sessionId)
+            : readAllSessionEvents(projectRoot);
+        const cycles = aggregateRepairCycles(events);
+        printResult(io, ok('observability.repair-cycles', {
+            scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
+            cycles
+        }, []), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('observability.repair-cycles', 'OBSERVABILITY_REPAIR_CYCLES_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
+        process.exitCode = 1;
+    }
+}
+const VALID_PERIODS = ['day', 'week', 'month'];
+function runReport(io, options) {
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(options.session, projectRoot);
+    const period = options.period !== undefined && VALID_PERIODS.includes(options.period)
+        ? options.period
+        : 'day';
+    try {
+        const allEvents = sessionId !== undefined
+            ? readSessionEvents(projectRoot, sessionId)
+            : readAllSessionEvents(projectRoot);
+        const periodStart = periodStartIso(period);
+        const events = filterByPeriod(allEvents, period);
+        const markdown = renderObservabilityReport({
+            scope: sessionId !== undefined ? 'session' : 'all-sessions',
+            scopeId: sessionId ?? 'all',
+            period,
+            generatedAt: new Date().toISOString(),
+            status: aggregateStatus(events),
+            slices: aggregateSlices(events),
+            fanout: aggregateFanout(events),
+            repairCycles: aggregateRepairCycles(events)
+        });
+        if (options.json === true) {
+            // --json on report: emit a metadata envelope so callers can
+            // machine-parse the markdown body without losing the envelope
+            // contract.
+            printResult(io, ok('observability.report', {
+                scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
+                period,
+                periodStart,
+                totalEventsScanned: allEvents.length,
+                totalEventsInPeriod: events.length,
+                markdown
+            }, []), true);
+            return;
+        }
+        io.stdout(markdown);
+    }
+    catch (error) {
+        printResult(io, fail('observability.report', 'OBSERVABILITY_REPORT_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerObservabilityCommands(program, io) {
+    const observability = program
+        .command('observability')
+        .description('Read-only slice topology observability queries (v2.11.1). Reads JSONL metrics from .peaks/_runtime/<sessionId>/metrics/slices.jsonl.');
+    addJsonOption(observability
+        .command('status')
+        .description('Aggregate metrics for the active session (or all sessions with --project + omitted --session). Includes totalEvents / totalSlices / successCount / failCount / repairCyclePeak / fanoutCostTotal.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')).action((options) => {
+        runStatus(io, options);
+    });
+    addJsonOption(observability
+        .command('slices')
+        .description('List all slices for the scope. Per slice: rid, transition count, first/last ts, durationMs, finalState, fanoutCount, repairCycleCount, success.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')).action((options) => {
+        runSlices(io, options);
+    });
+    addJsonOption(observability
+        .command('fanout')
+        .description('Fanout cost breakdown by sub-agent role (rd / qa / code-reviewer / karpathy-reviewer / peaks-security-audit / peaks-perf-audit; v2.12.0 collapse — `security-reviewer` removed from the role enum). Returns 0 per role until Slice C wires the `peaks sub-agent dispatch` hook.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')).action((options) => {
+        runFanout(io, options);
+    });
+    addJsonOption(observability
+        .command('repair-cycles')
+        .description('RD → QA repair-cycle count per slice. Cap = 3 (peaks-code repair-loop contract); capHit flag is set when any slice hits the cap.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')).action((options) => {
+        runRepairCycles(io, options);
+    });
+    observability
+        .command('report')
+        .description('Render a markdown summary suitable for paste into PR descriptions or .peaks/PROJECT.md timeline entries. Default period = day; --json emits an envelope wrapping the markdown body. Output sections: header + status summary + slice table + fanout table + repair-cycle table + top-N slowest slices.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
+        .option('--period <period>', 'one of: day | week | month (defaults to day)', 'day')
+        .action((options) => {
+        runReport(io, options);
+    });
+}

package/dist/cli/commands/openspec-commands.d.ts

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

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

@@ -0,0 +1,237 @@
+import { readFile } from 'node:fs/promises';
+import { loadOpenSpecChange, scanOpenSpec } from '../../services/openspec/openspec-scan-service.js';
+import { projectOpenSpecToRdInput } from '../../services/openspec/openspec-bridge-service.js';
+import { renderOpenSpecChange } from '../../services/openspec/openspec-render-service.js';
+import { validateOpenSpecChange } from '../../services/openspec/openspec-validate-service.js';
+import { archiveOpenSpecChange } from '../../services/openspec/openspec-archive-service.js';
+import { executeOpenSpecInit } from '../../services/openspec/openspec-init-service.js';
+import { proposeFromDoctor } from '../../services/openspec/openspec-propose-from-doctor-service.js';
+import { runDoctor } from '../../services/doctor/doctor-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+function resolveScanOptions(project) {
+    if (project === undefined) {
+        return {};
+    }
+    return { openspecRoot: `${project.replace(/\\/g, '/').replace(/\/$/, '')}/openspec` };
+}
+async function loadRenderRequest(requestPath) {
+    const raw = await readFile(requestPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Render request file must contain a JSON object');
+    }
+    return parsed;
+}
+export function registerOpenSpecCommands(program, io) {
+    const openspec = program.command('openspec').description('Inspect OpenSpec changes inside the target project');
+    addJsonOption(openspec
+        .command('list')
+        .description('List OpenSpec changes detected under <project>/openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')).action(async (options) => {
+        try {
+            const report = await scanOpenSpec(resolveScanOptions(options.project));
+            printResult(io, ok('openspec.list', report), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.list', 'OPENSPEC_LIST_FAILED', getErrorMessage(error), {}, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('show')
+        .description('Show parsed proposal and tasks progress for a single OpenSpec change')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')).action(async (changeId, options) => {
+        try {
+            const detail = await loadOpenSpecChange(changeId, resolveScanOptions(options.project));
+            if (detail === null) {
+                printResult(io, fail('openspec.show', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.show', detail), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.show', 'OPENSPEC_SHOW_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('to-rd')
+        .description('Project an OpenSpec change into an RD/SC input shape (acceptance, what-changes, commit boundaries)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')).action(async (changeId, options) => {
+        try {
+            const projection = await projectOpenSpecToRdInput(changeId, resolveScanOptions(options.project));
+            if (projection === null) {
+                printResult(io, fail('openspec.to-rd', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.to-rd', projection), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.to-rd', 'OPENSPEC_TO_RD_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('render')
+        .description('Render an OpenSpec change pack from a JSON request file (dry-run by default)')
+        .requiredOption('--request <path>', 'path to a JSON file describing the render request')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--apply', 'write the rendered files into openspec/changes/<id>/')
+        .option('--overwrite', 'overwrite an existing change directory when --apply is set')).action(async (options) => {
+        try {
+            const request = await loadRenderRequest(options.request);
+            const scan = resolveScanOptions(options.project);
+            const renderOptions = {};
+            if (scan.openspecRoot !== undefined) {
+                renderOptions.openspecRoot = scan.openspecRoot;
+            }
+            if (options.apply === true) {
+                renderOptions.apply = true;
+            }
+            if (options.overwrite === true) {
+                renderOptions.overwrite = true;
+            }
+            const result = await renderOpenSpecChange(request, renderOptions);
+            printResult(io, ok('openspec.render', result), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.render', 'OPENSPEC_RENDER_FAILED', getErrorMessage(error), { requestPath: options.request }, ['Check the request JSON shape and the openspec root before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('validate')
+        .description('Validate an OpenSpec change against internal lint rules (and optionally the external openspec CLI)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--prefer-external', 'use the external openspec CLI when available, fall back to internal lint')).action(async (changeId, options) => {
+        try {
+            const scan = resolveScanOptions(options.project);
+            const validateOptions = {};
+            if (scan.openspecRoot !== undefined) {
+                validateOptions.openspecRoot = scan.openspecRoot;
+            }
+            if (options.preferExternal === true) {
+                validateOptions.preferExternal = true;
+            }
+            const result = await validateOpenSpecChange(changeId, validateOptions);
+            if (result === null) {
+                printResult(io, fail('openspec.validate', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!result.valid) {
+                printResult(io, fail('openspec.validate', 'OPENSPEC_VALIDATE_INVALID', `OpenSpec change ${changeId} failed validation`, result, result.issues.map((issue) => `${issue.level}: ${issue.rule}: ${issue.message}`)), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.validate', result, result.issues.filter((issue) => issue.level === 'warning').map((issue) => `${issue.rule}: ${issue.message}`)), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.validate', 'OPENSPEC_VALIDATE_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('archive')
+        .description('Move an OpenSpec change under openspec/changes/<archiveDir>/<id>/ (dry-run by default)')
+        .argument('<changeId>', 'OpenSpec change directory name under openspec/changes')
+        .option('--project <path>', 'project root containing an openspec/ directory')
+        .option('--apply', 'actually move the change directory')
+        .option('--archive-dir <name>', 'archive subdirectory name (default: archive)')).action(async (changeId, options) => {
+        try {
+            const scan = resolveScanOptions(options.project);
+            const archiveOptions = {};
+            if (scan.openspecRoot !== undefined) {
+                archiveOptions.openspecRoot = scan.openspecRoot;
+            }
+            if (options.apply === true) {
+                archiveOptions.apply = true;
+            }
+            if (options.archiveDir !== undefined) {
+                archiveOptions.archiveDirName = options.archiveDir;
+            }
+            const result = await archiveOpenSpecChange(changeId, archiveOptions);
+            if (result === null) {
+                printResult(io, fail('openspec.archive', 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('openspec.archive', result, [], result.applied ? [] : [`Re-run with --apply to move ${result.from} → ${result.to}`]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.archive', 'OPENSPEC_ARCHIVE_FAILED', getErrorMessage(error), { changeId }, ['Check the project path and openspec/ layout before retrying']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('init')
+        .description('Scaffold the openspec/ directory in the target project (changes/, archive/, README.md, CHANGES.md). Idempotent — refuses to overwrite an existing openspec/')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--apply', 'write files to disk (default: dry-run preview)', false)).action(async (options) => {
+        try {
+            const result = await executeOpenSpecInit({
+                projectRoot: options.project,
+                apply: options.apply === true
+            });
+            const nextActions = [];
+            if (result.alreadyInitialized) {
+                nextActions.push('openspec/ already exists; no files were created or modified.');
+                if (result.existingFiles.length > 0) {
+                    nextActions.push(`Existing files preserved: ${result.existingFiles.join(', ')}`);
+                }
+            }
+            else if (!result.apply) {
+                nextActions.push('Re-run with --apply to write the planned files to disk.');
+            }
+            else {
+                nextActions.push('Run `peaks openspec render --request <path> --apply` to scaffold a first change proposal.');
+            }
+            printResult(io, ok('openspec.init', result, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.init', 'OPENSPEC_INIT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(openspec
+        .command('from-doctor')
+        .description('Slice L3.3: generate an OpenSpec change draft (proposal.md) from a peaks doctor finding')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--check-id <id>', 'the doctor check id to draft from (e.g. L3:l3-memory-health)')).action(async (options) => {
+        try {
+            const report = await runDoctor();
+            const finding = report.checks.find((c) => c.id === options.checkId);
+            if (finding === undefined) {
+                printResult(io, fail('openspec.from-doctor', 'CHECK_NOT_FOUND', `No doctor check with id "${options.checkId}"`, { availableIds: report.checks.map((c) => c.id) }, ['Run peaks doctor --json to list available check ids']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (finding.ok) {
+                printResult(io, fail('openspec.from-doctor', 'CHECK_ALREADY_PASSING', `Doctor check "${options.checkId}" is already passing; nothing to draft`, { checkId: options.checkId }, ['Pick a failing check from peaks doctor --json']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const doctorFinding = {
+                id: finding.id,
+                rule: finding.rule ?? finding.id,
+                detail: finding.message,
+                severity: 'fail',
+            };
+            const result = proposeFromDoctor({ projectRoot: options.project, finding: doctorFinding });
+            printResult(io, ok('openspec.from-doctor', result, [], [
+                `draft proposal written to ${result.proposalPath}`,
+                'Review + edit the draft, then run `peaks openspec validate <id>`',
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('openspec.from-doctor', 'OPENSPEC_FROM_DOCTOR_FAILED', getErrorMessage(error), { projectRoot: options.project, checkId: options.checkId }, ['Verify the project path and the check id']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/perf-audit-commands.d.ts

@@ -0,0 +1,22 @@
+/**
+ * peaks perf-audit * CLI surface — independent performance audit skill
+ * driver. Per slice v2.12.0 (Group A, Tier 3). Symmetric to
+ * `security-audit-commands.ts`.
+ *
+ * Subcommands:
+ *   - `peaks perf-audit detect` — JSON envelope describing the
+ *     5-state perf-audit runtime (ready / handoff-missing /
+ *     template-missing / dispatch-failed / envelope-malformed).
+ *   - `peaks perf-audit run` — runs the full pipeline:
+ *     detect → read handoff + template → write audit artifact to
+ *     `.peaks/_runtime/<sid>/audit/perf-<rid>.md`. Reads the
+ *     envelope JSON from --envelope file or stdin.
+ *
+ * The actual LLM-in-loop judgement is NOT in this CLI — the parent
+ * LLM (peaks-perf-audit skill prompt) is the judgement core.
+ * This CLI is the I/O + validation shell, mirroring the ecc-bridge
+ * pattern (slice 7 Group D).
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerPerfAuditCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/perf-audit-commands.js

@@ -0,0 +1,132 @@
+import { readFileSync } from 'node:fs';
+import { detectPerfAudit, isPerfAuditEnvelope, runPerfAudit, } from '../../services/audit-independent/perf-audit-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+function resolveEnvelope(envelopePath) {
+    if (envelopePath === undefined || envelopePath === '-') {
+        // Read from stdin
+        return readStdinSync();
+    }
+    try {
+        const raw = readFileSync(envelopePath, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Failed to read envelope from ${envelopePath}: ${getErrorMessage(error)}`);
+    }
+}
+function readStdinSync() {
+    // Node 22: read stdin synchronously via fs.readFileSync(0, 'utf8').
+    // We use the file descriptor 0 convention.
+    try {
+        // Lazy import to avoid pulling readline at module load
+        const { readFileSync: rfs } = require('node:fs');
+        const raw = rfs(0, 'utf8');
+        if (raw.trim().length === 0) {
+            throw new Error('stdin was empty; expected JSON envelope on stdin or --envelope <path>');
+        }
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('stdin was empty')) {
+            throw error;
+        }
+        throw new Error(`Failed to read envelope from stdin: ${getErrorMessage(error)}`);
+    }
+}
+export function registerPerfAuditCommands(program, io) {
+    const perfAudit = program
+        .command('perf-audit')
+        .description('Independent performance audit skill driver. Reads the immutable peaks-prd handoff (sha256-locked) + the project-level perf-template.md, then writes a structured perf-<rid>.md artifact. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 3). See skills/bee/peaks-perf-audit/SKILL.md for the full workflow.');
+    addJsonOption(perfAudit
+        .command('detect')
+        .description('Read-only probe: returns the 5-state perf-audit runtime as a JSON envelope (ready / handoff-missing / template-missing / dispatch-failed / envelope-malformed). The peaks-perf-audit skill calls this first to decide whether to invoke `run`. Mirrors `peaks security-audit detect` semantics.')
+        .option('--rid <rid>', 'request id (e.g. 2026-06-27-v2-12-...)')
+        .option('--sid <sid>', 'session id (e.g. 2026-06-27-session-...)')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        const sid = options.sid;
+        if (sid === undefined || sid.length === 0) {
+            printResult(io, fail('perf-audit.detect', 'SID_REQUIRED', 'session id (--sid) is required for perf-audit.detect', { state: 'sid-missing' }, ['Pass --sid <session-id> (e.g. 2026-06-27-session-...)', 'Run `peaks session info --active --json` to find the active sid.']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const detect = detectPerfAudit({
+                projectRoot,
+                sessionId: sid,
+            });
+            const envelope = detect.state === 'ready'
+                ? ok('perf-audit.detect', detect, [...detect.warnings], [...detect.nextActions])
+                : fail('perf-audit.detect', detect.state.toUpperCase().replace(/-/g, '_'), `perf-audit is not ready: ${detect.state}`, detect, [...detect.nextActions]);
+            printResult(io, envelope, options.json);
+            if (detect.state !== 'ready') {
+                process.exitCode = 1;
+            }
+        }
+        catch (error) {
+            printResult(io, fail('perf-audit.detect', 'DETECT_PERF_AUDIT_FAILED', getErrorMessage(error), {
+                state: 'detection-failed',
+                handoffPresent: false,
+                templatePresent: false,
+                warnings: [],
+                nextActions: [],
+            }, ['Re-run with --project <path> pointing at a known-good project root.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(perfAudit
+        .command('run')
+        .description('Run the full perf-audit pipeline: detect → read handoff + template → write audit artifact to `.peaks/_runtime/<sid>/audit/perf-<rid>.md`. Reads the envelope JSON from --envelope <path> or stdin. The peaks-perf-audit skill emits the envelope; this CLI validates the shape via isPerfAuditEnvelope and writes the artifact. Exits 0 on success, 1 on any failure mode (detection, validation, or write).')
+        .option('--rid <rid>', 'request id (e.g. 2026-06-27-v2-12-...)')
+        .option('--sid <sid>', 'session id (e.g. 2026-06-27-session-...)')
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--envelope <path>', 'path to envelope JSON file; "-" reads from stdin (default: stdin)')).action((options) => {
+        const projectRoot = options.project ?? process.cwd();
+        const sid = options.sid;
+        const rid = options.rid;
+        if (sid === undefined || sid.length === 0) {
+            printResult(io, fail('perf-audit.run', 'SID_REQUIRED', 'session id (--sid) is required for perf-audit.run', {}, ['Pass --sid <session-id> (e.g. 2026-06-27-session-...)']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        if (rid === undefined || rid.length === 0) {
+            printResult(io, fail('perf-audit.run', 'RID_REQUIRED', 'request id (--rid) is required for perf-audit.run', {}, ['Pass --rid <request-id> (e.g. 2026-06-27-v2-12-...)']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            const envelopeValue = resolveEnvelope(options.envelope);
+            if (!isPerfAuditEnvelope(envelopeValue)) {
+                printResult(io, fail('perf-audit.run', 'ENVELOPE_MALFORMED', 'envelope failed isPerfAuditEnvelope validation (expected { verdict, violations, summary })', { receivedType: typeof envelopeValue }, [
+                    'Verify the peaks-perf-audit skill prompt matches the strict-shape contract.',
+                    'Re-emit the envelope; see skills/bee/peaks-perf-audit/references/audit-protocol.md.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const result = runPerfAudit({
+                projectRoot,
+                sessionId: sid,
+                rid,
+                generatedAt: new Date().toISOString(),
+                envelope: envelopeValue,
+            });
+            if (result.detect.state !== 'ready' || result.artifactPath === null) {
+                printResult(io, fail('perf-audit.run', result.detect.state.toUpperCase().replace(/-/g, '_'), `perf-audit is not ready: ${result.detect.state}`, result, [...result.detect.nextActions]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('perf-audit.run', {
+                detect: result.detect,
+                artifactPath: result.artifactPath,
+                violationsCount: result.violationsCount,
+                verdict: result.verdict,
+            }, [...result.detect.warnings], [...result.detect.nextActions]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('perf-audit.run', 'RUN_PERF_AUDIT_FAILED', getErrorMessage(error), {}, ['Verify the envelope JSON is well-formed and matches the strict-shape contract.']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/perf-commands.d.ts

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

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

@@ -0,0 +1,41 @@
+import { executePerfBaselineInit, resolveProjectRootFromCwd } from '../../services/perf/perf-baseline-service.js';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerPerfCommands(program, io) {
+    const perf = program.command('perf').description('Manage performance baseline scaffolding for the RD stage');
+    addJsonOption(perf
+        .command('baseline')
+        .description('Scaffold .peaks/_runtime/<sid>/rd/perf-baseline.md so the RD can record the slice\'s perf numbers in a stable place that QA Gate A4 can diff against. Default dry-run; pass --apply to write.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--apply', 'write the scaffold into the target project', false)
+        .option('--reason <text>', 'human-readable reason for the baseline (recorded in the response data)')).action(async (options) => {
+        try {
+            const projectRoot = options.project !== undefined
+                ? options.project
+                : resolveProjectRootFromCwd(process.cwd());
+            const result = await executePerfBaselineInit({
+                projectRoot,
+                apply: options.apply === true,
+                ...(options.reason !== undefined ? { reason: options.reason } : {})
+            });
+            const nextActions = [];
+            if (result.sessionId === null) {
+                nextActions.push('No peaks session is bound for this project yet. Run `peaks workspace init` (or any peaks skill) first so a session directory exists.');
+            }
+            else if (result.alreadyInitialized) {
+                nextActions.push(`perf-baseline.md already exists; no files were written. Re-run only after a re-measurement if you intend to overwrite.`);
+            }
+            else if (!result.apply) {
+                nextActions.push('Re-run with --apply to write the scaffold.');
+            }
+            else {
+                nextActions.push('Open the file and fill in the Results table — that is the input QA Gate A4 will diff against.');
+            }
+            printResult(io, ok('perf.baseline', result, [], nextActions), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('perf.baseline', 'PERF_BASELINE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Verify the project path exists and is writable']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}