peaks-loop 3.0.0

package/dist/src/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-cli 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-cli'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-cli 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-cli
+ * install root, walking up from `import.meta.url` until a
+ * `package.json` with `"name": "peaks-cli"` is found. Returns
+ * `null` when peaks-cli 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-cli 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-cli 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-cli 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/src/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-cli 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/src/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-cli 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/src/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>;

package/dist/src/services/slice/cross-pass-edge-merger.js

@@ -0,0 +1,246 @@
+/**
+ * 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 { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { arbitrate } from './llm-arbitrator.js';
+// ---------------------------------------------------------------------------
+// Static-detection regexes
+// ---------------------------------------------------------------------------
+/** `import type { Foo } from '../upper/...'` and `import type * as Foo from '...'` */
+const TYPE_IMPORT_RE = /import\s+type\s+(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+['"]([^'"]+)['"]/g;
+/** `export { Bar } from '...'` / `export * from '...'` / `export type { Bar } from '...'`. */
+const RE_EXPORT_RE = /\bexport\s+(?:type\s+)?(?:\*|\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/g;
+/** Any `from '...'` — used only for the fixture-shares rule (test files). */
+const ANY_FROM_RE = /\bfrom\s+['"]([^'"]+)['"]/g;
+const RESOLVE_EXTENSIONS = [
+    '',
+    '.ts',
+    '.tsx',
+    '.js',
+    '/index.ts',
+    '/index.tsx',
+    '/index.js'
+];
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+export async function merge(passes, opts) {
+    const edges = [];
+    const llmCalls = [];
+    const maxLlm = opts.maxLlmCalls ?? 2;
+    const cacheDir = opts.cacheDir ?? join(opts.projectRoot, '.peaks/cache/arbitrator');
+    mkdirSync(cacheDir, { recursive: true });
+    for (let i = 0; i < passes.length - 1; i++) {
+        const upper = passes[i];
+        const lower = passes[i + 1];
+        // Index every upper file → the slice that owns it.
+        const upperFileToSlice = new Map();
+        for (const slice of upper.slices) {
+            for (const file of slice.files) {
+                upperFileToSlice.set(file, slice.id);
+            }
+        }
+        for (const slice of lower.slices) {
+            const emittedBefore = edges.length;
+            for (const file of slice.files) {
+                detectStaticEdges(file, slice.id, upper.passNumber, lower.passNumber, upperFileToSlice, edges);
+            }
+            const hadStaticEdge = edges.length > emittedBefore;
+            // LLM fallback — only when this slice emitted nothing AND we still have budget.
+            if (!hadStaticEdge && opts.llmRunner && llmCalls.length < maxLlm) {
+                await runLlmFallback(upper, slice, upper.passNumber, lower.passNumber, cacheDir, maxLlm, opts.llmRunner, edges, llmCalls);
+            }
+        }
+    }
+    return { edges, llmCalls };
+}
+// ---------------------------------------------------------------------------
+// Static detectors — append matched edges to `edges` in-place.
+// ---------------------------------------------------------------------------
+function detectStaticEdges(file, lowerSliceId, fromPass, toPass, upperFileToSlice, edges) {
+    if (!existsSync(file)) {
+        return;
+    }
+    const content = readFileSync(file, 'utf8');
+    // 1. type-shares — `import type ... from '...'`
+    forEachMatch(TYPE_IMPORT_RE, content, (spec, evidence) => {
+        const resolved = resolveImport(file, spec);
+        const upperSliceId = upperFileToSlice.get(resolved);
+        if (upperSliceId !== undefined) {
+            edges.push(buildEdge({
+                fromPass,
+                toPass,
+                fromSliceId: upperSliceId,
+                toSliceId: lowerSliceId,
+                kind: 'type-shares',
+                confidence: 'structural',
+                evidence,
+                arbitratedBy: null,
+            }));
+        }
+    });
+    // 2. import-re-export — `export ... from '...'`
+    forEachMatch(RE_EXPORT_RE, content, (spec, evidence) => {
+        const resolved = resolveImport(file, spec);
+        const upperSliceId = upperFileToSlice.get(resolved);
+        if (upperSliceId !== undefined) {
+            edges.push(buildEdge({
+                fromPass,
+                toPass,
+                fromSliceId: upperSliceId,
+                toSliceId: lowerSliceId,
+                kind: 'import-re-export',
+                confidence: 'structural',
+                evidence,
+                arbitratedBy: null,
+            }));
+        }
+    });
+    // 3. fixture-shares — test file imports an upper module.
+    if (isTestFile(file)) {
+        forEachMatch(ANY_FROM_RE, content, (spec, evidence) => {
+            const resolved = resolveImport(file, spec);
+            const upperSliceId = upperFileToSlice.get(resolved);
+            if (upperSliceId !== undefined) {
+                edges.push(buildEdge({
+                    fromPass,
+                    toPass,
+                    fromSliceId: upperSliceId,
+                    toSliceId: lowerSliceId,
+                    kind: 'fixture-shares',
+                    confidence: 'structural',
+                    evidence,
+                    arbitratedBy: null,
+                }));
+            }
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// LLM fallback
+// ---------------------------------------------------------------------------
+async function runLlmFallback(upper, lowerSlice, fromPass, toPass, cacheDir, maxCallsPerInvocation, llmRunner, edges, llmCalls) {
+    const upperSliceId = upper.slices[0]?.id ?? '<unknown-upper>';
+    const prompt = `Does upper slice "${upperSliceId}" depend on lower slice "${lowerSlice.id}"? ` +
+        `Reply with JSON of the shape {"depends": boolean, "reason": string}.`;
+    const promptHash = createHash('sha256').update(prompt).digest('hex');
+    const result = await arbitrate(prompt, {
+        cacheDir,
+        maxCallsPerInvocation,
+        perCallTimeoutMs: 5000,
+        llmRunner,
+    });
+    const isFailurePath = result.callId === 'budget-exhausted' ||
+        result.callId === 'timeout' ||
+        result.callId === 'error';
+    const confidence = isFailurePath ? 'low' : 'medium';
+    llmCalls.push({
+        callId: result.callId,
+        promptHash,
+        input: prompt,
+        output: result.output ?? '',
+        confidence,
+        tokens: result.tokens
+    });
+    if (result.output === null) {
+        return;
+    }
+    const parsed = parseDependsReply(result.output);
+    if (parsed?.depends === true) {
+        edges.push(buildEdge({
+            fromPass,
+            toPass,
+            fromSliceId: upperSliceId,
+            toSliceId: lowerSlice.id,
+            kind: 'llm-arbitrated',
+            confidence: 'llm',
+            evidence: `llm:${result.callId}: ${parsed.reason}`,
+            arbitratedBy: result.callId,
+        }));
+    }
+}
+function buildEdge(fields) {
+    return {
+        fromPass: fields.fromPass,
+        toPass: fields.toPass,
+        fromSliceId: fields.fromSliceId,
+        toSliceId: fields.toSliceId,
+        kind: fields.kind,
+        confidence: fields.confidence,
+        evidence: fields.evidence,
+        arbitratedBy: fields.arbitratedBy,
+    };
+}
+function forEachMatch(re, content, cb) {
+    re.lastIndex = 0;
+    let match;
+    while ((match = re.exec(content)) !== null) {
+        const spec = match[1];
+        cb(spec, match[0]);
+    }
+}
+/**
+ * Resolve an import specifier relative to the importing file. Tries common
+ * TypeScript extensions and returns the first candidate that exists on disk;
+ * if none exist (e.g. the file is virtual / generated), falls back to the
+ * `.ts` form so the caller can still match against its own index.
+ */
+function resolveImport(fromFile, spec) {
+    const base = isAbsolute(spec)
+        ? spec
+        : resolve(dirname(fromFile), spec);
+    for (const ext of RESOLVE_EXTENSIONS) {
+        const candidate = base + ext;
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return base + '.ts';
+}
+function isTestFile(filePath) {
+    return (filePath.endsWith('.test.ts') ||
+        filePath.endsWith('.test.tsx') ||
+        filePath.endsWith('.test.js') ||
+        /(^|[\\/])__tests__[\\/]/.test(filePath) ||
+        /(^|[\\/])tests[\\/]/.test(filePath));
+}
+function parseDependsReply(raw) {
+    // Accept either a pure JSON object or a fenced ```json { ... } ``` block.
+    const fence = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const candidate = fence ? fence[1] : raw;
+    try {
+        const obj = JSON.parse(candidate);
+        if (typeof obj.depends !== 'boolean')
+            return null;
+        return {
+            depends: obj.depends,
+            reason: typeof obj.reason === 'string' ? obj.reason : '',
+        };
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}