peaks-loop 4.0.0-beta → 4.0.0-beta.10

package/dist/services/recommendations/capability-seed-mappings.js

@@ -0,0 +1,54 @@
+export const seedCapabilityLandingMappings = [
+    mapping({ capabilityId: 'ruflo-access-repo.workflow-reference', sourceId: 'ruflo-access-repo', sourceGroup: 'access-repo', landingKind: 'catalog', target: 'peaks autonomous planning reference', guidance: 'Use as workflow orchestration inspiration only; Peaks owns execution boundaries.' }),
+    mapping({ capabilityId: 'context7.docs-lookup', sourceId: 'context7', sourceGroup: 'access-repo', landingKind: 'cli', target: 'peaks recommend', commandPreview: 'peaks recommend --workflow code-refactor --json', guidance: 'Use for current library/API documentation lookup through approved MCP access.' }),
+    mapping({ capabilityId: 'codegraph.project-indexing', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Dry-run reference only: if local indexing is explicitly approved, peaks-rd may use peaks codegraph index --project <path> before semantic analysis; generated .codegraph artifacts stay local unless explicitly approved.' }),
+    mapping({ capabilityId: 'codegraph.semantic-query', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Dry-run reference only: peaks-rd may use peaks codegraph query --project <path> <search> for project relationship evidence during RD planning when execution is approved; Peaks RD gates remain authoritative.' }),
+    mapping({ capabilityId: 'codegraph.impact-analysis', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Dry-run reference only: peaks-rd may use peaks codegraph affected --project <path> <files...> --json to inspect likely impact before slice planning and red-line checks when execution is approved.' }),
+    mapping({ capabilityId: 'codegraph.impact-analysis', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use affected output as regression-surface evidence only; QA validation and test evidence remain authoritative.' }),
+    mapping({ capabilityId: 'codegraph.context-pack', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Dry-run reference only: peaks-rd may use peaks codegraph context --project <path> <task> to gather local evidence for RD analysis when execution is approved, without replacing standards dry-runs.' }),
+    mapping({ capabilityId: 'codegraph.context-pack', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-code', skillName: 'peaks-code', guidance: 'Code may attach local context packs or affected summaries before role handoff so RD, QA, and TXT share the same project evidence.' }),
+    mapping({ capabilityId: 'codegraph.context-pack', sourceId: 'codegraph', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-txt', skillName: 'peaks-txt', guidance: 'TXT may summarize recorded codegraph context packs into handoffs while treating them as supporting evidence only.' }),
+    mapping({ capabilityId: 'playwright-mcp.browser-validation', sourceId: 'playwright-mcp', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use for browser and E2E validation after user-approved app targets are available.' }),
+    mapping({ capabilityId: 'chrome-devtools-mcp.browser-debug', sourceId: 'chrome-devtools-mcp', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-ui', skillName: 'peaks-ui', guidance: 'Use for runtime UI, console, network, and performance inspection.' }),
+    mapping({ capabilityId: 'context-mode.context-management', sourceId: 'context-mode', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-txt', skillName: 'peaks-txt', guidance: 'Use only for explicit context management; durable memory requires user opt-in.' }),
+    mapping({ capabilityId: 'modelcontextprotocol-servers.collection', sourceId: 'modelcontextprotocol-servers', sourceGroup: 'access-repo', landingKind: 'catalog', target: 'future peaks mcp catalog', guidance: 'Treat as an unscanned MCP collection; do not auto-install unknown servers.' }),
+    mapping({ capabilityId: 'searchcode-mcp.code-search', sourceId: 'searchcode-mcp', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use for external code discovery only after confirming queries do not expose secrets or private code.' }),
+    mapping({ capabilityId: 'mysql-mcp.database-inspection', sourceId: 'mysql-mcp-server', sourceGroup: 'access-repo', landingKind: 'catalog', target: 'database capability boundary', guidance: 'Database access requires explicit credentials and confirmation before any write query.' }),
+    mapping({ capabilityId: 'figma-context-mcp.design-context', sourceId: 'figma-context-mcp', sourceGroup: 'access-repo', landingKind: 'skill', target: 'peaks-ui', skillName: 'peaks-ui', guidance: 'Use for design-to-code context only with user-authorized Figma access.' }),
+    mapping({ capabilityId: 'everything-claude-code.code-review-agent', sourceId: 'everything-claude-code', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use as code review capability after local diff and test evidence exist.' }),
+    mapping({ capabilityId: 'everything-claude-code.code-review-guidance', sourceId: 'everything-claude-code', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use as project-local code review standards guidance during QA preflight.' }),
+    mapping({ capabilityId: 'everything-claude-code.language-standards', sourceId: 'everything-claude-code', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use as curated language standards source during RD standards preflight.' }),
+    mapping({ capabilityId: 'everything-claude-code.security-review-agent', sourceId: 'everything-claude-code', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use as security review capability after local diff and test evidence exist.' }),
+    mapping({ capabilityId: 'everything-claude-code.security-review-guidance', sourceId: 'everything-claude-code', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use as project-local security review standards guidance during QA preflight.' }),
+    mapping({ capabilityId: 'andrej-karpathy-skills.guidance', sourceId: 'andrej-karpathy-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use as engineering guidance inspiration after project-local standards are scanned.' }),
+    mapping({ capabilityId: 'mattpocock-skills.product-prd-methods', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-prd', skillName: 'peaks-prd', guidance: 'Use to-prd, zoom-out, and grill-with-docs as inspected product-method references; Peaks PRD artifacts remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.engineering-diagnosis', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use diagnose, triage, improve-codebase-architecture, and prototype as inspected engineering references; Peaks RD gates remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.tdd-method', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use tdd as an inspected tests-first reference during RD implementation; Peaks unit-test and review gates remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.tdd-method', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use tdd as an inspected reference for checking whether tests protect changed behavior; Peaks QA evidence gates remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.qa-triage', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use triage and grill-with-docs as inspected QA references for blockers, release risk, and acceptance evidence; Peaks QA remains the acceptance authority.' }),
+    mapping({ capabilityId: 'mattpocock-skills.handoff-context', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-txt', skillName: 'peaks-txt', guidance: 'Use handoff, to-issues, and write-a-skill as inspected context references; Peaks TXT local capsule and memory-authorization rules remain authoritative.' }),
+    mapping({ capabilityId: 'mattpocock-skills.git-guardrails', sourceId: 'mattpocock-skills', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'git guardrails reference catalog', guidance: 'Catalog only; do not install hooks, mutate git configuration, or write Claude settings from this capability map.' }),
+    mapping({ capabilityId: 'impeccable.quality-guidance', sourceId: 'impeccable', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'quality reference catalog', guidance: 'Use as quality inspiration; Peaks review gates remain authoritative.' }),
+    mapping({ capabilityId: 'vercel-agent-skills.skill-pack', sourceId: 'vercel-agent-skills', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'external skill catalog', guidance: 'Catalog only until individual skills are inspected and approved.' }),
+    mapping({ capabilityId: 'agent-browser.browser-agent', sourceId: 'agent-browser', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-qa', skillName: 'peaks-qa', guidance: 'Use for browser validation; never submit forms or mutate authenticated state without explicit permission.' }),
+    mapping({ capabilityId: 'minimax-skills.worker-guidance', sourceId: 'minimax-skills', sourceGroup: 'mcp-server', landingKind: 'cli', target: 'peaks minimax-worker', commandPreview: 'peaks minimax-worker --json', guidance: 'Use Peaks worker command only after reviewing inputs; add --confirm manually when explicit external-provider approval exists.' }),
+    mapping({ capabilityId: 'claude-mem.memory-persistence', sourceId: 'claude-mem', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-txt', skillName: 'peaks-txt', guidance: 'Use only with explicit durable-memory consent and never store secrets.' }),
+    mapping({ capabilityId: 'darwin-skill.external-skill', sourceId: 'darwin-skill', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'external skill catalog', guidance: 'Catalog only until inspected for project fit and safety.' }),
+    mapping({ capabilityId: 'claude-code-best-practice.workflow-guidance', sourceId: 'claude-code-best-practice', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-rd', skillName: 'peaks-rd', guidance: 'Use as Claude Code workflow reference while preserving Peaks gates.' }),
+    mapping({ capabilityId: 'openspec.spec-workflow', sourceId: 'openspec', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-prd', skillName: 'peaks-prd', guidance: 'Use for spec-first product and engineering artifact structure.' }),
+    mapping({ capabilityId: 'gitnexus.repo-intelligence', sourceId: 'gitnexus', sourceGroup: 'mcp-server', landingKind: 'fallback', target: 'future peaks mcp gitnexus proxy', guidance: 'Do not install globally; future use should be proxied through Peaks.' }),
+    mapping({ capabilityId: 'taste-skill.design-critique', sourceId: 'taste-skill', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-ui', skillName: 'peaks-ui', guidance: 'Use as design critique inspiration, with Peaks UI constraints staying authoritative.' }),
+    mapping({ capabilityId: 'ui-ux-pro-max-skill.design-guidance', sourceId: 'ui-ux-pro-max-skill', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-ui', skillName: 'peaks-ui', guidance: 'Use as UI/UX guidance after product goals and accessibility constraints are clear.' }),
+    mapping({ capabilityId: 'ruflo-mcp-server.workflow-reference', sourceId: 'ruflo-mcp-server', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'peaks autonomous planning reference', guidance: 'Use as orchestration inspiration only; Peaks owns execution boundaries.' }),
+    mapping({ capabilityId: 'superpowers.workflow-methodology', sourceId: 'superpowers', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-prd', skillName: 'peaks-prd', guidance: 'Use as workflow methodology reference for artifact sequencing.' }),
+    mapping({ capabilityId: 'penpot.design-source', sourceId: 'penpot', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-ui', skillName: 'peaks-ui', guidance: 'Use as design-source context only with user-authorized project access.' }),
+    mapping({ capabilityId: 'gstack.product-stack-guidance', sourceId: 'gstack', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-prd', skillName: 'peaks-prd', guidance: 'Use as product-stack guidance, not as a substitute for user goals.' }),
+    mapping({ capabilityId: 'awesome-design-md.design-reference', sourceId: 'awesome-design-md', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-ui', skillName: 'peaks-ui', guidance: 'Use as visual/reference material while preserving product-specific design direction.' }),
+    mapping({ capabilityId: 'anthropic-skills.skill-pack', sourceId: 'anthropic-skills', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'external skill catalog', guidance: 'Catalog only until individual skills are inspected and approved.' }),
+    mapping({ capabilityId: 'vercel-skills.skill-pack', sourceId: 'vercel-skills', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'external skill catalog', guidance: 'Catalog only until individual skills are inspected and approved.' }),
+    mapping({ capabilityId: 'reactbits.ui-reference', sourceId: 'reactbits', sourceGroup: 'mcp-server', landingKind: 'skill', target: 'peaks-ui', skillName: 'peaks-ui', guidance: 'Use as UI and motion inspiration after checking license, accessibility, and performance.' }),
+    mapping({ capabilityId: 'azure-skills.cloud-skill-pack', sourceId: 'azure-skills', sourceGroup: 'mcp-server', landingKind: 'catalog', target: 'cloud capability catalog', guidance: 'Cloud actions can affect cost and infrastructure; require explicit confirmation and credentials.' })
+];
+function mapping(input) {
+    return { ...input, dryRunOnly: true };
+}

package/dist/services/recommendations/recommendation-service.js

@@ -0,0 +1,106 @@
+import { resolveCapabilityAvailability } from './capability-availability.js';
+import { seedCapabilityItems } from './seed-capability-catalog.js';
+function getWorkflowItems(workflow) {
+    return seedCapabilityItems.filter((item) => item.workflows.includes(workflow));
+}
+function localize(language, zh, en) {
+    return language.startsWith('zh') ? zh : en;
+}
+function getWorkflowSummary(workflow, language) {
+    if (workflow === 'code-refactor') {
+        return localize(language, '建议先为代码重构准备代码评审和文档查询能力；缺失能力会以 fallback 方式显式展示。', 'Prepare code review and documentation lookup capabilities for code refactor; missing capabilities are shown with explicit fallbacks.');
+    }
+    if (workflow === 'product-refactor') {
+        return localize(language, '建议先围绕产品理解成本、交互路径和验收标准生成推荐计划。', 'Prepare a recommendation plan around product comprehension cost, interaction flow, and acceptance criteria.');
+    }
+    return localize(language, '建议先准备前端设计、浏览器验证和文档查询能力。', 'Prepare frontend design, browser validation, and documentation lookup capabilities.');
+}
+function getPreferredCapabilityId(workflow) {
+    if (workflow === 'code-refactor') {
+        return 'everything-claude-code.code-review-agent';
+    }
+    return 'context7.docs-lookup';
+}
+function toFallbackActionId(capabilityId) {
+    return `use-fallback-${capabilityId.replaceAll('.', '-')}`;
+}
+function getNextActions(workflow, availability) {
+    const preferredCapabilityId = getPreferredCapabilityId(workflow);
+    const preferredAvailability = availability.find((item) => item.capabilityId === preferredCapabilityId);
+    const fallbackActions = availability
+        .filter((item) => item.status !== 'available')
+        .map((item) => ({
+        id: toFallbackActionId(item.capabilityId),
+        type: 'use-fallback',
+        capabilityId: item.capabilityId,
+        requiresApproval: true,
+        riskLevel: item.risk
+    }));
+    if (preferredAvailability?.status !== 'available') {
+        return fallbackActions;
+    }
+    const invokeAction = workflow === 'code-refactor'
+        ? {
+            id: 'run-code-review',
+            type: 'invoke-capability',
+            capabilityId: preferredCapabilityId,
+            requiresApproval: false,
+            riskLevel: preferredAvailability.risk
+        }
+        : {
+            id: 'lookup-docs',
+            type: 'invoke-capability',
+            capabilityId: preferredCapabilityId,
+            requiresApproval: false,
+            riskLevel: preferredAvailability.risk
+        };
+    return [...fallbackActions, invokeAction];
+}
+export function createRecommendationPlan(options) {
+    const language = options.language ?? 'en';
+    const workflowItems = getWorkflowItems(options.workflow);
+    const availabilityOptions = options.installedCapabilityIds
+        ? { installedCapabilityIds: options.installedCapabilityIds }
+        : {};
+    const availability = resolveCapabilityAvailability(workflowItems, availabilityOptions);
+    const missingCapabilities = availability.filter((item) => item.status !== 'available');
+    const requiredCapabilities = workflowItems.map((item) => item.capabilityId);
+    const recommendedOption = {
+        id: 'recommended-foundation-route',
+        label: 'foundation-route',
+        why: 'Use available capabilities and expose missing ones before execution.',
+        requiredCapabilities,
+        ...(missingCapabilities.length > 0 ? { fallbackPath: 'explicit-fallback' } : {})
+    };
+    return {
+        intent: options.workflow,
+        workflow: options.workflow,
+        profile: 'code-guided-auto',
+        audience: ['engineer'],
+        options: [recommendedOption],
+        requiredCapabilities,
+        availability,
+        fallbacks: missingCapabilities.map((item) => item.fallback),
+        decisionRequired: missingCapabilities.length > 0,
+        machine: {
+            nextActions: getNextActions(options.workflow, availability),
+            constraints: ['do-not-install-capabilities', 'do-not-mutate-remote-state'],
+            stopConditions: ['missing-required-capability-without-fallback']
+        },
+        presentation: {
+            language,
+            summary: getWorkflowSummary(options.workflow, language),
+            options: [
+                {
+                    id: 'recommended-foundation-route',
+                    label: localize(language, '使用推荐基础路线', 'Use recommended foundation route'),
+                    why: localize(language, '先检查能力是否可用，再决定执行或降级，避免模型发散。', 'Check capability availability before execution or fallback to avoid model drift.')
+                }
+            ],
+            warnings: missingCapabilities.map((item) => localize(language, `缺少能力：${item.capabilityId}，将使用 fallback。`, `Missing capability: ${item.capabilityId}; fallback will be used.`)),
+            explanations: [
+                localize(language, '机器层保持稳定英文契约，给人看的摘要跟随当前语言。', 'The machine layer keeps stable English contracts while human summaries follow the selected language.')
+            ]
+        }
+    };
+}

package/dist/services/refactor/refactor-service.d.ts

@@ -0,0 +1,9 @@
+export type RefactorMode = 'code' | 'rd';
+export type RefactorDryRun = {
+    mode: RefactorMode;
+    implementationAllowed: false;
+    hardGates: string[];
+    requiredArtifacts: string[];
+    nextActions: string[];
+};
+export declare function createRefactorDryRun(mode: RefactorMode): RefactorDryRun;

package/dist/services/runtime/runtime-detector.d.ts

@@ -0,0 +1,15 @@
+export type DetectedVendor = 'claude-code' | 'codex' | 'copilot' | 'unknown';
+export interface RuntimeDetectorOptions {
+    /** Override for env (used by tests). */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override for home directory (used by tests). */
+    readonly home?: string;
+}
+export interface DetectionResult {
+    readonly vendor: DetectedVendor;
+    /** Why this vendor was chosen — useful for diagnostics and tests. */
+    readonly reason: string;
+}
+/** Detect the active vendor. Order: claude-code → codex → copilot →
+ *  unknown. The first match wins. */
+export declare function detectRuntime(opts?: RuntimeDetectorOptions): DetectionResult;

package/dist/services/runtime/runtime-detector.js

@@ -0,0 +1,62 @@
+/**
+ * Runtime detector — slice S2-a of RD-2.
+ *
+ * Given the current process environment, decide which vendor (if any)
+ * is the active AI runtime. Detection order matters: Claude Code is
+ * checked first because it is the default runtime for peaks-loop
+ * (the project literally runs inside Claude Code). Codex + Copilot
+ * are checked second; if none match we report `unknown`.
+ *
+ * Detectors MUST be cheap (no process spawn, no network). They look
+ * at env vars + filesystem sentinels + home-dir shapes only. This
+ * keeps `peaks runtime detect` sub-100ms even on cold paths.
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/** Heuristic: Claude Code sets CLAUDE_CODE_ENTRYPOINT or has a
+ *  .claude/skills directory under HOME (peaks-loop installs there). */
+function detectClaudeCode(opts) {
+    const env = opts.env ?? process.env;
+    if (env.CLAUDE_CODE === '1' || env.CLAUDE_CODE === 'true')
+        return true;
+    if (env.CLAUDE_CODE_ENTRYPOINT !== undefined && env.CLAUDE_CODE_ENTRYPOINT.length > 0)
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.claude')))
+        return true;
+    return false;
+}
+/** Heuristic: Codex sets CODEX_HOME or has a .codex dir under HOME. */
+function detectCodex(opts) {
+    const env = opts.env ?? process.env;
+    if (env.CODEX_HOME !== undefined && env.CODEX_HOME.length > 0)
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.codex')))
+        return true;
+    return false;
+}
+/** Heuristic: Copilot sets GITHUB_COPILOT or has a .copilot dir. */
+function detectCopilot(opts) {
+    const env = opts.env ?? process.env;
+    if (env.GITHUB_COPILOT === '1' || env.GITHUB_COPILOT === 'true')
+        return true;
+    const home = opts.home ?? process.env.HOME ?? process.env.USERPROFILE ?? '';
+    if (home.length > 0 && existsSync(join(home, '.copilot')))
+        return true;
+    return false;
+}
+/** Detect the active vendor. Order: claude-code → codex → copilot →
+ *  unknown. The first match wins. */
+export function detectRuntime(opts = {}) {
+    if (detectClaudeCode(opts)) {
+        return { vendor: 'claude-code', reason: 'CLAUDE_CODE_ENTRYPOINT / CLAUDE_CODE / ~/.claude matched' };
+    }
+    if (detectCodex(opts)) {
+        return { vendor: 'codex', reason: 'CODEX_HOME / ~/.codex matched' };
+    }
+    if (detectCopilot(opts)) {
+        return { vendor: 'copilot', reason: 'GITHUB_COPILOT / ~/.copilot matched' };
+    }
+    return { vendor: 'unknown', reason: 'no vendor sentinel detected' };
+}

package/dist/services/runtime/runtime-service.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Runtime service — slice S2-a of RD-2.
+ *
+ * Orchestrator that wires the runtime detector + vendor adapter
+ * registry into a small surface that the CLI commands call. The
+ * service owns the canonical list of built-in adapters (claude-code /
+ * codex / copilot) and decides which adapter handles a given
+ * `--via <id>` request.
+ *
+ * Design notes (Karpathy #2 Simplicity First):
+ *
+ *  - The service is a thin orchestrator — it does NOT contain any
+ *    vendor verb strings (claude / codex / copilot). All vendor verbs
+ *    live in `src/services/runtime/vendors/<vendor>.ts`. Verified by
+ *    AC-1.
+ *  - When `compactVia(id)` is called with an unknown id, the service
+ *    returns a "no-op" result with exitCode=0 and a warning instead of
+ *    throwing — vendor-neutrality means peaks-loop MUST keep working
+ *    even when the requested vendor adapter isn't registered.
+ *  - The service is the SOLE owner of the built-in adapter list. Tests
+ *    and CLI commands should never instantiate adapters directly;
+ *    they should call `listBuiltInAdapters()` or `getAdapter(id)`.
+ */
+import type { VendorAdapter, VendorCompactResult } from './vendor-adapter.js';
+export interface RuntimeServiceOptions {
+    /** Override the built-in adapter list (used by tests + the
+     *  adapter-registry's `register()` flow). */
+    readonly builtIns?: VendorAdapter[];
+    /** Override the home dir used by adapter detect() helpers. */
+    readonly home?: string;
+}
+/** Pure orchestrator. The runtime service holds built-in adapters as
+ *  the baseline registry; the AdapterRegistry layer (`src/services/
+ *  adapter/adapter-registry.ts`) extends this baseline at runtime via
+ *  user-registered adapters persisted to `.peaks/runtime/adapters.json`.
+ *  The two layers are intentionally separate:
+ *    - runtime-service: built-in vendor adapters for the runtime-detect
+ *      compact flow (S2-a).
+ *    - adapter-registry: persisted user-registered adapters (S2-a).
+ *  runtime-service itself does NOT consult the adapter registry —
+ *  callers (`peaks runtime compact --via <id>`) layer them: first look
+ *  up the id in the persisted registry, fall back to the built-in list.
+ */
+export declare class RuntimeService {
+    private readonly builtIns;
+    constructor(opts?: RuntimeServiceOptions);
+    /** Return all built-in adapters. Order: claude-code, codex, copilot. */
+    listBuiltInAdapters(): VendorAdapter[];
+    /** Resolve a built-in adapter by id. Returns undefined when not
+     *  found — caller should fall back to adapter registry or unknown. */
+    getBuiltInAdapter(id: string): VendorAdapter | undefined;
+    /** Compact via a built-in adapter. When the id is unknown, returns
+     *  a no-op result with a warning rather than throwing — vendor
+     *  neutrality demands peaks-loop stay alive even when a vendor is
+     *  not wired up. */
+    compactVia(id: string, force: boolean | undefined): Promise<VendorCompactResult & {
+        warning?: string;
+    }>;
+}

package/dist/services/runtime/runtime-service.js

@@ -0,0 +1,51 @@
+import { ClaudeCodeAdapter } from './vendors/claude-code.js';
+import { CodexAdapter } from './vendors/codex.js';
+import { CopilotAdapter } from './vendors/copilot.js';
+const DEFAULT_BUILT_INS = [
+    new ClaudeCodeAdapter(),
+    new CodexAdapter(),
+    new CopilotAdapter()
+];
+/** Pure orchestrator. The runtime service holds built-in adapters as
+ *  the baseline registry; the AdapterRegistry layer (`src/services/
+ *  adapter/adapter-registry.ts`) extends this baseline at runtime via
+ *  user-registered adapters persisted to `.peaks/runtime/adapters.json`.
+ *  The two layers are intentionally separate:
+ *    - runtime-service: built-in vendor adapters for the runtime-detect
+ *      compact flow (S2-a).
+ *    - adapter-registry: persisted user-registered adapters (S2-a).
+ *  runtime-service itself does NOT consult the adapter registry —
+ *  callers (`peaks runtime compact --via <id>`) layer them: first look
+ *  up the id in the persisted registry, fall back to the built-in list.
+ */
+export class RuntimeService {
+    builtIns;
+    constructor(opts = {}) {
+        this.builtIns = opts.builtIns ?? [...DEFAULT_BUILT_INS];
+    }
+    /** Return all built-in adapters. Order: claude-code, codex, copilot. */
+    listBuiltInAdapters() {
+        return [...this.builtIns];
+    }
+    /** Resolve a built-in adapter by id. Returns undefined when not
+     *  found — caller should fall back to adapter registry or unknown. */
+    getBuiltInAdapter(id) {
+        return this.builtIns.find((a) => a.id === id);
+    }
+    /** Compact via a built-in adapter. When the id is unknown, returns
+     *  a no-op result with a warning rather than throwing — vendor
+     *  neutrality demands peaks-loop stay alive even when a vendor is
+     *  not wired up. */
+    async compactVia(id, force) {
+        const adapter = this.getBuiltInAdapter(id);
+        if (adapter === undefined) {
+            return {
+                exitCode: 0,
+                stdout: '',
+                stderr: '',
+                warning: `no built-in adapter registered for id="${id}" — falling back to no-op; use \`peaks adapter register --id ${id} --binary <cmd>\` to wire one`
+            };
+        }
+        return adapter.compact({ force: force === true });
+    }
+}

package/dist/services/runtime/vendor-adapter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Vendor adapter contract — slice S2-a of RD-2 (2026-07-08 session).
+ *
+ * Each `VendorAdapter` is a thin wrapper around ONE AI runtime (Claude
+ * Code / Codex / Copilot / custom) that knows how to:
+ *
+ *   1. Detect whether the current environment is that vendor
+ *      (env vars, sentinel binaries, environment shape).
+ *   2. Issue a compact command through that vendor without forcing
+ *      peaks-loop's core code to know vendor-specific verbs.
+ *
+ * The interface is intentionally MINIMAL (Karpathy #2 Simplicity First):
+ * two methods (`detect`, `compact`) plus an `id` + `displayName`.
+ * New verbs (status, refactor, etc.) are NOT in scope — they would
+ * bloat the surface and force every vendor to implement every verb
+ * whether the vendor supports it or not. When a future verb is needed
+ * it can either be added to the interface (with all vendors forced to
+ * implement) or — preferred — handled through a separate
+ * verb-specific adapter family.
+ *
+ * Vendor-specific verb strings (`claude --compact`, `codex --compact`,
+ * `copilot compact`) MUST live ONLY in adapter implementations under
+ * `src/services/runtime/vendors/<vendor>.ts`. The runtime service that
+ * orchestrates these adapters (runtime-service.ts) and the CLI commands
+ * (`peaks runtime compact --via <id>`) MUST NOT contain vendor verbs
+ * — verified by AC-1: `rg -n "claude --compact|codex --compact|copilot
+ * compact" src/services/code/` must return 0 matches.
+ *
+ * See `.peaks/_runtime/2026-07-08-session-17918f/prd/002-adapter-runtime-and-polyrepo.md`
+ * for the source PRD.
+ */
+export interface VendorCompactArgs {
+    /** When `true`, the vendor is asked to compact unconditionally even
+     *  if its auto-detector says it would not normally do so. */
+    readonly force?: boolean;
+}
+export interface VendorCompactResult {
+    readonly exitCode: number;
+    readonly stdout: string;
+    readonly stderr: string;
+}
+export interface VendorAdapter {
+    /** Stable identifier used by `peaks runtime compact --via <id>` and
+     *  by the adapter registry. Convention: lowercase, dash-separated,
+     *  e.g. `claude-code`, `codex`, `copilot`. */
+    readonly id: string;
+    /** Human-readable name shown in `peaks runtime list` output. */
+    readonly displayName: string;
+    /** Whether the CURRENT environment is this vendor. Detectors MUST
+     *  be pure functions of env + filesystem; they MUST NOT spawn
+     *  processes or call vendor CLIs (a detect that itself runs the
+     *  vendor would defeat the purpose of asking whether the vendor is
+     *  present). */
+    detect(): Promise<boolean>;
+    /** Issue a compact command for this vendor. The adapter chooses
+     *  which binary + args + env to invoke; callers MUST NOT pass
+     *  vendor verbs through this method. */
+    compact(args?: VendorCompactArgs): Promise<VendorCompactResult>;
+}

package/dist/services/runtime/vendors/claude-code.d.ts

@@ -0,0 +1,7 @@
+import type { VendorAdapter, VendorCompactArgs, VendorCompactResult } from '../vendor-adapter.js';
+export declare class ClaudeCodeAdapter implements VendorAdapter {
+    readonly id = "claude-code";
+    readonly displayName = "Claude Code";
+    detect(): Promise<boolean>;
+    compact(args?: VendorCompactArgs): Promise<VendorCompactResult>;
+}

package/dist/services/runtime/vendors/claude-code.js

@@ -0,0 +1,39 @@
+/**
+ * Claude Code vendor adapter — slice S2-a.
+ *
+ * Stubs the compact verb to `claude --compact` (the canonical vendor
+ * verb for Claude Code). The actual binary is invoked via spawn so
+ * the adapter does NOT block peaks-loop. When the `claude` binary is
+ * not on PATH the adapter returns exitCode=127 + stderr explaining
+ * the missing binary, which the runtime service surfaces as a warning
+ * + no-op rather than a fatal error (vendor-neutrality: peaks-loop
+ * should still work even when the host vendor CLI is absent).
+ */
+import { spawn } from 'node:child_process';
+export class ClaudeCodeAdapter {
+    id = 'claude-code';
+    displayName = 'Claude Code';
+    async detect() {
+        return process.env.CLAUDE_CODE === '1'
+            || process.env.CLAUDE_CODE === 'true'
+            || (process.env.CLAUDE_CODE_ENTRYPOINT?.length ?? 0) > 0;
+    }
+    async compact(args = {}) {
+        const argv = ['--compact'];
+        if (args.force === true)
+            argv.push('--force');
+        return new Promise((resolveRun) => {
+            const proc = spawn('claude', 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 });
+            });
+        });
+    }
+}

package/dist/services/runtime/vendors/codex.d.ts

@@ -0,0 +1,7 @@
+import type { VendorAdapter, VendorCompactArgs, VendorCompactResult } from '../vendor-adapter.js';
+export declare class CodexAdapter implements VendorAdapter {
+    readonly id = "codex";
+    readonly displayName = "Codex";
+    detect(): Promise<boolean>;
+    compact(args?: VendorCompactArgs): Promise<VendorCompactResult>;
+}

package/dist/services/runtime/vendors/codex.js

@@ -0,0 +1,43 @@
+/**
+ * Codex vendor adapter — slice S2-a.
+ *
+ * Stub adapter (PRD out-of-scope: full implementation lands in a
+ * future slice). The detect() heuristic is intentionally permissive:
+ * if CODEX_HOME or ~/.codex is present we report detected=true so
+ * `peaks runtime detect` exercises the codex branch. compact() uses
+ * the canonical `codex --compact` invocation; missing-binary is
+ * reported as exitCode=127, not a thrown error (the runtime service
+ * surfaces that as a warning + no-op so a missing vendor CLI does
+ * not break peaks-loop).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export class CodexAdapter {
+    id = 'codex';
+    displayName = 'Codex';
+    async detect() {
+        if (process.env.CODEX_HOME !== undefined && process.env.CODEX_HOME.length > 0)
+            return true;
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+        return home.length > 0 && existsSync(join(home, '.codex'));
+    }
+    async compact(args = {}) {
+        const argv = ['--compact'];
+        if (args.force === true)
+            argv.push('--force');
+        return new Promise((resolveRun) => {
+            const proc = spawn('codex', 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 });
+            });
+        });
+    }
+}

package/dist/services/runtime/vendors/copilot.d.ts

@@ -0,0 +1,7 @@
+import type { VendorAdapter, VendorCompactArgs, VendorCompactResult } from '../vendor-adapter.js';
+export declare class CopilotAdapter implements VendorAdapter {
+    readonly id = "copilot";
+    readonly displayName = "GitHub Copilot";
+    detect(): Promise<boolean>;
+    compact(args?: VendorCompactArgs): Promise<VendorCompactResult>;
+}

package/dist/services/runtime/vendors/copilot.js

@@ -0,0 +1,40 @@
+/**
+ * Copilot vendor adapter — slice S2-a.
+ *
+ * Stub adapter (PRD out-of-scope: full implementation lands in a
+ * future slice). Copilot's compact verb is `copilot compact`
+ * (subcommand form, not `--compact` flag — different from Claude
+ * Code + Codex). The adapter encapsulates that verb here so the
+ * runtime service + CLI never see it.
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export class CopilotAdapter {
+    id = 'copilot';
+    displayName = 'GitHub Copilot';
+    async detect() {
+        if (process.env.GITHUB_COPILOT === '1' || process.env.GITHUB_COPILOT === 'true')
+            return true;
+        const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+        return home.length > 0 && existsSync(join(home, '.copilot'));
+    }
+    async compact(args = {}) {
+        const argv = ['compact'];
+        if (args.force === true)
+            argv.push('--force');
+        return new Promise((resolveRun) => {
+            const proc = spawn('copilot', 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 });
+            });
+        });
+    }
+}