peaks-cli 1.3.8 → 1.4.0

package/dist/src/services/skill-scope/adapters/cursor.js

@@ -0,0 +1,13 @@
+// TODO(slice-025.3-cursor): research Cursor's per-project skill scoping
+// config format. Cursor uses `.cursor/` for project-local config; the
+// skill-scope hook may live there or in `.cursor/rules/`.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/cursor-skills.json` (source-of-truth) on every
+//    `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// CursorSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const CURSOR_SKILL_SCOPE = makeStubAdapter('cursor', 'slice-025.3-cursor', 'Cursor');

package/dist/src/services/skill-scope/adapters/qoder.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const QODER_SKILL_SCOPE: SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/qoder.js

@@ -0,0 +1,13 @@
+// TODO(slice-025.5-qoder): research Qoder's per-project skill scoping
+// config format. Qoder is an AI IDE by Alibaba; per-project config dir
+// is unconfirmed at slice 025.1.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/qoder-skills.json` (source-of-truth) on every
+//    `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// QoderSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const QODER_SKILL_SCOPE = makeStubAdapter('qoder', 'slice-025.5-qoder', 'Qoder');

package/dist/src/services/skill-scope/adapters/tongyi.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const TONGYI_SKILL_SCOPE: SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/tongyi.js

@@ -0,0 +1,13 @@
+// TODO(slice-025.6-tongyi): research Tongyi Lingma's per-project skill
+// scoping config format. Tongyi Lingma is an AI IDE by Alibaba; per-
+// project config dir is unconfirmed at slice 025.1.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/tongyi-lingma-skills.json` (source-of-truth)
+//    on every `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// TongyiSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const TONGYI_SKILL_SCOPE = makeStubAdapter('tongyi-lingma', 'slice-025.6-tongyi', 'Tongyi Lingma');

package/dist/src/services/skill-scope/adapters/trae.d.ts

@@ -0,0 +1,2 @@
+import type { SkillScopeAdapter } from '../types.js';
+export declare const TRAE_SKILL_SCOPE: SkillScopeAdapter;

package/dist/src/services/skill-scope/adapters/trae.js

@@ -0,0 +1,12 @@
+// TODO(slice-025.2-trae): research Trae's per-project skill scoping config
+// format. Likely candidates: `.trae/skills.json` or `.trae/settings.json`.
+//
+// Until the real format is known, this stub:
+// 1. Writes `.peaks/scope/trae-skills.json` (source-of-truth) on every
+//    `applyScope` so the user's intent is captured on disk.
+// 2. Returns NOT_SUPPORTED with a clear message pointing at this slice.
+//
+// When implementing, replace the makeStubAdapter call with the real
+// TraeSkillScope class.
+import { makeStubAdapter } from './_stub-helper.js';
+export const TRAE_SKILL_SCOPE = makeStubAdapter('trae', 'slice-025.2-trae', 'Trae IDE');

package/dist/src/services/skill-scope/detect.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Detection algorithm for `peaks skill scope`.
+ *
+ * Pure function: given a project root and the installed-skills path, the
+ * algorithm produces a `DetectResult` (signals + per-skill classification
+ * + counts). No filesystem writes, no randomness, no time-of-day. AC11.
+ *
+ * Three layers:
+ * 1. `extractProjectSignals(projectRoot)` — read package.json + tsconfig +
+ *    file tree (top-50 extensions).
+ * 2. `classifySkill(skill, signals, hardcodedRules)` — keyword matching
+ *    against the skill's SKILL.md description.
+ * 3. `detectSkillScope({ projectRoot, installedSkillsPath })` — top-level
+ *    orchestrator that returns the JSON envelope (AC1).
+ */
+import type { ProjectSignals, SkillKind, SkillScopeCounts, SkillScopeRecord } from './types.js';
+/**
+ * Walk `src/` (recursively) AND the project root, collecting the top-50
+ * unique file extensions. Sorted lexicographically.
+ */
+export declare function scanFileTree(projectRoot: string, maxExtensions?: number): string[];
+/**
+ * Build the `ProjectSignals` object from the project root.
+ */
+export declare function extractProjectSignals(projectRoot: string): Promise<ProjectSignals>;
+export interface InstalledSkill {
+    readonly name: string;
+    readonly description: string;
+    readonly skillPath: string;
+}
+interface HardcodedRules {
+    readonly alwaysRelevant: ReadonlySet<string>;
+    readonly nonTsPrefixes: readonly string[];
+}
+/**
+ * Infer the `SkillKind` for a skill by name. Used for the JSON envelope.
+ */
+export declare function inferSkillKind(name: string, alwaysRelevant: ReadonlySet<string>): SkillKind;
+/**
+ * Classify a single skill given the project signals. Returns the relevance
+ * + a list of human-readable reasons (stable for fixtures, so unit tests
+ * can assert exact strings).
+ */
+export declare function classifySkill(skill: InstalledSkill, signals: ProjectSignals, rules: HardcodedRules): SkillScopeRecord;
+export interface DetectInput {
+    readonly projectRoot: string;
+    readonly installedSkillsPath?: string;
+    readonly detectedIde?: string | null;
+}
+export interface DetectResult {
+    readonly detectedIde: string | null;
+    readonly projectSignals: ProjectSignals;
+    readonly skills: readonly SkillScopeRecord[];
+    readonly counts: SkillScopeCounts;
+}
+/**
+ * Discover the installed skills under `installedSkillsPath` (default:
+ * `~/.claude/skills`). Each subdir containing a SKILL.md counts as an
+ * installed skill.
+ */
+export declare function listInstalledSkills(installedSkillsPath: string): Promise<InstalledSkill[]>;
+/**
+ * The default installed-skills path: `~/.claude/skills`. Resolved at call
+ * time so the orchestrator stays pure-ish (no module-level side effects).
+ */
+export declare function defaultInstalledSkillsPath(): string;
+/**
+ * Top-level orchestrator. Reads package.json + tsconfig + file tree,
+ * discovers installed skills, classifies each one, returns the JSON
+ * envelope. Idempotent: same input → same output. No filesystem writes.
+ */
+export declare function detectSkillScope(input: DetectInput): Promise<DetectResult>;
+/** Compute a stable summary hash (used by tests to assert no time-dependent fields). */
+export declare function detectSummary(result: DetectResult): string;
+export {};

package/dist/src/services/skill-scope/detect.js

@@ -0,0 +1,480 @@
+/**
+ * Detection algorithm for `peaks skill scope`.
+ *
+ * Pure function: given a project root and the installed-skills path, the
+ * algorithm produces a `DetectResult` (signals + per-skill classification
+ * + counts). No filesystem writes, no randomness, no time-of-day. AC11.
+ *
+ * Three layers:
+ * 1. `extractProjectSignals(projectRoot)` — read package.json + tsconfig +
+ *    file tree (top-50 extensions).
+ * 2. `classifySkill(skill, signals, hardcodedRules)` — keyword matching
+ *    against the skill's SKILL.md description.
+ * 3. `detectSkillScope({ projectRoot, installedSkillsPath })` — top-level
+ *    orchestrator that returns the JSON envelope (AC1).
+ */
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ALWAYS_RELEVANT_SKILLS, NON_TS_SKILL_PREFIXES, TRACKED_EXTENSIONS, } from './types.js';
+function hasAnyDep(pkg, names) {
+    const all = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    return names.some((name) => Object.prototype.hasOwnProperty.call(all, name));
+}
+function parseNodeEngineMajor(enginesNode) {
+    if (enginesNode === undefined)
+        return null;
+    // Match patterns like '>=20', '^20.0.0', '>=20.0.0 <21.0.0'
+    const match = enginesNode.match(/(\d+)/);
+    return match === null ? null : Number(match[1]);
+}
+/**
+ * Read and parse a JSON file. Returns null on parse error or missing file.
+ */
+async function readJson(path) {
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = await readFile(path, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function asPackageJson(value) {
+    if (value === null || typeof value !== 'object')
+        return null;
+    return value;
+}
+function asTsConfig(value) {
+    if (value === null || typeof value !== 'object')
+        return null;
+    return value;
+}
+/**
+ * Walk `src/` (recursively) AND the project root, collecting the top-50
+ * unique file extensions. Sorted lexicographically.
+ */
+export function scanFileTree(projectRoot, maxExtensions = 50) {
+    const roots = [];
+    if (existsSync(join(projectRoot, 'src')))
+        roots.push(join(projectRoot, 'src'));
+    roots.push(projectRoot);
+    const exts = new Set();
+    // Bound the walk: at most 2000 files, 5 levels deep.
+    let visited = 0;
+    const MAX_FILES = 2000;
+    const MAX_DEPTH = 5;
+    for (const root of roots) {
+        const stack = [root];
+        while (stack.length > 0 && visited < MAX_FILES) {
+            const dir = stack.pop();
+            if (!existsSync(dir))
+                continue;
+            let entries;
+            try {
+                entries = readdirSync(dir, { withFileTypes: true, encoding: 'utf8' });
+            }
+            catch {
+                continue;
+            }
+            for (const entry of entries) {
+                const name = entry.name;
+                if (typeof name !== 'string')
+                    continue;
+                const full = join(dir, name);
+                // Skip hidden dirs (e.g. node_modules, .git) and the fixture `skills/` dir.
+                if (name === 'node_modules' || name === '.git' || name === 'skills' || name === 'dist')
+                    continue;
+                if (entry.isDirectory()) {
+                    const depth = full.split(/[/\\]/).length - projectRoot.split(/[/\\]/).length;
+                    if (depth < MAX_DEPTH)
+                        stack.push(full);
+                }
+                else if (entry.isFile()) {
+                    visited += 1;
+                    if (visited >= MAX_FILES)
+                        break;
+                    const dot = name.lastIndexOf('.');
+                    if (dot < 0)
+                        continue;
+                    const ext = name.slice(dot).toLowerCase();
+                    exts.add(ext);
+                    if (exts.size >= maxExtensions)
+                        break;
+                }
+            }
+        }
+    }
+    return [...exts].sort().slice(0, maxExtensions);
+}
+function hasExt(exts, ext) {
+    return exts.includes(ext);
+}
+/**
+ * Build the `ProjectSignals` object from the project root.
+ */
+export async function extractProjectSignals(projectRoot) {
+    const pkgRaw = await readJson(join(projectRoot, 'package.json'));
+    const pkg = asPackageJson(pkgRaw);
+    const hasPackageJson = pkg !== null;
+    const isTypeScript = hasPackageJson &&
+        (hasAnyDep(pkg, ['typescript', 'tsx', '@types/node']) ||
+            existsSync(join(projectRoot, 'tsconfig.json')));
+    const tsRaw = await readJson(join(projectRoot, 'tsconfig.json'));
+    const tsConfig = asTsConfig(tsRaw);
+    const isTypeScriptESM = (pkg?.type === 'module') ||
+        (tsConfig?.compilerOptions?.module !== undefined &&
+            ['ESNext', 'NodeNext', 'ES2022'].includes(tsConfig.compilerOptions.module));
+    const isReact = pkg !== null && hasAnyDep(pkg, ['react', 'react-dom', 'preact']);
+    const isVue = pkg !== null && hasAnyDep(pkg, ['vue']);
+    const isSvelte = pkg !== null && hasAnyDep(pkg, ['svelte']);
+    const isNext = pkg !== null && hasAnyDep(pkg, ['next']);
+    const isNestJS = pkg !== null && hasAnyDep(pkg, ['@nestjs/core', '@nestjs/common']);
+    const isExpress = pkg !== null && hasAnyDep(pkg, ['express']);
+    const isFastify = pkg !== null && hasAnyDep(pkg, ['fastify']);
+    const isPostgres = pkg !== null && (hasAnyDep(pkg, ['pg', 'postgres', 'postgresql', 'prisma', '@prisma/client']));
+    const isMysql = pkg !== null && hasAnyDep(pkg, ['mysql', 'mysql2']);
+    const isMongo = pkg !== null && hasAnyDep(pkg, ['mongodb', 'mongoose']);
+    const isRedis = pkg !== null && hasAnyDep(pkg, ['redis', 'ioredis']);
+    const isDocker = existsSync(join(projectRoot, 'Dockerfile')) ||
+        existsSync(join(projectRoot, 'docker-compose.yml')) ||
+        existsSync(join(projectRoot, 'docker-compose.yaml'));
+    const isK8s = existsSync(join(projectRoot, 'k8s')) ||
+        existsSync(join(projectRoot, 'kubernetes')) ||
+        existsSync(join(projectRoot, 'deployment.yaml')) ||
+        existsSync(join(projectRoot, 'deployment.yml'));
+    const isCommander = pkg !== null && hasAnyDep(pkg, ['commander']);
+    // Detect Python projects (requirements.txt, pyproject.toml, setup.py, .py presence).
+    const isPython = !hasPackageJson ||
+        existsSync(join(projectRoot, 'requirements.txt')) ||
+        existsSync(join(projectRoot, 'pyproject.toml')) ||
+        existsSync(join(projectRoot, 'setup.py'));
+    const isCodegraph = pkg !== null && hasAnyDep(pkg, ['@colbymchenry/codegraph']);
+    const isHeadroom = pkg !== null && (hasAnyDep(pkg, ['headroom-ai']) ||
+        Object.keys({ ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) }).some((k) => k.startsWith('@headroom/')));
+    const nodeEngineMajor = parseNodeEngineMajor(pkg?.engines?.node);
+    const topExtensions = scanFileTree(projectRoot);
+    // Build the per-extension presence flag map.
+    const hasFileExtension = {};
+    for (const ext of TRACKED_EXTENSIONS) {
+        hasFileExtension[ext.slice(1)] = hasExt(topExtensions, ext);
+    }
+    return {
+        hasPackageJson,
+        isTypeScript,
+        isTypeScriptESM,
+        isReact,
+        isVue,
+        isSvelte,
+        isNext,
+        isNestJS,
+        isExpress,
+        isFastify,
+        isPostgres,
+        isMysql,
+        isMongo,
+        isRedis,
+        isDocker,
+        isK8s,
+        isCommander,
+        isCodegraph,
+        isHeadroom,
+        isPython,
+        nodeEngineMajor,
+        topExtensions,
+        hasFileExtension,
+    };
+}
+/**
+ * Infer the `SkillKind` for a skill by name. Used for the JSON envelope.
+ */
+export function inferSkillKind(name, alwaysRelevant) {
+    if (alwaysRelevant.has(name) && name.startsWith('peaks-'))
+        return 'peaks-family';
+    if (alwaysRelevant.has(name))
+        return 'generic-ai';
+    if (NON_TS_SKILL_PREFIXES.some((p) => name.startsWith(p)))
+        return 'language-specific';
+    return 'other';
+}
+/**
+ * Classify a single skill given the project signals. Returns the relevance
+ * + a list of human-readable reasons (stable for fixtures, so unit tests
+ * can assert exact strings).
+ */
+export function classifySkill(skill, signals, rules) {
+    const reasons = [];
+    // 1. Hard-coded allowlist always wins.
+    if (rules.alwaysRelevant.has(skill.name)) {
+        reasons.push('hard-coded always-relevant');
+        return {
+            name: skill.name,
+            kind: inferSkillKind(skill.name, rules.alwaysRelevant),
+            relevance: 'relevant',
+            reasons,
+        };
+    }
+    // 2. Non-TS prefix → irrelevant when the project is TS.
+    if (rules.nonTsPrefixes.some((prefix) => skill.name.startsWith(prefix))) {
+        if (signals.isTypeScript && !isNonTsProject(signals)) {
+            reasons.push('non-TS skill prefix; project is TS');
+            return {
+                name: skill.name,
+                kind: 'language-specific',
+                relevance: 'irrelevant',
+                reasons,
+            };
+        }
+    }
+    // 3. Keyword matching against the description (strong + weak hits).
+    const desc = skill.description.toLowerCase();
+    // Special-case: when the project is a non-TS project (Python, etc.),
+    // language-specific skills with matching keywords should be relevant.
+    if (isNonTsProject(signals)) {
+        const langMatch = languageKeywordMatch(desc);
+        if (langMatch !== null) {
+            reasons.push(`${langMatch} keyword + non-TS project`);
+            return {
+                name: skill.name,
+                kind: inferSkillKind(skill.name, rules.alwaysRelevant),
+                relevance: 'relevant',
+                reasons,
+            };
+        }
+    }
+    const strong = strongMatches(desc, signals);
+    const weak = weakMatches(desc, signals);
+    if (strong.length > 0) {
+        reasons.push(...strong);
+        return {
+            name: skill.name,
+            kind: inferSkillKind(skill.name, rules.alwaysRelevant),
+            relevance: 'relevant',
+            reasons,
+        };
+    }
+    if (weak.length > 0) {
+        reasons.push(...weak);
+        return {
+            name: skill.name,
+            kind: inferSkillKind(skill.name, rules.alwaysRelevant),
+            relevance: 'borderline',
+            reasons,
+        };
+    }
+    return {
+        name: skill.name,
+        kind: inferSkillKind(skill.name, rules.alwaysRelevant),
+        relevance: 'irrelevant',
+        reasons: ['no project-signal match'],
+    };
+}
+/**
+ * Strong matches: keyword in description that maps to a confirmed project signal.
+ */
+function strongMatches(description, signals) {
+    const matches = [];
+    if (signals.isReact && /\breact\b/.test(description))
+        matches.push('react project + react skill');
+    if (signals.isVue && /\bvue\b/.test(description))
+        matches.push('vue project + vue skill');
+    if (signals.isSvelte && /\bsvelte\b/.test(description))
+        matches.push('svelte project + svelte skill');
+    if (signals.isNext && /\bnext\.?js\b|\bnextjs\b/.test(description))
+        matches.push('next project + nextjs skill');
+    if (signals.isNestJS && /\bnest\.?js\b|\bnestjs\b/.test(description))
+        matches.push('nestjs project + nestjs skill');
+    if (signals.isExpress && /\bexpress\b/.test(description))
+        matches.push('express project + express skill');
+    if (signals.isFastify && /\bfastify\b/.test(description))
+        matches.push('fastify project + fastify skill');
+    if (signals.isPostgres && /\bpostgres|\bpostgresql\b/.test(description))
+        matches.push('postgres project + postgres skill');
+    if (signals.isMysql && /\bmysql\b/.test(description))
+        matches.push('mysql project + mysql skill');
+    if (signals.isMongo && /\bmongo(?:db)?\b/.test(description))
+        matches.push('mongo project + mongo skill');
+    if (signals.isRedis && /\bredis\b/.test(description))
+        matches.push('redis project + redis skill');
+    if (signals.isDocker && /\bdocker\b/.test(description))
+        matches.push('docker project + docker skill');
+    if (signals.isK8s && /\bkubernetes\b|\bk8s\b/.test(description))
+        matches.push('k8s project + k8s skill');
+    if (signals.isCommander && /\bcommander\b|\bcli\b/.test(description))
+        matches.push('cli project + cli skill');
+    if (/\btdd\b|\btest-driven\b/.test(description))
+        matches.push('tdd keyword (always relevant)');
+    if (/\brefactor\b/.test(description))
+        matches.push('refactor keyword (always relevant)');
+    return matches;
+}
+/**
+ * Weak matches: keyword that's a hint but not a confirmed signal.
+ */
+function weakMatches(description, signals) {
+    const matches = [];
+    if (/\bfrontend\b/.test(description) &&
+        (signals.isReact || signals.isVue || signals.isSvelte || signals.isNext)) {
+        matches.push('frontend keyword + frontend project');
+    }
+    if (/\bbackend\b/.test(description) &&
+        (signals.isNestJS || signals.isExpress || signals.isFastify)) {
+        matches.push('backend keyword + backend project');
+    }
+    if (/\bdatabase\b/.test(description) &&
+        (signals.isPostgres || signals.isMysql || signals.isMongo || signals.isRedis)) {
+        matches.push('database keyword + db project');
+    }
+    return matches;
+}
+/**
+ * Map a skill description to a non-TS language when the description
+ * explicitly mentions that language. Returns null when there's no match.
+ */
+function languageKeywordMatch(description) {
+    if (/\bpython\b/.test(description))
+        return 'python';
+    if (/\bkotlin\b/.test(description))
+        return 'kotlin';
+    if (/\bjava\b/.test(description))
+        return 'java';
+    if (/\brust\b/.test(description))
+        return 'rust';
+    if (/\bgo\b|\bgolang\b/.test(description))
+        return 'go';
+    if (/\bruby\b/.test(description))
+        return 'ruby';
+    if (/\bswift\b/.test(description))
+        return 'swift';
+    if (/\bc#\b|\bcsharp\b/.test(description))
+        return 'csharp';
+    if (/\bc\+\+|\bcpp\b/.test(description))
+        return 'cpp';
+    return null;
+}
+/**
+ * Multi-language project heuristic: if the project's file tree contains
+ * extensions matching a non-TS language, OR the project is a Python project,
+ * treat it as a non-TS project and let the language-specific skills be relevant.
+ */
+function isNonTsProject(signals) {
+    if (signals.isPython)
+        return true;
+    const nonTsExts = ['swift', 'kt', 'kts', 'java', 'scala', 'py', 'pyx', 'go', 'rs', 'rb', 'cs'];
+    return nonTsExts.some((ext) => signals.hasFileExtension[ext] === true);
+}
+/**
+ * Discover the installed skills under `installedSkillsPath` (default:
+ * `~/.claude/skills`). Each subdir containing a SKILL.md counts as an
+ * installed skill.
+ */
+export async function listInstalledSkills(installedSkillsPath) {
+    if (!existsSync(installedSkillsPath))
+        return [];
+    let entries;
+    try {
+        entries = readdirSync(installedSkillsPath, { withFileTypes: true, encoding: 'utf8' });
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const name = entry.name;
+        if (typeof name !== 'string')
+            continue;
+        const skillPath = join(installedSkillsPath, name, 'SKILL.md');
+        if (!existsSync(skillPath))
+            continue;
+        try {
+            const raw = await readFile(skillPath, 'utf8');
+            const frontmatter = parseFrontmatterLoose(raw);
+            skills.push({
+                name: frontmatter.name ?? name,
+                description: frontmatter.description ?? '',
+                skillPath,
+            });
+        }
+        catch {
+            skills.push({ name, description: '', skillPath });
+        }
+    }
+    skills.sort((a, b) => a.name.localeCompare(b.name));
+    return skills;
+}
+/**
+ * Lightweight YAML frontmatter parser (good enough for `name` + `description`).
+ * Falls back to regex when the file is malformed.
+ */
+function parseFrontmatterLoose(content) {
+    const lines = content.split(/\r?\n/);
+    if (lines[0] !== '---')
+        return {};
+    const end = lines.findIndex((line, index) => index > 0 && line === '---');
+    if (end === -1)
+        return {};
+    const out = {};
+    for (let i = 1; i < end; i += 1) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+        if (match === null || match[1] === undefined)
+            continue;
+        out[match[1]] = (match[2] ?? '').replace(/^['"]|['"]$/g, '').trim();
+    }
+    return out;
+}
+/**
+ * The default installed-skills path: `~/.claude/skills`. Resolved at call
+ * time so the orchestrator stays pure-ish (no module-level side effects).
+ */
+export function defaultInstalledSkillsPath() {
+    const home = process.env.HOME ?? process.env.USERPROFILE ?? '';
+    return join(home, '.claude', 'skills');
+}
+const ALWAYS_RELEVANT_SET = new Set(ALWAYS_RELEVANT_SKILLS);
+/**
+ * Top-level orchestrator. Reads package.json + tsconfig + file tree,
+ * discovers installed skills, classifies each one, returns the JSON
+ * envelope. Idempotent: same input → same output. No filesystem writes.
+ */
+export async function detectSkillScope(input) {
+    const projectRoot = input.projectRoot;
+    const skillsPath = input.installedSkillsPath ?? defaultInstalledSkillsPath();
+    const signals = await extractProjectSignals(projectRoot);
+    const installed = await listInstalledSkills(skillsPath);
+    const rules = {
+        alwaysRelevant: ALWAYS_RELEVANT_SET,
+        nonTsPrefixes: NON_TS_SKILL_PREFIXES,
+    };
+    const skills = installed.map((skill) => classifySkill(skill, signals, rules));
+    const counts = {
+        relevant: skills.filter((s) => s.relevance === 'relevant').length,
+        borderline: skills.filter((s) => s.relevance === 'borderline').length,
+        irrelevant: skills.filter((s) => s.relevance === 'irrelevant').length,
+    };
+    return {
+        detectedIde: input.detectedIde ?? null,
+        projectSignals: signals,
+        skills,
+        counts,
+    };
+}
+// ---------------------------------------------------------------------------
+// Idempotency guard helper for tests
+// ---------------------------------------------------------------------------
+/** Compute a stable summary hash (used by tests to assert no time-dependent fields). */
+export function detectSummary(result) {
+    const sorted = [...result.skills].sort((a, b) => a.name.localeCompare(b.name));
+    return JSON.stringify({
+        counts: result.counts,
+        skills: sorted.map((s) => ({ name: s.name, relevance: s.relevance })),
+    });
+}
+// Quiet the "unused" warning on statSync when used only in tests paths
+void statSync;

package/dist/src/services/skill-scope/registry.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `peaks skill scope` — adapter registry.
+ *
+ * The registry owns the map from IdeId → SkillScopeAdapter. It exposes two
+ * functions:
+ * - `getScopeAdapter(ide)` — direct lookup. Throws on unknown ide.
+ * - `resolveActiveAdapter(projectRoot)` — discover the best adapter by
+ *   probing every registered adapter's `detect(projectRoot)`. Falls back
+ *   to Claude Code with a synthetic score of 0.5 when no adapter scores
+ *   ≥ 0.5 (R3: "Claude Code shipped, Trae in progress" per package.json).
+ *
+ * See tech-doc-025 §7 for the discovery flow + fallback semantics.
+ */
+import type { IdeId } from '../ide/ide-types.js';
+import type { SkillScopeAdapter } from './types.js';
+/** Get the adapter for a given IDE id. Throws on unsupported IDE. */
+export declare function getScopeAdapter(ide: IdeId): SkillScopeAdapter;
+/** All registered adapter ids (insertion order). */
+export declare function listScopeAdapterIds(): readonly IdeId[];
+/** All registered adapters (insertion order). */
+export declare function listScopeAdapters(): readonly SkillScopeAdapter[];
+export interface ResolvedAdapter {
+    readonly adapter: SkillScopeAdapter;
+    readonly score: number;
+    /** True when the score is synthetic (no real adapter hit ≥ 0.5). */
+    readonly isFallback: boolean;
+}
+/**
+ * Discover the active adapter for a project root. Returns the highest-
+ * scoring adapter; if all adapters score < 0.5, falls back to the Claude
+ * Code adapter with a synthetic score of 0.5 (R3). Stubs (Trae, Cursor,
+ * Codex, Qoder, Tongyi) return 0.0 from `detect()` so they never win.
+ */
+export declare function resolveActiveAdapter(projectRoot: string): Promise<ResolvedAdapter>;
+/**
+ * Test seam: replace the registry (used by stub-adapter tests to inject
+ * a fresh adapter for an IDE without restarting the module).
+ */
+export declare function _setScopeAdapterForTesting(ide: IdeId, adapter: SkillScopeAdapter): void;
+/** Test seam: reset to built-in defaults. */
+export declare function _resetScopeAdaptersForTesting(): void;