peaks-loop 4.1.2 → 4.1.4

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

@@ -1,311 +1,38 @@
-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, OpenSpecArchiveError } 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/index.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { normalizePath } from '../../shared/path-utils.js';
-function resolveScanOptions(project) {
-    if (project === undefined) {
-        return {};
-    }
-    return { openspecRoot: `${normalizePath(project).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;
-}
+// src/cli/commands/openspec-commands.ts
+//
+// The `openspec` parent command and the registration order of its verbs.
+// The verb implementations live beside this file, one module per verb:
+//
+//   openspec-command-shared.ts        option shapes, flag translation, printers
+//   openspec-list-command.ts          list
+//   openspec-show-command.ts          show
+//   openspec-to-rd-command.ts         to-rd
+//   openspec-render-command.ts        render
+//   openspec-validate-command.ts      validate
+//   openspec-archive-command.ts       archive
+//   openspec-init-command.ts          init
+//   openspec-from-doctor-command.ts   from-doctor
+//
+// The order of the calls below IS the order commander registers the
+// subcommands in, so it is part of the CLI's observable surface.
+import { registerOpenSpecListCommand } from './openspec-list-command.js';
+import { registerOpenSpecShowCommand } from './openspec-show-command.js';
+import { registerOpenSpecToRdCommand } from './openspec-to-rd-command.js';
+import { registerOpenSpecRenderCommand } from './openspec-render-command.js';
+import { registerOpenSpecValidateCommand } from './openspec-validate-command.js';
+import { registerOpenSpecArchiveCommand } from './openspec-archive-command.js';
+import { registerOpenSpecInitCommand } from './openspec-init-command.js';
+import { registerOpenSpecFromDoctorCommand } from './openspec-from-doctor-command.js';
 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('--force', 'bypass the Pre-cond 2 Coverage Evidence gate (use only after confirming the gap is acceptable for this archive)')
-        .option('--coverage-summary <path>', 'override coverage-summary.json discovery (Fix-6B). Default: <projectRoot>/coverage/coverage-summary.json, then <projectRoot>/openspec/coverage-summary.json')
-        .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.force === true) {
-                archiveOptions.force = true;
-            }
-            if (options.coverageSummary !== undefined) {
-                archiveOptions.coverageSummaryPath = options.coverageSummary;
-            }
-            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;
-            }
-            const warnings = [];
-            if (result.coverageGateBypassed === true) {
-                warnings.push('Coverage gate bypassed via --force; archived with at least one uncovered requirement.');
-            }
-            if (result.coverageMismatchBypassed === true) {
-                warnings.push('Coverage summary mismatch bypassed via --force; archived with at least one capability below 100%.');
-            }
-            printResult(io, ok('openspec.archive', result, warnings, result.applied ? [] : [`Re-run with --apply to move ${result.from} → ${result.to}`]), options.json);
-        }
-        catch (error) {
-            if (error instanceof OpenSpecArchiveError) {
-                printResult(io, fail('openspec.archive', error.code, getErrorMessage(error), error.detail, nextActionsForArchiveError(error.code)), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            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;
-        }
-    });
-}
-/**
- * Per-error-code remediation hints for the archive gate.
- * Centralized here so the catch block stays readable and the next-actions
- * can be reviewed in isolation.
- */
-function nextActionsForArchiveError(code) {
-    switch (code) {
-        case 'OPENSPEC_COVERAGE_GATE_PARTIAL':
-            return [
-                'Update the Coverage Evidence table to mark each failing requirement as covered',
-                'Or re-run with --force to bypass the gate after confirming the gap is acceptable'
-            ];
-        case 'OPENSPEC_COVERAGE_GATE_FAILED':
-            return [
-                'Add the missing Coverage Evidence or Capability Mapping block to proposal.md (see error.message)',
-                'Or re-run with --force to bypass the gate after confirming the gap is acceptable'
-            ];
-        case 'OPENSPEC_COVERAGE_EVIDENCE_MALFORMED':
-            return [
-                'Fix the proposal.md Coverage Evidence table — the heading exists but no parsable rows were found',
-                'Expected shape: | capability | requirement | status | testAnchor | with status in {covered, partial, uncovered}'
-            ];
-        case 'OPENSPEC_COVERAGE_EVIDENCE_MISSING':
-            return [
-                'Run `pnpm test:coverage` (which invokes scripts/coverage-c8.mjs) to generate coverage-summary.json',
-                'Or pass --coverage-summary <path> to point at an existing summary',
-                'Or re-run with --force to bypass the gate'
-            ];
-        case 'OPENSPEC_COVERAGE_EVIDENCE_STALE':
-            return [
-                'Re-run `pnpm test:coverage` to refresh coverage-summary.json',
-                'Or re-run with --force to bypass the gate after confirming the source delta is acceptable'
-            ];
-        case 'OPENSPEC_COVERAGE_EVIDENCE_MISMATCH':
-            return [
-                'Inspect error.detail.mismatches[] — each entry lists the failing capability, file, and actual pct',
-                'Close the coverage gap (add tests or update the Capability Mapping block in proposal.md)',
-                'Or re-run with --force to bypass the gate after confirming the gap is acceptable'
-            ];
-    }
+    registerOpenSpecListCommand(openspec, io);
+    registerOpenSpecShowCommand(openspec, io);
+    registerOpenSpecToRdCommand(openspec, io);
+    registerOpenSpecRenderCommand(openspec, io);
+    registerOpenSpecValidateCommand(openspec, io);
+    registerOpenSpecArchiveCommand(openspec, io);
+    registerOpenSpecInitCommand(openspec, io);
+    registerOpenSpecFromDoctorCommand(openspec, io);
 }

package/dist/cli/commands/openspec-from-doctor-command.d.ts

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

package/dist/cli/commands/openspec-from-doctor-command.js

@@ -0,0 +1,66 @@
+// src/cli/commands/openspec-from-doctor-command.ts
+//
+// `peaks openspec from-doctor` — draft a change proposal from a failing
+// `peaks doctor` check. Extracted from `openspec-commands.ts`; the registered
+// name, description, options and envelopes are unchanged.
+import { proposeFromDoctor } from '../../services/openspec/openspec-propose-from-doctor-service.js';
+import { runDoctor } from '../../services/doctor/index.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { failOpenSpec } from './openspec-command-shared.js';
+/**
+ * Resolve `--check-id` against the live doctor report. A missing id or an
+ * already-passing check both print their own envelope and return null; the
+ * caller stops without writing a draft.
+ */
+function draftFromDoctor(io, report, options) {
+    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 null;
+    }
+    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 null;
+    }
+    return {
+        id: finding.id,
+        rule: finding.rule ?? finding.id,
+        detail: finding.message,
+        severity: 'fail'
+    };
+}
+export function registerOpenSpecFromDoctorCommand(openspec, io) {
+    // Slice L3.3: from-doctor — auto-generate an OpenSpec change record
+    // (proposal.md) from a doctor finding. The LLM then reviews + edits
+    // the draft before peaks openspec validate will accept it.
+    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 = draftFromDoctor(io, report, options);
+            if (finding === null) {
+                return;
+            }
+            const result = proposeFromDoctor({ projectRoot: options.project, finding });
+            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) {
+            failOpenSpec(io, 'openspec.from-doctor', {
+                code: 'OPENSPEC_FROM_DOCTOR_FAILED',
+                error,
+                data: { projectRoot: options.project, checkId: options.checkId },
+                nextActions: ['Verify the project path and the check id'],
+                json: options.json
+            });
+        }
+    });
+}

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

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

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

@@ -0,0 +1,49 @@
+// src/cli/commands/openspec-init-command.ts
+//
+// `peaks openspec init --project <root>`. Extracted from
+// `openspec-commands.ts`; the registered name, description, options and
+// envelopes are unchanged.
+import { executeOpenSpecInit } from '../../services/openspec/openspec-init-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { failOpenSpec } from './openspec-command-shared.js';
+/** The `openspec.init` follow-up lines; one branch per scaffold outcome. */
+function initNextActions(result) {
+    if (result.alreadyInitialized) {
+        const nextActions = ['openspec/ already exists; no files were created or modified.'];
+        if (result.existingFiles.length > 0) {
+            nextActions.push(`Existing files preserved: ${result.existingFiles.join(', ')}`);
+        }
+        return nextActions;
+    }
+    if (!result.apply) {
+        return ['Re-run with --apply to write the planned files to disk.'];
+    }
+    return [
+        'Run `peaks openspec render --request <path> --apply` to scaffold a first change proposal.'
+    ];
+}
+export function registerOpenSpecInitCommand(openspec, io) {
+    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
+            });
+            printResult(io, ok('openspec.init', result, [], initNextActions(result)), options.json);
+        }
+        catch (error) {
+            failOpenSpec(io, 'openspec.init', {
+                code: 'OPENSPEC_INIT_FAILED',
+                error,
+                data: { projectRoot: options.project },
+                nextActions: ['Verify the project path exists and is writable'],
+                json: options.json
+            });
+        }
+    });
+}

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

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

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

@@ -0,0 +1,27 @@
+// src/cli/commands/openspec-list-command.ts
+//
+// `peaks openspec list`. Extracted from `openspec-commands.ts`; the registered
+// name, description, options and envelopes are unchanged.
+import { scanOpenSpec } from '../../services/openspec/openspec-scan-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { failOpenSpec, OPENSPEC_PATH_HINT, resolveScanOptions } from './openspec-command-shared.js';
+export function registerOpenSpecListCommand(openspec, io) {
+    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) {
+            failOpenSpec(io, 'openspec.list', {
+                code: 'OPENSPEC_LIST_FAILED',
+                error,
+                nextActions: OPENSPEC_PATH_HINT,
+                json: options.json
+            });
+        }
+    });
+}

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

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

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

@@ -0,0 +1,33 @@
+// src/cli/commands/openspec-render-command.ts
+//
+// `peaks openspec render --request <path>`. Extracted from
+// `openspec-commands.ts`; the registered name, description, options and
+// envelopes are unchanged.
+import { renderOpenSpecChange } from '../../services/openspec/openspec-render-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { failOpenSpec, loadRenderRequest, toRenderOptions } from './openspec-command-shared.js';
+export function registerOpenSpecRenderCommand(openspec, io) {
+    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 result = await renderOpenSpecChange(request, toRenderOptions(options.project, options));
+            printResult(io, ok('openspec.render', result), options.json);
+        }
+        catch (error) {
+            failOpenSpec(io, 'openspec.render', {
+                code: 'OPENSPEC_RENDER_FAILED',
+                error,
+                data: { requestPath: options.request },
+                nextActions: ['Check the request JSON shape and the openspec root before retrying'],
+                json: options.json
+            });
+        }
+    });
+}

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

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

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

@@ -0,0 +1,33 @@
+// src/cli/commands/openspec-show-command.ts
+//
+// `peaks openspec show <changeId>`. Extracted from `openspec-commands.ts`; the
+// registered name, description, options and envelopes are unchanged.
+import { loadOpenSpecChange } from '../../services/openspec/openspec-scan-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { failOpenSpec, OPENSPEC_PATH_HINT, printChangeNotFound, resolveScanOptions } from './openspec-command-shared.js';
+export function registerOpenSpecShowCommand(openspec, io) {
+    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) {
+                printChangeNotFound(io, 'openspec.show', changeId, options.json);
+                return;
+            }
+            printResult(io, ok('openspec.show', detail), options.json);
+        }
+        catch (error) {
+            failOpenSpec(io, 'openspec.show', {
+                code: 'OPENSPEC_SHOW_FAILED',
+                error,
+                data: { changeId },
+                nextActions: OPENSPEC_PATH_HINT,
+                json: options.json
+            });
+        }
+    });
+}

package/dist/cli/commands/openspec-to-rd-command.d.ts

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

package/dist/cli/commands/openspec-to-rd-command.js

@@ -0,0 +1,33 @@
+// src/cli/commands/openspec-to-rd-command.ts
+//
+// `peaks openspec to-rd <changeId>`. Extracted from `openspec-commands.ts`; the
+// registered name, description, options and envelopes are unchanged.
+import { projectOpenSpecToRdInput } from '../../services/openspec/openspec-bridge-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { failOpenSpec, OPENSPEC_PATH_HINT, printChangeNotFound, resolveScanOptions } from './openspec-command-shared.js';
+export function registerOpenSpecToRdCommand(openspec, io) {
+    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) {
+                printChangeNotFound(io, 'openspec.to-rd', changeId, options.json);
+                return;
+            }
+            printResult(io, ok('openspec.to-rd', projection), options.json);
+        }
+        catch (error) {
+            failOpenSpec(io, 'openspec.to-rd', {
+                code: 'OPENSPEC_TO_RD_FAILED',
+                error,
+                data: { changeId },
+                nextActions: OPENSPEC_PATH_HINT,
+                json: options.json
+            });
+        }
+    });
+}

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

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