@cleocode/contracts 2026.4.151 → 2026.4.153

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/contracts",
-  "version": "2026.4.151",
+  "version": "2026.4.153",
   "description": "Domain types, interfaces, and contracts for the CLEO ecosystem",
   "type": "module",
   "main": "./dist/index.js",
@@ -49,6 +49,14 @@
     "./nexus-tasks-bridge-ops.js": {
       "types": "./dist/nexus-tasks-bridge-ops.d.ts",
       "import": "./dist/nexus-tasks-bridge-ops.js"
+    },
+    "./operations/*": {
+      "types": "./dist/operations/*.d.ts",
+      "import": "./dist/operations/*.js"
+    },
+    "./operations/*.js": {
+      "types": "./dist/operations/*.d.ts",
+      "import": "./dist/operations/*.js"
     }
   },
   "engines": {

package/src/branch-lock.ts

@@ -227,6 +227,8 @@ export interface OwnerOverrideConfig {
  * Error codes emitted by the branch-lock + override-auth system.
  *
  * @task T1118
+ * @task T1501
+ * @task T1502
  */
 export const BRANCH_LOCK_ERROR_CODES = {
   /** L2: git shim blocked a branch-mutating operation. */
@@ -247,6 +249,17 @@ export const BRANCH_LOCK_ERROR_CODES = {
   E_OVERRIDE_NEEDS_TTY: 'E_OVERRIDE_NEEDS_TTY',
   /** L4d: session override limit exceeded. */
   E_OVERRIDE_RATE_LIMIT: 'E_OVERRIDE_RATE_LIMIT',
+  /**
+   * T1501 / P0-5: per-session cap (default 3) exceeded without a valid waiver doc.
+   * Set CLEO_OWNER_OVERRIDE_WAIVER=<absolute path> to a file containing
+   * `cap-waiver: true` in its frontmatter to bypass the cap.
+   */
+  E_OVERRIDE_CAP_EXCEEDED: 'E_OVERRIDE_CAP_EXCEEDED',
+  /**
+   * T1502 / P0-6: the same evidence atom was used across >3 distinct tasks and
+   * `--shared-evidence` was not passed (or CLEO_STRICT_EVIDENCE=1 is set in CI).
+   */
+  E_SHARED_EVIDENCE_FLAG_REQUIRED: 'E_SHARED_EVIDENCE_FLAG_REQUIRED',
 } as const;
 
 /** Union of all branch-lock error code strings. */

package/src/facade.ts

@@ -276,6 +276,8 @@ export interface TasksAPI {
     labels?: string[];
     depends?: string[];
     notes?: string;
+    /** Acceptance criteria items (free-text strings or structured gate specs). */
+    acceptance?: string[];
   }): Promise<unknown>;
   /** Find tasks by query, ID, status, or limit. */
   find(params: {

package/src/index.ts

@@ -462,7 +462,6 @@ export type {
   AdminDashParams,
   AdminDetectParams,
   AdminExportParams,
-  AdminHandlerOps,
   AdminHealthMutateParams,
   AdminHealthQueryParams,
   AdminHelpParams,
@@ -477,6 +476,7 @@ export type {
   AdminMapMutateParams,
   AdminMapQueryParams,
   AdminMigrateParams,
+  AdminOps,
   AdminPathsParams,
   AdminRoadmapParams,
   AdminRuntimeParams,

package/src/operations/admin.ts

@@ -2085,91 +2085,3 @@ export type AdminOps =
       params: AdminInstallGlobalParams;
       result: AdminInstallGlobalResult;
     };
-
-// ============================================================================
-// AdminHandlerOps — TypedOpRecord for TypedDomainHandler<AdminHandlerOps>
-//
-// Maps each handler-level operation name (without the "admin." prefix used in
-// AdminOps) to a `[Params, Result]` tuple.  This is the format consumed by
-// `defineTypedHandler` and `typedDispatch` in the dispatch adapter.
-//
-// Operations that support multiple result shapes (e.g. `admin.job` returns
-// either a status record or a list) use a union result type — callers narrow
-// on the `action` param they supplied.
-//
-// @task T1426 — typed-narrowing migration for admin domain
-// @see AdminOps (discriminated-union form, kept for facade / external callers)
-// ============================================================================
-
-/**
- * TypedOpRecord for the `admin` domain handler.
- *
- * Each entry maps the bare operation name (as dispatched by the handler
- * switch, without the `admin.` domain prefix) to `[Params, Result]`.
- *
- * @task T1426 — Wave D typed-dispatch migration for admin domain
- */
-export type AdminHandlerOps = {
-  // ---- Query ops ----
-  readonly version: readonly [AdminVersionParams, AdminVersionResult];
-  readonly health: readonly [AdminHealthQueryParams, AdminHealthQueryResult | AdminDoctorResult];
-  readonly 'config.show': readonly [AdminConfigShowParams, AdminConfigShowResult];
-  readonly 'config.presets': readonly [AdminConfigPresetsParams, AdminConfigPresetsResult];
-  readonly stats: readonly [AdminStatsParams, AdminStatsResult];
-  readonly context: readonly [AdminContextParams, AdminContextResult];
-  readonly 'context.pull': readonly [AdminContextPullParams, AdminContextPullResult];
-  readonly runtime: readonly [AdminRuntimeParams, AdminRuntimeResult];
-  readonly paths: readonly [AdminPathsParams, AdminPathsResult];
-  readonly job: readonly [AdminJobStatusParams, AdminJobStatusResult | AdminJobListResult];
-  readonly dash: readonly [AdminDashParams, AdminDashResult];
-  readonly log: readonly [AdminLogParams, AdminLogResult];
-  readonly sequence: readonly [AdminSequenceParams, AdminSequenceResult];
-  readonly help: readonly [AdminHelpParams, AdminHelpResult];
-  readonly token: readonly [
-    AdminTokenQueryParams,
-    AdminTokenSummaryResult | AdminTokenListResult | AdminTokenShowResult,
-  ];
-  readonly 'adr.find': readonly [AdminAdrFindParams, AdminAdrFindResult];
-  readonly 'adr.show': readonly [AdminAdrShowParams, AdminAdrShowResult];
-  readonly backup: readonly [AdminBackupListParams, AdminBackupListResult];
-  readonly export: readonly [
-    AdminExportParams,
-    AdminExportStandardResult | AdminExportSnapshotResult | AdminExportTasksPackageResult,
-  ];
-  readonly map: readonly [AdminMapQueryParams, AdminMapResult];
-  readonly roadmap: readonly [AdminRoadmapParams, AdminRoadmapResult];
-  readonly smoke: readonly [AdminSmokeParams, AdminSmokeResult];
-  readonly 'smoke.provider': readonly [AdminSmokeProviderParams, AdminSmokeProviderResult];
-  readonly 'hooks.matrix': readonly [AdminHooksMatrixParams, AdminHooksMatrixResult];
-  // ---- Mutate ops ----
-  readonly init: readonly [AdminInitParams, AdminInitResult];
-  readonly 'scaffold-hub': readonly [AdminScaffoldHubParams, AdminScaffoldHubResult];
-  readonly 'health.mutate': readonly [
-    AdminHealthMutateParams,
-    AdminHealthRepairResult | AdminDoctorResult,
-  ];
-  readonly 'config.set': readonly [AdminConfigSetParams, AdminConfigSetResult];
-  readonly 'config.set-preset': readonly [AdminConfigSetPresetParams, AdminConfigSetPresetResult];
-  readonly 'backup.mutate': readonly [
-    AdminBackupMutateParams,
-    AdminBackupCreateResult | AdminBackupRestoreByIdResult | AdminBackupRestoreFileResult,
-  ];
-  readonly migrate: readonly [AdminMigrateParams, AdminMigrateResult];
-  readonly cleanup: readonly [AdminCleanupParams, AdminCleanupResult];
-  readonly 'job.cancel': readonly [AdminJobCancelParams, AdminJobCancelResult];
-  readonly safestop: readonly [AdminSafestopParams, AdminSafestopResult];
-  readonly 'inject.generate': readonly [AdminInjectGenerateParams, AdminInjectGenerateResult];
-  readonly 'adr.sync': readonly [AdminAdrSyncParams, AdminAdrSyncResult | AdminAdrValidateResult];
-  readonly import: readonly [
-    AdminImportParams,
-    AdminImportStandardResult | AdminImportSnapshotResult | AdminImportTasksPackageResult,
-  ];
-  readonly detect: readonly [AdminDetectParams, AdminDetectResult];
-  readonly 'token.mutate': readonly [
-    AdminTokenMutateParams,
-    AdminTokenRecordResult | AdminTokenDeleteResult | AdminTokenClearResult,
-  ];
-  readonly 'context.inject': readonly [AdminContextInjectParams, AdminContextInjectResult];
-  readonly 'map.mutate': readonly [AdminMapMutateParams, AdminMapMutateResult];
-  readonly 'install.global': readonly [AdminInstallGlobalParams, AdminInstallGlobalResult];
-};

package/src/operations/index.ts

@@ -15,6 +15,8 @@ export * from './nexus.js';
 export * from './nexus-user-profile.js';
 export * from './orchestrate.js';
 export * from './params.js';
+export * from './pipeline.js';
+export * from './playbook.js';
 export * from './release.js';
 export * from './research.js';
 export * from './sentient.js';

package/src/operations/nexus.ts

@@ -20,6 +20,7 @@
  */
 
 // Profile types are now canonical in nexus-user-profile.ts (T1424 dedup)
+import type { SigilCard } from './memory.js';
 import type {
   NexusProfileExportParams,
   NexusProfileExportResult,
@@ -781,19 +782,43 @@ export interface NexusImpactParams {
   projectId?: string;
   /** Include "why" reasons (optional). */
   why?: boolean;
+  /** Maximum reverse traversal depth (default 3, capped at 5). */
+  depth?: number;
 }
 /** Affected symbol in impact result. */
 export interface NexusImpactAffectedNode {
+  /** Nexus node ID. */
   nodeId: string;
+  /** Human-readable label. */
   label: string;
+  /** Node kind. */
   kind: string;
+  /** Source file path (nullable). */
+  filePath: string | null;
+  /** BFS depth from the target (1 = direct caller). */
+  depth: number;
+  /** Path-strings explaining why this symbol is impacted. */
   reasons: string[];
 }
 /** Result of `nexus.impact`. */
 export interface NexusImpactResult {
+  /** Original symbol query string. */
+  query: string;
+  /** Project ID the analysis ran against. */
+  projectId: string;
+  /** Resolved target node ID (or null when no match was found). */
   targetNodeId: string | null;
+  /** Resolved target label (or null when no match was found). */
+  targetLabel: string | null;
+  /** Whether `why` reasons were requested and populated. */
   why: boolean;
+  /** Risk tier based on totalImpact count. */
   riskLevel: 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+  /** Total affected symbols across all depths (excludes the target itself). */
+  totalImpact: number;
+  /** Maximum traversal depth applied. */
+  maxDepth: number;
+  /** Affected symbols grouped by BFS depth. */
   affected: NexusImpactAffectedNode[];
 }
 
@@ -901,7 +926,12 @@ export interface NexusSigilListParams {
   role?: string;
 }
 /** Result of `nexus.sigil.list`. */
-export type NexusSigilListResult = unknown;
+export interface NexusSigilListResult {
+  /** Array of sigil records, ordered by displayName ascending. */
+  sigils: SigilCard[];
+  /** Total count of sigils returned. */
+  count: number;
+}
 
 /** Parameters for `nexus.sigil.sync` — none. */
 export type NexusSigilSyncParams = Record<string, never>;

package/src/operations/pipeline.ts

@@ -0,0 +1,13 @@
+/**
+ * Pipeline Domain Operations — wire-format contracts.
+ *
+ * All pipeline *Params/*Result types were removed in T1446 (T1435-W2).
+ * The canonical source of truth is `OpsFromCore<typeof coreOps>` inside
+ * `packages/cleo/src/dispatch/domains/pipeline.ts`, which infers all
+ * operation param/result shapes directly from Core function signatures
+ * without requiring per-op type aliases in contracts.
+ *
+ * @task T1441 — OpsFromCore inference migration
+ * @task T1435 — Wave 1 dispatch refactor
+ * @task T1446 — strip redundant Params/Result aliases (T1435-W2)
+ */

package/src/operations/session.ts

@@ -173,6 +173,9 @@ export type SessionBriefingShowResult = unknown;
 // session.history (query — not in primary handler but exported for completeness)
 /** Parameters for `session.history`. */
 export interface SessionHistoryParams {
+  /** Specific session id to filter to. */
+  sessionId?: string;
+  /** Maximum number of sessions to return. */
   limit?: number;
 }
 /** A single session history entry. */

package/src/operations/tasks.ts

@@ -1,13 +1,20 @@
 /**
- * Tasks Domain Operations (22 operations)
+ * Tasks Domain Operations — wire-format contracts for the tasks dispatch domain.
  *
- * Query operations: 10
- * Mutate operations: 12
+ * Contains only types that appear in the `TasksOps` discriminated union (the
+ * authoritative wire-format spec) plus shared primitives (`TaskOp`,
+ * `MinimalTask`, `TaskPriority`, `TaskStatus`) used cross-domain.
+ *
+ * Legacy pre-dispatch aliases (`TasksCreateParams`, `TasksUpdateParams`, etc.)
+ * were removed in T1446 (T1435-W2). Use the dispatch-level types
+ * (`TasksAddParams`, `TasksUpdateQueryParams`, etc.) that appear in `TasksOps`.
  *
  * SYNC: Canonical type definitions live in the CLI package at:
  *   src/types/task.ts (TaskStatus, TaskPriority, Task, etc.)
  * These operation types are the API contract (wire format).
  * Internal domain types must stay aligned with CLI definitions.
+ *
+ * @task T1446 — strip redundant Params/Result aliases (T1435-W2)
  */
 
 /**
@@ -44,12 +51,6 @@ export interface MinimalTask {
  * Query Operations
  */
 
-// tasks.get
-export interface TasksGetParams {
-  taskId: string;
-}
-export type TasksGetResult = TaskOp;
-
 // tasks.list
 export interface TasksListParams {
   parent?: string;
@@ -105,316 +106,16 @@ export interface TasksFindParams {
   verbose?: boolean;
   /**
    * Filter by role axis (T944 — orthogonal axes).
-   * Accepts the same values as the `role` field on TasksCreateParams.
    * @task T963 / T944
    */
   role?: string;
 }
 export type TasksFindResult = MinimalTask[];
 
-// tasks.exists
-export interface TasksExistsParams {
-  taskId: string;
-}
-export interface TasksExistsResult {
-  exists: boolean;
-  taskId: string;
-}
-
-// tasks.tree
-export interface TasksTreeParams {
-  rootId?: string;
-  depth?: number;
-}
-export interface TaskTreeNode {
-  task: TaskOp;
-  children: TaskTreeNode[];
-  depth: number;
-}
-export type TasksTreeResult = TaskTreeNode[];
-
-// tasks.blockers
-export interface TasksBlockersParams {
-  taskId: string;
-}
-export interface Blocker {
-  taskId: string;
-  title: string;
-  status: TaskStatus;
-  blockType: 'dependency' | 'parent' | 'gate';
-}
-export type TasksBlockersResult = Blocker[];
-
-// tasks.deps
-export interface TasksDepsParams {
-  taskId: string;
-  direction?: 'upstream' | 'downstream' | 'both';
-}
-export interface TaskDependencyNode {
-  taskId: string;
-  title: string;
-  status: TaskStatus;
-  distance: number;
-}
-export interface TasksDepsResult {
-  taskId: string;
-  upstream: TaskDependencyNode[];
-  downstream: TaskDependencyNode[];
-}
-
-// tasks.analyze
-export interface TasksAnalyzeParams {
-  epicId?: string;
-}
-export interface TriageRecommendation {
-  taskId: string;
-  title: string;
-  priority: number;
-  reason: string;
-  readiness: 'ready' | 'blocked' | 'pending';
-}
-export type TasksAnalyzeResult = TriageRecommendation[];
-
-// tasks.next
-export interface TasksNextParams {
-  epicId?: string;
-  count?: number;
-}
-export interface SuggestedTask {
-  taskId: string;
-  title: string;
-  score: number;
-  rationale: string;
-}
-export type TasksNextResult = SuggestedTask[];
-
 /**
  * Mutate Operations
  */
 
-// tasks.create
-/**
- * Parameters for `tasks.create` / `tasks.add`.
- *
- * @remarks
- * Re-synced to match `AddTaskOptions` in `packages/core/src/tasks/add.ts`
- * and the dispatch handler in `packages/cleo/src/dispatch/domains/tasks.ts`.
- * The legacy contract was missing 8 fields (`type`, `acceptance`, `phase`,
- * `size`, `notes`, `files`, `dryRun`, `parentSearch`) — agents following
- * the contract would omit them and fail CLEO's anti-hallucination + epic
- * creation enforcement.
- *
- * @task T963 — contract↔impl drift reconciliation (T910 audit)
- */
-export interface TasksCreateParams {
-  /** Task title (required, 1..200 chars). @task T963 */
-  title: string;
-  /**
-   * Task description (required by anti-hallucination rule T5698 — must
-   * differ from `title`). The legacy contract marked this required; kept
-   * required here to preserve behavior.
-   * @task T963
-   */
-  description: string;
-  /** Parent task id (`T###`). Omit for root-level tasks (epics only). @task T963 */
-  parent?: string;
-  /** Task IDs this task depends on. @task T963 */
-  depends?: string[];
-  /** Priority (`critical`|`high`|`medium`|`low`). Defaults to `medium`. @task T963 */
-  priority?: TaskPriority;
-  /** Label tags (lowercase alphanumeric + hyphens/periods). @task T963 */
-  labels?: string[];
-  /**
-   * Task type. When omitted, inferred from parent (epic-child → `task`,
-   * task-child → `subtask`, rootless → `task`). @task T963
-   */
-  type?: 'epic' | 'task' | 'subtask';
-  /**
-   * Acceptance criteria (pipe-separated strings). Minimum 3 required by
-   * enforcement layer; epics require minimum 5.
-   * @task T963
-   */
-  acceptance?: string[];
-  /** Phase slug (lowercase alphanumeric + hyphens). @task T963 */
-  phase?: string;
-  /** Task size (`small`|`medium`|`large`). Defaults to `medium`. @task T963 */
-  size?: 'small' | 'medium' | 'large';
-  /** Initial note text (timestamped at insertion). @task T963 */
-  notes?: string;
-  /** File paths associated with the task. @task T963 */
-  files?: string[];
-  /**
-   * When true, validate + preview the task without allocating a task id or
-   * writing to the DB. Preview returns an `id: 'T???'` placeholder.
-   * @task T963
-   */
-  dryRun?: boolean;
-  /**
-   * CLI helper for parent resolution via search term — when set, dispatch
-   * layer resolves the search to a parent id before calling core.
-   * @task T963
-   */
-  parentSearch?: string;
-}
-export type TasksCreateResult = TaskOp;
-
-// tasks.update
-/**
- * Parameters for `tasks.update`.
- *
- * @remarks
- * Re-synced to match `UpdateTaskOptions` in
- * `packages/core/src/tasks/update.ts` and the dispatch handler in
- * `packages/cleo/src/dispatch/domains/tasks.ts`. The legacy contract was
- * missing `acceptance`, `pipelineStage` (T834 / ADR-051 Decision 4),
- * `files`, `blockedBy`, `phase`, `noAutoComplete`, the narrow typing of
- * `type`/`size`, and the `addDepends`/`removeDepends` array mutators.
- *
- * @task T963 — contract↔impl drift reconciliation (T910 audit)
- */
-export interface TasksUpdateParams {
-  /** Task ID to update (required). @task T963 */
-  taskId: string;
-  /** Replace title. @task T963 */
-  title?: string;
-  /** Replace description. @task T963 */
-  description?: string;
-  /** Target status — `done` transitions route through complete flow. @task T963 */
-  status?: TaskStatus;
-  /** Replace priority. @task T963 */
-  priority?: TaskPriority;
-  /** Append a timestamped note. @task T963 */
-  notes?: string;
-  /** Set parent ID, or null/"" to promote to root. @task T963 */
-  parent?: string | null;
-  /** Replace labels wholesale. @task T963 */
-  labels?: string[];
-  /** Additive label insert. @task T963 */
-  addLabels?: string[];
-  /** Label removal set. @task T963 */
-  removeLabels?: string[];
-  /** Replace dependency list. @task T963 */
-  depends?: string[];
-  /** Additive dependency insert. @task T963 */
-  addDepends?: string[];
-  /** Dependency removal set. @task T963 */
-  removeDepends?: string[];
-  /** Task type (`epic`|`task`|`subtask`). @task T963 */
-  type?: 'epic' | 'task' | 'subtask';
-  /** Task size (`small`|`medium`|`large`). @task T963 */
-  size?: 'small' | 'medium' | 'large';
-  /**
-   * Replace acceptance criteria. Subject to AC enforcement — min 3 for
-   * all tasks, min 5 for epics.
-   * @task T963
-   */
-  acceptance?: string[];
-  /** Replace files attached to the task. @task T963 */
-  files?: string[];
-  /** Phase slug (lowercase alphanumeric + hyphens). @task T963 */
-  phase?: string;
-  /** Blocking reason (set when status=`blocked`). @task T963 */
-  blockedBy?: string;
-  /**
-   * When true, skip auto-complete cascading when all children complete.
-   * @task T963
-   */
-  noAutoComplete?: boolean;
-  /**
-   * RCASD-IVTR+C pipeline stage transition target. Forward-only
-   * (validated by `validatePipelineTransition`); epic advancements are
-   * additionally gated by `validateEpicStageAdvancement`; non-epic tasks
-   * are gated by `validateChildStageCeiling` against their ancestor epic.
-   * @task T963 / T834 / ADR-051 Decision 4
-   */
-  pipelineStage?: string;
-}
-export type TasksUpdateResult = TaskOp;
-
-// tasks.complete
-export interface TasksCompleteParams {
-  taskId: string;
-  notes?: string;
-  archive?: boolean;
-}
-export interface TasksCompleteResult {
-  taskId: string;
-  completed: string;
-  archived: boolean;
-}
-
-// tasks.delete
-export interface TasksDeleteParams {
-  taskId: string;
-  force?: boolean;
-}
-export interface TasksDeleteResult {
-  taskId: string;
-  deleted: true;
-}
-
-// tasks.archive
-export interface TasksArchiveParams {
-  taskId?: string;
-  before?: string;
-}
-export interface TasksArchiveResult {
-  archived: number;
-  taskIds: string[];
-}
-
-// tasks.unarchive
-export interface TasksUnarchiveParams {
-  taskId: string;
-}
-export type TasksUnarchiveResult = TaskOp;
-
-// tasks.reparent
-export interface TasksReparentParams {
-  taskId: string;
-  newParent: string;
-}
-export type TasksReparentResult = TaskOp;
-
-// tasks.promote
-export interface TasksPromoteParams {
-  taskId: string;
-}
-export type TasksPromoteResult = TaskOp;
-
-// tasks.reorder
-export interface TasksReorderParams {
-  taskId: string;
-  position: number;
-}
-export interface TasksReorderResult {
-  taskId: string;
-  newPosition: number;
-}
-
-// tasks.restore (completed tasks) — alias: reopen
-export interface TasksReopenParams {
-  taskId: string;
-}
-export type TasksReopenResult = TaskOp;
-
-// tasks.start (begin working on a task)
-export interface TasksStartParams {
-  taskId: string;
-}
-export interface TasksStartResult {
-  taskId: string;
-  sessionId: string;
-  timestamp: string;
-}
-
-// tasks.stop (stop working on current task)
-export type TasksStopParams = Record<string, never>;
-export interface TasksStopResult {
-  stopped: true;
-  previousTask?: string;
-}
-
 // tasks.current (get currently active task)
 export type TasksCurrentParams = Record<string, never>;
 export interface TasksCurrentResult {

package/src/operations/validate.ts

@@ -195,6 +195,13 @@ export interface ValidateGateParams {
   reset?: boolean;
   evidence?: string;
   sessionId?: string;
+  /**
+   * Acknowledge that the same evidence atom is being applied to more than 3
+   * distinct tasks in this session (T1502 / P0-6).  Without this flag,
+   * such reuse triggers a warning (or a hard reject in strict mode when
+   * `CLEO_STRICT_EVIDENCE=1`).
+   */
+  sharedEvidence?: boolean;
 }
 export interface ValidateGateResult {
   taskId: string;