@cleocode/contracts 2026.5.121 → 2026.5.123

package/src/operations/tasks.ts

@@ -28,9 +28,20 @@ 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 {
+  CompletionEvaluateParams,
+  CompletionEvaluateResult,
+  CompletionExplainParams,
+  CompletionExplainResult,
+  CompletionListParams,
+  CompletionListResult,
+  CompletionProjectionRepairParams,
+  CompletionProjectionRepairResult,
   TaskComplexityFactor,
   TaskDependsResult,
   TaskLabelInfo,
+  TaskMutationDryRunSummary,
+  TaskMutationEnvelope,
+  TaskMutationWarning,
   TaskPlanResult,
   TaskTreeNode,
   TaskView,
@@ -179,13 +190,15 @@ export interface TasksCurrentResult {
   sessionId?: string;
 }
 
-// tasks.show (with optional history/ivtrHistory flags)
+// tasks.show (with optional history/ivtrHistory/relations flags)
 export interface TasksShowParams {
   taskId: string;
   /** When true, include task change history. */
   history?: boolean;
   /** When true, include IVTR phase history. */
   ivtrHistory?: boolean;
+  /** When true, include expanded relation/doc ID lists alongside compact counts. */
+  relations?: boolean;
 }
 
 /**
@@ -215,6 +228,19 @@ export interface TaskShowAttachmentEntry {
   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.
@@ -237,6 +263,40 @@ export interface TasksShowResult {
    * @task T9966
    */
   attachments: TaskShowAttachmentEntry[];
+  /**
+   * Acceptance-criterion rows hydrated from the `task_acceptance_criteria`
+   * table (T10502). Each entry carries the stable UUID `id`, the
+   * `AC<ordinal>` alias, the ordinal itself, and the canonical AC text.
+   *
+   * Optional — undefined when the task has no rows in the table (e.g.
+   * legacy tasks not yet backfilled by T10505). Consumers should fall
+   * back to `task.acceptance` (the legacy JSON string) in that case.
+   *
+   * @task T10508
+   * @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}.
+ *
+ * Mirrors the `AcDetail` shape from `@cleocode/core/tasks/show.js` but
+ * lives in contracts so dispatch-layer consumers don't depend on core.
+ *
+ * @task T10508
+ */
+export interface TaskShowAcRowEntry {
+  /** UUIDv4 stable identifier, immutable for the AC's lifetime. */
+  id: string;
+  /** Display alias derived from ordinal — `AC1`, `AC2`, etc. */
+  alias: string;
+  /** 1-based ordinal — never reused per task (gaps remain on shrink). */
+  ordinal: number;
+  /** The AC statement text. Structured gates round-trip as JSON. */
+  text: string;
 }
 
 // tasks.tree dispatch params (with optional withBlockers flag — dispatch alias)
@@ -303,6 +363,52 @@ export interface TasksDependsParams {
  */
 export type TasksDependsResult = TaskDependsResult;
 
+// tasks.slice
+/** 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[];
+}
+
 // tasks.analyze dispatch params (with optional taskId and tierLimit)
 export interface TasksAnalyzeQueryParams {
   taskId?: string;
@@ -318,6 +424,211 @@ export interface TasksAnalyzeQueryParams {
  */
 export type TasksAnalyzeQueryResult = TaskAnalysisResult & { tierLimit: number };
 
+// ---------------------------------------------------------------------------
+// tasks.context — Task-scoped context pack with token budget (T10629)
+// ---------------------------------------------------------------------------
+
+/** 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>;
+}
+
 // tasks.deps.validate
 /**
  * Parameters for `tasks.deps.validate`.
@@ -477,6 +788,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.
@@ -487,11 +804,55 @@ export interface TasksRelatesResult {
   /** The task ID whose relations were loaded. */
   taskId: string;
   /** All relations for this task. */
-  relations: Array<{ taskId: string; type: string; reason?: string }>;
+  relations: Array<{
+    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;
 }
 
+// tasks.relates.add-batch
+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 };
+  }>;
+}
+
 // tasks.complexity.estimate
 export interface TasksComplexityEstimateParams {
   taskId: string;
@@ -599,6 +960,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.
@@ -623,6 +992,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;
 }
 
 // tasks.restore (with from routing: done → reopen, archived → unarchive)
@@ -719,6 +1094,57 @@ export interface TasksRelatesAddResult {
   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 };
+  }>;
+}
+
 // tasks.relates.remove
 export interface TasksRelatesRemoveParams {
   /** Source task ID. */
@@ -789,14 +1215,68 @@ 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;
 }
 
 // tasks.add (dispatch-level params — extends TasksCreateParams)
@@ -836,7 +1316,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). */
@@ -845,6 +1325,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;
 }
 
 // tasks.update (dispatch-level params — extends TasksUpdateParams)
@@ -902,11 +1394,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;
 }
 
 // tasks.complete (dispatch-level params)
@@ -926,6 +1432,24 @@ export interface TasksCompleteQueryParams {
   overrideReason?: string;
   /** Reason for acknowledging CRITICAL nexus impact risk (bypasses nexusImpact gate). */
   acknowledgeRisk?: string;
+  /**
+   * Comma-separated AC tokens (UUIDs or `AC<n>` aliases) waived from the
+   * AC-coverage gate (T10509). MUST be paired with {@link waiveReason} —
+   * the gate rejects the call when one is set without the other.
+   *
+   * Waivers are recorded to `.cleo/audit/ac-waiver.jsonl` per ADR-079-r4 §4.
+   *
+   * @task T10509
+   * @saga T10377 (SG-IVTR-AC-BINDING)
+   */
+  waiveAc?: string;
+  /**
+   * Justification text for the {@link waiveAc} waiver. Mandatory whenever
+   * `waiveAc` is non-empty.
+   *
+   * @task T10509
+   */
+  waiveReason?: string;
 }
 /**
  * Result of `tasks.complete` — completion confirmation with unblocked tasks.
@@ -951,13 +1475,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;
 }
 
 // tasks.archive (dispatch-level params)
@@ -1053,6 +1589,8 @@ export interface TasksSagaCreateParams {
   description?: string;
   /** Pipe-separated acceptance criteria. */
   acceptance?: string[];
+  /** Validate and preview the Saga without writing rows. */
+  dryRun?: boolean;
 }
 
 /**
@@ -1062,13 +1600,23 @@ 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;
@@ -1187,7 +1735,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;
 }
 
@@ -1216,6 +1764,70 @@ export interface TasksSagaRepairResult {
   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`.
  *
@@ -1235,7 +1847,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;
   /**
@@ -1346,12 +1958,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,
@@ -1361,6 +1981,8 @@ export type TasksOps = {
   readonly current: readonly [TasksCurrentParams, TasksCurrentResult];
   readonly 'label.list': readonly [TasksLabelListParams, TasksLabelListResult];
   readonly 'sync.links': readonly [TasksSyncLinksParams, TasksSyncLinksResult];
+  // T10629 — task-scoped context pack with token budget
+  readonly context: readonly [TasksContextParams, TasksContextResult];
   // Mutate ops
   readonly add: readonly [TasksAddParams, TasksAddResult];
   readonly 'add-batch': readonly [TasksAddBatchParams, TasksAddBatchResult];
@@ -1373,6 +1995,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];
@@ -1391,6 +2014,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,
+  ];
 };
 
 // ---------------------------------------------------------------------------
@@ -1429,7 +2057,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;
@@ -1437,7 +2065,7 @@ export interface TasksAddBatchEntry {
   labels?: string[];
   /** Task type (saga | epic | task | subtask). */
   type?: TaskType; // SSoT-EXEMPT:kind≠type — same axis split as TasksAddBatchParams (T944) // ssot-exempt-ok: mirrors parent type
-  /** 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;
@@ -1550,9 +2178,17 @@ export const TASKS_ADD_BATCH_INPUT_SCHEMA: JsonSchema = {
           parent: { type: 'string' },
           depends: { type: 'array', items: { type: 'string' } },
           priority: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] },
-          labels: { type: 'array', items: { type: 'string' } },
+          labels: {
+            type: 'array',
+            items: { type: 'string' },
+            'x-fix-hint': 'pass labels as a JSON array, e.g. ["pm-core-v2", "wave.3"]',
+          },
           type: { type: 'string', enum: ['saga', 'epic', 'task', 'subtask'] },
-          acceptance: { type: 'array', items: { type: 'string' } },
+          acceptance: {
+            type: 'array',
+            items: { type: 'string' },
+            'x-fix-hint': 'pass acceptance as a JSON array, not a pipe-delimited string',
+          },
           phase: { type: 'string' },
           size: { type: 'string', enum: ['small', 'medium', 'large'] },
           notes: { type: 'string' },
@@ -1584,7 +2220,18 @@ export const tasksAddBatchInputContract: OperationInputContract<TasksAddBatchPar
     {
       name: 'two-tasks',
       value: {
-        tasks: [{ title: 'first task' }, { title: 'second task' }],
+        tasks: [
+          {
+            title: 'first task',
+            labels: ['pm-core-v2', 'wave.3'],
+            acceptance: ['first acceptance criterion'],
+          },
+          {
+            title: 'second task',
+            labels: ['batch'],
+            acceptance: ['second acceptance criterion'],
+          },
+        ],
       },
       description: 'Atomic insert of two tasks under no shared parent.',
     },