peaks-loop 4.0.0-beta.8 → 4.0.0-beta.9

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

@@ -0,0 +1,86 @@
+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;
+}
+interface InstallBundledSkillsOptions {
+    readonly ideId: IdeId;
+    readonly projectRoot: string;
+    readonly dryRun?: boolean;
+    readonly targetRoot?: string;
+}
+interface InstallResult {
+    readonly installed: readonly string[];
+    readonly skipped: readonly string[];
+}
+type InstallerFn = (opts: InstallBundledSkillsOptions) => InstallResult;
+/**
+ * Resolve the path of `install-skills.mjs` inside the peaks-loop
+ * install root, walking up from `import.meta.url` until a
+ * `package.json` with `"name": "peaks-loop"` is found. Returns
+ * `null` when peaks-loop is not on the import path or the script
+ * is absent (e.g. a partial install).
+ */
+export declare function resolvePeaksCliInstallerPath(): string | null;
+/**
+ * Test seam: attempt to import the installer at `scriptPath`.
+ * Returns the `installBundledSkills` function on success, or
+ * `null` when the file is missing / not importable. The
+ * production code calls this through `loadInstaller`; tests
+ * `vi.spyOn` it to drive the three-tier probe without touching
+ * the real filesystem.
+ */
+export declare function loadInstallerForTest(scriptPath: string): Promise<InstallerFn | null>;
+/**
+ * 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>;
+/**
+ * Test-only export surface. Not part of the public API; subject
+ * to breaking changes without a major version bump.
+ *
+ * The seam exposes the `services` indirection table (so tests
+ * can `vi.spyOn` the resolver and loader) and a cache reset.
+ */
+export declare const __testing: {
+    services: {
+        resolvePeaksCliInstallerPath(): string | null;
+        loadInstallerForTest(scriptPath: string): Promise<InstallerFn | null>;
+    };
+    resetInstallerCache(): void;
+};
+export {};

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

@@ -0,0 +1,271 @@
+/**
+ * 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).
+ *
+ * Slice 2.0.1-bug2-skill-sync-fallback: when peaks-loop is
+ * installed from npm into a consumer project, that consumer's
+ * CWD does not contain `scripts/install-skills.mjs`. The previous
+ * hard-coded `join(process.cwd(), 'scripts', 'install-skills.mjs')`
+ * therefore threw `ERR_MODULE_NOT_FOUND` in every consumer run.
+ * The fix is a three-tier probe:
+ *   1. peaks-loop's own install path (resolved from
+ *      `import.meta.url` walking up to the package root, or
+ *      from `process.argv[1]` for CJS-equivalent entrypoints),
+ *   2. the consumer CWD (`<cwd>/scripts/install-skills.mjs`),
+ *   3. graceful skip — warn once per process, return a no-op
+ *      installer so the per-platform result is `ok: true` with
+ *      `installed: []` and a `skipped` rationale.
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve as resolvePath } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+/**
+ * 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',
+];
+/**
+ * Sentinel: the resolver ran, found no installer, and warned.
+ * Memoized so subsequent `loadInstaller()` calls short-circuit
+ * without re-walking the filesystem on every platform iteration.
+ */
+const NO_INSTALLER_SENTINEL = Symbol('sync-service.no-installer');
+/**
+ * Cache state: either an installer function, the "not found"
+ * sentinel, or `null` (cache cold, first probe still pending).
+ */
+let cachedInstaller = null;
+/**
+ * No-op installer used when neither candidate path resolves to
+ * an importable `install-skills.mjs`. Reports zero installs and
+ * a single skip reason so the per-platform result is `ok: true`
+ * with an explainable `skipped` line.
+ */
+function noopInstaller(_opts) {
+    return {
+        installed: [],
+        skipped: [
+            'install-skills.mjs not found in project; skill sync skipped — bundled skills are installed via peaks-loop postinstall',
+        ],
+    };
+}
+/**
+ * Internal indirection table for the test seam. The production
+ * `loadInstaller` reads `services.resolvePeaksCliInstallerPath()`
+ * and `services.loadInstallerForTest()` at call time, so a
+ * `vi.spyOn(services, 'resolvePeaksCliInstallerPath')` in tests
+ * takes effect (ES module top-level `const` captures the original
+ * reference and would bypass the spy).
+ */
+const services = {
+    resolvePeaksCliInstallerPath,
+    loadInstallerForTest,
+};
+/**
+ * Resolve the path of `install-skills.mjs` inside the peaks-loop
+ * install root, walking up from `import.meta.url` until a
+ * `package.json` with `"name": "peaks-loop"` is found. Returns
+ * `null` when peaks-loop is not on the import path or the script
+ * is absent (e.g. a partial install).
+ */
+export function resolvePeaksCliInstallerPath() {
+    const candidates = [];
+    // Tier 1a: walk up from this module's URL.
+    try {
+        const here = dirname(fileURLToPath(import.meta.url));
+        let cursor = here;
+        for (let depth = 0; depth < 8; depth += 1) {
+            const pkgJson = join(cursor, 'package.json');
+            if (existsSync(pkgJson)) {
+                candidates.push(join(cursor, 'scripts', 'install-skills.mjs'));
+                break;
+            }
+            const parent = dirname(cursor);
+            if (parent === cursor)
+                break;
+            cursor = parent;
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // import.meta.url may be unavailable in some bundlers; fall through.
+    }
+    // Tier 1b: process.argv[1] (the entrypoint). Useful when this
+    // module is bundled or shimmed.
+    try {
+        const argvEntry = process.argv[1];
+        if (typeof argvEntry === 'string' && argvEntry.length > 0) {
+            let cursor = resolvePath(dirname(argvEntry));
+            for (let depth = 0; depth < 8; depth += 1) {
+                const pkgJson = join(cursor, 'package.json');
+                if (existsSync(pkgJson)) {
+                    candidates.push(join(cursor, 'scripts', 'install-skills.mjs'));
+                    break;
+                }
+                const parent = dirname(cursor);
+                if (parent === cursor)
+                    break;
+                cursor = parent;
+            }
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        // process.argv may be unavailable in some runtimes; fall through.
+    }
+    for (const candidate of candidates) {
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Test seam: attempt to import the installer at `scriptPath`.
+ * Returns the `installBundledSkills` function on success, or
+ * `null` when the file is missing / not importable. The
+ * production code calls this through `loadInstaller`; tests
+ * `vi.spyOn` it to drive the three-tier probe without touching
+ * the real filesystem.
+ */
+export async function loadInstallerForTest(scriptPath) {
+    try {
+        const mod = (await import(pathToFileURL(scriptPath).href));
+        return mod.installBundledSkills;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * Resolve and load the installer, memoizing the outcome.
+ * Three-tier probe (peaks-loop install path → CWD → no-op),
+ * with the "not found" outcome memoized as a sentinel so the
+ * warning is logged at most once per process.
+ *
+ * The probe delegates to the `services` indirection table so
+ * tests can `vi.spyOn(services, 'resolvePeaksCliInstallerPath')`
+ * and have the spied value take effect at runtime (direct
+ * module-level calls would bind the original function at load
+ * time and bypass the spy).
+ */
+async function loadInstaller() {
+    if (cachedInstaller === NO_INSTALLER_SENTINEL) {
+        return noopInstaller;
+    }
+    if (cachedInstaller !== null) {
+        return cachedInstaller;
+    }
+    // Tier 1: peaks-loop install path.
+    const peaksCliScript = services.resolvePeaksCliInstallerPath();
+    if (peaksCliScript !== null) {
+        const installer = await services.loadInstallerForTest(peaksCliScript);
+        if (installer !== null) {
+            cachedInstaller = installer;
+            return installer;
+        }
+    }
+    // Tier 2: consumer CWD.
+    const cwdScript = join(process.cwd(), 'scripts', 'install-skills.mjs');
+    const cwdInstaller = await services.loadInstallerForTest(cwdScript);
+    if (cwdInstaller !== null) {
+        cachedInstaller = cwdInstaller;
+        return cwdInstaller;
+    }
+    // Tier 3: graceful skip. Warn once per process.
+    cachedInstaller = NO_INSTALLER_SENTINEL;
+    // eslint-disable-next-line no-console -- intentional user-visible signal
+    console.warn('peaks skill sync: install-skills.mjs not found in project; ' +
+        'skipping (bundled skills come from peaks-loop postinstall).');
+    return noopInstaller;
+}
+/**
+ * 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,
+    };
+}
+/**
+ * Test-only export surface. Not part of the public API; subject
+ * to breaking changes without a major version bump.
+ *
+ * The seam exposes the `services` indirection table (so tests
+ * can `vi.spyOn` the resolver and loader) and a cache reset.
+ */
+export const __testing = {
+    services,
+    resetInstallerCache() {
+        cachedInstaller = null;
+    },
+};

package/dist/services/slice/calibration-store.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Calibration store for slice work-estimation.
+ *
+ * v1 (current): pure heuristic based on LoC + test count + complexity.
+ *   confidence: 'low' until >= 5 historical slice records exist.
+ *   formula: minutesP50 = 0.25 * locSum + 0.5 * testCount + 0.1 * complexitySum
+ *            minutesP90 = minutesP50 * 1.6
+ *
+ * v1.1 (next): read `.peaks/_runtime/<sessionId>/qa/cycle-time.json` history; if
+ *   sample size >= 5 for a complexity bucket, switch to percentile-based
+ *   estimate with confidence 'high'.
+ *
+ * v1 rationale: peaks-loop itself has fewer than 5 completed refactor slices
+ * (per the design doc R3), so v1 cannot be calibrated yet. v1 ships the
+ * heuristic AND records every estimate to `.peaks/_runtime/<sid>/sc/
+ * slice-calibration/<rid>.json` so the next slice can use the prior data.
+ *
+ * LoC is intentionally kept as a primary input (not replaced). The user
+ * feedback that motivated the algorithm explicitly cited LoC as a useful
+ * signal -- the issue was the absence of a DAG on top, not the absence
+ * of LoC. The "complexity" field in nodes is unused for v1 because
+ * codegraph v0.7.10 does not emit it; v2 can re-enable once
+ * `.codegraph/codegraph.db` is read directly.
+ */
+import type { WorkEstimate } from './slice-decompose-types.js';
+/**
+ * Compute a work-estimate envelope.
+ *
+ * @param complexitySum Sum of `complexity` of touched graph nodes. Pass 0
+ *                      when codegraph v0.7.10 (the field is not emitted).
+ * @param testCount     Number of test files this slice adds/modifies.
+ * @param locSum        Sum of LoC across the slice's primary files.
+ * @param sampleSize    Number of historical slice records the calibrator
+ *                      could draw from. Drives confidence:
+ *                        >= 5 -> 'high' (percentile lookup would be used in v1.1)
+ *                        >= 1 -> 'medium' (some signal)
+ *                         == 0 -> 'low' (heuristic only)
+ */
+export declare function calibrate(complexitySum: number, testCount: number, locSum: number, sampleSize: number): WorkEstimate;

package/dist/services/slice/calibration-store.js

@@ -0,0 +1,68 @@
+/**
+ * Calibration store for slice work-estimation.
+ *
+ * v1 (current): pure heuristic based on LoC + test count + complexity.
+ *   confidence: 'low' until >= 5 historical slice records exist.
+ *   formula: minutesP50 = 0.25 * locSum + 0.5 * testCount + 0.1 * complexitySum
+ *            minutesP90 = minutesP50 * 1.6
+ *
+ * v1.1 (next): read `.peaks/_runtime/<sessionId>/qa/cycle-time.json` history; if
+ *   sample size >= 5 for a complexity bucket, switch to percentile-based
+ *   estimate with confidence 'high'.
+ *
+ * v1 rationale: peaks-loop itself has fewer than 5 completed refactor slices
+ * (per the design doc R3), so v1 cannot be calibrated yet. v1 ships the
+ * heuristic AND records every estimate to `.peaks/_runtime/<sid>/sc/
+ * slice-calibration/<rid>.json` so the next slice can use the prior data.
+ *
+ * LoC is intentionally kept as a primary input (not replaced). The user
+ * feedback that motivated the algorithm explicitly cited LoC as a useful
+ * signal -- the issue was the absence of a DAG on top, not the absence
+ * of LoC. The "complexity" field in nodes is unused for v1 because
+ * codegraph v0.7.10 does not emit it; v2 can re-enable once
+ * `.codegraph/codegraph.db` is read directly.
+ */
+/**
+ * Compute a work-estimate envelope.
+ *
+ * @param complexitySum Sum of `complexity` of touched graph nodes. Pass 0
+ *                      when codegraph v0.7.10 (the field is not emitted).
+ * @param testCount     Number of test files this slice adds/modifies.
+ * @param locSum        Sum of LoC across the slice's primary files.
+ * @param sampleSize    Number of historical slice records the calibrator
+ *                      could draw from. Drives confidence:
+ *                        >= 5 -> 'high' (percentile lookup would be used in v1.1)
+ *                        >= 1 -> 'medium' (some signal)
+ *                         == 0 -> 'low' (heuristic only)
+ */
+export function calibrate(complexitySum, testCount, locSum, sampleSize) {
+    if (!Number.isFinite(complexitySum) || complexitySum < 0) {
+        throw new RangeError(`calibrate: complexitySum must be a non-negative finite number, got ${complexitySum}`);
+    }
+    if (!Number.isInteger(testCount) || testCount < 0) {
+        throw new RangeError(`calibrate: testCount must be a non-negative integer, got ${testCount}`);
+    }
+    if (!Number.isFinite(locSum) || locSum < 0) {
+        throw new RangeError(`calibrate: locSum must be a non-negative finite number, got ${locSum}`);
+    }
+    if (!Number.isInteger(sampleSize) || sampleSize < 0) {
+        throw new RangeError(`calibrate: sampleSize must be a non-negative integer, got ${sampleSize}`);
+    }
+    const minutesP50 = 0.25 * locSum + 0.5 * testCount + 0.1 * complexitySum;
+    const minutesP90 = minutesP50 * 1.6;
+    const confidence = sampleSize >= 5 ? 'high' : sampleSize >= 1 ? 'medium' : 'low';
+    const rationale = sampleSize === 0
+        ? 'v1 heuristic: 0.25 min/LoC + 0.5 min/test + 0.1 min/complexity; confidence low because no historical sample'
+        : sampleSize < 5
+            ? `v1 heuristic: ${sampleSize} historical sample(s) available; will switch to percentile lookup at sampleSize >= 5`
+            : `v1 heuristic with sampleSize ${sampleSize}; v1.1 will switch to percentile lookup`;
+    return {
+        complexitySum,
+        testCount,
+        locSum,
+        minutesP50: Math.round(minutesP50 * 10) / 10,
+        minutesP90: Math.round(minutesP90 * 10) / 10,
+        confidence,
+        rationale
+    };
+}

package/dist/services/slice/cross-pass-edge-merger.d.ts

@@ -0,0 +1,53 @@
+/**
+ * CrossPassEdgeMerger — Phase 2 of slice-topology-multipass (W2 T7).
+ *
+ * Produces `CrossPassEdge`s that span two adjacent decomposition passes by
+ * combining fast structural detectors with the `LLMArbitrator` fallback.
+ *
+ * Pipeline (per adjacent pass pair `(upper, lower)`):
+ *   1. Build a `path → upperSliceId` index of every file owned by `upper`.
+ *   2. For each lower slice, for each file in that slice:
+ *        a. type-shares      — `import type { ... } from '...'` resolves to an upper file.
+ *        b. import-re-export — `export ... from '...'` resolves to an upper file.
+ *        c. fixture-shares    — file is a test file AND `from '...'` resolves to an upper file.
+ *      Each match emits one `CrossPassEdge` with `confidence: 'structural'` and
+ *      `arbitratedBy: null`.
+ *   3. If a lower slice emitted NO static edges AND `opts.llmRunner` is provided AND
+ *      `llmCalls.length < opts.maxLlmCalls`, invoke `arbitrate(...)` once. On a
+ *      successful `{"depends": true}` response, emit one edge with
+ *      `kind: 'llm-arbitrated'`, `confidence: 'llm'`, and `arbitratedBy: <callId>`.
+ *   4. The budget is `opts.maxLlmCalls ?? 2`; once exhausted the merger returns
+ *      what it has accumulated and never crashes.
+ *
+ * Pass 3 is reserved for future use; the type allows `passNumber: 3` but v1 input
+ * never contains it. Pairs are processed left-to-right so edges are deterministic.
+ */
+import type { CrossPassEdge, LlmConfidence, PassResult } from './slice-topology-types.js';
+import type { LlmRunner } from '../audit/audit-goal-service.js';
+export interface MergeResult {
+    readonly edges: readonly CrossPassEdge[];
+    readonly llmCalls: readonly LlmCallTrace[];
+}
+export interface MergeOptions {
+    readonly projectRoot: string;
+    readonly llmRunner?: LlmRunner;
+    readonly cacheDir?: string;
+    readonly maxLlmCalls?: number;
+}
+/**
+ * Full LLM-call trace captured by `runLlmFallback` for every arbitrator call.
+ * Mirrors v2 `LlmArbitration` minus the non-null `tokens` contract; the
+ * orchestrator coalesces a possible `null` `tokens` to a zeroed pair.
+ */
+export interface LlmCallTrace {
+    readonly callId: string;
+    readonly promptHash: string;
+    readonly input: string;
+    readonly output: string;
+    readonly confidence: LlmConfidence;
+    readonly tokens: {
+        readonly input: number;
+        readonly output: number;
+    } | null;
+}
+export declare function merge(passes: readonly PassResult[], opts: MergeOptions): Promise<MergeResult>;