peaks-loop 4.0.0-beta.8 → 4.0.1

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

@@ -0,0 +1,175 @@
+import { join } from 'node:path';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
+import { loadRetrospectiveIndex } from '../../services/retrospective/retrospective-index.js';
+import { showRetrospective } from '../../services/retrospective/retrospective-show.js';
+import { searchRetrospective } from '../../services/retrospective/retrospective-search-service.js';
+import { pickFromList } from '../../services/fuzzy-matching/fzf-pick-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+const VALID_RETRO_TYPES = ['refactor', 'feature', 'bugfix', 'config', 'docs', 'chore'];
+const VALID_RETRO_OUTCOMES = ['shipped', 'blocked', 'in-flight', 'cancelled'];
+export function runRetrospectiveSearch(io, options) {
+    const projectRoot = options.project !== undefined
+        ? resolveCanonicalProjectRoot(options.project)
+        : (findProjectRoot(process.cwd()) ?? process.cwd());
+    const typeFilter = options.type !== undefined && VALID_RETRO_TYPES.includes(options.type)
+        ? options.type
+        : undefined;
+    const outcomeFilter = options.outcome !== undefined && VALID_RETRO_OUTCOMES.includes(options.outcome)
+        ? options.outcome
+        : undefined;
+    try {
+        const matches = searchRetrospective({
+            query: options.query,
+            projectRoot,
+            ...(typeFilter !== undefined ? { type: typeFilter } : {}),
+            ...(outcomeFilter !== undefined ? { outcome: outcomeFilter } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+        });
+        printResult(io, ok('retrospective.search', {
+            query: options.query,
+            total: matches.length,
+            matches,
+            warnings: [],
+        }, []), options.json);
+    }
+    catch (error) {
+        const message = getErrorMessage(error);
+        const code = error.code ?? 'RETROSPECTIVE_SEARCH_FAILED';
+        const suggestions = [];
+        if (code === 'INDEX_MISSING') {
+            suggestions.push('Build a retrospective index.json in .peaks/retrospective/');
+        }
+        if (code === 'EMPTY_QUERY') {
+            suggestions.push('Use `peaks retrospective index` to list all entries');
+        }
+        printResult(io, fail('retrospective.search', code, message, { projectRoot, query: options.query }, suggestions), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerRetrospectiveCommands(program, io) {
+    const retrospective = program.command('retrospective').description('Read the peaks retrospective index (R3: index.json, not the legacy <id>/ MD tree)');
+    addJsonOption(retrospective
+        .command('index')
+        .description('List all retrospective entries from .peaks/retrospective/index.json (R3: replaces the per-workflow MD dirs). Pass --pick to spawn fzf for interactive multi-select; the picked subset is written to .peaks/retrospective/picked.json.')
+        .option('--pick', 'spawn fzf for interactive multi-select (requires fzf >= 0.38); writes picked.json')
+        .option('--fzf-bin <path>', 'override fzf binary path (default: fzf on PATH)', 'fzf')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action(async (options) => {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        try {
+            const result = loadRetrospectiveIndex(projectRoot);
+            const warnings = result.warning === null ? [] : [result.warning];
+            let picked = null;
+            let pickedOutputPath = null;
+            let fzfVersion = null;
+            if (options.pick === true) {
+                const outputPath = join(projectRoot, '.peaks', 'retrospective', 'picked.json');
+                const byId = new Map(result.entries.map((e) => [e.id, e]));
+                const pickResult = await pickFromList({
+                    items: result.entries,
+                    formatLine: (e) => `${e.id} | ${e.type} | ${e.title} | ${e.outcome}`,
+                    parseLine: (line) => {
+                        const parts = line.split('|').map((p) => p.trim());
+                        if (parts.length < 1)
+                            return null;
+                        const id = parts[0];
+                        if (id === undefined || id.length === 0)
+                            return null;
+                        return byId.get(id) ?? null;
+                    },
+                    outputPath,
+                    meta: { totalCandidates: result.totalCount, source: result.source },
+                    ...(options.fzfBin !== undefined ? { fzfBin: options.fzfBin } : {}),
+                    projectRoot,
+                    multi: true,
+                    prompt: 'retrospective> '
+                });
+                picked = [...pickResult.picked];
+                pickedOutputPath = pickResult.outputPath;
+                fzfVersion = pickResult.fzfVersion;
+            }
+            printResult(io, ok('retrospective.index', {
+                indexPath: result.indexPath,
+                source: result.source,
+                total: result.totalCount,
+                entries: result.entries,
+                ...(options.pick === true ? { picked, pickedOutputPath, fzfVersion } : {})
+            }, warnings), options.json);
+        }
+        catch (error) {
+            const msg = getErrorMessage(error);
+            const isFzfError = /brew install fzf|apt-get install fzf|older than required/.test(msg);
+            if (isFzfError)
+                process.exitCode = 127;
+            else
+                process.exitCode = 1;
+            printResult(io, fail('retrospective.index', isFzfError ? 'FZF_UNAVAILABLE' : 'RETROSPECTIVE_INDEX_FAILED', msg, { projectRoot }, isFzfError
+                ? ['Install fzf (brew install fzf or apt-get install fzf) or run without --pick to list entries as JSON.']
+                : ['Check the project path and .peaks/retrospective/index.json']), options.json);
+        }
+    });
+    addJsonOption(retrospective
+        .command('show <id>')
+        .description('Show one retrospective entry by id. Default format is `compact` (LLM-primary); pass --pretty to get the disk / re-hydrated pretty form.')
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')
+        .option('--pretty', 'return the pretty form (re-hydrated from source artifacts); overrides the compact default')).action((id, options) => {
+        const projectRoot = options.project !== undefined
+            ? resolveCanonicalProjectRoot(options.project)
+            : (findProjectRoot(process.cwd()) ?? process.cwd());
+        try {
+            const format = options.pretty === true ? 'pretty' : 'compact';
+            const result = showRetrospective({ projectRoot, id, format });
+            if (!result.ok) {
+                const suggestions = [];
+                if (result.code === 'INDEX_MISSING')
+                    suggestions.push('Build a retrospective index.json in .peaks/retrospective/');
+                if (result.code === 'NOT_FOUND')
+                    suggestions.push('Run `peaks retrospective index --json` to see available ids');
+                if (result.code === 'ARTIFACT_MISSING' || result.missingArtifacts !== undefined) {
+                    suggestions.push('Restore the missing artifact at the path listed under missingArtifacts');
+                }
+                printResult(io, fail('retrospective.show', result.code, result.message, { id, projectRoot, ...(result.missingArtifacts !== undefined ? { missingArtifacts: result.missingArtifacts } : {}) }, suggestions), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('retrospective.show', {
+                id: result.entry.id,
+                sessionId: result.entry.sessionId,
+                sliceId: result.entry.sliceId ?? null,
+                type: result.entry.type,
+                title: result.entry.title,
+                summary: result.entry.summary,
+                outcome: result.entry.outcome,
+                keyDecisions: result.entry.keyDecisions,
+                lessonsLearned: result.entry.lessonsLearned,
+                artifactPaths: result.entry.artifactPaths,
+                updatedAt: result.entry.updatedAt,
+                body: result.body,
+                format: result.format
+            }, result.warnings), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('retrospective.show', 'RETROSPECTIVE_SHOW_FAILED', getErrorMessage(error), { id, projectRoot }, ['Check the project path and id']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(retrospective
+        .command('search <query>')
+        .description('Fuzzy-search the retrospective index (deterministic, local, zero-token). Default --limit 6.')
+        .option('--type <type>', `filter by retrospective type (one of: ${VALID_RETRO_TYPES.join(', ')})`)
+        .option('--outcome <outcome>', `filter by retrospective outcome (one of: ${VALID_RETRO_OUTCOMES.join(', ')})`)
+        .option('--limit <n>', 'maximum number of matches to return', (value) => Number(value))
+        .option('--project <path>', 'target project root (defaults to git root or cwd)')).action((query, options) => {
+        runRetrospectiveSearch(io, {
+            query,
+            ...(options.type !== undefined ? { type: options.type } : {}),
+            ...(options.outcome !== undefined ? { outcome: options.outcome } : {}),
+            ...(options.limit !== undefined ? { limit: options.limit } : {}),
+            ...(options.project !== undefined ? { project: options.project } : {}),
+            ...(options.json !== undefined ? { json: options.json } : {}),
+        });
+    });
+}

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

@@ -0,0 +1,14 @@
+/**
+ * `peaks reviewer run` / `peaks reviewer status` — CLI surface for the
+ * G4 third-party reviewer. v2.14.0.
+ *
+ *   peaks reviewer run   --rid <rid> [--json]
+ *   peaks reviewer status [--json]
+ *
+ * The CLI never silently prompts for API keys. When `~/.peaks/config.json`
+ * has no `reviewer` section, both commands emit a structured skip envelope
+ * and exit 0 (consistent with A4.3 fallbackOnError=skip).
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerReviewerCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,64 @@
+import { runReviewer, REVIEWER_ID } from '../../services/reviewer/reviewer-service.js';
+import { loadReviewerConfig } from '../../services/reviewer/reviewer-config.js';
+import { deriveModelFamily } from '../../services/reviewer/model-family.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+export function registerReviewerCommands(program, io) {
+    const reviewer = program
+        .command('reviewer')
+        .description('Third-party reviewer (v2.14.0 G4 anti-fake-green) — runs an out-of-band model on the slice and emits a schema-validated ReviewerEnvelope.');
+    addJsonOption(reviewer
+        .command('run')
+        .description('Run the configured third-party reviewer on a slice.')
+        .option('--rid <rid>', 'request id (slice) to review')).action(async (options) => {
+        const rid = options.rid ?? '';
+        if (rid.length === 0) {
+            printResult(io, fail('reviewer.run', 'MISSING_RID', '--rid is required', null), options.json === true);
+            process.exitCode = 2;
+            return;
+        }
+        const status = loadReviewerConfig();
+        if (!status.ok) {
+            const envelope = {
+                reviewerId: REVIEWER_ID,
+                modelId: 'skipped',
+                modelFamily: 'skipped',
+                passed: true,
+                violations: [],
+                gateAction: 'allow',
+                reason: 'skipped: no-reviewer-config (fallbackOnError=skip)'
+            };
+            printResult(io, ok('reviewer.run', { envelope, reason: status.reason }), options.json === true);
+            return;
+        }
+        const result = await runReviewer({ rid, context: `rid=${rid}` });
+        if (result.ok) {
+            printResult(io, ok('reviewer.run', { envelope: result.envelope }), options.json === true);
+            return;
+        }
+        printResult(io, fail('reviewer.run', 'NO_REVIEWER_CONFIG', result.reason, null), options.json === true);
+    });
+    addJsonOption(reviewer
+        .command('status')
+        .description('Show whether the reviewer is configured and which selection mode + provider families are active.')).action((options) => {
+        const status = loadReviewerConfig();
+        if (!status.ok) {
+            printResult(io, ok('reviewer.status', { configured: false, reason: status.reason }), options.json === true);
+            return;
+        }
+        const families = status.config.providers.map((p) => ({
+            name: p.name,
+            model: p.model,
+            modelFamily: deriveModelFamily(p.model).modelFamily
+        }));
+        printResult(io, ok('reviewer.status', {
+            configured: true,
+            selection: status.config.selection,
+            requireDistinctModelFamily: status.config.requireDistinctModelFamily,
+            fallbackOnError: status.config.fallbackOnError,
+            schemaPath: status.config.schemaPath,
+            rdProviderName: status.config.rdProviderName,
+            providers: families
+        }), options.json === true);
+    });
+}

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

@@ -0,0 +1,13 @@
+/**
+ * v2.15.0 follow-up — G9: peaks role * CLI.
+ *
+ *   - `peaks role list`                  — list all roles
+ *   - `peaks role add <name> --description <text>` — register a role
+ *   - `peaks role grant <role> <permission>`      — grant a permission
+ *   - `peaks role check <role> <permission>`      — check a permission
+ *
+ * Persistence: `.peaks/role-registry.json`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerRoleCommands(program: Command, io: ProgramIO): void;

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

@@ -0,0 +1,85 @@
+/**
+ * v2.15.0 follow-up — G9: peaks role * CLI.
+ *
+ *   - `peaks role list`                  — list all roles
+ *   - `peaks role add <name> --description <text>` — register a role
+ *   - `peaks role grant <role> <permission>`      — grant a permission
+ *   - `peaks role check <role> <permission>`      — check a permission
+ *
+ * Persistence: `.peaks/role-registry.json`.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { DEFAULT_SENIOR_FE_ROLE, grantPermission, readRoleRegistry, roleHasPermission, upsertRole, writeRoleRegistry } from '../../services/role/role-registry.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerRoleCommands(program, io) {
+    const role = program
+        .command('role')
+        .description('v2.15.0 follow-up G9: lightweight role registry (RBAC for multi-user peaks-loop teams).');
+    addJsonOption(role
+        .command('list')
+        .description('List all roles in the registry.')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const registry = readRoleRegistry(projectRoot);
+        printResult(io, ok('role.list', { projectRoot, roles: registry.roles, count: registry.roles.length }, [], [
+            registry.roles.length === 0 ? 'No roles registered. Run `peaks role add <name>` to start.' : ''
+        ].filter(Boolean)), opts.json ?? false);
+    });
+    addJsonOption(role
+        .command('add <name>')
+        .description('Register a new role. Use `--preset senior-fe` to seed the default ' +
+        '12-Gaps senior-FE permission set. Use `--description` for the ' +
+        'human-readable label.')
+        .option('--description <text>', 'role description')
+        .option('--preset <name>', 'apply a preset (currently only: senior-fe)')
+        .option('--permission <perm>', 'add an additional permission (repeatable)', (v, prev) => [...prev, v], [])
+        .option('--project <path>', 'project root (default: cwd)')).action((name, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        let newRole;
+        if (opts.preset === 'senior-fe') {
+            newRole = { ...DEFAULT_SENIOR_FE_ROLE, name, description: opts.description ?? DEFAULT_SENIOR_FE_ROLE.description, permissions: [...DEFAULT_SENIOR_FE_ROLE.permissions, ...opts.permission] };
+        }
+        else {
+            newRole = { name, description: opts.description ?? '', permissions: opts.permission };
+        }
+        const registry = readRoleRegistry(projectRoot);
+        const next = upsertRole(registry, newRole);
+        writeRoleRegistry(projectRoot, next);
+        printResult(io, ok('role.add', { projectRoot, role: newRole }, [], [
+            `Role "${name}" registered with ${newRole.permissions.length} permission(s).`
+        ]), opts.json ?? false);
+    });
+    addJsonOption(role
+        .command('grant <role> <permission>')
+        .description('Grant a permission to an existing role.')
+        .option('--project <path>', 'project root (default: cwd)')).action((roleName, permission, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const registry = readRoleRegistry(projectRoot);
+        if (!registry.roles.find((r) => r.name === roleName)) {
+            printResult(io, fail('role.grant', 'ROLE_NOT_FOUND', `role "${roleName}" not found. Run peaks role add first.`, { projectRoot }, []), opts.json ?? false);
+            process.exitCode = 1;
+            return;
+        }
+        const next = grantPermission(registry, roleName, permission);
+        writeRoleRegistry(projectRoot, next);
+        printResult(io, ok('role.grant', { projectRoot, role: roleName, permission, granted: true }, [], [
+            `Granted "${permission}" to role "${roleName}".`
+        ]), opts.json ?? false);
+    });
+    addJsonOption(role
+        .command('check <role> <permission>')
+        .description('Check if a role has a permission. Exits 0 when granted, 1 when not. ' +
+        'Useful for piping into peaks hooks PreToolUse (the 12 Gaps memory ' +
+        'B layer: peaks-hooks PreToolUse).')
+        .option('--project <path>', 'project root (default: cwd)')).action((roleName, permission, opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const registry = readRoleRegistry(projectRoot);
+        const granted = roleHasPermission(registry, roleName, permission);
+        printResult(io, ok('role.check', { projectRoot, role: roleName, permission, granted }, [], [
+            granted ? `Role "${roleName}" has permission "${permission}".` : `Role "${roleName}" does NOT have permission "${permission}".`
+        ]), opts.json ?? false);
+        if (!granted)
+            process.exitCode = 1;
+    });
+}

package/dist/cli/commands/runtime-commands-helpers.d.ts

@@ -0,0 +1,7 @@
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export declare function ensureRegistryDir(registryFile: string): void;
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export declare function registryFileFor(projectRoot: string): string;

package/dist/cli/commands/runtime-commands-helpers.js

@@ -0,0 +1,24 @@
+/**
+ * Internal helpers for the adapter-registry path used by
+ * `peaks adapter register|list`. Extracted from runtime-commands.ts
+ * after Task 1.7 (design §13.1) retired the `peaks runtime compact`
+ * dispatch — the registry plumbing is still used by the
+ * adapter-registration CLI, so it lives here as a stand-alone module
+ * rather than re-attaching to the retired dispatch surface.
+ */
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export function ensureRegistryDir(registryFile) {
+    mkdirSync(dirname(registryFile), { recursive: true });
+}
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export function registryFileFor(projectRoot) {
+    const f = AdapterRegistry.defaultFile(projectRoot);
+    ensureRegistryDir(f);
+    return f;
+}

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

@@ -0,0 +1,52 @@
+/**
+ * `peaks runtime *` — vendor-runtime detection + compact CLI surface.
+ *
+ * Slice S2-a of RD-2 (2026-07-08 session). Four subcommands:
+ *
+ *   detect    — print which vendor is the active AI runtime
+ *               (claude-code / codex / copilot / unknown).
+ *   list      — list the built-in vendor adapters registered by
+ *               RuntimeService (Claude Code / Codex / Copilot).
+ *   compact   — invoke a vendor's compact verb via the adapter. The
+ *               adapter (NOT this file) chooses the vendor verb;
+ *               see src/services/runtime/vendors/<vendor>.ts.
+ *
+ * Vendor verb strings (`claude --compact`, `codex --compact`,
+ * `copilot compact`) MUST live ONLY in `src/services/runtime/vendors/`
+ * — verified by AC-1: `rg -n "claude --compact|codex --compact|copilot
+ * compact" src/services/code/` returns 0 matches.
+ *
+ * `peaks runtime compact --via <id>` first consults the user
+ * adapter registry (`.peaks/runtime/adapters.json`) for the id, then
+ * falls back to the built-in adapter list. Missing vendor CLI
+ * surfaces as exitCode=127 + warning, NOT as a fatal error — vendor
+ * neutrality demands peaks-loop stay alive.
+ */
+import type { Command } from 'commander';
+import { join } from 'node:path';
+import { type ProgramIO } from '../cli-helpers.js';
+export interface RuntimeDetectOptions {
+    json?: boolean;
+}
+export interface RuntimeListOptions {
+    json?: boolean;
+}
+export interface RuntimeCompactOptions {
+    json?: boolean;
+    /** Vendor adapter id (built-in or registered). */
+    via?: string;
+    force?: boolean;
+    /** Override the project root (defaults to .peaks runtime lookup). */
+    project?: string;
+}
+export declare function registerRuntimeCommands(program: Command, io: ProgramIO): void;
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export declare function ensureRegistryDir(registryFile: string): void;
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export declare function registryFileFor(projectRoot: string): string;
+/** Re-export the path join helper for completeness; not strictly
+ *  needed by callers but keeps the module self-contained. */
+export { join };

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

@@ -0,0 +1,149 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, getErrorMessage, ok } from 'peaks-loop-shared/result';
+import { detectRuntime } from '../../services/runtime/runtime-detector.js';
+import { RuntimeService } from '../../services/runtime/runtime-service.js';
+import { AdapterRegistry } from '../../services/adapter/adapter-registry.js';
+function resolveProjectRoot(explicit) {
+    if (explicit !== undefined && explicit.length > 0)
+        return explicit;
+    return process.cwd();
+}
+export function registerRuntimeCommands(program, io) {
+    const runtime = program
+        .command('runtime')
+        .description('Vendor runtime detection + compact via adapter (--via <vendor-id>)');
+    // -----------------------------------------------------------------
+    // 1. peaks runtime detect [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(runtime
+        .command('detect')
+        .description('Print the active AI runtime vendor (claude-code / codex / copilot / unknown)')).action((options) => {
+        try {
+            const result = detectRuntime();
+            printResult(io, ok('runtime.detect', result, [], [
+                result.vendor === 'unknown'
+                    ? 'No vendor sentinel detected. Use `peaks adapter register --id <vendor> --binary <cmd>` to wire a custom one.'
+                    : `Run \`peaks runtime compact --via ${result.vendor}\` to invoke its compact verb.`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('runtime.detect', 'RUNTIME_DETECT_FAILED', getErrorMessage(error), {}, ['Retry with a clean env']), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 2. peaks runtime list [--json]
+    // -----------------------------------------------------------------
+    addJsonOption(runtime
+        .command('list')
+        .description('List the built-in vendor adapters registered by RuntimeService')).action((options) => {
+        try {
+            const svc = new RuntimeService();
+            const adapters = svc.listBuiltInAdapters().map((a) => ({ id: a.id, displayName: a.displayName }));
+            printResult(io, ok('runtime.list', { builtIn: adapters }, [], [
+                `Run \`peaks adapter register --id <vendor> --binary <cmd>\` to add a custom adapter (persists to .peaks/runtime/adapters.json).`
+            ]), options.json);
+        }
+        catch (error) {
+            printResult(io, fail('runtime.list', 'RUNTIME_LIST_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+    // -----------------------------------------------------------------
+    // 3. peaks runtime compact [--via <id>] [--force] [--json] [--project <root>]
+    // -----------------------------------------------------------------
+    addJsonOption(runtime
+        .command('compact')
+        .description('Compact the active vendor via the chosen adapter (--via <vendor-id>); vendor verbs live ONLY in adapter files')
+        .option('--via <id>', 'vendor adapter id (built-in or user-registered)')
+        .option('--force', 'ask the vendor to compact unconditionally')
+        .option('--project <path>', 'project root (defaults to cwd)')).action(async (options) => {
+        try {
+            const projectRoot = resolveProjectRoot(options.project);
+            const requested = options.via;
+            if (requested === undefined || requested.length === 0) {
+                // No explicit --via: try to detect first, then fall back.
+                const detected = detectRuntime();
+                if (detected.vendor === 'unknown') {
+                    printResult(io, fail('runtime.compact', 'NO_VENDOR_SPECIFIED', 'No --via <id> provided and no vendor detected.', { detected }, [
+                        'Pass --via <vendor-id>, or run `peaks runtime detect` to see what was detected.'
+                    ]), options.json);
+                    process.exitCode = 1;
+                    return;
+                }
+                await runCompact(projectRoot, detected.vendor, options.force === true, io, options.json);
+                return;
+            }
+            await runCompact(projectRoot, requested, options.force === true, io, options.json);
+        }
+        catch (error) {
+            printResult(io, fail('runtime.compact', 'RUNTIME_COMPACT_FAILED', getErrorMessage(error), {}, []), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+async function runCompact(projectRoot, viaId, force, io, asJson) {
+    // Layer 1: user-registered adapter (via AdapterRegistry).
+    const registryFile = AdapterRegistry.defaultFile(projectRoot);
+    const registry = new AdapterRegistry();
+    if (existsSync(registryFile)) {
+        try {
+            registry.load(registryFile);
+        }
+        catch { // TODO(g2): vendor-neutrality — corrupt adapter registry must NOT block peaks runtime
+            // Treat corrupt registry as empty — vendor-neutrality: a corrupt
+            // .peaks/runtime/adapters.json must NOT block peaks runtime.
+            // We still try the built-in path below.
+        }
+    }
+    const registered = registry.resolve(viaId);
+    if (registered !== undefined) {
+        const r = await registered.compact({ force });
+        const warnings = [];
+        if (r.exitCode === 127) {
+            warnings.push(`binary for adapter "${viaId}" not found on PATH; compact is a no-op`);
+        }
+        printResult(io, ok('runtime.compact', { via: viaId, source: 'registry', compact: r }, warnings, [
+            r.exitCode === 0
+                ? 'Compact completed.'
+                : `Compact exited with code ${r.exitCode}. Check stderr above.`
+        ]), asJson);
+        if (r.exitCode !== 0)
+            process.exitCode = 1;
+        return;
+    }
+    // Layer 2: built-in adapter (via RuntimeService).
+    const svc = new RuntimeService();
+    const r = await svc.compactVia(viaId, force);
+    const warnings = [];
+    if (r.warning !== undefined)
+        warnings.push(r.warning);
+    if (r.exitCode === 127) {
+        warnings.push(`built-in adapter "${viaId}" binary not found on PATH; compact is a no-op`);
+    }
+    printResult(io, ok('runtime.compact', { via: viaId, source: 'built-in', compact: { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr } }, warnings, [
+        r.exitCode === 0
+            ? 'Compact completed.'
+            : `Compact exited with code ${r.exitCode}. Check stderr above.`
+    ]), asJson);
+    if (r.exitCode !== 0)
+        process.exitCode = 1;
+}
+/** Internal helper exposed for tests + future programmatic callers:
+ *  resolve the registry file location, ensuring the parent dir
+ *  exists. Idempotent. */
+export function ensureRegistryDir(registryFile) {
+    mkdirSync(dirname(registryFile), { recursive: true });
+}
+/** Internal helper for tests: locate the registry file under the
+ *  given project root. Thin wrapper so tests can stub the resolution. */
+export function registryFileFor(projectRoot) {
+    const f = AdapterRegistry.defaultFile(projectRoot);
+    ensureRegistryDir(f);
+    return f;
+}
+/** Re-export the path join helper for completeness; not strictly
+ *  needed by callers but keeps the module self-contained. */
+export { join };

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

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

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

@@ -0,0 +1,47 @@
+import { createArtifactRetentionReport, createChangeImpact, getChangeTraceabilityStatus, getScHelpText, recordCommitBoundary, validateArtifactRetention } from '../../services/sc/sc-service.js';
+import { ok } from 'peaks-loop-shared/result';
+import { addJsonOption, multipleOption, printResult } from '../cli-helpers.js';
+export function registerSCCommands(program, io) {
+    const sc = program
+        .command('sc', { hidden: true })
+        .description('Source control and change traceability (peaks-sc integration)');
+    registerSCStatusCommands(sc, io);
+    registerSCArtifactCommands(sc, io);
+}
+function registerSCStatusCommands(sc, io) {
+    addJsonOption(sc.command('status').description('Show change traceability status')).action((options) => {
+        printResult(io, ok('sc.status', getChangeTraceabilityStatus()), options.json);
+    });
+    addJsonOption(sc.command('help').description('Show peaks-sc help text')).action((options) => {
+        const helpText = getScHelpText().join('\n');
+        if (options.json) {
+            printResult(io, ok('sc.help', { helpText }), options.json);
+        }
+        else {
+            io.stdout(helpText);
+        }
+    });
+}
+function registerSCArtifactCommands(sc, io) {
+    // Slice 2026-06-29-change-id-root-removal: `--change-id` is no
+    // longer accepted on `peaks sc impact`. The CLI surfaces a
+    // per-`(module, file)` impact report without a top-level
+    // change-id binding.
+    addJsonOption(sc.command('impact').description('Generate change impact artifact').option('--module <module>', 'affected module', multipleOption).option('--file <file>', 'affected file', multipleOption)).action((options) => {
+        const impactOptions = {
+            sessionId: '',
+            ...(options.module ? { affectedModules: options.module } : {}),
+            ...(options.file ? { affectedFiles: options.file } : {})
+        };
+        printResult(io, ok('sc.impact', createChangeImpact(impactOptions)), options.json);
+    });
+    addJsonOption(sc.command('retention').description('Create artifact retention report').requiredOption('--slice-id <id>', 'slice identifier').option('--prd <artifact>', 'PRD artifact path', multipleOption).option('--rd <artifact>', 'RD artifact path', multipleOption).option('--qa <artifact>', 'QA artifact path', multipleOption).option('--coverage <artifact>', 'coverage artifact path', multipleOption).option('--review <artifact>', 'review artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
+        printResult(io, ok('sc.retention', createArtifactRetentionReport({ sliceId: options.sliceId, ...(options.prd ? { prdArtifacts: options.prd } : {}), ...(options.rd ? { rdArtifacts: options.rd } : {}), ...(options.qa ? { qaArtifacts: options.qa } : {}), ...(options.coverage ? { coverageArtifacts: options.coverage } : {}), ...(options.review ? { reviewArtifacts: options.review } : {}), ...(options.code ? { codeChanges: options.code } : {}) })), options.json);
+    });
+    addJsonOption(sc.command('validate').description('Validate artifact retention for a slice').requiredOption('--slice-id <id>', 'slice identifier')).action((options) => {
+        printResult(io, ok('sc.validate', validateArtifactRetention(options.sliceId)), options.json);
+    });
+    addJsonOption(sc.command('boundary').description('Record retention boundary for a slice').requiredOption('--slice-id <id>', 'slice identifier').option('--artifact <path>', 'artifact path', multipleOption).option('--code <file>', 'code file path', multipleOption)).action((options) => {
+        printResult(io, ok('sc.boundary', recordCommitBoundary({ sliceId: options.sliceId, ...(options.artifact ? { artifacts: options.artifact } : {}), ...(options.code ? { codeFiles: options.code } : {}) })), options.json);
+    });
+}

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

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