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

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 'peaks-loop-doctor';
+import { fail, ok } from 'peaks-loop-shared/result';
+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.js

@@ -0,0 +1,132 @@
+import { readFileSync } from 'node:fs';
+import { detectPerfAudit, isPerfAuditEnvelope, runPerfAudit, } from 'peaks-loop-audit-independent';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+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', { hidden: true })
+        .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.js

@@ -0,0 +1,41 @@
+import { executePerfBaselineInit, resolveProjectRootFromCwd } from '../../services/perf/perf-baseline-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+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;
+        }
+    });
+}

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

@@ -0,0 +1,37 @@
+/**
+ * `peaks polyrepo *` — polyrepo workflow CLI surface.
+ *
+ * Slice S2-b of RD-2 (2026-07-08 session). Three subcommands:
+ *
+ *   init      — scan the parent dir for child git repos + write a
+ *               polyrepo manifest to `.peaks/polyrepo.json`.
+ *   status    — read the persisted manifest + report children.
+ *   dispatch  — mirror a PRD/RD/QA artifact from the parent into
+ *               each target child's
+ *               `.peaks/_runtime/<sid>/<role>/` directory.
+ *
+ * Per the project's two-axis convention, all reviewable artifacts
+ * live under `.peaks/_runtime/<sid>/<role>/` — never as top-level
+ * siblings of `.peaks/_runtime/`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface PolyrepoInitOptions {
+    json?: boolean;
+    root?: string;
+    children?: string;
+}
+export interface PolyrepoStatusOptions {
+    json?: boolean;
+    root?: string;
+}
+export interface PolyrepoDispatchOptions {
+    json?: boolean;
+    root?: string;
+    rid?: string;
+    to?: string;
+    role?: 'prd' | 'rd' | 'qa';
+    artifact?: string;
+    sid?: string;
+}
+export declare function registerPolyrepoCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,155 @@
+import { existsSync } from 'node:fs';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok, getErrorMessage } from 'peaks-loop-shared/result';
+import { PolyrepoService } from '../../services/polyrepo/polyrepo-service.js';
+function parseChildren(raw) {
+    if (raw === undefined || raw.length === 0)
+        return undefined;
+    return raw.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function resolveRoot(explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    return process.cwd();
+}
+export function registerPolyrepoCommands(program, io) {
+    const polyrepo = program
+        .command('polyrepo')
+        .description('Polyrepo workflow (parent dir + child git repos with their own .peaks/ subsets)');
+    // -----------------------------------------------------------------
+    // 1. peaks polyrepo init [--children <dir1,dir2>] [--root <dir>]
+    // -----------------------------------------------------------------
+    addJsonOption(polyrepo
+        .command('init')
+        .description('Scan the parent dir for child git repos and write .peaks/polyrepo.json')
+        .option('--children <list>', 'comma-separated child directory names (defaults to auto-discovery)')
+        .option('--root <path>', 'parent root (defaults to cwd)')).action((options) => {
+        try {
+            const root = resolveRoot(options.root);
+            const svc = new PolyrepoService();
+            const children = parseChildren(options.children);
+            const result = children === undefined
+                ? svc.init({ root })
+                : svc.init({ root, children });
+            printResult(io, ok('polyrepo.init', {
+                root: result.manifest.root,
+                detectedAt: result.manifest.detectedAt,
+                children: result.manifest.children,
+                manifestPath: `${result.manifest.root}/.peaks/polyrepo.json`,
+                created: result.created
+            }, [], [
+                result.manifest.children.length === 0
+                    ? 'No child git repos detected. Pass --children <dir1,dir2> to override.'
+                    : `Run \`peaks polyrepo dispatch --rid <rid> --to <child-id>\` to mirror an artifact into one or more children.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('polyrepo.init', 'POLYREPO_INIT_FAILED', getErrorMessage(error), {}, ['Verify --root exists and is a directory']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 2. peaks polyrepo status [--root <dir>]
+    // -----------------------------------------------------------------
+    addJsonOption(polyrepo
+        .command('status')
+        .description('Report the persisted polyrepo manifest + children')
+        .option('--root <path>', 'parent root (defaults to cwd)')).action((options) => {
+        try {
+            const root = resolveRoot(options.root);
+            const svc = new PolyrepoService();
+            const result = svc.status(root);
+            if (!result.manifestExists) {
+                printResult(io, ok('polyrepo.status', { ...result, initialized: false }, [], [
+                    'No polyrepo manifest found. Run `peaks polyrepo init [--children <list>]` first.'
+                ]), options.json);
+                return;
+            }
+            printResult(io, ok('polyrepo.status', { ...result, initialized: true }, [], [
+                result.children.length === 0
+                    ? 'Manifest exists but has no children. Re-run `peaks polyrepo init --children <list>`.'
+                    : `Run \`peaks polyrepo dispatch --rid <rid> --to <child-id>\` to mirror an artifact.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('polyrepo.status', 'POLYREPO_STATUS_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 3. peaks polyrepo dispatch --rid <rid> [--to <child-id>] --role <prd|rd|qa> --artifact <path>
+    // -----------------------------------------------------------------
+    addJsonOption(polyrepo
+        .command('dispatch')
+        .description('Mirror a PRD/RD/QA artifact from the parent into one or more children')
+        .requiredOption('--rid <rid>', 'request id (used in the on-disk filename)')
+        .option('--to <list>', 'comma-separated child ids (defaults to all children in the manifest)')
+        .requiredOption('--role <role>', 'artifact role: prd | rd | qa')
+        .requiredOption('--artifact <path>', 'source artifact path (relative to --root or absolute)')
+        .option('--sid <sid>', 'session id override (defaults to the canonical binding)')
+        .option('--root <path>', 'parent root (defaults to cwd)')).action((options) => {
+        try {
+            const root = resolveRoot(options.root);
+            const sid = options.sid ?? 'default';
+            const rid = options.rid ?? '';
+            const role = options.role;
+            if (role !== 'prd' && role !== 'rd' && role !== 'qa') {
+                printResult(io, fail('polyrepo.dispatch', 'INVALID_ROLE', `--role must be prd | rd | qa (got "${role}")`, {}, [
+                    'Re-run with --role prd (or rd / qa).'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const artifact = options.artifact ?? '';
+            if (!existsSync(artifact)) {
+                printResult(io, fail('polyrepo.dispatch', 'ARTIFACT_NOT_FOUND', `source artifact does not exist: ${artifact}`, {}, [
+                    'Verify the path or pass an absolute path.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Resolve targets from the manifest first so we can default to
+            // "all children" when --to is omitted.
+            const svc = new PolyrepoService();
+            const status = svc.status(root);
+            if (!status.manifestExists) {
+                printResult(io, fail('polyrepo.dispatch', 'NO_MANIFEST', `no polyrepo manifest at ${root}/.peaks/polyrepo.json`, {}, [
+                    'Run `peaks polyrepo init` first.'
+                ]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            let targets;
+            if (options.to !== undefined && options.to.length > 0) {
+                targets = options.to.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+            }
+            else {
+                targets = status.children.map((c) => c.id);
+            }
+            const result = svc.dispatch(root, {
+                sid, rid, targets, role, artifactPath: artifact
+            });
+            const allOk = result.perChild.every((c) => c.ok);
+            printResult(io, ok('polyrepo.dispatch', {
+                root,
+                sid,
+                rid,
+                role,
+                artifact,
+                dispatch: result.dispatch,
+                perChild: result.perChild,
+                allOk
+            }, result.warnings, [
+                allOk
+                    ? `Mirrored artifact to ${result.perChild.length} child(ren).`
+                    : `One or more child mirrors failed; inspect perChild[].ok.`
+            ]), options.json);
+            if (!allOk)
+                process.exitCode = 1;
+        }
+        catch (error) {
+            printResult(io, fail('polyrepo.dispatch', 'POLYREPO_DISPATCH_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/prd-blocks-commands.js

@@ -0,0 +1,50 @@
+/**
+ * v2.15.0 follow-up — G3: prd 4 必填块 CLI (sub-command under existing `peaks prd`).
+ *
+ *   - `peaks prd check-blocks <request-id>` — validate the prd artifact
+ *     contains the 4 mandatory sections (业务场景 / 边界 case /
+ *     UI 装配意图 / 上游基线). Complements `peaks request lint`
+ *     (which checks placeholders) by checking the design quality
+ *     lock-down at the prd stage.
+ *
+ * NOTE: lives under existing `peaks prd` (registered by
+ * `prd-commands.ts`). This file does NOT create a new top-level
+ * `peaks prd` — that would collide with the existing prd-commands
+ * registration and break `peaks request transition --role prd` due
+ * to Commander routing conflicts.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { checkPrdBlocks } from '../../services/prd/prd-blocks-checker.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerPrdBlocksCommands(program, io) {
+    // Find existing `prd` top-level command (registered by prd-commands.ts).
+    // Do NOT create a new one — that collides with the existing prd role
+    // command and breaks `peaks request transition --role prd`.
+    const prd = program.commands.find((c) => c.name() === 'prd');
+    if (prd === undefined) {
+        // Fallback: create if missing. Should never trigger in normal startup.
+        program
+            .command('prd')
+            .description('v2.15.0 follow-up G3: PRD design-quality gates.');
+    }
+    const target = prd ?? program.commands.find((c) => c.name() === 'prd');
+    addJsonOption(target
+        .command('check-blocks <request-id>')
+        .description('Validate the prd artifact body contains the 4 mandatory sections: ' +
+        '业务场景 / 边界 case / UI 装配意图 / 上游基线 (latter required only for fork projects). ' +
+        'Complements `peaks request lint`. Exits non-zero when any required block is missing or too short.')
+        .requiredOption('--project <path>', 'project root')).action((requestId, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const report = checkPrdBlocks(projectRoot, requestId);
+        printResult(io, ok('prd.check-blocks', report, [], report.ok
+            ? []
+            : [
+                'Fix the missing / too-short required blocks above.',
+                'The 12 Gaps positioning memory: prd design quality is the only lever — execution layer does not add quality.'
+            ]), opts.json ?? false);
+        if (!report.ok) {
+            process.exitCode = 1;
+        }
+    });
+}