@cleocode/contracts 2026.5.92 → 2026.5.94

package/src/doctor.ts

@@ -0,0 +1,130 @@
+/**
+ * Doctor domain contracts — types for `cleo doctor` worktree-orphan audit/prune.
+ *
+ * These types describe orphan `.cleo/` directories left behind under
+ * `<projectRoot>/.claude/worktrees/` by the T9550/T9580 SSoT bug (fixed in
+ * v2026.5.83) and the schema for the audit JSONL line written per prune.
+ *
+ * Consumed by:
+ *   - `packages/core/src/doctor/worktree-orphans.ts` (scan + prune primitives)
+ *   - `packages/cleo/src/cli/commands/doctor.ts` (CLI flags)
+ *
+ * @task T9790
+ * @epic T9790
+ */
+
+/**
+ * One orphan `.cleo/` directory discovered under
+ * `<projectRoot>/.claude/worktrees/`.
+ *
+ * Worktrees are nested 1-3 levels deep — examples:
+ *   - `<projectRoot>/.claude/worktrees/agent-X/.cleo/`            (depth 1)
+ *   - `<projectRoot>/.claude/worktrees/agent-X/T9220/.cleo/`     (depth 2)
+ *
+ * Each entry carries full provenance so the operator can decide whether
+ * the orphan represents lost work before pruning.
+ */
+export interface OrphanEntry {
+  /**
+   * The worktree root that contains the orphan — the first directory under
+   * `.claude/worktrees/` (e.g. `<projectRoot>/.claude/worktrees/agent-X`).
+   * Used as the boundary that `pruneWorktreeOrphans` validates against.
+   */
+  worktreePath: string;
+
+  /**
+   * Absolute path to the orphan `.cleo/` directory itself. Always lives
+   * under `worktreePath` (the security check rejects anything that doesn't).
+   */
+  orphanPath: string;
+
+  /**
+   * List of `tasks.db`, `brain.db`, `nexus.db`, or `config.json` paths
+   * found inside the orphan. Empty array means the orphan exists but is
+   * structurally empty (still pruned — it shouldn't be there at all).
+   */
+  dbFiles: string[];
+
+  /** Total byte size of the orphan tree (sum of regular file sizes). */
+  sizeBytes: number;
+
+  /** ISO-8601 timestamp of the most recent file modification under the orphan. */
+  lastModifiedAt: string;
+
+  /**
+   * Seconds since `lastModifiedAt` (relative to scan time). Surfaces "stale
+   * vs recent" without forcing the caller to compute date math.
+   */
+  ageSeconds: number;
+
+  /**
+   * `true` when the orphan contains more than just stray DB files — e.g. a
+   * full duplicate of `adrs/`, `agent-outputs/`, `rcasd/`, etc. These need
+   * heightened operator review before pruning.
+   */
+  isFullDuplicate: boolean;
+}
+
+/**
+ * Result of one prune operation. Reports the archive location, the per-entry
+ * outcome, and any entries rejected by the security gate.
+ */
+export interface PruneResult {
+  /**
+   * Absolute path to the `.tar.gz` archive written before any deletion.
+   * `null` only when `dryRun: true` AND no archive was produced.
+   */
+  archivePath: string | null;
+
+  /** Whether this was a dry run (no archive, no rm, no audit-log line). */
+  dryRun: boolean;
+
+  /** Entries that were successfully pruned (or would be in dry-run mode). */
+  pruned: OrphanEntry[];
+
+  /**
+   * Entries that failed validation and were skipped. The `reason` is a
+   * stable machine-readable code (e.g. `path-outside-worktrees-root`,
+   * `path-not-found`, `rm-failed`).
+   */
+  rejected: Array<{ entry: OrphanEntry; reason: string }>;
+
+  /** Total bytes archived (sum of `pruned[].sizeBytes`). */
+  totalSizeBytes: number;
+
+  /** ISO-8601 timestamp the prune completed. */
+  prunedAt: string;
+}
+
+/**
+ * One line appended to `.cleo/audit/worktree-prune.jsonl` per prune
+ * operation. Extends the existing audit-log schema (timestamp +
+ * worktreePath + action + agent) with the orphan-specific fields needed
+ * to reconstruct what was removed.
+ *
+ * Existing fields preserved for schema continuity:
+ *   - `timestamp`, `worktreePath`, `action`, `agent`
+ *
+ * New fields for orphan prune:
+ *   - `orphanPath`, `sizeBytes`, `dbFileCount`, `archivePath`, `dryRun`
+ */
+export interface PruneAuditEntry {
+  /** ISO-8601 timestamp. */
+  timestamp: string;
+  /** Worktree root that contained the orphan. */
+  worktreePath: string;
+  /** Absolute path to the orphan `.cleo/` directory removed. */
+  orphanPath: string;
+  /** Action code — fixed to `'prune-worktree-orphan'` for this flow. */
+  action: 'prune-worktree-orphan';
+  /** Always `'cleo'` — written by `cleo doctor`. */
+  agent: 'cleo';
+  /** Byte size of the pruned tree. */
+  sizeBytes: number;
+  /** Number of DB files found in the orphan (informational). */
+  dbFileCount: number;
+  /** Absolute path to the archive. `null` only on dry-run lines. */
+  archivePath: string | null;
+  /** Whether this entry represents a dry-run plan (no actual removal). */
+  dryRun: boolean;
+}

package/src/exit-codes.ts

@@ -244,6 +244,17 @@ export const E_DIRTY_TREE = 'E_DIRTY_TREE' as const;
 export const E_EPIC_EMPTY = 'E_EPIC_EMPTY' as const;
 /** Epic referenced by `--epic` does not exist (R-021). Exit code 10. */
 export const E_EPIC_NOT_FOUND = 'E_EPIC_NOT_FOUND' as const;
+/**
+ * Leaf-Epic-as-Task ship (`--epic <id>` where the Epic has zero non-cancelled
+ * child tasks) was attempted but the Epic itself carries zero ADR-051 evidence
+ * atoms. Per ADR-073 the leaf-Epic-as-PR pattern is canonical for atomic ships,
+ * but the Epic still needs evidence (commit:sha, files, pr:<num>, etc.) to
+ * be promoted into a release. Exit code 83. `error.details.epicId` reports
+ * the offending Epic. `error.details.fix` points at `cleo verify`.
+ *
+ * @task T9838
+ */
+export const E_EPIC_EMPTY_LEAF_NO_EVIDENCE = 'E_EPIC_EMPTY_LEAF_NO_EVIDENCE' as const;
 /** Channel + version scheme are incompatible (R-022). Exit code 6. */
 export const E_CHANNEL_MISMATCH = 'E_CHANNEL_MISMATCH' as const;
 /**
@@ -280,6 +291,25 @@ export const E_GH_NOT_AUTHENTICATED = 'E_GH_NOT_AUTHENTICATED' as const;
  */
 export const E_WORKFLOW_NOT_FOUND = 'E_WORKFLOW_NOT_FOUND' as const;
 
+/**
+ * E_WRITE_CONTENTION — Persistent SQLITE_BUSY after exhausting application-level
+ * retry. Emitted by {@link withWriteRetry} (in `@cleocode/core`'s
+ * `store/with-retry.ts`) when a SQLite write transaction fails 4 consecutive
+ * attempts with `SQLITE_BUSY: database is locked` despite the engine-level
+ * `busy_timeout=5000ms` pragma.
+ *
+ * **Recovery**: retry the operation after a brief delay (the contended writer
+ * usually commits within 1-2 seconds). If the error reoccurs reliably, suspect
+ * a long-running writer holding a RESERVED lock — inspect with
+ * `sqlite3 .cleo/tasks.db "PRAGMA wal_checkpoint(FULL); SELECT * FROM sqlite_lock;"`.
+ *
+ * Maps to {@link ExitCode.LOCK_TIMEOUT} (7) at the CLI boundary.
+ *
+ * @bug gh-391 — parallel `cleo update --add-labels` losing ~50% of writes.
+ * @task T9839
+ */
+export const E_WRITE_CONTENTION = 'E_WRITE_CONTENTION' as const;
+
 /** Check if an exit code represents an error (1-99). */
 export function isErrorCode(code: ExitCode): boolean {
   return code >= 1 && code < 100;

package/src/index.ts

@@ -180,6 +180,9 @@ export type { AdapterCapabilities } from './capabilities.js';
 // === Changesets (CLEO-native task-anchored DSL — T9738) ===
 export type { ChangesetEntry, ChangesetKind } from './changesets.js';
 export { CHANGESET_KINDS, ChangesetEntrySchema } from './changesets.js';
+// === CLI Category Types (help renderer grouping SSoT) ===
+export type { CliCategory } from './cli-category.js';
+export { CLI_CATEGORY_ORDER } from './cli-category.js';
 // === Code Symbol Types (tree-sitter AST) ===
 export type {
   BatchParseResult,
@@ -277,6 +280,22 @@ export type {
   StoreDocParams,
   StoreDocResult,
 } from './docs-accessor.js';
+// === Canonical Doc-Kind Taxonomy Registry (T9788) ===
+export type {
+  BuiltinDocKind,
+  DocKindConfigFile,
+  DocKindExtensionConfig,
+  DocKindMetadata,
+  SlugValidationResult,
+} from './docs-taxonomy.js';
+export {
+  BUILTIN_DOC_KIND_VALUES,
+  BUILTIN_DOC_KINDS,
+  DocKindConfigError,
+  DocKindRegistry,
+} from './docs-taxonomy.js';
+// === Doctor: Worktree-Orphan Audit + Prune Types (T9790) ===
+export type { OrphanEntry, PruneAuditEntry, PruneResult } from './doctor.js';
 export type {
   EngineErrorPayload,
   EngineFailure,
@@ -339,6 +358,7 @@ export {
   E_CHANNEL_MISMATCH,
   E_DIRTY_TREE,
   E_EPIC_EMPTY,
+  E_EPIC_EMPTY_LEAF_NO_EVIDENCE,
   E_EPIC_NOT_FOUND,
   E_EVIDENCE_INSUFFICIENT,
   // SPEC-T9345 release pipeline v2 error code names (T9530)
@@ -347,6 +367,8 @@ export {
   E_PLAN_NOT_FOUND,
   E_RELEASE_PLAN_INVALID,
   E_WORKFLOW_NOT_FOUND,
+  // gh#391 — application-level SQLITE_BUSY retry exhaustion (T9839)
+  E_WRITE_CONTENTION,
   ExitCode,
   getExitCodeName,
   isErrorCode,
@@ -993,6 +1015,9 @@ export type {
   SessionGcResult,
   SessionHandoffShowParams,
   SessionHandoffShowResult,
+  SessionLintParams,
+  SessionLintResult,
+  SessionLintViolation,
   SessionListParams,
   SessionListResult,
   SessionOps,
@@ -1015,6 +1040,8 @@ export type {
   DepGraphIssue,
   DepsTreeEdge,
   DepsTreeNode,
+  TasksAddBatchParams,
+  TasksAddBatchResult,
   TasksAddParams,
   TasksAddResult,
   TasksAnalyzeQueryParams,
@@ -1105,6 +1132,8 @@ export type {
   ComplianceMetrics,
   ValidateArchiveStatsParams,
   ValidateArchiveStatsResult,
+  ValidateCanonDocsParams,
+  ValidateCanonDocsResult,
   ValidateCanonParams,
   ValidateCanonResult,
   ValidateChainParams,
@@ -1247,13 +1276,18 @@ export type {
 export type { AdapterPathProvider } from './provider-paths.js';
 // === Release Channel ===
 export type { ChannelValidationResult, ReleaseChannel } from './release/channel.js';
-// === Release Evidence Atoms (T9764) ===
-export type { GhPrViewPayload, ParsedPrEvidenceAtom } from './release/evidence-atoms.js';
+// === Release Evidence Atoms (T9764 + T9838) ===
+export type {
+  GhPrViewPayload,
+  ParsedPrEvidenceAtom,
+  PrEvidenceStateModifier,
+} from './release/evidence-atoms.js';
 export {
   ghPrViewSchema,
   PR_REQUIRED_WORKFLOWS,
   PR_REQUIRED_WORKFLOWS_ENV_VAR,
   parsedPrEvidenceAtomSchema,
+  prEvidenceStateModifierSchema,
 } from './release/evidence-atoms.js';
 // === Release GitHub PR ===
 export type {

package/src/operations/docs.ts

@@ -29,6 +29,7 @@
  */
 
 import type { AttachmentKind } from '../attachment.js';
+import { BUILTIN_DOC_KIND_VALUES, type BuiltinDocKind } from '../docs-taxonomy.js';
 
 // ============================================================================
 // Shared Attachment Types (API wire format)
@@ -54,28 +55,32 @@ export type { AttachmentKind } from '../attachment.js';
 /**
  * Allowed values for the `--type` taxonomy on `cleo docs add`.
  *
- * The set is closed at the CLI surface; new values require a coordinated
- * update to (1) {@link DOCS_TYPE_VALUES}, (2) the dispatch-layer guard, and
- * (3) the citty CLI flag description. The DB column itself is open (no CHECK)
- * so older clients reading a forward-compatible value gracefully degrade.
+ * As of T9788 this is derived from the canonical {@link BUILTIN_DOC_KIND_VALUES}
+ * in `docs-taxonomy.ts` — adding a kind there automatically widens this set
+ * without a duplicate edit here.
+ *
+ * Project-level extensions registered through `.cleo/docs-config.json` are
+ * NOT included in this constant (they are runtime-only, since the
+ * compile-time union must stay closed). Use {@link DocKindRegistry.list}
+ * to enumerate built-ins plus extensions at runtime.
  *
  * @task T9637 (T-DOCS-SLUG-2)
+ * @task T9788 (E-DOCS-TAXONOMY-V2 — registry consolidation)
  */
-export const DOCS_TYPE_VALUES = [
-  'spec',
-  'adr',
-  'research',
-  'handoff',
-  'note',
-  'llm-readme',
-] as const;
+export const DOCS_TYPE_VALUES: ReadonlyArray<BuiltinDocKind> =
+  BUILTIN_DOC_KIND_VALUES as ReadonlyArray<BuiltinDocKind>;
 
 /**
  * Closed-set type alias for {@link DOCS_TYPE_VALUES}.
  *
+ * As of T9788 this aliases {@link BuiltinDocKind} from the canonical
+ * registry — the union widens automatically when a new built-in kind
+ * is added to {@link BUILTIN_DOC_KINDS}.
+ *
  * @task T9637
+ * @task T9788
  */
-export type DocsType = (typeof DOCS_TYPE_VALUES)[number];
+export type DocsType = BuiltinDocKind;
 
 /**
  * Flattened wire-format attachment row returned by docs query operations.
@@ -169,16 +174,38 @@ export interface AttachmentRecord {
 // docs.list — list attachments for an owner
 // --------------------------------------------------------------------------
 
+/**
+ * Sort key for `docs.list` results.
+ *
+ * - `newest` — descending by `createdAt` (default — most recent first).
+ * - `sha`    — ascending by `sha256` (stable lexicographic).
+ * - `slug`   — ascending by `slug`; entries without a slug sort last.
+ *
+ * @task T9792
+ */
+export type DocsListOrderBy = 'newest' | 'sha' | 'slug';
+
+/**
+ * Default maximum number of rows returned by `docs.list` when the caller
+ * does not pass an explicit `limit`. Mirrored on the CLI flag default so the
+ * dispatch and CLI surfaces agree on the browsing window.
+ *
+ * @task T9792
+ */
+export const DOCS_LIST_DEFAULT_LIMIT = 50;
+
 /**
  * Parameters for `docs.list`.
  *
- * Exactly one of `task`, `session`, `observation`, or `project` must be
- * provided. `project=true` lists ALL attachments in the project DB
- * regardless of owner. `type` is an optional filter applicable to every
- * mode and matches the {@link DocsType} taxonomy exactly.
+ * Scope is auto-promoted to whole-project when no owner-scope flag is set
+ * (T9792). Pre-T9792 callers MUST still pass `project: true` explicitly to
+ * stay forward-compatible — the auto-promote happens at the CLI layer.
+ * `type` is an optional filter applicable to every mode and matches the
+ * {@link DocsType} taxonomy exactly.
  *
  * @task T9637 (T-DOCS-SLUG-2 — `type` filter)
  * @task T9638 (T-DOCS-SLUG-3 — `project` scope)
+ * @task T9792 (E-DOCS-LIST-UX-FIX — auto-promote project scope + limit + orderBy)
  */
 export interface DocsListParams {
   /** Task identifier to list attachments for. */
@@ -199,6 +226,20 @@ export interface DocsListParams {
    * @task T9637
    */
   type?: DocsType;
+  /**
+   * Maximum number of rows to return. Defaults to
+   * {@link DOCS_LIST_DEFAULT_LIMIT} when omitted. Values `<= 0` are treated
+   * as "no limit" so agents can opt-in to the full result set explicitly.
+   *
+   * @task T9792
+   */
+  limit?: number;
+  /**
+   * Sort key for the returned rows. Defaults to `newest` when omitted.
+   *
+   * @task T9792
+   */
+  orderBy?: DocsListOrderBy;
 }
 
 /**
@@ -218,8 +259,41 @@ export interface DocsListResult {
   project?: boolean;
   /** Type taxonomy filter, echoed back from the request when provided. */
   type?: DocsType;
-  /** Count of attachments for this owner. */
+  /** Count of attachments for this owner (after limit + filters). */
   count: number;
+  /**
+   * Total number of attachments matching the scope + filters BEFORE the
+   * `limit` window was applied. Only emitted when `limit` truncated the
+   * result set so consumers can distinguish "fewer than limit" from
+   * "limit truncated".
+   *
+   * @task T9792
+   */
+  totalCount?: number;
+  /**
+   * Effective limit applied to this response. Mirrored from the request
+   * (or {@link DOCS_LIST_DEFAULT_LIMIT} when the request did not set one)
+   * so consumers can paginate without re-deriving the default.
+   *
+   * @task T9792
+   */
+  limit?: number;
+  /**
+   * Effective sort key applied to this response. Mirrored from the request
+   * (or `"newest"` when the request did not set one).
+   *
+   * @task T9792
+   */
+  orderBy?: DocsListOrderBy;
+  /**
+   * Optional human-readable hint surfaced when a default behaviour kicked
+   * in (e.g. project scope auto-promoted because no scope was passed). The
+   * CLI surfaces this through `meta.hint` so JSON consumers can detect that
+   * a narrower invocation may have been intended.
+   *
+   * @task T9792
+   */
+  hint?: string;
   /** Attachment metadata array. */
   attachments: DocsAttachmentRow[];
   /** Current attachment backend in use. */

package/src/operations/release.ts

@@ -16,14 +16,6 @@ export interface ReleaseGate {
   reason?: string;
 }
 
-export interface ChangelogSection {
-  type: 'feat' | 'fix' | 'docs' | 'test' | 'refactor' | 'chore';
-  entries: Array<{
-    taskId: string;
-    message: string;
-  }>;
-}
-
 /**
  * Mutate Operations
  */
@@ -65,26 +57,6 @@ export interface ReleasePrepareResult {
   taskCount: number;
 }
 
-// release.changelog
-/** Parameters for `release.changelog`. @task T963 */
-export interface ReleaseChangelogParams {
-  /** Version to build the changelog for (must match an existing manifest). @task T963 */
-  version: string;
-  /** Filter emitted sections. @task T963 */
-  sections?: Array<'feat' | 'fix' | 'docs' | 'test' | 'refactor' | 'chore'>;
-}
-/** Result of `release.changelog`. @task T963 */
-export interface ReleaseChangelogResult {
-  /** Version. @task T963 */
-  version: string;
-  /** Rendered changelog content (Markdown). @task T963 */
-  content: string;
-  /** Grouped changelog sections. @task T963 */
-  sections: ChangelogSection[];
-  /** Count of commits aggregated. @task T963 */
-  commitCount: number;
-}
-
 // release.commit
 /** Parameters for `release.commit`. @task T963 */
 export interface ReleaseCommitParams {

package/src/operations/session.ts

@@ -587,6 +587,76 @@ export interface SessionRecordAssumptionResult {
   timestamp: string;
 }
 
+// session.lint — agent-accountability harness (T9797)
+
+/**
+ * Parameters for `session.lint`.
+ *
+ * Scans a Claude Code-style session transcript (`*.jsonl`) for raw
+ * markdown writes that bypass the docs SSoT. Flags any tool call whose
+ * `file_path` lands under a `rawMdPaths` entry whose owning DocKind has
+ * `rawMdAllowed: false` in `.cleo/canon.yml`.
+ *
+ * @task T9797
+ */
+export interface SessionLintParams {
+  /**
+   * Absolute path to the `.jsonl` transcript to scan. Required.
+   */
+  transcript: string;
+}
+
+/**
+ * One violation surfaced by `session.lint`.
+ *
+ * Mirrors `CanonLintViolation` from
+ * `packages/core/src/session/canon-lint.ts` (the SDK-level engine).
+ *
+ * @task T9797
+ */
+export interface SessionLintViolation {
+  /** Session id derived from the transcript filename. */
+  sessionId: string;
+  /** Anthropic `tool_use.id` (e.g. `toolu_01ABC...`). May be empty. */
+  toolUseId: string;
+  /** Tool name — `Write`, `Edit`, or `MultiEdit`. */
+  tool: string;
+  /** Repo-relative path the agent attempted to write. */
+  path: string;
+  /** Owning DocKind id (e.g. `adr`, `note`). */
+  docKind: string;
+  /** Matching `rawMdPaths` entry (e.g. `.cleo/adrs/`). */
+  matchedPath: string;
+  /** Categorical reason — always `'raw-md-canonical'` today. */
+  kind: 'raw-md-canonical';
+  /** First 200 chars of the violating content. */
+  evidence: string;
+  /** Suggested fix command. */
+  fix: string;
+}
+
+/**
+ * Result of `session.lint`.
+ *
+ * @task T9797
+ */
+export interface SessionLintResult {
+  /** Absolute transcript path that was scanned. */
+  transcriptPath: string;
+  /** Session id derived from the transcript filename. */
+  sessionId: string;
+  /** True when no violations were flagged. */
+  passed: boolean;
+  /** Number of `Write`/`Edit`/`MultiEdit` tool calls inspected. */
+  scanned: number;
+  /** Violations in transcript order. Empty when `passed === true`. */
+  violations: SessionLintViolation[];
+  /** Non-fatal warnings (e.g. JSON parse failures on isolated lines). */
+  warnings: string[];
+  /** `'enforced'` when canon.yml present, `'no-canon'` when missing. */
+  mode: 'enforced' | 'no-canon';
+}
+
 // ---------------------------------------------------------------------------
 // Typed operation record (Wave D adapter — T975)
 // ---------------------------------------------------------------------------
@@ -619,4 +689,5 @@ export type SessionOps = {
     SessionRecordAssumptionParams,
     SessionRecordAssumptionResult,
   ];
+  readonly lint: readonly [SessionLintParams, SessionLintResult];
 };

package/src/operations/tasks.ts

@@ -524,6 +524,7 @@ export interface TasksCancelParams {
  * Result of `tasks.cancel` — cancellation confirmation.
  *
  * @task T1703
+ * @task T9838 (idempotency — `alreadyCancelled` returned when re-cancelling)
  */
 export interface TasksCancelResult {
   /** The task ID that was cancelled. */
@@ -534,6 +535,14 @@ export interface TasksCancelResult {
   reason?: string;
   /** ISO 8601 timestamp of cancellation. */
   cancelledAt: string;
+  /**
+   * True when the task was already cancelled before this call — the
+   * operation is a no-op and the response reflects the pre-existing
+   * cancellation state. Idempotent re-cancellation (T9838).
+   *
+   * @defaultValue undefined
+   */
+  alreadyCancelled?: boolean;
 }
 
 // tasks.restore (with from routing: done → reopen, archived → unarchive)
@@ -653,6 +662,63 @@ export interface TasksRelatesRemoveResult {
   removed: boolean;
 }
 
+// tasks.add-batch (atomic multi-task insert)
+/**
+ * Parameters for `tasks.add-batch`.
+ *
+ * Wraps N `tasks.add` inserts in a single transaction; any failure rolls
+ * back ALL inserts. Closes the partial-batch bug in the CLI `add-batch`
+ * command (T9813 / T9814).
+ *
+ * @task T9814
+ */
+export interface TasksAddBatchParams {
+  /**
+   * Array of task specs to insert. Must be non-empty.
+   * Each spec accepts the same fields as `tasks.add` (except `dryRun`
+   * which is hoisted to the batch level).
+   */
+  tasks: Array<{
+    title: string;
+    description?: string;
+    parent?: string;
+    depends?: string[];
+    priority?: string;
+    labels?: string[];
+    type?: string; // SSoT-EXEMPT:kind≠type — 'type' is hierarchy(epic|task|subtask), 'kind' is intent(work|bug|...) — separate axes T944
+    acceptance?: string[];
+    phase?: string;
+    size?: string;
+    notes?: string;
+    files?: string[];
+    kind?: string;
+    scope?: string;
+    severity?: string;
+    forceDuplicate?: boolean;
+  }>;
+  /** Optional default parent ID applied when a task spec omits `parent`. */
+  defaultParent?: string;
+  /**
+   * Dry-run mode: validate each spec and return predicted IDs without
+   * writing to the database. Created count is always 0 in dry-run.
+   */
+  dryRun?: boolean;
+}
+
+/**
+ * Result of `tasks.add-batch`.
+ *
+ * @task T9814
+ */
+export interface TasksAddBatchResult {
+  /** 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;
+}
+
 // tasks.add (dispatch-level params — extends TasksCreateParams)
 export interface TasksAddParams {
   title: string;
@@ -1043,6 +1109,7 @@ export type TasksOps = {
   readonly 'sync.links': readonly [TasksSyncLinksParams, TasksSyncLinksResult];
   // Mutate ops
   readonly add: readonly [TasksAddParams, TasksAddResult];
+  readonly 'add-batch': readonly [TasksAddBatchParams, TasksAddBatchResult];
   readonly update: readonly [TasksUpdateQueryParams, TasksUpdateQueryResult];
   readonly complete: readonly [TasksCompleteQueryParams, TasksCompleteQueryResult];
   readonly cancel: readonly [TasksCancelParams, TasksCancelResult];