opencode-swarm 7.189.0 → 7.190.0

package/dist/epic/scorecard.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Epic v2 C8 — the epic scorecard (pure over the epic record).
+ *
+ * One bounded summary of how an epic ran, computed from what the lifecycle
+ * record already holds (waves, per-task outcomes recorded at wave close,
+ * phase review runs) — no I/O here. The close report embeds it
+ * (`epic-report-v2`, `close.ts`) and `/swarm epic report` shows it live for
+ * the open epic and for past epics (`report.ts`).
+ *
+ * Time (`wave-span-v1`):
+ *   spanMs  = Σ over CLOSED waves of (closedAt − issuedAt)
+ *   workMs  = Σ over tasks completed in a closed wave of
+ *             (resolvedAt − issuedAt of that wave), each clamped ≥ 0
+ *   concurrencyFactor = workMs / spanMs (null when spanMs = 0)
+ * It is a CONCURRENCY FACTOR, NOT A SPEEDUP (critic M12): a task's
+ * issue→resolve time includes queueing behind serialized QA (reviewers and
+ * test engineers run one task at a time), and a wave closes only when the
+ * architect next calls `epic_next_wave`. It says how much task time
+ * overlapped, never how much faster the epic was than a serial run.
+ * interWaveIdleMs = Σ max(0, issuedAt(next) − closedAt(previous)).
+ *
+ * Gate rates are first-pass rates over the tasks completed in the epic;
+ * the failure counts they come from are LOWER BOUNDS (the evidence
+ * workflow keeps only its last 3 retry entries; a phase keeps at most
+ * {@link EPIC_PHASE_VERDICTS_KEEP} review verdicts), so the rates are upper
+ * bounds — `boundedHistory: true` says so.
+ */
+import type { EpicCloseOutcome, EpicRecordV1 } from './lifecycle.js';
+import { type EpicSizingVerdict } from './sizing.js';
+export declare const EPIC_SCORECARD_SCHEMA = "epic-scorecard-v1";
+/** Undeclared files listed (sorted); the total is kept separately. */
+export declare const EPIC_SCORECARD_FILES_KEEP = 20;
+/** Hot files listed (hottest first). */
+export declare const EPIC_SCORECARD_HOT_FILES_KEEP = 10;
+export declare const EPIC_CONCURRENCY_FACTOR_LABEL = "concurrency factor, not speedup; includes queueing behind serialized QA";
+/** What the scorecard reads from an epic record (a v1 report has these too). */
+export type EpicScorecardSource = Pick<EpicRecordV1, 'epicKey' | 'planId' | 'startedAt' | 'forced' | 'sizing' | 'priorDigest' | 'waves' | 'tasks' | 'phases'>;
+export interface EpicScorecardRate {
+    passed: number;
+    of: number;
+    /** passed / of, 3 decimals; null when `of` is 0. */
+    rate: number | null;
+}
+export interface EpicScorecardV1 {
+    schema: typeof EPIC_SCORECARD_SCHEMA;
+    epicKey: string;
+    planId: string;
+    /** `open` for the live scorecard of the open epic. */
+    outcome: EpicCloseOutcome | 'open';
+    startedAt: string;
+    closedAt: string | null;
+    forced: boolean;
+    sizingAtStart: EpicSizingVerdict;
+    tasks: {
+        /** Tasks of the plan (null when the plan is gone or orphaned). */
+        total: number | null;
+        /** Tasks resolved `completed` through an epic wave. */
+        completedInEpic: number;
+        /** Tasks already completed when the epic started (when known). */
+        adoptedAtStart?: number;
+        /** Tasks issued alone in an `exclusive` wave (open wave included). */
+        exclusive: number;
+        /** Tasks issued alone as one task of a densely coupled component. */
+        serialComponent: number;
+    };
+    waves: {
+        /** Waves issued, the open one included (aborted waves excluded). */
+        count: number;
+        /** Waves with two or more tasks. */
+        parallel: number;
+        meanWidth: number;
+        maxWidth: number;
+    };
+    time: {
+        method: 'wave-span-v1';
+        label: typeof EPIC_CONCURRENCY_FACTOR_LABEL;
+        spanMs: number;
+        workMs: number;
+        /** workMs / spanMs, 3 decimals; null when no closed wave has a span. */
+        concurrencyFactor: number | null;
+        interWaveIdleMs: number;
+    };
+    conflicts: {
+        /** Tasks whose worktree merge-back failed while their wave ran. */
+        mergeFailures: number;
+        /** Tasks that wrote files outside their declared scope. */
+        undeclaredWriteTasks: number;
+        /** Undeclared files (task + wave level), sorted, first 20. */
+        undeclaredFiles: string[];
+        undeclaredFilesTotal: number;
+    };
+    rework: {
+        /** Tasks whose evidence workflow reached generation ≥ 2. */
+        tasksWithRework: number;
+        /** Σ max(0, generation − 1). */
+        extraGenerations: number;
+        /** Σ ledger transitions out of `completed` during the epic. */
+        reopened: number;
+    };
+    gates: {
+        stageAFirstPass: EpicScorecardRate;
+        stageBFirstPass: EpicScorecardRate;
+        /** Phases whose FIRST review run was approved by reviewer and critic. */
+        phaseReviewFirstPass: EpicScorecardRate;
+        boundedHistory: true;
+    };
+    learning: {
+        /** Digest of the project prior the epic inherited (null: neutral). */
+        priorDigest: string | null;
+        /** Hot files of the epic's learned state, hottest first (≤ 10). */
+        topHotFiles: string[];
+    };
+}
+export interface EpicScorecardInput {
+    record: EpicScorecardSource;
+    outcome: EpicCloseOutcome | 'open';
+    closedAt: string | null;
+    /** Plan task count (null/absent: unknown). */
+    planTaskTotal?: number | null;
+    /** Tasks completed before the epic started (absent: unknown). */
+    adoptedAtStart?: number;
+    /** Hot files of the learned state (any order is kept; bounded here). */
+    hotFiles?: readonly string[];
+}
+/** The scorecard of `input.record` (pure; never throws on a sane record). */
+export declare function computeEpicScorecard(input: EpicScorecardInput): EpicScorecardV1;
+/** `1h 02m`, `3m 05s`, `12s`, `0s`. */
+export declare function formatEpicDuration(durationMs: number): string;
+/** Markdown lines for `/swarm epic report` (bounded by the scorecard). */
+export declare function formatEpicScorecardLines(card: EpicScorecardV1): string[];

package/dist/epic/shaping-sizing.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Epic v2 C7 — THE plan sizing (pure), shared by `/swarm epic start` and
+ * plan shaping (`shaping.ts`), bounded by a work budget.
+ *
+ * T pending tasks (status ∉ {completed, closed}), C of them with an
+ * estimated scope (live declared scope, else `files_touched`), L = Σ over
+ * phases of the dry-run steps of the component planner
+ * (`dryRunEpicPhase`, `components.ts`: waves + tasks it can never
+ * schedule), then `evaluateEpicSizing` (`sizing.ts`: S = T / L, Amdahl
+ * S_eff). Cross-phase dependencies count as satisfied (phases run in order).
+ *
+ * Bounded: every dry-run step is charged its deterministic cost
+ * (`epicWaveWork`, ≈ path comparisons) against `maxWork`; when the budget
+ * runs out the remaining tasks count as one serial step each (a
+ * pessimistic L — never an optimistic one) and the sizing is `aborted`.
+ * Without `maxWork` the sizing is unbounded and exact.
+ *
+ * Pure except {@link isDirectoryOnDisk}, the one bounded stat callers pass
+ * to shaping for scope entries without an extension.
+ */
+import type { LeanTurboConfig, PluginConfig } from '../config/schema.js';
+import type { PlanTask as PartitionTask } from '../turbo/lean/partition-common.js';
+import type { EpicPlanningSignals } from './planning-signals.js';
+import { type EpicSizingThresholds, type EpicSizingVerdict } from './sizing.js';
+/**
+ * Work units `/swarm epic start` may spend sizing a plan (≈ 1.5 s on a
+ * laptop; plan shaping's own allowance is `MAX_SHAPING_WORK`). Beyond it
+ * the remaining tasks count as serial and the refusal says the plan was
+ * too large to size exactly.
+ */
+export declare const MAX_START_SIZING_WORK = 60000000;
+/**
+ * Is the project-relative scope `entry` a directory on disk? One `statSync`
+ * (false on any error or an escaping path).
+ */
+export declare function isDirectoryOnDisk(directory: string, entry: string): boolean;
+/** The plan view sizing and shaping read (a structural subset of `Plan`). */
+export interface EpicShapingTask {
+    id: string;
+    status?: string;
+    size?: string;
+    description?: string;
+    depends?: readonly string[];
+    files_touched?: readonly string[];
+}
+export interface EpicShapingPhase {
+    id: number;
+    tasks?: readonly EpicShapingTask[];
+}
+/** Pending = still to run (the sizing's T): not completed and not closed. */
+export declare function isEpicPendingStatus(status: string | undefined): boolean;
+export interface EpicScopeEstimate {
+    /** Pending task id → estimated scope. */
+    scopes: Record<string, string[]>;
+    pendingIds: string[];
+    /** Pending tasks with a non-empty estimated scope. */
+    scoped: number;
+}
+/**
+ * Estimated scope of every pending task: the live declared scope, else
+ * `files_touched` (declarations are per phase and expire, so most tasks
+ * are estimated from the plan).
+ */
+export declare function estimateEpicScopes(phases: readonly EpicShapingPhase[], declared: Readonly<Record<string, readonly string[]>>): EpicScopeEstimate;
+/** Everything the dry run needs besides the tasks and their scopes. */
+export interface EpicPlanSizingContext {
+    directory: string;
+    leanConfig: LeanTurboConfig;
+    signals: EpicPlanningSignals;
+    maxParallel: number;
+    thresholds: EpicSizingThresholds;
+}
+/**
+ * The epic's wave width: `turbo.lean.max_parallel_coders` (default 4) in a
+ * git project; 1 otherwise (a non-git epic runs serially).
+ */
+export declare function epicWaveWidth(config: Pick<PluginConfig, 'turbo'>, isGitRepo: boolean): number;
+/** The sizing context of `config` (lean risk policy + sizing thresholds). */
+export declare function epicSizingContextFor(directory: string, config: Pick<PluginConfig, 'turbo' | 'epic'>, maxParallel: number, signals: EpicPlanningSignals): EpicPlanSizingContext;
+/** One phase's dry run as the sizing counts it. */
+export interface EpicPhaseRun {
+    /** Serial steps: waves + unscheduled tasks. */
+    steps: number;
+    /** Tasks the run could not schedule (cycle, blocked, or budget). */
+    unscheduled: number;
+    /** Work units spent. */
+    work: number;
+    /** The run stopped at its work budget. */
+    aborted: boolean;
+}
+/** The pending tasks of a phase, as the planner reads them. */
+export declare function pendingTasksOf(phase: EpicShapingPhase): PartitionTask[];
+/** Dry-run one phase's `tasks` (bounded by `maxWork` when given). */
+export declare function runEpicPhase(context: EpicPlanSizingContext, tasks: readonly PartitionTask[], scopes: Record<string, string[]>, maxWork?: number): EpicPhaseRun;
+export interface EpicPlanSizing {
+    verdict: EpicSizingVerdict;
+    /** Phase id → its dry run (phases with pending tasks only). */
+    phases: Map<number, EpicPhaseRun>;
+    /** Work units spent over all phases. */
+    work: number;
+    /** A phase's dry run stopped at the budget: L is pessimistic. */
+    aborted: boolean;
+}
+/**
+ * THE sizing of a plan (see the module header). `maxWork` bounds the total
+ * work over every phase.
+ */
+export declare function sizeEpicPlan(context: EpicPlanSizingContext, phases: readonly EpicShapingPhase[], estimate: EpicScopeEstimate, maxWork?: number): EpicPlanSizing;

package/dist/epic/shaping-suggestions.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Epic v2 C7 — plan-shaping suggestion builders (pure; orchestrated by
+ * `shapeEpicPlan` in `shaping.ts`).
+ *
+ * Every suggestion that changes the plan is a CONCRETE `save_plan` patch
+ * (complete resulting `files_touched` / `depends` per touched task, new
+ * task ids unused and valid) and is judged by a what-if: the patch applied
+ * to the phase, the phase dry-run again (`runEpicPhase`), L and S_eff
+ * recomputed. A what-if is rejected when it leaves more tasks unschedulable
+ * than the baseline (a dependency cycle the patch would create), when it
+ * does not finish within the work budget, or when it does not help.
+ *
+ * Work is metered ({@link EpicWorkMeter}): graph builds, edge-driver
+ * lookups, merge pair scans and every dry run are charged their
+ * deterministic cost; when the meter runs out the remaining candidates are
+ * skipped (`truncated`).
+ */
+import type { PlanTask as PartitionTask } from '../turbo/lean/partition-common.js';
+import { type EpicConflictGraph } from './components.js';
+import { type EpicPlanSizing, type EpicPlanSizingContext, type EpicScopeEstimate, type EpicShapingPhase } from './shaping-sizing.js';
+/** Hub rule: a file declared by at least this many tasks… */
+export declare const HUB_MIN_TASKS = 3;
+/** …driving at least this share of the plan's conflict edges… */
+export declare const HUB_MIN_EDGE_SHARE = 0.25;
+/** …or whose extraction gains at least this much S_eff. */
+export declare const HUB_MIN_DELTA = 0.25;
+/** Merge rule: scope Jaccard similarity at least this. */
+export declare const MERGE_MIN_JACCARD = 0.8;
+/** Deterministic work meter (units ≈ path comparisons, `epicWaveWork`). */
+export declare class EpicWorkMeter {
+    readonly max: number;
+    spent: number;
+    truncated: boolean;
+    constructor(max: number);
+    get left(): number;
+    /** Spend `cost` if it fits; otherwise mark the meter truncated. */
+    charge(cost: number): boolean;
+}
+/** What a suggestion would do to the sizing (the changed plan's sizing). */
+export interface EpicShapingWhatIf {
+    effectiveSpeedup: number;
+    serialSteps: number;
+    pendingTasks: number;
+    epicSized: boolean;
+}
+/** One task edit of a patch; the resulting fields are complete. */
+export interface EpicShapingTaskEdit {
+    taskId: string;
+    /** The task's complete `depends` after the edit. */
+    depends: string[];
+    /** The task's complete `files_touched` after the edit (when changed). */
+    files_touched?: string[];
+    /** Delta view of the same edit (extract / isolate). */
+    remove_files?: string[];
+    add_depends?: string[];
+}
+export interface EpicShapingNewTask {
+    id: string;
+    phase: number;
+    description: string;
+    files_touched: string[];
+    depends: string[];
+}
+/** extract-prerequisite / isolate-hot-file: add `newTask`, apply `edits`. */
+export interface EpicShapingPatch {
+    newTask: EpicShapingNewTask;
+    edits: EpicShapingTaskEdit[];
+}
+interface SuggestionBase {
+    summary: string;
+    /** ΔS_eff of the what-if (null: not computable — scope advice). */
+    deltaEffectiveSpeedup: number | null;
+    whatIf: EpicShapingWhatIf | null;
+}
+export type EpicShapingSuggestion = (SuggestionBase & {
+    type: 'declare-scope';
+    taskIds: string[];
+    count: number;
+}) | (SuggestionBase & {
+    type: 'narrow-scope';
+    phase: number;
+    /** The directory entry that conflicts with every task under it. */
+    entry: string;
+    taskIds: string[];
+}) | (SuggestionBase & {
+    type: 'extract-prerequisite' | 'isolate-hot-file';
+    phase: number;
+    file: string;
+    fileKind: 'global-file' | 'hot-file' | 'hub-file';
+    taskIds: string[];
+    edgeShare: number;
+    patch: EpicShapingPatch;
+}) | (SuggestionBase & {
+    type: 'split-task';
+    phase: number;
+    taskId: string;
+    /** One file set per part (part 1 keeps the task id). */
+    parts: string[][];
+    patch: {
+        newTasks: EpicShapingNewTask[];
+        edits: EpicShapingTaskEdit[];
+    };
+}) | (SuggestionBase & {
+    type: 'merge-tasks';
+    phase: number;
+    keep: string;
+    absorb: string;
+    jaccard: number;
+    patch: {
+        removed_task_ids: string[];
+        removal_reason: string;
+        edits: EpicShapingTaskEdit[];
+    };
+});
+/** Everything a builder needs about the baseline. */
+export interface ShapingBase {
+    context: EpicPlanSizingContext;
+    phases: readonly EpicShapingPhase[];
+    estimate: EpicScopeEstimate;
+    sizing: EpicPlanSizing;
+    hot: ReadonlySet<string>;
+    /** Every task id of the plan, any status (new ids must be unused). */
+    usedIds: ReadonlySet<string>;
+    /** Task id → depends, every task of the plan. */
+    dependsOf: ReadonlyMap<string, readonly string[]>;
+    /** Task id → the tasks that depend on it, every task of the plan. */
+    dependents: ReadonlyMap<string, readonly string[]>;
+    /** Optional on-disk directory check for scope entries (no-extension names). */
+    isDirectory?: (entry: string) => boolean;
+    meter: EpicWorkMeter;
+}
+/** Next unused `<phase>.<n>` task id (and reserve it in `taken`). */
+export declare function nextTaskId(phaseId: number, taken: Set<string>): string;
+/** Does `from` (transitively, through `depends`) depend on `target`? */
+export declare function dependsOnTransitively(base: ShapingBase, from: string, target: string): boolean;
+export interface PhaseModel {
+    phase: EpicShapingPhase;
+    tasks: PartitionTask[];
+    graph: EpicConflictGraph;
+    edgeCount: number;
+    /** File → edges it drives (path overlaps; the shorter path drives). */
+    driven: Map<string, number>;
+    /** File → tasks it makes exclusive (global / hot). */
+    exclusiveCaused: Map<string, number>;
+}
+/** Model one phase, or null (no pending task, or out of budget). */
+export declare function modelPhase(base: ShapingBase, phase: EpicShapingPhase): PhaseModel | null;
+/**
+ * A scope entry that names a directory: a trailing separator, a prefix of
+ * another scope path of the plan, or (no extension) a directory on disk
+ * when the caller can check — without a checker a name without an
+ * extension counts as a directory.
+ */
+export declare function isDirectoryEntry(base: ShapingBase, entry: string, rawEntries: readonly string[], allPaths: ReadonlySet<string>): boolean;
+export declare function narrowScopeSuggestion(phase: EpicShapingPhase, entry: string, taskIds: string[]): EpicShapingSuggestion;
+export declare function fileSuggestion(base: ShapingBase, model: PhaseModel, file: string, totalEdges: number): EpicShapingSuggestion | null;
+/** Articulation points of the non-exclusive conflict graph (Tarjan). */
+export declare function articulationPoints(graph: EpicConflictGraph): string[];
+export declare function splitSuggestion(base: ShapingBase, model: PhaseModel, taskId: string): EpicShapingSuggestion | null;
+export declare function jaccard(a: ReadonlySet<string>, b: ReadonlySet<string>): number;
+/**
+ * Merge `absorb` into `keep`. Skipped when one reaches the other through
+ * another task (the merged task would depend on itself); a direct
+ * dependency between them is fine (it disappears).
+ */
+export declare function mergeSuggestion(base: ShapingBase, phase: EpicShapingPhase, keep: PartitionTask, absorb: PartitionTask, similarity: number): EpicShapingSuggestion | null;
+/** Every task of the plan: id → depends, and id → dependents. */
+export declare function dependencyIndex(phases: readonly EpicShapingPhase[]): {
+    dependsOf: Map<string, readonly string[]>;
+    dependents: Map<string, string[]>;
+};
+export {};

package/dist/epic/shaping.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Epic v2 C7 — plan shaping (pure).
+ *
+ * Tells the architect HOW a plan could run better as an epic, with the same
+ * model `/swarm epic start` sizes it with (`shaping-sizing.ts`: a dry run
+ * of the component planner, `components.ts`, then `sizing.ts`):
+ *
+ *   1. baseline: the plan's sizing (T, C, L, S_eff) — passed in by
+ *      `/swarm epic start` (its own sizing), computed otherwise;
+ *   2. the conflict graph of each phase and the files DRIVING its edges (a
+ *      path overlap between two expanded scopes is driven by the shorter
+ *      path); edge share = edges a file drives / all edges of the plan;
+ *      global/hot files also count the tasks they make exclusive;
+ *   3. what-ifs (`shaping-suggestions.ts`): each suggestion is a concrete
+ *      save_plan patch, applied to its phase and dry-run again → ΔS_eff;
+ *      a patch that would leave more tasks unschedulable (a cycle) is
+ *      rejected;
+ *   4. suggestions, capped at {@link MAX_SHAPING_SUGGESTIONS}: scope advice
+ *      first — `declare-scope` (tasks with no scope run alone) and
+ *      `narrow-scope` (a directory entry driving conflicts: it cannot be
+ *      extracted) — then by ΔS_eff: `extract-prerequisite` (a hub file of
+ *      ≥ 3 tasks with edge share ≥ 0.25 or ΔS_eff ≥ 0.25 moved into a new
+ *      prerequisite task), `isolate-hot-file` (a learned hot file of fewer
+ *      tasks, same patch), `split-task` (an articulation task, one part per
+ *      cluster), `merge-tasks` (two small tasks with scope Jaccard ≥ 0.8;
+ *      offered at ΔS_eff ≥ 0 — they serialize anyway and one task saves a
+ *      QA cycle).
+ *
+ * Verdicts: `acceptable` (epic-sized; nothing worth changing),
+ * `improvable` (a suggestion makes the plan epic-sized, improves an
+ * epic-sized plan by ≥ {@link MIN_USEFUL_DELTA}, or scope advice applies),
+ * `not-epic-sized` (no suggestion makes it epic-sized — run it in Balanced),
+ * `skipped-budget` (over {@link MAX_SHAPING_TASKS} pending tasks or
+ * {@link MAX_SHAPING_FILES} distinct scope files, or the baseline did not
+ * fit the work budget, or no what-if did).
+ *
+ * Bounded by WORK, not by a clock: one {@link MAX_SHAPING_WORK} meter
+ * (deterministic units ≈ path comparisons, `epicWaveWork`) is charged for
+ * the baseline dry runs (each step before it runs), the graph builds, the
+ * edge-driver lookups, the merge pair scan and every what-if dry run; when
+ * it runs out the rest is skipped. Calibrated so the worst plan within the
+ * caps adds ≈ 0.3 s to a save_plan on a laptop. A synchronous computation
+ * cannot be interrupted by a timeout (`withTimeout` would only stop
+ * waiting), so there is no timeout verdict — the budget is the bound.
+ *
+ * Analysis only: nothing here is write authorization or plan state.
+ */
+import { type EpicPlanSizing, type EpicPlanSizingContext, type EpicShapingPhase } from './shaping-sizing.js';
+import { type EpicShapingSuggestion } from './shaping-suggestions.js';
+import { type EpicSizingVerdict } from './sizing.js';
+/** Plans with more pending tasks are not shaped (`skipped-budget`). */
+export declare const MAX_SHAPING_TASKS = 200;
+/** Plans whose pending scopes name more distinct files are not shaped. */
+export declare const MAX_SHAPING_FILES = 500;
+/** File what-ifs (extract / isolate), top candidates only. */
+export declare const MAX_WHAT_IF_FILES = 10;
+/** Split-task what-ifs (articulation tasks, highest degree first). */
+export declare const MAX_WHAT_IF_SPLITS = 3;
+/** Merge-tasks what-ifs (highest Jaccard first). */
+export declare const MAX_WHAT_IF_MERGES = 3;
+/**
+ * Work units for one whole shaping (baseline + analysis + what-ifs) — the
+ * save_plan latency bound (see the module header).
+ */
+export declare const MAX_SHAPING_WORK = 6000000;
+/** Suggestions returned. */
+export declare const MAX_SHAPING_SUGGESTIONS = 5;
+/** An epic-sized plan is `improvable` only for a gain at least this. */
+export declare const MIN_USEFUL_DELTA = 0.05;
+export type EpicShapingVerdictKind = 'acceptable' | 'improvable' | 'not-epic-sized' | 'skipped-budget';
+export interface EpicShapingReport {
+    verdict: EpicShapingVerdictKind;
+    /** Baseline sizing (null when it was not (fully) computed). */
+    sizing: EpicSizingVerdict | null;
+    suggestions: EpicShapingSuggestion[];
+    budget: {
+        tasks: number;
+        files: number;
+        maxTasks: number;
+        maxFiles: number;
+        whatIfs: number;
+        /** Work units spent and the allowance. */
+        work: number;
+        maxWork: number;
+        /** Something was skipped because the work budget ran out. */
+        truncated: boolean;
+    };
+}
+export interface EpicShapingInput extends EpicPlanSizingContext {
+    phases: readonly EpicShapingPhase[];
+    /** Live declared scope per task id (`[]`/absent ⇒ `files_touched`). */
+    declared: Readonly<Record<string, readonly string[]>>;
+    /**
+     * The caller's own sizing of this plan with these inputs (the start's) —
+     * reused instead of a second baseline. An aborted one ⇒ skipped-budget.
+     */
+    baseline?: EpicPlanSizing;
+    /** On-disk directory check for no-extension scope entries (optional). */
+    isDirectory?: (entry: string) => boolean;
+    /** Work allowance (default {@link MAX_SHAPING_WORK}). */
+    maxWork?: number;
+}
+/** Shape one plan (see the module header). */
+export declare function shapeEpicPlan(input: EpicShapingInput): EpicShapingReport;
+/** Why shaping was skipped (`skipped-budget`). */
+export declare function describeEpicShapingSkip(report: EpicShapingReport): string;
+/** `<reason>; <reason>` — the sizing reasons as one line. */
+export declare function describeEpicShapingReasons(sizing: EpicSizingVerdict): string;
+/** Markdown lines of the advisory (`/swarm coupling --suggest`, start). */
+export declare function formatEpicShapingLines(report: EpicShapingReport, options?: {
+    maxSuggestions?: number;
+}): string[];

package/dist/epic/sizing.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Epic sizing (Epic v2 C1a) — pure.
+ *
+ * Decides whether a plan is worth running as an epic. Inputs are counted by
+ * the caller (`src/epic/start.ts`):
+ *   T  = pending tasks (status ∉ {completed, closed}) across the plan
+ *   C  = pending tasks with a non-empty scope (live declared scope, else
+ *        `files_touched`)
+ *   L  = serial steps of a dry-run of the Epic component planner
+ *        (`components.ts`) over every phase with pending tasks (waves + tasks
+ *        it can never schedule), under the epic's own wave-width cap
+ *
+ *   coverage = C / T,  S = T / L,  S_eff = 1 / ((1 − c) + c / S)   (Amdahl)
+ *
+ * where c = `epic.sizing.coder_fraction` is the share of a task's
+ * wall-clock that parallel coders actually overlap (Stage A/B QA and the
+ * architect's turns stay serial). Epic-sized ⇔ T ≥ min_tasks ∧
+ * coverage ≥ min_scope_coverage ∧ S_eff ≥ min_effective_speedup.
+ */
+/** Resolved thresholds (config keys `epic.sizing.*`). */
+export interface EpicSizingThresholds {
+    minTasks: number;
+    minScopeCoverage: number;
+    minEffectiveSpeedup: number;
+    coderFraction: number;
+}
+export declare const DEFAULT_EPIC_SIZING_THRESHOLDS: EpicSizingThresholds;
+export type EpicSizingReason = 'too-few-tasks' | 'insufficient-scope-coverage' | 'insufficient-parallelism';
+export interface EpicSizingInput {
+    pendingTasks: number;
+    scopedTasks: number;
+    serialSteps: number;
+}
+export interface EpicSizingVerdict {
+    epicSized: boolean;
+    reasons: EpicSizingReason[];
+    pendingTasks: number;
+    scopedTasks: number;
+    scopeCoverage: number;
+    serialSteps: number;
+    /** Raw concurrency S = T / L (1 when L = 0). */
+    concurrency: number;
+    /** Amdahl-adjusted speedup S_eff. */
+    effectiveSpeedup: number;
+    thresholds: EpicSizingThresholds;
+}
+/** S_eff = 1 / ((1 − c) + c / S). S ≤ 1 or c ≤ 0 ⇒ 1. */
+export declare function computeEffectiveSpeedup(concurrency: number, coderFraction: number): number;
+/** Config view consumed by {@link resolveEpicSizingThresholds}. */
+export interface EpicSizingConfigView {
+    min_tasks?: number;
+    min_scope_coverage?: number;
+    min_effective_speedup?: number;
+    coder_fraction?: number;
+}
+export declare function resolveEpicSizingThresholds(sizing: EpicSizingConfigView | undefined): EpicSizingThresholds;
+export declare function evaluateEpicSizing(input: EpicSizingInput, thresholds?: EpicSizingThresholds): EpicSizingVerdict;
+export declare function describeEpicSizingReason(reason: EpicSizingReason, verdict: EpicSizingVerdict): string;
+/** One-line summary for start/status/report output. */
+export declare function summarizeEpicSizing(verdict: EpicSizingVerdict): string;