opencode-swarm 7.86.0 → 7.87.1

package/dist/turbo/epic/activation.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Epic Mode activation decision (Capability C).
+ *
+ * `decideEpicActivation(...)` is the pure heart of M3: given a plan, a
+ * co-change pair list, and the activation thresholds, it returns a
+ * structured `promote | demote` verdict with the rationale fields a
+ * caller can persist for audit. Pure function — no I/O.
+ *
+ * Three independent gates must all pass for promotion:
+ *
+ *   1. **p-threshold gate.** Compute the coupling coefficient `p` over
+ *      the plan's task graph using Capability A's `epicPairConflict` (via
+ *      Capability B's `computeCouplingReport`). Promote only when
+ *      `p <= activation_threshold`.
+ *
+ *   2. **Hot-module gate.** No task in scope may touch a Lean Turbo
+ *      "global" or "protected" path — these are the same lists Lean
+ *      Turbo already maintains (reused by import; not duplicated).
+ *      Touching a hot module forces serial regardless of `p`.
+ *
+ *   3. **Greenfield gate.** If the co-change history is sparse (fewer
+ *      than `min_commits_for_signal` distinct commits across the
+ *      analyzer output), the signal is too weak to trust per brief §4.2's
+ *      greenfield rule. Force serial.
+ *
+ * Default-serial-promote-on-proof (brief §4.2): when any gate fails or
+ * the data is missing, the decision is `demote`. Promotion requires
+ * positive evidence on every gate.
+ */
+import type { CoChangeEntry } from '../../tools/co-change-analyzer.js';
+import type { CouplingTask } from './coupling-report.js';
+/** Thresholds the caller supplies (typically derived from EpicConfigSchema). */
+export interface EpicActivationOptions {
+    /** Plan-wide p ceiling. Plans with p > activationThreshold are demoted. */
+    activationThreshold: number;
+    /** Greenfield floor on the analyzer's commit window. */
+    minCommitsForSignal: number;
+    /** NPMI floor for the co-change conflict signal — passed through to coupling. */
+    cochangeNpmiThreshold: number;
+    /** Minimum raw co-change count for the conflict signal. */
+    cochangeMinCoChanges: number;
+    /**
+     * Capability D (calibration) additions to the hot-module list. The static
+     * Lean Turbo predicates (`isGlobalFile` / `isProtectedPath`) always apply;
+     * these are normalised paths the calibration loop has promoted after
+     * observing divergent writes against the static set. Optional — falsy or
+     * empty means "no calibration overrides". Path matching is exact (post-
+     * `normalizePath`); callers compute that via `effectiveHotModules` in
+     * `./calibration-engine.ts`.
+     */
+    extraHotModules?: readonly string[];
+    /**
+     * Greenfield-smart Rule 1: whether the project is under git version control.
+     * The greenfield gate exists because co-change signals require git history
+     * to compute. When the project is not a git repo, there is no signal type
+     * to evaluate — the gate's premise is absent, so it passes trivially
+     * rather than fail-closed. Callers (typically `epic_run_phase`) resolve
+     * this via `isGitRepo(directory)` from `src/git/branch.ts`.
+     *
+     * Backward-compat: omitted or `undefined` reverts to legacy behavior
+     * (apply the `commitsObserved >= minCommitsForSignal` floor
+     * unconditionally). Callers should pass an explicit boolean.
+     */
+    isGitProject?: boolean;
+    /**
+     * Phase 13 (B20): task IDs the architect declared in `depends:` that
+     * don't resolve to ANY task in the plan. Typically an LLM typo. The
+     * gate fails closed with a dedicated `phantom dep` blocking reason so
+     * the architect sees the actual bad ID instead of being misled into
+     * hunting a non-existent cross-phase upstream. Pass alongside
+     * `crossPhaseUpstreams` (the two lists are disjoint).
+     */
+    phantomDeps?: readonly string[];
+    /**
+     * Phase 10 — predecessor-evidence gate redesign.
+     *
+     * Cross-phase upstream task IDs for the phase being decided: every
+     * task that lives in a strictly-prior phase AND is depended on by a
+     * task in the current phase. The gate verifies each one has a
+     * `swarm(task <id>):` marker in git log via `isUpstreamCommitted`.
+     *
+     * Empty array (the legacy default) ⇒ no cross-phase deps to check;
+     * predecessor evidence is vacuously satisfied. This is correct for
+     * Phase 1 (no prior phase), single-phase projects, and phases the
+     * architect explicitly declared as independent.
+     *
+     * Why this replaces the `commitsObserved >= minCommitsForSignal`
+     * floor: the floor was a statistical proxy for "do we have enough
+     * history to trust `p`?", but in small projects it permanently
+     * blocked parallelism (a 12-task project never reaches 20 commits).
+     * The structural check asks the actually-relevant question — "are
+     * the things this phase depends on actually in git?" — directly,
+     * regardless of project size. The architect's declared dep graph IS
+     * the parallelism specification (Lamport happens-before); Rule 2's
+     * commits ARE the synchronization point; this check ties them
+     * together.
+     *
+     * Callers (`epic_run_phase`) compute this from the plan's dep graph.
+     */
+    crossPhaseUpstreams?: readonly string[];
+    /**
+     * Predicate for the predecessor-evidence check above. Returns true
+     * when the given taskId has a `swarm(task <id>):` marker in git
+     * history. Same predicate Rule 3 uses at the lane planner — share
+     * one source of truth.
+     *
+     * Omitted ⇒ the gate treats every cross-phase upstream as
+     * uncommitted (fail-closed). Pair `crossPhaseUpstreams` with this
+     * predicate, or pass neither.
+     */
+    isUpstreamCommitted?: (taskId: string) => boolean;
+}
+/** Each gate's pass/fail outcome plus the evidence behind it. */
+export interface EpicActivationRationale {
+    pCheck: {
+        passed: boolean;
+        p: number;
+        threshold: number;
+    };
+    hotModuleCheck: {
+        passed: boolean;
+        touchedHotModules: string[];
+    };
+    greenfieldCheck: {
+        passed: boolean;
+        commitsObserved: number;
+        minCommits: number;
+        /**
+         * `true` when the caller flagged the project as non-git
+         * (`options.isGitProject === false`). In that case the gate is
+         * bypassed (`passed: true`) because the co-change signal does not
+         * apply — not because the history floor was met. Surfaced for audit
+         * so reviewers can distinguish "bypassed" from "satisfied".
+         */
+        bypassedNoGit?: boolean;
+        /**
+         * Phase 10: cross-phase upstream task IDs the gate consulted.
+         * Empty when the current phase has no cross-phase deps (Phase 1,
+         * single-phase plans, declared-independent phases).
+         *
+         * Phase 13 (B19): optional because pre-Phase-10 records on disk
+         * (`.swarm/evidence/epic-promotions.jsonl`) lack this field.
+         * Renderers MUST default to `[]` when reading historical records.
+         */
+        crossPhaseUpstreams?: string[];
+        /**
+         * Phase 10: cross-phase upstreams the predicate reported as NOT
+         * yet committed. Non-empty ⇒ the gate failed; the architect
+         * needs to wait for those tasks to commit before re-deciding.
+         *
+         * Phase 13 (B19): optional, same reason as above.
+         */
+        missingUpstreams?: string[];
+        /**
+         * Phase 13 (B20): dep IDs the architect declared that don't
+         * resolve to any task in the plan. Usually an LLM typo; the gate
+         * fails CLOSED so the architect can see the bad ID and fix the
+         * declaration. Distinct from `missingUpstreams` because phantom
+         * IDs aren't tasks that need to be "committed" — they don't
+         * exist at all, and the remediation is "fix the dep ID", not
+         * "wait for the upstream to land".
+         */
+        phantomDeps?: string[];
+    };
+}
+/** The verdict `decideEpicActivation` returns. */
+export interface EpicActivationVerdict {
+    decision: 'promote' | 'demote';
+    p: number;
+    rationale: EpicActivationRationale;
+    /** Plain-English reasons the verdict went the way it did — for logs and UI. */
+    blockingReasons: string[];
+}
+/**
+ * Decide whether the given tasks should be promoted to parallel execution
+ * via Lean Turbo's lane planner.
+ *
+ * Inputs are pre-resolved by the caller:
+ *  - `tasks`: every task in scope (typically the whole plan), with the
+ *    same `{ id, scope }` shape Capability B consumes. The caller
+ *    handles `readTaskScopes` / `files_touched` resolution and any
+ *    completed-task filtering.
+ *  - `cochangePairs`: the analyzer's output (unfiltered) plus the
+ *    `commitsObserved` count from `parseGitLog`. The greenfield gate
+ *    consults the count directly so the function stays pure.
+ *  - `options`: thresholds (typically read from
+ *    `turbo.epic.mode.*` + `turbo.epic.cochange.*`).
+ *
+ * Output: structured verdict the caller persists to
+ * `.swarm/evidence/epic-promotions.jsonl` and surfaces via
+ * `/swarm epic status`.
+ */
+export declare function decideEpicActivation(tasks: CouplingTask[], cochangePairs: CoChangeEntry[], commitsObserved: number, options: EpicActivationOptions): EpicActivationVerdict;

package/dist/turbo/epic/calibration-engine.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Calibration engine for Epic Mode Capability D.
+ *
+ * `applyCalibration(state, newRecords, options) → newState` is a pure
+ * function that walks fresh divergence records (those not yet processed)
+ * and produces an updated calibration state. The wiring code is responsible
+ * for: (a) reading the prior state, (b) filtering history to the
+ * unprocessed tail, (c) writing the new state.
+ *
+ * Hard design rules (brief §4.5-D + the user's ratified §20.3 defaults):
+ *
+ *   1. **Auto-tighten only on threshold.** A divergent task tightens
+ *      `activationThresholdOverride` toward zero by `tightenStep`,
+ *      bounded by `floorThreshold` (we never tighten below the floor —
+ *      a value too small makes Epic Mode never promote anything).
+ *
+ *   2. **Hot-module list monotonically grows.** Files in a divergent
+ *      task's `undeclared` set are added to `hotModuleAdditions`. The
+ *      list is NEVER auto-shrunk; loosening a hot-module promotion
+ *      requires manual intervention. This is a one-way ratchet.
+ *
+ *   3. **Loosen only after `loosenWindow` consecutive clean tasks.**
+ *      Every clean (divergenceRatio === 0) task increments
+ *      `consecutiveCleanCount`; every divergent task resets it to zero.
+ *      When the counter reaches `loosenWindow`, the threshold is loosened
+ *      by `loosenStep` toward the static config value (never past it) and
+ *      the counter resets to zero. The hot-module list is NOT shrunk by
+ *      loosening — only the threshold relaxes.
+ *
+ *   4. **No oscillation.** A clean-then-divergent-then-clean sequence
+ *      cannot swing the threshold back and forth: every divergent task
+ *      resets the clean-counter and tightens by `tightenStep`, so the
+ *      threshold only moves toward zero in the divergent direction and
+ *      toward the static value (with the clean-window gate) in the
+ *      clean direction. Tests assert this invariant.
+ */
+import type { CalibrationState } from './calibration.js';
+import type { DivergenceRecord } from './divergence-recorder.js';
+export interface ApplyCalibrationOptions {
+    /** Static config value — the absolute ceiling for the threshold. */
+    staticThreshold: number;
+    /**
+     * Floor for the threshold — calibration never tightens past this.
+     * Default 0.05 — below that, Epic Mode effectively never promotes
+     * even on highly-decoupled plans.
+     */
+    floorThreshold?: number;
+    /** Per-divergent-task tightening step. Default 0.02. */
+    tightenStep?: number;
+    /** Per-loosening-event step (toward static). Default 0.01. */
+    loosenStep?: number;
+    /** Consecutive-clean-tasks required before any loosening. Default 10. */
+    loosenWindow?: number;
+}
+/**
+ * Apply the calibration rules to a chronological list of NEW divergence
+ * records. Pure — no I/O, no side effects, deterministic for a given
+ * (state, newRecords, options) triple.
+ *
+ * The caller is responsible for tracking which records are "new" (typically
+ * by reading the full divergence history and slicing past the
+ * `processedRecords` count from the current state). This function does
+ * not deduplicate — feeding the same record twice will double-count its
+ * effect.
+ */
+export declare function applyCalibration(state: CalibrationState, newRecords: readonly DivergenceRecord[], options: ApplyCalibrationOptions): CalibrationState;
+/**
+ * Resolve the effective activation threshold by combining the static config
+ * value with the calibration override (if any). The override is always a
+ * tighter or equal value to the static — calibration can never relax past
+ * static. Returns the static value when calibration state is null
+ * (fail-closed mode) or when no override is set.
+ *
+ * Belt-and-braces clamps:
+ *  - upper bound: static ceiling (calibration never relaxes past it)
+ *  - lower bound: 0 (a negative or absurdly small override — e.g. from a
+ *    hand-edited calibration.json — would make Epic Mode never promote
+ *    anything; treat 0 as the absolute floor here; callers that pass a
+ *    higher `floor_threshold` to the engine get that bound at WRITE time,
+ *    so this clamp only matters for corrupt on-disk values)
+ */
+export declare function effectiveActivationThreshold(staticThreshold: number, state: CalibrationState | null): number;
+/**
+ * Union the static hot-module list (Lean Turbo's globals + protected) with
+ * the calibration's learned additions. Returns a fresh array; callers can
+ * pass this to `decideEpicActivation`'s effective-hot-module check.
+ */
+export declare function effectiveHotModules(staticHotModules: readonly string[], state: CalibrationState | null): string[];

package/dist/turbo/epic/calibration.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Durable calibration state for Epic Mode Capability D.
+ *
+ * Persists the LEARNED knob overrides that `decideEpicActivation` consults
+ * at runtime — the activation-threshold override (tighter than the static
+ * config when divergence has been observed) and the auto-added hot-module
+ * list (monotonically grows; never auto-shrinks per design).
+ *
+ * Lives at `<projectRoot>/.swarm/epic/calibration.json`. Pattern mirrors
+ * `src/turbo/epic/state.ts` exactly — atomic `tmp + rename`, per-directory
+ * fail-closed marker on malformed file, repair seam.
+ *
+ * No imports from `src/turbo/lean/` — purely additive to the Epic namespace.
+ */
+/** Persisted shape of `.swarm/epic/calibration.json`. */
+export interface CalibrationState {
+    version: 1;
+    updatedAt: string;
+    /**
+     * Effective activation threshold override. When set, supersedes the
+     * static `turbo.epic.mode.activation_threshold` config value (which is
+     * always the absolute ceiling — calibration can tighten, never loosen
+     * past, the static value). Range: same as the static config — [0, 1].
+     */
+    activationThresholdOverride?: number;
+    /**
+     * Modules promoted to the hot-module list by observed divergence.
+     * Monotonically grows — never auto-shrinks (loosening the hot-module
+     * list requires manual intervention; the calibration loop only adds).
+     * Sorted lexicographically for stable diffs.
+     */
+    hotModuleAdditions: string[];
+    /**
+     * Running counter of consecutive clean (divergenceRatio === 0) task
+     * outcomes since the last divergent task or the last loosening event.
+     * Drives the loosen-rule (loosen only after `loosenWindow` consecutive
+     * clean tasks). Cleared by the engine after any loosening or divergence.
+     */
+    consecutiveCleanCount: number;
+    /** ISO 8601 timestamp of the most recent calibration-engine invocation. */
+    lastCalibrationAt?: string;
+    /** Number of divergence records processed by the engine so far. */
+    processedRecords: number;
+}
+export declare function emptyCalibrationState(): CalibrationState;
+export declare function isCalibrationStateUnreadable(directory: string): boolean;
+export declare function repairCalibrationUnreadable(directory: string): void;
+/**
+ * Read calibration state from disk. Seeds an empty file on first access so
+ * subsequent writes do not race on directory creation. Returns null when
+ * the file is malformed (fail-closed via `stateUnreadableMap`).
+ *
+ * Self-healing: when the in-memory unreadable marker is set, this function
+ * first attempts to re-validate the on-disk file. If a user (or another
+ * process) has repaired the file out-of-band, the marker auto-clears and the
+ * normal read proceeds. Without this, a long-lived plugin process would keep
+ * returning null until manually told to repair (adversarial review H2).
+ */
+export declare function loadCalibrationState(directory: string): CalibrationState | null;
+/**
+ * Atomic write of calibration state. `tmp + rename` pattern with random
+ * suffix to avoid concurrent-collision; tmp file is best-effort cleaned up
+ * on rename failure so a failed write does not leave orphans.
+ */
+export declare function saveCalibrationState(directory: string, state: CalibrationState): void;

package/dist/turbo/epic/cochange-conflict.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Co-change-aware pair conflict predicate for Epic mode.
+ *
+ * Combines Lean Turbo's existing path-based conflict signal (imported from
+ * `../lean/conflicts`) with a git co-change signal (from the
+ * `co_change_analyzer` output, sourced via `./cochange-source`).
+ *
+ * Conservative combination rule (design notes §15.2 step 4):
+ *  - The co-change signal may only ESCALATE a verdict, never DOWNGRADE it.
+ *  - `conflict = pathConflict || cochangeConflict`.
+ *  - This module never modifies Lean Turbo's behavior — when its caller does
+ *    not invoke it, nothing changes anywhere.
+ *
+ * Path / co-change name reconciliation:
+ *  - Scope paths may arrive normalized but absolute (`{projectRoot}/src/x.ts`)
+ *    because `src/turbo/lean/planner.ts:getValidatedFiles` prepends `directory`
+ *    to relative scopes.
+ *  - Co-change paths come from `git log --name-only` and are always
+ *    repo-relative (e.g. `src/x.ts`).
+ *  - We bridge with a boundary-aware suffix match: a scope path matches a
+ *    co-change path if they are equal OR the scope ends with `'/' + cochange`.
+ *    This handles both absolute and relative scope paths without needing the
+ *    project root.
+ */
+import type { CoChangeEntry } from '../../tools/co-change-analyzer.js';
+/**
+ * Threshold for treating a co-change pair as a conflict signal.
+ *
+ * `npmi` and `minCoChanges` directly correspond to fields on
+ * `CoChangeEntry`. Both must be satisfied for a pair to contribute a signal.
+ * Defaults live in `EpicConfigSchema` (`src/config/schema.ts`) and are
+ * deliberately stricter than `co_change_analyzer`'s discovery defaults.
+ */
+export interface CoChangeThreshold {
+    /** Minimum NPMI in [-1, 1]. */
+    npmi: number;
+    /** Minimum raw co-change count, to suppress small-sample noise. */
+    minCoChanges: number;
+}
+/** Detailed verdict from `epicPairConflict`. */
+export interface EpicPairVerdict {
+    /** True iff the two scopes conflict under the combined signal. */
+    conflict: boolean;
+    /** Which signal(s) fired. `'none'` only when `conflict === false`. */
+    reason: 'path' | 'cochange' | 'both' | 'none';
+    /** Concrete pairs that drove the verdict. Empty arrays when no signal fired. */
+    evidence: {
+        /** Path-overlapping pairs (each entry: `[scopeApath, scopeBpath]`). */
+        pathPairs: Array<[string, string]>;
+        /** Co-change pairs (each entry references files as they appear in CoChangeEntry). */
+        cochangePairs: Array<{
+            a: string;
+            b: string;
+            npmi: number;
+            coChangeCount: number;
+        }>;
+    };
+}
+/**
+ * Decide whether two task scopes conflict, combining path-based and co-change
+ * signals. Pure function — no I/O, no side effects.
+ *
+ * @param scopeA       Files task 1 declares. Paths may be absolute or relative.
+ * @param scopeB       Files task 2 declares.
+ * @param cochangePairs Unfiltered co-change entries from `./cochange-source`.
+ *                     This function applies the threshold internally so callers
+ *                     can pass the analyzer's output verbatim.
+ * @param threshold    NPMI floor + min co-change count.
+ *
+ * Behavioral invariants verified by tests:
+ *  - Empty `cochangePairs` (greenfield / signal absent) → verdict is exactly
+ *    the path-only result. This is the "feature disabled" guarantee from
+ *    design notes §15.6.
+ *  - Co-change-only conflict promotes `'none'` to `'cochange'`.
+ *  - Path-only conflict is unaffected by co-change input.
+ *  - Both signals present → reason `'both'`.
+ *  - Empty scopes (either side) → no conflict (no pairs to evaluate).
+ */
+export declare function epicPairConflict(scopeA: string[], scopeB: string[], cochangePairs: CoChangeEntry[], threshold: CoChangeThreshold): EpicPairVerdict;

package/dist/turbo/epic/cochange-source.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Co-change pair source for Epic mode.
+ *
+ * Composes the existing `co_change_analyzer` primitives (`parseGitLog`,
+ * `buildCoChangeMatrix`) to produce a full, unfiltered list of file-pair
+ * co-change entries the Epic conflict module can threshold itself.
+ *
+ * Why not call `detectDarkMatter` directly?
+ *  - `detectDarkMatter` caps output at the top 20 pairs by NPMI and excludes
+ *    pairs that already have a static import edge. That filter is correct for
+ *    *dark-matter discovery* (its purpose) but wrong for lane-conflict signal:
+ *    a high-NPMI pair with a static edge is still a real coupling signal the
+ *    lane planner should know about.
+ *
+ * Caching:
+ *  - One entry per project directory, keyed on `git rev-parse HEAD`.
+ *  - Same HEAD → cache hit, no git re-scan.
+ *  - Different HEAD or different directory → recompute.
+ *  - FIFO eviction at `MAX_TRACKED_DIRS` so multi-project usage stays bounded
+ *    (AGENTS.md invariant 8: module-level state needs explicit eviction).
+ *
+ * Reuse vs reimplementation:
+ *  - This module never copies analyzer logic. It only orchestrates calls to
+ *    the analyzer's existing exported `_internals` (per AGENTS.md invariant
+ *    on composition).
+ *  - The git HEAD read is a separate bounded subprocess, exposed via the
+ *    `_internals` DI seam so tests can stub it without `mock.module`.
+ */
+import * as child_process from 'node:child_process';
+import { type CoChangeEntry, _internals as coChangeAnalyzer } from '../../tools/co-change-analyzer.js';
+declare const execFileAsync: typeof child_process.execFile.__promisify__;
+export interface GetCoChangePairsOptions {
+    /** Maximum commits the analyzer scans. Defaults to 500. */
+    maxCommitsToAnalyze?: number;
+}
+/**
+ * Output of `getCoChangeData`. Carries the same `pairs` returned by
+ * `getCoChangePairs`, plus the commit count the analyzer actually observed
+ * — which Capability C's greenfield gate needs to decide whether the
+ * signal is dense enough to trust.
+ */
+export interface CoChangeData {
+    pairs: CoChangeEntry[];
+    commitsObserved: number;
+}
+/**
+ * Return the full co-change data for the given directory at the current
+ * git HEAD. The returned `pairs` are unfiltered (every pair the analyzer
+ * recorded, with NPMI / lift / counts / static-edge fields); `commitsObserved`
+ * is the number of distinct commits the analyzer scanned. Capability A
+ * applies the NPMI threshold to `pairs`; Capability C's greenfield gate
+ * inspects `commitsObserved`.
+ *
+ * Returns `{ pairs: [], commitsObserved: 0 }` when:
+ *  - Directory is not a git repo, or `git` is unavailable / times out.
+ *  - The analyzer's commit map is empty (greenfield repo).
+ * Both cases are signal-absent.
+ */
+export declare function getCoChangeData(directory: string, options?: GetCoChangePairsOptions): Promise<CoChangeData>;
+/**
+ * Back-compat wrapper kept for the M2 path (`/swarm coupling` only needs
+ * `pairs`). Capability C uses `getCoChangeData` directly for the
+ * greenfield gate.
+ */
+export declare function getCoChangePairs(directory: string, options?: GetCoChangePairsOptions): Promise<CoChangeEntry[]>;
+/** Test-only: drop all cache entries. */
+export declare function _clearCache(): void;
+/** Test-only: cache size, for asserting eviction behavior. */
+export declare function _cacheSize(): number;
+/**
+ * Test-only DI seam. Mutating this object is file-scoped and trivially
+ * restorable via afterEach, avoiding Bun's cross-file `mock.module` leak
+ * (AGENTS.md invariant 7).
+ */
+export declare const _internals: {
+    execFile: typeof execFileAsync;
+    parseGitLog: typeof coChangeAnalyzer.parseGitLog;
+    buildCoChangeMatrix: typeof coChangeAnalyzer.buildCoChangeMatrix;
+};
+export {};

package/dist/turbo/epic/coupling-report.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Coupling report computation for Epic mode (Capability B).
+ *
+ * Given a plan, computes:
+ *  - `p` — the coupling coefficient (fraction of task pairs that conflict
+ *          under the combined path + co-change signal from Capability A).
+ *  - `perModule` — for each file/module that caused at least one conflict,
+ *          the count of conflicting pairs it appeared in.
+ *  - `roadmap` — the modules ranked by conflict-contribution, with each
+ *          one's share of total detected conflicts. The team can use this
+ *          as a decoupling priority order.
+ *
+ * Read-only — this module changes no execution behavior. It composes
+ * Capability A's `epicPairConflict` (the same predicate the future epic
+ * mode will use when scheduling), so the report answers exactly the
+ * question "what would Capability A say about this plan if I asked it
+ * about every task pair?".
+ */
+import type { CoChangeEntry } from '../../tools/co-change-analyzer.js';
+import { type CoChangeThreshold, type EpicPairVerdict } from './cochange-conflict.js';
+/** A task as `epic` mode sees it: identifier + declared file scope. */
+export interface CouplingTask {
+    id: string;
+    scope: string[];
+}
+/** One conflicting pair in the report. */
+export interface ConflictingPair {
+    a: string;
+    b: string;
+    reason: EpicPairVerdict['reason'];
+    cochangeMatches: number;
+    pathMatches: number;
+}
+/** Per-module conflict contribution. */
+export interface ModuleContention {
+    module: string;
+    conflicts: number;
+    share: number;
+}
+/** Output of `computeCouplingReport`. */
+export interface CouplingReport {
+    /** Number of tasks considered. */
+    taskCount: number;
+    /** Number of unordered task pairs evaluated (`n*(n-1)/2`). */
+    totalPairs: number;
+    /** Pairs the combined signal flagged as conflicting. */
+    conflictingPairCount: number;
+    /** Coupling coefficient `p` = conflictingPairCount / totalPairs (0 when totalPairs == 0). */
+    p: number;
+    /** Each conflicting pair, with the per-pair verdict reason and evidence counts. */
+    conflictingPairs: ConflictingPair[];
+    /** Per-module contention table, sorted by `conflicts` descending. */
+    perModule: ModuleContention[];
+    /** Top-N modules with a human-readable rank line for each. */
+    roadmap: string[];
+}
+export interface ComputeCouplingReportOptions {
+    /** Cap on roadmap rank entries. Default 5. */
+    roadmapTop?: number;
+}
+/**
+ * Compute the coupling report over a set of tasks.
+ *
+ * Inputs:
+ *  - `tasks`: the tasks to consider. The caller decides scoping (whole
+ *    plan vs a single phase) and any filtering (pending vs all). Empty
+ *    array is valid and produces `p = 0`.
+ *  - `cochangePairs`: typically the output of
+ *    `getCoChangePairs(directory)` — passed in so this function stays
+ *    pure (no I/O) and trivially testable. Empty array is valid (the
+ *    Capability A predicate falls back to path-only verdicts).
+ *  - `threshold`: NPMI + min-co-changes floor, same shape Capability A
+ *    consumes.
+ *  - `options.roadmapTop`: how many modules to list in the roadmap
+ *    (default 5).
+ *
+ * Pure function — no file I/O, no side effects.
+ */
+export declare function computeCouplingReport(tasks: CouplingTask[], cochangePairs: CoChangeEntry[], threshold: CoChangeThreshold, options?: ComputeCouplingReportOptions): CouplingReport;
+/**
+ * Render a `CouplingReport` as a markdown document. Output shape is
+ * stable so downstream tools can parse it; the JSON form (via
+ * `JSON.stringify(report)`) is the better target for programmatic use.
+ */
+export declare function formatCouplingReportMarkdown(report: CouplingReport): string;