opencode-swarm 7.86.0 → 7.87.1

package/dist/turbo/epic/divergence-recorder.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Divergence recorder for Epic Mode Capability D (self-calibration).
+ *
+ * After every task transitions to `completed`, this module:
+ *   1. Compares the task's DECLARED scope (from
+ *      `.swarm/scopes/scope-{taskId}.json` — what the coder said it would
+ *      touch) against the ACTUAL files modified during the task
+ *      (`session.modifiedFilesThisCoderTask` — what the guardrails hook
+ *      observed the coder writing to).
+ *   2. Computes divergence — undeclared writes (actual − declared), unused
+ *      declarations (declared − actual), and a per-task divergence ratio
+ *      (undeclared / max(1, actual)).
+ *   3. Appends one record to `.swarm/epic/divergence.jsonl`.
+ *
+ * The calibration engine (`./calibration-engine.ts`) reads this history on
+ * the next `epic_decide_phase` invocation and uses it to adjust the
+ * activation threshold and hot-module list. This module just records.
+ *
+ * Pure I/O: never throws to the caller. Failures are logged and swallowed
+ * so the task-completion path is never blocked by an audit write.
+ */
+/** One record per task completion. */
+export interface DivergenceRecord {
+    /** ISO 8601. */
+    timestamp: string;
+    sessionID: string;
+    taskId: string;
+    /** Phase the task belonged to, when known. */
+    phaseNumber?: number;
+    /** Normalised paths declared via `declare_scope` or files_touched fallback. */
+    declaredScope: string[];
+    /** Normalised paths the guardrails hook observed the coder write to. */
+    actualFiles: string[];
+    /** Files in `actualFiles` not present in `declaredScope`. */
+    undeclared: string[];
+    /** Files in `declaredScope` not present in `actualFiles`. */
+    unused: string[];
+    /** undeclared.length / max(1, actualFiles.length). 0 ⇒ fully declared. */
+    divergenceRatio: number;
+    /** True when divergenceRatio === 0 (no undeclared writes). */
+    isClean: boolean;
+}
+/**
+ * Compute the divergence between a declared scope and the files actually
+ * modified. Pure — no I/O, no side effects. Returns the diff sets plus the
+ * ratio used by the calibration engine.
+ *
+ * Path comparison uses `normalizePath` (POSIX-style, no trailing slash,
+ * Windows-lowercased) from Lean Turbo's conflicts module so the comparison
+ * is consistent with everything else in the lane planner.
+ */
+export declare function computeDivergence(declaredScope: readonly string[], actualFiles: readonly string[]): {
+    declared: string[];
+    actual: string[];
+    undeclared: string[];
+    unused: string[];
+    divergenceRatio: number;
+};
+interface RecordTaskDivergenceArgs {
+    directory: string;
+    sessionID: string;
+    taskId: string;
+    phaseNumber?: number;
+    declaredScope: readonly string[];
+    actualFiles: readonly string[];
+}
+/**
+ * Append one divergence record to the JSONL audit file.
+ *
+ * Append-only, line-delimited so partial writes are tolerable (the calibration
+ * reader skips malformed lines). Best-effort — never throws to caller:
+ *   - Directory-creation failure → log and return null.
+ *   - Append write failure → log and return null.
+ * Either keeps the task-completion path moving even if the audit subsystem
+ * is broken (audit miss is not a correctness issue; blocking task completion
+ * would be).
+ */
+export declare function recordTaskDivergence(args: RecordTaskDivergenceArgs): {
+    path: string;
+    record: DivergenceRecord;
+} | null;
+export interface ReadDivergenceHistoryOptions {
+    /** Read at most this many of the most recent records. */
+    limit?: number;
+    /** Filter to this session (default: all sessions). */
+    sessionID?: string;
+    /**
+     * Maximum bytes to read from the tail of the file. Defaults to
+     * `MAX_TAIL_BYTES` (16 MiB) — large enough to hold thousands of
+     * records, small enough to avoid OOMing on a runaway audit log.
+     * Pass `Infinity` to disable the bound (callers that truly need the
+     * whole history — adversarial review H3).
+     */
+    maxBytes?: number;
+}
+/**
+ * Read divergence records from disk, oldest-to-newest within the read
+ * window. Malformed lines (rare — could occur on partial write) are
+ * silently skipped — they do not corrupt the well-formed records before or
+ * after them. Returns `[]` when the file does not exist.
+ *
+ * Tail-bounded: by default reads at most the last `MAX_TAIL_BYTES`. When
+ * the file is larger, the read starts mid-file and the FIRST encountered
+ * line (which is almost certainly a partial record split by the byte
+ * boundary) is discarded. This means very old records are not returned by
+ * a default-bounded read — the calibration engine consumes the tail
+ * incrementally via `processedRecords`, so it never needs the full history
+ * in memory at once. For full-history audit reads (tests, ad-hoc tooling),
+ * pass `maxBytes: Infinity`.
+ */
+export declare function readDivergenceHistory(directory: string, options?: ReadDivergenceHistoryOptions): DivergenceRecord[];
+export {};

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

@@ -0,0 +1,24 @@
+/**
+ * Epic mode — barrel export.
+ *
+ * Epic mode is a new, additive execution mode that composes Lean Turbo without
+ * modifying it. Capabilities:
+ *  - A: co-change-aware pair conflict (`epicPairConflict`).
+ *  - B: coupling KPI + decoupling roadmap (`computeCouplingReport`).
+ *  - C: per-plan activation decision (`decideEpicActivation`).
+ *
+ * Dependency direction is one-way: `epic` depends on `lean`; `lean` never
+ * depends on `epic`. All Lean Turbo files stay byte-for-byte untouched.
+ */
+export type { EpicActivationOptions, EpicActivationRationale, EpicActivationVerdict, } from './activation.js';
+export { decideEpicActivation } from './activation.js';
+export type { CoChangeThreshold, EpicPairVerdict, } from './cochange-conflict.js';
+export { epicPairConflict } from './cochange-conflict.js';
+export type { CoChangeData, GetCoChangePairsOptions, } from './cochange-source.js';
+export { getCoChangeData, getCoChangePairs } from './cochange-source.js';
+export type { ComputeCouplingReportOptions, ConflictingPair, CouplingReport, CouplingTask, ModuleContention, } from './coupling-report.js';
+export { computeCouplingReport, formatCouplingReportMarkdown, } from './coupling-report.js';
+export type { PromotionEvidenceRecord } from './promotion-evidence.js';
+export { appendPromotionEvidence, readPromotionEvidence, } from './promotion-evidence.js';
+export type { EpicLastDecision, EpicPersistedState, EpicSessionState, } from './state.js';
+export { disableEpicMode, emptyPersisted as emptyEpicPersisted, emptySessionState as emptyEpicSessionState, enableEpicMode, isEpicModeActive, isStateUnreadable as isEpicStateUnreadable, loadEpicSessionState, recordEpicDecision, repairStateUnreadable as repairEpicStateUnreadable, resetEpicSession, saveEpicSessionState, } from './state.js';

package/dist/turbo/epic/promotion-evidence.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Promotion-evidence writer for Epic Mode (Capability C).
+ *
+ * Each activation decision (one per phase per session) appends a single
+ * JSON line to `.swarm/evidence/epic-promotions.jsonl`. The file is
+ * line-delimited so partial writes are tolerable — readers can skip a
+ * truncated trailing line and continue.
+ *
+ * The write is intentionally append-mode (not atomic-rename) because
+ * each line is a self-contained record and the file is monotonically
+ * growing. Per AGENTS.md invariant 4, writes go under `ctx.directory`,
+ * never `process.cwd()`.
+ */
+import type { EpicActivationVerdict } from './activation.js';
+/** What `appendPromotionEvidence` writes per decision. */
+export interface PromotionEvidenceRecord {
+    /** ISO 8601 timestamp of the decision. */
+    timestamp: string;
+    /** Session that made the decision (so multi-session usage stays auditable). */
+    sessionID: string;
+    /** Phase the decision applied to (Capability C operates per-plan but each
+     *  phase invokes the runner; we record per phase for granular telemetry). */
+    phase?: number;
+    /** The decision and the rationale, copied from the activation verdict. */
+    verdict: EpicActivationVerdict;
+}
+/**
+ * Append one decision record to `.swarm/evidence/epic-promotions.jsonl`.
+ *
+ * Returns the absolute path of the file written. On any I/O failure the
+ * error is rethrown — the caller decides whether to surface a warning to
+ * the user or fail closed. Returns null when the directory itself cannot
+ * be created (best-effort fail-soft so a missing `.swarm/` does not break
+ * the activation flow's primary verdict).
+ */
+export declare function appendPromotionEvidence(directory: string, record: PromotionEvidenceRecord): string | null;
+/**
+ * Read all evidence records from the JSONL file. Convenience for
+ * `/swarm epic status` and tests. Skips malformed lines (best-effort
+ * tolerance for the rare partial-write case).
+ */
+export declare function readPromotionEvidence(directory: string): PromotionEvidenceRecord[];

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

@@ -0,0 +1,85 @@
+/**
+ * Durable Epic Mode session state (Capability C).
+ *
+ * Persists per-session Epic Mode activation state under
+ * `<projectRoot>/.swarm/epic-state.json` so toggling survives process
+ * restarts. Mirrors the pattern in `src/turbo/lean/state.ts` (atomic
+ * `tmp + rename`, per-directory `stateUnreadableMap` for fail-closed
+ * semantics, sessions-keyed shape) — without modifying that file.
+ *
+ * Dependency direction is one-way: this module imports nothing from
+ * `src/turbo/lean/`. The shape is parallel but independent.
+ */
+/** Top-level state for a single session. */
+export interface EpicSessionState {
+    sessionID: string;
+    /** When epic mode was last enabled for this session (ISO 8601). */
+    enabledAt?: string;
+    /** When epic mode was last disabled for this session (ISO 8601). */
+    disabledAt?: string;
+    /** Most recent activation decision recorded for this session, if any. */
+    lastDecision?: EpicLastDecision;
+    /** Whether epic mode is currently active for this session. */
+    active: boolean;
+}
+/** Minimal snapshot of the last activation decision. */
+export interface EpicLastDecision {
+    decidedAt: string;
+    phase?: number;
+    decision: 'promote' | 'demote';
+    p: number;
+    blockingReasons: string[];
+}
+/** Persisted shape of `.swarm/epic-state.json`. */
+export interface EpicPersistedState {
+    version: 1;
+    updatedAt: string;
+    sessions: Record<string, EpicSessionState>;
+}
+export declare function emptyPersisted(): EpicPersistedState;
+export declare function emptySessionState(sessionID: string): EpicSessionState;
+export declare function isStateUnreadable(directory: string): boolean;
+export declare function repairStateUnreadable(directory: string): void;
+/** Read this session's state, or null if not yet recorded. */
+export declare function loadEpicSessionState(directory: string, sessionID: string): EpicSessionState | null;
+/** Write the given session state, replacing any prior entry for that sessionID. */
+export declare function saveEpicSessionState(directory: string, state: EpicSessionState): void;
+/** True iff epic mode is currently active for the given session. */
+export declare function isEpicModeActive(directory: string, sessionID: string): boolean;
+/**
+ * True iff epic mode is currently active for ANY session in the project.
+ *
+ * Use this when a code path needs to know "is the project running under
+ * Epic Mode right now" without caring which session toggled it. The
+ * session-scoped `isEpicModeActive` answers "did THIS session toggle it" —
+ * a different question with a different answer.
+ *
+ * The architect's session enables Epic via `/swarm epic on`; sub-agents
+ * (coders, reviewers) dispatched through the `Task` tool run in their own
+ * sessions and have no record of that toggle. Asking the project-scoped
+ * check is the only correct way to honor Epic Mode from those flows.
+ * Rule 2's auto-commit (centralized in Phase 5) is the canonical caller.
+ *
+ * Fail-closed: returns `false` on unreadable state, matching the rest of
+ * this module's defaults.
+ */
+export declare function isEpicModeActiveForProject(directory: string): boolean;
+/** Enable epic mode for the session; records `enabledAt`. */
+export declare function enableEpicMode(directory: string, sessionID: string): void;
+/** Disable epic mode for the session; records `disabledAt`. */
+export declare function disableEpicMode(directory: string, sessionID: string): void;
+/** Reset the session's state entry entirely. */
+export declare function resetEpicSession(directory: string, sessionID: string): void;
+/**
+ * Update the session's `lastDecision` field. Used by the runner after each
+ * activation evaluation so `/swarm epic status` can show the most recent
+ * decision rationale without re-reading the evidence JSONL.
+ *
+ * Precondition: the session must already have an entry (i.e. the caller has
+ * called `enableEpicMode` previously). This is intentional — recording a
+ * decision for a never-toggled session would produce phantom state that
+ * `/swarm epic status` could not distinguish from a legitimately-active
+ * session. Callers that reach this function should have already verified
+ * `isEpicModeActive(...)` returned `true`. Throws if no session entry exists.
+ */
+export declare function recordEpicDecision(directory: string, sessionID: string, decision: EpicLastDecision): void;

package/dist/turbo/epic/task-commit.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Auto-commit on task completion — Rule 2 of the greenfield-smart redesign.
+ *
+ * When Epic Mode is active for the session and the project is a git repo,
+ * `update_task_status` calls `commitTaskCompletion` after a task transitions
+ * to `completed` and the durable plan write has succeeded. The resulting
+ * commit serves two purposes:
+ *
+ *   1. **Greenfield gate progress.** Each completed-and-committed task
+ *      advances `commitsObserved` so the activation gate
+ *      (`src/turbo/epic/activation.ts`) eventually opens. Without this,
+ *      an Epic-only workflow never produces commits and the gate
+ *      permanently blocks parallel promotion — the exact failure mode
+ *      Rule 4 of the redesign identified.
+ *
+ *   2. **Parallel-eligibility evidence (Rule 3).** Downstream tasks can
+ *      require their `depends:` upstream to be *committed* (not just
+ *      marked complete) before they fan out. The commit message format
+ *      `swarm(task <id>): ...` is the searchable marker the lane
+ *      planner consumes in `upstream-commits.ts`.
+ *
+ * Failure handling: every step degrades non-fatally. A failed commit must
+ * never block the durable task-status update — the plan ledger is the
+ * authoritative source (AGENTS.md #5), git is a downstream artifact.
+ *
+ * Subprocess discipline: delegates to `src/git/branch.ts`, which already
+ * enforces AGENTS.md #3 (explicit cwd, bounded timeout, array-form spawn,
+ * non-interactive). This module adds no new subprocess primitives.
+ */
+/** Result of a single task-commit attempt. */
+export interface CommitTaskCompletionResult {
+    /**
+     * `true` when a `swarm(task <id>):` marker for this taskId is present
+     * in git history at function exit — whether this call produced it
+     * (`reason: 'success'`) or whether an earlier call did
+     * (`reason: 'idempotent-skip'`).
+     *
+     * Phase 17 (B.M9): pre-Phase-17 the `'already-committed'` reason
+     * returned `committed: false`, self-contradicting ("not committed
+     * because already committed"). Architect LLMs interpreted the
+     * `false` as a failure and retried, producing log noise. The fixed
+     * semantic: `committed` answers "is the marker in git for this
+     * taskId now?" — yes for both the fresh-write and the idempotent
+     * skip paths.
+     */
+    committed: boolean;
+    reason: 'no-git' | 'commit-failed' | 'success' | 'idempotent-skip';
+    sha?: string;
+    error?: string;
+}
+export declare function formatTaskCommitMessage(taskId: string, description?: string): string;
+export declare function commitTaskCompletion(directory: string, taskId: string, description?: string, scopePaths?: string[]): Promise<CommitTaskCompletionResult>;
+/**
+ * DI seam — production code calls through `_internals.<name>` so tests
+ * substitute deterministic doubles without `mock.module`'s cross-file
+ * leak (AGENTS.md invariant 7). Restore in `afterEach`.
+ */
+export declare const _internals: {
+    isGitRepo: (cwd: string) => boolean;
+    /**
+     * Stage exactly the declared scope paths for this task. The trailing
+     * `:(exclude).swarm` + `:(exclude).swarm/**` pathspecs are belt-and-
+     * suspenders against AGENTS.md #4 even when the architect's scope
+     * declaration accidentally points into `.swarm/`. We do NOT rely on
+     * the user's `.gitignore`: a single misconfigured project would
+     * otherwise commit prompts, ledgers, telemetry, and evidence into
+     * git history every time Rule 2 fires.
+     *
+     * Missing pathspecs (declared scope points to a non-existent file) are
+     * left to surface as a `commit-failed` reason — better than silent
+     * staging skip, since it tells the user their scope declaration is
+     * stale. Rule 2's non-fatal contract means the plan-write still wins.
+     */
+    stageScopedPaths: (cwd: string, paths: string[]) => void;
+    /**
+     * `--allow-empty` variant of commit. We don't expose this in
+     * `src/git/branch.ts` because it's specific to the task-completion
+     * marker semantics — a normal commit should fail on empty trees to
+     * surface bugs. Here we explicitly want the marker.
+     *
+     * Phase 8: `--no-verify` skips `pre-commit`, `commit-msg`, and
+     * `pre-commit-msg` hooks. Rule 2's commits are protocol markers, not
+     * user-authored content — running Biome/typecheck/lint on every task
+     * completion would add minutes of wall-clock per task and, worse,
+     * could block the marker entirely on a repo with a strict pre-commit
+     * gate. Plan ledger remains authoritative; the commit is the audit
+     * trail, not the gate.
+     */
+    commitAllowEmpty: (cwd: string, message: string) => void;
+    gitHeadSha: (cwd: string) => string;
+    /**
+     * Returns true when a `swarm(task <id>):` marker subject for this
+     * taskId already exists anywhere in git history. Used by the
+     * idempotency guard above so repeat completion calls don't mint
+     * duplicate markers.
+     *
+     * Implementation: `git log --grep=<pattern> -F` is NOT used (it
+     * fixed-string-matches the whole subject); instead we anchor the
+     * regex with `--extended-regexp` and bound the scan with `-n 1` so a
+     * single match suffices. Returns false on any git failure — the
+     * caller treats that as "unknown" and proceeds.
+     */
+    /**
+     * Phase 11 (B5): async sleep used by `commitTaskCompletion`'s
+     * retry loop. Routed through `_internals` so tests can substitute
+     * a no-op stub and not actually wait during fast-path unit tests.
+     */
+    sleep: (ms: number) => Promise<void>;
+    hasExistingTaskCommit: (cwd: string, taskId: string) => boolean;
+};

package/dist/turbo/epic/upstream-commits.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Upstream-commit predicate — Rule 3 of the greenfield-smart redesign.
+ *
+ * Given a project directory, returns a fast `(taskId) => boolean` predicate
+ * that answers "has this task been committed?" The lane planner consults
+ * this when evaluating cross-batch dependencies: a downstream task is
+ * parallel-eligible only when every `depends:` upstream that lives in a
+ * prior phase batch is already in git HEAD's history.
+ *
+ * Why this matters: without it, the planner treats any dep not in the
+ * current task batch as implicitly satisfied (the existing behavior in
+ * `src/turbo/lean/planner.ts:381-390`). That's fine when the prior batch
+ * actually finished cleanly, but it doesn't distinguish "marked complete"
+ * from "marked complete *and* the work is in version control". Rule 3
+ * insists on the stronger condition so parallel coders can't inherit an
+ * uncommitted upstream worktree.
+ *
+ * Source format: `commitTaskCompletion` writes commit subjects shaped like
+ * `swarm(task <id>): <description>` (see `./task-commit.ts:formatTaskCommitMessage`).
+ * This module parses the `<id>` from those subjects.
+ *
+ * Boundedness (AGENTS.md #3): subprocess timeout matches the rest of git
+ * helpers (30s); `--max-count` caps the log scan; failures degrade to a
+ * permissive predicate so the planner does not regress when git is broken.
+ */
+export interface BuildUpstreamCommitsOptions {
+    /** Override the log scan window. Default: 10,000. */
+    maxCommits?: number;
+}
+/**
+ * Eagerly read git log once and return a fast `(taskId) => boolean`
+ * predicate the lane planner uses for cross-batch upstream-commit checks.
+ *
+ * Single evidence source: a `swarm(task <id>):` commit subject in git
+ * log, produced by Rule 2's `commitTaskCompletion`.
+ *
+ * History note: an earlier revision OR'd in a plan-ledger fallback (any
+ * task with `status: completed` in `.swarm/plan.json` was treated as
+ * committed) to guard against a hypothetical deadlock where `commit-
+ * TaskCompletion` failed silently. Phase 5 of the 2026-06-03 corrective
+ * plan made Rule 2 reliable on every completion path by centralizing
+ * the invocation in `plan/manager.updateTaskStatus` — so the guard's
+ * premise no longer holds, and keeping the fallback would defeat Rule 3's
+ * own purpose (distinguishing "marked complete" from "in git history").
+ * Removed in Phase 6.
+ *
+ * Failure mode:
+ *  - Git log read fails (no git, spawn error, timeout) → predicate
+ *    returns `true` for everything (permissive). The lane planner falls
+ *    back to its legacy "cross-batch dep implicitly satisfied" behavior,
+ *    which is the pre-Rule-3 semantics. Better legacy than wedged in a
+ *    broken environment.
+ */
+export declare function buildIsUpstreamCommitted(directory: string, options?: BuildUpstreamCommitsOptions): (taskId: string) => boolean;
+/**
+ * Phase 12 (B10) — same predicate construction as `buildIsUpstreamCommitted`
+ * but exposes whether the git-log read failed. Callers that need to FAIL
+ * CLOSED on a broken git environment (e.g. the Phase 10 activation gate,
+ * where the predicate is the only safety signal) use `gitFailed` to pick
+ * a stricter policy; callers that can tolerate "I don't know" fall-open
+ * (e.g. Rule 3 at the lane planner, where wave ordering is the backstop)
+ * continue using `buildIsUpstreamCommitted` directly.
+ *
+ * The two-tier API exists because the original permissive degradation
+ * was correct for Rule 3 (no regression vs pre-Rule-3 semantics) but
+ * inverted the safety polarity for Phase 10 (which has no Path-B
+ * fallback after the commit-count floor was retired).
+ */
+export interface UpstreamCommittedEvidence {
+    predicate: (taskId: string) => boolean;
+    /** True when the git-log read threw — predicate is the permissive fallback. */
+    gitFailed: boolean;
+}
+export declare function buildIsUpstreamCommittedWithStatus(directory: string, options?: BuildUpstreamCommitsOptions): UpstreamCommittedEvidence;
+/**
+ * DI seam — production code routes the git-log read through `_internals`
+ * so tests can substitute deterministic doubles without `mock.module`
+ * (AGENTS.md invariant 7).
+ */
+export declare const _internals: {
+    readGitLogSubjects: (cwd: string, max: number) => string;
+};

package/dist/turbo/epic/wave-planner.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Epic Mode Wave Planner.
+ *
+ * The wave planner partitions a phase's pending tasks into ordered *waves*.
+ * A wave is a set of tasks that:
+ *   - have all their dependencies satisfied by tasks in completed waves, AND
+ *   - have mutually disjoint declared scopes (no two tasks in the same wave
+ *     touch a shared file or parent/child path).
+ *
+ * Architectural contrast with the lane planner:
+ *   - Lane planner: greedy fill into a fixed number of independent serial
+ *     chains. Branching DAGs (e.g. `A → B → {C, D, E}`) collapse into a
+ *     single chain because the cross-lane-dep rule forbids C/D/E from
+ *     living in a different lane than A/B.
+ *   - Wave planner: emits a sequence of concurrent groups. The same DAG
+ *     becomes `wave 1: [A], wave 2: [B], wave 3: [C, D, E]`. Within a wave
+ *     the architect dispatches one Task per taskId — all in one message —
+ *     and the next wave starts only when the prior one is done.
+ *
+ * The two planners share `runPartitionPreflight` from `partition-common.ts`
+ * so classification (global/protected/no-scope/normal), scope resolution,
+ * and topological sort are identical. Divergence is intentional and lives
+ * only in the assignment loop below.
+ */
+import type { LeanTurboConfig } from '../../config/schema';
+import { type PlanPhase } from '../lean/partition-common';
+import type { LeanTurboDegradedTask } from '../lean/state';
+/**
+ * A single wave in the Epic plan. Tasks in a wave run concurrently; the next
+ * wave starts only after all tasks in this wave complete.
+ */
+export interface EpicWave {
+    /** 1-indexed wave number (display + ordering). */
+    waveId: number;
+    /** Tasks in this wave. Architect dispatches one Task per id, all in one message. */
+    taskIds: string[];
+    /**
+     * Union of declared scope files across the wave. Informational — Epic
+     * Mode does NOT acquire file locks (architect-driven dispatch goes
+     * directly through `Task`, bypassing the lean runner's lock path).
+     * Used for evidence/divergence reporting.
+     */
+    files: string[];
+}
+/**
+ * The complete wave plan produced by `planEpicWaves`.
+ */
+export interface EpicWavePlan {
+    /** The phase number this plan covers. */
+    phase: number;
+    /** Unique identifier for this wave plan. */
+    planId: string;
+    /** Ordered list of waves. Empty when every task degraded or serialized. */
+    waves: EpicWave[];
+    /** Tasks that were serialized (cycles, no-scope, invalid-scope, protected with serialize policy). */
+    serializedTasks: string[];
+    /** Tasks that were degraded (global files, protected paths, Rule-3 leftovers). */
+    degradedTasks: LeanTurboDegradedTask[];
+    /** Human-readable summary when all tasks ended up degraded. */
+    degradationSummary?: string;
+    /** Total number of pending tasks the planner saw (before assignment). */
+    totalPendingTasks: number;
+    /** Sum of `waves[*].taskIds.length` — tasks that will actually run concurrently in a wave. */
+    totalConcurrentTasks: number;
+}
+/**
+ * Partition phase tasks into ordered concurrent waves.
+ *
+ * @param directory - Project root directory
+ * @param phaseNumber - Phase number to plan
+ * @param plan - The full plan object (from `.swarm/plan.json`)
+ * @param config - Lean Turbo configuration (reused for risk/conflict policy)
+ * @param scopes - Optional pre-loaded scopes map (taskId -> file paths)
+ * @param isUpstreamCommitted - Optional Rule-3 predicate (greenfield-smart).
+ *        When supplied, a cross-batch dependency (a `depends:` upstream NOT
+ *        in this planning call's task set) is treated as satisfied only if
+ *        the predicate returns `true`. Without it, legacy semantics apply
+ *        (cross-batch deps implicitly satisfied).
+ * @returns Complete wave plan with ordered concurrent groups.
+ */
+export declare function planEpicWaves(directory: string, phaseNumber: number, plan: {
+    phases: PlanPhase[];
+}, config: LeanTurboConfig, scopes?: Record<string, string[]>, isUpstreamCommitted?: (taskId: string) => boolean): EpicWavePlan;

package/dist/turbo/lean/partition-common.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared partition primitives for Lean Turbo's lane planner AND Epic Mode's
+ * wave planner. Both planners run the same three preflight steps:
+ *
+ *   1. Resolve declared scopes (or files_touched fallback) per pending task.
+ *   2. Classify each task by file risk (global / protected / no-scope / normal).
+ *   3. Topologically sort with cycle detection so a downstream task can never
+ *      be released before its upstream.
+ *
+ * They diverge only at the assignment step:
+ *   - Lane planner: greedy fill into a fixed number of serial chains.
+ *   - Wave planner: emit ordered concurrent groups whose membership is gated
+ *     by inter-task scope disjointness.
+ *
+ * Owning the preflight in one place guarantees both planners produce
+ * identical classifications and sort orders for the same inputs.
+ */
+import type { LeanTurboConfig } from '../../config/schema';
+import { type TaskRiskAssessment } from './risk';
+/**
+ * A single task within a plan phase. Matches `.swarm/plan.json`.
+ */
+export interface PlanTask {
+    id: string;
+    description: string;
+    status: 'pending' | 'in_progress' | 'completed' | 'blocked';
+    depends?: string[];
+    files_touched?: string[];
+}
+/**
+ * A phase within a plan, containing multiple tasks.
+ */
+export interface PlanPhase {
+    id: number;
+    name: string;
+    tasks: PlanTask[];
+}
+export type ClassifiedTask = {
+    task: PlanTask;
+    files: string[];
+    hasDeclaredScope: boolean;
+    category: TaskRiskAssessment['category'];
+    conflictReason?: string;
+};
+export interface PartitionPreflight {
+    /** Topologically sorted, lexicographically tie-broken. */
+    sortedTasks: ClassifiedTask[];
+    /** taskId -> ClassifiedTask for O(1) lookup. */
+    taskMap: Map<string, ClassifiedTask>;
+    /** Tasks whose deps form a cycle. Callers must fail-closed: serialize them. */
+    tasksInCycle: Set<string>;
+}
+/**
+ * Validate and normalize a task's declared scope.
+ *
+ * Symlink containment is NOT enforced here — the lock layer resolves symlinks
+ * at acquisition time. This lets architects declare scopes with symlinks for
+ * convenience without compromising actual file-write safety.
+ *
+ * @returns Tuple of [validFiles, invalidCount]
+ */
+export declare function getValidatedFiles(files: string[], directory: string): [string[], number];
+/**
+ * Run the shared preflight: resolve scopes, classify by risk, topo-sort with
+ * cycle detection.
+ *
+ * The same `(directory, pendingTasks, config, scopes)` produces the same
+ * `PartitionPreflight` from both planners.
+ */
+export declare function runPartitionPreflight(directory: string, pendingTasks: PlanTask[], config: LeanTurboConfig, scopes?: Record<string, string[]>): PartitionPreflight;
+/**
+ * Build the predicate that a task's dependencies are all satisfied.
+ *
+ * Rule 3 (greenfield-smart): when `isUpstreamCommitted` is supplied, a
+ * cross-batch dependency (a `depends:` upstream NOT in the current planning
+ * call's task set — typically completed in a prior phase) is treated as
+ * satisfied **only** if the predicate returns `true`. Without the predicate
+ * the legacy semantics apply: cross-batch deps are implicitly satisfied.
+ */
+export declare function makeDependencySatisfactionChecker(taskMap: Map<string, ClassifiedTask>, assignedTasks: Set<string>, isUpstreamCommitted?: (taskId: string) => boolean): (task: ClassifiedTask) => boolean;
+/**
+ * Return the next group of tasks ready for assignment: not yet assigned and
+ * all dependencies satisfied. Lexicographically sorted for determinism.
+ */
+export declare function getReadyTasks(sortedTasks: ClassifiedTask[], assignedTasks: Set<string>, isSatisfied: (task: ClassifiedTask) => boolean): ClassifiedTask[];