peaks-loop 4.1.2 → 4.1.4

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

@@ -0,0 +1,129 @@
+// src/cli/commands/memory-list-command.ts
+//
+// `peaks memory list` — read `.peaks/memory/index.json`, optionally with fzf
+// multi-select, plus the Slice B `--summary` view. Extracted from
+// `memory-commands.ts`; the envelope, the flags and the exported symbol names
+// are unchanged.
+import { join } from 'node:path';
+import { ok } from 'peaks-loop-shared/result';
+import { boundedNames, fitSummaryToBytes } from '../../services/context/summary-view.js';
+import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
+import { loadMemoryIndex } from '../../services/memory/memory-search-service.js';
+import { printResult } from '../cli-helpers.js';
+import { memoryFailure, resolveKindFilter, resolveMemoryProjectRoot } from './memory-command-shared.js';
+/**
+ * Slice B: bounded view of `memory list`. `count` is the true total; `names`
+ * carries `name (kind)` labels for the first N entries.
+ */
+export function buildMemoryListSummary(data) {
+    const label = (e) => `${e.name} (${e.kind})`;
+    const view = {
+        view: 'summary',
+        indexPath: data.snapshot.indexPath,
+        version: data.snapshot.version,
+        updatedAt: data.snapshot.updatedAt,
+        total: data.entries.length,
+        kindFilter: data.kindFilter ?? null,
+        entries: boundedNames(data.entries.map(label))
+    };
+    if (data.pickedOutputPath !== null) {
+        view.picked = boundedNames(data.pickedEntries.map(label));
+        view.pickedOutputPath = data.pickedOutputPath;
+        view.fzfVersion = data.fzfVersion;
+    }
+    return fitSummaryToBytes(view);
+}
+export async function runMemoryList(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    try {
+        const snapshot = loadMemoryIndex(projectRoot);
+        const kindFilter = resolveKindFilter(options.kind);
+        const entries = kindFilter === undefined
+            ? snapshot.entries
+            : snapshot.entries.filter((e) => e.kind === kindFilter);
+        const picked = await pickMemoryEntries(projectRoot, entries, kindFilter, options);
+        const data = memoryListData({ snapshot, entries, kindFilter, options, picked });
+        printResult(io, ok('memory.list', data, [], listNextActions(entries, picked)), options.json);
+    }
+    catch (error) {
+        printResult(io, memoryFailure({
+            command: 'memory.list',
+            fallbackCode: 'MEMORY_LIST_FAILED',
+            error,
+            projectRoot,
+            byCode: {
+                INDEX_MISSING: 'Run `peaks memory extract` to build the index from memory/*.md files'
+            }
+        }), options.json);
+        process.exitCode = 1;
+    }
+}
+/** The pick notice and the empty-index notice, in that order. */
+function listNextActions(entries, picked) {
+    const nextActions = [];
+    if (picked.pickedOutputPath !== null) {
+        nextActions.push(`Picked ${picked.pickedEntries.length} entr(ies); written to ${picked.pickedOutputPath}`);
+    }
+    if (entries.length === 0) {
+        nextActions.push('No entries match; run `peaks memory extract` to build the index from memory/*.md files.');
+    }
+    return nextActions;
+}
+/**
+ * Slice B: `--summary` swaps the full entry array for a bounded
+ * `{count, names}` view. The default (no flag) view is byte-identical to
+ * before — the flag is strictly opt-in.
+ */
+function memoryListData(input) {
+    const { snapshot, entries, kindFilter, options, picked } = input;
+    if (options.summary === true) {
+        return buildMemoryListSummary({ snapshot, entries, kindFilter, ...picked });
+    }
+    return {
+        indexPath: snapshot.indexPath,
+        version: snapshot.version,
+        updatedAt: snapshot.updatedAt,
+        total: entries.length,
+        kindFilter: kindFilter ?? null,
+        entries,
+        ...(options.pick === true
+            ? {
+                picked: picked.pickedEntries,
+                pickedOutputPath: picked.pickedOutputPath,
+                fzfVersion: picked.fzfVersion
+            }
+            : {})
+    };
+}
+/** The `--pick` branch, or the unchanged entry list when the flag is absent. */
+async function pickMemoryEntries(projectRoot, entries, kindFilter, options) {
+    if (options.pick !== true) {
+        return { pickedEntries: entries, pickedOutputPath: null, fzfVersion: null };
+    }
+    const outputPath = join(projectRoot, '.peaks', 'memory', 'picked.json');
+    const byName = new Map(entries.map((e) => [e.name, e]));
+    const result = await pickFromList({
+        items: entries,
+        formatLine: (entry) => `${entry.name} | ${entry.kind} | ${entry.description.slice(0, 60)}`,
+        parseLine: (line) => {
+            const parts = line.split('|').map((p) => p.trim());
+            if (parts.length < 1)
+                return null;
+            const name = parts[0];
+            if (name === undefined || name.length === 0)
+                return null;
+            return byName.get(name) ?? null;
+        },
+        outputPath,
+        meta: { kindFilter: kindFilter ?? null, totalCandidates: entries.length },
+        ...(options.fzfBin !== undefined ? { fzfBin: options.fzfBin } : {}),
+        projectRoot,
+        multi: true,
+        prompt: 'memory> '
+    });
+    return {
+        pickedEntries: [...result.picked],
+        pickedOutputPath: result.outputPath,
+        fzfVersion: result.fzfVersion
+    };
+}

package/dist/cli/commands/memory-reindex-command.d.ts

@@ -0,0 +1,9 @@
+import { type MemoryReindexReport } from '../../services/memory/project-memory-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+import { type MemoryReindexCommandOptions } from './memory-command-shared.js';
+/**
+ * `memory reindex`. The full report's arrays stay on disk / in the default
+ * envelope; this replaces them with `{count, names}` views (≤ 2 KB).
+ */
+export declare function buildMemoryReindexSummary(report: MemoryReindexReport): Record<string, unknown>;
+export declare function runMemoryReindex(io: ProgramIO, options: MemoryReindexCommandOptions): Promise<void>;

package/dist/cli/commands/memory-reindex-command.js

@@ -0,0 +1,78 @@
+// src/cli/commands/memory-reindex-command.ts
+//
+// `peaks memory reindex` — rebuild `.peaks/memory/index.json` from disk and
+// regenerate `MEMORY.md`. Dry-run by default; `--apply` writes. Extracted from
+// `memory-commands.ts`; the envelope, the flags and the exported symbol names
+// are unchanged.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { boundedNames, fitSummaryToBytes } from '../../services/context/summary-view.js';
+import { executeMemoryReindex } from '../../services/memory/project-memory-service.js';
+import { printResult } from '../cli-helpers.js';
+import { memoryFailure, resolveMemoryProjectRoot } from './memory-command-shared.js';
+/**
+ * `memory reindex`. The full report's arrays stay on disk / in the default
+ * envelope; this replaces them with `{count, names}` views (≤ 2 KB).
+ */
+export function buildMemoryReindexSummary(report) {
+    const view = {
+        view: 'summary',
+        apply: report.apply,
+        projectRoot: report.projectRoot,
+        memoryDir: report.memoryDir,
+        indexPath: report.indexPath,
+        memoryMdPath: report.memoryMdPath,
+        scannedFiles: report.scannedFiles,
+        indexed: report.indexed,
+        indexedByKind: report.indexedByKind,
+        unclassified: boundedNames(report.unclassified.map((u) => `${u.name}${u.rawKind === null ? '' : ` (${u.rawKind})`}`)),
+        nameConflicts: boundedNames(report.nameConflicts.map((c) => c.name)),
+        orphanIndex: boundedNames(report.orphanIndex.map((o) => o.name)),
+        orphanDisk: boundedNames(report.orphanDisk.map((p) => p.split(/[\\/]/).pop() ?? p)),
+        memoryMd: report.memoryMd,
+        writtenFiles: boundedNames(report.writtenFiles.map((p) => p.split(/[\\/]/).pop() ?? p))
+    };
+    return fitSummaryToBytes(view);
+}
+export async function runMemoryReindex(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    if (options.dryRun === true && options.apply === true) {
+        printResult(io, fail('memory.reindex', 'INVALID_MEMORY_REINDEX_FLAGS', 'Use either --dry-run or --apply, not both', {}, ['Run without --apply to preview the drift report, or pass --apply to rebuild']), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const report = executeMemoryReindex({ projectRoot, apply: options.apply === true });
+        // Slice B: `--summary` keeps the scalar drift counts + names-of-first-N;
+        // the full report (with every unclassified/orphan path) stays available
+        // by omitting the flag. Default shape is unchanged.
+        const data = options.summary === true ? buildMemoryReindexSummary(report) : report;
+        printResult(io, ok('memory.reindex', data, [], reindexNextActions(report, options)), options.json);
+    }
+    catch (error) {
+        printResult(io, memoryFailure({
+            command: 'memory.reindex',
+            fallbackCode: 'MEMORY_REINDEX_FAILED',
+            error,
+            projectRoot,
+            suggestions: ['Check that the project has a readable .peaks/memory directory']
+        }), options.json);
+        process.exitCode = 1;
+    }
+}
+/** The drift notices the report earns, in the report's own field order. */
+function reindexNextActions(report, options) {
+    const nextActions = [];
+    if (options.apply !== true) {
+        nextActions.push('Preview only — re-run with --apply to rebuild index.json and regenerate MEMORY.md.');
+    }
+    if (report.unclassified.length > 0) {
+        nextActions.push(`${report.unclassified.length} file(s) have no resolvable kind; add \`metadata.type\` (or \`kind:\`) to index them.`);
+    }
+    if (report.orphanIndex.length > 0) {
+        nextActions.push(`${report.orphanIndex.length} previous index entry(ies) point at missing files; they are dropped from the rebuilt index.`);
+    }
+    if (report.nameConflicts.length > 0) {
+        nextActions.push(`${report.nameConflicts.length} name collision(s) across files; both entries are kept — rename one file to disambiguate.`);
+    }
+    return nextActions;
+}

package/dist/cli/commands/memory-rotate-command.d.ts

@@ -0,0 +1,3 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type MemoryRotateCommandOptions } from './memory-command-shared.js';
+export declare function runMemoryRotate(io: ProgramIO, options: MemoryRotateCommandOptions): Promise<void>;

package/dist/cli/commands/memory-rotate-command.js

@@ -0,0 +1,55 @@
+// src/cli/commands/memory-rotate-command.ts
+//
+// `peaks memory rotate` — tier-driven retention for `.peaks/memory/`
+// (sediment pruning policy, tier 1: archive, never delete). Dry-run by default;
+// `--apply` moves tier-C candidates into `archived/`. Extracted from
+// `memory-commands.ts`; the envelope, the flags and the exported symbol name
+// are unchanged.
+import { fail, ok } from 'peaks-loop-shared/result';
+import { executeMemoryRotate } from '../../services/memory/memory-rotate-service.js';
+import { printResult } from '../cli-helpers.js';
+import { memoryFailure, resolveMemoryProjectRoot } from './memory-command-shared.js';
+export async function runMemoryRotate(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    if (options.dryRun === true && options.apply === true) {
+        printResult(io, fail('memory.rotate', 'INVALID_MEMORY_ROTATE_FLAGS', 'Use either --dry-run or --apply, not both', {}, [
+            'Run without --apply to preview the rotation plan, or pass --apply to archive tier-C candidates'
+        ]), options.json);
+        process.exitCode = 1;
+        return;
+    }
+    try {
+        const report = executeMemoryRotate({ projectRoot, apply: options.apply === true });
+        printResult(io, ok('memory.rotate', report, report.warnings, rotateNextActions(report, options)), options.json);
+        if (report.refused)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        printResult(io, memoryFailure({
+            command: 'memory.rotate',
+            fallbackCode: 'MEMORY_ROTATE_FAILED',
+            error,
+            projectRoot,
+            suggestions: ['Check that the project has a readable .peaks/memory directory']
+        }), options.json);
+        process.exitCode = 1;
+    }
+}
+/** The refusal / preview / exclusion / tier-D notices the plan earns, in order. */
+function rotateNextActions(report, options) {
+    const nextActions = [];
+    if (report.refused) {
+        nextActions.push(`Refused to apply: ${report.refusalReasons.join('; ')}`);
+    }
+    else if (options.apply !== true) {
+        nextActions.push('Preview only — re-run with --apply to move the tier-C candidates into archived/.');
+    }
+    if (report.excluded.length > 0) {
+        nextActions.push(`${report.excluded.length} candidate(s) excluded by a safety gate (see \`excluded\`).`);
+    }
+    const deleteCandidates = report.candidates.filter((candidate) => candidate.action === 'delete-candidate');
+    if (deleteCandidates.length > 0) {
+        nextActions.push(`${deleteCandidates.length} tier-D file(s) are delete-candidates only; peaks never deletes them — remove by hand if you are sure.`);
+    }
+    return nextActions;
+}

package/dist/cli/commands/memory-search-command.d.ts

@@ -0,0 +1,7 @@
+import { type ProgramIO } from '../cli-helpers.js';
+import { type MemorySearchCommandOptions } from './memory-command-shared.js';
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export declare function runMemorySearch(io: ProgramIO, options: MemorySearchCommandOptions): Promise<void>;

package/dist/cli/commands/memory-search-command.js

@@ -0,0 +1,46 @@
+// src/cli/commands/memory-search-command.ts
+//
+// `peaks memory search` — deterministic, local, zero-token fuzzy search over
+// the memory index. Extracted from `memory-commands.ts`; the envelope, the
+// flags and the exported symbol name are unchanged.
+import { ok } from 'peaks-loop-shared/result';
+import { searchMemory } from '../../services/memory/memory-search-service.js';
+import { printResult } from '../cli-helpers.js';
+import { memoryFailure, resolveKindFilter, resolveMemoryProjectRoot } from './memory-command-shared.js';
+/** The one action each named failure earns. */
+const SEARCH_HINTS = {
+    INDEX_MISSING: 'Run `peaks memory extract --apply` to build the index from memory/*.md files',
+    EMPTY_QUERY: 'Use `peaks memory index` to list all entries'
+};
+/**
+ * Run the memory search subcommand. Extracted so unit tests can
+ * exercise the full envelope without spawning a subprocess.
+ */
+export async function runMemorySearch(io, options) {
+    const projectRoot = resolveMemoryProjectRoot(options.project);
+    const kindFilter = resolveKindFilter(options.kind);
+    try {
+        const matches = searchMemory({
+            query: options.query,
+            projectRoot,
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(kindFilter !== undefined ? { kind: kindFilter } : {})
+        });
+        printResult(io, ok('memory.search', {
+            query: options.query,
+            total: matches.length,
+            matches,
+            warnings: []
+        }, []), options.json);
+    }
+    catch (error) {
+        printResult(io, memoryFailure({
+            command: 'memory.search',
+            fallbackCode: 'MEMORY_SEARCH_FAILED',
+            error,
+            projectRoot,
+            byCode: SEARCH_HINTS
+        }), options.json);
+        process.exitCode = 1;
+    }
+}

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

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

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

@@ -0,0 +1,55 @@
+// src/cli/commands/openspec-archive-command.ts
+//
+// `peaks openspec archive <changeId>`. Extracted from `openspec-commands.ts`;
+// the registered name, description, options and envelopes are unchanged.
+import { archiveOpenSpecChange, OpenSpecArchiveError } from '../../services/openspec/openspec-archive-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { failOpenSpec, OPENSPEC_PATH_HINT, printArchiveError, printChangeNotFound, toArchiveOptions } from './openspec-command-shared.js';
+/** The `--force` bypasses an archived run reports, in a fixed order. */
+function archiveWarnings(result) {
+    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%.');
+    }
+    return warnings;
+}
+const ARCHIVE_DESCRIPTION = 'Move an OpenSpec change under openspec/changes/<archiveDir>/<id>/ (dry-run by default)';
+const FORCE_DESCRIPTION = 'bypass the Pre-cond 2 Coverage Evidence gate (use only after confirming the gap is acceptable for this archive)';
+const COVERAGE_SUMMARY_DESCRIPTION = 'override coverage-summary.json discovery (Fix-6B). Default: <projectRoot>/coverage/coverage-summary.json, then <projectRoot>/openspec/coverage-summary.json';
+export function registerOpenSpecArchiveCommand(openspec, io) {
+    addJsonOption(openspec
+        .command('archive')
+        .description(ARCHIVE_DESCRIPTION)
+        .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', FORCE_DESCRIPTION)
+        .option('--coverage-summary <path>', COVERAGE_SUMMARY_DESCRIPTION)
+        .option('--archive-dir <name>', 'archive subdirectory name (default: archive)')).action(async (changeId, options) => {
+        try {
+            const result = await archiveOpenSpecChange(changeId, toArchiveOptions(options.project, options));
+            if (result === null) {
+                printChangeNotFound(io, 'openspec.archive', changeId, options.json);
+                return;
+            }
+            printResult(io, ok('openspec.archive', result, archiveWarnings(result), result.applied ? [] : [`Re-run with --apply to move ${result.from} → ${result.to}`]), options.json);
+        }
+        catch (error) {
+            if (error instanceof OpenSpecArchiveError) {
+                printArchiveError(io, error, options.json);
+                return;
+            }
+            failOpenSpec(io, 'openspec.archive', {
+                code: 'OPENSPEC_ARCHIVE_FAILED',
+                error,
+                data: { changeId },
+                nextActions: OPENSPEC_PATH_HINT,
+                json: options.json
+            });
+        }
+    });
+}

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

@@ -0,0 +1,62 @@
+import type { OpenSpecScanOptions } from '../../services/openspec/openspec-scan-service.js';
+import type { OpenSpecArchiveError, OpenSpecArchiveOptions } from '../../services/openspec/openspec-archive-service.js';
+import type { OpenSpecRenderOptions, OpenSpecRenderRequest } from '../../services/openspec/openspec-render-service.js';
+import type { OpenSpecValidateOptions } from '../../services/openspec/openspec-validate-service.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export type OpenSpecListOptions = {
+    project?: string;
+    json?: boolean;
+};
+export type OpenSpecShowOptions = OpenSpecListOptions;
+export type OpenSpecToRdOptions = OpenSpecListOptions;
+export type OpenSpecRenderCommandOptions = OpenSpecListOptions & {
+    request: string;
+    apply?: boolean;
+    overwrite?: boolean;
+};
+export type OpenSpecValidateCommandOptions = OpenSpecListOptions & {
+    preferExternal?: boolean;
+};
+export type OpenSpecArchiveCommandOptions = OpenSpecListOptions & {
+    apply?: boolean;
+    force?: boolean;
+    coverageSummary?: string;
+    archiveDir?: string;
+};
+export type OpenSpecInitCommandOptions = {
+    project: string;
+    apply?: boolean;
+    json?: boolean;
+};
+/** The next action every path/layout failure carries. */
+export declare const OPENSPEC_PATH_HINT: string[];
+/** Everything a verb-specific catch needs to build its failure envelope. */
+export type OpenSpecFailure = {
+    readonly code: string;
+    readonly error: unknown;
+    readonly nextActions: string[];
+    readonly json: boolean | undefined;
+    readonly data?: Record<string, unknown>;
+};
+export declare function resolveScanOptions(project: string | undefined): OpenSpecScanOptions;
+export declare function loadRenderRequest(requestPath: string): Promise<OpenSpecRenderRequest>;
+/** Print a verb failure and mark the run failed. One call site per catch. */
+export declare function failOpenSpec(io: ProgramIO, command: string, failure: OpenSpecFailure): void;
+/** The `<changeId>` resolution every change-scoped verb shares. */
+export declare function printChangeNotFound(io: ProgramIO, command: string, changeId: string, json: boolean | undefined): void;
+/**
+ * Translate `--project` into the service option shape, carrying only the flags
+ * the caller actually set (a `false`/`undefined` flag must stay absent, not be
+ * written as `false`).
+ */
+export declare function toRenderOptions(project: string | undefined, options: OpenSpecRenderCommandOptions): OpenSpecRenderOptions;
+export declare function toValidateOptions(project: string | undefined, options: OpenSpecValidateCommandOptions): OpenSpecValidateOptions;
+export declare function toArchiveOptions(project: string | undefined, options: OpenSpecArchiveCommandOptions): OpenSpecArchiveOptions;
+/**
+ * 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.
+ */
+export declare function nextActionsForArchiveError(code: OpenSpecArchiveError['code']): string[];
+/** The `openspec.archive` failure envelope for the gate's own error class. */
+export declare function printArchiveError(io: ProgramIO, error: OpenSpecArchiveError, json: boolean | undefined): void;

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

@@ -0,0 +1,135 @@
+// src/cli/commands/openspec-command-shared.ts
+//
+// The option shapes, flag translation and envelope printers shared by every
+// `peaks openspec <verb>` subcommand module. Split out of
+// `openspec-commands.ts` so each verb can live in its own file without
+// repeating the `fail(...)` boilerplate eight times.
+import { readFile } from 'node:fs/promises';
+import { getErrorMessage, printResult } from '../cli-helpers.js';
+import { normalizePath } from '../../shared/path-utils.js';
+import { fail } from 'peaks-loop-shared/result';
+/** The next action every path/layout failure carries. */
+export const OPENSPEC_PATH_HINT = [
+    'Check the project path and openspec/ layout before retrying'
+];
+export function resolveScanOptions(project) {
+    if (project === undefined) {
+        return {};
+    }
+    return { openspecRoot: `${normalizePath(project).replace(/\/$/, '')}/openspec` };
+}
+export 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;
+}
+/** Print a verb failure and mark the run failed. One call site per catch. */
+export function failOpenSpec(io, command, failure) {
+    printResult(io, fail(command, failure.code, getErrorMessage(failure.error), failure.data ?? {}, failure.nextActions), failure.json);
+    process.exitCode = 1;
+}
+/** The `<changeId>` resolution every change-scoped verb shares. */
+export function printChangeNotFound(io, command, changeId, json) {
+    printResult(io, fail(command, 'OPENSPEC_CHANGE_NOT_FOUND', `OpenSpec change ${changeId} was not found`, { changeId }, [`Verify openspec/changes/${changeId}/ exists`]), json);
+    process.exitCode = 1;
+}
+const ROOT_KEY = 'openspecRoot';
+/**
+ * Translate `--project` into the service option shape, carrying only the flags
+ * the caller actually set (a `false`/`undefined` flag must stay absent, not be
+ * written as `false`).
+ */
+export function toRenderOptions(project, options) {
+    const renderOptions = {};
+    const scan = resolveScanOptions(project);
+    if (scan.openspecRoot !== undefined) {
+        renderOptions[ROOT_KEY] = scan.openspecRoot;
+    }
+    if (options.apply === true) {
+        renderOptions.apply = true;
+    }
+    if (options.overwrite === true) {
+        renderOptions.overwrite = true;
+    }
+    return renderOptions;
+}
+export function toValidateOptions(project, options) {
+    const validateOptions = {};
+    const scan = resolveScanOptions(project);
+    if (scan.openspecRoot !== undefined) {
+        validateOptions[ROOT_KEY] = scan.openspecRoot;
+    }
+    if (options.preferExternal === true) {
+        validateOptions.preferExternal = true;
+    }
+    return validateOptions;
+}
+export function toArchiveOptions(project, options) {
+    const archiveOptions = {};
+    const scan = resolveScanOptions(project);
+    if (scan.openspecRoot !== undefined) {
+        archiveOptions[ROOT_KEY] = 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;
+    }
+    return archiveOptions;
+}
+/**
+ * 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.
+ */
+export 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'
+            ];
+    }
+}
+/** The `openspec.archive` failure envelope for the gate's own error class. */
+export function printArchiveError(io, error, json) {
+    printResult(io, fail('openspec.archive', error.code, getErrorMessage(error), error.detail, nextActionsForArchiveError(error.code)), json);
+    process.exitCode = 1;
+}

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

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