@cleocode/contracts 2026.5.122 → 2026.5.123

package/dist/operations/tasks.d.ts

@@ -26,7 +26,7 @@ import type { TaskStatus } from '../status-registry.js';
 import type { TaskPriority, TaskType } from '../task.js';
 import type { TaskRecord } from '../task-record.js';
 import type { ExternalTask, ExternalTaskLink, ReconcileResult } from '../task-sync.js';
-import type { TaskComplexityFactor, TaskDependsResult, TaskLabelInfo, TaskPlanResult, TaskTreeNode, TaskView } from '../tasks.js';
+import type { CompletionEvaluateParams, CompletionEvaluateResult, CompletionExplainParams, CompletionExplainResult, CompletionListParams, CompletionListResult, CompletionProjectionRepairParams, CompletionProjectionRepairResult, TaskComplexityFactor, TaskDependsResult, TaskLabelInfo, TaskMutationDryRunSummary, TaskMutationEnvelope, TaskMutationWarning, TaskPlanResult, TaskTreeNode, TaskView } from '../tasks.js';
 import type { DocsType } from './docs.js';
 import type { JsonSchema, OperationInputContract } from './input-contract.js';
 export type { TaskPriority, TaskStatus };
@@ -165,6 +165,8 @@ export interface TasksShowParams {
     history?: boolean;
     /** When true, include IVTR phase history. */
     ivtrHistory?: boolean;
+    /** When true, include expanded relation/doc ID lists alongside compact counts. */
+    relations?: boolean;
 }
 /**
  * Minimal attachment entry surfaced in the `tasks.show` envelope.
@@ -192,6 +194,27 @@ export interface TaskShowAttachmentEntry {
     /** Storage kind — discriminant for the full attachment variant. */
     kind: string;
 }
+export interface TaskShowRelationsEntry {
+    /** Direct dependency IDs. */
+    depends: string[];
+    /** Explicit blockedBy entries from the task record. */
+    blockedBy: string[];
+    /** Non-dependency task relation links. */
+    relates: Array<{
+        taskId: string;
+        type: string;
+        reason?: string;
+    }>;
+    /** Direct child task IDs. */
+    children: string[];
+    /** Linked docs attachment IDs/slugs. */
+    docs: Array<{
+        attachmentId: string;
+        slug?: string;
+        type?: DocsType;
+        kind: string;
+    }>;
+}
 /**
  * Result of `tasks.show` — the full task record plus its canonical view
  * projection. `view` is null when the task has no lifecycle pipeline.
@@ -227,6 +250,8 @@ export interface TasksShowResult {
      * @epic T10381
      */
     acRows?: TaskShowAcRowEntry[];
+    /** Expanded relation/doc lists returned only when `cleo show --relations` is requested. */
+    relations?: TaskShowRelationsEntry;
 }
 /**
  * One acceptance-criterion entry in {@link TasksShowResult.acRows}.
@@ -308,6 +333,48 @@ export interface TasksDependsParams {
  * @task T1703
  */
 export type TasksDependsResult = TaskDependsResult;
+/** Localized task/workgraph node returned by `tasks.slice`. */
+export interface TasksSliceNode {
+    id: string;
+    title: string;
+    status: TaskStatus;
+    type?: TaskType;
+    priority?: TaskPriority;
+    /** Canonical wire field for parent task ID (ADR-057 D2). */
+    parent?: string;
+    children: string[];
+    depends: string[];
+    dependents: string[];
+    depth: number;
+}
+/** Params for `tasks.slice` — fixed-radius local WorkGraph context around a task. */
+export interface TasksSliceParams {
+    taskId: string;
+    /** Slice direction. `around` returns upstream, downstream, and siblings. Defaults to `around`. */
+    direction?: 'upstream' | 'downstream' | 'around';
+    /** Back-compat alias for dependency traversal depth. */
+    radius?: number;
+    /** Dependency traversal depth for upstream/downstream. Defaults to 1. */
+    depth?: number;
+    /** Maximum nodes per returned section. Defaults to unbounded. */
+    budget?: number;
+    /** Include direct non-dependency `relates` neighbors in a `related` bucket. */
+    includeRelates?: boolean;
+}
+/** Result of `tasks.slice` — center task, deps, dependents, siblings, and optional relations. */
+export interface TasksSliceResult {
+    taskId: string;
+    direction: 'upstream' | 'downstream' | 'around';
+    depth: number;
+    radius: number;
+    budget?: number;
+    includeRelates: boolean;
+    center: TasksSliceNode;
+    upstream: TasksSliceNode[];
+    downstream: TasksSliceNode[];
+    siblings: TasksSliceNode[];
+    related?: TasksSliceNode[];
+}
 export interface TasksAnalyzeQueryParams {
     taskId?: string;
     tierLimit?: number;
@@ -323,6 +390,196 @@ export interface TasksAnalyzeQueryParams {
 export type TasksAnalyzeQueryResult = TaskAnalysisResult & {
     tierLimit: number;
 };
+/** Params for `tasks.context` — bounded task context pack. */
+export interface TasksContextParams {
+    /** Task ID to build context for. */
+    taskId: string;
+    /**
+     * Scope mode: `saga` resolves member-epic rollup + ready frontier across
+     * all members; `epic` resolves child-task rollup + ready frontier for the
+     * epic. When omitted or `undefined`, behaves as a single-task context pack
+     * (T10629 baseline). @defaultValue undefined (task-only)
+     */
+    scope?: 'saga' | 'epic';
+    /** Maximum token budget for the returned pack. @defaultValue 1500 */
+    budgetTokens?: number;
+    /** Include acceptance criteria in the pack. @defaultValue true */
+    includeAcceptance?: boolean;
+    /** Include blocker summary in the pack. @defaultValue true */
+    includeBlockers?: boolean;
+    /** Include attached docs in the pack. @defaultValue true */
+    includeDocs?: boolean;
+    /** Include graph edges (upstream/downstream/siblings/related) in the pack. @defaultValue true */
+    includeEdges?: boolean;
+    /** Include recent activity (audit log) in the pack. @defaultValue true */
+    includeActivity?: boolean;
+    /** Maximum number of recent activity events. @defaultValue 10 */
+    activityLimit?: number;
+    /** Maximum depth for graph edges when includeEdges is true. @defaultValue 1 */
+    edgeDepth?: number;
+}
+/** A single omitted section with reason and count. */
+export interface TasksContextOmission {
+    /** Section path that was omitted (e.g. "acceptance", "blockers", "docs", "edges.upstream", "activity"). */
+    path: string;
+    /** Reason for omission. */
+    reason: 'budget_exceeded' | 'not_requested' | 'not_available';
+    /** Human-readable explanation. */
+    message: string;
+    /** Number of items omitted, when countable. */
+    count?: number;
+    /**
+     * CLI command to expand this section, when an expansion path exists
+     * (e.g. `"cleo orchestrate ready T10547"`, `"cleo saga rollup T10538"`).
+     * @task T10630
+     */
+    expansionCommand?: string;
+}
+/** Budget accounting for a task context pack. */
+export interface TasksContextBudget {
+    /** Caller-provided token budget. */
+    tokenBudget: number;
+    /** Estimated tokens consumed by the returned payload. */
+    estimatedTokens: number;
+    /** Remaining tokens after payload selection. */
+    remainingTokens: number;
+    /** True when one or more sections were truncated or omitted. */
+    truncated: boolean;
+}
+/** Single AC entry in the context pack. */
+export interface TasksContextAcceptanceEntry {
+    /** AC alias (e.g. "AC1") or UUID. */
+    alias: string;
+    /** Full acceptance criterion text. */
+    text: string;
+    /** Whether this AC has evidence bindings. */
+    hasEvidence?: boolean;
+}
+/** Single blocker entry in the context pack. */
+export interface TasksContextBlockerEntry {
+    /** Blocking task ID. */
+    taskId: string;
+    /** Title of the blocking task. */
+    title: string;
+    /** Status of the blocking task. */
+    status: string;
+    /** Blocker kind: dependency or gate. */
+    kind: 'dependency' | 'gate';
+}
+/** Single doc entry in the context pack. */
+export interface TasksContextDocEntry {
+    /** Doc slug or attachment identifier. */
+    slug: string;
+    /** Doc type. */
+    type: string;
+    /** Human-readable title or description. */
+    title: string;
+}
+/** Single activity event in the context pack. */
+export interface TasksContextActivityEvent {
+    /** ISO timestamp. */
+    timestamp: string;
+    /** Action type. */
+    action: string;
+    /** Actor who performed the action. */
+    actor?: string;
+    /** Free-form details. */
+    details?: string;
+}
+/**
+ * Rollup summary for a saga or epic scope.
+ * @task T10630
+ */
+export interface TasksScopeRollup {
+    /** Total number of member epics (saga) or child tasks (epic). */
+    total: number;
+    done: number;
+    active: number;
+    blocked: number;
+    pending: number;
+    /** Completion percentage (0–100). */
+    completionPct: number;
+}
+/**
+ * A single member epic entry in a saga context pack.
+ * @task T10630
+ */
+export interface TasksScopeMember {
+    /** Epic task ID. */
+    epicId: string;
+    /** Epic title. */
+    title: string;
+    /** Current status. */
+    status: string;
+}
+/**
+ * A single ready-frontier entry in a saga/epic context pack.
+ * @task T10630
+ */
+export interface TasksScopeReadyEntry {
+    /** Task ID that is ready to execute. */
+    id: string;
+    /** Task title. */
+    title: string;
+    /** Priority level. */
+    priority: string;
+    /** Declared dependency IDs. */
+    depends: string[];
+}
+/** Result of `tasks.context` — bounded task context pack with omission tracking. */
+export interface TasksContextResult {
+    /** Task ID this pack describes. */
+    taskId: string;
+    /** ISO timestamp when the pack was generated. */
+    generatedAt: string;
+    /** Budget accounting. */
+    budget: TasksContextBudget;
+    /** Task identity (title, status, type, priority, description). */
+    identity: {
+        id: string;
+        title: string;
+        status: string;
+        type?: string;
+        priority?: string;
+        description?: string;
+        parentId?: string | null;
+    };
+    /** Acceptance criteria, when requested and within budget. */
+    acceptance?: TasksContextAcceptanceEntry[];
+    /** Blockers, when requested and within budget. */
+    blockers?: TasksContextBlockerEntry[];
+    /** Attached docs, when requested and within budget. */
+    docs?: TasksContextDocEntry[];
+    /** Graph edges, when requested and within budget. */
+    edges?: {
+        upstream: TasksSliceNode[];
+        downstream: TasksSliceNode[];
+        siblings: TasksSliceNode[];
+        related?: TasksSliceNode[];
+    };
+    /** Recent activity events, when requested and within budget. */
+    activity?: TasksContextActivityEvent[];
+    /**
+     * Saga/epic rollup summary — present when `scope` is `'saga'` or
+     * `'epic'` and rollup data is available. @task T10630
+     */
+    rollup?: TasksScopeRollup;
+    /**
+     * Saga member epics — present when `scope` is `'saga'` and member data
+     * is available. @task T10630
+     */
+    members?: TasksScopeMember[];
+    /**
+     * Ready frontier — parallel-safe tasks that can be dispatched now.
+     * Present when `scope` is `'saga'` or `'epic'` and ready data is
+     * available. @task T10630
+     */
+    readyFrontier?: TasksScopeReadyEntry[];
+    /** Omitted/truncated sections with reasons and counts. */
+    omissions: TasksContextOmission[];
+    /** Expansion hints for omitted sections. */
+    expansionHints: Record<string, string>;
+}
 /**
  * Parameters for `tasks.deps.validate`.
  *
@@ -466,6 +723,12 @@ export interface TasksRelatesParams {
     taskId: string;
     mode?: 'suggest' | 'discover';
     threshold?: number;
+    /** List edges where taskId is the source, target, or either side. Defaults to both. */
+    direction?: 'out' | 'in' | 'both';
+    /** Filter by relation type, or `depends`/`depends_on` for dependency edges. */
+    type?: string;
+    /** Include scheduler dependency edges in list output. Defaults to true. */
+    includeDependencies?: boolean;
 }
 /**
  * Result of `tasks.relates` — task relations list.
@@ -480,10 +743,52 @@ export interface TasksRelatesResult {
         taskId: string;
         type: string;
         reason?: string;
+        direction?: 'out' | 'in';
+        source?: 'relation' | 'dependency';
+        ready?: boolean;
+        status?: string;
     }>;
+    /** Direction filter applied by list output. */
+    direction?: 'out' | 'in' | 'both';
     /** Total number of relations. */
     count: number;
 }
+export interface TasksRelatesAddBatchEntry {
+    taskId?: string;
+    from?: string;
+    relatedId?: string;
+    to?: string;
+    type: string;
+    reason?: string;
+}
+export interface TasksRelatesAddBatchParams {
+    relations?: TasksRelatesAddBatchEntry[];
+    edges?: TasksRelatesAddBatchEntry[];
+    dryRun?: boolean;
+    reasonWaiver?: string;
+}
+export interface TasksRelatesAddBatchResult {
+    dryRun: boolean;
+    validatedCount: number;
+    created: number;
+    wouldCreate: number;
+    relations: Array<{
+        from: string;
+        to: string;
+        type: string;
+        reason?: string;
+        waivedReason?: boolean;
+    }>;
+    warnings: Array<{
+        code: string;
+        message: string;
+        edge?: {
+            from: string;
+            to: string;
+            type: string;
+        };
+    }>;
+}
 export interface TasksComplexityEstimateParams {
     taskId: string;
 }
@@ -578,6 +883,14 @@ export interface TasksSyncLinksRemoveResult {
 export interface TasksCancelParams {
     taskId: string;
     reason?: string;
+    /** Explicit child handling mode. Defaults to 'block' so propagation is never implicit. */
+    children?: 'block' | 'cascade' | 'orphan';
+    /** Operator waiver for large cascade cancellation. */
+    force?: boolean;
+    /** Large-subtree cascade guard threshold. Defaults to 10 descendants. */
+    cascadeThreshold?: number;
+    /** Config-level cascade permission. Defaults to true. */
+    allowCascade?: boolean;
 }
 /**
  * Result of `tasks.cancel` — cancellation confirmation.
@@ -602,6 +915,12 @@ export interface TasksCancelResult {
      * @defaultValue undefined
      */
     alreadyCancelled?: boolean;
+    /** Explicit child handling mode applied by the operation. */
+    childStrategy?: 'block' | 'cascade' | 'orphan';
+    /** Child or descendant tasks affected by cascade/orphan handling. */
+    affectedTasks?: string[];
+    /** Count of affected child/descendant tasks. */
+    affectedCount?: number;
 }
 export interface TasksRestoreParams {
     taskId: string;
@@ -688,6 +1007,58 @@ export interface TasksRelatesAddResult {
     /** Whether the relation was newly created (false if it already existed). */
     added: boolean;
 }
+export interface TasksRelatesAddBatchEntry {
+    /** Source task ID. */
+    taskId?: string;
+    /** Source task ID alias accepted by file payloads. */
+    from?: string;
+    /** Target task ID. */
+    relatedId?: string;
+    /** Target task ID alias accepted by file payloads. */
+    to?: string;
+    /** Relation type: related|blocks|duplicates|absorbs|fixes|extends|supersedes|groups. */
+    type: string;
+    /** Audit reason for creating this advisory relation. Required unless reasonWaiver is set. */
+    reason?: string;
+}
+export interface TasksRelatesAddBatchParams {
+    /** Relation edges to add atomically. */
+    relations?: TasksRelatesAddBatchEntry[];
+    /** Relation edges alias for WorkGraph-flavored callers. */
+    edges?: TasksRelatesAddBatchEntry[];
+    /** Validate and report without writing. */
+    dryRun?: boolean;
+    /** Explicit reason-waiver text applied to any edge missing an edge-level reason. */
+    reasonWaiver?: string;
+}
+export interface TasksRelatesAddBatchResult {
+    /** Whether this dispatch only previewed writes. */
+    dryRun: boolean;
+    /** Validated relation count. */
+    validatedCount: number;
+    /** Number of relation rows inserted or previewed. */
+    created: number;
+    /** Dry-run prediction of rows that would be inserted. */
+    wouldCreate: number;
+    /** Accepted normalized relation edges. */
+    relations: Array<{
+        from: string;
+        to: string;
+        type: string;
+        reason?: string;
+        waivedReason?: boolean;
+    }>;
+    /** Non-fatal audit notes, including explicit missing-reason waivers. */
+    warnings: Array<{
+        code: string;
+        message: string;
+        edge?: {
+            from: string;
+            to: string;
+            type: string;
+        };
+    }>;
+}
 export interface TasksRelatesRemoveParams {
     /** Source task ID. */
     taskId: string;
@@ -754,14 +1125,71 @@ export interface TasksAddBatchParams {
  * Result of `tasks.add-batch`.
  *
  * @task T9814
+ * @task T10599 (dry-run semantics: wouldCreate, wouldAffect, validatedCount, insertedCount, validationFindings)
  */
-export interface TasksAddBatchResult {
+export interface TasksAddBatchResult extends TaskMutationEnvelope<number, [], []> {
     /** Number of tasks actually created (0 on rollback or dry-run). */
     created: number;
     /** Per-task results in input order. */
     tasks: TasksAddResult[];
     /** Whether this was a dry run. */
     dryRun?: boolean;
+    /**
+     * Number of tasks that would be created if the dry run were executed for real.
+     * Only present when `dryRun` is `true`. Use this for `--output count` in
+     * dry-run mode — `created` is always 0 in a dry run.
+     *
+     * @task T10599
+     */
+    wouldCreate?: number;
+    /**
+     * Generic number of rows/entities that would be affected by the dry-run operation.
+     * For `tasks.add-batch`, this equals `wouldCreate`.
+     *
+     * @task T10599
+     */
+    wouldAffect?: number;
+    /**
+     * Number of task specs that successfully passed validation during a dry run.
+     * Always equals `wouldCreate` when no validation errors occurred; may be less
+     * when partial validation failures are tolerated.
+     *
+     * @task T10599
+     */
+    validatedCount?: number;
+    /**
+     * Number of tasks durably written to the database.
+     * - Live run: equals `created`.
+     * - Dry run: always `0` (no writes performed).
+     *
+     * Kept separate from `created` so callers can distinguish "batch was a
+     * dry run with 0 writes" from "batch was live but created nothing due to
+     * rollback/validation failure".
+     *
+     * @task T10599
+     */
+    insertedCount?: number;
+    /**
+     * Per-task non-blocking validation warnings emitted during a dry run.
+     * Only present when at least one task spec produced a warning.
+     * Index matches the position of the spec in the `tasks` input array.
+     *
+     * @task T10599
+     */
+    validationFindings?: Array<{
+        index: number;
+        warnings: string[];
+    }>;
+    /** Standard dry-run/preflight projection shared by task mutations. @task T10608 */
+    dryRunSummary?: TaskMutationDryRunSummary;
+    /** Structured partial-success warnings, flattened across batch entries. @task T10608 */
+    mutationWarnings: TaskMutationWarning[];
+    /** Updated task records; empty for add-batch. @task T10608 */
+    updated: [];
+    /** Deleted task records; empty for add-batch. @task T10608 */
+    deleted: [];
+    /** Total number of live rows/entities affected. @task T10608 */
+    affectedCount: number;
 }
 export interface TasksAddParams {
     title: string;
@@ -799,7 +1227,7 @@ export interface TasksAddParams {
  *
  * @task T1703
  */
-export interface TasksAddResult {
+export interface TasksAddResult extends TaskMutationEnvelope<TaskRecord[], [], []> {
     /** The created task record. */
     task: TaskRecord;
     /** Whether a duplicate was detected (but bypassed via forceDuplicate). */
@@ -808,6 +1236,18 @@ export interface TasksAddResult {
     dryRun?: boolean;
     /** Non-blocking validation warnings. @defaultValue undefined */
     warnings?: string[];
+    /** Standardized created bucket; contains `task` on live create, empty on dry-run. @task T10608 */
+    created: TaskRecord[];
+    /** Standardized updated bucket; empty for create. @task T10608 */
+    updated: [];
+    /** Standardized deleted bucket; empty for create. @task T10608 */
+    deleted: [];
+    /** Total number of live rows/entities affected. @task T10608 */
+    affectedCount: number;
+    /** Structured partial-success/preflight warnings. @task T10608 */
+    mutationWarnings: TaskMutationWarning[];
+    /** Standard dry-run/preflight projection. @task T10608 */
+    dryRunSummary?: TaskMutationDryRunSummary;
 }
 export interface TasksUpdateQueryParams {
     taskId: string;
@@ -871,11 +1311,25 @@ export interface TasksUpdateQueryParams {
  *
  * @task T1703
  */
-export interface TasksUpdateQueryResult {
+export interface TasksUpdateQueryResult extends TaskMutationEnvelope<[], TaskRecord[], []> {
     /** Updated task record. */
     task: TaskRecord;
     /** Human-readable list of fields that were changed. @defaultValue undefined */
     changes?: string[];
+    /** Whether this was a dry run (no mutation persisted). @defaultValue undefined */
+    dryRun?: boolean;
+    /** Standardized created bucket; empty for update. @task T10608 */
+    created: [];
+    /** Standardized updated bucket; contains the updated task on live update, empty on dry-run. @task T10608 */
+    updated: TaskRecord[];
+    /** Standardized deleted bucket; empty for update. @task T10608 */
+    deleted: [];
+    /** Total number of live rows/entities affected. @task T10608 */
+    affectedCount: number;
+    /** Structured partial-success/preflight warnings. @task T10608 */
+    mutationWarnings: TaskMutationWarning[];
+    /** Standard dry-run/preflight projection. @task T10608 */
+    dryRunSummary?: TaskMutationDryRunSummary;
 }
 export interface TasksCompleteQueryParams {
     taskId: string;
@@ -934,13 +1388,25 @@ export interface TasksDeleteQueryParams {
  *
  * @task T1703
  */
-export interface TasksDeleteQueryResult {
+export interface TasksDeleteQueryResult extends TaskMutationEnvelope<[], [], boolean> {
     /** The deleted task record. */
     deletedTask: TaskRecord;
     /** Whether the deletion was applied (always true on success). */
     deleted: boolean;
     /** IDs of child tasks cascade-deleted along with the parent. @defaultValue undefined */
     cascadeDeleted?: string[];
+    /** Whether this was a dry run (no mutation persisted). @defaultValue undefined */
+    dryRun?: boolean;
+    /** Standardized created bucket; empty for delete. @task T10608 */
+    created: [];
+    /** Standardized updated bucket; empty for delete. @task T10608 */
+    updated: [];
+    /** Total number of live rows/entities affected. @task T10608 */
+    affectedCount: number;
+    /** Structured partial-success/preflight warnings. @task T10608 */
+    mutationWarnings: TaskMutationWarning[];
+    /** Standard dry-run/preflight projection. @task T10608 */
+    dryRunSummary?: TaskMutationDryRunSummary;
 }
 export interface TasksArchiveQueryParams {
     taskId?: string;
@@ -1023,6 +1489,8 @@ export interface TasksSagaCreateParams {
     description?: string;
     /** Pipe-separated acceptance criteria. */
     acceptance?: string[];
+    /** Validate and preview the Saga without writing rows. */
+    dryRun?: boolean;
 }
 /**
  * Result of `tasks.saga.create` — the newly created Saga task.
@@ -1031,12 +1499,22 @@ export interface TasksSagaCreateParams {
  * @task T9521
  */
 export interface TasksSagaCreateResult {
-    /** The created task record (type=epic, labels includes 'saga'). */
+    /** The created task record (type='saga'). */
     task: TaskRecord;
+    /** True when this is a validation-only preview. */
+    dryRun?: boolean;
+    /** Number of Saga tasks that would be created by a successful dry-run. */
+    wouldCreate?: number;
+    /** Generic affected-entity count for dry-run projection. */
+    wouldAffect?: number;
+    /** Number of Saga specs validated during dry-run preflight. */
+    validatedCount?: number;
+    /** Number of rows durably inserted; always 0 for dry-run. */
+    insertedCount?: number;
 }
 /** Params for `tasks.saga.add` — link an Epic to a Saga. */
 export interface TasksSagaAddParams {
-    /** Saga task ID (must have label='saga'). */
+    /** Saga task ID (must have type='saga'). */
     sagaId: string;
     /** Epic task ID to link as a member. */
     epicId: string;
@@ -1150,7 +1628,7 @@ export interface TasksSagaMembersResult {
  * @see ADR-073-above-epic-naming.md §1.2 — invariant I5
  */
 export interface TasksSagaRepairParams {
-    /** Saga task ID (must have `label='saga'`). */
+    /** Saga task ID (must have type='saga'). */
     sagaId: string;
 }
 /**
@@ -1177,6 +1655,70 @@ export interface TasksSagaRepairResult {
     /** Free-form notes the CLI renderer can surface alongside the result. */
     note?: string;
 }
+/**
+ * Params for `tasks.saga.migrate-containment` — migrate parent_id-based Saga
+ * membership to `task_relations.type='groups'` (ADR-073 §1.2 invariant I5).
+ *
+ * Converts Epics whose `parent_id` points to a `type='saga'` task into
+ * proper `groups` relations. Non-Epic tasks with Saga parents are documented
+ * as conflicts requiring manual resolution.
+ *
+ * @task T10637
+ * @see ADR-073-above-epic-naming.md §1.2 — invariant I5
+ */
+export interface TasksSagaMigrateContainmentParams {
+    /** Specific Saga ID to migrate. When omitted, migrates ALL sagas. */
+    sagaId?: string;
+    /** Dry-run mode: scan only, no mutations performed. */
+    dryRun?: boolean;
+}
+/**
+ * A single Epic that was migrated from parent_id to groups relation.
+ *
+ * @task T10637
+ */
+export interface TasksSagaMigratedEpic {
+    epicId: string;
+    sagaId: string;
+    oldParentId: string | null;
+    groupsRelation: {
+        from: string;
+        to: string;
+        type: 'groups';
+    };
+}
+/**
+ * A task (non-Epic) with a Saga parent — cannot be auto-migrated.
+ *
+ * @task T10637
+ */
+export interface TasksSagaContainmentConflict {
+    taskId: string;
+    sagaId: string;
+    taskType: string;
+    taskTitle: string;
+    reason: string;
+}
+/**
+ * Result of `tasks.saga.migrate-containment` — reports every Epic migrated
+ * and every non-Epic conflict that needs manual resolution.
+ *
+ * @task T10637
+ */
+export interface TasksSagaMigrateContainmentResult {
+    /** Total sagas scanned. */
+    sagasScanned: number;
+    /** Number of Epics successfully migrated. */
+    migrated: number;
+    /** Number of already-correct Epics skipped (idempotent no-op). */
+    skipped: number;
+    /** Detailed list of migrated Epics. */
+    migratedEpics: TasksSagaMigratedEpic[];
+    /** Non-Epic tasks with Saga parents — need manual resolution. */
+    conflicts: TasksSagaContainmentConflict[];
+    /** Whether this was a dry run (no mutations). */
+    dryRun: boolean;
+}
 /**
  * Per-saga reconciliation action returned by `tasks.saga.reconcile`.
  *
@@ -1195,7 +1737,7 @@ export type TasksSagaReconcileAction = 'close' | 'no-op' | 'blocked' | 'error';
 export interface TasksSagaReconcileParams {
     /**
      * Optional single saga to reconcile. When omitted, the verb walks every
-     * saga returned by `taskList({ type: 'epic', label: 'saga' })`.
+     * saga returned by `taskList({ type: 'saga' })`.
      */
     sagaId?: string;
     /**
@@ -1296,12 +1838,20 @@ export type TasksOps = {
     readonly tree: readonly [TasksTreeDispatchParams, TasksTreeDispatchResult];
     readonly blockers: readonly [TasksBlockersQueryParams, TasksBlockersQueryResult];
     readonly depends: readonly [TasksDependsParams, TasksDependsResult];
+    readonly slice: readonly [TasksSliceParams, TasksSliceResult];
     readonly 'deps.validate': readonly [TasksDepsValidateParams, TasksDepsValidateResult];
     readonly 'deps.tree': readonly [TasksDepsTreeParams, TasksDepsTreeResult];
     readonly analyze: readonly [TasksAnalyzeQueryParams, TasksAnalyzeQueryResult];
     readonly impact: readonly [TasksImpactParams, TasksImpactResult];
     readonly next: readonly [TasksNextQueryParams, TasksNextQueryResult];
     readonly plan: readonly [TasksPlanParams, TasksPlanResult];
+    readonly 'completion.list': readonly [CompletionListParams, CompletionListResult];
+    readonly 'completion.evaluate': readonly [CompletionEvaluateParams, CompletionEvaluateResult];
+    readonly 'completion.explain': readonly [CompletionExplainParams, CompletionExplainResult];
+    readonly 'projection.repair': readonly [
+        CompletionProjectionRepairParams,
+        CompletionProjectionRepairResult
+    ];
     readonly relates: readonly [TasksRelatesParams, TasksRelatesResult];
     readonly 'complexity.estimate': readonly [
         TasksComplexityEstimateParams,
@@ -1311,6 +1861,7 @@ export type TasksOps = {
     readonly current: readonly [TasksCurrentParams, TasksCurrentResult];
     readonly 'label.list': readonly [TasksLabelListParams, TasksLabelListResult];
     readonly 'sync.links': readonly [TasksSyncLinksParams, TasksSyncLinksResult];
+    readonly context: readonly [TasksContextParams, TasksContextResult];
     readonly add: readonly [TasksAddParams, TasksAddResult];
     readonly 'add-batch': readonly [TasksAddBatchParams, TasksAddBatchResult];
     readonly update: readonly [TasksUpdateQueryParams, TasksUpdateQueryResult];
@@ -1322,6 +1873,7 @@ export type TasksOps = {
     readonly reparent: readonly [TasksReparentQueryParams, TasksReparentDispatchResult];
     readonly reorder: readonly [TasksReorderQueryParams, TasksReorderDispatchResult];
     readonly 'relates.add': readonly [TasksRelatesAddParams, TasksRelatesAddResult];
+    readonly 'relates.add-batch': readonly [TasksRelatesAddBatchParams, TasksRelatesAddBatchResult];
     readonly 'relates.remove': readonly [TasksRelatesRemoveParams, TasksRelatesRemoveResult];
     readonly start: readonly [TasksStartQueryParams, TasksStartQueryResult];
     readonly stop: readonly [TasksStopQueryParams, TasksStopQueryResult];
@@ -1339,6 +1891,11 @@ export type TasksOps = {
     readonly 'saga.repair': readonly [TasksSagaRepairParams, TasksSagaRepairResult];
     /** T10121 — idempotent cron-safe auto-close repair (supersedes T10098 scope). */
     readonly 'saga.reconcile': readonly [TasksSagaReconcileParams, TasksSagaReconcileResult];
+    /** T10637 — migrate parent_id-based Saga membership to groups relations. */
+    readonly 'saga.migrate-containment': readonly [
+        TasksSagaMigrateContainmentParams,
+        TasksSagaMigrateContainmentResult
+    ];
 };
 /**
  * Per-task entry inside a `tasks.add-batch` payload.
@@ -1357,7 +1914,7 @@ export interface TasksAddBatchEntry {
     description?: string;
     /** Parent task ID (makes this task a subtask). */
     parent?: string;
-    /** Comma-separated dependency task IDs. */
+    /** Dependency task IDs as a JSON array. */
     depends?: string[];
     /** Task priority (low | medium | high | critical). */
     priority?: string;
@@ -1365,7 +1922,7 @@ export interface TasksAddBatchEntry {
     labels?: string[];
     /** Task type (saga | epic | task | subtask). */
     type?: TaskType;
-    /** Pipe-separated acceptance criteria, normalized to string[]. */
+    /** Acceptance criteria as a JSON array; pipe-delimited strings are not canonical. */
     acceptance?: string[];
     /** Phase slug to assign the task to. */
     phase?: string;