peaks-loop 4.0.0-beta → 4.0.0-beta.11

package/dist/cli/program.js

@@ -0,0 +1,416 @@
+import { readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { skillsDir, repoRoot } from '../shared/paths.js';
+import { CLI_VERSION } from '../shared/version.js';
+import { registerCoreAndArtifactCommands } from './commands/core-artifact-commands.js';
+import { registerWorkflowCommands } from './commands/workflow-commands.js';
+import { registerCapabilityWorkerConfigAndSCCommands } from './commands/capability-worker-config-sc-commands.js';
+import { registerCodegraphCommands } from './commands/codegraph-commands.js';
+import { registerOpenSpecCommands } from './commands/openspec-commands.js';
+import { registerPerfCommands } from './commands/perf-commands.js';
+import { registerPreferencesCommands } from './commands/preferences-commands.js';
+// Slice #014: peaks progress * CLI surface deleted (replaced by sub-agent
+// dispatch + heartbeat, slice #009 + #010). Sub-agent progress is
+// surfaced via `peaks sub-agent dispatch|heartbeat|share`.
+import { registerProjectCommands } from './commands/project-commands.js';
+import { registerPrdCommands } from './commands/prd-commands.js';
+import { registerRequestCommands } from './commands/request-commands.js';
+import { registerRetrospectiveCommands } from './commands/retrospective-commands.js';
+import { registerScanCommands } from './commands/scan-commands.js';
+import { registerSliceCommands } from './commands/slice-commands.js';
+import { registerSopCommands } from './commands/sop-commands.js';
+// v2.15.0 slice 002 AC-3: feedback-promotion CLI (`peaks feedback promote`
+// + `peaks feedback check-unpromoted`). See
+// `sops/feedback-promotion-sop.md`.
+import { registerFeedbackCommands } from './commands/feedback-commands.js';
+import { registerForkCommands } from './commands/fork-commands.js';
+import { registerImpactCommands } from './commands/impact-commands.js';
+import { registerSmokeCommands } from './commands/smoke-commands.js';
+import { registerReleaseCommands } from './commands/release-commands.js';
+import { registerPrdBlocksCommands } from './commands/prd-blocks-commands.js';
+import { registerUserTouchpointCommands } from './commands/user-touchpoint-commands.js';
+import { registerSliceReviewCommands } from './commands/slice-review-commands.js';
+import { registerQaBusinessReviewCommands } from './commands/qa-business-review-commands.js';
+import { registerSliceIntegrateCommands } from './commands/slice-integrate-commands.js';
+import { registerDocCommands } from './commands/doc-commands.js';
+import { registerLegacyCommands } from './commands/legacy-commands.js';
+import { registerRoleCommands } from './commands/role-commands.js';
+import { registerComplexityCommands } from './commands/complexity-commands.js';
+import { registerSubAgentCommands } from './commands/sub-agent-commands.js';
+import { registerSubAgentDispatchGuard } from './commands/sub-agent-dispatch-guard.js';
+import { registerGateCommands } from './commands/gate-commands.js';
+import { registerHookHandleCommand } from './commands/hook-handle.js';
+import { registerHooksCommands } from './commands/hooks-commands.js';
+import { registerStatusLineCommands } from './commands/statusline-commands.js';
+import { registerUnderstandCommands } from './commands/understand-commands.js';
+import { registerWorkspaceCommands } from './commands/workspace-commands.js';
+import { registerWorkflowPlanCommands } from './commands/workflow-plan-commands.js';
+import { registerAuditCommands } from './commands/audit-commands.js';
+import { registerFinalReviewCommands } from './commands/final-review-commands.js';
+import { registerClassifyCommands } from './commands/classify-classify-commands.js';
+import { registerContextCommands } from './commands/context-commands.js';
+import { registerContractCommands } from './commands/contract-commands.js';
+import { registerSkillConformanceCommands } from './commands/skill-conformance-commands.js';
+import { registerSkillLoopEngineeringReadinessCommands } from './commands/skill-loop-engineering-readiness-commands.js';
+import { registerLoopCommands } from './commands/loop-commands.js';
+import { registerWorkflowEvalCommands } from './commands/loop-eval-commands.js';
+import { registerEvolutionCommands } from './commands/evolution-commands.js';
+import { registerAssetCommands } from './commands/asset-commands.js';
+import { registerBeeCommands } from './commands/bee-commands.js';
+import { registerEccCommands } from './commands/ecc-commands.js';
+import { registerUpgradeCommands } from './commands/upgrade-commands.js';
+import { registerCodeReviewCommands } from './commands/code-review-commands.js';
+import { registerSecurityAuditCommands } from './commands/security-audit-commands.js';
+import { registerPerfAuditCommands } from './commands/perf-audit-commands.js';
+import { registerVerdictAggregateCommands } from './commands/verdict-aggregate-command.js';
+import { registerLogCommands } from './commands/log-commands.js';
+import { registerQaCommands } from './commands/qa-commands.js';
+import { registerTestCommands } from './commands/test-commands.js';
+import { registerPlaywrightCommands } from './commands/playwright-commands.js';
+import { registerCodeCommands } from './commands/code-commands.js';
+import { registerMutCommands } from './commands/mut-commands.js';
+import { registerFixtureCommands } from './commands/fixture-commands.js';
+import { registerReviewerCommands } from './commands/reviewer-commands.js';
+import { registerObservabilityCommands } from './commands/observability-commands.js';
+// Slice 2026-07-09 add-zcode-adapter (Slice C): `peaks ide model --current` —
+// read-only runtime model probe surfaced via the registered IDE adapter
+// chain. See src/services/ide/current-model-detector.ts.
+import { registerIdeCommands } from './commands/ide-commands.js';
+// Slice 2026-07-01-strategic-compact-cli: peaks compact
+// (suggest | recommend | survival | dry-run | force) — strategic-compact
+// CLI primitives. See src/services/compact/ and
+// src/cli/commands/compact-command.ts.
+import { registerCompactCommands } from './commands/compact-command.js';
+// Slice 2026-07-01-job-m3.1: `peaks job init|status|...` — Job orchestration CLI surface.
+import { registerJobCommands } from './commands/job-commands.js';
+// Slice 2026-07-04-cli-15a: `peaks skill sediment <verb>` + `peaks skill adapter <verb>`
+// — Task 15a 4-verb subset (add-segment / add-bee / list / rebuild-index).
+// 15b / 15c / 15d will extend sediment-commands.ts with the remaining 14 verbs.
+import { registerSedimentCommands } from './commands/sediment-commands.js';
+import { registerAdapterCommands } from './commands/adapter-commands.js';
+// Slice RD-2 S2-a: `peaks runtime *` (detect / list / compact) +
+// `peaks adapter *` (list / register). See src/services/runtime/ and
+// src/services/adapter/adapter-registry.ts. Coexists with the older
+// `peaks skill adapter` surface (slice 2026-07-04-cli-15a) which is
+// for skill materialization, not vendor-adapter registry.
+import { registerRuntimeCommands } from './commands/runtime-commands.js';
+import { registerAdapterS2ACommands } from './commands/adapter-commands-s2a.js';
+// Slice RD-2 S2-b: `peaks polyrepo *` (init / status / dispatch).
+import { registerPolyrepoCommands } from './commands/polyrepo-commands.js';
+import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
+import { applyRetention, cleanupEccCache } from '../services/log/retention.js';
+import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
+export { printResult } from './cli-helpers.js';
+/**
+ * Slice 2026-06-16-cli-logging (G1, G2, G3, G7). One structured
+ * `peaks-loop start` entry per CLI invocation, plus a 7-day
+ * retention sweep. Wired into the global program so EVERY
+ * peaks-loop command — even a bare `peaks` quickstart — writes
+ * a log line.
+ *
+ * The logger NEVER writes to stdout; it touches only the log
+ * file (always) and stderr (when `verbose` is true or
+ * `PEAKS_LOG_LEVEL=debug`). JSON envelopes stay parseable.
+ */
+function bootstrapLogger(verbose) {
+    try {
+        applyRetention({ retentionDays: 7 });
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* best-effort retention sweep; never block the CLI */
+    }
+    // Slice 3 (on-demand-ecc): 7-day TTL sweep over ecc-<sha>/ cache dirs.
+    try {
+        cleanupEccCache({ retentionDays: 7, nowMs: Date.now() });
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* best-effort ECC retention sweep; never block the CLI */
+    }
+    const dateOverride = process.env.PEAKS_LOG_DATE_OVERRIDE;
+    const entry = {
+        ts: new Date().toISOString(),
+        level: 'info',
+        command: 'main',
+        msg: 'peaks-loop start',
+        version: CLI_VERSION
+    };
+    try {
+        writeLogEntry(entry, dateOverride !== undefined ? { dateOverride } : {});
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* best-effort */
+    }
+    if (verbose || process.env.PEAKS_LOG_LEVEL === 'debug') {
+        maybeWriteStderr(entry, { verbose: true });
+    }
+}
+// Slice 2026-06-16-cli-logging (AC1 regression fix, repair cycle 1):
+// Process-scoped guard so the bootstrap log line is written AT MOST
+// once per process, regardless of whether it fires from the
+// `preAction` hook (subcommand path) or from the version action
+// (`-v` / `--version` / `-V` path). Reset between test invocations
+// via `__resetBootstrapForTests`.
+let bootstrapRan = false;
+export function __resetBootstrapForTests() {
+    bootstrapRan = false;
+}
+export function createProgram(io = { stdout: (text) => console.log(text), stderr: (text) => console.error(text) }) {
+    const program = new Command();
+    program
+        .name('peaks')
+        .description(`Peaks Loop ${CLI_VERSION} — loop engineering CLI: workflow primitive / loop guards / evaluators / slice orchestration
+
+Run peaks (no arguments) for a quickstart. You likely want one of:
+ peaks doctor check your environment
+ peaks skill list or manage skills
+ peaks slice boundary check (tsc + vitest +3-way + verify-pipeline)
+ peaks workflow plan workflow routing dry-run graphs
+ peaks sop author your own workflow gates
+ peaks hooks install the un-bypassable gate-enforcement hook
+ peaks gate enforce/bypass SOP gates on Bash commands`)
+        .configureOutput({
+        writeOut: (text) => io.stdout(text.trimEnd()),
+        writeErr: (text) => io.stderr(text.trimEnd())
+    })
+        // Slice 2026-06-16-cli-logging (AC1 regression fix, repair cycle 1):
+        // We DO NOT use Commander's built-in `.version()` here. Commander's
+        // built-in version handler short-circuits the program BEFORE the
+        // `preAction` hook fires, which means a bare `peaks --version`
+        // invocation skips the JSONL bootstrap. Per PRD AC1 the log file
+        // MUST be created on every CLI invocation, including `--version`.
+        //
+        // Instead we register `-V` and `-v, --version` as regular options
+        // and handle them in the program-level action: run the log
+        // bootstrap, print the version, and exit. The `preAction` hook
+        // below still fires for subcommands; we deduplicate via a
+        // `bootstrapRan` guard so the start line is written at most once
+        // per process.
+        .option('-v, --version', 'output the version number')
+        .option('-V', 'output the version number')
+        // Slice 2026-06-16-cli-logging (G3): global verbose flag. Mirrors
+        // the PEAKS_LOG_LEVEL=debug env var; with this set, the logger
+        // mirrors every entry to stderr IN ADDITION to the file.
+        // Long-only: `-v` is already bound to `--version` by the
+        // `.option()` call above, so we accept the env-var form
+        // (PEAKS_LOG_LEVEL=debug) as the short-form equivalent.
+        .option('--verbose', 'mirror log lines to stderr (also: PEAKS_LOG_LEVEL=debug)')
+        .hook('preAction', () => {
+        const opts = program.opts();
+        // Slice 2026-06-16-cli-logging (repair cycle 2): gate the bootstrap on
+        // the same `bootstrapRan` guard the version action uses, so a single
+        // process that invokes the program twice (vitest, programmatic) does
+        // not emit duplicate `peaks-loop start` JSONL entries.
+        if (!bootstrapRan) {
+            bootstrapLogger(opts.verbose === true);
+            bootstrapRan = true;
+        }
+    })
+        .action(() => {
+        const opts = program.opts();
+        if (opts.V || opts.version) {
+            // AC1: write the peaks-loop start log line BEFORE printing the
+            // version, so even a bare `--version` invocation creates the log
+            // file. `bootstrapRan` dedupes when `preAction` already ran.
+            if (!bootstrapRan) {
+                bootstrapLogger(opts.verbose === true);
+                bootstrapRan = true;
+            }
+            io.stdout(CLI_VERSION);
+            return;
+        }
+        // Count bundled skills by reading the skills dir directly (synchronous so
+        // the quickstart renders instantly — no import/async overhead on startup).
+        let skillCount = 0;
+        const skillsPath = skillsDir;
+        try {
+            if (existsSync(skillsPath)) {
+                skillCount = readdirSync(skillsPath, { withFileTypes: true })
+                    .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+                    .filter((entry) => existsSync(join(skillsPath, entry.name, 'SKILL.md')))
+                    .length;
+            }
+        }
+        catch { /* disk read is best-effort; zero skills is still truthful */ } // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        io.stdout(`Peaks Loop ${CLI_VERSION} · ${skillCount} skills ready
+
+ Peaks is a loop-engineering CLI + skill family for Claude Code.
+ It turns "don't skip steps" into hard enforcement — gates that block
+ advancement in-conversation, un-bypassably.
+
+ Before diving into a project, two things worth doing now:
+
+ peaks doctor check your environment in one glance
+ peaks-sop <<< ask this skill to author your first SOP
+
+ Or jump straight in:
+ peaks sop init --id my-flow --apply && peaks hooks install
+`);
+    })
+        .exitOverride();
+    registerCoreAndArtifactCommands(program, io);
+    registerWorkflowCommands(program, io);
+    registerCapabilityWorkerConfigAndSCCommands(program, io);
+    registerCodegraphCommands(program, io);
+    registerOpenSpecCommands(program, io);
+    registerPerfCommands(program, io);
+    registerPreferencesCommands(program);
+    registerProjectCommands(program, io);
+    registerPrdCommands(program, io);
+    registerRequestCommands(program, io);
+    registerRetrospectiveCommands(program, io);
+    registerScanCommands(program, io);
+    registerSliceCommands(program, io);
+    registerSopCommands(program, io);
+    // v2.15.0 slice 002 AC-3: feedback promotion CLI.
+    registerFeedbackCommands(program, io);
+    // v2.15.0 follow-up G11: fork sync CLI (status / upstream-check / sync-plan / sync / sync-verify).
+    registerForkCommands(program, io);
+    // v2.15.0 follow-up G13: impact scan CLI (scan / must-check).
+    registerImpactCommands(program, io);
+    // v2.15.0 follow-up G14: smoke regression CLI (define / run / run-and-repair / add-path).
+    registerSmokeCommands(program, io);
+    // v2.15.0 follow-up G15: release / hotfix CLI (plan / canary / promote / watch / done / rollback / hotfix).
+    registerReleaseCommands(program, io);
+    // v2.15.0 follow-up G3: prd 4 必填块 CLI (check-blocks).
+    registerPrdBlocksCommands(program, io);
+    // v2.15.0 follow-up G4: user touchpoint CLI (gate-classify / user-touchpoints / commit-boundary-actions).
+    registerUserTouchpointCommands(program, io);
+    // v2.15.0 follow-up G1: slice business review CLI (review / score / accept / reject).
+    registerSliceReviewCommands(program, io);
+    // v2.15.0 follow-up G5: QA business review CLI (business-review / score / accept / reject).
+    registerQaBusinessReviewCommands(program, io);
+    // v2.15.0 follow-up G6: slice cross-integration verifier (slice-integrate).
+    registerSliceIntegrateCommands(program, io);
+    // v2.15.0 follow-up G7: doc auto-generation (generate-skill / changelog-suggest).
+    registerDocCommands(program, io);
+    // v2.15.0 follow-up G8: legacy code smell detector (legacy-detect).
+    registerLegacyCommands(program, io);
+    // v2.15.0 follow-up G9: lightweight role registry (role list/add/grant/check).
+    registerRoleCommands(program, io);
+    // v2.15.0 follow-up G10: complexity estimator (complexity-estimate).
+    registerComplexityCommands(program, io);
+    registerSubAgentCommands(program, io);
+    registerContractCommands(program, io);
+    // Slice #010 G9.5: register the hook-only internal atom. Hidden from
+    // `peaks --help` (no description text); used by `peaks hooks install`
+    // to wire the PreToolUse hook chain.
+    registerSubAgentDispatchGuard(program);
+    registerGateCommands(program, io);
+    registerHookHandleCommand(program, io);
+    registerHooksCommands(program, io);
+    registerStatusLineCommands(program, io);
+    registerUnderstandCommands(program, io);
+    registerWorkspaceCommands(program, io);
+    registerWorkflowPlanCommands(program, io);
+    // Slice L2.1: peaks audit * — red-line audit framework.
+    registerAuditCommands(program, io);
+    // Slice 2026-06-25-slice-topology-multipass (Fix M2): peaks prepare-final-review CLI wrapper.
+    registerFinalReviewCommands(program, io);
+    // Slice #2: peaks classify * — L1a task classification + L1b per-level gate sets.
+    registerClassifyCommands(program, io);
+    // Slice #3: peaks context * — L1c context 4-layer loader.
+    registerContextCommands(program, io);
+    // Slice #12: peaks skills:audit-conformance — skill family alignment pass.
+    registerSkillConformanceCommands(program, io);
+    // M6 (2026-07-07 spec §7.5 / §8.4): peaks skill lint --category
+    // loop-engineering-readiness — readiness gate for any new peaks-*
+    // skill that participates in Loop Engineering.
+    registerSkillLoopEngineeringReadinessCommands(program, io);
+    // Slice #13: peaks swarm * — additional subcommands (pipeline /
+    // dispatch / verify / loop) are added inline in workflow-commands.ts
+    // alongside the existing swarm.plan. This avoids the duplicate top-level
+    // command conflict (peaks-loop-when-adding-a-new-subcommand-check-for-existing-top-level-first).
+    // Slice #14: peaks loop * + peaks goal compose — L4 Agent Loop sub-features.
+    registerLoopCommands(program, io);
+    // Slice v3.0.0 loop-eng-native-code-a-b: peaks workflow run|plan|lint
+    // + peaks loop eval. Wraps the existing workflow + loop groups so the
+    // add-a-new-subcommand-check-for-existing-top-level-first rule is honoured.
+    registerWorkflowEvalCommands(program, io);
+    // M4 (2026-07-07 spec): `peaks evolution propose|evaluate|revert|status|mark-keep`
+    // — Darwin-style ratchet CLI surface.
+    registerEvolutionCommands(program, io);
+    // M5 (2026-07-07 spec): `peaks asset crystallize|dispose|status` —
+    // umbrella cross-asset crystallization surface.
+    registerAssetCommands(program, io);
+    // M7 (2026-07-07 spec §7A.2 / §10 RL-9): `peaks bee export|import`
+    // — cross-user share surface for bee_release rows.
+    registerBeeCommands(program, io);
+    // Slice 3 (on-demand-ecc): `peaks ecc install|status|ls|show` replaces the
+    // deleted `peaks agent run|list` subprocess surface.
+    registerEccCommands(program, io);
+    // Slice: 1.x → 2.0 umbrella (per "one-key completion" + "minimal-user-operation" tenets).
+    registerUpgradeCommands(program, io);
+    // Slice: ocr soft-optional integration (peaks-rd Gate B3 augmentation).
+    registerCodeReviewCommands(program, io);
+    // Slice v2.12.0 Group A Tier 2: `peaks security-audit` (independent security audit skill driver).
+    registerSecurityAuditCommands(program, io);
+    // Slice v2.12.0 Group A Tier 3: `peaks perf-audit` (independent perf audit skill driver).
+    registerPerfAuditCommands(program, io);
+    // Slice v2.13.2 AC-2: `peaks verdict aggregate` (cross-source verdict aggregator CLI surface).
+    registerVerdictAggregateCommands(program, io);
+    // Slice 2026-06-16-cli-logging (G4): `peaks log tail` / `peaks log ls`.
+    registerLogCommands(program, io);
+    // Slice 2026-06-16-playwright-restart-loop (G5 + AC4): `peaks qa run`.
+    registerQaCommands(program, io);
+    // Slice 2026-06-17-2.5.0-sub-fix-B: `peaks test` (user-invoked, smart
+    // fingerprint-cache wrapper around jest/vitest/mocha).
+    registerTestCommands(program, io);
+    // Slice 2026-06-17-2.5.0-sub-fix-C: `peaks playwright start|ls|stop`
+    // (multi-terminal Playwright MCP lifecycle).
+    registerPlaywrightCommands(program, io);
+    // Slice 2 (peaks-code fast mode): `peaks code plan [--fast] <change-id>`
+    // v2.11.0 Group F (D5 + D7): also registers `peaks code should-pause` and
+    // `peaks code post-compact-detect` for runtime-friction probes.
+    registerCodeCommands(program, io);
+    // Plan 2 / Task 6: `peaks mut run|mutants|asserts|report` — mutation
+    // testing + assertion validity scan (spec §4.2 / §7). The
+    // production Stryker invoker is wired here; tests use the
+    // `createMutCommands({ invokeStryker })` factory directly with a
+    // mock to keep @stryker-mutator/core out of the unit-test path.
+    registerMutCommands(program, io);
+    // Slice v2.14.0 G1 AC-1.4: `peaks fixture capture` — fixture-replay
+    // anti-fake-green test suite producer. Sanitizes + checksums the
+    // captured envelope and writes a co-located fixture.meta.json.
+    registerFixtureCommands(program, io);
+    // Slice v2.14.0 G4 AC-4.1: `peaks reviewer run|status` — third-party
+    // reviewer CLI. The reviewer modelFamily MUST differ from the
+    // karpathy-reviewer modelFamily (AC-4.4); see
+    // src/services/reviewer/model-family.ts. The THIRD_PARTY_REVIEW prereq
+    // is wired into src/services/artifacts/artifact-prerequisites.ts.
+    registerReviewerCommands(program, io);
+    // Slice B of v2.11.1: `peaks observability status|slices|fanout|repair-cycles`
+    // (read-only queries over the JSONL metrics emitted from the
+    // peaks request transition hook in Slice A).
+    // Slice 2026-07-09 add-zcode-adapter (C.6): `peaks ide model --current`
+    // (read-only runtime model probe via the registered IDE adapter chain).
+    registerIdeCommands(program, io);
+    registerObservabilityCommands(program, io);
+    // Slice 2026-07-01-strategic-compact-cli: `peaks compact
+    // suggest|recommend|survival|dry-run|force` — strategic-compact CLI
+    // primitives. See src/cli/commands/compact-command.ts.
+    registerCompactCommands(program, io);
+    // Slice 2026-07-01-job-m3.1: `peaks job init|status|...` — Job
+    // orchestration CLI surface. M3.1 wires init + status + 2 stubs;
+    // the remaining 5 subcommands land in M3.2.
+    registerJobCommands(program, io);
+    // Slice 2026-07-04-cli-15a: `peaks skill sediment <verb>` — Task 15a
+    // 4-verb subset. Dispatches to runSediment; remaining verbs land in 15b/15c/15d.
+    registerSedimentCommands(program, io);
+    // Slice 2026-07-04-cli-15a: `peaks skill adapter <verb>` — adapter list / set-active.
+    registerAdapterCommands(program, io);
+    // Slice RD-2 S2-a: `peaks runtime *` (detect / list / compact) +
+    // `peaks adapter *` (list / register). Vendor verbs live ONLY in
+    // src/services/runtime/vendors/<vendor>.ts (AC-1 enforcement).
+    registerRuntimeCommands(program, io);
+    registerAdapterS2ACommands(program, io);
+    // Slice RD-2 S2-b: `peaks polyrepo *` (init / status / dispatch).
+    registerPolyrepoCommands(program, io);
+    // Slice 2026-07-05-peaks-code-to-peaks-code (Task 1): `peaks skill:visibility --list --json`
+    // — read .claude-plugin/marketplace.json and report each skill's
+    // visibility (public vs internal). Used to surface which skills are
+    // user-invocable vs LLM-only internal role skills. See
+    // src/cli/commands/skill-visibility.ts.
+    registerSkillVisibilityCommand(program, repoRoot);
+    return program;
+}

package/dist/services/adapter/adapter-registry.d.ts

@@ -0,0 +1,48 @@
+import type { VendorAdapter } from '../runtime/vendor-adapter.js';
+/** Serializable adapter record (the on-disk shape). */
+export interface AdapterRecord {
+    readonly id: string;
+    readonly displayName: string;
+    /** Binary name or absolute path to invoke for compact. */
+    readonly binary: string;
+    /** Extra args appended after the compact verb. */
+    readonly args?: string[];
+}
+export interface PersistedAdapterRegistry {
+    readonly version: 1;
+    readonly adapters: AdapterRecord[];
+}
+export interface RegisterOptions {
+    /** Overwrite an existing record with the same id. Defaults to false
+     *  to prevent silent overwrites of user customizations. */
+    readonly force?: boolean;
+}
+/** In-memory + on-disk adapter registry. The registry holds USER
+ *  adapters (those registered via `peaks adapter register`); built-in
+ *  adapters live in RuntimeService and are NOT registered here. */
+export declare class AdapterRegistry {
+    private readonly records;
+    /** Register a new adapter. When an adapter with the same id already
+     *  exists, returns the existing record unless `force: true`. */
+    register(record: AdapterRecord, opts?: RegisterOptions): {
+        record: AdapterRecord;
+        created: boolean;
+    };
+    /** Resolve a registered adapter by id, materializing it as a
+     *  runnable VendorAdapter. Returns undefined when not registered. */
+    resolve(id: string): VendorAdapter | undefined;
+    /** List registered adapter records (serializable form). */
+    list(): AdapterRecord[];
+    /** Remove a registered adapter. Returns true if it existed. */
+    unregister(id: string): boolean;
+    /** Persist the current registry to disk as JSON. Writes atomically
+     *  (write to `<file>.tmp` then rename) so a crash mid-write does
+     *  not corrupt the registry file. */
+    persist(file: string): void;
+    /** Load a registry from disk. Missing file = empty registry.
+     *  Corrupt file = throw (caller decides whether to bail or
+     *  fall back to empty). */
+    load(file: string): void;
+    /** Default location for the on-disk registry file. */
+    static defaultFile(projectRoot: string): string;
+}

package/dist/services/adapter/adapter-registry.js

@@ -0,0 +1,186 @@
+/**
+ * Adapter registry — slice S2-a of RD-2.
+ *
+ * Persists user-registered vendor adapters to
+ * `.peaks/runtime/adapters.json` and resolves them by id. The
+ * registry is layered on top of `RuntimeService` (built-in adapters
+ * live there); a caller asks "do you have an adapter for id=X?" by
+ * first asking the registry, then falling back to built-ins. The
+ * runtime service itself does NOT consult the registry (kept
+ * decoupled so the registry can be swapped for a different
+ * persistence backend without touching runtime-service).
+ *
+ * Design notes:
+ *  - Persistence uses atomic write (write to tmp + rename) so a
+ *    crash mid-write does not corrupt the registry file.
+ *  - `register()` defaults to fail-if-exists to prevent silent
+ *    overwrites of user customizations; pass `force: true` to
+ *    overwrite (matches the CLI surface from PRD §4.4).
+ *  - VendorAdapter implementations are NOT directly serializable
+ *    (they hold closures over `home`, child_process handles, etc.).
+ *    Instead the registry persists a minimal JSON shape:
+ *    `{id, displayName, binary, args}` and reconstructs a
+ *    ProcessVendorAdapter wrapper on load. This keeps the JSON
+ *    file human-readable + diff-friendly.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawn } from 'node:child_process';
+/** A registry-built adapter: wraps a persisted record + invokes the
+ *  recorded binary with the recorded args. Used so `peaks runtime
+ *  compact --via <id>` works against user-registered adapters without
+ *  peaks-loop needing to ship a vendor-specific implementation. */
+class ProcessVendorAdapter {
+    id;
+    displayName;
+    binary;
+    extraArgs;
+    constructor(record) {
+        this.id = record.id;
+        this.displayName = record.displayName;
+        this.binary = record.binary;
+        this.extraArgs = record.args ?? [];
+    }
+    async detect() {
+        // Heuristic: process-spawned adapters are always "detectable" once
+        // registered; their actual availability is checked at compact()
+        // time. This avoids probing every registered binary on every
+        // detect() call.
+        return true;
+    }
+    async compact(args = {}) {
+        const argv = [...this.extraArgs];
+        if (args.force === true)
+            argv.push('--force');
+        return new Promise((resolveRun) => {
+            const proc = spawn(this.binary, argv, { stdio: ['ignore', 'pipe', 'pipe'] });
+            let stdout = '';
+            let stderr = '';
+            proc.stdout.on('data', (chunk) => { stdout += chunk.toString('utf8'); });
+            proc.stderr.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+            proc.on('error', (err) => {
+                resolveRun({ exitCode: 127, stdout, stderr: stderr + (stderr.length > 0 ? '\n' : '') + err.message });
+            });
+            proc.on('close', (code) => {
+                resolveRun({ exitCode: code ?? 0, stdout, stderr });
+            });
+        });
+    }
+}
+/** Validate an adapter record. Used by register() to fail fast on
+ *  malformed CLI input. Returns an error message or undefined. */
+function validateRecord(record) {
+    if (record.id.length === 0)
+        return 'adapter id must be non-empty';
+    if (!/^[a-z0-9][a-z0-9._-]*$/.test(record.id)) {
+        return `adapter id "${record.id}" must match /^[a-z0-9][a-z0-9._-]*$/`;
+    }
+    if (record.displayName.length === 0)
+        return 'adapter displayName must be non-empty';
+    if (record.binary.length === 0)
+        return 'adapter binary must be non-empty';
+    if (record.binary.includes('/') || record.binary.includes('\\')) {
+        return `adapter binary "${record.binary}" must be a name, not a path`;
+    }
+    return undefined;
+}
+/** In-memory + on-disk adapter registry. The registry holds USER
+ *  adapters (those registered via `peaks adapter register`); built-in
+ *  adapters live in RuntimeService and are NOT registered here. */
+export class AdapterRegistry {
+    records = new Map();
+    /** Register a new adapter. When an adapter with the same id already
+     *  exists, returns the existing record unless `force: true`. */
+    register(record, opts = {}) {
+        const validationError = validateRecord(record);
+        if (validationError !== undefined) {
+            throw new Error(`invalid adapter record: ${validationError}`);
+        }
+        const existed = this.records.has(record.id);
+        if (existed && opts.force !== true) {
+            return { record: this.records.get(record.id), created: false };
+        }
+        this.records.set(record.id, record);
+        return { record, created: !existed };
+    }
+    /** Resolve a registered adapter by id, materializing it as a
+     *  runnable VendorAdapter. Returns undefined when not registered. */
+    resolve(id) {
+        const rec = this.records.get(id);
+        if (rec === undefined)
+            return undefined;
+        return new ProcessVendorAdapter(rec);
+    }
+    /** List registered adapter records (serializable form). */
+    list() {
+        return Array.from(this.records.values());
+    }
+    /** Remove a registered adapter. Returns true if it existed. */
+    unregister(id) {
+        return this.records.delete(id);
+    }
+    /** Persist the current registry to disk as JSON. Writes atomically
+     *  (write to `<file>.tmp` then rename) so a crash mid-write does
+     *  not corrupt the registry file. */
+    persist(file) {
+        const payload = {
+            version: 1,
+            adapters: this.list()
+        };
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.tmp`;
+        writeFileSync(tmp, JSON.stringify(payload, null, 2), 'utf8');
+        renameSync(tmp, file);
+    }
+    /** Load a registry from disk. Missing file = empty registry.
+     *  Corrupt file = throw (caller decides whether to bail or
+     *  fall back to empty). */
+    load(file) {
+        if (!existsSync(file))
+            return;
+        const raw = readFileSync(file, 'utf8');
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`adapter registry at ${file} is not valid JSON: ${err.message}`);
+        }
+        if (!isPersistedRegistry(parsed)) {
+            throw new Error(`adapter registry at ${file} has unexpected shape (expected version=1 + adapters[])`);
+        }
+        this.records.clear();
+        for (const rec of parsed.adapters) {
+            const validationError = validateRecord(rec);
+            if (validationError !== undefined) {
+                // Skip + continue — partial recovery is better than throwing on
+                // a single bad row. The CLI surfaces the count of skipped
+                // records via the load() return value below.
+                continue;
+            }
+            this.records.set(rec.id, rec);
+        }
+    }
+    /** Default location for the on-disk registry file. */
+    static defaultFile(projectRoot) {
+        return join(projectRoot, '.peaks', 'runtime', 'adapters.json');
+    }
+}
+function isPersistedRegistry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const v = value;
+    if (v.version !== 1)
+        return false;
+    if (!Array.isArray(v.adapters))
+        return false;
+    return v.adapters.every((a) => {
+        if (typeof a !== 'object' || a === null)
+            return false;
+        const r = a;
+        return typeof r.id === 'string'
+            && typeof r.displayName === 'string'
+            && typeof r.binary === 'string'
+            && (r.args === undefined || (Array.isArray(r.args) && r.args.every((x) => typeof x === 'string')));
+    });
+}