peaks-cli 1.4.2 → 2.0.0

package/dist/src/services/openspec/openspec-propose-from-doctor-service.js

@@ -0,0 +1,95 @@
+/**
+ * openspec-propose-from-doctor-service (Slice L3.3) — generates a draft
+ * OpenSpec change record (proposal.md) from a doctor CRITICAL finding.
+ *
+ * Per L1+L2+L3 redesign §5.4: "CRITICAL → proposal 草稿生成". The doctor
+ * scans the project for issues; when a CRITICAL finding is surfaced,
+ * peaks-cli generates a draft `openspec/changes/<id>/proposal.md` so the
+ * LLM doesn't have to start from scratch.
+ *
+ * The draft proposal is INFORMATIONAL — it requires the LLM to review +
+ * edit before `peaks openspec validate` will accept it.
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getErrorMessage } from '../../shared/result.js';
+const SLUGIFY = /[^a-z0-9]+/g;
+function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(SLUGIFY, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 50);
+}
+function formatProposal(input) {
+    return `# Doctor Finding: ${input.finding.rule}
+
+**Date**: ${input.date}
+**Change ID**: ${input.changeId}
+**Source**: \`peaks doctor\` finding (CRITICAL severity: ${input.finding.severity})
+
+## Why
+
+A \`peaks doctor\` scan flagged the following issue at \`${input.finding.id}\`:
+
+> ${input.finding.detail}
+
+The current behavior is broken or degraded. This proposal outlines a fix.
+
+## What Changes
+
+- Address the doctor finding at \`${input.finding.id}\`.
+- See the Why section above for the original error message.
+- Acceptance criteria below describe the success conditions.
+
+## Acceptance Criteria
+
+- \`peaks doctor --json\` returns \`ok: true\` for the \`${input.finding.id}\` check.
+- Re-running the audit does not regress other findings.
+
+## Out of Scope
+
+- Other doctor findings (each is tracked in its own OpenSpec change).
+- Refactors that don't fix this specific issue.
+
+## Risks
+
+- Low: this is a doctor-flagged issue with a clear acceptance criterion.
+
+## Status
+
+- created: ${input.date}
+- last update: ${input.date}
+- state: draft
+- state reason: auto-generated from peaks doctor; LLM must review + edit before validate
+`;
+}
+function makeChangeId(finding, date) {
+    return `${date}-fix-${slugify(finding.id)}`;
+}
+export function proposeFromDoctor(input) {
+    const date = (input.clock ?? (() => new Date().toISOString()))().slice(0, 10);
+    const changeId = makeChangeId(input.finding, date);
+    const changeDir = join(input.projectRoot, 'openspec/changes', changeId);
+    const proposalPath = join(changeDir, 'proposal.md');
+    let created = false;
+    try {
+        if (!existsSync(changeDir)) {
+            mkdirSync(changeDir, { recursive: true });
+        }
+        if (!existsSync(proposalPath)) {
+            const content = formatProposal({
+                changeId,
+                finding: input.finding,
+                title: `Fix ${input.finding.rule}`,
+                date,
+            });
+            writeFileSync(proposalPath, content);
+            created = true;
+        }
+    }
+    catch (error) {
+        throw new Error(`proposeFromDoctor: ${getErrorMessage(error)}`);
+    }
+    return { changeId, changeDir, proposalPath, created };
+}

package/dist/src/services/preferences/preferences-service.d.ts

@@ -0,0 +1,6 @@
+import { DEFAULT_PREFERENCES, PREFERENCES_SCHEMA_VERSION, type ProjectPreferences } from './preferences-types.js';
+export { DEFAULT_PREFERENCES, PREFERENCES_SCHEMA_VERSION };
+export type { ProjectPreferences } from './preferences-types.js';
+export declare function preferencesPath(projectRoot: string): string;
+export declare function loadPreferences(projectRoot: string): ProjectPreferences;
+export declare function savePreferences(projectRoot: string, overrides: Partial<ProjectPreferences>): ProjectPreferences;

package/dist/src/services/preferences/preferences-service.js

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { DEFAULT_PREFERENCES, PREFERENCES_SCHEMA_VERSION, } from './preferences-types.js';
+const PREFS_REL_PATH = '.peaks/preferences.json';
+export { DEFAULT_PREFERENCES, PREFERENCES_SCHEMA_VERSION };
+export function preferencesPath(projectRoot) {
+    return join(projectRoot, PREFS_REL_PATH);
+}
+export function loadPreferences(projectRoot) {
+    const filePath = preferencesPath(projectRoot);
+    if (!existsSync(filePath)) {
+        return structuredClone(DEFAULT_PREFERENCES);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(filePath, 'utf8'));
+    }
+    catch (err) {
+        throw new Error(`PREFERENCES_JSON_INVALID: failed to parse ${filePath}: ${err.message}`);
+    }
+    if (typeof raw !== 'object' ||
+        raw === null ||
+        raw.schema_version !== PREFERENCES_SCHEMA_VERSION) {
+        throw new Error(`PREFERENCES_SCHEMA_MISMATCH: expected schema_version=${PREFERENCES_SCHEMA_VERSION} in ${filePath}, got ${raw?.schema_version}`);
+    }
+    return mergePreferences(DEFAULT_PREFERENCES, raw);
+}
+export function savePreferences(projectRoot, overrides) {
+    const filePath = preferencesPath(projectRoot);
+    const current = loadPreferences(projectRoot);
+    const merged = mergePreferences(current, overrides);
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+    return merged;
+}
+function mergePreferences(base, overrides) {
+    const definedEntries = Object.entries(overrides).filter(([, value]) => value !== undefined);
+    return {
+        ...base,
+        ...Object.fromEntries(definedEntries),
+        schema_version: PREFERENCES_SCHEMA_VERSION,
+    };
+}

package/dist/src/services/preferences/preferences-types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * peaks-cli 2.0 project-local preferences schema.
+ * Per spec §8.4 — per-project state lives in `.peaks/preferences.json`,
+ * NOT in `~/.peaks/config.json` (which is slim global).
+ *
+ * Spec reference: docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §8.4
+ */
+export declare const PREFERENCES_SCHEMA_VERSION = "2.0.0";
+/**
+ * Per-task-level UA install UX prompt decision.
+ * Values:
+ *   - 'unset'              — ask every session (default)
+ *   - 'skip-this-session'  — skip prompt for current session only
+ *   - 'skip-forever'       — never ask, never install
+ */
+export type UaPromptDecision = 'unset' | 'skip-this-session' | 'skip-forever';
+/**
+ * L1a task classification conservatism.
+ * Values:
+ *   - 'default'  — use default signal thresholds
+ *   - 'strict'   — always upgrade to next level (slower, safer)
+ *   - 'lax'      — always downgrade to previous level (faster, riskier)
+ */
+export type ClassifyConservatism = 'default' | 'strict' | 'lax';
+/**
+ * Per-touchpoint headroom-AI mode override.
+ * Spec §7.4 — default 'balanced'.
+ */
+export type HeadroomMode = 'balanced' | 'aggressive' | 'conservative';
+export interface HeadroomPreferences {
+    /** Whether headroom integration is enabled globally. Default: true */
+    readonly enabled: boolean;
+    /** Default mode if a touchpoint doesn't override. Default: 'balanced' */
+    readonly defaultMode: HeadroomMode;
+    /** Per-touchpoint mode overrides */
+    readonly perTouchpoint: {
+        memorySearch: HeadroomMode;
+        retrospectiveSearch: HeadroomMode;
+        doctorScan: HeadroomMode;
+        doctorRoute: HeadroomMode;
+    };
+}
+export interface ClassifyRuleOverrides {
+    /** File count threshold above which a task is promoted to 'feature' */
+    readonly feature_threshold_files?: number;
+    /** Line count threshold above which a task is promoted to 'feature' */
+    readonly feature_threshold_lines?: number;
+    /** Whether to require a 24h grace before cleaning recently-active sessions */
+    readonly runtime_clean_grace_hours?: number;
+}
+export interface SwarmSpeculativePreferences {
+    /** Whether speculative dispatch is enabled. Default: true */
+    readonly enabled: boolean;
+    /** Max concurrent speculative sub-agents. Default: 2 */
+    readonly maxConcurrent: number;
+    /** Min hit rate below which speculative auto-disables. Default: 0.5 */
+    readonly minHitRate: number;
+}
+export interface ProjectPreferences {
+    /**
+     * On-disk schema version. The JSON key is `schema_version` (snake_case) — this matches the
+     * raw on-disk key in `.peaks/preferences.json`, NOT the camelCase used by the rest of this
+     * interface. preferences-service.ts validates this value against PREFERENCES_SCHEMA_VERSION
+     * on load and writes the current value on save. Any mismatch throws PREFERENCES_SCHEMA_MISMATCH.
+     */
+    readonly schema_version: typeof PREFERENCES_SCHEMA_VERSION;
+    readonly economyMode: boolean;
+    readonly swarmMode: boolean;
+    readonly uaPrompt: UaPromptDecision;
+    readonly agentShieldPrompt: UaPromptDecision;
+    readonly classifyConservatism: ClassifyConservatism;
+    readonly classifyRules: ClassifyRuleOverrides;
+    readonly headroom: HeadroomPreferences;
+    readonly swarmSpeculative: SwarmSpeculativePreferences;
+    /** Loop Autonomous (L4 14.5) toggle. Default: false — never auto-enable. */
+    readonly loopAutonomousEnabled: boolean;
+    /**
+     * L2.3 P2-a: ECC AgentShield subprocess toggle. Default: false.
+     *
+     * When true, `peaks audit static` spawns `npx ecc-agentshield scan --json`
+     * and merges its findings into the audit report. When false (default),
+     * the audit runs peaks-cli-only and the subprocess is never spawned.
+     *
+     * The preference is independent of whether ECC is installed — i.e.
+     * `agentShieldEnabled: true` with ECC missing surfaces a soft
+     * "ECC not installed" warning and the audit still completes.
+     */
+    readonly agentShieldEnabled: boolean;
+}
+export declare const DEFAULT_PREFERENCES: ProjectPreferences;

package/dist/src/services/preferences/preferences-types.js

@@ -0,0 +1,38 @@
+/**
+ * peaks-cli 2.0 project-local preferences schema.
+ * Per spec §8.4 — per-project state lives in `.peaks/preferences.json`,
+ * NOT in `~/.peaks/config.json` (which is slim global).
+ *
+ * Spec reference: docs/superpowers/specs/2026-06-11-peaks-cli-l1-l2-l3-redesign.md §8.4
+ */
+export const PREFERENCES_SCHEMA_VERSION = '2.0.0';
+export const DEFAULT_PREFERENCES = {
+    schema_version: PREFERENCES_SCHEMA_VERSION,
+    economyMode: true,
+    swarmMode: true,
+    uaPrompt: 'unset',
+    agentShieldPrompt: 'unset',
+    classifyConservatism: 'default',
+    classifyRules: {
+        feature_threshold_files: 10,
+        feature_threshold_lines: 100,
+        runtime_clean_grace_hours: 24,
+    },
+    headroom: {
+        enabled: true,
+        defaultMode: 'balanced',
+        perTouchpoint: {
+            memorySearch: 'balanced',
+            retrospectiveSearch: 'balanced',
+            doctorScan: 'balanced',
+            doctorRoute: 'conservative',
+        },
+    },
+    swarmSpeculative: {
+        enabled: true,
+        maxConcurrent: 2,
+        minHitRate: 0.5,
+    },
+    loopAutonomousEnabled: false,
+    agentShieldEnabled: false,
+};

package/dist/src/services/skills/skill-conformance-service.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Skill-conformance audit (Slice #12) — checks every peaks-* SKILL.md
+ * against the 5 standards from the L1+L2+L3 redesign §5.4 Slice #12:
+ *
+ *   1. task-level frontmatter (all 12 skills must declare one)
+ *   2. CLI-back 注解 coverage (each skill body must document which
+ *      `peaks <cmd>` commands it composes; the absence is a SKILL.md
+ *      anti-pattern — it means the LLM has to discover the CLI
+ *      primitives by accident)
+ *   3. loadStrategy on-demand 标注 (skills should declare when they
+ *      load — `eager` for always-loaded, `on-demand` for invoked)
+ *   4. 800-line cap (Karpathy limit per spec §2.3)
+ *   5. outputStyle: peaks-concise-v1 frontmatter (peak-cli display
+ *      style for the skill's user-visible output)
+ *
+ * Plus 1 derived check:
+ *   6. CLI primitives declared in references/audit/ (Skill must
+ *      surface every peaks <cmd> it composes in the references/ subdir;
+ *      this is the "CLI-back 注解 100% 覆盖" check)
+ */
+export type LoadStrategy = 'eager' | 'on-demand';
+export type ConformanceLevel = 'pass' | 'warn' | 'fail';
+export interface ConformanceCheck {
+    readonly id: string;
+    readonly skill: string;
+    readonly level: ConformanceLevel;
+    readonly message: string;
+}
+export interface ConformanceReport {
+    readonly checked: number;
+    readonly passed: number;
+    readonly warned: number;
+    readonly failed: number;
+    readonly checks: readonly ConformanceCheck[];
+    readonly summary: string;
+}
+export interface SkillConformanceInput {
+    readonly projectRoot: string;
+}
+export declare function auditSkillConformance(input: SkillConformanceInput): ConformanceReport;

package/dist/src/services/skills/skill-conformance-service.js

@@ -0,0 +1,136 @@
+/**
+ * Skill-conformance audit (Slice #12) — checks every peaks-* SKILL.md
+ * against the 5 standards from the L1+L2+L3 redesign §5.4 Slice #12:
+ *
+ *   1. task-level frontmatter (all 12 skills must declare one)
+ *   2. CLI-back 注解 coverage (each skill body must document which
+ *      `peaks <cmd>` commands it composes; the absence is a SKILL.md
+ *      anti-pattern — it means the LLM has to discover the CLI
+ *      primitives by accident)
+ *   3. loadStrategy on-demand 标注 (skills should declare when they
+ *      load — `eager` for always-loaded, `on-demand` for invoked)
+ *   4. 800-line cap (Karpathy limit per spec §2.3)
+ *   5. outputStyle: peaks-concise-v1 frontmatter (peak-cli display
+ *      style for the skill's user-visible output)
+ *
+ * Plus 1 derived check:
+ *   6. CLI primitives declared in references/audit/ (Skill must
+ *      surface every peaks <cmd> it composes in the references/ subdir;
+ *      this is the "CLI-back 注解 100% 覆盖" check)
+ */
+import { readFileSync, statSync } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const SKILL_NAMES = [
+    'peaks-ide',
+    'peaks-prd',
+    'peaks-ui',
+    'peaks-rd',
+    'peaks-qa',
+    'peaks-sc',
+    'peaks-solo',
+    'peaks-solo-resume',
+    'peaks-solo-status',
+    'peaks-solo-test',
+    'peaks-sop',
+    'peaks-txt',
+    'peaks-doctor'
+];
+const REQUIRED_FRONTMATTER_FIELDS = ['name', 'description'];
+const OPTIONAL_FRONTMATTER_FIELDS = ['task-level', 'loadStrategy', 'outputStyle'];
+const MAX_LINE_COUNT = 800;
+const CLI_BACK_PATTERNS = [
+    /`peaks\s+[a-z][a-z0-9-]+(?:\s+[a-z][a-z0-9-]+)*`/g,
+    /`peaks\s+[a-z][a-z0-9-]+/g,
+];
+function readSkillFrontmatter(skillPath) {
+    if (!existsSync(skillPath))
+        return null;
+    const content = readFileSync(skillPath, 'utf-8');
+    const match = /^---\n([\s\S]*?)\n---\n/.exec(content);
+    if (match === null)
+        return { raw: content, fields: {} };
+    const raw = match[1] ?? '';
+    const fields = {};
+    for (const line of raw.split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim();
+        if (key.length > 0)
+            fields[key] = value;
+    }
+    return { raw, fields };
+}
+function lineCount(filePath) {
+    try {
+        return statSync(filePath).size > 0 ? readFileSync(filePath, 'utf-8').split(/\r?\n/).length : 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function countCliBackReferences(content) {
+    let count = 0;
+    for (const pattern of CLI_BACK_PATTERNS) {
+        pattern.lastIndex = 0;
+        const matches = content.match(pattern);
+        if (matches)
+            count += matches.length;
+    }
+    return count;
+}
+export function auditSkillConformance(input) {
+    const skillsDir = join(input.projectRoot, 'skills');
+    const checks = [];
+    for (const skillName of SKILL_NAMES) {
+        const skillPath = join(skillsDir, skillName, 'SKILL.md');
+        const fm = readSkillFrontmatter(skillPath);
+        // 1. task-level frontmatter
+        if (fm === null) {
+            checks.push({ id: 'frontmatter:present', skill: skillName, level: 'fail', message: 'SKILL.md missing' });
+        }
+        else {
+            for (const required of REQUIRED_FRONTMATTER_FIELDS) {
+                if (fm.fields[required] === undefined) {
+                    checks.push({ id: `frontmatter:${required}`, skill: skillName, level: 'fail', message: `frontmatter missing required field "${required}"` });
+                }
+            }
+        }
+        // 2. CLI-back annotation
+        if (fm !== null) {
+            const content = readFileSync(skillPath, 'utf-8');
+            const cliCount = countCliBackReferences(content);
+            if (cliCount === 0) {
+                checks.push({ id: 'cli-back:present', skill: skillName, level: 'warn', message: 'no `peaks <cmd>` references in SKILL.md body; consider documenting which CLI primitives the skill composes' });
+            }
+        }
+        // 3. loadStrategy on-demand 标注
+        if (fm !== null && fm.fields['loadStrategy'] === undefined) {
+            checks.push({ id: 'loadStrategy:declared', skill: skillName, level: 'warn', message: 'loadStrategy not declared in frontmatter (eager | on-demand)' });
+        }
+        // 4. 800-line cap
+        if (fm !== null) {
+            const lines = lineCount(skillPath);
+            if (lines > MAX_LINE_COUNT) {
+                checks.push({ id: 'line-count:cap', skill: skillName, level: 'fail', message: `${lines} lines > ${MAX_LINE_COUNT} cap (Karpathy)` });
+            }
+        }
+        // 5. outputStyle: peaks-concise-v1
+        if (fm !== null && fm.fields['outputStyle'] === undefined) {
+            checks.push({ id: 'outputStyle:declared', skill: skillName, level: 'warn', message: 'outputStyle not declared in frontmatter' });
+        }
+    }
+    const failed = checks.filter((c) => c.level === 'fail').length;
+    const warned = checks.filter((c) => c.level === 'warn').length;
+    const passed = checks.filter((c) => c.level === 'pass').length;
+    return {
+        checked: checks.length,
+        passed,
+        warned,
+        failed,
+        checks,
+        summary: failed === 0 ? 'all hard checks pass; warnings are advisory' : `${failed} hard failure(s); fix before shipping`,
+    };
+}

package/dist/src/services/skills/skill-runbook-service.js

@@ -1,4 +1,5 @@
 import { dirname, join } from 'node:path';
+import * as path from 'node:path';
 import { readText } from '../../shared/fs.js';
 import { loadSkillRegistry } from './skill-registry.js';
 const DESTRUCTIVE_APPLY_PATTERNS = [
@@ -12,8 +13,25 @@ const DESTRUCTIVE_APPLY_PATTERNS = [
 const AUTHORIZATION_KEYWORDS_PATTERN = /authoriz|explicit|--dry-run|approv|only after|only when/i;
 const PEAKS_COMMAND_LINE_PATTERN = /^\s*peaks\s+\w/;
 function extractRunbookSection(body) {
-    const match = /## Default runbook\n+([\s\S]*?)(?=\n## |$)/.exec(body);
-    return match === null ? null : match[1];
+    // Find a `## Default runbook` heading at the start of a line, then capture
+    // the section body up to the next `## ` heading or end of input.
+    //
+    // Implementation note: we avoid a regex with a multiline `(?=\n## |$)`
+    // lookahead because the `m` flag turns `$` into "end of any line" in
+    // JavaScript, which would let the lazy capture stop at the first `\n`.
+    // Instead, we (a) use the regex only to locate the heading, then (b)
+    // manually scan forward for the next `## ` heading or end of input.
+    const headingRe = /^## Default runbook[^\n]*(?:\n|$)/m;
+    const headingMatch = headingRe.exec(body);
+    if (headingMatch === null)
+        return null;
+    const startAfter = headingMatch.index + headingMatch[0].length;
+    const rest = body.slice(startAfter);
+    // Find the next `## ` heading at the start of a line.
+    const nextHeadingRe = /^## /m;
+    const nextMatch = nextHeadingRe.exec(rest);
+    const end = nextMatch === null ? rest.length : nextMatch.index;
+    return rest.slice(0, end);
 }
 /**
  * Load the runbook section, falling back to `references/runbook.md` if the
@@ -32,15 +50,31 @@ function extractRunbookSection(body) {
  */
 async function loadRunbookSection(skillPath, body) {
     const inline = extractRunbookSection(body);
-    const refPath = join(dirname(skillPath), 'references', 'runbook.md');
-    let refSection = null;
-    try {
-        const refBody = await readText(refPath);
-        refSection = extractRunbookSection(refBody);
-    }
-    catch {
-        // reference file does not exist or is not readable
+    const skillDir = dirname(skillPath);
+    // Try multiple reference filenames. Convention: each skill may name its
+    // runbook file `runbook.md` (the generic name, used by peaks-solo), or
+    // `<role>-runbook.md` (the role-suffixed name, used by peaks-rd → rd-runbook.md,
+    // peaks-qa → qa-runbook.md, etc.). Prefer the longest extracted section.
+    const refCandidates = [
+        join(skillDir, 'references', 'runbook.md'),
+        join(skillDir, 'references', `${path.basename(skillDir).replace(/^peaks-/, '')}-runbook.md`)
+    ];
+    let bestRef = null;
+    for (const refPath of refCandidates) {
+        try {
+            const refBody = await readText(refPath);
+            const refSection = extractRunbookSection(refBody);
+            if (refSection === null)
+                continue;
+            if (bestRef === null || refSection.length > bestRef.length) {
+                bestRef = refSection;
+            }
+        }
+        catch {
+            // candidate not present or unreadable; try the next one
+        }
     }
+    const refSection = bestRef;
     if (inline === null)
         return refSection;
     if (refSection === null)

package/dist/src/services/skills/sync-service.d.ts

@@ -0,0 +1,43 @@
+import type { IdeId } from '../ide/ide-types.js';
+/**
+ * The 8 platforms per Slice #12 final piece. Slice #0.7 + Slice
+ * #0.5.2 registered these in the IdeId union; this list is the
+ * single source of truth for the sync fan-out.
+ */
+export declare const SYNC_PLATFORMS: readonly IdeId[];
+export interface PlatformSyncResult {
+    /** The platform that was attempted. */
+    readonly platform: IdeId;
+    /** True if installBundledSkills returned without error. */
+    readonly ok: boolean;
+    /** Skills newly symlinked (idempotent re-runs return []). */
+    readonly installed: readonly string[];
+    /** Skills whose target was not a managed symlink (third-party owned). */
+    readonly skipped: readonly string[];
+    /** Error message; present when ok=false. */
+    readonly error?: string;
+    /** Wall-clock duration in ms. */
+    readonly durationMs: number;
+}
+export interface SyncServiceInput {
+    readonly projectRoot: string;
+    /** When omitted, the service iterates all 8 platforms. */
+    readonly platforms?: readonly IdeId[] | undefined;
+    /** When true, the installer is invoked in dry-run mode. */
+    readonly dryRun?: boolean | undefined;
+}
+export interface SyncServiceResult {
+    readonly applied: boolean;
+    readonly dryRun: boolean;
+    readonly projectRoot: string;
+    readonly perPlatform: readonly PlatformSyncResult[];
+    readonly syncedCount: number;
+    readonly failedCount: number;
+    readonly totalInstalled: number;
+}
+/**
+ * Validate a single platform id against the SYNC_PLATFORMS
+ * allowlist. Throws on a bogus value.
+ */
+export declare function assertValidPlatform(platform: string): asserts platform is IdeId;
+export declare function runSkillSync(input: SyncServiceInput): Promise<SyncServiceResult>;

package/dist/src/services/skills/sync-service.js

@@ -0,0 +1,99 @@
+/**
+ * peaks skill sync — fan-out the peaks-* skill family to all 8
+ * supported LLM-CLI platforms. Per spec §9 line 1105 (Slice #12
+ * final piece): "peaks skills sync 8 平台分发".
+ *
+ * The 8 target platforms are enumerated by the `IdeId` union
+ * (src/services/ide/ide-types.ts:16-24). The per-IDE install
+ * profile is `IdeSkillInstall`; the actual symlink installer
+ * is `scripts/install-skills.mjs::installBundledSkills` (dynamically
+ * imported so this module does not require a build step).
+ */
+import { pathToFileURL } from 'node:url';
+import { join } from 'node:path';
+/**
+ * The 8 platforms per Slice #12 final piece. Slice #0.7 + Slice
+ * #0.5.2 registered these in the IdeId union; this list is the
+ * single source of truth for the sync fan-out.
+ */
+export const SYNC_PLATFORMS = [
+    'claude-code',
+    'trae',
+    'codex',
+    'cursor',
+    'qoder',
+    'tongyi-lingma',
+    'hermes',
+    'openclaw',
+];
+let cachedInstaller = null;
+async function loadInstaller() {
+    if (cachedInstaller !== null)
+        return cachedInstaller;
+    const scriptPath = join(process.cwd(), 'scripts', 'install-skills.mjs');
+    const mod = (await import(pathToFileURL(scriptPath).href));
+    cachedInstaller = mod.installBundledSkills;
+    return cachedInstaller;
+}
+/**
+ * Validate a single platform id against the SYNC_PLATFORMS
+ * allowlist. Throws on a bogus value.
+ */
+export function assertValidPlatform(platform) {
+    if (!SYNC_PLATFORMS.includes(platform)) {
+        throw new Error(`peaks skill sync: unknown platform "${platform}". ` +
+            `Valid platforms: ${SYNC_PLATFORMS.join(', ')}`);
+    }
+}
+export async function runSkillSync(input) {
+    const platforms = input.platforms ?? SYNC_PLATFORMS;
+    for (const p of platforms) {
+        assertValidPlatform(p);
+    }
+    const dryRun = input.dryRun === true;
+    const installer = await loadInstaller();
+    const perPlatform = [];
+    let syncedCount = 0;
+    let failedCount = 0;
+    let totalInstalled = 0;
+    for (const platform of platforms) {
+        const start = Date.now();
+        try {
+            const result = installer({
+                ideId: platform,
+                projectRoot: input.projectRoot,
+                ...(dryRun ? { dryRun: true } : {}),
+            });
+            perPlatform.push({
+                platform,
+                ok: true,
+                installed: result.installed,
+                skipped: result.skipped,
+                durationMs: Date.now() - start,
+            });
+            syncedCount += 1;
+            totalInstalled += result.installed.length;
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            perPlatform.push({
+                platform,
+                ok: false,
+                installed: [],
+                skipped: [],
+                error: message,
+                durationMs: Date.now() - start,
+            });
+            failedCount += 1;
+        }
+    }
+    return {
+        applied: !dryRun,
+        dryRun,
+        projectRoot: input.projectRoot,
+        perPlatform,
+        syncedCount,
+        failedCount,
+        totalInstalled,
+    };
+}